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.