facts and untrackedRef

This page is hand-maintained. Check kix/lib/core/markers.nix (mkUntrackedRef, passiveKinds), kix/lib/core/facts.nix, and kix/lib/core/resource.nix when in doubt.

kix.facts

Kix attaches endpoint facts to Service addresses such as out.fqdn and out.url. When an address reaches a workload, those facts let Kix derive network-policy rules and DNS dependencies. Facts do not change the rendered string and do not become deploy-order dependencies by themselves.

Most packages get the right behavior by passing an out address directly. The helpers below cover cases where a value is not used in its default role.

refOnly

kix.facts.refOnly service.out.fqdn

Marks an endpoint value as a reference rather than a connection. It preserves the resource identity carried by the string, so deploy ordering remains, but it suppresses the network-policy edge and the warning that a Service was referenced without using its address.

Use it when an address-shaped output becomes display text, a label, or other structural data that the workload does not dial.

connect

kix.facts.connect service.factTokens.endpoint service.out.name

Attaches a resource’s endpoint facts to another string. Use it when the consumer dials a value that does not receive endpoint facts automatically. The second argument should still carry the resource identity when deploy ordering is required, as service.out.name does in this example.

structural

outputs.replicas = kix.facts.structural (toString config.replicas);

Marks a package-defined outputs value as descriptive rather than an address. scope.mkResource exposes the value through out, preserves its resource identity, and treats any endpoint context it acquired as reference-only. This prevents a consumer that reads the output from creating a false network-policy edge.

kix.untrackedRef

kix.untrackedRef "cluster-ca"
kix.untrackedRef { name; kind ? null; apiVersion ? "v1"; by ? null; }

Returns name as a string that marks it as a reference to an object Kix does not render. The cross-resource checks accept the name in the referring resource’s namespace, so a volume, envFrom or serviceAccountName can name an object the cluster, an operator or another system provides.

Form	Deploy order	kix.run/expects	Listed by architecture.untrackedReferences
"name"	none	none	yes
{ name; kind; }	none	the object; deploy waits for it before applying the referrer	yes
{ name; by = creator; }	the referrer deploys after creator	none	yes
{ name; kind; by = creator; }	the referrer deploys after creator	the object	no, unless another reference to the name in that namespace omits kind or by
{ name; by = "self"; }	none	none	no, while exactly one resource in the cluster carries a self reference to the name

kix.run/expects makes kix deploy wait up to 180 seconds for the object to exist. The attribute-set forms are experimental.

by

by names the resource that creates the object: a Job, a workload, or an operator’s custom resource.

secretName = kix.untrackedRef {
  kind = "Secret";
  name = "admission-cert";
  by = self.certJob;
};

by refuses a built-in kind that creates no object a manifest refers to by name, such as ConfigMap, Secret, Service, PersistentVolumeClaim, ServiceAccount, the RBAC kinds, NetworkPolicy, PodDisruptionBudget, StorageClass, CustomResourceDefinition, the admission webhook and policy kinds, and APIService. The list is matched by API group, so a custom kind that shares a built-in name is accepted. Every other kind is accepted, including Namespace (the control plane creates kube-root-ca.crt and the default ServiceAccount in each namespace) and Ingress.

by = "self"

Use it when the resource holding the reference creates the object itself, such as an operator Deployment that mounts an optional Secret and then creates it:

volumes = [
  {
    name = "certs";
    secret = {
      secretName = kix.untrackedRef { name = "operator-certs"; by = "self"; };
      optional = true;
    };
  }
];

It adds no dependency and no kix.run/expects, because the object appears only after the referrer runs. Evaluation fails when:

• the reference also sets kind or apiVersion;
• the referring resource is one of the built-in kinds by refuses;
• a workload’s pod requires the object: a secret, configMap or projected volume, env or envFrom reference without optional = true, a PersistentVolumeClaim, or serviceAccountName.

A self reference passed to another resource, for example through out, is an ordinary claim there, and the architecture.untrackedReferences audit lists the name.

Explanation

See Escape hatches for when to reach for kix.untrackedRef.