github.com/operator-framework/operator-lifecycle-manager@v0.30.0/doc/contributors/design-proposals/related-images.md (about)

     1  # Related Images
     2  
     3  Status: Pending
     4  
     5  Version: Alpha
     6  
     7  Implementation Owner: ecordell 
     8  
     9  # Motivation
    10  
    11  Operators often need to make use of other container images to perform their functions as operators. 
    12  
    13  ## Proposal
    14  
    15  Introduce a new field `relatedImages` to the `ClusterServiceVersion` spec. 
    16  
    17  ### ClusterServiceVersion Spec Changes
    18  
    19  A new section `relatedImages` is added to the ClusterServiceVersionSpec.
    20  
    21  ```yaml
    22  kind: ClusterServiceVersion 
    23  metadata:
    24    name: etcd-operator
    25  spec:
    26    relatedImages:
    27    - name: default
    28      image: quay.io/coreos/etcd@sha256:12345 
    29      annotation: default
    30    - name: etcd-2.1.5
    31      image: quay.io/coreos/etcd@sha256:12345 
    32    - name: etcd-3.1.1
    33      image: quay.io/coreos/etcd@sha256:12345 
    34  ```
    35  
    36  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.
    37  
    38  ```yaml
    39  kind: Deployment
    40  metadata:
    41    name: etcd-operator
    42    annotations:
    43      default: quay.io/coreos/etcd@sha256:12345 
    44      olm.relatedImage.etcd-2.1.5: quay.io/coreos/etcd@sha256:12345 
    45      olm.relatedImage.etcd-3.1.1: quay.io/coreos/etcd@sha256:12345 
    46  spec:
    47    replicas: 1
    48    selector:
    49      matchLabels:
    50        name: etcd-operator
    51    template:
    52      metadata:
    53        name: etcd-operator
    54        labels:
    55          name: etcd-operator
    56      spec:
    57        serviceAccountName: etcd-operator
    58        containers:
    59        - name: etcd-operator
    60          command:
    61          - etcd-operator
    62          - --create-crd=false
    63          - --defaultImage=${DEFAULT}
    64          image: quay.io/coreos/etcd-operator@sha256:c0301e4686c3ed4206e370b42de5a3bd2229b9fb4906cf85f3f30650424abec2
    65          env:
    66          - name: NAMESPACE
    67            valueFrom:
    68              fieldRef:
    69                fieldPath: metadata.namespace
    70          - name: DEFAULT
    71            valueFrom:
    72              fieldRef:
    73                fieldPath: metadata.annotations['default']
    74  ```
    75  
    76  ### Implementation
    77  
    78  #### ClusterServiceVersion Spec and Status
    79  
    80  Spec needs to be updated to include the fields described above, and the openapi validation should be updated as well.
    81  
    82  Note that the `name` field for related images must satisfy the annotation name conventions.
    83  
    84  #### Install Strategy
    85  
    86  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.
    87  
    88  - The install strategy will now need to know about related images.
    89  	- `CheckInstalled` will check that the annotations on the operator deployments include the `relatedImages` annotations.
    90  	- `Install` will also need to project the relatedImages as annotations on the deployment.
    91  	
    92  #### Implementation Stages
    93  
    94  - [ ] API Changes
    95  - [ ] Annotation Projection on Deployments
    96  
    97  ### User Documentation
    98  
    99  #### Associating Related Images
   100  
   101  Operators often need to make use of other container images to perform their functions. For example, the etcd operator 
   102  makes use of etcd container images to create etcd clusters as requested by the user.
   103  
   104  To indicate that such images are used by the operator, a ClusterServiceVersion author can fill out the `relatedImages` 
   105  field on the CSV spec.
   106  
   107  These fields are optional, but should be filled out whenever possible. Tooling can take advantage of this information
   108  to ensure that all required images are available in the cluster.
   109  
   110  ```yaml
   111  kind: ClusterServiceVersion 
   112  metadata:
   113    name: etcd-operator
   114  spec:
   115    relatedImages:
   116    - name: default
   117      image: quay.io/coreos/etcd@sha256:12345 
   118      annotation: default
   119    - name: etcd-2.1.5
   120      image: quay.io/coreos/etcd@sha256:12345 
   121    - name: etcd-3.1.1
   122      image: quay.io/coreos/etcd@sha256:12345  
   123  ```
   124  
   125  ### Operator Registry Changes
   126  
   127  If a CSV includes an `relatedImages` section, images in this file are extracted during the `load` operation of a bundle into an
   128  operator-registry database. With the following rules:
   129  
   130  - Images are pulled from the ClusterServiceVersion `container` definitions as if kustomize has been run over it.
   131  - Images are read from the `relatedImages section`
   132  
   133  If a bundle does not include a `relatedImages` section, images are extracted from the ClusterServiceVersion `container` definitions.
   134  
   135  The `Query` interface for an operator-registry database will have two new APIs: 
   136  
   137  ```go
   138  type Query interface {
   139      // ... 
   140      ListImages(ctx context.Context) ([]string, error)
   141      GetImagesForBundle(ctx context.Context, csvName string) ([]string, error)
   142  }
   143  ```
   144  
   145  `ListImages` will list all images in an operator-registry database. 
   146  
   147  
   148  ### Future Work
   149  
   150  #### Using related images via downwardAPI
   151  
   152  The related images can be consumed by the operator deployment. This may be useful if, for example, the operator
   153  and operand images are tightly coupled. The `annotation` field from the `relatedImages` is used as the name of the annotation.
   154  
   155  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.
   156  
   157  ```yaml
   158  kind: Deployment
   159  metadata:
   160    name: etcd-operator
   161    annotations:
   162      default: quay.io/coreos/etcd@sha256:12345 
   163      olm.relatedImage.etcd-2.1.5: quay.io/coreos/etcd@sha256:12345 
   164      olm.relatedImage.etcd-3.1.1: quay.io/coreos/etcd@sha256:12345 
   165  spec:
   166    replicas: 1
   167    selector:
   168      matchLabels:
   169        name: etcd-operator
   170    template:
   171      metadata:
   172        name: etcd-operator
   173        labels:
   174          name: etcd-operator
   175      spec:
   176        serviceAccountName: etcd-operator
   177        containers:
   178        - name: etcd-operator
   179          command:
   180          - etcd-operator
   181          - --create-crd=false
   182          - --defaultImage=${DEFAULT}
   183          image: quay.io/coreos/etcd-operator@sha256:c0301e4686c3ed4206e370b42de5a3bd2229b9fb4906cf85f3f30650424abec2
   184          env:
   185          - name: NAMESPACE
   186            valueFrom:
   187              fieldRef:
   188                fieldPath: metadata.namespace
   189          - name: DEFAULT
   190            valueFrom:
   191              fieldRef:
   192                fieldPath: metadata.annotations['default']
   193  ```
   194  
   195  #### Required Images
   196  
   197  Any of the related images may be marked required. This would prevent the operator from installing if the required image is unavailable.
   198  
   199  
   200  ```yaml
   201  kind: ClusterServiceVersion 
   202  metadata:
   203    name: etcd-operator
   204  spec:
   205    relatedImages:
   206    - name: default
   207      image: quay.io/coreos/etcd@sha256:12345 
   208      annotation: default
   209      required: true
   210    - name: etcd-2.1.5
   211      image: quay.io/coreos/etcd@sha256:12345 
   212    - name: etcd-3.1.1
   213      image: quay.io/coreos/etcd@sha256:12345 
   214  ```