Skip to content
kix /docs
Install the CLI

How-to guide Author packages and clusters

Declare readiness for custom resources

Tell Kix which status value means that an operator-managed custom resource is ready.

Use a readiness declaration when a custom resource’s controller does not set a standard Ready or Available condition. Declare the controller’s convention on the CRD or CRD reference, then create resources through its typed builder:

how-to/composition/custom-resource-package.nix
      widgetCrd = scope.mkCRD (
        scope.crd.fromKind "Widget" { spec.group = "widgets.example.com"; }
        // {
          readiness = {
            path = "/status/phase";
            equals = "Ready";
          };
        }
      );


      widget = self.widgetCrd.out.mkCR scope {
        name = "example";
        spec.size = "small";
      };

View source on GitHub ↗

path is a JSON pointer into the live custom resource. equals is the string value that indicates readiness. In this example, Kix waits until status.phase is Ready.

A controller that reports a condition instead of a plain status field takes the condition form:

readiness = {
  condition = {
    type = "Bootstrapped";
    status = "True";
  };
};

Kix then waits until status.conditions holds an entry with that type and status. Use this form for operators such as StackGres (Bootstrapped) and for Gateway API kinds (Accepted on a GatewayClass, Programmed on a Gateway), which never set Ready or Available.

Keep this declaration in the package that owns or imports the CRD. Every custom resource created through widgetCrd.out.mkCR then receives the same readiness rule, along with its dependency on the CRD.

Check the generated custom resource

Section titled “Check the generated custom resource”

Build the cluster as JSON and inspect the custom resource. The output excerpt shows the readiness annotation Kix generated from the declaration:

kix-examples/ output excerpt 
❱ kix build how-to-composition --output json
{
  "apiVersion": "widgets.example.com/v1",
  "kind": "Widget",
  "metadata": {
    "name": "example",
    "annotations": {
      "kix.run/readiness": "{\"equals\":\"Ready\",\"path\":\"/status/phase\"}"
    }
  },
  "spec": {
    "size": "small"
  }
}

Run the normal pre-deploy checks as well:

kix-examples/ 
❱ kix check how-to-composition

During deployment, Kix reads the live object at the declared path and waits for the expected value. Make the path match the status field written by the controller, including its exact capitalization.