Create Deployments using Astro Runtime SHA256 digest

By default, Deployment creation references an Astro Runtime image by its tag in the Kubernetes spec, like quay.io/astronomer/astro-runtime:9.3.0. However, image tags are mutable and can lead to non-reproducible builds if the image associated with the tag changes. Instead of using the Runtime image tag, you can configure Astro Private Cloud to reference a Runtime image’s immutable sha256 digest, such as quay.io/astronomer/astro-runtime@sha256:<digest>. Using the sha256 digest ensures secure, immutable, and reproducible Deployments, which prevents unexpected behavior caused by tag reassignments.

After you enable using the sha256 digest, when users create or update Deployments that include a SHA version, they still see the same Runtime Image tag view as before in the UI or CLI, but the system resolves the build using the sha256 digest in the Kubernetes spec.

Step 1: Enable configuration

Apply a config change to your Houston values.yaml file to enable customImageShaEnabled.

1
astronomer:
2
  houston:
3
    config:
4
      deployments:
5
        customImageShaEnabled: true

Step 2: (Optional) Correlate SHA256 with Runtime versions

By default, Astro Private Cloud checks for Airflow updates, which are included in the Astro Runtime, once per day at midnight by querying https://updates.astronomer.io/astronomer-runtime. This returns a JSON file with details about the latest available Astro Runtime versions.

You can store this information in the cluster itself by completing the following steps:

1. Download the JSON files and store them in a Kubernetes configmap by running the following commands:

1
curl -XGET https://updates.astronomer.io/astronomer-runtime -o astro_runtime_releases.json
2
3
kubectl -n <astronomer platform namespace> create configmap astro-runtime-base-images --from-file=astro_runtime_releases.json

2. Open the astro_runtime_release.json file and manually add the SHA256 values that you want Deployments to use for each Runtime version. For example, the following code example shows

1
"13.0.0": {
2
  "metadata": {
3
    "airflowVersion": "2.11.0",
4
    "channel": "stable",
5
    "releaseDate": "2025-05-20",
6
    "endOfSupport": "2026-11-30",
7
    "LTS": true
8
  },
9
  "migrations": {
10
    "airflowDatabase": false,
11
    "stellarDatabase": false
12
  }
13
}

Add the Tag and SHA256 value and save:

1
"13.0.0": {
2
  "metadata": {
3
    "airflowVersion": "2.11.0",
4
    "channel": "stable",
5
    "releaseDate": "2025-05-20",
6
    "endOfSupport": "2026-11-30",
7
     "LTS": true
8
  },
9
  "migrations": {
10
    "airflowDatabase": false,
11
    "stellarDatabase": false
12
  },
13
  "sha256": "82dc7efe0b16acc74e96a82bc8f1fd1db35a76a5a8c32f581d171d9765c02326"
14
}

3. Add your configmap name, astro-runtime-base-images to your Houston configuration using the runtimeReleasesConfigMapName configuration:

1
astronomer:
2
  houston:
3
    runtimeReleasesConfigMapName: astro-runtime-base-images
4
    config:
5
      airgapped:
6
        enabled: true

Step 3: (Optional) Specify default Runtime

If you want to configure your platform to create Deployments with a single, specific Runtime version, you can add the defaultRuntimeRepository configuration to specify the Runtime:

1
astronomer:
2
  houston:
3
    config:
4
      deployments:
5
        customImageShaEnabled: true
6
      helm:
7
        defaultRuntimeRepository: quay.io/astronomer/astro-runtime@sha256