Quickstart: CLI

This page outlines how to use the cofidectl CLI tool in conjunction with the Connect plugin (cofidectl-connect-plugin) to configure and manage Cofide resources, all backed by the Connect platform.

Initialisation

The first step is to configure the CLI to point to a Connect instance. Connect will act as its data store, as well as action changes throughout the control plane to any Cofide Agents or Cofide SPIRE servers that have been installed and are active.

The initialisation is done with the cofidectl connect init command and always includes the following flags:

• --connect-url: URL and port of the Connect instance
• --connect-trust-domain: Trust domain of the Connect instance
• --connect-bundle-host: Connect instance endpoint where bundles are hosted
• --authorization-domain: OpenID Connect issuer used to authenticate with the Connect API
• --authorization-client-id: OpenID Connect client ID used to authenticate with the Connect API

Important

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

With Cofide SPIRE

The Cofide SPIRE server is the default and will be used in each of the trust zones:

cofidectl connect init \
...

Authentication options

There are multiple options for authenticating Cofide SPIRE with Connect. If using a join token, add the --use-join-token flag to the cofidectl connect init command:

cofidectl connect init \
...
  --use-join-token

See here for further information on authentication.

Disable Cofide Agent

If using Cofide SPIRE, it is possible to disable deployment of the Cofide Agent:

cofidectl connect init \
...
  --deploy-agent=false

Important

Disabling the Cofide Agent prevents the use of federated services.

With OSS SPIRE

To use the OSS SPIRE server instead of the Cofide SPIRE Server in each of the trust zones, add the --use-oss-spire flag to the cofidectl connect init command:

cofidectl connect init \
  --use-oss-spire \
...

Login to Connect

Once initialised, 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. User logins are valid for a limited time, and tokens are stored by default at ~/.cofide/credentials.

Define Resources in Connect API

Add a Trust Zone

After initialisation and user authentication, a trust zone with a single cluster can be created with the following command:

cofidectl trust-zone add \
  <trust-zone-name> \
  --trust-domain <trust-domain> \
  --kubernetes-cluster <name-of-k8s-cluster> \
  --kubernetes-context <context-of-k8s-cluster> \
  --profile kubernetes

• --trust-domain: The trust domain used in this trust zone
• --kubernetes-cluster: The name of the target Kubernetes cluster
• --kubernetes-context: The context of the target Kubernetes cluster
• --profile: The trust zone profile to use (options: kubernetes, istio)

There are multiple options for authenticating Cofide SPIRE with Connect. If using OpenID Connect, add the --kubernetes-oidc-issuer flag to the cofidectl trust-zone add command:

cofidectl trust-zone add \
...
  --kubernetes-oidc-issuer <your.kubernetes.oidc.issuer>

See here for further information on authentication.

Important

Note: the Cofide Agent and the Helm chart are hosted at Cofide’s container registry. Contact the Cofide team for access.

Add a Federation

If multiple trust zones exist, then they may be federated, allowing for a trust relationship to be established.

cofidectl federation add \
  --trust-zone <local trust zone> \
  --remote-trust-zone <remote trust zone>

The trust relationship is unidirectional - the local trust zone trusts the remote, but it is not necessarily reciprocated. Bidirectional trust is required for mutual TLS, and may be established by adding a second federation with the arguments reversed.

Add an Attestation Policy

Attestation policies can be defined at the namespace and/or pod label level. Creating a namespace attestation policy and binding it to the new trust zone can be done with:

cofidectl attestation-policy add kubernetes \
  --name <name-of-ap> \
  --namespace <namespace>

• --name: Name of the policy
• --namespace: Namespace to issue identities for

cofidectl attestation-policy-binding add \
  --trust-zone <trust-zone-name> \
  --attestation-policy <name-of-ap>

• --trust-zone: Trust zone to bind the policy to
• --attestation-policy: Attestation policy to bind

Similarly, a pod label attestation policy can be created with:

cofidectl attestation-policy add kubernetes \
  --name <name-of-another-ap> \
  --pod-label <pod-label>

• --name: Name of the policy
• --pod-label: Pod label to issue identities for

and bound to the trust zone in the same way as above.

Important

Cofide SPIRE does not support pod-level attestation policies without use of the accompanying cofide-observer component

If using open source SPIRE, SPIFFE IDs issued by an attestation policy bound to a trust zone will be of the default format:

spiffe://trust.domain/ns/namespace/sa/service-account

If using Cofide SPIRE, SPIFFE IDs will be of the following format:

spiffe://trust.domain/ns/namespace

Important

Note: The format of Cofide SPIRE issued SPIFFE IDs is expected to change in a future release.

In a trust zone with federations, workloads do not automatically trust workloads in other trust zones - they must opt in. This can be done using the --federates-with argument when creating an attestation policy binding:

cofidectl attestation-policy-binding add \
  --trust-zone <trust-zone-name> \
  --attestation-policy <name-of-ap> \
  --federates-with <federated trust zone>

Provision Infrastructure to Clusters

The trust zone, together with the attestation policy, can now be deployed with:

cofidectl up --trust-zone <trust-zone-name>

Deploy Cofide Observer

Cofide SPIRE relies on the cofide-observer component to obtain workload-level telemetry for advanced attestation policy support. This is deployed via Helm.