Chapter 7. Using the 3scale API Management operator to configure and provision 3scale

Procedure

1. Define a secret that contains an OAS document. For example, you might create the myoasdoc1.yaml with this content:

   openapi: "3.0.2"
   info:
     title: "some title"
     description: "some description"
     version: "1.0.0"
   paths:
     /pet:
       get:
         operationId: "getPet"
         responses:
           405:
             description: "invalid input"

   Copy to Clipboard Toggle word wrap

2. Create the secret. For example:

   $ oc create secret generic myoasdoc1 --from-file myoasdoc1.yaml
   
   secret/myoasdoc1 created

   Copy to Clipboard Toggle word wrap

3. Define your OpenAPI CR. Be sure to specify a reference to the secret that contains your OAS document. For example, you might create the myopenapicr1.yaml file:

   apiVersion: capabilities.3scale.net/v1beta1
   kind: OpenAPI
   metadata:
     name: myopenapicr1
   spec:
     openapiRef:
       secretRef:
         name: myoasdoc1

   Copy to Clipboard Toggle word wrap

4. Create the resource you just defined. For example:

   $ oc create -f myopenapicr1.yaml

   Copy to Clipboard Toggle word wrap

   For the given example, the output would be:

   $ openapi.capabilities.3scale.net/myopenapicr1 created

   Copy to Clipboard Toggle word wrap

Procedure

1. Create the secret, for example, my-secret.yaml, with the following content:

   kind: Secret
   apiVersion: v1
   metadata:
     name: my-secret
     namespace: 3scale-test
   data:
     issuerEndpoint: https://3scale-zync:some-secret@keycloak-rhsso-test.example.com/auth/realms/petstore
   type: Opaque

   Copy to Clipboard Toggle word wrap

2. Apply the secret with the following command:

   $ oc apply -f my-secret.yaml

   Copy to Clipboard Toggle word wrap

3. Create the OpenAPI CR for OIDC and OAuth2, for example, openapi-example.yaml, with the following content:

   apiVersion: capabilities.3scale.net/v1beta1
   kind: OpenAPI
   metadata:
     generation: 1
     name: openapi-example
   spec:
     openapiRef:
       url: "https://example.com/petstore.yaml"
     privateAPISecretToken: "xxxx"
     oidc:
       issuerType: keycloak
       issuerEndpointRef:
         name: my-secret
       jwtClaimWithClientID: azp
       jwtClaimWithClientIDType: plain
       authenticationFlow:
         standardFlowEnabled: true
         implicitFlowEnabled: true
         serviceAccountsEnabled: true
         directAccessGrantsEnabled: true
       gatewayResponse:
         errorStatusAuthFailed: 403

   Copy to Clipboard Toggle word wrap

4. Apply the OpenAPI CR for OIDC and OAuth2 with the following command:

   $ oc apply -f <openapi-cr-file>.yaml

   Copy to Clipboard Toggle word wrap

Procedure

1. In your OpenShift account, navigate to Operators > Installed operators.
2. Click the 3scale operator.
3. Choose the YAML tab.

4. Create an OpenAPI custom resource (CR). For example:

   apiVersion: capabilities.3scale.net/v1beta1
   kind: OpenAPI
   metadata:
     name: openapi1
   spec:
     openapiRef:
       url: "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml"
     providerAccountRef:
       name: mytenant

   Copy to Clipboard Toggle word wrap
5. Click Save. It takes a few seconds for the 3scale operator to create the OpenAPI CR.

Verification

1. In OpenShift, in the 3scale Product Overview page, confirm that the Synced condition is marked as True.
2. Go to your 3scale account.
3. Confirm that the OAS document is present. For the example above, you would see a new OAS document named openapi1.

Procedure

1. Create the secret. For example:

   $ oc create secret generic myoasdoc1 --from-file myoasdoc1.yaml
   
   secret/myoasdoc1 created

   Copy to Clipboard Toggle word wrap

