Operators

Procedure

1. Create a new project in the OpenShift Container Platform web console for this procedure. This example uses a project called my-etcd.

2. Navigate to the Operators → Installed Operators page. The Operators that have been installed to the cluster by the cluster administrator and are available for use are shown here as a list of cluster service versions (CSVs). CSVs are used to launch and manage the software provided by the Operator.

   Tip

   You can get this list from the CLI using:

   $ oc get csv

3. On the Installed Operators page, click the etcd Operator to view more details and available actions.

   As shown under Provided APIs, this Operator makes available three new resource types, including one for an etcd Cluster (the EtcdCluster resource). These objects work similar to the built-in native Kubernetes ones, such as Deployment or ReplicaSet, but contain logic specific to managing etcd.

4. Create a new etcd cluster:

   1. In the etcd Cluster API box, click Create instance.
   2. The next screen allows you to make any modifications to the minimal starting template of an EtcdCluster object, such as the size of the cluster. For now, click Create to finalize. This triggers the Operator to start up the pods, services, and other components of the new etcd cluster.

5. Click on the example etcd cluster, then click the Resources tab to see that your project now contains a number of resources created and configured automatically by the Operator.

   Verify that a Kubernetes service has been created that allows you to access the database from other pods in your project.

6. All users with the edit role in a given project can create, manage, and delete application instances (an etcd cluster, in this example) managed by Operators that have already been created in the project, in a self-service manner, just like a cloud service. If you want to enable additional users with this ability, project administrators can add the role using the following command:

   $ oc policy add-role-to-user edit <user> -n <target_project>

Procedure

1. Navigate in the web console to the Operators → OperatorHub page.

2. Scroll or type a keyword into the Filter by keyword box to find the Operator you want. For example, type advanced to find the Advanced Cluster Management for Kubernetes Operator.

   You can also filter options by Infrastructure Features. For example, select Disconnected if you want to see Operators that work in disconnected environments, also known as restricted network environments.

3. Select the Operator to display additional information.

   Note

   Choosing a Community Operator warns that Red Hat does not certify Community Operators; you must acknowledge the warning before continuing.

4. Read the information about the Operator and click Install.

5. On the Install Operator page:

   1. Choose a specific, single namespace in which to install the Operator. The Operator will only watch and be made available for use in this single namespace.
   2. Select an Update Channel (if more than one is available).
   3. Select Automatic or Manual approval strategy, as described earlier.

6. Click Install to make the Operator available to the selected namespaces on this OpenShift Container Platform cluster.

   1. If you selected a Manual approval strategy, the upgrade status of the subscription remains Upgrading until you review and approve the install plan.

      After approving on the Install Plan page, the subscription upgrade status moves to Up to date.

   2. If you selected an Automatic approval strategy, the upgrade status should resolve to Up to date without intervention.

7. After the upgrade status of the subscription is Up to date, select Operators → Installed Operators to verify that the cluster service version (CSV) of the installed Operator eventually shows up. The Status should ultimately resolve to InstallSucceeded in the relevant namespace.

   Note

   For the All namespaces…​ installation mode, the status resolves to InstallSucceeded in the openshift-operators namespace, but the status is Copied if you check in other namespaces.

   If it does not:

   1. Check the logs in any pods in the openshift-operators project (or other relevant namespace if A specific namespace…​ installation mode was selected) on the Workloads → Pods page that are reporting issues to troubleshoot further.

Procedure

1. View the list of Operators available to the cluster from OperatorHub:

   $ oc get packagemanifests -n openshift-marketplace

   Example output

   NAME                               CATALOG               AGE
   3scale-operator                    Red Hat Operators     91m
   advanced-cluster-management        Red Hat Operators     91m
   amq7-cert-manager                  Red Hat Operators     91m
   ...
   couchbase-enterprise-certified     Certified Operators   91m
   crunchy-postgres-operator          Certified Operators   91m
   mongodb-enterprise                 Certified Operators   91m
   ...
   etcd                               Community Operators   91m
   jaeger                             Community Operators   91m
   kubefed                            Community Operators   91m
   ...

   Note the catalog for your desired Operator.

2. Inspect your desired Operator to verify its supported install modes and available channels:

   $ oc describe packagemanifests <operator_name> -n openshift-marketplace

3. An Operator group, defined by an OperatorGroup object, selects target namespaces in which to generate required RBAC access for all Operators in the same namespace as the Operator group.

   The namespace to which you subscribe the Operator must have an Operator group that matches the install mode of the Operator, either the AllNamespaces or SingleNamespace mode. If the Operator you intend to install uses the AllNamespaces, then the openshift-operators namespace already has an appropriate Operator group in place.

   However, if the Operator uses the SingleNamespace mode and you do not already have an appropriate Operator group in place, you must create one.

   Note

   The web console version of this procedure handles the creation of the OperatorGroup and Subscription objects automatically behind the scenes for you when choosing SingleNamespace mode.

   1. Create an OperatorGroup object YAML file, for example operatorgroup.yaml:

      Example OperatorGroup object

      apiVersion: operators.coreos.com/v1
      kind: OperatorGroup
      metadata:
        name: <operatorgroup_name>
        namespace: <namespace>
      spec:
        targetNamespaces:
        - <namespace>

   2. Create the OperatorGroup object:

      $ oc apply -f operatorgroup.yaml

4. Create a Subscription object YAML file to subscribe a namespace to an Operator, for example sub.yaml:

   Example Subscription object

   apiVersion: operators.coreos.com/v1alpha1
   kind: Subscription
   metadata:
     name: <subscription_name>
     namespace: openshift-operators 1
   spec:
     channel: <channel_name> 2
     name: <operator_name> 3
     source: redhat-operators 4
     sourceNamespace: openshift-marketplace 5
     config:
       env: 6
       - name: ARGS
         value: "-v=10"
       envFrom: 7
       - secretRef:
           name: license-secret
       volumes: 8
       - name: <volume_name>
         configMap:
           name: <configmap_name>
       volumeMounts: 9
       - mountPath: <directory_name>
         name: <volume_name>
       tolerations: 10
       - operator: "Exists"
       resources: 11
         requests:
           memory: "64Mi"
           cpu: "250m"
         limits:
           memory: "128Mi"
           cpu: "500m"
       nodeSelector: 12
         foo: bar

   1

   For AllNamespaces install mode usage, specify the openshift-operators namespace. Otherwise, specify the relevant single namespace for SingleNamespace install mode usage.

   2

   Name of the channel to subscribe to.

   3

   Name of the Operator to subscribe to.

   4

   Name of the catalog source that provides the Operator.

   5

   Namespace of the catalog source. Use openshift-marketplace for the default OperatorHub catalog sources.

   6

   The env parameter defines a list of Environment Variables that must exist in all containers in the pod created by OLM.

   7

   The envFrom parameter defines a list of sources to populate Environment Variables in the container.

   8

   The volumes parameter defines a list of Volumes that must exist on the pod created by OLM.

   9

   The volumeMounts parameter defines a list of VolumeMounts that must exist in all containers in the pod created by OLM. If a volumeMount references a volume that does not exist, OLM fails to deploy the Operator.

   10

   The tolerations parameter defines a list of Tolerations for the pod created by OLM.

   11

   The resources parameter defines resource constraints for all the containers in the pod created by OLM.

   12

   The nodeSelector parameter defines a NodeSelector for the pod created by OLM.

5. Create the Subscription object:

   $ oc apply -f sub.yaml

   At this point, OLM is now aware of the selected Operator. A cluster service version (CSV) for the Operator should appear in the target namespace, and APIs provided by the Operator should be available for creation.

Procedure

1. Create a Subscription object YAML file that subscribes a namespace to an Operator with a specific version by setting the startingCSV field. Set the installPlanApproval field to Manual to prevent the Operator from automatically upgrading if a later version exists in the catalog.

   For example, the following sub.yaml file can be used to install the Red Hat Quay Operator specifically to version 3.4.0:

   Subscription with a specific starting Operator version

   apiVersion: operators.coreos.com/v1alpha1
   kind: Subscription
   metadata:
     name: quay-operator
     namespace: quay
   spec:
     channel: quay-v3.4
     installPlanApproval: Manual 1
     name: quay-operator
     source: redhat-operators
     sourceNamespace: openshift-marketplace
     startingCSV: quay-operator.v3.4.0 2

   1

   Set the approval strategy to Manual in case your specified version is superseded by a later version in the catalog. This plan prevents an automatic upgrade to a later version and requires manual approval before the starting CSV can complete the installation.

   2

   Set a specific version of an Operator CSV.

2. Create the Subscription object:

   $ oc apply -f sub.yaml

3. Manually approve the pending install plan to complete the Operator installation.

Procedure

1. Navigate in the web console to the Operators → OperatorHub page.

2. Scroll or type a keyword into the Filter by keyword box to find the Operator you want. For example, type advanced to find the Advanced Cluster Management for Kubernetes Operator.

   You can also filter options by Infrastructure Features. For example, select Disconnected if you want to see Operators that work in disconnected environments, also known as restricted network environments.

3. Select the Operator to display additional information.

   Note

   Choosing a Community Operator warns that Red Hat does not certify Community Operators; you must acknowledge the warning before continuing.

4. Read the information about the Operator and click Install.

5. On the Install Operator page:

   1. Select one of the following:

      • All namespaces on the cluster (default) installs the Operator in the default openshift-operators namespace to watch and be made available to all namespaces in the cluster. This option is not always available.
      • A specific namespace on the cluster allows you to choose a specific, single namespace in which to install the Operator. The Operator will only watch and be made available for use in this single namespace.
   2. Choose a specific, single namespace in which to install the Operator. The Operator will only watch and be made available for use in this single namespace.
   3. Select an Update Channel (if more than one is available).
   4. Select Automatic or Manual approval strategy, as described earlier.

6. Click Install to make the Operator available to the selected namespaces on this OpenShift Container Platform cluster.

   1. If you selected a Manual approval strategy, the upgrade status of the subscription remains Upgrading until you review and approve the install plan.

      After approving on the Install Plan page, the subscription upgrade status moves to Up to date.

   2. If you selected an Automatic approval strategy, the upgrade status should resolve to Up to date without intervention.

7. After the upgrade status of the subscription is Up to date, select Operators → Installed Operators to verify that the cluster service version (CSV) of the installed Operator eventually shows up. The Status should ultimately resolve to InstallSucceeded in the relevant namespace.

   Note

   For the All namespaces…​ installation mode, the status resolves to InstallSucceeded in the openshift-operators namespace, but the status is Copied if you check in other namespaces.

   If it does not:

   1. Check the logs in any pods in the openshift-operators project (or other relevant namespace if A specific namespace…​ installation mode was selected) on the Workloads → Pods page that are reporting issues to troubleshoot further.

Procedure

