Home › Docs › Fleet resource

Fleet resource

The manifest consumed by klimax fleet create -f and klimax fleet delete -f. It's a Kubernetes-style resource: apiVersion: klimax.dev/v1alpha1, kind: Fleet. Every field below is optional except spec.clusters.

Full example

The annotated reference manifest — the same one shipped as examples/fleet.yaml:

apiVersion: klimax.dev/v1alpha1
kind: Fleet
metadata:
  name: dev-fleet
spec:
  # Concurrent cluster creations. 0/1 = sequential (default). Independent
  # clusters run in parallel up to this cap; dependsOn ordering is always honoured.
  maxParallel: 2

  # FailFast (default): stop scheduling new clusters after the first failure.
  # ContinueOnError: keep creating independent clusters and report failures at the end.
  strategy: FailFast

  # Applied to every cluster below that does not set the field itself.
  defaults:
    registries:
      mirrors: ["*"]        # all mirrors from ~/.klimax/config.yaml
    labels:                 # merged into every cluster (entry labels win on conflict)
      owner: platform-team

  # Every cluster always gets node labels: managed-by=klimax, plus
  # klimax.dev/fleet=<metadata.name> and topology.kubernetes.io/region + zone.
  clusters:
    # A bare string is shorthand for "just create a cluster with this name".
    - hub

    # An object entry can override any per-cluster option.
    - name: spoke-a
      dependsOn: [hub]      # created only after "hub" is ready
      # num: 7              # pin the cluster num (1-99); omit to auto-assign a free slot
      # nodeVersion: v1.35.0  # ⚠ overriding is unsupported; see 'klimax cluster create' warning
      region: europe-west4
      zone: europe-west4-b
      registries:
        mirrors: ["registry-dockerio", "registry-quayio"]   # cherry-pick by name
      labels:              # extra node labels on this cluster's nodes
        team: search
        env: dev
      addons:
        metricsServer:
          enabled: true
          # version: v0.7.2          # omit for the latest release
          # kubeletInsecureTLS: true # default true (required on kind)

    - name: spoke-b
      dependsOn: [hub]
      registries:
        mirrors: []          # no pull-through mirrors (pull straight from upstream)

Envelope

metadata

spec

spec.defaults

Every field here is also a per-cluster field; a value set on a cluster entry wins over the default.

spec.clusters[] — cluster entry

A bare string (- dev) is shorthand for an object with only name set. Object form:

registries

Valid under spec.defaults and per cluster.

addons

Valid under spec.defaults and per cluster. Currently one addon:

Node labels

Every cluster klimax creates has its nodes labelled with kubectl label nodes --all after creation; topology labels are set even earlier, at node registration. See Fleet management → Node labels for how to set custom ones.

Validation

The whole manifest is validated before any cluster is created — --dry-run runs the same checks. A manifest is rejected when:

• apiVersion ≠ klimax.dev/v1alpha1 or kind ≠ Fleet.
• strategy is not "", FailFast, or ContinueOnError.
• maxParallel < 0, or spec.clusters is empty.
• A cluster name is missing, duplicated, or not a valid DNS-style name.
• A num is outside 1–99, or two clusters request the same explicit num.
• A dependsOn entry names a cluster not in the manifest, or a cluster depends on itself.
• The dependency graph contains a cycle.
• A selected mirror name isn't defined in ~/.klimax/config.yaml, or a label key/value isn't a valid Kubernetes label.

See also

• Fleet management — the how-to guide with worked examples.
• CLI reference — Clusters — apply and delete -f flags.
• Configuration — the mirrors and defaults a fleet draws on.