Cluster

k8s.nyl/v1

Kubernetes Rendering Resources · Download JSON Schema · Usage guide

Describes a concrete Kubernetes destination and its deterministic rendering capabilities.

Cluster values supply reusable facts; target values take precedence. This is compiler configuration and is not emitted as a workload manifest.

When needed

Required for every workload destination and every explicitly configured Argo CD control-plane destination in Kubernetes GitOps.

If omitted

Target rendering fails if the referenced Cluster is missing. Omitting DeploymentTarget.spec.clusterRef selects a Cluster with the target name; it does not create that Cluster or infer its capabilities from kubeconfig.

Example

apiVersion: k8s.nyl/v1
kind: Cluster
metadata:
  name: primary
spec:
  destination:
    server: https://kubernetes.default.svc
  kubernetes:
    apiVersions:
      - v1
      - apps/v1
    kubeVersion: 1.31.4

Fields

Required means required within the containing object. Optional and nullable are distinct; contextual defaults and requirements are explained with each field.

Unknown fields are rejected.

apiVersion

Required · string

API group and version defining this resource.

const: "k8s.nyl/v1"

kind

Required · string

Resource kind within the API group.

const: "Cluster"

metadata

Required · object

Resource identity and metadata.

Unknown fields are rejected.

metadata.labels

Optional · object

Literal labels used for organization and target selection.

metadata.labels[key]

Optional · string

metadata.name

Required · string

Project-local identity, validated by the resource kind; remains static during discovery.

spec

Required · object

Configuration for this resource.

Unknown fields are rejected.

Validation constraints

if:
  properties:
    apiContractFrom:
      properties:
        mode:
          const: all
      required:
        - mode
      type: object
  required:
    - apiContractFrom
then:
  properties:
    kubernetes:
      type: "null"
else:
  properties:
    kubernetes:
      not:
        type: "null"
  required:
    - kubernetes

spec.apiContractFrom

Optional · object or null

Borrow a declared Cluster’s captured API contract. Destination, values, and live settings remain local.

Unknown fields are rejected.

spec.apiContractFrom.clusterRef

Required · object

Project-local Cluster providing the contract. References must be acyclic.

Unknown fields are rejected.

spec.apiContractFrom.clusterRef.name

Required · string

Project-local name of the referenced resource; its kind and API group are determined by the containing field.

spec.apiContractFrom.mode

Required · string

schemas borrows CRD schemas; all also borrows Kubernetes capabilities.

Allowed values: "schemas" · "all"

spec.destination

Required · object

Exactly one concrete Argo CD destination, identified by server URL or registered cluster name.

Unknown fields are rejected.

Choose exactly one variant:

• name — Addresses the destination by its registered Argo CD cluster name.
• server — Addresses the destination by its Kubernetes API server URL.

spec.destination.name

Optional · string or null

Argo CD registered cluster name. Exactly one of server and name must be non-null.

spec.destination.server

Optional · string or null

Kubernetes API server URL. Exactly one of server and name must be non-null.

spec.kubernetes

Optional · object or null

Committed Kubernetes capabilities for deterministic offline rendering. Required unless apiContractFrom.mode is all; omit when inheriting all capabilities. Target rendering requires an effective version and at least one API version.

Unknown fields are rejected.

spec.kubernetes.apiVersions

Optional · array

API versions exposed to Helm. An empty list is valid for scaffolding; target rendering requires at least one entry. With vendoredCrds, entries served by vendored CustomResourceDefinitions are omitted here and added from the snapshot.

spec.kubernetes.apiVersions[]

Required · string

spec.kubernetes.clusterScopedKinds

Optional · array

Cluster-scoped kinds as group/Kind, with core for the core API group, such as core/Namespace. Recorded by nyl capture cluster; every other kind listed in apiVersions is namespaced. Empty means the scope is unknown.

spec.kubernetes.clusterScopedKinds[]

Required · string

spec.kubernetes.kubeVersion

Optional · string or null

Kubernetes version exposed to Helm. May be omitted for scaffolding; required for target rendering.

spec.kubernetes.vendoredCrds

Optional · boolean

Whether CustomResourceDefinitions were vendored by nyl capture cluster --crds. Their API versions and scopes then come from the vendored snapshot, and rendering fails while it is missing or stale.

spec.live

Optional · object or null

Local connection settings. Omitted from templates and render hashes.

Unknown fields are rejected.

spec.live.context

Required · string

Local kubeconfig context. Live commands prefer an explicit --context, then this value, then the current kubeconfig context.

spec.values

Optional · object

Cluster facts merged recursively with target values; target values win.

Additional keys may contain any value.