Chapter 4. Installing the 3scale Operator on OpenShift

Note

3scale supports the last two general availability (GA) releases of OpenShift Container Platform (OCP). For more information, see the Red Hat 3scale API Management Supported Configurations page.

This documentation shows you how to:

  • Create a new project.
  • Deploy a Red Hat 3scale API Management instance.
  • Install the 3scale operator through Operator Lifecycle Manager (OLM).
  • Deploy the custom resources once the operator has been deployed.

Prerequisites

Warning

Deploy the 3scale operator and custom resource definitions (CRDs) in a separate newly created, empty project. If you deploy them in an existing project containing infrastructure, it could alter or delete existing elements.

To install the 3scale operator on OpenShift, perform the steps outlined in the following sections:

4.1. Creating a new OpenShift project

This procedure explains how to create a new OpenShift project named 3scale-project. Replace this project name with your own.

Procedure

To create a new OpenShift project:

  • Indicate a valid name using alphanumeric characters and dashes. As an example, run the command below to create 3scale-project: 

    oc new-project 3scale-project

This creates the new OpenShift project where the operator, the APIManager custom resource (CR), and the Capabilities custom resources will be installed. The operator manages the custom resources through OLM in that project.

4.2. Installing and configuring the 3scale operator using the OLM

Use Operator Lifecycle Manager (OLM) to install the 3scale operator on an OpenShift Container Platform (OCP) 4.6 cluster through the OperatorHub in the OCP console. You can install the 3scale operator using the following installation modes:

  • Cluster-wide in which the operator is available in all namespaces on the cluster.
  • A specific namespace on the cluster
Note

If you are using the OpenShift Container Platform on a restricted network or a disconnected cluster, the Operator Lifecycle Manager can no longer use the OperatorHub. Follow the instructions for setting up and using the OLM in the guide titled Using Operator Lifecycle Manager on restricted networks.

Prerequisites

Procedure

  1. In the OpenShift Container Platform console, log in using an account with administrator privileges.

    Note

    The menu structure depends on the version of OpenShift you are using:

  2. Click Operators > OperatorHub
  3. In the Filter by keyword box, type 3scale operator to find the 3scale operator.
  4. Click the 3scale operator. Information about the Operator is displayed.
  5. Read the information about the operator and click Install. The Install Operator page opens.
  6. On the Install Operator page, select the desired channel to update in the Update channel section.

  7. In the Installation mode section, select where to install the operator.

    1. All namespaces on the cluster (default) - The operator will be available in all namespaces on the cluster.
    2. A specific namespace on the cluster - The operator will only be available in the specific single namespace on the cluster that you have selected.
  8. Click Subscribe. The 3scale operator details page is displayed and you can see the Subscription Overview.
  9. Confirm that the subscription Upgrade Status is displayed as Up to date.

  10. Verify that the 3scale operator ClusterServiceVersion (CSV) is displayed, and the Status of the operator ultimately resolves to InstallSucceeded in the project you defined in Creating a new OpenShift project:

    • Click Operators > Installed Operators. In this case, successful installation will register the APIManager CRD, and the CRDs related to the Capabilities functionality of the operator in the OpenShift API server.

  11. After successful installation, query the resource types defined by the CRDs via oc get.

    1. For example, to verify that the APIManager CRD has been correctly registered, execute the following command: 

      oc get apimanagers

  12. You should see the following output: 

    No resources found.

Besides the indicated procedure, create a list of the allowed domains you intend to use in the 3scale Developer Portal while using OCP on restricted networks. Consider the following examples:

  • Any link you intend to add to the Developer Portal.
  • SSO integrations through third party SSO providers such as GitHub.
  • Billing.
  • Webhooks that trigger an external URL.

4.2.1. Restrictions in disconnected environments

The following list outlines current restrictions in a disconnected environment for 3scale 2.12:

  • The GitHub login to the Developer Portal is not available.
  • Support links are not operational.
  • Links to external documentation are not operational.
  • The validator for the OpenAPI Specification (OAS) in the Developer Portal is not operational, affecting links to external services.

  • In the product Overview page in ActiveDocs, links to OAS are not operational.

    • It is also necessary to check the option Skip swagger validations when you create a new ActiveDocs specification.

Additional resources

4.3. Upgrading the 3scale operator using the OLM

To upgrade the 3scale operator from a single namespace to a cluster-wide installation in all namespaces on an operator-based deployment, you must remove the 3scale operator from the namespace and then reinstall the operator on the cluster.

Cluster administrators can delete installed operators from a selected namespace by using the web console. Uninstalling the operator does not uninstall an existing 3scale instance.

After the 3scale operator is uninstalled from the namespace, you can use OLM to install the operator in the cluster-wide mode.

Prerequisites

  • 3scale administrator permissions or an OpenShift role that has delete permissions for the namespace.

Procedure

  1. In the OpenShift Container Platform console, log in using an account with administrator privileges.

    Note

    The menu structure depends on the version of OpenShift you are using:

  2. Click Operators > OperatorHub. The installed Operators page is displayed.
  3. Enter 3scale into the Filter by name to find the Operator and click on it.
  4. On the Operator Details page, select Uninstall Operator from the Actions drop-down menu to remove it from a specific namespace.

  5. 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.
  6. Select Uninstall. This operator stops running and no longer receives updates.
  7. In the OpenShift Container Platform console click Operators > OperatorHub.
  8. In the Filter by keyword box, type 3scale operator to find the 3scale operator.
  9. Click the 3scale operator. Information about the Operator is displayed.
  10. Click Install. The Install Operator page opens.
  11. On the Install Operator page, select the desired channel to update in the Update channel section.
  12. In the Installation mode section, select All namespaces on the cluster (default). The operator will be available in all namespaces on the cluster.
  13. Click Subscribe. The 3scale operator details page is displayed and you can see the Subscription Overview.
  14. Confirm that the subscription Upgrade Status is displayed as Up to date.
  15. Verify that the 3scale operator ClusterServiceVersion (CSV) is displayed.

Additional Resources