docs: mention digests support in imageName

gbartolini · mnencia · web-flow · commit 80c34d0122d4 · 2021-06-07T18:19:08.000+02:00
To get deterministic and repeatable deployments, you can add the digests to the image name, through the `<image>:<tag>@sha256:<digestValue>` format. This will ensure that you deploy the exact same image manifest. Co-authored-by: Marco Nenciarini <marco.nenciarini@enterprisedb.com>
diff --git a/api/v1/cluster_types.go b/api/v1/cluster_types.go
@@ -78,7 +78,9 @@ type ClusterSpec struct {
 	// Description of this PostgreSQL cluster
 	Description string `json:"description,omitempty"`
 
-	// Name of the container image
+	// Name of the container image, supporting both tags (`<image>:<tag>`)
+	// and digests for deterministic and repeatable deployments
+	// (`<image>:<tag>@sha256:<digestValue>`)
 	ImageName string `json:"imageName,omitempty"`
 
 	// The UID of the `postgres` user inside the image, defaults to `26`
diff --git a/config/crd/bases/postgresql.k8s.enterprisedb.io_clusters.yaml b/config/crd/bases/postgresql.k8s.enterprisedb.io_clusters.yaml
@@ -458,7 +458,8 @@ spec:
                   type: object
                 type: array
               imageName:
-                description: Name of the container image
+                description: Name of the container image, supporting both tags (`<image>:<tag>`)
+                  and digests for deterministic and repeatable deployments (`<image>:<tag>@sha256:<digestValue>`)
                 type: string
               imagePullSecrets:
                 description: The list of pull secrets to be used to pull the images
diff --git a/docs/src/api_reference.md b/docs/src/api_reference.md
@@ -243,7 +243,7 @@ ClusterSpec defines the desired state of Cluster
 Name                  | Description                                                                                                                                                                                                    | Type                                                                                                                            
 --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------
 `description          ` | Description of this PostgreSQL cluster                                                                                                                                                                         | string                                                                                                                          
-`imageName            ` | Name of the container image                                                                                                                                                                                    | string                                                                                                                          
+`imageName            ` | Name of the container image, supporting both tags (`<image>:<tag>`) and digests for deterministic and repeatable deployments (`<image>:<tag>@sha256:<digestValue>`)                                            | string                                                                                                                          
 `postgresUID          ` | The UID of the `postgres` user inside the image, defaults to `26`                                                                                                                                              | int64                                                                                                                           
 `postgresGID          ` | The GID of the `postgres` user inside the image, defaults to `26`                                                                                                                                              | int64                                                                                                                           
 `instances            ` | Number of instances required in the cluster                                                                                                                                                                    - *mandatory*  | int32                                                                                                                           
diff --git a/docs/src/operator_capability_levels.md b/docs/src/operator_capability_levels.md
@@ -54,7 +54,8 @@ Community and published on Quay.io by EnterpriseDB.
 You can use any compatible image of PostgreSQL supporting the
 primary/standby architecture directly by setting the `imageName`
 attribute in the CR. The operator also supports `imagePullSecretsNames`
-to access private container registries.
+to access private container registries, as well as digests in addition to
+tags for finer control of container image immutability.
 
 ### Labels and annotations
 
diff --git a/docs/src/quickstart.md b/docs/src/quickstart.md
@@ -169,3 +169,5 @@ spec:
     Never use tags like `latest` or `13` in a production environment
     as it might lead to unpredictable scenarios in terms of update
     policies and version consistency in the cluster.
+    For strict deterministic and repeatable deployments, you can add the digests
+    to the image name, through the `<image>:<tag>@sha256:<digestValue>` format.