1. View the list of Operators available to the cluster from OperatorHub:

   $ oc get packagemanifests -n openshift-marketplace

   Example output

   NAME                               CATALOG               AGE
   3scale-operator                    Red Hat Operators     91m
   advanced-cluster-management        Red Hat Operators     91m
   amq7-cert-manager                  Red Hat Operators     91m
   ...
   couchbase-enterprise-certified     Certified Operators   91m
   crunchy-postgres-operator          Certified Operators   91m
   mongodb-enterprise                 Certified Operators   91m
   ...
   etcd                               Community Operators   91m
   jaeger                             Community Operators   91m
   kubefed                            Community Operators   91m
   ...

   Note the catalog for your desired Operator.

2. Inspect your desired Operator to verify its supported install modes and available channels:

   $ oc describe packagemanifests <operator_name> -n openshift-marketplace

3. An Operator group, defined by an OperatorGroup object, selects target namespaces in which to generate required RBAC access for all Operators in the same namespace as the Operator group.

   The namespace to which you subscribe the Operator must have an Operator group that matches the install mode of the Operator, either the AllNamespaces or SingleNamespace mode. If the Operator you intend to install uses the AllNamespaces, then the openshift-operators namespace already has an appropriate Operator group in place.

   However, if the Operator uses the SingleNamespace mode and you do not already have an appropriate Operator group in place, you must create one.

   Note

   The web console version of this procedure handles the creation of the OperatorGroup and Subscription objects automatically behind the scenes for you when choosing SingleNamespace mode.

   1. Create an OperatorGroup object YAML file, for example operatorgroup.yaml:

      Example OperatorGroup object

      apiVersion: operators.coreos.com/v1
      kind: OperatorGroup
      metadata:
        name: <operatorgroup_name>
        namespace: <namespace>
      spec:
        targetNamespaces:
        - <namespace>

   2. Create the OperatorGroup object:

      $ oc apply -f operatorgroup.yaml

4. Create a Subscription object YAML file to subscribe a namespace to an Operator, for example sub.yaml:

   Example Subscription object

   apiVersion: operators.coreos.com/v1alpha1
   kind: Subscription
   metadata:
     name: <subscription_name>
     namespace: openshift-operators 1
   spec:
     channel: <channel_name> 2
     name: <operator_name> 3
     source: redhat-operators 4
     sourceNamespace: openshift-marketplace 5
     config:
       env: 6
       - name: ARGS
         value: "-v=10"
       envFrom: 7
       - secretRef:
           name: license-secret
       volumes: 8
       - name: <volume_name>
         configMap:
           name: <configmap_name>
       volumeMounts: 9
       - mountPath: <directory_name>
         name: <volume_name>
       tolerations: 10
       - operator: "Exists"
       resources: 11
         requests:
           memory: "64Mi"
           cpu: "250m"
         limits:
           memory: "128Mi"
           cpu: "500m"
       nodeSelector: 12
         foo: bar

   1

   For AllNamespaces install mode usage, specify the openshift-operators namespace. Otherwise, specify the relevant single namespace for SingleNamespace install mode usage.

   2

   Name of the channel to subscribe to.

   3

   Name of the Operator to subscribe to.

   4

   Name of the catalog source that provides the Operator.

   5

   Namespace of the catalog source. Use openshift-marketplace for the default OperatorHub catalog sources.

   6

   The env parameter defines a list of Environment Variables that must exist in all containers in the pod created by OLM.

   7

   The envFrom parameter defines a list of sources to populate Environment Variables in the container.

   8

   The volumes parameter defines a list of Volumes that must exist on the pod created by OLM.

   9

   The volumeMounts parameter defines a list of VolumeMounts that must exist in all containers in the pod created by OLM. If a volumeMount references a volume that does not exist, OLM fails to deploy the Operator.

   10

   The tolerations parameter defines a list of Tolerations for the pod created by OLM.

   11

   The resources parameter defines resource constraints for all the containers in the pod created by OLM.

   12

   The nodeSelector parameter defines a NodeSelector for the pod created by OLM.

5. Create the Subscription object:

   $ oc apply -f sub.yaml

   At this point, OLM is now aware of the selected Operator. A cluster service version (CSV) for the Operator should appear in the target namespace, and APIs provided by the Operator should be available for creation.

Procedure

1. Create a Subscription object YAML file that subscribes a namespace to an Operator with a specific version by setting the startingCSV field. Set the installPlanApproval field to Manual to prevent the Operator from automatically upgrading if a later version exists in the catalog.

   For example, the following sub.yaml file can be used to install the Red Hat Quay Operator specifically to version 3.4.0:

   Subscription with a specific starting Operator version

   apiVersion: operators.coreos.com/v1alpha1
   kind: Subscription
   metadata:
     name: quay-operator
     namespace: quay
   spec:
     channel: quay-v3.4
     installPlanApproval: Manual 1
     name: quay-operator
     source: redhat-operators
     sourceNamespace: openshift-marketplace
     startingCSV: quay-operator.v3.4.0 2

   1

   Set the approval strategy to Manual in case your specified version is superseded by a later version in the catalog. This plan prevents an automatic upgrade to a later version and requires manual approval before the starting CSV can complete the installation.

   2

   Set a specific version of an Operator CSV.

2. Create the Subscription object:

   $ oc apply -f sub.yaml

3. Manually approve the pending install plan to complete the Operator installation.

1. Determine a node or set of nodes to target for the pods per your requirements. If available, note an existing label, such as node-role.kubernetes.io/app, that identifies the node or nodes. Otherwise, add a label, such as myoperator, by using a machine set or editing the node directly. You will use this label in a later step as the node selector on your project.
2. If you want to ensure that only pods with a certain label are allowed to run on the nodes, while steering unrelated workloads to other nodes, add a taint to the node or nodes by using a machine set or editing the node directly. Use an effect that ensures that new pods that do not match the taint cannot be scheduled on the nodes. For example, a myoperator:NoSchedule taint ensures that new pods that do not match the taint are not scheduled onto that node, but existing pods on the node are allowed to remain.
3. Create a project that is configured with a default node selector and, if you added a taint, a matching toleration.

Procedure

1. In the Administrator perspective of the web console, navigate to Operators → Installed Operators.
2. Click the name of the Operator you want to change the update channel for.
3. Click the Subscription tab.
4. Click the name of the update channel under Channel.
5. Click the newer update channel that you want to change to, then click Save.

6. For subscriptions with an Automatic approval strategy, the update begins automatically. Navigate back to the Operators → Installed Operators page to monitor the progress of the update. When complete, the status changes to Succeeded and Up to date.

   For subscriptions with a Manual approval strategy, you can manually approve the update from the Subscription tab.

Procedure

1. In the Administrator perspective of the OpenShift Container Platform web console, navigate to Operators → Installed Operators.
2. Operators that have a pending update display a status with Upgrade available. Click the name of the Operator you want to update.
3. Click the Subscription tab. Any update requiring approval are displayed next to Upgrade Status. For example, it might display 1 requires approval.
4. Click 1 requires approval, then click Preview Install Plan.
5. Review the resources that are listed as available for update. When satisfied, click Approve.
6. Navigate back to the Operators → Installed Operators page to monitor the progress of the update. When complete, the status changes to Succeeded and Up to date.

Procedure

1. From the Operators → Installed Operators page, scroll or type a keyword into the Filter by name to find the Operator you want. Then, click on it.

2. On the right side of the Operator Details page, select Uninstall Operator from the Actions list.

   An Uninstall Operator? dialog box is displayed, reminding you that:

   Removing the Operator will not remove any of its custom resource definitions or managed resources. If your Operator has deployed applications on the cluster or configured off-cluster resources, these will continue to run and need to be cleaned up manually.

   This action removes the Operator as well as the Operator deployments and pods, if any. Any Operands, and resources managed by the Operator, including CRDs and CRs, are not removed. The web console enables dashboards and navigation items for some Operators. To remove these after uninstalling the Operator, you might need to manually delete the Operator CRDs.

3. Select Uninstall. This Operator stops running and no longer receives updates.

Procedure

1. Check the current version of the subscribed Operator (for example, jaeger) in the currentCSV field:

   $ oc get subscription jaeger -n openshift-operators -o yaml | grep currentCSV

   Example output

     currentCSV: jaeger-operator.v1.8.2

2. Delete the subscription (for example, jaeger):

   $ oc delete subscription jaeger -n openshift-operators

   Example output

   subscription.operators.coreos.com "jaeger" deleted

3. Delete the CSV for the Operator in the target namespace using the currentCSV value from the previous step:

   $ oc delete clusterserviceversion jaeger-operator.v1.8.2 -n openshift-operators

   Example output

   clusterserviceversion.operators.coreos.com "jaeger-operator.v1.8.2" deleted

Procedure

1. Get the names of the Subscription and ClusterServiceVersion objects from the namespace where the Operator is installed:

   $ oc get sub,csv -n <namespace>

   Example output

   NAME                                                       PACKAGE                  SOURCE             CHANNEL
   subscription.operators.coreos.com/elasticsearch-operator   elasticsearch-operator   redhat-operators   5.0
   
   NAME                                                                         DISPLAY                            VERSION    REPLACES   PHASE
   clusterserviceversion.operators.coreos.com/elasticsearch-operator.5.0.0-65   OpenShift Elasticsearch Operator   5.0.0-65              Succeeded

2. Delete the subscription:

   $ oc delete subscription <subscription_name> -n <namespace>

3. Delete the cluster service version:

   $ oc delete csv <csv_name> -n <namespace>

4. Get the names of any failing jobs and related config maps in the openshift-marketplace namespace:

   $ oc get job,configmap -n openshift-marketplace

   Example output

   NAME                                                                        COMPLETIONS   DURATION   AGE
   job.batch/1de9443b6324e629ddf31fed0a853a121275806170e34c926d69e53a7fcbccb   1/1           26s        9m30s
   
   NAME                                                                        DATA   AGE
   configmap/1de9443b6324e629ddf31fed0a853a121275806170e34c926d69e53a7fcbccb   3      9m30s

5. Delete the job:

   $ oc delete job <job_name> -n openshift-marketplace

   This ensures pods that try to pull the inaccessible image are not recreated.

6. Delete the config map:

   $ oc delete configmap <configmap_name> -n openshift-marketplace

7. Reinstall the Operator using OperatorHub in the web console.

Procedure

1. Navigate in the web console to the Operators → OperatorHub page.
2. Select the Operator and click Install.

