Chapter 5. Configuration and provision of 3scale via the operator

This document contains information about 3scale operator for capabilities, which involves provisioning 3scale services and configurations via the 3scale operator through the OpenShift Container Platform (OCP) user interface.

When using the 3scale operator to update API configurations in 3scale, the custom resource definitions (CRDs) are the source of truth. If changes are made in the Admin user interface, they will not persist and eventually be overridden by the definition in the CRD.

Important

3scale operator for capabilities is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

This chapter includes details about how operator application capabilities work, and the following procedures to deploy:

Additionally, you will find information about the limitations of capabilities via the 3scale operator.

5.1. General prerequisites

For the configuration and provision of 3scale via the operator, these are the required elements:

5.2. Application capabilities via the 3scale operator

The 3scale operator contains these featured capabilities:

  • Allows interaction with the underlying Red Hat 3scale API Management solution.
  • Manages the 3scale application declaratively using custom resources from OpenShift.

The diagram below shows 3scale entities and relations that are eligible for management using OpenShift custom resources in a declarative way. Products contain one or more backends. At the product level, you can configure applications, application plans, as well as mapping rules. At the backend level, you can set up metrics, methods and mapping rules for each backend.

3scale entities and relations eligible for management using OpenShift custom resources.

The 3scale operator provides custom resource definitions and their relations, which are visible in the following diagram.

3scale entities and relations eligible for management using OpenShift custom resources.

5.3. Deploying your first 3scale product and backend

Using Openshift Container Platform in your newly created tenant, you will deploy your first 3scale product and backend with the minimum required configuration.

Prerequisites

The same installation requirements as listed in General prerequisites, with these considerations:

  • The 3scale account can be local in the working OpenShift namespace or a remote installation.
  • The required parameters from this account are the 3scale Admin URL address and the access token.

Procedure

  1. Create a secret for the 3scale provider account using the credentials from the 3scale Admin Portal. For example: adminURL=https://3scale-admin.example.com and token=123456.

    oc create secret generic threescale-provider-account --from-literal=adminURL=https://3scale-admin.example.com --from-literal=token=123456
  2. Configure the 3scale backend with the upstream API URL:

    1. Create a YAML file with the following content:

      apiVersion: capabilities.3scale.net/v1beta1
      kind: Backend
      metadata:
        name: backend1
      spec:
        name: "Operated Backend 1"
        systemName: "backend1"
        privateBaseURL: "https://api.example.com"
      • Once you create the file, the operator will confirm if the step was successful.
      • For more details about the fields of Backend custom resource and possible values, see the Backend CRD Reference.
    2. Create a custom resource:

      oc create -f backend1.yaml
  3. Configure the 3scale product:

    1. Create a product with all the default settings applied to the previously created backend:

      apiVersion: capabilities.3scale.net/v1beta1
      kind: Product
      metadata:
        name: product1
      spec:
        name: "OperatedProduct 1"
        systemName: "operatedproduct1"
        backendUsages:
          backend1:
            path: /
      • Once you create the file, the operator will confirm if the step was successful.
      • For more details about the fields of the Product custom resource and possible values, see the Product CRD Reference.
    2. Create a custom resource:

      oc create -f product1.yaml
  4. Created custom resources will take a few seconds to populate your 3scale instance. To confirm when resources are synchronized, you can choose one of these alternatives:

    • Verify the status field of the object.
    • Use the oc wait commands:

      oc wait --for=condition=Synced --timeout=-1s backend/backend1
      oc wait --for=condition=Synced --timeout=-1s product/product1

5.6. Deploying a tenant custom resource

A tenant custom resource is also known as the Provider Account.

Creating the APIManager custom resource indicates the operator to deploy 3scale. A default 3scale installation includes a default tenant ready to be used. Optionally, you may create other tenants creating tenant custom resource objects.

Prerequisites

To deploy a new tenant in your 3scale instance, you need some preparation steps:

  1. Obtain or create the 3scale master credentials secret: MASTER_SECRET

    You can perform tenant management tasks by only using the 3scale master account credentials, preferably an access token. You have the following options:

    • If the tenant resource is created in the same namespace as 3scale, the secret with master account credentials has been created already and it is called system-seed.
    • If the tenant resource is not created in the same namespace as 3scale, create a secret with the master account credentials. In this command, the name of the secret is optional. The secret name will be used in the tenant custom resource:

      oc create secret generic system-seed --from-literal=MASTER_ACCESS_TOKEN=<master access token>
  2. Create a new secret to store the password for the admin account of the new tenant: ADMIN_SECRET. In this command, the name of the secret is optional. The secret name will be used in the tenant custom resource.

    oc create secret generic ecorp-admin-secret --from-literal=admin_password=<admin password value>
  3. Get the 3scale master account hostname: MASTER_HOSTNAME. When you deploy 3scale using the operator, the master account has a fixed URL with this pattern: master.${wildcardDomain}

    • If you have access to the namespace where 3scale is installed, get the master account hostname:

      oc get routes --field-selector=spec.to.name==system-master -o jsonpath="{.items[].spec.host}"

Procedure

  1. Deploy the new tenant custom resource:

    apiVersion: capabilities.3scale.net/v1alpha1
    kind: Tenant
    metadata:
      name: ecorp-tenant
    spec:
      username: admin
      systemMasterUrl: https://<MASTER_HOSTNAME>
      email: admin@ecorp.com
      organizationName: ECorp
      masterCredentialsRef:
        name: <MASTER_SECRET>
      passwordCredentialsRef:
        name: <ADMIN_SECRET*>
      tenantSecretRef:
        name: tenant-secret
  2. Create the tenant resource:

    oc create -f <yaml-name>
    • This command triggers the creation of a new tenant in your 3scale solution.
    • The 3scale operator will create a new secret and store the new tenant credentials in the secret.
    • The new tenant provider_key and admin domain url will be stored in a secret.
    • The secret location can be specified using the tenantSecretRef tenant specification key.

As a reference, this is an example of the created secret content:

apiVersion: v1
kind: Secret
metadata:
  name: tenant-secret
type: Opaque
stringData:
  adminURL: https://my3scale-admin.example.com:443
  token: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

For more details about the fields of tenant custom resource and possible values, see the Tenant CRD Reference.

5.7. Limitations of capabilities via the 3scale operator

In Red Hat 3scale API Management 2.10, 3scale operator contains these limitations with capabilities:

  • Deletion of a backend custom resource definition (CRD) is not reconciled: existing backends in 3scale will not be deleted.
  • Deletion of a product CRD is not reconciled: existing products in 3scale will not be deleted.
  • Product CRD does not support Single Sign-On (SSO) authentication for the Admin and Developer portals.
  • Product CRD does not support OpenID Connect authentication .
  • ActiveDocs CRD not currently available.
  • Gateway Policy CRD not currently available.
  • Product CRD Gateway does not support response custom code and errors
  • 3scale operator CRD holding OAS3 does not reference as source of truth for 3scale product configuration.

5.8. Additional resources

For more information, check the following guides: