Cluster

A target Kubernetes cluster, how convoy connects to it, and metadata for templates.

A Cluster is a target for Releases. It holds the connection data, the credentials and free-form metadata that mutations and hooks can read.


API group	`core.convoy.kumodo.io/v1alpha1`
Scope	Namespaced
Subresources	`/status`
Conditions	`Ready`

Example#

clusters/cluster-auth-agentless.yaml
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 is required. It has no default.

Mode	Implemented	How convoy connects
`inCluster`	Yes	With the credentials of the convoy pod. Use it for the cluster where convoy runs.
`agentless`	Yes, with `kubeconfig` auth only	With the credentials in `spec.agentless.auth`.
`agent`	No	`Ready=False`, reason `Unsupported`.

The block that matches the mode (agentless or agent) must be set. The other block must not be set.

Auth types for agentless mode#

`auth.type`	Implemented
`kubeconfig`	Yes. `kubeconfig.secretRef` points to a Secret key that holds a full kubeconfig.
`token`, `clientCert`, `execPlugin`, `oidc`	No. `Ready=False`, reason `Unsupported`.

With kubeconfig auth, the kubeconfig sets the server and the CA. convoy does not use agentless.server or agentless.caPublicCertRef to connect. convoy copies agentless.server into status.lastAttempted.resolvedCluster of each Release.

Metadata#

spec.metadata is a map of strings. Mutations and lifecycle hooks read it as cluster.<key>. cluster.name is the name of the Cluster. Credentials are never in this context.

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

Deletion#

convoy adds the finalizer cluster.core.convoy.kumodo.io/prune-releases to each Cluster.

deletionPolicy.pruneReleases: false (the default): the Cluster is deleted. Its Releases stay, and fail with reason ClusterNotReady.
deletionPolicy.pruneReleases: true: convoy deletes each Release in the same namespace that references the Cluster. The Cluster is deleted after all those Releases are gone. Each Release runs its own deletion policy.

Fields#

