Chapter 3. User tasks

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.