3. On the Install Operator page, modify the Subscription object to include one or more of the following environment variables in the spec section:

   • HTTP_PROXY
   • HTTPS_PROXY
   • NO_PROXY

   For example:

   Subscription object with proxy setting overrides

   apiVersion: operators.coreos.com/v1alpha1
   kind: Subscription
   metadata:
     name: etcd-config-test
     namespace: openshift-operators
   spec:
     config:
       env:
       - name: HTTP_PROXY
         value: test_http
       - name: HTTPS_PROXY
         value: test_https
       - name: NO_PROXY
         value: test
     channel: clusterwide-alpha
     installPlanApproval: Automatic
     name: etcd
     source: community-operators
     sourceNamespace: openshift-marketplace
     startingCSV: etcdoperator.v0.9.4-clusterwide

   Note

   These environment variables can also be unset using an empty value to remove any previously set cluster-wide or custom proxy settings.

   OLM handles these environment variables as a unit; if at least one of them is set, all three are considered overridden and the cluster-wide defaults are not used for the deployments of the subscribed Operator.

4. Click Install to make the Operator available to the selected namespaces.

5. After the CSV for the Operator appears in the relevant namespace, you can verify that custom proxy environment variables are set in the deployment. For example, using the CLI:

   $ oc get deployment -n openshift-operators \
       etcd-operator -o yaml \
       | grep -i "PROXY" -A 2

   Example output

           - name: HTTP_PROXY
             value: test_http
           - name: HTTPS_PROXY
             value: test_https
           - name: NO_PROXY
             value: test
           image: quay.io/coreos/etcd-operator@sha256:66a37fd61a06a43969854ee6d3e21088a98b93838e284a6086b13917f96b0d9c
   ...

Procedure

1. Create an empty config map in the namespace where the subscription for your Operator exists and include the following label:

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: trusted-ca 1
     labels:
       config.openshift.io/inject-trusted-cabundle: "true" 2

   1

   Name of the config map.

   2

   Requests the Cluster Network Operator to inject the merged bundle.

   After creating this config map, it is immediately populated with the certificate contents of the merged bundle.

2. Update your the Subscription object to include a spec.config section that mounts the trusted-ca config map as a volume to each container within a pod that requires a custom CA:

   apiVersion: operators.coreos.com/v1alpha1
   kind: Subscription
   metadata:
     name: my-operator
   spec:
     package: etcd
     channel: alpha
     config: 1
       selector:
         matchLabels:
           <labels_for_pods> 2
       volumes: 3
       - name: trusted-ca
         configMap:
           name: trusted-ca
           items:
             - key: ca-bundle.crt 4
               path: tls-ca-bundle.pem 5
       volumeMounts: 6
       - name: trusted-ca
         mountPath: /etc/pki/ca-trust/extracted/pem
         readOnly: true

   1

   Add a config section if it does not exist.

   2

   Specify labels to match pods that are owned by the Operator.

   3

   Create a trusted-ca volume.

   4

   ca-bundle.crt is required as the config map key.

   5

   tls-ca-bundle.pem is required as the config map path.

   6

   Create a trusted-ca volume mount.

Procedure

1. List Operator subscriptions:

   $ oc get subs -n <operator_namespace>

2. Use the oc describe command to inspect a Subscription resource:

   $ oc describe sub <subscription_name> -n <operator_namespace>

3. In the command output, find the Conditions section for the status of Operator subscription condition types. In the following example, the CatalogSourcesUnhealthy condition type has a status of false because all available catalog sources are healthy:

   Example output

   Conditions:
      Last Transition Time:  2019-07-29T13:42:57Z
      Message:               all available catalogsources are healthy
      Reason:                AllCatalogSourcesHealthy
      Status:                False
      Type:                  CatalogSourcesUnhealthy

Procedure

1. List the catalog sources in a namespace. For example, you can check the openshift-marketplace namespace, which is used for cluster-wide catalog sources:

   $ oc get catalogsources -n openshift-marketplace

   Example output

   NAME                  DISPLAY               TYPE   PUBLISHER   AGE
   certified-operators   Certified Operators   grpc   Red Hat     55m
   community-operators   Community Operators   grpc   Red Hat     55m
   example-catalog       Example Catalog       grpc   Example Org 2m25s
   redhat-marketplace    Red Hat Marketplace   grpc   Red Hat     55m
   redhat-operators      Red Hat Operators     grpc   Red Hat     55m

2. Use the oc describe command to get more details and status about a catalog source:

   $ oc describe catalogsource example-catalog -n openshift-marketplace

   Example output

   Name:         example-catalog
   Namespace:    openshift-marketplace
   ...
   Status:
     Connection State:
       Address:              example-catalog.openshift-marketplace.svc:50051
       Last Connect:         2021-09-09T17:07:35Z
       Last Observed State:  TRANSIENT_FAILURE
     Registry Service:
       Created At:         2021-09-09T17:05:45Z
       Port:               50051
       Protocol:           grpc
       Service Name:       example-catalog
       Service Namespace:  openshift-marketplace

   In the preceding example output, the last observed state is TRANSIENT_FAILURE. This state indicates that there is a problem establishing a connection for the catalog source.

3. List the pods in the namespace where your catalog source was created:

   $ oc get pods -n openshift-marketplace

   Example output

   NAME                                    READY   STATUS             RESTARTS   AGE
   certified-operators-cv9nn               1/1     Running            0          36m
   community-operators-6v8lp               1/1     Running            0          36m
   marketplace-operator-86bfc75f9b-jkgbc   1/1     Running            0          42m
   example-catalog-bwt8z                   0/1     ImagePullBackOff   0          3m55s
   redhat-marketplace-57p8c                1/1     Running            0          36m
   redhat-operators-smxx8                  1/1     Running            0          36m

   When a catalog source is created in a namespace, a pod for the catalog source is created in that namespace. In the preceding example output, the status for the example-catalog-bwt8z pod is ImagePullBackOff. This status indicates that there is an issue pulling the catalog source’s index image.

4. Use the oc describe command to inspect a pod for more detailed information:

   $ oc describe pod example-catalog-bwt8z -n openshift-marketplace

   Example output

   Name:         example-catalog-bwt8z
   Namespace:    openshift-marketplace
   Priority:     0
   Node:         ci-ln-jyryyg2-f76d1-ggdbq-worker-b-vsxjd/10.0.128.2
   ...
   Events:
     Type     Reason          Age                From               Message
     ----     ------          ----               ----               -------
     Normal   Scheduled       48s                default-scheduler  Successfully assigned openshift-marketplace/example-catalog-bwt8z to ci-ln-jyryyf2-f76d1-fgdbq-worker-b-vsxjd
     Normal   AddedInterface  47s                multus             Add eth0 [10.131.0.40/23] from openshift-sdn
     Normal   BackOff         20s (x2 over 46s)  kubelet            Back-off pulling image "quay.io/example-org/example-catalog:v1"
     Warning  Failed          20s (x2 over 46s)  kubelet            Error: ImagePullBackOff
     Normal   Pulling         8s (x3 over 47s)   kubelet            Pulling image "quay.io/example-org/example-catalog:v1"
     Warning  Failed          8s (x3 over 47s)   kubelet            Failed to pull image "quay.io/example-org/example-catalog:v1": rpc error: code = Unknown desc = reading manifest v1 in quay.io/example-org/example-catalog: unauthorized: access to the requested resource is not authorized
     Warning  Failed          8s (x3 over 47s)   kubelet            Error: ErrImagePull

   In the preceding example output, the error messages indicate that the catalog source’s index image is failing to pull successfully because of an authorization issue. For example, the index image might be stored in a registry that requires login credentials.

Procedure

1. Edit the OperatorCondition object for the Operator:

   $ oc edit operatorcondition <name>

2. Add a Spec.Overrides array to the object:

   Example Operator condition override

   apiVersion: operators.coreos.com/v1
   kind: OperatorCondition
   metadata:
     name: my-operator
     namespace: operators
   spec:
     overrides:
     - type: Upgradeable 1
       status: "True"
       reason: "upgradeIsSafe"
       message: "This is a known issue with the Operator where it always reports that it cannot be upgraded."
     conditions:
     - type: Upgradeable
       status: "False"
       reason: "migration"
       message: "The operator is performing a migration."
       lastTransitionTime: "2020-08-24T23:15:55Z"

   1

   Allows the cluster administrator to change the upgrade readiness to True.

Procedure

1. Create a new namespace:

   $ cat <<EOF | oc create -f -
   apiVersion: v1
   kind: Namespace
   metadata:
     name: scoped
   EOF

2. Allocate permissions that you want the Operator(s) to be confined to. This involves creating a new service account, relevant role(s), and role binding(s).

   $ cat <<EOF | oc create -f -
   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: scoped
     namespace: scoped
   EOF

   The following example grants the service account permissions to do anything in the designated namespace for simplicity. In a production environment, you should create a more fine-grained set of permissions:

   $ cat <<EOF | oc create -f -
   apiVersion: rbac.authorization.k8s.io/v1
   kind: Role
   metadata:
     name: scoped
     namespace: scoped
   rules:
   - apiGroups: ["*"]
     resources: ["*"]
     verbs: ["*"]
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: RoleBinding
   metadata:
     name: scoped-bindings
     namespace: scoped
   roleRef:
     apiGroup: rbac.authorization.k8s.io
     kind: Role
     name: scoped
   subjects:
   - kind: ServiceAccount
     name: scoped
     namespace: scoped
   EOF

3. Create an OperatorGroup object in the designated namespace. This Operator group targets the designated namespace to ensure that its tenancy is confined to it.

   In addition, Operator groups allow a user to specify a service account. Specify the service account created in the previous step:

   $ cat <<EOF | oc create -f -
   apiVersion: operators.coreos.com/v1
   kind: OperatorGroup
   metadata:
     name: scoped
     namespace: scoped
   spec:
     serviceAccountName: scoped
     targetNamespaces:
     - scoped
   EOF

   Any Operator installed in the designated namespace is tied to this Operator group and therefore to the service account specified.

4. Create a Subscription object in the designated namespace to install an Operator:

   $ cat <<EOF | oc create -f -
   apiVersion: operators.coreos.com/v1alpha1
   kind: Subscription
   metadata:
     name: etcd
     namespace: scoped
   spec:
     channel: singlenamespace-alpha
     name: etcd
     source: <catalog_source_name> 1
     sourceNamespace: <catalog_source_namespace> 2
   EOF

   1

   Specify a catalog source that already exists in the designated namespace or one that is in the global catalog namespace.

   2

   Specify a namespace where the catalog source was created.

   Any Operator tied to this Operator group is confined to the permissions granted to the specified service account. If the Operator requests permissions that are outside the scope of the service account, the installation fails with relevant errors.

1. Disable all of the default global catalogs.
2. Enable custom, curated catalogs in the same namespace where the relevant Operator groups have been pre-installed.

Procedure

1. Review the Subscription object. Its status has an object reference installPlanRef that points to the InstallPlan object that attempted to create the necessary [Cluster]Role[Binding] object(s) for the Operator:

   apiVersion: operators.coreos.com/v1
   kind: Subscription
   metadata:
     name: etcd
     namespace: scoped
   status:
     installPlanRef:
       apiVersion: operators.coreos.com/v1
       kind: InstallPlan
       name: install-4plp8
       namespace: scoped
       resourceVersion: "117359"
       uid: 2c1df80e-afea-11e9-bce3-5254009c9c23