Field	Type	Description
`spec`	`ClusterSpec`	ClusterSpec defines the desired state of the Cluster.
`spec.agent`	`object`	Agent is the configuration of the agent connection mode.
`spec.agentless`	`ClusterAgentlessModeSpec`	Agentless is the configuration of the agentless connection mode.
`spec.agentless.auth` required	`ClusterAuthSpec`	Auth is the authentication configuration for the agentless connection mode.
`spec.agentless.auth.clientCert`	`ClientCertAuthSpec`	ClientCert is the authentication mode using a client certificate.
`spec.agentless.auth.clientCert.certRef` required	`SecretKeySelector`	CertRef is the name and the key of the Secret containing the client certificate.
`spec.agentless.auth.clientCert.keyRef` required	`SecretKeySelector`	KeyRef is the name and the key of the Secret containing the client certificate key.
`spec.agentless.auth.execPlugin`	`ExecPluginAuthSpec`	ExecPlugin is the authentication mode using an exec plugin.
`spec.agentless.auth.execPlugin.args`	`[]string`list type: atomic	Args are the arguments to pass to the command.
`spec.agentless.auth.execPlugin.command` required	`string`	Command is the command to execute.
`spec.agentless.auth.execPlugin.credentialsRef` required	`SecretReference`	CredentialsRef is the optional reference to credentials the plugin needs (e.g., AWS IAM role). Defined by the reference to the Secret and the key of the Secret containing the credentials.
`spec.agentless.auth.execPlugin.env`	`[]EnvVar`list type: map, keys: name	Env are the environment variables to pass to the command.
`spec.agentless.auth.kubeconfig`	`KubeconfigAuthSpec`	Kubeconfig is the authentication mode using a kubeconfig file.
`spec.agentless.auth.kubeconfig.secretRef` required	`SecretKeySelector`	SecretRef is the name and the key of the Secret containing the kubeconfig file.
`spec.agentless.auth.oidc`	`OIDAuthSpec`	OIDC is the authentication mode using OIDC client credentials.
`spec.agentless.auth.oidc.audience`	`string`	Audience is the OIDC audience.
`spec.agentless.auth.oidc.clientAuth` required	`OIDCClientAuthSpec`	ClientAuth is the OIDC authentication method used for authentication.
`spec.agentless.auth.oidc.clientAuth.clientSecret`	`OIDCAuthClientSecretSpec`	ClientSecret is the reference to the Secret and the key of the Secret containing the OIDC client secret.
`spec.agentless.auth.oidc.clientAuth.clientSecret.clientSecretRef` required	`SecretKeySelector`	ClientSecretRef is the name and the key of the Secret containing the OIDC client secret.
`spec.agentless.auth.oidc.clientAuth.privateKeyJWT`	`OIDCAuthPrivateKeyJWTSpec`	PrivateKeyJWT is the reference to the Secret and the key of the Secret containing the OIDC private key JWT.
`spec.agentless.auth.oidc.clientAuth.privateKeyJWT.privateKeyRef` required	`SecretKeySelector`	PrivateKeyRef is the name and the key of the Secret containing the OIDC private key JWT.
`spec.agentless.auth.oidc.clientAuth.tlsClientAuth`	`OIDCAuthTLSClientAuthSpec`	TLSClientAuth is the reference to the Secrets and the keys of the Secret(s) containing the OIDC client certificate and key.
`spec.agentless.auth.oidc.clientAuth.tlsClientAuth.certRef` required	`SecretKeySelector`	CertRef is the name and the key of the Secret containing the OIDC client certificate.
`spec.agentless.auth.oidc.clientAuth.tlsClientAuth.keyRef` required	`SecretKeySelector`	KeyRef is the name and the key of the Secret containing the OIDC client certificate key.
`spec.agentless.auth.oidc.clientAuth.type` required	`string`	Type is the OIDC authentication method type used for authentication. `clientSecret` is the OIDC authentication method using a client secret. `privateKeyJWT` is the OIDC authentication method using a private key JWT. `tlsClientAuth` is the OIDC authentication method using TLS client authentication.
`spec.agentless.auth.oidc.clientID` required	`string`	ClientID is the OIDC client ID.
`spec.agentless.auth.oidc.issuerURL` required	`string`	IssuerURL is the URL of the OIDC issuer.
`spec.agentless.auth.oidc.scopes`	`[]string`list type: atomic	Scopes are the OIDC scopes.
`spec.agentless.auth.oidc.tls`	`TLSSpec`	TLS is the issuer TLS configuration.
`spec.agentless.auth.oidc.tls.caPublicCertRef` required	`ConfigMapKeySelector`	CAPublicCertRef is the name and the key of the ConfigMap containing the CA public certificate. The CA certificate is used to verify the IdP server's certificate.
`spec.agentless.auth.oidc.tls.insecureSkipVerify` required	`boolean`	InsecureSkipVerify is a flag to skip the certificate verification.
`spec.agentless.auth.token`	`TokenAuthSpec`	Token is the authentication mode using a token.
`spec.agentless.auth.token.tokenRef` required	`SecretKeySelector`	TokenRef is the name and the key of the Secret containing the token.
`spec.agentless.auth.type` required	`string`	Type is the authentication mode used to connect to the target cluster. The workload identity authentication mode does not require specific configuration as it uses the identity of the controller's pod. `clientCert` is the authentication method using a client certificate. `execPlugin` is the authentication method using an exec plugin. `kubeconfig` is the authentication method using a kubeconfig file. `oidc` is the authentication method using OIDC. `token` is the authentication method using a token.
`spec.agentless.caPublicCertRef` required accepted, not used	`ConfigMapKeySelector`	CAPublicCertRef is the name and the key of the ConfigMap containing the CA public certificate. The CA certificate is used to verify the Kubernetes API server's certificate.
`spec.agentless.connectionParameters` required accepted, not used	`ClusterConnectionParametersSpec`	ClusterConnectionParametersSpec defines the connection parameters of the cluster.
`spec.agentless.connectionParameters.burst` required	`integer`	Burst is the maximum number of burst queries per second (QPS) to the Kubernetes API server.
`spec.agentless.connectionParameters.qps` required	`integer`	QPS is the maximum number of queries per second (QPS) to the Kubernetes API server.
`spec.agentless.connectionParameters.timeout` required	`Duration`	Timeout is the timeout for the Kubernetes API server connection.
`spec.agentless.server` required	`string`	Server is the address of the Kubernetes API server.
`spec.capabilities` accepted, not used	`ClusterCapabilitiesSpec`	Capabilities is the capabilities of the cluster.
`spec.capabilities.apiVersions`	`[]string`list type: atomic	APIVersions is the list of specific API versions the renderer can rely on.
`spec.capabilities.serverSideApply` required	`boolean`
`spec.connectionMode` required	`string`	ConnectionMode is the connection mode between the control plane and the target cluster. Possible values are: - agentless - agent `agent` defines the connection mode when the agent is running on the target cluster, pulls the workload manifests and applies them locally. `agentless` defines the connection mode when the control plane pushes the workload manifests to the cluster connecting to the target cluster's API server. `inCluster` defines the connection mode when the control plane is running in the same cluster as the target cluster.
`spec.deletionPolicy`	`ClusterDeletionPolicy`	DeletionPolicy is the deletion policy of the cluster.
`spec.deletionPolicy.pruneReleases` required	`boolean`	PruneReleases is the deletion policy for the Release objects in case of the cluster deletion.
`spec.metadata`	`map[string]string`	Metadata is the metadata of the cluster that is used for the templating of the workload manifests defined in the corresponding Release objects.

Field	Type	Description
`status`	`ClusterStatus`	ClusterStatus reflects the observed state of the Cluster.
`status.agentStatus`	`ClusterAgentStatus`	AgentStatus is the status of the agent running on the cluster. Applicable only if the cluster connection mode is agent.
`status.agentStatus.agentVersion` required	`string`	AgentVersion is the version of the agent running on the cluster.
`status.agentStatus.lastHeartbeat`	`Time`	LastHeartbeat is the time when the agent last sent a heartbeat.
`status.agentStatus.registeredAt` required	`Time`	RegisteredAt is the time when the agent was registered with the cluster.
`status.conditions`	`[]Condition`list type: map, keys: type	Conditions is the list of conditions related to the cluster.
`status.discoveredAPIVersions`	`[]string`list type: atomic	DiscoveredAPIVersions is the list of discovered API versions of the cluster.
`status.discoveredVersion`	`string`	DiscoveredVersion is the discovered Kubernetes version of the cluster.
`status.lastSeen`	`Time`	LastSeen is the last time the cluster was seen by the controller.
`status.observedGeneration`	`integer`	ObservedGeneration is the last generation that was observed by the controller.
`status.reachable` required	`boolean`	Reachable is a flag indicating whether the cluster is reachable.
`status.releaseCount`	`integer`	ReleaseCount is the number of Release objects in the cluster.

status.discoveredAPIVersions is informational. The Helm renderer does not use it. status.releaseCount and status.agentStatus are not set.

Conditions#

Ready · written by convoy-controller-manager

Reason	Status	Meaning
`Reachable`	True	convoy connected to the cluster and read its Kubernetes version.
`Unsupported`	False	The connection mode or the auth type is not implemented. Only `inCluster`, and `agentless` with `kubeconfig` auth, are implemented. convoy does not retry with backoff. The periodic resync checks the Cluster again.
`ProbeFailed`	False	convoy could not connect to the cluster or read its version. convoy retries.