Installing and configuring cofidectl

Having provisioned (or been given access to a Cofide-hosted) Connect Control Plane, it is now time to start making use of the Connect platform to secure your workloads using modern, cryptographically-verifiable workload identity primitives.

This page explains how to set up your local environment in order to start working with the Cofide Connect platform.

Command-line interface (CLI)

The open-source cofidectl tool provides a command-line interface to deploy and configure workload identity resources in Kubernetes clusters. Cofide also maintain a proprietary Connect-enabled version of cofidectl to securely interact with the Connect control plane. Cofide partners and customers should use the proprietary version.

The key difference between the two cofidectl versions is that the former uses a local cofide.yaml file to store all workload identity configuration, whereas the Connect-enabled CLI uses the production-ready Connect control plane as a data store and its local config file simply stores the minimal configuration required to talk to Connect. From a user’s perspective, the simplest way to tell which CLI version you are using is to check whether there’s a cofidectl connect subcommand available.

There is a quickstart script which will retrieve the latest stable binaries to use the Connect-enabled CLI:

curl -sfL https://get.cofide.dev/cofidectl.sh --output get.sh

This will download the script locally, ready to be run with:

bash ./get.sh

Security

Please feel free to inspect the contents of this script before you run it for the first time. Its remit is only to pull binaries and make them available to your local filesystem.

The script is interactive and will prompt you to confirm the version to install. Once downloaded, you will be offered the option to move cofidectl to /usr/local/bin for system-wide access, or it will remain in the current directory. The resulting cofidectl binary is the Connect-enabled CLI, ready to use with a Connect control plane instance.

Initialization

To configure the CLI to use your Connect control plane, run cofidectl init. This adds a profile for the Connect instance to the cofidectl config file, creating the file if it doesn’t already exist. By default the config file is cofide/cofidectl.yaml in the user config directory (for example, ~/.config/cofide/cofidectl.yaml on Linux), and you can use a different file with the global --config flag.

A single config file can hold profiles for multiple Connect instances. A profile is named by --profile or the COFIDECTL_PROFILE environment variable; if neither is set, the name is derived from --connect-tls-grpc-target. If the config file has no default profile yet, the new profile becomes the default. Use --profile (or COFIDECTL_PROFILE) with any cofidectl command to act on a non-default profile, and see cofidectl profile to list, inspect or delete profiles.

The following flag is always required for cofidectl init:

• --connect-tls-grpc-target: gRPC target (host:port) used to reach the Connect API (this should match connect.apiAddress in the Connect API Helm chart, with the port being mandatory here)

The following flags are optional, you may need to set them if the defaults are not applicable for your Connect instance:

• --oauth-client-id: OAuth client ID used to authenticate with the Connect API
• --connect-audience: OAuth audience that Connect API access tokens must carry in their aud claim
• --connect-tls-server-name: Override the TLS server name (SNI) presented by the Connect API, if it differs from the host in --connect-tls-grpc-target
• --connect-insecure-tls: Do not validate the certificate of Cofide Connect

The --oauth-issuer-url flag, which sets the issuer URL of the OAuth 2.0 / OIDC identity provider that backs authentication, is optional. When it is omitted, the CLI discovers the issuer from the Connect API’s OAuth protected resource metadata. If discovery isn’t available, set the authorization and token endpoints directly with --oauth-authorization-url and --oauth-token-url.

Note

cofidectl init only configures how the CLI authenticates with the Connect API. The SPIFFE mTLS and XDS gRPC targets, Connect SPIFFE ID, trust bundle host and image overrides used to generate Helm values are passed directly to the relevant command instead, for example cofidectl trust-zone helm values or cofidectl connect agent helm values for Cofide Agent.

Important

If you have a Cofide-hosted instance of Connect, please get in contact to receive cofidectl init configuration details.

Login to Connect

Once initialized, you’ll need to login with the identity provider (IdP) backing Cofide Connect. This can be done with:

cofidectl connect login

before following the browser prompt. Credentials are cached per profile; use cofidectl profile get-credentials-path to print the path of the cached credentials file for the current (or a given --profile) profile.

See Identity provider requirements for details on the identity provider that backs this login flow.