2. Define your ActiveDoc CR. Be sure to specify a reference to the secret that contains your OAS document. For example, you might create the myactivedoccr1.yaml file:

   apiVersion: capabilities.3scale.net/v1beta1
   kind: ActiveDoc
   metadata:
     name: myactivedoccr1
   spec:
     name: "Operated ActiveDoc From secret"
     activeDocOpenAPIRef:
       secretRef:
         name: myoasdoc1

   Copy to Clipboard Toggle word wrap

3. Create the resource you just defined. For example:

   $ oc create -f myactivedoccr1.yaml

   Copy to Clipboard Toggle word wrap

   For the given example, the output would be:

   $ activedoc.capabilities.3scale.net/myactivedoccr1 created

   Copy to Clipboard Toggle word wrap

Verification

1. Log in to your Red Hat OpenShift Container Platform (OCP) administrator account.
2. Navigate to Operators > Installed Operators.
3. Click Red Hat Integration - 3scale.
4. Click the Active Doc tab.
5. Confirm that the OAS document is present. For the example above, you would see a new OAS document named myactivedoccr1.

Procedure

1. In your OpenShift account, navigate to Operators > Installed operators.
2. Click the 3scale operator.
3. Click the Active Doc tab.

4. Create an ActiveDoc CR. For example:

   apiVersion: capabilities.3scale.net/v1beta1
   kind: ActiveDoc
   metadata:
     name: myactivedoccr1
   spec:
     openapiRef:
       url: "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml"
     providerAccountRef:
       name: mytenant

   Copy to Clipboard Toggle word wrap

5. Optional. For self-managed APIcast, in the ActiveDoc CR, set the productionPublicBaseURL and stagingPublicBaseURL fields to the URLs for your deployment. For example:

   apiVersion: capabilities.3scale.net/v1beta1
   kind: ActiveDoc
   metadata:
     name: myactivedoccr1
   spec:
     openapiRef:
       url: "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml"
     productionPublicBaseURL: "https://production.my-gateway.example.com"
     stagingPublicBaseURL: "https://staging.my-gateway.example.com"

   Copy to Clipboard Toggle word wrap
6. Click Save. It takes a few seconds for the 3scale operator to create the ActiveDoc CR.

Verification

1. Log in to your Red Hat OpenShift Container Platform (OCP) administrator account.
2. Navigate to Operators > Installed Operators.
3. Click Red Hat Integration 3scale.
4. Click the Active Doc tab.
5. Confirm that the OAS document is present. For the example above, you would see a new OAS document named myactivedoccr1.

Procedure

1. In your OpenShift account, navigate to Installed operators.
2. Click on the 3scale operator.
3. Under 3scale Backend, click Create Instance.
4. Choose the YAML View.

5. Create a 3scale backend pointing to a specific 3scale Admin URL address:

   apiVersion: capabilities.3scale.net/v1beta1
   kind: Backend
   metadata:
     name: <your_backend_OpenShift_name>
   spec:
     name: "<your_backend_name>"
     privateBaseURL: "<your_admin_portal_URL>"

   Copy to Clipboard Toggle word wrap

   For example:

   apiVersion: capabilities.3scale.net/v1beta1
   kind: Backend
   metadata:
     name: backend-1
   spec:
     name: "My Backend Name"
     privateBaseURL: "https://api.example.com"

   Copy to Clipboard Toggle word wrap
6. To save your changes, click Create.

7. Wait a few seconds to have the backend created both in OpenShift, and in your 3scale account. Then, you can perform the following verifications:

   1. Confirm that the backend has been created in OpenShift, by checking in the 3scale Backend Overview page that the Synced condition is marked as True.
   2. Go to your 3scale account, and you will see that the backend has been created. In the example above, you will see a new backend called My Backend Name.

1. Checks credentials from the providerAccountRef resource attribute. This is a secret local reference; for instance mytenant:

   apiVersion: capabilities.3scale.net/v1beta1
   kind: Backend
   metadata:
     name: backend-1
   spec:
     name: "My Backend Name"
     privateBaseURL: "https://api.example.com"
     providerAccountRef:
       name: mytenant

   Copy to Clipboard Toggle word wrap

   The mytenant secret must have adminURL and token fields filled with tenant credentials. For example:

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

   Copy to Clipboard Toggle word wrap

