Skip to content
Switch branches/tags
Go to file
Cannot retrieve contributors at this time

Contributing to OKD4

Introduction into release payloads

Unlike other Kubernetes distributions OKD4 has a strictly defined set of software to be installed:

  • It must be installed on a new installation of a supported OS, the setup on already provisioned machines is not supported
  • OKD doesn't use RPM repositories
  • Strictly controls most control plane details using operator pattern.

In order to install OKD4 you need an image, which contains references to all parts - its called "release payload". It contains an operator (Cluster Version Operator), a list of manifests to apply and a reference file. Its contents can be conveniently viewed using oc utility:

$ oc adm release info
Name:      4.4.0-0.okd-2020-04-14-172428
Digest:    sha256:54446b5bcbd5ec702cfa659230d2228932dfca37bd1cb5fe49cdd9ba869f9329
Created:   2020-04-14T17:27:12Z
OS/Arch:   linux/amd64
Manifests: 413

Pull From:

Release Metadata:
  Version:  4.4.0-0.okd-2020-04-14-172428
  Upgrades: <none>

Component Versions:
  kubernetes 1.17.1
  machine-os 31.20200407.20 Fedora CoreOS

  NAME                                           DIGEST
  aws-machine-controllers                        sha256:2a39cd7f86fd2ecc98d65e0a84c93d8263ecf31aafb3d49b138a84192301f092
  azure-machine-controllers                      sha256:81939c4826f3f497833b0761d42ad2e611f7e9180a9117a97ae7f4c78f1fe254
  baremetal-installer                            sha256:05a359b353b330b05a2a2dfaf92fada3769d6bdd30071684dc09e7a23e4fb647

The release payload contains references to all the images required to setup a cluster, including oc and openshift-install. These tools can be extracted from the release payload using oc adm release extract '--command-os=*' --tools --to=/path/to/destination command. Make sure you're using oc version 4 to perform this. Github releases or OCP mirrors have oc archives for your platform.

Release payloads are used during updates too - updating OKD4 means pulling a new release payload, running CVO and applying the new manifests, which causes operators to be updated etc.

Mirroring the images

If the external release image registry is not accessible in your setup, all images can be mirrored to a different registry using the mirror subcommand:

oc adm -a /path/to/pull-secret.json \
  release mirror \
  --from "" \
  --to \

This command would copy images, referenced in image to and create a new release image The new release image would use as an additional source of images.

release mirror command would also print out the mirroring configuration for the installer.

See installing a cluster on bare metal in a restricted network.

Making changes

oc adm release can be used to create new releases, amending existing releases. If one of the images needs to be updated use release new subcommand.

For example, lets create a new release with updated Prometheus image. Use release info command to print the pullspec used in the existing image:

$ oc adm release info --pullspecs | grep prometheus

With the release new command a list of replaced images can be specified:

$ oc adm -a /path/to/pull_secret.json \
  release new \
  --from-release \
  --to-image \

This command would do the following:

  • fetch --from-release image and parse image references in it
  • replace prometheus reference with a new one
  • create a new --to-image release with updated reference.

release new command supports more than one replacement in the cli (separated by the space).

Installer in the new image would also be updated - it would point to the new release:

$ oc adm release extract '--command-os=/usr/bin/openshift-install'

This installer would now use this release as a source of truth - and use Prometheus v2.17.1 pulling it from Dockerhub.

Replacing other images

Images referenced in the release payload are prepared on CI using Openshift builds from git repos (with one exception - machine-os-content, see below). In order to find out details about a particular image use --commit-urls:

$ oc adm release info --commit-urls
  NAME                                           URL 

This shows the particular commit used to build these images.

In order to include a change in OKD release you'd need to make code changes and rebuild the image. Most repositories have a Dockerfile at the root of the repo - so a simple podman build rebuilds it.

If it is not clear which Dockerfile is used to build the image refer to CI configuration: for instance, here's how machine-config-operator image gets built.

Go to<operator repo name>, where repo name is machine-config-operator. Pick the file describing CI config for particular branch - OKD 4.4 uses a forked version located on the fcos branch, so it's openshift-machine-config-operator-fcos.yaml. In images list it mentions that Dockerfile is used to build machine-config-operator image.

Building machine-os-content image

TDB, see