github.com/openshift/installer@v1.4.17/docs/dev/alternative_release_image_sources.md (about)

     1  # Alternative Release-Image Sources
     2  
     3  ## release-image content vs release-image source
     4  
     5  `release-image` **content** - which operators get installed to the cluster & which version/container image of each operator  
     6  `release-image` **source** - where `release-image` content gets pulled from
     7  
     8  The installer controls *both* the `release-image` content and source using the embedded release-image location or the `OPENSHIFT_INSTALL_RELEASE_IMAGE_OVERRIDE` env. Users may also use a release-image from a private registry (change the `release-image` source), but keep the `release-image` content identical to one vetted by OpenShift.
     9  
    10  ## Controlling the content
    11  
    12  The content of the `release-image`, i.e. the digest, continues to be controlled by the embedded release-image location or the `OPENSHIFT_INSTALL_RELEASE_IMAGE_OVERRIDE` env.
    13  
    14  ## Controlling the source
    15  
    16  The installer allows the users to specify sources for the release-image repository and other repositories referenced in the release-image through the InstallConfig.
    17  
    18  ## Details
    19  
    20  The design is based on the assumption that all flows of using multiple sources/repositories for the release-image originate with the `oc adm release mirror` command to create those sources/repositories.
    21  
    22  ## InstallConfig
    23  
    24  ```go
    25  type InstallConfig struct {
    26      // ImageContentSources lists sources/repositories for the release-image content.
    27      ImageContentSources []ImageContentSource `json:"imageContentSources"`
    28  }
    29  
    30  // ImageContentSource defines a list of sources/repositories that can be used to pull content.
    31  type ImageContentSource struct {
    32      Source  string   `json:"source"`
    33      Mirrors []string `json:"mirrors"`
    34  }
    35  ```
    36  
    37  If the release-image `q.io/ocp/release-x.y@sha256:abc` which has references to the images in repositories `q.io/openshift/x.y` was mirrored to `local.registry.com/ocp/release-x.y`, the `install-config.yaml` would look like,
    38  
    39  ```yaml
    40  ...
    41  imageContentSources:
    42  - source: q.io/ocp/release-x.y
    43    mirrors:
    44    - local.registry.com/ocp/release-x.y
    45  - source: q.io/openshift/x.y
    46    mirrors:
    47    - local.registry.com/ocp/release-x.y
    48  ...
    49  ```
    50  
    51  ### ImageContentSourcePolicy
    52  
    53  If a list of `ImageContentSources` is specified, the installer configures the [RepositoryDigestMirrors][repository-digest-mirrors] for each `ImageContentSource`.
    54  
    55  Using the same `install-config.yaml` from above, the `ImageContentSourcePolicy` object would look like:
    56  
    57  ```yaml
    58  ...
    59  repositoryDigestMirrors:
    60  - source: q.io/ocp/release-x.y
    61    mirrors:
    62    - local.registry.com/ocp/release-x.y
    63  - source: q.io/openshift/x.y
    64    mirrors:
    65    - local.registry.com/ocp/release-x.y
    66  ...
    67  ```
    68  
    69  ### release-image location
    70  
    71  The release-image location that is propagated to the bootstrap node and the cluster-version-operator will continue to be the embedded release-image location.
    72  
    73  ### Bootstrap machine containers-registries.conf
    74  
    75  If a list of `ImageContentSources` is specified, the [Registries][registry-containers-registries-conf] will be configured to have each source be a mirror for another.
    76  
    77  For example, our `install-config.yaml` will result in:
    78  
    79  ```toml
    80  [[registry]]
    81  location = "q.io/ocp/release-x.y"
    82  mirror-by-digest-only = true
    83  
    84  [[registry.mirror]]
    85  location = "local.registry.com/ocp/release"
    86  
    87  [[registry]]
    88  location = "q.io/openshift/x.y"
    89  mirror-by-digest-only = true
    90  
    91  [[registry.mirror]]
    92  location = "local.registry.com/ocp/release"
    93  ```
    94  
    95  ### oc adm release mirror
    96  
    97  The `release mirror` mirrors the release-image and all other images referenced in the release-image to another repository and then provides details for setting up the `install-config.yaml`.
    98  
    99  The output would look like:
   100  
   101  ```console
   102  Release Image q.io/ocp/release-x.y@sha256:abcd was successfully mirrored to local.registry.com/ocp/release-x.y@sha256:abcd
   103  
   104  Following section can be added to the install-config.yaml to create a cluster using new repository:
   105  imageContentSources:
   106  - source: q.io/ocp/release-x.y
   107    mirrors:
   108    - local.registry.com/ocp/release-x.y
   109  - source: q.io/openshift/x.y
   110    mirrors:
   111    - local.registry.com/ocp/release-x.y
   112  ```
   113  
   114  [repository-digest-mirrors]: https://github.com/openshift/api/blob/9525304a0adb725ab4a4a54539a1a6bf6cc343d3/operator/v1alpha1/types_image_content_source_policy.go#L56
   115  [registry-containers-registries-conf]: https://github.com/containers/image/blob/v2.0.0/docs/containers-registries.conf.5.md#remapping-and-mirroring-registries