Skip to content

Latest commit

 

History

History
172 lines (121 loc) · 6.99 KB

CONTRIBUTING.md

File metadata and controls

172 lines (121 loc) · 6.99 KB
Raw

Contributing Guide

Prerequisites

openshift/builder is designed to run exclusively on Linux systems. If you are developing on a Windows or Mac machine, we recommend setting up a virtual environment that runs the latest Fedora, CentOS Stream, or Red Hat Enterprise Linux distribution.

You will also need to install the following dependencies on your system:

  • Go SDK - refer to go.mod for the minimum required version.
  • The following packages:
    • btrfs-progs-devel
    • device-mapper-devel
    • gpgme-devel

Compiling the Code

To get started, fork the openshift/builder repo, then clone it to a local directory:

$ mkdir -p ~/go/src/github.com/openshift
$ cd ~/go/src/github.com/openshift
$ git clone https://github.com/openshift/builder.git
$ cd builder

Once in the source code directory, run the build Makefile target to compile the binary:

$ make build

If the build succeeds, you are ready to start making code changes!

Submitting a Pull Request

Before submitting a pull request, ensure all unit tests are passing by running make test. You are encouraged to add your own unit tests alongside code contributions. This repository uses the standard Go test framework for unit tests.

Once you are satisfied with your code changes (and unit tests are passing), submit a pull request to the openshift/builder repo. A member of the OpenShift team will evaluate your change for approval.

Testing

The OpenShift Builder image is intended to run exclusively as a container within an OpenShift build. The best way to experiment with new code changes is to build the image, push to a container registry, and then configure OpenShift to deploy your "test" image when running builds.

Red Hat employees can also use cluster-bot (available on the internal Slack as an app) to launch a cluster that includes code changes submitted in a pull request. Refer to the ci-chat-bot source for more information.

Building the image

This repository can build two flavors of images:

  1. A "developer" image, which uses publicly available base images.
  2. The "product" image, which uses base images only available on Red Hat's CI infrastructure.

The two images are intended to be similar, but may have some skews due to differences in how OpenShift's build system assembles the entire platform (aka "the payload").

Developer Image

Run the build-devel-image Makefile target, giving it an appropriate host, repository, and image tag:

$ make build-devel-image IMAGE=<MYREPO>/<MYIMAGE> TAG=<MYTAG>

Product Image

This procedure will only succeed if you are a Red Hat employee and have been granted permission to pull images from the OpenShift CI system. Refer to the Openshift CI docs for instructions on how to request access to the CI container registries.

  1. First, log into the api.ci cluster using your Red Hat SSO credentials.

  2. Use the Copy Login Command to get command line access to the cluster. Note that you must have the oc command line installed on your system:

    $ oc login --token=<xxx> --server=<server_url>:<port>

  3. Once logged in to the cluster successfully, use oc to authenticate with the cluster's container registry (registry.ci.openshift.org):

    $ oc registry login

  4. Finally, build the container image using the build-image Makefile target:

    $ make build IMAGE=<MYREPO>/<MYIMAGE> TAG=<MYTAG>

Testing on an OpenShift Cluster

Cluster-bot

For Red Hat employees, the easiest way to test code changes is to submit a pull request (add "WIP" to the title if your code is not ready to merge), then create a cluster with cluster-bot referencing your PR number. Refer to the cluster-bot FAQ for an example of how to do this.

Self-Managed OpenShift

For the general public, you must first gain access to a self-managed OpenShift cluster. The builder image cannot be tested on managed clusters, such as Red Hat OpenShift Service on AWS (ROSA), because the procedure for testing brings your cluster into an unsupported state. Options include self-managed installation paths on console.redhat.com or running OpenShift Local on your machine.

You may also deploy OpenShift from a CI payload - refer to the appropriate release status page for instructions on how to deploy a cluster with a specific channel and payload.

After your cluster is installed, you will need to do the following:

  1. Patch the cluster version so that you can launch your own builder image:

    $ oc patch clusterversion/version --patch '{"spec":{"overrides":[{"group":"v1", "kind":"ConfigMap", "namespace":"openshift-controller-manager-operator", "name":"openshift-controller-manager-images", "unmanaged":true}]}}' --type=merge

  2. Alternatively, scale the Cluster Version Operator (CVO) deployment down to zero:

    $ oc scale --replicas 0 -n openshift-cluster-version deployments/cluster-version-operator

  3. Patch the ConfigMap in the override above to instruct the cluster to use your builder image:

    $ oc patch configmap openshift-controller-manager-images -n openshift-controller-manager-operator --patch '{"data":{"builderImage":"<MYREPO>/<MYIMAGE>:<MYTAG>"}}' --type=merge

  4. Wait for the openshift controller manager deployment to roll out the update (this can take a few minutes):

    $ oc get deployment controller-manager -n openshift-controller-manager -w

  5. To test your changes end to end, trigger an OpenShift build via oc start-build. You can use one of the templates suggested in oc new-app to populate your project with a build.

  6. To set your cluster back to its original state, either remove the overrides section added in step 1, or scale the CVO deployment back to previous count:

    $ oc scale --replicas 1 -n openshift-cluster-version deployments/cluster-version-operator

E2E Test Suite

The OpenShift builder is considered a core component of the OpenShift Container Platform. The e2e test suite run against each pull request is located in the openshift/origin repo. Tests whose description contains [Feature:Builds] are run as part of the e2e suite, and are generally placed in the test/extended/builds directory. Refer to the extended tests README for instructions on how to develop and run these tests against your own cluster.