OLM installation
As OperatorSource is being deprecated and the bundle format will become the standard packaging for operator, this document describes how to install the RHMI operator through OLM, by creating bundles and indices and a CatalogSource. Mainly for development/testing purposes.
Nomenclature
- Bundle: A bundle is a non-runnable docker image containing the operator manifests for a specific release.
- Index: An index is a docker image exposing a database throgh GRPc, which contains references to many bundles
- OLM_TYPE: managed-api-service for RHOAM, integreatly-operator for RHMI
Both bundles and indices are potentially pulled by the cluster, so they must be made public in order to successfully perform the installation
Prerequites
opm
is a CLI tool used to automate the generation of bundles and indices.- Information on how to build it can be found here
- Releases page for direct download: https://github.com/operator-framework/operator-registry/releases
- You need to be logged to your registry.
Steps
There are 2 approaches on building the bundles and indexes for OLM installation. It is important to know, that if you need your custom build RHOAM or RHMI binary, your will need to build the image yourself and update it in the CSV in the containerImage
and image
for a given version.
To build your own RHOAM or RHMI image run:
INSTALLATION_TYPE=<managed-api|managed> ORG=<organization> make image/build
Make command above can take in a couple of parameters but the above is the minimum you should provide:
REG
- your registry, for example: quay.io, defaults to quay.io
ORG
- organisation within your registry, defaults to integreatly
PROJECT
- defaults to based on OLM TYPE - managed-api-service|integreatly-operator
TAG
- image tag, defaults to RHOAM_TAG which is the most recent version
Example:
INSTALLATION_TYPE=managed-api ORG=<quay username> TAG=master make image/build
The above will build an image of RHOAM with a tag master
Next, please push the image to your registry with:
INSTALLATION_TYPE=managed-api ORG=<quay username> TAG=master make image/push
Once the image has been pushed, ensure it's available to public and replace both fields mentioned above in the CSV.
Automated approach
In integreatly operator repository use the make create/olm/bundle
command with the following parameters:
OLM_TYPE - must be specified, refers to type of operator lifecycle manager type, can either be integreatly-operator (RHMI) or managed-api-service (RHOAM)
UPGRADE - defaults to false, if upgrade is false the oldest version specified in the BUNDLE_VERSIONS will have it's replaces removed, otherwise, replaces will stay
BUNDLE_VERSIONS - specifies the versions that are going to have the bundles build. Versions must exists in the bundle/OLM_TYPE folder and must be listed in a descending order
ORG - organisation of where to push the bundles and indexes (for quay.io it is the organisation)
REG - registry of where to push the bundles and indexes, defaults to quay.io
BUILD_TOOL - tool used for building the index, defaults to docker - for now, only podman and docker are verified as the supported build tools
OC_INSTALL - set to true if you want the catalogue source to be created pointing to the "oldest" version within the versions specified (version must have no replaces field)(must be oc logged in)
Example:
make create/olm/bundle OLM_TYPE=managed-api-service UPGRADE=false BUNDLE_VERSIONS=1.16.0,1.15.2 ORG=<YOUR_QUAY_USERNAME> OC_INSTALL=true
Running the above command will:
1. Remove replaces
field from 1.15.2 making it the initial version to be installed on the cluster
2. Build a bundle of 1.15.2 and 1.16.0 folder and push it to quay.io
3. Build an index for 1.15.2 and 1.16.0 and push it to quay.io
4. OC create catalogue source pointing to 1.15.2
The make command can also be used for a single bundle and index, or 2 releases.
Manual approach
For each release that we want to make available in OLM, we need to generate a bundle.
The bundles are stored in bundles/<OLM_TYPE>/<VERSION>
(example: integreatly-operator/bundles/managed-api-service/1.15.0
), having
one directory per release.
Generate new bundle
In order to generate a new release, the prepare-release
script can be used:
OLM_TYPE=<OLM_TYPE> SEMVER=<release version> ORG=<quay username> make release/prepare
This will generate a new directory with a new CSV and up to date manifests. Ensure the following in the newly generated CSV:
- The image references the operator image we want to use
- If this is the earliest CSV we want to make available, manually delete the
replaces
field, as otherwise it'll fail to validate the bundle when creating an index.
Build bundle for a given release
From main folder, run:
make olm/bundle BUNDLE_TAG=quay.io/<quay username>/<OLM_TYPE>-bundle:<release version> VERSION=<VERSION> OLM_TYPE=<OLM_TYPE>
Example:
make olm/bundle BUNDLE_TAG="quay.io/<quay username>/managed-api:1.15.2" VERSION=1.15.2 OLM_TYPE=managed-api-service
The above command will build the bundle for you of existing bundle files in the ./bundles/
It's important to have the CSV in a state that you need, for example, if this is the initial bundle that will be installed on cluster, remove the replaces field, if it's to use your own RHOAM binary, update the containerImage and image fields in the CSV.
If there are old bundle files in this directory you will need to remove those before re-running the bundle command.
Next, push the bundle:
docker push quay.io/<quay username>/<OLM_TYPE>-bundle:<release version>
operator-sdk bundle validate quay.io/<quay username>/<OLM_TYPE>-bundle:<release version>
Example:
docker push quay.io/<quay username>/managed-api-service-bundle:1.15.2
operator-sdk bundle validate quay.io/<quay username>/managed-api-service-bundle:1.15.2
Generate index for a given release
opm
includes tooling to generate an index for many bundles. Run the command:
opm index add \
--bundles quay.io/<your org>/<OLM_TYPE>-bundle:<bundle 1 version> \
--bundles quay.io/<your org>/<OLM_TYPE>-bundle:<bundle n version if more than one bundle in the bundle chain> \
--build-tool docker \
--tag quay.io/<your org>/<OLM_TYPE>-index:<index version>
Example:
opm index add \
--bundles quay.io/<quay username>/managed-api-service-bundle:1.15.2 \
--bundles quay.io/<quay username>/managed-api-service-bundle:1.16.0 \
--bundles quay.io/<quay username>/managed-api-service-bundle:1.17.0 \
--tag quay.io/<quay username>/managed-api-service-index:1.17.0
The following parameters have been used:
--bundles
: Specifies the tag of a bundle to include in the index. Can be passed many times, as many as bundles we want to include--build-tool
: Tool to build the image. Can be docker or podman--tag
: Tag of the index image. For convenience, use the version of the latest release included in the index
Push the index
docker push quay.io/<your org>/<OLM_TYPE>-index:<index version>
Example:
docker push quay.io/<quay username>/managed-api-service-index:1.17.0
Create CatalogSource
Once we have an index image, all we have to do is create a CatalogSource referencing that image. This will prompt the generation of a pod and a service exposing the bundles, which will be discovered and aggregated by OLM, generating the PackageManifest that we'll subscribe to.
Create the following CatalogSource
Save the YAML below to a file
rhmi-operators.yaml
and runoc apply -f rhmi-operators.yaml
apiVersion: operators.coreos.com/v1alpha1
kind: CatalogSource
metadata:
name: rhmi-operators
namespace: openshift-marketplace
spec:
sourceType: grpc
image: quay.io/<your org>/<OLM_TYPE>-index:<index version>
Prepare cluster
Run the following command to prepare the cluster:
This will create the
redhat-rhmi-operator
orredhat-rhoam-operator
namespace/project as well as the secrets required for the installation.
INSTALLATION_TYPE=<managed-api||managed> LOCAL=false make cluster/prepare/local
Deploy RHMI CR
Installation of RHOAM through OLM will not deploy the RHMI CR automatically. Run the following command to deploy the RHMI CR to the cluster:
INSTALLATION_TYPE=managed-api LOCAL=false make deploy/integreatly-rhmi-cr.yml
Install from OperatorHub
Once OLM has created the PackageManifest, find the RHOAM
or RHMI
in the operator hub and
click install
Scenario: Simulating upgrades
In order to simulate an upgrade, a separate index can be created, containing an additional release that replaces the current one. Push this index and, when ready to make the upgrade available, update the CatalogSource in the spec to reference the new index.