2. Check the status of the InstallPlan object for any errors:

   apiVersion: operators.coreos.com/v1
   kind: InstallPlan
   status:
     conditions:
     - lastTransitionTime: "2019-07-26T21:13:10Z"
       lastUpdateTime: "2019-07-26T21:13:10Z"
       message: 'error creating clusterrole etcdoperator.v0.9.4-clusterwide-dsfx4: clusterroles.rbac.authorization.k8s.io
         is forbidden: User "system:serviceaccount:scoped:scoped" cannot create resource
         "clusterroles" in API group "rbac.authorization.k8s.io" at the cluster scope'
       reason: InstallComponentFailed
       status: "False"
       type: Installed
     phase: Failed

   The error message tells you:

   • The type of resource it failed to create, including the API group of the resource. In this case, it was clusterroles in the rbac.authorization.k8s.io group.
   • The name of the resource.
   • The type of error: is forbidden tells you that the user does not have enough permission to do the operation.
   • The name of the user who attempted to create or update the resource. In this case, it refers to the service account specified in the Operator group.

   • The scope of the operation: cluster scope or not.

     The user can add the missing permission to the service account and then iterate.

     Note

     Operator Lifecycle Manager (OLM) does not currently provide the complete list of errors on the first try.

Procedure

1. Start a new index:

   $ opm index add \
       --bundles <registry>/<namespace>/<bundle_image_name>:<tag> \1
       --tag <registry>/<namespace>/<index_image_name>:<tag> \2
       [--binary-image <registry_base_image>] 3

   1

   Comma-separated list of bundle images to add to the index.

   2

   The image tag that you want the index image to have.

   3

   Optional: An alternative registry base image to use for serving the catalog.

2. Push the index image to a registry.

   1. If required, authenticate with your target registry:

      $ podman login <registry>

   2. Push the index image:

      $ podman push <registry>/<namespace>/<index_image_name>:<tag>

Procedure

1. Create a CatalogSource object that references your index image.

   1. Modify the following to your specifications and save it as a catalogSource.yaml file:

      apiVersion: operators.coreos.com/v1alpha1
      kind: CatalogSource
      metadata:
        name: my-operator-catalog
        namespace: openshift-marketplace 1
      spec:
        sourceType: grpc
        image: <registry>:<port>/<namespace>/redhat-operator-index:v4.8 2
        displayName: My Operator Catalog
        publisher: <publisher_name> 3
        updateStrategy:
          registryPoll: 4
            interval: 30m

      1

      If you want the catalog source to be available globally to users in all namespaces, specify the openshift-marketplace namespace. Otherwise, you can specify a different namespace for the catalog to be scoped and available only for that namespace.

      2

      Specify your index image.

      3

      Specify your name or an organization name publishing the catalog.

      4

      Catalog sources can automatically check for new versions to keep up to date.

   2. Use the file to create the CatalogSource object:

      $ oc apply -f catalogSource.yaml

2. Verify the following resources are created successfully.

   1. Check the pods:

      $ oc get pods -n openshift-marketplace

      Example output

      NAME                                    READY   STATUS    RESTARTS  AGE
      my-operator-catalog-6njx6               1/1     Running   0         28s
      marketplace-operator-d9f549946-96sgr    1/1     Running   0         26h

   2. Check the catalog source:

      $ oc get catalogsource -n openshift-marketplace

      Example output

      NAME                  DISPLAY               TYPE PUBLISHER  AGE
      my-operator-catalog   My Operator Catalog   grpc            5s

   3. Check the package manifest:

      $ oc get packagemanifest -n openshift-marketplace

      Example output

      NAME                          CATALOG               AGE
      jaeger-product                My Operator Catalog   93s

Procedure

1. Update the existing index by adding bundle images:

   $ opm index add \
       --bundles <registry>/<namespace>/<new_bundle_image>@sha256:<digest> \1
       --from-index <registry>/<namespace>/<existing_index_image>:<existing_tag> \2
       --tag <registry>/<namespace>/<existing_index_image>:<updated_tag> \3
       --pull-tool podman 4

   1

   The --bundles flag specifies a comma-separated list of additional bundle images to add to the index.

   2

   The --from-index flag specifies the previously pushed index.

   3

   The --tag flag specifies the image tag to apply to the updated index image.

   4

   The --pull-tool flag specifies the tool used to pull container images.

   where:

   <registry>

   Specifies the hostname of the registry, such as quay.io or mirror.example.com.

   <namespace>

   Specifies the namespace of the registry, such as ocs-dev or abc.

   <new_bundle_image>

   Specifies the new bundle image to add to the registry, such as ocs-operator.

   <digest>

   Specifies the SHA image ID, or digest, of the bundle image, such as c7f11097a628f092d8bad148406aa0e0951094a03445fd4bc0775431ef683a41.

   <existing_index_image>

   Specifies the previously pushed image, such as abc-redhat-operator-index.

   <existing_tag>

   Specifies a previously pushed image tag, such as 4.8.

   <updated_tag>

   Specifies the image tag to apply to the updated index image, such as 4.8.1.

   Example command

   $ opm index add \
       --bundles quay.io/ocs-dev/ocs-operator@sha256:c7f11097a628f092d8bad148406aa0e0951094a03445fd4bc0775431ef683a41 \
       --from-index mirror.example.com/abc/abc-redhat-operator-index:4.8 \
       --tag mirror.example.com/abc/abc-redhat-operator-index:4.8.1 \
       --pull-tool podman

2. Push the updated index image:

   $ podman push <registry>/<namespace>/<existing_index_image>:<updated_tag>

3. After Operator Lifecycle Manager (OLM) automatically polls the index image referenced in the catalog source at its regular interval, verify that the new packages are successfully added:

   $ oc get packagemanifests -n openshift-marketplace

Procedure

1. Authenticate with your target registry:

   $ podman login <target_registry>

