From b3a5a6634e43d93af583d111412daceb76da69aa Mon Sep 17 00:00:00 2001 From: Evan Cordell Date: Tue, 9 Jul 2019 10:52:40 -0400 Subject: [PATCH 1/3] proposal(relatedImages): add a proposal for specifying related images in CSVs --- .../design-proposals/related-images.md | 192 ++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 Documentation/contributors/design-proposals/related-images.md diff --git a/Documentation/contributors/design-proposals/related-images.md b/Documentation/contributors/design-proposals/related-images.md new file mode 100644 index 0000000000..e397a05d1f --- /dev/null +++ b/Documentation/contributors/design-proposals/related-images.md @@ -0,0 +1,192 @@ +# Related Images + +Status: Pending + +Version: Alpha + +Implementation Owner: ecordell + +## Motivation + +Operators often need to make use of other container images to perform their functions as operators. + +## Proposal + +Introduce a new field `relatedImages` to the `ClusterServiceVersion` spec. + +### ClusterServiceVersion Spec Changes + +A new section `relatedImages` is added to the ClusterServiceVersionSpec. + +```yaml +kind: ClusterServiceVersion +metadata: + name: etcd-operator +spec: + relatedImages: + - name: default + image: quay.io/coreos/etcd@sha256:12345 + annotation: default + - name: etcd-2.1.5 + image: quay.io/coreos/etcd@sha256:12345 + - name: etcd-3.1.1 + image: quay.io/coreos/etcd@sha256:12345 +``` + +These will be made available as annotations on the operator deployments, so that they can be used via downward API if desired. This may be particularly useful for operators that are tightly coupled to another particular image. + +```yaml +kind: Deployment +metadata: + name: etcd-operator + annotations: + default: quay.io/coreos/etcd@sha256:12345 + olm.relatedImage.etcd-2.1.5: quay.io/coreos/etcd@sha256:12345 + olm.relatedImage.etcd-3.1.1: quay.io/coreos/etcd@sha256:12345 +spec: + replicas: 1 + selector: + matchLabels: + name: etcd-operator + template: + metadata: + name: etcd-operator + labels: + name: etcd-operator + spec: + serviceAccountName: etcd-operator + containers: + - name: etcd-operator + command: + - etcd-operator + - --create-crd=false + - --defaultImage=${DEFAULT} + image: quay.io/coreos/etcd-operator@sha256:c0301e4686c3ed4206e370b42de5a3bd2229b9fb4906cf85f3f30650424abec2 + env: + - name: NAMESPACE + valueFrom: + fieldRef: + fieldPath: metadata.namespace + - name: DEFAULT + valueFrom: + fieldRef: + fieldPath: metadata.annotations['default'] +``` + +### Implementation + +#### ClusterServiceVersion Spec and Status + +Spec needs to be updated to include the fields described above, and the openapi validation should be updated as well. + +Note that the `name` field for related images must satisfy the annotation name conventions. + +#### Install Strategy + +Most of the change will take place in the install strategy; which knows how to take the deployment spec defined in a CSV and check if the cluster is up-to-date, and apply changes if needed. + +- The install strategy will now need to know about related images. + - `CheckInstalled` will check that the annotations on the operator deployments include the `relatedImages` annotations. + - `Install` will also need to project the relatedImages as annotations on the deployment. + +#### Implementation Stages + +- [ ] API Changes +- [ ] Annotation Projection on Deployments + +### User Documentation + +#### Associating Related Images + +Operators often need to make use of other container images to perform their functions. For example, the etcd operator +makes use of etcd container images to create etcd clusters as requested by the user. + +To indicate that such images are used by the operator, a ClusterServiceVersion author can fill out the `relatedImages` +field on the CSV spec. + +These fields are optional, but should be filled out whenever possible. Tooling can take advantage of this information +to ensure that all required images are available in the cluster. + +```yaml +kind: ClusterServiceVersion +metadata: + name: etcd-operator +spec: + relatedImages: + - name: default + image: quay.io/coreos/etcd@sha256:12345 + annotation: default + - name: etcd-2.1.5 + image: quay.io/coreos/etcd@sha256:12345 + - name: etcd-3.1.1 + image: quay.io/coreos/etcd@sha256:12345 +``` + + +#### Using related images via downwardAPI + +The related images can be consumed by the operator deployment. This may be useful if, for example, the operator +and operand images are tightly coupled. The `annotation` field from the `relatedImages` is used as the name of the annotation. + +These will be made available as annotations on the operator deployments, so that they can be used via downward API if desired. This may be particularly useful for operators that are tightly coupled to another particular image. + +```yaml +kind: Deployment +metadata: + name: etcd-operator + annotations: + default: quay.io/coreos/etcd@sha256:12345 + olm.relatedImage.etcd-2.1.5: quay.io/coreos/etcd@sha256:12345 + olm.relatedImage.etcd-3.1.1: quay.io/coreos/etcd@sha256:12345 +spec: + replicas: 1 + selector: + matchLabels: + name: etcd-operator + template: + metadata: + name: etcd-operator + labels: + name: etcd-operator + spec: + serviceAccountName: etcd-operator + containers: + - name: etcd-operator + command: + - etcd-operator + - --create-crd=false + - --defaultImage=${DEFAULT} + image: quay.io/coreos/etcd-operator@sha256:c0301e4686c3ed4206e370b42de5a3bd2229b9fb4906cf85f3f30650424abec2 + env: + - name: NAMESPACE + valueFrom: + fieldRef: + fieldPath: metadata.namespace + - name: DEFAULT + valueFrom: + fieldRef: + fieldPath: metadata.annotations['default'] +``` + +### Future Work + +#### Required Images + +Any of the related images may be marked required. This would prevent the operator from installing if the required image is unavailable. + + +```yaml +kind: ClusterServiceVersion +metadata: + name: etcd-operator +spec: + relatedImages: + - name: default + image: quay.io/coreos/etcd@sha256:12345 + annotation: default + required: true + - name: etcd-2.1.5 + image: quay.io/coreos/etcd@sha256:12345 + - name: etcd-3.1.1 + image: quay.io/coreos/etcd@sha256:12345 +``` From b3e6d463a1529ed904f06e121ab81deeaa2c5779 Mon Sep 17 00:00:00 2001 From: Evan Cordell Date: Thu, 25 Jul 2019 10:39:03 -0400 Subject: [PATCH 2/3] proposal(relatedImages): update related images proposal to use kustomize --- .../design-proposals/related-images.md | 227 +++++++----------- 1 file changed, 82 insertions(+), 145 deletions(-) diff --git a/Documentation/contributors/design-proposals/related-images.md b/Documentation/contributors/design-proposals/related-images.md index e397a05d1f..3ae221e7f8 100644 --- a/Documentation/contributors/design-proposals/related-images.md +++ b/Documentation/contributors/design-proposals/related-images.md @@ -12,181 +12,118 @@ Operators often need to make use of other container images to perform their func ## Proposal -Introduce a new field `relatedImages` to the `ClusterServiceVersion` spec. +We will take advantage of the [images metadata](https://github.com/kubernetes-sigs/kustomize/blob/master/docs/fields.md#images) +for kustomization files and include a `kustomization.yaml` file within the bundle. -### ClusterServiceVersion Spec Changes - -A new section `relatedImages` is added to the ClusterServiceVersionSpec. +This can be used to write down additional metadata, or as a way to +change only the images in a bundle without touching the rest of the definition (i.e. as part of a CI/CD process). ```yaml -kind: ClusterServiceVersion -metadata: - name: etcd-operator -spec: - relatedImages: - - name: default - image: quay.io/coreos/etcd@sha256:12345 - annotation: default - - name: etcd-2.1.5 - image: quay.io/coreos/etcd@sha256:12345 - - name: etcd-3.1.1 - image: quay.io/coreos/etcd@sha256:12345 +images: +- name: postgres + newName: my-registry/my-postgres + newTag: v1 +- name: nginx + newTag: 1.8.0 +- name: my-demo-app + newName: my-app +- name: alpine + digest: sha256:24a0c4b4a4c0eb97a1aabb8e29f18e917d05abfe1b7a7c07857230879ce7d3d3 ``` -These will be made available as annotations on the operator deployments, so that they can be used via downward API if desired. This may be particularly useful for operators that are tightly coupled to another particular image. +([image type](https://github.com/kubernetes-sigs/kustomize/blob/master/pkg/image/image.go)) -```yaml -kind: Deployment -metadata: - name: etcd-operator - annotations: - default: quay.io/coreos/etcd@sha256:12345 - olm.relatedImage.etcd-2.1.5: quay.io/coreos/etcd@sha256:12345 - olm.relatedImage.etcd-3.1.1: quay.io/coreos/etcd@sha256:12345 -spec: - replicas: 1 - selector: - matchLabels: - name: etcd-operator - template: - metadata: - name: etcd-operator - labels: - name: etcd-operator - spec: - serviceAccountName: etcd-operator - containers: - - name: etcd-operator - command: - - etcd-operator - - --create-crd=false - - --defaultImage=${DEFAULT} - image: quay.io/coreos/etcd-operator@sha256:c0301e4686c3ed4206e370b42de5a3bd2229b9fb4906cf85f3f30650424abec2 - env: - - name: NAMESPACE - valueFrom: - fieldRef: - fieldPath: metadata.namespace - - name: DEFAULT - valueFrom: - fieldRef: - fieldPath: metadata.annotations['default'] -``` +The images in the `image` list will be used to determine the set of related images that are required for the operator. -### Implementation +The images in this list will be considered related even if applying the config to the ClusterServiceVersion would not +transform it (i.e. the `name` of an image does not need to exist in the CSV). -#### ClusterServiceVersion Spec and Status +The kustomization will be applied to the CSV, so the `image` config may be used to overwrite the images in the deployment in the CSV. -Spec needs to be updated to include the fields described above, and the openapi validation should be updated as well. +### Why kustomize? -Note that the `name` field for related images must satisfy the annotation name conventions. +There are several other existing approaches to associating images with an application. -#### Install Strategy +CNAB: Using CNAB's `bundle.json` would allow us to associate image metadata, but comes with a heavy spec. CNAB bundles cannot be applied directly to a kubernetes cluster, they require additional tooling. -Most of the change will take place in the install strategy; which knows how to take the deployment spec defined in a CSV and check if the cluster is up-to-date, and apply changes if needed. +ImageStream: OpenShift ClusterOperators include an `image-references` file that contains an ImageStream object. This allows listing objects, but is not meaningful when applied to a cluster (despite being a real object), and can only be applied to OpenShift clusters. -- The install strategy will now need to know about related images. - - `CheckInstalled` will check that the annotations on the operator deployments include the `relatedImages` annotations. - - `Install` will also need to project the relatedImages as annotations on the deployment. - -#### Implementation Stages +By using Kustomize's metadata, we: -- [ ] API Changes -- [ ] Annotation Projection on Deployments +- Have a way to list out images needed by the operator +- Have a way to override the images needed by the operator (without touching the base manifests) +- Retain `kubectl` compatibility; operator bundles can be applied to a cluster with `kubectl apply -k -f bundle` -### User Documentation +### Operator Registry Changes -#### Associating Related Images +If a bundle includes an `kustomization.yaml` file, images in this file are extracted during the `load` operation of a bundle into an +operator-registry database. With the following rules: -Operators often need to make use of other container images to perform their functions. For example, the etcd operator -makes use of etcd container images to create etcd clusters as requested by the user. +- Images are pulled from the ClusterServiceVersion `container` definitions as if kustomize has been run over it. +- Images are pulled from the `kustomization.yaml` file regardless of whether they are "used" by the bundle. -To indicate that such images are used by the operator, a ClusterServiceVersion author can fill out the `relatedImages` -field on the CSV spec. +If a bundle does not include a `kustomization.yaml` file, images are extracted from the ClusterServiceVersion `container` definitions. -These fields are optional, but should be filled out whenever possible. Tooling can take advantage of this information -to ensure that all required images are available in the cluster. +The `Query` interface for an operator-registry database will have two new APIs: -```yaml -kind: ClusterServiceVersion -metadata: - name: etcd-operator -spec: - relatedImages: - - name: default - image: quay.io/coreos/etcd@sha256:12345 - annotation: default - - name: etcd-2.1.5 - image: quay.io/coreos/etcd@sha256:12345 - - name: etcd-3.1.1 - image: quay.io/coreos/etcd@sha256:12345 +```go +type Query interface { + // ... + ListImages(ctx context.Context) ([]string, error) + GetImagesForBundle(ctx context.Context, csvName string) ([]string, error) +} ``` +`ListImages` will list all images in an operator-registry database. -#### Using related images via downwardAPI +### Example -The related images can be consumed by the operator deployment. This may be useful if, for example, the operator -and operand images are tightly coupled. The `annotation` field from the `relatedImages` is used as the name of the annotation. +```sh +$ tree bundle +bundle +├── csv.yaml +└── kustomization.yaml +``` -These will be made available as annotations on the operator deployments, so that they can be used via downward API if desired. This may be particularly useful for operators that are tightly coupled to another particular image. +**bundle/csv.yaml** ```yaml -kind: Deployment -metadata: - name: etcd-operator - annotations: - default: quay.io/coreos/etcd@sha256:12345 - olm.relatedImage.etcd-2.1.5: quay.io/coreos/etcd@sha256:12345 - olm.relatedImage.etcd-3.1.1: quay.io/coreos/etcd@sha256:12345 -spec: - replicas: 1 - selector: - matchLabels: - name: etcd-operator - template: - metadata: - name: etcd-operator - labels: - name: etcd-operator - spec: - serviceAccountName: etcd-operator - containers: - - name: etcd-operator - command: - - etcd-operator - - --create-crd=false - - --defaultImage=${DEFAULT} - image: quay.io/coreos/etcd-operator@sha256:c0301e4686c3ed4206e370b42de5a3bd2229b9fb4906cf85f3f30650424abec2 - env: - - name: NAMESPACE - valueFrom: - fieldRef: - fieldPath: metadata.namespace - - name: DEFAULT - valueFrom: - fieldRef: - fieldPath: metadata.annotations['default'] + containers: + - command: + - etcd-operator + - --create-crd=false + image: quay.io/coreos/etcd-operator@sha256:66a37fd61a06a43969854ee6d3e21087a98b93838e284a6086b13917f96b0d9b + name: etcd-operator ``` -### Future Work +**bundle/kustomization.yaml** +```yaml +images: +- name: quay.io/coreos/etcd-operator + newTag: latest +- name: quay.io/coreos/etcd + newTag: 3.0.5 +- name: quay.io/coreos/etcd + digest: sha256:24a0c4b4a4c0eb97a1aabb8e29f18e917d05abfe1b7a7c07857230879ce7d3d3 +resources: + - csv.yaml +``` -#### Required Images +The list of images will then be: -Any of the related images may be marked required. This would prevent the operator from installing if the required image is unavailable. +``` +quay.io/coreos/etcd-operator:latest +quay.io/coreos/etcd:3.0.5 +quay.io/coreos/etcd@sha256:24a0c4b4a4c0eb97a1aabb8e29f18e917d05abfe1b7a7c07857230879ce7d3d3 +``` +Note that `quay.io/coreos/etcd-operator@sha256:66a37fd61a06a43969854ee6d3e21087a98b93838e284a6086b13917f96b0d9b` is not +included, since it would be replaced with `:latest` if the `kustomization.yaml` were applied. + +### Future Work + +#### Override Operand + +Add a `relatedImages` field to the ClusterServiceVersion, and make use of kustomize's [transformer configs](https://github.com/kubernetes-sigs/kustomize/blob/master/examples/transformerconfigs/images/README.md) to teach it about those fields. +`relatedImages` can be projected into operator deployments via downward API, which will allow the kustomization file to override operand images in addition to opeator images. -```yaml -kind: ClusterServiceVersion -metadata: - name: etcd-operator -spec: - relatedImages: - - name: default - image: quay.io/coreos/etcd@sha256:12345 - annotation: default - required: true - - name: etcd-2.1.5 - image: quay.io/coreos/etcd@sha256:12345 - - name: etcd-3.1.1 - image: quay.io/coreos/etcd@sha256:12345 -``` From 840a709774ca36dcf3cf70df4384231af80650cc Mon Sep 17 00:00:00 2001 From: Evan Cordell Date: Thu, 10 Oct 2019 15:02:52 -0400 Subject: [PATCH 3/3] proposal(relatedimages): combine the two previous proposals --- .../design-proposals/related-images.md | 129 ----------- .../design-proposals/related-images.md | 214 ++++++++++++++++++ 2 files changed, 214 insertions(+), 129 deletions(-) delete mode 100644 Documentation/contributors/design-proposals/related-images.md create mode 100644 doc/contributors/design-proposals/related-images.md diff --git a/Documentation/contributors/design-proposals/related-images.md b/Documentation/contributors/design-proposals/related-images.md deleted file mode 100644 index 3ae221e7f8..0000000000 --- a/Documentation/contributors/design-proposals/related-images.md +++ /dev/null @@ -1,129 +0,0 @@ -# Related Images - -Status: Pending - -Version: Alpha - -Implementation Owner: ecordell - -## Motivation - -Operators often need to make use of other container images to perform their functions as operators. - -## Proposal - -We will take advantage of the [images metadata](https://github.com/kubernetes-sigs/kustomize/blob/master/docs/fields.md#images) -for kustomization files and include a `kustomization.yaml` file within the bundle. - -This can be used to write down additional metadata, or as a way to -change only the images in a bundle without touching the rest of the definition (i.e. as part of a CI/CD process). - -```yaml -images: -- name: postgres - newName: my-registry/my-postgres - newTag: v1 -- name: nginx - newTag: 1.8.0 -- name: my-demo-app - newName: my-app -- name: alpine - digest: sha256:24a0c4b4a4c0eb97a1aabb8e29f18e917d05abfe1b7a7c07857230879ce7d3d3 -``` - -([image type](https://github.com/kubernetes-sigs/kustomize/blob/master/pkg/image/image.go)) - -The images in the `image` list will be used to determine the set of related images that are required for the operator. - -The images in this list will be considered related even if applying the config to the ClusterServiceVersion would not -transform it (i.e. the `name` of an image does not need to exist in the CSV). - -The kustomization will be applied to the CSV, so the `image` config may be used to overwrite the images in the deployment in the CSV. - -### Why kustomize? - -There are several other existing approaches to associating images with an application. - -CNAB: Using CNAB's `bundle.json` would allow us to associate image metadata, but comes with a heavy spec. CNAB bundles cannot be applied directly to a kubernetes cluster, they require additional tooling. - -ImageStream: OpenShift ClusterOperators include an `image-references` file that contains an ImageStream object. This allows listing objects, but is not meaningful when applied to a cluster (despite being a real object), and can only be applied to OpenShift clusters. - -By using Kustomize's metadata, we: - -- Have a way to list out images needed by the operator -- Have a way to override the images needed by the operator (without touching the base manifests) -- Retain `kubectl` compatibility; operator bundles can be applied to a cluster with `kubectl apply -k -f bundle` - -### Operator Registry Changes - -If a bundle includes an `kustomization.yaml` file, images in this file are extracted during the `load` operation of a bundle into an -operator-registry database. With the following rules: - -- Images are pulled from the ClusterServiceVersion `container` definitions as if kustomize has been run over it. -- Images are pulled from the `kustomization.yaml` file regardless of whether they are "used" by the bundle. - -If a bundle does not include a `kustomization.yaml` file, images are extracted from the ClusterServiceVersion `container` definitions. - -The `Query` interface for an operator-registry database will have two new APIs: - -```go -type Query interface { - // ... - ListImages(ctx context.Context) ([]string, error) - GetImagesForBundle(ctx context.Context, csvName string) ([]string, error) -} -``` - -`ListImages` will list all images in an operator-registry database. - -### Example - -```sh -$ tree bundle -bundle -├── csv.yaml -└── kustomization.yaml -``` - -**bundle/csv.yaml** - -```yaml - containers: - - command: - - etcd-operator - - --create-crd=false - image: quay.io/coreos/etcd-operator@sha256:66a37fd61a06a43969854ee6d3e21087a98b93838e284a6086b13917f96b0d9b - name: etcd-operator -``` - -**bundle/kustomization.yaml** -```yaml -images: -- name: quay.io/coreos/etcd-operator - newTag: latest -- name: quay.io/coreos/etcd - newTag: 3.0.5 -- name: quay.io/coreos/etcd - digest: sha256:24a0c4b4a4c0eb97a1aabb8e29f18e917d05abfe1b7a7c07857230879ce7d3d3 -resources: - - csv.yaml -``` - -The list of images will then be: - -``` -quay.io/coreos/etcd-operator:latest -quay.io/coreos/etcd:3.0.5 -quay.io/coreos/etcd@sha256:24a0c4b4a4c0eb97a1aabb8e29f18e917d05abfe1b7a7c07857230879ce7d3d3 -``` - -Note that `quay.io/coreos/etcd-operator@sha256:66a37fd61a06a43969854ee6d3e21087a98b93838e284a6086b13917f96b0d9b` is not -included, since it would be replaced with `:latest` if the `kustomization.yaml` were applied. - -### Future Work - -#### Override Operand - -Add a `relatedImages` field to the ClusterServiceVersion, and make use of kustomize's [transformer configs](https://github.com/kubernetes-sigs/kustomize/blob/master/examples/transformerconfigs/images/README.md) to teach it about those fields. -`relatedImages` can be projected into operator deployments via downward API, which will allow the kustomization file to override operand images in addition to opeator images. - diff --git a/doc/contributors/design-proposals/related-images.md b/doc/contributors/design-proposals/related-images.md new file mode 100644 index 0000000000..f34473b74b --- /dev/null +++ b/doc/contributors/design-proposals/related-images.md @@ -0,0 +1,214 @@ +# Related Images + +Status: Pending + +Version: Alpha + +Implementation Owner: ecordell + +# Motivation + +Operators often need to make use of other container images to perform their functions as operators. + +## Proposal + +Introduce a new field `relatedImages` to the `ClusterServiceVersion` spec. + +### ClusterServiceVersion Spec Changes + +A new section `relatedImages` is added to the ClusterServiceVersionSpec. + +```yaml +kind: ClusterServiceVersion +metadata: + name: etcd-operator +spec: + relatedImages: + - name: default + image: quay.io/coreos/etcd@sha256:12345 + annotation: default + - name: etcd-2.1.5 + image: quay.io/coreos/etcd@sha256:12345 + - name: etcd-3.1.1 + image: quay.io/coreos/etcd@sha256:12345 +``` + +These will be made available as annotations on the operator deployments, so that they can be used via downward API if desired. This may be particularly useful for operators that are tightly coupled to another particular image. + +```yaml +kind: Deployment +metadata: + name: etcd-operator + annotations: + default: quay.io/coreos/etcd@sha256:12345 + olm.relatedImage.etcd-2.1.5: quay.io/coreos/etcd@sha256:12345 + olm.relatedImage.etcd-3.1.1: quay.io/coreos/etcd@sha256:12345 +spec: + replicas: 1 + selector: + matchLabels: + name: etcd-operator + template: + metadata: + name: etcd-operator + labels: + name: etcd-operator + spec: + serviceAccountName: etcd-operator + containers: + - name: etcd-operator + command: + - etcd-operator + - --create-crd=false + - --defaultImage=${DEFAULT} + image: quay.io/coreos/etcd-operator@sha256:c0301e4686c3ed4206e370b42de5a3bd2229b9fb4906cf85f3f30650424abec2 + env: + - name: NAMESPACE + valueFrom: + fieldRef: + fieldPath: metadata.namespace + - name: DEFAULT + valueFrom: + fieldRef: + fieldPath: metadata.annotations['default'] +``` + +### Implementation + +#### ClusterServiceVersion Spec and Status + +Spec needs to be updated to include the fields described above, and the openapi validation should be updated as well. + +Note that the `name` field for related images must satisfy the annotation name conventions. + +#### Install Strategy + +Most of the change will take place in the install strategy; which knows how to take the deployment spec defined in a CSV and check if the cluster is up-to-date, and apply changes if needed. + +- The install strategy will now need to know about related images. + - `CheckInstalled` will check that the annotations on the operator deployments include the `relatedImages` annotations. + - `Install` will also need to project the relatedImages as annotations on the deployment. + +#### Implementation Stages + +- [ ] API Changes +- [ ] Annotation Projection on Deployments + +### User Documentation + +#### Associating Related Images + +Operators often need to make use of other container images to perform their functions. For example, the etcd operator +makes use of etcd container images to create etcd clusters as requested by the user. + +To indicate that such images are used by the operator, a ClusterServiceVersion author can fill out the `relatedImages` +field on the CSV spec. + +These fields are optional, but should be filled out whenever possible. Tooling can take advantage of this information +to ensure that all required images are available in the cluster. + +```yaml +kind: ClusterServiceVersion +metadata: + name: etcd-operator +spec: + relatedImages: + - name: default + image: quay.io/coreos/etcd@sha256:12345 + annotation: default + - name: etcd-2.1.5 + image: quay.io/coreos/etcd@sha256:12345 + - name: etcd-3.1.1 + image: quay.io/coreos/etcd@sha256:12345 +``` + +### Operator Registry Changes + +If a CSV includes an `relatedImages` section, images in this file are extracted during the `load` operation of a bundle into an +operator-registry database. With the following rules: + +- Images are pulled from the ClusterServiceVersion `container` definitions as if kustomize has been run over it. +- Images are read from the `relatedImages section` + +If a bundle does not include a `relatedImages` section, images are extracted from the ClusterServiceVersion `container` definitions. + +The `Query` interface for an operator-registry database will have two new APIs: + +```go +type Query interface { + // ... + ListImages(ctx context.Context) ([]string, error) + GetImagesForBundle(ctx context.Context, csvName string) ([]string, error) +} +``` + +`ListImages` will list all images in an operator-registry database. + + +### Future Work + +#### Using related images via downwardAPI + +The related images can be consumed by the operator deployment. This may be useful if, for example, the operator +and operand images are tightly coupled. The `annotation` field from the `relatedImages` is used as the name of the annotation. + +These will be made available as annotations on the operator deployments, so that they can be used via downward API if desired. This may be particularly useful for operators that are tightly coupled to another particular image. + +```yaml +kind: Deployment +metadata: + name: etcd-operator + annotations: + default: quay.io/coreos/etcd@sha256:12345 + olm.relatedImage.etcd-2.1.5: quay.io/coreos/etcd@sha256:12345 + olm.relatedImage.etcd-3.1.1: quay.io/coreos/etcd@sha256:12345 +spec: + replicas: 1 + selector: + matchLabels: + name: etcd-operator + template: + metadata: + name: etcd-operator + labels: + name: etcd-operator + spec: + serviceAccountName: etcd-operator + containers: + - name: etcd-operator + command: + - etcd-operator + - --create-crd=false + - --defaultImage=${DEFAULT} + image: quay.io/coreos/etcd-operator@sha256:c0301e4686c3ed4206e370b42de5a3bd2229b9fb4906cf85f3f30650424abec2 + env: + - name: NAMESPACE + valueFrom: + fieldRef: + fieldPath: metadata.namespace + - name: DEFAULT + valueFrom: + fieldRef: + fieldPath: metadata.annotations['default'] +``` + +#### Required Images + +Any of the related images may be marked required. This would prevent the operator from installing if the required image is unavailable. + + +```yaml +kind: ClusterServiceVersion +metadata: + name: etcd-operator +spec: + relatedImages: + - name: default + image: quay.io/coreos/etcd@sha256:12345 + annotation: default + required: true + - name: etcd-2.1.5 + image: quay.io/coreos/etcd@sha256:12345 + - name: etcd-3.1.1 + image: quay.io/coreos/etcd@sha256:12345 +```