Clusters

A Cluster is a target for Releases. It tells convoy how to connect to a Kubernetes API server. It also holds metadata that mutations and lifecycle hooks can read. Each Release references one Cluster in its own namespace.

apiVersion: core.convoy.kumodo.io/v1alpha1
kind: Cluster
metadata:
  name: convoy-managed
  namespace: default
spec:
  connectionMode: agentless
  agentless:
    server: https://convoy-managed-control-plane:6443
    auth:
      type: kubeconfig
      kubeconfig:
        secretRef:
          name: convoy-managed-kubeconfig
          key: kubeconfig
  metadata:
    type: kind
    role: managed

Connection modes#

spec.connectionMode selects how convoy connects to the target API server:

For agentless mode with kubeconfig auth:

• convoy reads the Secret in the namespace of the Cluster. kubeconfig.secretRef.key selects the key.
• The key must hold a full kubeconfig. convoy uses its current context.
• The kubeconfig sets the server, the CA and the credentials. convoy does not use agentless.server or agentless.caPublicCertRef to connect.

An auth type that is not built gives Ready=False with reason Unsupported. See Cluster for all fields.

The controller-manager connects to apply and prune objects. The observer connects to read live objects for drift and health. Both use the same connection code.

The probe#

The cluster controller probes each Cluster:

1. It builds a connection from spec.
2. It reads the server version through the discovery API.
3. It reads the API groups and versions that the server serves.

After a ProbeFailed result, the controller retries with a rate limit. After an Unsupported result, it does not retry. It probes all Clusters again at each periodic informer resync.

Reachability gates the Release#

At each reconcile, the Release controller fetches the source, and then reads the target Cluster. Before rendering, it checks the Cluster:

• If the Cluster does not exist, the Release reports Applied=False, reason ClusterNotReady.
• If status.reachable is false, the Release reports Applied=False, reason ClusterNotReady.

In both cases convoy does not render and does not apply. It retries the Release as a transient failure. The objects of the last apply stay on the target cluster.

A change to a Cluster does not start a reconcile of its Releases. A Release reads the new Cluster state at its next reconcile. See Sync policy.

Metadata as template context#

spec.metadata is a map of strings. convoy gives it to templates and CEL expressions as cluster:

spec:
  metadata:
    region: eu-west-1
    tier: production

• cluster.name replaces a metadata key with the name name.
• The context never contains credentials, the server address or the status.
• These parts of convoy read the context: mutations, the from.name and from.path fields of a mutation, and lifecycle hooks.

A mutation that reads metadata makes the render depend on the Cluster. When you change the metadata, the render can change. A changed render has a new renderRef, and convoy applies it as a new rollout. See Rendering.

Deletion#

convoy adds the finalizer cluster.core.convoy.kumodo.io/prune-releases to each Cluster. spec.deletionPolicy.pruneReleases controls what happens to the Releases that reference the Cluster:

With pruneReleases: true, each Release runs its own deletion while the Cluster still exists. The deletion policy of each Release applies, for example keepWorkloads and blockOnClusterUnreachable. See Deletion.