2. Checks the default threescale-provider-account secret. 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

   Copy to Clipboard Toggle word wrap
3. Checks the default provider account in the same namespace of the 3scale deployment: The operator will gather required credentials automatically for the default 3scale tenant (provider account), if the 3scale installation is located in the same namespace as the custom resource.

Procedure

1. Determine the endpoint issuerEndpoint, which defines the location of your OpenID Provider and use this format in the product CR:

   https://<client_id>:<client_secret>@<host>:<port_number>/auth/realms/<realm_name>`

   Copy to Clipboard Toggle word wrap

2. Define or update a 3scale Product CR that specifies OpenID Connect (OIDC) authentication for any OAuth 2.0 flow. For example:

   apiVersion: capabilities.3scale.net/v1beta1
   kind: Product
   metadata:
     name: product1
   spec:
     name: "OperatedProduct 1"
     deployment:
       <any>:
         authentication:
           oidc:
             issuerType: "keycloak"
             issuerEndpoint: "https://myclientid:myclientsecret@mykeycloack.example.com/auth/realms/myrealm"
             authenticationFlow:
               standardFlowEnabled: false
               implicitFlowEnabled: true
               serviceAccountsEnabled: true
               directAccessGrantsEnabled: true
             jwtClaimWithClientID: "azp"
             jwtClaimWithClientIDType: "plain"

   Copy to Clipboard Toggle word wrap

3. Create the resource you just defined. For example:

   $ oc create -f product1.yaml

   Copy to Clipboard Toggle word wrap

   For the given example, the output would be:

   $ product.capabilities.3scale.net/product1 created

   Copy to Clipboard Toggle word wrap

Procedure

1. In a new or deployed Product CR, configure one or more responses in the gatewayResponse object. The following example shows response configuration for an Apicast hosted deployment with an authentication mode called userKey:

   apiVersion: capabilities.3scale.net/v1beta1
   kind: Product
   metadata:
     name: product1
   spec:
     name: "OperatedProduct 1"
     deployment:
       apicastHosted:
         authentication:
           userkey:
             gatewayResponse:
               errorStatusAuthFailed: 500
               errorHeadersAuthFailed: "text/plain; charset=mycharset"
               errorAuthFailed: "My custom reponse body"
               errorStatusAuthMissing: 500
               errorHeadersAuthMissing: "text/plain; charset=mycharset"
               errorAuthMissing: "My custom reponse body"
               errorStatusNoMatch: 501
               errorHeadersNoMatch: "text/plain; charset=mycharset"
               errorNoMatch: "My custom reponse body"
               errorStatusLimitsExceeded: 502
               errorHeadersLimitsExceeded: "text/plain; charset=mycharset"
               errorLimitsExceeded: "My custom reponse body"

   Copy to Clipboard Toggle word wrap

2. Deploy the Product CR that contains the gateway responses. For example, if you updated the product1.yaml file, you would run the following command:

   $ oc create -f product1.yaml

   Copy to Clipboard Toggle word wrap

   For the given example, the output would be:

   product.capabilities.3scale.net/product1 created

   Copy to Clipboard Toggle word wrap

Procedure

