How-to guide Promote images

Pin an instance's image without code

An instance pin sets one image option of one instance. No Nix reads it: Kix applies it to the option itself. Pinning a package’s default image is then adding an entry to the pin file, and returning to the default is deleting it.

This guide assumes your cluster already has a pin file. See Create a committed image pin file to start one.

Pass the pin file to the cluster

Kix applies instance pins from the file you pass to kix.buildCluster as pins. With mkFlake { pins = ./pins.json; }, a cluster function that takes pins passes it on:

114
  inherit pins;

View source on GitHub ↗

A cluster that reads its own file passes pins = kix.pins ./pins.json; the same way. A file with instance pins belongs to one cluster: Kix refuses a pin for an instance the cluster does not have, so in a flake with several clusters, give each one its own pin file.

Pin the image

Name the instance as <namespace>/<instance>. A new instance pin needs the repository; later moves keep it:

kix-project/

❱ kix pin set monitoring/grafana --repository docker.io/grafana/grafana --tag 13.1.3

❱ kix pin set monitoring/grafana --tag 13.1.4

Kix resolves the tag and writes the digest. The entry sets instances.monitoring.grafana.config.image:

1
"instances": {
2
  "monitoring/grafana": {
3
    "image": {
4
      "repository": "docker.io/grafana/grafana",
5
      "tag": "13.1.4",
6
      "digest": "sha256:…"
7
    }
8
  }
9
}

For an image option other than image, add --option with its path in the instance’s config, such as --option sidecar.image. When a package runs several images from one release, pin each of them: pinning only the main image moves the others’ tags and drops their digests. A tool that writes pins for you should do the same.

A file with instance pins declares "version": 2. A Kix that reads only version 1 refuses it with an error asking you to upgrade Kix.

Remove the value from code

A pin and a value in the cluster’s code for the same option is an evaluation error naming both places, unless the value is a lib.mkDefault, which the pin wins over, so delete the value in code, such as image.tag = "13.1.3";, in the commit that adds the pin. Kix also refuses an instance pin for an instance the cluster does not have, or for an option that is not an image option.

Moving a value from code to a pin changes no manifest, so the Activation keeps its name and the deploy is a no-op.

Check where each image comes from

kix-image-sources.json, beside the Activation in the build result, lists each image option with its value, the package’s default, and its origin: pin, package_default, code, injected, or nix_built. After the move, the instance’s image reports "origin": "pin".