mkResource

scope.mkResource seals one namespaced Kubernetes manifest as a Kix resource. It supplies the package namespace and cluster and instance labels, records dependencies carried by Nix string context, and returns tracked values under out.

Use a typed workload builder for a Deployment, StatefulSet, DaemonSet, Job, or CronJob. mkResource rejects those kinds because it would bypass pod validation, availability placement, PodDisruptionBudget derivation, and network-policy processing. Use mkClusterResource for a cluster-scoped object.

This page is hand-maintained. Check kix/lib/core/resource.nix and kix/lib/scope/builders.nix when in doubt.

Arguments

Argument	Default	Meaning
apiVersion	required	Kubernetes API version, such as v1 or policy/v1.
kind	required	Kubernetes resource kind.
name	required	metadata.name. Kix validates it as a Kubernetes object name.
spec	{ }	spec, omitted when empty.
data	{ }	data, omitted when empty.
stringData	{ }	stringData, omitted when empty.
labels	{ }	Resource-specific labels, merged over the labels supplied by the scope.
annotations	{ }	Resource-specific annotations.
outputs	{ }	Additional values exported through resource.out. Values are converted to tracked strings; null values are omitted.
requires	[ ]	Explicit resource dependencies, reported as requires edges in the deploy graph.
extraDeps	[ ]	Additional ordering dependencies, reported as extra edges.
extra	{ }	Other top-level manifest fields. Use the dedicated arguments for spec, data, stringData, and metadata.
ownership	{ }	Server-side apply fields Kix may cede. See Field ownership.

factBehavior and clusterDomain are normally supplied by the package scope. Packages that own a custom kind declare its endpoint behavior on mkCRD or mkCRDRef instead of passing factBehavior to each object.

Returned resource

The result includes the manifest and its deployment identity:

Field	Meaning
manifest	Manifest with dependency context attached to its string values.
rawManifest	Plain manifest before CLI identity and package stamps are added.
outPath	Nix store path containing the sealed manifest.
out.name	Tracked resource name.
out.fqdn	<name>.<namespace>.svc.<cluster-domain>. Most useful for Services.
out.identityHash	Hash portion of the sealed manifest’s store path.
out.selector	spec.selector.matchLabels, or the resource labels when no match-label selector exists. Omitted when neither exists.
out.ports	A Service’s spec.ports.
out.url { scheme; port; }	A Service URL. scheme defaults to http; port defaults to the first Service port.

Fields from outputs are merged into out and can replace an automatically derived field. Values from out carry resource identity, so using one in another manifest normally creates the ordering edge automatically.

Example

configMap = scope.mkResource {
  apiVersion = "v1";
  kind = "ConfigMap";
  name = "${scope.instanceName}-config";
  data."app.conf" = builtins.toJSON {
    endpoint = backend.out.url { port = 8080; };
  };
  outputs.configName = "${scope.instanceName}-config";
};

The backend URL carries the backend Service’s identity into the ConfigMap. Kix records that dependency without a separate requires entry.

Field ownership

Some controllers take ownership of selected fields after an object is created. Declare those paths with ownership.cede:

webhook = scope.mkResource {
  apiVersion = "admissionregistration.k8s.io/v1";
  kind = "MutatingWebhookConfiguration";
  name = scope.instanceName;
  extra.webhooks = [ /* initial webhook */ ];
  ownership.cede = [ "webhooks[*].clientConfig.caBundle" ];
};

Kix stamps the paths as kix.run/cede-fields. If server-side apply returns a conflict and every conflicting path is covered, the deploy engine retries once without the ceded fields. A conflict on any other path still fails. Paths use the API server’s field notation without a leading dot; * matches one list element. See Cede fields to a controller for the complete workflow.