How-to guide Platform capabilities

Set the cluster availability level

Declare the cluster's failure domains, choose its default availability level, and override individual instances.

Declare the cluster substrate first. Kix derives the default availability level and workload placement from these capabilities.

Declare nodes and zones

For a multi-node cluster spanning three zones:

1
cluster.capabilities.multiNode = true;
2
cluster.capabilities.availabilityZones = [ "a" "b" "c" ];

Use the zone values your nodes actually carry. An empty list means the cluster is known to occupy one zone. Leave a capability unset only when the environment really is unknown; Kix warns when it cannot verify the derived level.

Kix derives cluster.availability.substrate from these declarations. It also uses that value as cluster.availability.default unless you set another default.

Choose a lower default

The default may be lower than the substrate when the cluster does not require the strongest available failure guarantee:

1
cluster.availability.default = "node";

The levels are none, pod, node, and zone. Setting a level above a fully declared substrate is an evaluation error.

Override one instance

An instance may request another level up to the substrate limit:

1
instances.apps.preview = {
2
  package = packages.echo-server;
3
  availability = "none";
4
};

This override affects the level passed to the package and the placement Kix derives for its workloads. Explicit package option values, such as a replica count set directly by the instance, still win over the package’s defaults.

Use custom topology labels

The default keys are Kubernetes’s well-known zone and hostname labels. Change them when the cluster uses another failure-domain vocabulary:

1
cluster.topology.zoneKey = "infrastructure.example.com/rack";
2
cluster.topology.hostKey = "infrastructure.example.com/hypervisor";

The labels must exist on the nodes before a hard node or zone constraint can schedule its pods. kix deploy warns when a schedulable node lacks a label required by a hard constraint.

Inspect the result

Evaluate the cluster, then inspect the generated constraints and budgets:

❱ kix check demo

❱ kix build demo -o json | jq '.[] | select(.kind == "Deployment" or .kind == "StatefulSet" or .kind == "PodDisruptionBudget") | {kind, name: .metadata.name, replicas: .spec.replicas, spread: .spec.template.spec.topologySpreadConstraints, maxUnavailable: .spec.maxUnavailable}'

Multi-replica Deployments and StatefulSets receive derived spread and a PDB. A confirmed single-node cluster has no failure-domain keys, so Kix derives neither.