1. In a new or deployed Product CR, configure one or more policies in the policies object. For example:

   • With configuration from value

       apiVersion: capabilities.3scale.net/v1beta1
       kind: Product
       metadata:
         name: product1
       spec:
         name: "OperatedProduct 1"
         policies:
         - configuration:
             http_proxy: http://example.com
             https_proxy: https://example.com
           enabled: true
           name: camel
           version: builtin
         - configuration: {}
           enabled: true
           name: apicast
           version: builtin

     Copy to Clipboard Toggle word wrap

   • With configuration from secret

     apiVersion: v1
     kind: Secret
     metadata:
       name: my-config-policy
     type: Opaque
     stringData:
       configuration: "{\"http_proxy\":\"http://secret.com\"}"
     ---
     apiVersion: capabilities.3scale.net/v1beta1
     kind: Product
     metadata:
       name: product2
     spec:
       name: "OperatedProduct 2"
       policies:
       - configurationRef:
           name: my-config-policy
         enabled: true
         name: camel
         version: builtin
       - configuration: {}
         enabled: true
         name: apicast
         version: builtin

     Copy to Clipboard Toggle word wrap

     For each policy, specify these fields:

   • configuration is a pair of empty braces when a policy has no parameters. When a policy has parameters, specify them here. For the names of any parameters that you need to specify, see the documentation for the relevant policy in Administering the API Gateway, APIcast standard policies.
   • enabled is a Boolean switch for turning the policy on or off.
   • name identifies the policy. This is a unique name in the scope of the tenant that the Product CR links to. To identify policy names, see the documentation for the relevant policy in Standard policies to change default 3scale API Management APIcast behavior.

   • version is builtin for standard policies or a user-defined string for custom policies. For example, you could set the version of a custom policy to 1.0.

     If a Product CR does not specify the apicast policy, the operator adds it.

     If a policy chain is already defined in the Admin Portal, you can run the 3scale toolbox export command to export the policy chain in .yaml format. You can paste the export output into a Product CR. For example, if api-provider-account-one is the name of your 3scale provider account, and my-api-product-one is the name of the product whose policy chain you want to export, you would run the following command:

   $ 3scale policies export api-provider-account-one my-api-product-one

   Copy to Clipboard Toggle word wrap

2. Deploy the Product CR that contains the policy chain. For example, if you updated the product1.yaml file, you would run the following command:

   $ oc create -f product1.yaml

   Copy to Clipboard Toggle word wrap

   For the given example, the output would be:

   $ product.capabilities.3scale.net/product1 created

   Copy to Clipboard Toggle word wrap

1. Checks credentials from the providerAccountRef resource attribute. This is a secret local reference; for instance mytenant:

   apiVersion: capabilities.3scale.net/v1beta1
   kind: Product
   metadata:
     name: product1
   spec:
     name: "OperatedProduct 1"
     providerAccountRef:
       name: mytenant

   Copy to Clipboard Toggle word wrap

   The mytenant secret must have adminURL and token fields filled with tenant credentials. For example:

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

   Copy to Clipboard Toggle word wrap

2. Checks the default threescale-provider-account secret. 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

   Copy to Clipboard Toggle word wrap
3. Checks the default provider account in the same namespace of the 3scale deployment: The operator will gather required credentials automatically for the default 3scale tenant (provider account), if the 3scale installation is located in the same namespace as the custom resource.

Procedure

1. In your OpenShift account, navigate to Installed Operators.
2. Click on Red Hat Integration - 3scale.
3. In the Application tab, click Create application.
4. Choose the YAML View.

5. Create a 3scale application pointing to a specific application plan:

   For example:

   apiVersion: capabilities.3scale.net/v1beta1
   kind: Application
   metadata:
     name: example
     namespace: 3scale_project_name
   spec:
     accountCR:
       name: developer_account
     applicationPlanName: application_plan_name
     productCR:
       name: product_custom_resource
     name: application_name
     description: describe_your_application

   Copy to Clipboard Toggle word wrap
6. To save your changes, click Create.

7. Wait a few seconds to have the application created both in OpenShift, as well as in your 3scale account. Then, you can perform the following verifications:

   1. Confirm that the application has been created in OpenShift, by checking in the 3scale Application Overview. The Ready condition value should be True.
   2. Go to your 3scale account, and you will see that the application has been created. In the example above, you will see a new application by the unique name you have given it.

Procedure

1. In the namespace that contains the 3scale operator, create and save a resource file that defines a secret that contains the user name and password for a developer user who will have the admin role in the new developer account resource. For example, the myusername01.yaml file might contain:

   apiVersion: v1
   kind: Secret
   metadata:
     name: myusername01
   stringData:
     password: "123456"

   Copy to Clipboard Toggle word wrap

