DEVELOPMENT.md

Developing the IM Operator

Prerequisites

To build this project, you will need the following:

1. Go 1.16 or greater
2. operator-sdk
3. A container CLI like Podman or Docker

Build Dependencies

The Makefile is structured such that other dependencies of this project are obtained as they are needed by running go install or curl to download and install these dependencies to the bin directory of this project. The versions of these dependencies are pinned via defaulted variables within the Makefile. If you would like to run with different versions of these dependencies, install them to this project's bin directory and export the variables associated with each custom version. These variables are as follows:

• kustomize:
  • KUSTOMIZE: path to kustomize binary
  • KUSTOMIZE_VERSION: version of kustomize installed
• yq:
  • YQ: path to yq binary
  • YQ_VERSION: version of yq installed
• controller-gen:
  • CONTROLLER_GEN: path to controller-gen binary
  • CONTROLLER_TOOLS_VERSION: version of controller-gen installed
• Go:
  • GO_VERSION: version of go installed

Building Artifacts

Environment Variables

These environment variables impact the resulting build artifacts and can be changed to affect the output of the build:

• IMG: The base name of the Operator image
• REGISTRY: The registry namespace; used for Operator image builds
• IMAGE_TAG_BASE: The registry namespace and part of the image name; used for Operator bundle image builds
• GIT_COMMIT_ID: The short commit SHA for the HEAD of the current branch; used for image labels and single-arch image tags
• GIT_REMOTE_URL: The URL of the git remote for this project; used for image labels
• CONTAINER_CLI: The container tool for builds and other image-related activities
• VERSION: The version of the Operator; used for the bundle image, multi-arch manifest, and catalog image tags
• BUILD_LOCALLY: Skips pushing the images when set to "1" for targets where Operator images are built
• MODE: When set to "dev", runs bundle-related targets using development-only copies of overlays and Dockerfiles

Operator Binary

Running make build builds the Operator binary for the host OS and architecture.

Operator Images

Single-Arch Images

To build an Operator image for a single architecture only, run one of the following:

• For amd64:

  make build-image-amd64

• For ppc64le:

  make build-image-ppc64le

• For s390x:

  make build-image-s390x

Multi-Arch Images

To build an Operator image for each architecture as well as a multi-arch manifest, run the following target:

make images

Operator Bundles

The Operator bundle is generated by using a variety of tools to create and fill out the templates in the config directory. To generate the Operator bundle based upon the configuration and code present, run the following:

make bundle

Bundle Development Targets

In order to allow for development-only changes to the kustomizations and config without touching the prod kustomization overlays, you can generate a new set of development-only overlays by running the following:

make dev-overlays

This make target will copy the contents of the prod overlays into new set of dev overlay directories. A common use case is updating the Operand images to point to pre-prod references; this can be achieved by editing the image_env_vars_patch.yaml to use whichever images references you want for the Operands.

Once all of the desired changes have been made, you can create a new Operator bundle using the dev overlays by running the following:

MODE=dev make bundle

When running the above make target, it will also replace the Operator image reference in the manager manifest with ${IMAGE_TAG_BASE}:${VERSION}. These variables default to the production registry reference and latest Operator version tag respectively, but setting these variables allows you to build and push Operator images to different registries and image tags. Note that these variables are used for other make targets as well and can affect their output; see Environment Variables for more.

Finally, to build a dev bundle image, run the following target:

MODE=dev make bundle-build

Updating the Project's Version

To set the version of the project to a new SemVer, run the following:

# NEW_VERSION is the desired SemVer to set across source and artifacts, e.g. 4.11.0
VERSION="${NEW_VERSION:-}" make update-version

This will update all image tags, the production kustomize overlays, and the version set in version.go with the SemVer value of VERSION. After this target completes successfully, you should also run make bundle to update the latest production bundle with these new version values.

Cleaning Up

There may come a point at which you would like to remove old manager binaries, dev kustomize overlays, and downloaded build tools to clear the way for new ones to be written. This can be done by running the following target:

make clean

Creating an FBC Catalog

To create a custom FBC catalog for testing your changes, perform the following steps:

1. Set and export the following environment variables:
   • CATALOG_BASE_IMG should be set to the catalog image reference you wish to update bundles in or add bundles to. For example, quay.io/daily-build-namespace/ibm-common-service-catalog:cd.
   • MODE should be set to "dev" if creating a catalog image for development and testing purposes. Otherwise, this can be left unset.
   • REGISTRY should be set to the registry and namespace that you use for development images, e.g. quay.io/my-dev-namespace. If the registry is not globally readable, you will need to be sure to create a new pull secret or update an existing one to include the credentials for pulling this secret on your test cluster.
   • IMAGE_TAG_BASE should be set to ${REGISTRY}/ibm-iam-operator so that the development images are all placed in a common namespace. Going with the previous REGISTRY value example, IMAGE_TAG_BASE would be set to quay.io/my-dev-namespace/ibm-iam-operator.
   • VERSION should be set to an identifier that will help distinguish development images from one another; for example, you could set VERSION to the development branch name or commit SHA.
2. Log into the registries where images will be pushed to and pulled from so that future attempts to do this will succeed. If using a Docker-based client on macOS, e.g. Rancher Desktop, you will need to add your credentials to ~/.docker/config.json as they will not be accessible to opm from the OSX keyring. With Podman on macOS, you can instead log into the registry from within the VM like so:

   echo "${registry_token:-}" | podman machine ssh "podman login \"${registry}\" -u \"${registry_user}\" --password-stdin"

3. Run make dev-overlays if the dev kustomize overlays are not already present in the config directory.
4. Run make catalog-render - this will pull the catalog image referred to by CATALOG_BASE_IMG and render the index as a yaml file in the catalog directory.
5. Make any edits to the kustomize overlays that are necessary, e.g. run make dev-overlays and afterward write Operand image reference updates for the prod bundle build.
6. If changes to the Operator are being made, run make images so that the Operator images have been built and pushed to the location set in REGISTRY using the VERSION value for the tag.
7. Run make bundle bundle-build bundle-push to build the OLM bundle, build the image containing that bundle, and push that image to REGISTRY.
8. Optionally, run make channel-render to create an OLM channel manifest and include it in the FBC index. This is needed when the bundle is being added to a channel that does not exist yet.
9. Run make bundle-render to add the OLM bundle to the FBC.
10. Run make catalog-build catalog-push to build and push the OLM catalog image to REGISTRY. The default name for this image is ibm-iam-operator-catalog, but, if another name is desired, e.g. ibm-common-service-catalog, that can be achieved by setting the IMG variable, e.g. IMG=ibm-common-service make catalog-build catalog-push.