From 8b5c39f6f40af2f4b6478686a4ec53c1b1263821 Mon Sep 17 00:00:00 2001 From: Adam Kaplan Date: Wed, 20 Nov 2024 08:34:05 -0500 Subject: [PATCH] docs: Image Digest Pinning Add an "advanced" article to describe how `relatedImages` and image digest pinning works. This includes the use of `RELATED_IMAGE_*` environment variables to digest pin operands deployed by the operator, which is not currently documented. Signed-off-by: Adam Kaplan --- .../en/docs/advanced-topics/digest-pinning.md | 42 +++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 website/content/en/docs/advanced-topics/digest-pinning.md diff --git a/website/content/en/docs/advanced-topics/digest-pinning.md b/website/content/en/docs/advanced-topics/digest-pinning.md new file mode 100644 index 00000000000..f45ecb9cc19 --- /dev/null +++ b/website/content/en/docs/advanced-topics/digest-pinning.md @@ -0,0 +1,42 @@ +--- +title: Digest Pinning +weight: 80 +--- + +# Image Digest Pinning + +Operator authors have the ability to pin container images by their +[digest](https://github.com/opencontainers/image-spec/blob/main/descriptor.md) when generating +bundles. The digest simultaneously acts as a unique identifier for the image as well as a checksum +for the image contents. Referencing images by digest rather than their tag ensures the operator +bundle deployment is consistent and reproducible. + +## Usage + +To generate bundles that reference images by digest, pass the `--use-image-digests` flag to operator-sdk: + +```sh +$ operator-sdk generate bundle --use-image-digests +``` + +Operator projects using the `go` and `helm` builders can also set the `USE_IMAGE_DIGESTS` Makefile variable to `true`: + +```sh +$ make bundle USE_IMAGE_DIGESTS=true +``` + +## Bundle Image Detection and Resolution + +`operator-sdk` resolves image references to digests by analyzing the `ClusterServiceVersion` object +provided as input. The following fields in the CSV are used to find and resolve image references: + +- All containers in the CSV deployments (`spec.install.spec.deployments`). +- All environment variables prefixed with `RELATED_IMAGE_` and have a valid container image reference. + +Each resolved image is rendered into the ouput bundle's `ClusterServiceVersion` as follows: + +1. Images referenced by tag are updated to be referenced by image digest SHA. +2. Each resolved image is also referenced in the `spec.relatedImages` field in the bundle CSV. + +The `relatedImages` field is intended for external tools to identify all container images needed to +deploy your operator and operands. It is not required to bundle or deploy your operator.