2. Determine the list of packages you want to include in your pruned index.

   1. Run the source index image that you want to prune in a container. For example:

      $ podman run -p50051:50051 \
          -it registry.redhat.io/redhat/redhat-operator-index:v4.8

      Example output

      Trying to pull registry.redhat.io/redhat/redhat-operator-index:v4.8...
      Getting image source signatures
      Copying blob ae8a0c23f5b1 done
      ...
      INFO[0000] serving registry                              database=/database/index.db port=50051

   2. In a separate terminal session, use the grpcurl command to get a list of the packages provided by the index:

      $ grpcurl -plaintext localhost:50051 api.Registry/ListPackages > packages.out

   3. Inspect the packages.out file and identify which package names from this list you want to keep in your pruned index. For example:

      Example snippets of packages list

      ...
      {
        "name": "advanced-cluster-management"
      }
      ...
      {
        "name": "jaeger-product"
      }
      ...
      {
      {
        "name": "quay-operator"
      }
      ...

   4. In the terminal session where you executed the podman run command, press Ctrl and C to stop the container process.

3. Run the following command to prune the source index of all but the specified packages:

   $ opm index prune \
       -f registry.redhat.io/redhat/redhat-operator-index:v4.8 \1
       -p advanced-cluster-management,jaeger-product,quay-operator \2
       [-i registry.redhat.io/openshift4/ose-operator-registry:v4.8] \3
       -t <target_registry>:<port>/<namespace>/redhat-operator-index:v4.8 4

   1

   Index to prune.

   2

   Comma-separated list of packages to keep.

   3

   Required only for IBM Power Systems and IBM Z images: Operator Registry base image with the tag that matches the target OpenShift Container Platform cluster major and minor version.

   4

   Custom tag for new index image being built.

4. Run the following command to push the new index image to your target registry:

   $ podman push <target_registry>:<port>/<namespace>/redhat-operator-index:v4.8

   where <namespace> is any existing namespace on the registry.

Procedure

1. Create a secret for each required private registry.

   1. Log in to the private registry to create or update your registry credentials file:

      $ podman login <registry>:<port>

      Note

      The file path of your registry credentials can be different depending on the container tool used to log in to the registry. For the podman CLI, the default location is ${XDG_RUNTIME_DIR}/containers/auth.json. For the docker CLI, the default location is /root/.docker/config.json.

   2. It is recommended to include credentials for only one registry per secret, and manage credentials for multiple registries in separate secrets. Multiple secrets can be included in a CatalogSource object in later steps, and OpenShift Container Platform will merge the secrets into a single virtual credentials file for use during an image pull.

      A registry credentials file can, by default, store details for more than one registry. Verify the current contents of your file. For example:

      File storing credentials for two registries

      {
              "auths": {
                      "registry.redhat.io": {
                              "auth": "FrNHNydQXdzclNqdg=="
                      },
                      "quay.io": {
                              "auth": "Xd2lhdsbnRib21iMQ=="
                      }
              }
      }

      Because this file is used to create secrets in later steps, ensure that you are storing details for only one registry per file. This can be accomplished by using either of the following methods:

      • Use the podman logout <registry> command to remove credentials for additional registries until only the one registry you want remains.

      • Edit your registry credentials file and separate the registry details to be stored in multiple files. For example:

        File storing credentials for one registry

        {
                "auths": {
                        "registry.redhat.io": {
                                "auth": "FrNHNydQXdzclNqdg=="
                        }
                }
        }

        File storing credentials for another registry

        {
                "auths": {
                        "quay.io": {
                                "auth": "Xd2lhdsbnRib21iMQ=="
                        }
                }
        }

   3. Create a secret in the openshift-marketplace namespace that contains the authentication credentials for a private registry:

      $ oc create secret generic <secret_name> \
          -n openshift-marketplace \
          --from-file=.dockerconfigjson=<path/to/registry/credentials> \
          --type=kubernetes.io/dockerconfigjson

      Repeat this step to create additional secrets for any other required private registries, updating the --from-file flag to specify another registry credentials file path.

2. Create or update an existing CatalogSource object to reference one or more secrets:

   apiVersion: operators.coreos.com/v1alpha1
   kind: CatalogSource
   metadata:
     name: my-operator-catalog
     namespace: openshift-marketplace
   spec:
     sourceType: grpc
     secrets: 1
     - "<secret_name_1>"
     - "<secret_name_2>"
     image: <registry>:<port>/<namespace>/<image>:<tag>
     displayName: My Operator Catalog
     publisher: <publisher_name>
     updateStrategy:
       registryPoll:
         interval: 30m

   1

   Add a spec.secrets section and specify any required secrets.

3. If any Operator or Operand images that are referenced by a subscribed Operator require access to a private registry, you can either provide access to all namespaces in the cluster, or individual target tenant namespaces.

   • To provide access to all namespaces in the cluster, add authentication details to the global cluster pull secret in the openshift-config namespace.

     Warning

     Cluster resources must adjust to the new global pull secret, which can temporarily limit the usability of the cluster.

     1. Extract the .dockerconfigjson file from the global pull secret:

        $ oc extract secret/pull-secret -n openshift-config --confirm

     2. Update the .dockerconfigjson file with your authentication credentials for the required private registry or registries and save it as a new file:

        $ cat .dockerconfigjson | \
            jq --compact-output '.auths["<registry>:<port>/<namespace>/"] |= . + {"auth":"<token>"}' \1
            > new_dockerconfigjson

        1

        Replace <registry>:<port>/<namespace> with the private registry details and <token> with your authentication credentials.

     3. Update the global pull secret with the new file:

        $ oc set data secret/pull-secret -n openshift-config \
            --from-file=.dockerconfigjson=new_dockerconfigjson

   • To update an individual namespace, add a pull secret to the service account for the Operator that requires access in the target tenant namespace.

     1. Recreate the secret that you created for the openshift-marketplace in the tenant namespace:

        $ oc create secret generic <secret_name> \
            -n <tenant_namespace> \
            --from-file=.dockerconfigjson=<path/to/registry/credentials> \
            --type=kubernetes.io/dockerconfigjson

     2. Verify the name of the service account for the Operator by searching the tenant namespace:

        $ oc get sa -n <tenant_namespace> 1

        1

        If the Operator was installed in an individual namespace, search that namespace. If the Operator was installed for all namespaces, search the openshift-operators namespace.

        Example output

        NAME            SECRETS   AGE
        builder         2         6m1s
        default         2         6m1s
        deployer        2         6m1s
        etcd-operator   2         5m18s 1

        1

        Service account for an installed etcd Operator.

     3. Link the secret to the service account for the Operator:

        $ oc secrets link <operator_sa> \
            -n <tenant_namespace> \
             <secret_name> \
            --for=pull

Procedure

1. In the Administrator perspective of the web console, navigate to Administration → Cluster Settings.
2. Click the Global Configuration tab, and then click OperatorHub.
3. Click the Sources tab.
4. Select the Options menu for the catalog that you want to remove, and then click Delete CatalogSource.

Procedure

1. Authenticate with registry.redhat.io:

   $ podman login registry.redhat.io

2. Authenticate with your target registry:

   $ podman login <target_registry>

3. Determine the list of packages you want to include in your pruned index.

   1. Run the source index image that you want to prune in a container. For example:

      $ podman run -p50051:50051 \
          -it registry.redhat.io/redhat/redhat-operator-index:v4.8

      Example output

      Trying to pull registry.redhat.io/redhat/redhat-operator-index:v4.8...
      Getting image source signatures
      Copying blob ae8a0c23f5b1 done
      ...
      INFO[0000] serving registry                              database=/database/index.db port=50051

   2. In a separate terminal session, use the grpcurl command to get a list of the packages provided by the index:

      $ grpcurl -plaintext localhost:50051 api.Registry/ListPackages > packages.out

   3. Inspect the packages.out file and identify which package names from this list you want to keep in your pruned index. For example:

      Example snippets of packages list

      ...
      {
        "name": "advanced-cluster-management"
      }
      ...
      {
        "name": "jaeger-product"
      }
      ...
      {
      {
        "name": "quay-operator"
      }
      ...

   4. In the terminal session where you executed the podman run command, press Ctrl and C to stop the container process.

4. Run the following command to prune the source index of all but the specified packages:

   $ opm index prune \
       -f registry.redhat.io/redhat/redhat-operator-index:v4.8 \1
       -p advanced-cluster-management,jaeger-product,quay-operator \2
       [-i registry.redhat.io/openshift4/ose-operator-registry:v4.8] \3
       -t <target_registry>:<port>/<namespace>/redhat-operator-index:v4.8 4

   1

   Index to prune.

   2

   Comma-separated list of packages to keep.

   3

   Required only for IBM Power Systems and IBM Z images: Operator Registry base image with the tag that matches the target OpenShift Container Platform cluster major and minor version.

   4

   Custom tag for new index image being built.

5. Run the following command to push the new index image to your target registry:

   $ podman push <target_registry>:<port>/<namespace>/redhat-operator-index:v4.8

   where <namespace> is any existing namespace on the registry. For example, you might create an olm-mirror namespace to push all mirrored content to.

Procedure

1. If you want to mirror a Red Hat-provided catalog, run the following command on your workstation with unrestricted network access to authenticate with registry.redhat.io:

   $ podman login registry.redhat.io

2. The oc adm catalog mirror command extracts the contents of an index image to generate the manifests required for mirroring. The default behavior of the command generates manifests, then automatically mirrors all of the image content from the index image, as well as the index image itself, to your mirror registry. Alternatively, if your mirror registry is on a completely disconnected, or airgapped, host, you can first mirror the content to removable media, move the media to the disconnected environment, then mirror the content from the media to the registry.

   • Option A: If your mirror registry is on the same network as your workstation with unrestricted network access, take the following actions on your workstation:

     1. If your mirror registry requires authentication, run the following command to log in to the registry:

        $ podman login <mirror_registry>

     2. Run the following command to mirror the content:

        $ oc adm catalog mirror \
            <index_image> \1
            <mirror_registry>:<port>/<namespace> \2
            [-a ${REG_CREDS}] \3
            [--insecure] \4
            [--index-filter-by-os='<platform>/<arch>'] \5
            [--manifests-only] 6

        1

        Specify the index image for the catalog you want to mirror. For example, this might be a pruned index image that you created previously, or one of the source index images for the default catalogs, such as registry.redhat.io/redhat/redhat-operator-index:v4.8.

        2

        Specify the fully qualified domain name (FQDN) for the target registry and namespace to mirror the Operator content to, where <namespace> is any existing namespace on the registry. For example, you might create an olm-mirror namespace to push all mirrored content to.

        3

        Optional: If required, specify the location of your registry credentials file. {REG_CREDS} is required for registry.redhat.io.

        4

        Optional: If you do not want to configure trust for the target registry, add the --insecure flag.

        5

        Optional: Specify which platform and architecture of the index image to select when multiple variants are available. Images are passed as '<platform>/<arch>[/<variant>]'. This does not apply to images referenced by the index. Valid values are linux/amd64, linux/ppc64le, linux/s390x, and .*

        6

        Optional: Generate only the manifests required for mirroring, and do not actually mirror the image content to a registry. This option can be useful for reviewing what will be mirrored, and it allows you to make any changes to the mapping list if you require only a subset of packages. You can then use the mapping.txt file with the oc image mirror command to mirror the modified list of images in a later step. This flag is intended for only advanced selective mirroring of content from the catalog; the opm index prune command, if you used it previously to prune the index image, is suitable for most catalog management use cases.

        Example output

        src image has index label for database path: /database/index.db
        using database path mapping: /database/index.db:/tmp/153048078
        wrote database to /tmp/153048078 1
        ...
        wrote mirroring manifests to manifests-redhat-operator-index-1614211642 2

        1

        Directory for the temporary index.db database generated by the command.

        2

        Be sure to record the manifests directory name that is generated. This directory name is used in a later step.

        Note

        Red Hat Quay does not support nested repositories. As a result, running the oc adm catalog mirror command will fail with a 401 unauthorized error. As a workaround, you can use the --max-components=2 option when running the oc adm catalog mirror command to disable the creation of nested repositories. For more information on this workaround, see the Unauthorized error thrown while using catalog mirror command with Quay registry Knowledgebase Solution article.

   • Option B: If your mirror registry is on a disconnected host, take the following actions.

     1. Run the following command on your workstation with unrestricted network access to mirror the content to local files:

        $ oc adm catalog mirror \
            <index_image> \1
            file:///local/index \2
            [-a ${REG_CREDS}] \
            [--insecure] \
            [--index-filter-by-os='<platform>/<arch>']

        1

        Specify the index image for the catalog you want to mirror. For example, this might be a pruned index image that you created previously, or one of the source index images for the default catalogs, such as registry.redhat.io/redhat/redhat-operator-index:v4.8.

        2

        Mirrors content to local files in your current directory.

        Example output

        ...
        info: Mirroring completed in 5.93s (5.915MB/s)
        wrote mirroring manifests to manifests-my-index-1614985528 1
        
        To upload local images to a registry, run:
        
        	oc adm catalog mirror file://local/index/myrepo/my-index:v1 REGISTRY/REPOSITORY 2

        1

        Be sure to record the manifests directory name that is generated. This directory name is used in a later step.

        2

        Record the expanded file:// path that based on your provided index image. This path is used in a later step.

     2. Copy the v2/ directory that is generated in your current directory to removable media.
     3. Physically remove the media and attach it to a host in the disconnected environment that has access to the mirror registry.

     4. If your mirror registry requires authentication, run the following command on your host in the disconnected environment to log in to the registry:

        $ podman login <mirror_registry>

     5. Run the following command from the parent directory containing the v2/ directory to upload the images from local files to the mirror registry:

        $ oc adm catalog mirror \
            file://local/index/<repo>/<index_image>:<tag> \1
            <mirror_registry>:<port>/<namespace> \2
            [-a ${REG_CREDS}] \
            [--insecure] \
            [--index-filter-by-os='<platform>/<arch>']

        1

        Specify the file:// path from the previous command output.

        2

        Specify the fully qualified domain name (FQDN) for the target registry and namespace to mirror the Operator content to, where <namespace> is any existing namespace on the registry. For example, you might create an olm-mirror namespace to push all mirrored content to.

        Note

        Red Hat Quay does not support nested repositories. As a result, running the oc adm catalog mirror command will fail with a 401 unauthorized error. As a workaround, you can use the --max-components=2 option when running the oc adm catalog mirror command to disable the creation of nested repositories. For more information on this workaround, see the Unauthorized error thrown while using catalog mirror command with Quay registry Knowledgebase Solution article.

     6. Run the oc adm catalog mirror command again. Use the newly mirrored index image as the source and the same mirror registry namespace used in the previous step as the target:

        $ oc adm catalog mirror \
            <mirror_registry>:<port>/<index_image> \
            <mirror_registry>:<port>/<namespace> \
            --manifests-only \1
            [-a ${REG_CREDS}] \
            [--insecure]

        1

        The --manifests-only flag is required for this step so that the command does not copy all of the mirrored content again.

        Important

        This step is required because the image mappings in the imageContentSourcePolicy.yaml file generated during the previous step must be updated from local paths to valid mirror locations. Failure to do so will cause errors when you create the ImageContentSourcePolicy object in a later step.

3. After mirroring the content to your registry, inspect the manifests directory that is generated in your current directory.

   Note

   The manifests directory name is used in a later step.

   If you mirrored content to a registry on the same network in the previous step, the directory name takes the following form:

   manifests-<index_image_name>-<random_number>

   If you mirrored content to a registry on a disconnected host in the previous step, the directory name takes the following form:

   manifests-index/<namespace>/<index_image_name>-<random_number>

   The manifests directory contains the following files, some of which might require further modification:

   • The catalogSource.yaml file is a basic definition for a CatalogSource object that is pre-populated with your index image tag and other relevant metadata. This file can be used as is or modified to add the catalog source to your cluster.

     Important

     If you mirrored the content to local files, you must modify your catalogSource.yaml file to remove any backslash (/) characters from the metadata.name field. Otherwise, when you attempt to create the object, it fails with an "invalid resource name" error.

   • The imageContentSourcePolicy.yaml file defines an ImageContentSourcePolicy object that can configure nodes to translate between the image references stored in Operator manifests and the mirrored registry.

     Note

     If your cluster uses an ImageContentSourcePolicy object to configure repository mirroring, you can use only global pull secrets for mirrored registries. You cannot add a pull secret to a project.

   • The mapping.txt file contains all of the source images and where to map them in the target registry. This file is compatible with the oc image mirror command and can be used to further customize the mirroring configuration.

     Important

     If you used the --manifests-only flag during the mirroring process and want to further trim the subset of packages to be mirrored, see the steps in the Mirroring a package manifest format catalog image procedure of the OpenShift Container Platform 4.7 documentation about modifying your mapping.txt file and using the file with the oc image mirror command. After following those further actions, you can continue this procedure.

4. On a host with access to the disconnected cluster, create the ImageContentSourcePolicy (ICSP) object by running the following command to specify the imageContentSourcePolicy.yaml file in your manifests directory:

   $ oc create -f <path/to/manifests/dir>/imageContentSourcePolicy.yaml

   where <path/to/manifests/dir> is the path to the manifests directory for your mirrored content.

   You can now create a CatalogSource object to reference your mirrored index image and Operator content.

Procedure

1. Create a CatalogSource object that references your index image. If you used the oc adm catalog mirror command to mirror your catalog to a target registry, you can use the generated catalogSource.yaml file as a starting point.

   1. Modify the following to your specifications and save it as a catalogSource.yaml file:

      apiVersion: operators.coreos.com/v1alpha1
      kind: CatalogSource
      metadata:
        name: my-operator-catalog 1
        namespace: openshift-marketplace 2
      spec:
        sourceType: grpc
        image: <registry>:<port>/<namespace>/redhat-operator-index:v4.8 3
        displayName: My Operator Catalog
        publisher: <publisher_name> 4
        updateStrategy:
          registryPoll: 5
            interval: 30m

      1

      If you mirrored content to local files before uploading to a registry, remove any backslash (/) characters from the metadata.name field to avoid an "invalid resource name" error when you create the object.

      2

      If you want the catalog source to be available globally to users in all namespaces, specify the openshift-marketplace namespace. Otherwise, you can specify a different namespace for the catalog to be scoped and available only for that namespace.

      3

      Specify your index image.

      4

      Specify your name or an organization name publishing the catalog.

      5

      Catalog sources can automatically check for new versions to keep up to date.

   2. Use the file to create the CatalogSource object:

      $ oc apply -f catalogSource.yaml

2. Verify the following resources are created successfully.

   1. Check the pods:

      $ oc get pods -n openshift-marketplace

      Example output

      NAME                                    READY   STATUS    RESTARTS  AGE
      my-operator-catalog-6njx6               1/1     Running   0         28s
      marketplace-operator-d9f549946-96sgr    1/1     Running   0         26h

   2. Check the catalog source:

      $ oc get catalogsource -n openshift-marketplace

      Example output

      NAME                  DISPLAY               TYPE PUBLISHER  AGE
      my-operator-catalog   My Operator Catalog   grpc            5s

   3. Check the package manifest:

      $ oc get packagemanifest -n openshift-marketplace

      Example output

      NAME                          CATALOG               AGE
      jaeger-product                My Operator Catalog   93s

Procedure

1. Update the existing index by adding bundle images:

   $ opm index add \
       --bundles <registry>/<namespace>/<new_bundle_image>@sha256:<digest> \1
       --from-index <registry>/<namespace>/<existing_index_image>:<existing_tag> \2
       --tag <registry>/<namespace>/<existing_index_image>:<updated_tag> \3
       --pull-tool podman 4

   1

   The --bundles flag specifies a comma-separated list of additional bundle images to add to the index.

   2

   The --from-index flag specifies the previously pushed index.

   3

   The --tag flag specifies the image tag to apply to the updated index image.

   4

   The --pull-tool flag specifies the tool used to pull container images.

   where:

   <registry>

   Specifies the hostname of the registry, such as quay.io or mirror.example.com.

   <namespace>

   Specifies the namespace of the registry, such as ocs-dev or abc.

   <new_bundle_image>

   Specifies the new bundle image to add to the registry, such as ocs-operator.

   <digest>

   Specifies the SHA image ID, or digest, of the bundle image, such as c7f11097a628f092d8bad148406aa0e0951094a03445fd4bc0775431ef683a41.

   <existing_index_image>

   Specifies the previously pushed image, such as abc-redhat-operator-index.

   <existing_tag>

   Specifies a previously pushed image tag, such as 4.8.

   <updated_tag>

   Specifies the image tag to apply to the updated index image, such as 4.8.1.

   Example command

   $ opm index add \
       --bundles quay.io/ocs-dev/ocs-operator@sha256:c7f11097a628f092d8bad148406aa0e0951094a03445fd4bc0775431ef683a41 \
       --from-index mirror.example.com/abc/abc-redhat-operator-index:4.8 \
       --tag mirror.example.com/abc/abc-redhat-operator-index:4.8.1 \
       --pull-tool podman

2. Push the updated index image:

   $ podman push <registry>/<namespace>/<existing_index_image>:<updated_tag>

3. Follow the steps in the Mirroring an Operator catalog procedure again to mirror the updated content. However, when you get to the step about creating the ImageContentSourcePolicy (ICSP) object, use the oc replace command instead of the oc create command. For example:

   $ oc replace -f ./manifests-redhat-operator-index-<random_number>/imageContentSourcePolicy.yaml

   This change is required because the object already exists and must be updated.

   Note

   Normally, the oc apply command can be used to update existing objects that were previously created using oc apply. However, due to a known issue regarding the size of the metadata.annotations field in ICSP objects, the oc replace command must be used for this step currently.

4. After Operator Lifecycle Manager (OLM) automatically polls the index image referenced in the catalog source at its regular interval, verify that the new packages are successfully added:

   $ oc get packagemanifests -n openshift-marketplace

1. Create an Operator project by using the Operator SDK command-line interface (CLI).
2. Define new resource APIs by adding custom resource definitions (CRDs).
3. Specify resources to watch by using the Operator SDK API.
4. Define the Operator reconciling logic in a designated handler and use the Operator SDK API to interact with resources.
5. Use the Operator SDK CLI to build and generate the Operator deployment manifests.

Procedure

1. Navigate to the OpenShift mirror site.
2. From the 4.8.4 directory, download the latest version of the tarball for Linux.

3. Unpack the archive:

   $ tar xvf operator-sdk-v1.8.0-ocp-linux-x86_64.tar.gz

4. Make the file executable:

   $ chmod +x operator-sdk

5. Move the extracted operator-sdk binary to a directory that is on your PATH.

   Tip

   To check your PATH:

   $ echo $PATH

   $ sudo mv ./operator-sdk /usr/local/bin/operator-sdk

Procedure

1. Make the following changes to your PROJECT file:

   1. Update the PROJECT file plugins object to use manifests and scorecard objects.

      The manifests and scorecard plug-ins that create Operator Lifecycle Manager (OLM) and scorecard manifests now have plug-in objects for running create subcommands to create related files.

      • For Go-based Operator projects, an existing Go-based plug-in configuration object is already present. While the old configuration is still supported, these new objects will be useful in the future as configuration options are added to their respective plug-ins:

        Old configuration

        version: 3-alpha
        ...
        plugins:
          go.sdk.operatorframework.io/v2-alpha: {}

        New configuration

        version: 3-alpha
        ...
        plugins:
          manifests.sdk.operatorframework.io/v2: {}
          scorecard.sdk.operatorframework.io/v2: {}

      • Optional: For Ansible- and Helm-based Operator projects, the plug-in configuration object previously did not exist. While you are not required to add the plug-in configuration objects, these new objects will be useful in the future as configuration options are added to their respective plug-ins:

        version: 3-alpha
        ...
        plugins:
          manifests.sdk.operatorframework.io/v2: {}
          scorecard.sdk.operatorframework.io/v2: {}

   2. The PROJECT config version 3-alpha must be upgraded to 3. The version key in your PROJECT file represents the PROJECT config version:

      Old PROJECT file

      version: 3-alpha
      resources:
      - crdVersion: v1
      ...

      Version 3-alpha has been stabilized as version 3 and contains a set of config fields sufficient to fully describe a project. While this change is not technically breaking because the spec at that version was alpha, it was used by default in operator-sdk commands, so it should be marked as breaking and have a convenient upgrade path.

      1. Run the alpha config-3alpha-to-3 command to convert most of your PROJECT file from version 3-alpha to 3:

         $ operator-sdk alpha config-3alpha-to-3

         Example output

         Your PROJECT config file has been converted from version 3-alpha to 3. Please make sure all config data is correct.

         The command will also output comments with directions where automatic conversion is not possible.

      2. Verify the change:

         New PROJECT file

         version: "3"
         resources:
         - api:
           crdVersion: v1
         ...

2. Make the following changes to your config/manager/manager.yaml file:

   1. For Ansible- and Helm-based Operator projects, add liveness and readiness probes.

      New projects built with the Operator SDK have the probes configured by default. The endpoints /healthz and /readyz are available now in the provided image base. You can update your existing projects to use the probes by updating the Dockerfile to use the latest base image, then add the following to the manager container in the config/manager/manager.yaml file:

      Example 5.1. Configuration for Ansible-based Operator projects

        livenessProbe:
          httpGet:
            path: /healthz
            port: 6789
          initialDelaySeconds: 15
          periodSeconds: 20
        readinessProbe:
          httpGet:
            path: /readyz
            port: 6789
          initialDelaySeconds: 5
          periodSeconds: 10

      Example 5.2. Configuration for Helm-based Operator projects

        livenessProbe:
          httpGet:
            path: /healthz
            port: 8081
          initialDelaySeconds: 15
          periodSeconds: 20
        readinessProbe:
          httpGet:
            path: /readyz
            port: 8081
          initialDelaySeconds: 5
          periodSeconds: 10

   2. For Ansible- and Helm-based Operator projects, add security contexts to your manager’s deployment.

      In the config/manager/manager.yaml file, add the following security contexts:

      Example 5.3. config/manager/manager.yaml file

      spec:
        ...
        template:
          ...
          spec:
            securityContext:
              runAsNonRoot: true
            containers:
            - name: manager
              securityContext:
                allowPrivilegeEscalation: false

3. Make the following changes to your Makefile:

   1. For Ansible- and Helm-based Operator projects, update the helm-operator and ansible-operator URLs in the Makefile:

      • For Ansible-based Operator projects, change:

        https://github.com/operator-framework/operator-sdk/releases/download/v1.3.0/ansible-operator-v1.3.0-$(ARCHOPER)-$(OSOPER)

        to:

        https://github.com/operator-framework/operator-sdk/releases/download/v1.8.0/ansible-operator_$(OS)_$(ARCH)

      • For Helm-based Operator projects, change:

        https://github.com/operator-framework/operator-sdk/releases/download/v1.3.0/helm-operator-v1.3.0-$(ARCHOPER)-$(OSOPER)

        to:

        https://github.com/operator-framework/operator-sdk/releases/download/v1.8.0/helm-operator_$(OS)_$(ARCH)

   2. For Ansible- and Helm-based Operator projects, update the helm-operator, ansible-operator, and kustomize rules in the Makefile. These rules download a local binary but do not use it if a global binary is present:

      Example 5.4. Makefile diff for Ansible-based Operator projects

       PATH  := $(PATH):$(PWD)/bin
       SHELL := env PATH=$(PATH) /bin/sh
      -OS := $(shell uname -s | tr '[:upper:]' '[:lower:]')
      -ARCH := $(shell uname -m | sed 's/x86_64/amd64/')
      +OS    = $(shell uname -s | tr '[:upper:]' '[:lower:]')
      +ARCH  = $(shell uname -m | sed 's/x86_64/amd64/')
      +OSOPER   = $(shell uname -s | tr '[:upper:]' '[:lower:]' | sed 's/darwin/apple-darwin/' | sed 's/linux/linux-gnu/')
      +ARCHOPER = $(shell uname -m )
      
      -# Download kustomize locally if necessary, preferring the $(pwd)/bin path over global if both exist.
      -.PHONY: kustomize
      -KUSTOMIZE = $(shell pwd)/bin/kustomize
       kustomize:
      -ifeq (,$(wildcard $(KUSTOMIZE)))
      -ifeq (,$(shell which kustomize 2>/dev/null))
      +ifeq (, $(shell which kustomize 2>/dev/null))
       	@{ \
       	set -e ;\
      -	mkdir -p $(dir $(KUSTOMIZE)) ;\
      -	curl -sSLo - https://github.com/kubernetes-sigs/kustomize/releases/download/kustomize/v3.5.4/kustomize_v3.5.4_$(OS)_$(ARCH).tar.gz | \
      -	tar xzf - -C bin/ ;\
      +	mkdir -p bin ;\
      +	curl -sSLo - https://github.com/kubernetes-sigs/kustomize/releases/download/kustomize/v3.5.4/kustomize_v3.5.4_$(OS)_$(ARCH).tar.gz | tar xzf - -C bin/ ;\
       	}
      +KUSTOMIZE=$(realpath ./bin/kustomize)
       else
      -KUSTOMIZE = $(shell which kustomize)
      -endif
      +KUSTOMIZE=$(shell which kustomize)
       endif
      
      -# Download ansible-operator locally if necessary, preferring the $(pwd)/bin path over global if both exist.
      -.PHONY: ansible-operator
      -ANSIBLE_OPERATOR = $(shell pwd)/bin/ansible-operator
       ansible-operator:
      -ifeq (,$(wildcard $(ANSIBLE_OPERATOR)))
      -ifeq (,$(shell which ansible-operator 2>/dev/null))
      +ifeq (, $(shell which ansible-operator 2>/dev/null))
       	@{ \
       	set -e ;\
      -	mkdir -p $(dir $(ANSIBLE_OPERATOR)) ;\
      -	curl -sSLo $(ANSIBLE_OPERATOR) https://github.com/operator-framework/operator-sdk/releases/download/v1.3.0/ansible-operator_$(OS)_$(ARCH) ;\
      -	chmod +x $(ANSIBLE_OPERATOR) ;\
      +	mkdir -p bin ;\
      +	curl -LO https://github.com/operator-framework/operator-sdk/releases/download/v1.8.0/ansible-operator-v1.8.0-$(ARCHOPER)-$(OSOPER) ;\
      +	mv ansible-operator-v1.8.0-$(ARCHOPER)-$(OSOPER) ./bin/ansible-operator ;\
      +	chmod +x ./bin/ansible-operator ;\
       	}
      +ANSIBLE_OPERATOR=$(realpath ./bin/ansible-operator)
       else
      -ANSIBLE_OPERATOR = $(shell which ansible-operator)
      -endif
      +ANSIBLE_OPERATOR=$(shell which ansible-operator)
       endif

      Example 5.5. Makefile diff for Helm-based Operator projects

       PATH  := $(PATH):$(PWD)/bin
       SHELL := env PATH=$(PATH) /bin/sh
      -OS := $(shell uname -s | tr '[:upper:]' '[:lower:]')
      -ARCH := $(shell uname -m | sed 's/x86_64/amd64/')
      +OS    = $(shell uname -s | tr '[:upper:]' '[:lower:]')
      +ARCH  = $(shell uname -m | sed 's/x86_64/amd64/')
      +OSOPER   = $(shell uname -s | tr '[:upper:]' '[:lower:]' | sed 's/darwin/apple-darwin/' | sed 's/linux/linux-gnu/')
      +ARCHOPER = $(shell uname -m )
      
      -# Download kustomize locally if necessary, preferring the $(pwd)/bin path over global if both exist.
      -.PHONY: kustomize
      -KUSTOMIZE = $(shell pwd)/bin/kustomize
       kustomize:
      -ifeq (,$(wildcard $(KUSTOMIZE)))
      -ifeq (,$(shell which kustomize 2>/dev/null))
      +ifeq (, $(shell which kustomize 2>/dev/null))
       	@{ \
       	set -e ;\
      -	mkdir -p $(dir $(KUSTOMIZE)) ;\
      -	curl -sSLo - https://github.com/kubernetes-sigs/kustomize/releases/download/kustomize/v3.5.4/kustomize_v3.5.4_$(OS)_$(ARCH).tar.gz | \
      -	tar xzf - -C bin/ ;\
      +	mkdir -p bin ;\
      +	curl -sSLo - https://github.com/kubernetes-sigs/kustomize/releases/download/kustomize/v3.5.4/kustomize_v3.5.4_$(OS)_$(ARCH).tar.gz | tar xzf - -C bin/ ;\
       	}
      +KUSTOMIZE=$(realpath ./bin/kustomize)
       else
      -KUSTOMIZE = $(shell which kustomize)
      -endif
      +KUSTOMIZE=$(shell which kustomize)
       endif
      
      -# Download helm-operator locally if necessary, preferring the $(pwd)/bin path over global if both exist.
      -.PHONY: helm-operator
      -HELM_OPERATOR = $(shell pwd)/bin/helm-operator
       helm-operator:
      -ifeq (,$(wildcard $(HELM_OPERATOR)))
      -ifeq (,$(shell which helm-operator 2>/dev/null))
      +ifeq (, $(shell which helm-operator 2>/dev/null))
       	@{ \
       	set -e ;\
      -	mkdir -p $(dir $(HELM_OPERATOR)) ;\
      -	curl -sSLo $(HELM_OPERATOR) https://github.com/operator-framework/operator-sdk/releases/download/v1.3.0/helm-operator_$(OS)_$(ARCH) ;\
      -	chmod +x $(HELM_OPERATOR) ;\
      +	mkdir -p bin ;\
      +	curl -LO https://github.com/operator-framework/operator-sdk/releases/download/v1.8.0/helm-operator-v1.8.0-$(ARCHOPER)-$(OSOPER) ;\
      +	mv helm-operator-v1.8.0-$(ARCHOPER)-$(OSOPER) ./bin/helm-operator ;\
      +	chmod +x ./bin/helm-operator ;\
       	}
      +HELM_OPERATOR=$(realpath ./bin/helm-operator)
       else
      -HELM_OPERATOR = $(shell which helm-operator)
      -endif
      +HELM_OPERATOR=$(shell which helm-operator)
       endif

   3. Move the positional directory argument . in the make target for docker-build.

      The directory argument . in the docker-build target was moved to the last positional argument to align with podman CLI expectations, which makes substitution cleaner:

      Old target

      docker-build:
        docker build . -t ${IMG}

      New target

      docker-build:
        docker build -t ${IMG} .

      You can make this change by running the following command:

      $ sed -i 's/docker build . -t ${IMG}/docker build -t ${IMG} ./' $(git grep -l 'docker.*build \. ')

   4. For Ansible- and Helm-based Operator projects, add a help target to the Makefile.

      Ansible- and Helm-based projects now provide help target in the Makefile by default, similar to a --help flag. You can manually add this target to your Makefile using the following lines:

      Example 5.6. help target

      ##@ General
      
      # The help target prints out all targets with their descriptions organized
      # beneath their categories. The categories are represented by '##@' and the
      # target descriptions by '##'. The awk commands is responsible for reading the
      # entire set of makefiles included in this invocation, looking for lines of the
      # file as xyz: ## something, and then pretty-format the target and help. Then,
      # if there's a line with ##@ something, that gets pretty-printed as a category.
      # More info on the usage of ANSI control characters for terminal formatting:
      # https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_parameters
      # More info on the awk command:
      # http://linuxcommand.org/lc3_adv_awk.php
      
      help: ## Display this help.
      	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z_0-9-]+:.*?##/ { printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)

   5. Add opm and catalog-build targets. You can use these targets to create your own catalogs for your Operator or add your Operator bundles to an existing catalog:

      1. Add the targets to your Makefile by adding the following lines:

         Example 5.7. opm and catalog-build targets

         .PHONY: opm
         OPM = ./bin/opm
         opm:
         ifeq (,$(wildcard $(OPM)))
         ifeq (,$(shell which opm 2>/dev/null))
         	@{ \
         	set -e ;\
         	mkdir -p $(dir $(OPM)) ;\
         	curl -sSLo $(OPM) https://github.com/operator-framework/operator-registry/releases/download/v1.15.1/$(OS)-$(ARCH)-opm ;\
         	chmod +x $(OPM) ;\
         	}
         else
         OPM = $(shell which opm)
         endif
         endif
         BUNDLE_IMGS ?= $(BUNDLE_IMG)
         CATALOG_IMG ?= $(IMAGE_TAG_BASE)-catalog:v$(VERSION) ifneq ($(origin CATALOG_BASE_IMG), undefined) FROM_INDEX_OPT := --from-index $(CATALOG_BASE_IMG) endif
         .PHONY: catalog-build
         catalog-build: opm
         	$(OPM) index add --container-tool docker --mode semver --tag $(CATALOG_IMG) --bundles $(BUNDLE_IMGS) $(FROM_INDEX_OPT)
         
         .PHONY: catalog-push
         catalog-push: ## Push the catalog image.
         	$(MAKE) docker-push IMG=$(CATALOG_IMG)

      2. If you are updating a Go-based Operator project, also add the following Makefile variables:

         Example 5.8. Makefile variables

         OS = $(shell go env GOOS)
         ARCH = $(shell go env GOARCH)

   6. For Go-based Operator projects, set the SHELL variable in your Makefile to the system bash binary.

      Importing the setup-envtest.sh script requires bash, so the SHELL variable must be set to bash with error options:

      Example 5.9. Makefile diff

      else GOBIN=$(shell go env GOBIN)
      endif
      +# Setting SHELL to bash allows bash commands to be executed by recipes.
      +# This is a requirement for 'setup-envtest.sh' in the test target.
      +# Options are set to exit when a recipe line exits non-zero or a piped command fails.
      +SHELL = /usr/bin/env bash -o pipefail
      +.SHELLFLAGS = -ec
      + all: build

4. For Go-based Operator projects, upgrade controller-runtime to v0.8.3 and Kubernetes dependencies to v0.20.2 by changing the following entries in your go.mod file, then rebuild your project:

   Example 5.10. go.mod file

   ...
   	k8s.io/api v0.20.2
   	k8s.io/apimachinery v0.20.2
   	k8s.io/client-go v0.20.2
   	sigs.k8s.io/controller-runtime v0.8.3

5. Add a system:controller-manager service account to your project. A non-default service account controller-manager is now generated by the operator-sdk init command to improve security for Operators installed in shared namespaces. To add this service account to your existing project, follow these steps:

   1. Create the ServiceAccount definition in a file:

      Example 5.11. config/rbac/service_account.yaml file

      apiVersion: v1
      kind: ServiceAccount
      metadata:
        name: controller-manager
        namespace: system

   2. Add the service account to the list of RBAC resources:

      $ echo "- service_account.yaml" >> config/rbac/kustomization.yaml

   3. Update all RoleBinding and ClusterRoleBinding objects that reference the Operator’s service account:

      $ find config/rbac -name *_binding.yaml -exec sed -i -E 's/  name: default/  name: controller-manager/g' {} \;

   4. Add the service account name to the manager deployment’s spec.template.spec.serviceAccountName field:

      $ sed -i -E 's/([ ]+)(terminationGracePeriodSeconds:)/\1serviceAccountName: controller-manager\n\1\2/g' config/manager/manager.yaml

   5. Verify the changes look like the following diffs:

      Example 5.12. config/manager/manager.yaml file diff

      ...
                 requests:
                   cpu: 100m
                   memory: 20Mi
      +      serviceAccountName: controller-manager
             terminationGracePeriodSeconds: 10

      Example 5.13. config/rbac/auth_proxy_role_binding.yaml file diff

      ...
         name: proxy-role
       subjects:
       - kind: ServiceAccount
      -  name: default
      +  name: controller-manager
         namespace: system

      Example 5.14. config/rbac/kustomization.yaml file diff

       resources:
      +- service_account.yaml
       - role.yaml
       - role_binding.yaml
       - leader_election_role.yaml

      Example 5.15. config/rbac/leader_election_role_binding.yaml file diff

      ...
         name: leader-election-role
       subjects:
       - kind: ServiceAccount
      -  name: default
      +  name: controller-manager
         namespace: system

      Example 5.16. config/rbac/role_binding.yaml file diff

      ...
         name: manager-role
       subjects:
       - kind: ServiceAccount
      -  name: default
      +  name: controller-manager
         namespace: system

      Example 5.17. config/rbac/service_account.yaml file diff

      +apiVersion: v1
      +kind: ServiceAccount
      +metadata:
      +  name: controller-manager
      +  namespace: system

6. Make the following changes to your config/manifests/kustomization.yaml file:

   1. Add a Kustomize patch to remove the cert-manager volume and volumeMount objects from your cluster service version (CSV).

      Because Operator Lifecycle Manager (OLM) does not yet support cert-manager, a JSON patch was added to remove this volume and mount so OLM can create and manage certificates for your Operator.

      In the config/manifests/kustomization.yaml file, add the following lines:

      Example 5.18. config/manifests/kustomization.yaml file

      patchesJson6902:
      - target:
          group: apps
          version: v1
          kind: Deployment
          name: controller-manager
          namespace: system
        patch: |-
          # Remove the manager container's "cert" volumeMount, since OLM will create and mount a set of certs.
          # Update the indices in this path if adding or removing containers/volumeMounts in the manager's Deployment.
          - op: remove
            path: /spec/template/spec/containers/1/volumeMounts/0
          # Remove the "cert" volume, since OLM will create and mount a set of certs.
          # Update the indices in this path if adding or removing volumes in the manager's Deployment.
          - op: remove
            path: /spec/template/spec/volumes/0

   2. Optional: For Ansible- and Helm-based Operator projects, configure ansible-operator and helm-operator with a component config. To add this option, follow these steps:

      1. Create the following file:

         Example 5.19. config/default/manager_config_patch.yaml file

         apiVersion: apps/v1
         kind: Deployment
         metadata:
           name: controller-manager
           namespace: system
         spec:
           template:
             spec:
               containers:
               - name: manager
                 args:
                 - "--config=controller_manager_config.yaml"
                 volumeMounts:
                 - name: manager-config
                   mountPath: /controller_manager_config.yaml
                   subPath: controller_manager_config.yaml
               volumes:
               - name: manager-config
                 configMap:
                   name: manager-config

      2. Create the following file:

         Example 5.20. config/manager/controller_manager_config.yaml file

         apiVersion: controller-runtime.sigs.k8s.io/v1alpha1
         kind: ControllerManagerConfig
         health:
           healthProbeBindAddress: :6789
         metrics:
           bindAddress: 127.0.0.1:8080
         
         leaderElection:
           leaderElect: true
           resourceName: <resource_name>

      3. Update the config/default/kustomization.yaml file by applying the following changes to resources:

         Example 5.21. config/default/kustomization.yaml file

           resources:
           ...
           - manager_config_patch.yaml

      4. Update the config/manager/kustomization.yaml file by applying the following changes:

         Example 5.22. config/manager/kustomization.yaml file

           generatorOptions:
             disableNameSuffixHash: true
         
           configMapGenerator:
           - files:
             - controller_manager_config.yaml
             name: manager-config
           apiVersion: kustomize.config.k8s.io/v1beta1
           kind: Kustomization
           images:
           - name: controller
             newName: quay.io/example/memcached-operator
             newTag: v0.0.1

   3. Optional: Add a manager config patch to the config/default/kustomization.yaml file.

      The generated --config flag was not added to either the ansible-operator or helm-operator binary when config file support was originally added, so it does not currently work. The --config flag supports configuration of both binaries by file; this method of configuration only applies to the underlying controller manager and not the Operator as a whole.

      To optionally configure the Operator’s deployment with a config file, make changes to the config/default/kustomization.yaml file as shown in the following diff:

      Example 5.23. config/default/kustomization.yaml file diff

      # If you want your controller-manager to expose the /metrics # endpoint w/o any authn/z, please comment the following line.
      \- manager_auth_proxy_patch.yaml
      +# Mount the controller config file for loading manager configurations
      +# through a ComponentConfig type
      +- manager_config_patch.yaml

      Flags can be used as is or to override config file values.

7. For Ansible- and Helm-based Operator projects, add role rules for leader election by making the following changes to the config/rbac/leader_election_role.yaml file:

   Example 5.24. config/rbac/leader_election_role.yaml file

   - apiGroups:
     - coordination.k8s.io
     resources:
     - leases
     verbs:
     - get
     - list
     - watch
     - create
     - update
     - patch
     - delete

8. For Ansible-based Operator projects, update Ansible collections.

   In your requirements.yml file, change the version field for community.kubernetes to 1.2.1, and the version field for operator_sdk.util to 0.2.0.

9. Make the following changes to your config/default/manager_auth_proxy_patch.yaml file:

   • For Ansible-based Operator projects, add the --health-probe-bind-address=:6789 argument to the config/default/manager_auth_proxy_patch.yaml file:

     Example 5.25. config/default/manager_auth_proxy_patch.yaml file

     spec:
       template:
         spec:
           containers:
           - name: manager
             args:
             - "--health-probe-bind-address=:6789"
             ...

   • For Helm-based Operator projects:

     1. Add the --health-probe-bind-address=:8081 argument to the config/default/manager_auth_proxy_patch.yaml file:

        Example 5.26. config/default/manager_auth_proxy_patch.yaml file

        spec:
          template:
            spec:
              containers:
              - name: manager
                args:
                - "--health-probe-bind-address=:8081"
                ...

     2. Replace the deprecated flag --enable-leader-election with --leader-elect, and the deprecated flag --metrics-addr with --metrics-bind-address.

10. Make the following changes to your config/prometheus/monitor.yaml file:

    1. Add scheme, token, and TLS config to the Prometheus ServiceMonitor metrics endpoint.

       The /metrics endpoint, while specifying the https port on the manager pod, was not actually configured to serve over HTTPS because no tlsConfig was set. Because kube-rbac-proxy secures this endpoint as a manager sidecar, using the service account token mounted into the pod by default corrects this problem.

       Apply the changes to the config/prometheus/monitor.yaml file as shown in the following diff:

       Example 5.27. config/prometheus/monitor.yaml file diff

       spec:
          endpoints:
            - path: /metrics
              port: https
       +      scheme: https
       +      bearerTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token
       +      tlsConfig:
       +        insecureSkipVerify: true
          selector:
            matchLabels:
              control-plane: controller-manager

       Note

       If you removed kube-rbac-proxy from your project, ensure that you secure the /metrics endpoint using a proper TLS configuration.

11. Ensure that existing dependent resources have owner annotations.

    For Ansible-based Operator projects, owner reference annotations on cluster-scoped dependent resources and dependent resources in other namespaces were not applied correctly. A workaround was to add these annotations manually, which is no longer required as this bug has been fixed.

12. Deprecate support for package manifests.

    The Operator Framework is removing support for the Operator package manifest format in a future release. As part of the ongoing deprecation process, the operator-sdk generate packagemanifests and operator-sdk run packagemanifests commands are now deprecated. To migrate package manifests to bundles, the operator-sdk pkgman-to-bundle command can be used.

    Run the operator-sdk pkgman-to-bundle --help command and see "Migrating package manifest projects to bundle format" for more details.

13. Update the finalizer names for your Operator.

    The finalizer name format suggested by Kubernetes documentation is:

    <qualified_group>/<finalizer_name>

    while the format previously documented for Operator SDK was:

    <finalizer_name>.<qualified_group>

    If your Operator uses any finalizers with names that match the incorrect format, change them to match the official format. For example, finalizer.cache.example.com must be changed to cache.example.com/finalizer.