2. Create the secret. For example:

   $ oc create -f myusername01.yaml

   Copy to Clipboard Toggle word wrap

   For the given example, the output would be:

   $ secret/myusername01 created

   Copy to Clipboard Toggle word wrap

3. Create and save a .yaml file that defines a DeveloperUser CR for a developer who has the admin role. This DeveloperUser CR is required for the 3scale operator to deploy a new DeveloperAccount CR. For example, the developeruser01.yaml file might contain:

   apiVersion: capabilities.3scale.net/v1beta1
   kind: DeveloperUser
   metadata:
     name: developeruser01
   spec:
     username: myusername01
     email: myusername01@example.com
     passwordCredentialsRef:
       name: myusername01
     role: admin
     developerAccountRef:
       name: developeraccount1
     providerAccountRef:
       name: mytenant

   Copy to Clipboard Toggle word wrap

   In a DeveloperUser CR:

   • The developer user account name, user name, and email must be unique in the tenant that the containing DeveloperAccount links to.
   • The developer account name that you specify here must match the name of the DeveloperAccount CR that you are deploying in this procedure. It does not matter whether you create the DeveloperAccount CR before or after you create this DeveloperUser CR.
   • The tenant that a DeveloperUser CR links to must be the same tenant that the specified DeveloperAccount CR links to.

4. Create the resource you just defined. For example:

   $ oc create -f developeruser01.yaml

   Copy to Clipboard Toggle word wrap

   For the given example, the output would be:

   $ developeruser.capabilities.3scale.net/developeruser01 created

   Copy to Clipboard Toggle word wrap

5. Create and save a .yaml file that defines a DeveloperAccount CR. In this .yaml file, the spec.OrgName field must specify an organization name. For example, the developeraccount01.yaml file might contain:

   apiVersion: capabilities.3scale.net/v1beta1
   kind: DeveloperAccount
   metadata:
     name: developeraccount01
   spec:
     orgName: Ecorp
     providerAccountRef:
       name: mytenant

   Copy to Clipboard Toggle word wrap

6. Create the resource you just defined. For example:

   $ oc create -f developeraccount01.yaml

   Copy to Clipboard Toggle word wrap

   For the given example, the output would be:

   $ developeraccount.capabilities.3scale.net/developeraccount01 created

   Copy to Clipboard Toggle word wrap

Procedure

1. In the namespace that contains the 3scale operator, create and save a resource file that defines a secret that contains the username and password for a developer user. For example, the myusername02.yaml file might contain:

   apiVersion: v1
   kind: Secret
   metadata:
     name: myusername02
   stringData:
     password: "987654321"

   Copy to Clipboard Toggle word wrap

2. Create the secret. For example:

   $ oc create -f myusername02.yaml

   Copy to Clipboard Toggle word wrap

   For the given example, the output would be:

   $ secret/myusername02 created

   Copy to Clipboard Toggle word wrap

3. Create and save a .yaml file that defines a DeveloperUser CR. In the spec.role field, specify admin or member. For example, the developeruser02.yaml file might contain:

   apiVersion: capabilities.3scale.net/v1beta1
   kind: DeveloperUser
   metadata:
     name: developeruser02
   spec:
     username: myusername02
     email: myusername02@example.com
     passwordCredentialsRef:
       name: myusername02
     role: member
     developerAccountRef:
       name: developeraccount1
     providerAccountRef:
       name: mytenant

   Copy to Clipboard Toggle word wrap

   In a DeveloperUser CR:

   • The developer username (specified in the metadata.name field), the username, and email must be unique in the tenant that the containing DeveloperAccount links to.
   • The developerAccountRef field must specify the name of a deployed DeveloperAccount CR.
   • The tenant that a DeveloperUser CR links to must be the same tenant that the specified DeveloperAccount CR links to.

4. Create the resource you just defined. For example:

   $ oc create -f developefuser02.yaml

   Copy to Clipboard Toggle word wrap

   For the given example, the output would be:

   $ developeruser.capabilities.3scale.net/developeruser02 created

   Copy to Clipboard Toggle word wrap