Chapter 8. Using the 3scale operator to configure and provision 3scale

8.1. General prerequisites
Link kopieren

To configure and provision 3scale by using the 3scale operator, these are the required elements:

A user account with administrator privileges for 3scale 2.11 On-Premises instance
3scale operator installed.
OpenShift Container Platform 4 with a user account that has administrator privileges in the OpenShift cluster.
- Note: OCP 4 supports deployment of 3scale using the operator only.
- For more information about supported configurations, see the Red Hat 3scale API Management Supported Configurations page.

8.2. Application capabilities via the 3scale operator
Link kopieren

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.

8.3. Deploying your first 3scale product and backend
Link kopieren

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

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

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

Configure the 3scale backend with the upstream API URL:

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"

apiVersion: capabilities.3scale.net/v1beta1
kind: Backend
metadata:
  name: backend1
spec:
  name: "Operated Backend 1"
  systemName: "backend1"
  privateBaseURL: "https://api.example.com"

Copy to Clipboard

Toggle word wrap

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.

Create a custom resource:
```
oc create -f backend1.yaml
```
```
oc create -f backend1.yaml
```
Copy to Clipboard Toggle word wrap

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: /
  Copy to Clipboard Toggle word wrap
  - 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
  Copy to Clipboard Toggle word wrap
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
  Copy to Clipboard Toggle word wrap

8.4. Promoting a product’s APIcast configuration
Link kopieren

Using the 3scale operator, you can promote the product’s APIcast configuration to staging or production. The ProxyConfigPromote custom resource (CR) promotes the latest APIcast configuration to the staging environment. Optionally, you can configure the ProxyConfigPromote CR to promote to the production environment as well.

Note

ProxyConfigPromote objects only take effect when created. After creation, any updates on them are not reconciled.

Prerequisites

The same installation requirements as listed in General prerequisites, including:

Have a product CR already created.

Procedure

Create and save a YAML file with the following content:

apiVersion: capabilities.3scale.net/v1beta1
kind: ProxyConfigPromote
metadata:
  name: proxyconfigpromote-sample
spec:
  productCRName: product1-sample

apiVersion: capabilities.3scale.net/v1beta1
kind: ProxyConfigPromote
metadata:
  name: proxyconfigpromote-sample
spec:
  productCRName: product1-sample

Copy to Clipboard

Toggle word wrap

To promote the APIcast configuration to the production environment, set the optional field spec.production to true:

apiVersion: capabilities.3scale.net/v1beta1
kind: ProxyConfigPromote
metadata:
  name: proxyconfigpromote-sample
spec:
  productCRName: product1-sample
  production: true

apiVersion: capabilities.3scale.net/v1beta1
kind: ProxyConfigPromote
metadata:
  name: proxyconfigpromote-sample
spec:
  productCRName: product1-sample
  production: true

Copy to Clipboard

Toggle word wrap

To delete the ProxyConfigPromote object after a successful promotion, set the optional field spec.deleteCR to true:

apiVersion: capabilities.3scale.net/v1beta1
kind: ProxyConfigPromote
metadata:
  name: proxyconfigpromote-sample
spec:
  productCRName: product1-sample
  deleteCR: true

apiVersion: capabilities.3scale.net/v1beta1
kind: ProxyConfigPromote
metadata:
  name: proxyconfigpromote-sample
spec:
  productCRName: product1-sample
  deleteCR: true

Copy to Clipboard

Toggle word wrap

To check the status condition of the file, type the following command:

oc get proxyconfigpromote proxyconfigpromote-sample -o yaml

oc get proxyconfigpromote proxyconfigpromote-sample -o yaml

Copy to Clipboard

Toggle word wrap

The output should show the satus is Ready:

apiVersion: capabilities.3scale.net/v1beta1
kind: ProxyConfigPromote
metadata:
  name: proxyconfigpromote-sample
spec:
  productCRName: product1-sample
status:
  conditions:
  - lastTransitionTime: "2022-10-28T11:35:19Z"
    status: "True"
    type: Ready

apiVersion: capabilities.3scale.net/v1beta1
kind: ProxyConfigPromote
metadata:
  name: proxyconfigpromote-sample
spec:
  productCRName: product1-sample
status:
  conditions:
  - lastTransitionTime: "2022-10-28T11:35:19Z"
    status: "True"
    type: Ready

Copy to Clipboard

Toggle word wrap

Create the custom resource:

oc create -f proxyconfigpromote-sample.yaml

oc create -f proxyconfigpromote-sample.yaml

Copy to Clipboard

Toggle word wrap

For the given example, the output would be:

proxyconfigpromote.capabilities.3scale.net/proxyconfigpromote-sample created

proxyconfigpromote.capabilities.3scale.net/proxyconfigpromote-sample created

Copy to Clipboard

Toggle word wrap

Additional resources

ProxyConfigPromote CRD Reference

8.5. How the 3scale operator identifies the tenant that a custom resource links to
Link kopieren

You can deploy 3scale custom resources (CRs) to manage a variety of 3scale objects. A 3scale CR links to exactly one tenant.

If the 3scale operator is installed in the same namespace as 3scale the default behavior is that a 3scale CR links to that 3scale instance’s default tenant. To link a 3scale CR to a different tenant, you can do one of the following:

Create the threescale-provider-account secret in the namespace that contains the 3scale CR. When you deploy a 3scale CR, the operator reads this secret to identify the tenant that the CR links to. For the operator to use this secret, one of the following must be true:
- The 3scale CR specifies the spec.providerAccountRef field as null.
- The 3scale CR omits the spec.providerAccountRef field.
  The threescale-provider-account secret identifies the tenant that the CR links to. The secret must contain a reference to a 3scale instance in the form of a URL and credentials for accessing a tenant in that 3scale instance in the form of a token. For example:
  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
  The threescale-provider-account secret can identify any tenant in any 3scale instance as long as the HTTP connection is available. In other words, a 3scale CR and the 3scale instance that contains the tenant that the CR links to can be in different namespaces, or in different OpenShift clusters.

In the 3scale CR, specify spec.providerAccountRef and set it to the name of a local reference to an OpenShift Secret that identifies the tenant. In the following 3scale DeveloperAccount CR example, mytenant is the secret:

apiVersion: capabilities.3scale.net/v1beta1
kind: DeveloperAccount
metadata:
  name: developeraccount-simple-sample
spec:
  orgName: Ecorp
  providerAccountRef:
    name: mytenant

apiVersion: capabilities.3scale.net/v1beta1
kind: DeveloperAccount
metadata:
  name: developeraccount-simple-sample
spec:
  orgName: Ecorp
  providerAccountRef:
    name: mytenant

Copy to Clipboard

Toggle word wrap

In the secret:

adminURL specifies the URL for a 3scale instance that can be in any namespace.

token specifies credentials for access to one tenant in that 3scale instance. This tenant can be the default tenant or any other tenant in that instance.

Typically, when you deploy a tenant custom resource you create this secret. For example:

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

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

If the 3scale operator cannot identify the tenant that a CR links to, the operator generates an error message.

8.6. Deploying 3scale OpenAPI custom resources
Link kopieren

An OpenAPI custom resource (CR) is one way to import an OpenAPI Specification (OAS) document that you can use for ActiveDocs in the Developer Portal. The OAS is a standard that does not tie you to using one particular programming language for your APIs. Humans and computers can more easily understand the capabilities of the API product without source code access, documentation, or network traffic inspection.

Prerequisites

A user account with administrator privileges for a 3scale 2.11 On-Premises instance.
An OAS document that defines your API.
An understanding of how an OpenAPI CR links to a tenant.

8.6.1. Deploying a 3scale OpenAPI custom resource that imports an OAS document from a secret
Link kopieren

Deploy an OpenAPI custom resource (CR) so that you can create 3scale backends and products.

Note

The operator reads only the content in the secret. The operator does not read the field name in the secret.

Prerequisites

You understand How the 3scale operator identifies the tenant that a custom resource links to.

Procedure

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"

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

Create the secret. For example:

oc create secret generic myoasdoc1 --from-file myoasdoc1.yaml

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

secret/myoasdoc1 created

Copy to Clipboard

Toggle word wrap

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

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

Copy to Clipboard

Toggle word wrap

Create the resource you just defined. For example:
```
oc create -f myopenapicr1.yaml
```
```
$ 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
```
```
openapi.capabilities.3scale.net/myopenapicr1 created
```
Copy to Clipboard Toggle word wrap

8.6.2. Features of 3scale OpenAPI custom resource definitions
Link kopieren

Knowledge of the OpenAPI custom resource definition (CRD) deployment features will help you with configuration of the 3scale product, backend, and the subsequent creation of ActiveDocs for the Developer Portal.

The OAS document can be read from the following:
- The Kubernetes secret
- The URL in both http and https formats
In an OAS document, the info.title setting must not exceed 215 characters. The operator uses this setting to create OpenShift object names, which have length limitations.
Only the first servers[0].url element in a server list is parsed as a private URL. The OpenAPI Specification (OAS) uses its basePath component of servers[0].url element.
The OpenAPI CRD supports a single top level security requirement, however it does not support operational level security.
The OpenAPI CRD supports the apiKey security scheme.

Additional resources

8.6.3. Import rules when defining OpenAPI custom resources
Link kopieren

The import rules specify how the OpenAPI Specification (OAS) works with 3scale when you are setting up an OpenAPI document for your 3scale deployment.

Product name

The default product system name is taken from the info.title field in the OpenAPI document. To override the product name in an OpenAPI document, specify the spec.productSystemName field in an OpenAPI custom resource (CR).

Private base URL

The private base URL is read from the OpenAPI CR servers[0].url field. You can override this by using the spec.privateBaseURL field in your OpenAPI CR.

3scale methods

Each operation that is defined in the imported OpenAPI document translates to one 3scale method at the product level. The method name is read from the operationId field of the operation object.

3scale mapping rules

Each operation that is defined in the imported OpenAPI document translates to one 3scale mapping rule at the product level. Previously existing mapping rules are replaced by those imported with the OpenAPI CR.

In an OpenAPI document, the paths object provides mapping rules for verb and pattern properties. 3scale methods are associated accordingly to the operationId.

The delta value is hard-coded to 1.

By default, Strict matching policy is configured. Matching policy can be switched to Prefix matching using the spec.PrefixMatching field of the OpenAPI CRD.

Authentication

Just one top level security requirement is supported. Operation level security requirements are not supported.

The supported security scheme is apiKey.

The apiKey security scheme type:

credentials location will be read from the OpenAPI document in field of the security scheme object.
Auth user key will be read from the OpenAPI document name field of the security scheme object.

The following is a partial example of OAS 3.0.2 with apiKey security requirement:

openapi: "3.0.2"
security:
  - petstore_api_key: []
components:
  securitySchemes:
    petstore_api_key:
      type: apiKey
      name: api_key
      in: header

openapi: "3.0.2"
security:
  - petstore_api_key: []
components:
  securitySchemes:
    petstore_api_key:
      type: apiKey
      name: api_key
      in: header

Copy to Clipboard

Toggle word wrap

When the OpenAPI document does not specify any security requirements, the following applies:

The product authentication will be configured for apiKey.
credentials location will default to 3scale value As query parameters (GET) or body parameters (POST/PUT/DELETE).
The Auth user key defaults to 3scale value user_key.

3scale Authentication Security can be set using the spec.privateAPIHostHeader and the spec.privateAPISecretToken fields of the OpenAPI CRD.

ActiveDocs

No 3scale ActiveDoc is created.

3scale product policy chain

The 3scale policy chain is the default one 3scale creates.

3scale deployment mode

By default, the configured 3scale deployment mode will be APIcast 3scale managed. However, when the spec.productionPublicBaseURL or the spec.stagingPublicBaseURL, or both fields are present in an OpenAPI CR, the product’s deployment mode is APIcast self-managed.

Example of a OpenAPI CR with custom public base URL:

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"
  productionPublicBaseURL: "https://production.my-gateway.example.com"
  stagingPublicBaseURL: "https://staging.my-gateway.example.com"

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"
  productionPublicBaseURL: "https://production.my-gateway.example.com"
  stagingPublicBaseURL: "https://staging.my-gateway.example.com"

Copy to Clipboard

Toggle word wrap

8.6.4. Deploying a 3scale OpenAPI custom resource that imports an OAS document from a URL
Link kopieren

You can deploy an OpenAPI custom resource that imports an OAS document from a URL that you specify. You can then use this OAS document as the foundation for ActiveDocs for your API in the Developer Portal.

Prerequisites

If you are creating an OpenAPI custom resource that does not link to the default tenant in the 3scale instance that is in the same namespace then the namespace that will contain the OpenAPI CR contains a secret that identifies the tenant that the OpenAPI CR links to. The name of the secret is one of the following:
- threescale-provider-account
- User defined
This secret contains the URL for a 3scale instance and a token that contains credentials for access to one tenant in that 3scale instance.

Procedure

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

Create an OpenAPI custom resource. 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

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

Click Save. It takes a few seconds for the 3scale operator to create the OpenAPI CR.

Verification

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

8.6.5. Additional resources
Link kopieren

8.7. Deploying 3scale ActiveDoc custom resources
Link kopieren

Red Hat 3scale API Management ActiveDocs are based on API definition documents that define RESTful web services that conform to the OpenAPI Specification. An ActiveDoc custom resource (CR) is one way to import an OpenAPI Specification (OAS) document that you can use for ActiveDocs in the Developer Portal. The OAS is a standard that does not tie you to using one particular programming language for your APIs. Humans and computers can more easily understand the capabilities of the API product without source code access, documentation, or network traffic inspection.

Prerequisites

A user account with administrator privileges for a 3scale 2.11 On-Premises instance.
An OAS document that defines your API.
An understanding of how an ActiveDoc CR links to a tenant.

8.7.1. Deploying a 3scale ActiveDoc custom resource that imports an OAS document from a secret
Link kopieren

Deploy an ActiveDoc custom resource (CR) so that you can create 3scale backends and products.

Note

The operator reads only the content in the secret. The operator does not read the field name in the secret. For example, data is structured in key: value pairs where value represents the content of a file and key is the file name. The file name is ignored by the operator in this context of ActiveDoc CRD. The operator reads only the content of the file.

Prerequisites

You understand How the 3scale operator identifies the tenant that a custom resource links to.

Define a secret that contains an OAS (OpenAPI Specification) 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"

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

Procedure

Create the secret. For example:

oc create secret generic myoasdoc1 --from-file myoasdoc1.yaml

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

secret/myoasdoc1 created

Copy to Clipboard

Toggle word wrap

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

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

Create the resource you just defined. For example:
```
oc create -f myactivedoccr1.yaml
```
```
$ 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
```
```
activedoc.capabilities.3scale.net/myactivedoccr1 created
```
Copy to Clipboard Toggle word wrap

Verification

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

8.7.2. Features of 3scale ActiveDoc custom resource definitions
Link kopieren

The ActiveDoc custom resource definition (CRD) concerns product documentation in the OpenAPI document format for developers. Knowledge of the ActiveDoc CRD deployment features help you with the creation of ActiveDocs for the Developer Portal.

An ActiveDoc CR, can read and OpenAPI document from either of the following:
- Secret
- A URL in either http or https format
Optionally, you can link the ActiveDoc CR with a 3scale product using the productSystemName field. The value must be the system_name of the 3scale product’s CR.
You can publish or hide the ActiveDoc document in 3scale using the published field. By default, this is set to be hidden.
You can skip OpenAPI 3.0 validation using the skipSwaggerValidations field. By default, the ActiveDoc CR is validated.

Additional resources

8.7.3. Deploying a 3scale ActiveDoc custom resource that imports an OAS document from a URL
Link kopieren

You can deploy an ActiveDoc custom resource (CR) that imports an OAS (OpenAPI Specification) document from a URL that you specify. You can then use this OAS document as the foundation for ActiveDocs for your API in the Developer Portal.

Prerequisites

You understand How the 3scale operator identifies the tenant that a custom resource links to.

Procedure

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

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

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

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"

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

Click Save. It takes a few seconds for the 3scale operator to create the ActiveDoc CR.

Verification

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

8.7.4. Additional resources
Link kopieren

8.8. Backend custom resources related to capabilities
Link kopieren

Using Openshift Container Platform in your newly created tenant, you will configure backends, their corresponding metrics, methods, and mapping rules. You will also learn about the status of the backend custom resource, and how the backend is linked to a tenant account.

Prerequisites

The same installation requirements as listed in General prerequisites, with the following consideration:

The minimum required parameters from the 3scale account are the Admin Portal URL address, and the access token.

8.8.1. Deploying backend custom resources related to capabilities
Link kopieren

Using Openshift Container Platform in your newly created tenant, you will configure a new backend.

Procedure

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

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>"

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"

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

To save your changes, click Create.
Wait a few seconds to have the backend created both in OpenShift, as well as 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.

8.8.2. Defining backend metrics
Link kopieren

Using Openshift Container Platform with your newly created 3scale tenant, define desired backend metrics in your backend custom resource.

Consider these observations:

metrics map key names will be used as system_name. In the example below: metric01, metric02 and hits.
metrics map key names must be unique among all metrics and methods.
unit and friendlyName are required fields.
If you do not add a hits metric, this metric will be created by the operator.

Procedure

Add backend metrics to the new 3scale backend, as in this example:

apiVersion: capabilities.3scale.net/v1beta1
kind: Backend
metadata:
  name: backend-1
spec:
  name: "My Backend Name"
  privateBaseURL: "https://api.example.com"
  metrics:
    metric01:
      friendlyName: Metric01
      unit: "1"
    metric02:
      friendlyName: Metric02
      unit: "1"
    hits:
      description: Number of API hits
      friendlyName: Hits
      unit: "hit

apiVersion: capabilities.3scale.net/v1beta1
kind: Backend
metadata:
  name: backend-1
spec:
  name: "My Backend Name"
  privateBaseURL: "https://api.example.com"
  metrics:
    metric01:
      friendlyName: Metric01
      unit: "1"
    metric02:
      friendlyName: Metric02
      unit: "1"
    hits:
      description: Number of API hits
      friendlyName: Hits
      unit: "hit

Copy to Clipboard

Toggle word wrap

8.8.3. Defining backend methods
Link kopieren

Using Openshift Container Platform with your newly created 3scale tenant, define desired backend methods in your backend custom resource.

Consider these observations:

methods map key names will be used as system_name. In the example below: Method01 and Method02.
methods map key names must be unique among all metrics and methods.
friendlyName is a required field.

Procedure

Add backend methods to the new 3scale backend, as in this example:

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

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

Copy to Clipboard

Toggle word wrap

8.8.4. Defining backend mapping rules
Link kopieren

Using Openshift Container Platform with your newly created 3scale tenant, define desired backend mapping rules in your backend custom resource.

Consider these observations:

httpMethod, pattern, increment and metricMethodRef are required fields.
metricMethodRef holds a reference to the existing metric or method map key name system_name. In the example below, hits.

Procedure

Add backend mapping rules to the new 3scale backend, as in this example:

apiVersion: capabilities.3scale.net/v1beta1
kind: Backend
metadata:
  name: backend-1
spec:
  name: "My Backend Name"
  privateBaseURL: "https://api.example.com"
  mappingRules:
    - httpMethod: GET
      pattern: "/pets"
      increment: 1
      metricMethodRef: hits
    - httpMethod: GET
      pattern: "/pets/id"
      increment: 1
      metricMethodRef: hits
  metrics:
    hits:
      description: Number of API hits
      friendlyName: Hits
      unit: "hit"

apiVersion: capabilities.3scale.net/v1beta1
kind: Backend
metadata:
  name: backend-1
spec:
  name: "My Backend Name"
  privateBaseURL: "https://api.example.com"
  mappingRules:
    - httpMethod: GET
      pattern: "/pets"
      increment: 1
      metricMethodRef: hits
    - httpMethod: GET
      pattern: "/pets/id"
      increment: 1
      metricMethodRef: hits
  metrics:
    hits:
      description: Number of API hits
      friendlyName: Hits
      unit: "hit"

Copy to Clipboard

Toggle word wrap

8.8.5. Status of the backend custom resource
Link kopieren

The status field shows resource information useful for the end user. It is not intended to be updated manually and it is synchronized on every change of the resource.

These are the attributes of the status field:

backendId: The internal identifier of a 3scale backend.
conditions: Represents the status.Conditions Kubernetes common pattern. It has these types, or states:
- Invalid: The combination of configuration in the BackendSpec is not supported. This is not a transient error, but indicates a state that must be fixed before progress can be made.
- Synced: The backend has been successfully synchronized.
- Failed: An error occurred during synchronization.
observedGeneration: It is a helper field to confirm that the status information is updated with the latest resource specification.

Example of a synchronized resource:

status:
    backendId: 59978
    conditions:
    - lastTransitionTime: "2020-06-22T10:50:33Z"
      status: "False"
      type: Failed
    - lastTransitionTime: "2020-06-22T10:50:33Z"
      status: "False"
      type: Invalid
    - lastTransitionTime: "2020-06-22T10:50:33Z"
      status: "True"
      type: Synced
    observedGeneration: 2

status:
    backendId: 59978
    conditions:
    - lastTransitionTime: "2020-06-22T10:50:33Z"
      status: "False"
      type: Failed
    - lastTransitionTime: "2020-06-22T10:50:33Z"
      status: "False"
      type: Invalid
    - lastTransitionTime: "2020-06-22T10:50:33Z"
      status: "True"
      type: Synced
    observedGeneration: 2

Copy to Clipboard

Toggle word wrap

8.8.6. The backend custom resource linked to a tenant account
Link kopieren

When the 3scale operator finds new 3scale resources, the LookupProviderAccount process starts with the purpose of identifying the tenant owning the resource.

The process checks tenant credential sources. If none is found, an error is raised.

The following steps describe how the process verifies the tenant credential sources:

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

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"

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

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

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

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.

8.9. Product custom resources related to capabilities
Link kopieren

Using Openshift Container Platform in your newly created tenant, you will configure products, and their corresponding metrics, methods, application plans, and mapping rules, as well as define product backend usages and link your product to your tenant account.

Prerequisites

The same installation requirements as listed in General prerequisites, with the following consideration:

The minimum required parameter from the 3scale account is the product name.

8.9.1. Deploying product custom resources related to capabilities
Link kopieren

Using Openshift Container Platform in your newly created tenant, you will configure a new product.

8.9.1.1. Deploying a basic product custom resource
Link kopieren

Procedure

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

Create a 3scale product:

apiVersion: capabilities.3scale.net/v1beta1
kind: Product
metadata:
  name: <your_product_OpenShift_name>
spec:
  name: "<your_product_name>"

apiVersion: capabilities.3scale.net/v1beta1
kind: Product
metadata:
  name: <your_product_OpenShift_name>
spec:
  name: "<your_product_name>"

Copy to Clipboard

Toggle word wrap

For example:

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

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

Copy to Clipboard

Toggle word wrap

To save your changes, click Create.
Wait a few seconds to have the product created both in OpenShift, as well as in your 3scale account. Then, you can perform the following verifications:
1. Confirm that the product has been created in OpenShift, by checking in the 3scale Product Overview page that the Synced condition is marked as True.
2. Go to your 3scale account, and you will see that the product has been created. In the example above, you will see a new product called OperatedProduct 1.

Additionally, you can specify the APIcast deployment mode for each product that you create. There are two alternatives:

8.9.1.2. Deploying a product with APIcast hosted
Link kopieren

Configure your product with APIcast hosted:

apiVersion: capabilities.3scale.net/v1beta1
kind: Product
metadata:
  name: product1
spec:
  name: "OperatedProduct 1"
  deployment:
    apicastHosted: {}

apiVersion: capabilities.3scale.net/v1beta1
kind: Product
metadata:
  name: product1
spec:
  name: "OperatedProduct 1"
  deployment:
    apicastHosted: {}

Copy to Clipboard

Toggle word wrap

8.9.1.3. Deploying a product with APIcast self-managed
Link kopieren

Configure your product with APIcast self-managed. In this case, specify a stagingPublicBaseURL and a productionPublicBaseURL:

apiVersion: capabilities.3scale.net/v1beta1
kind: Product
metadata:
  name: product1
spec:
  name: "OperatedProduct 1"
  deployment:
    apicastSelfManaged:
      stagingPublicBaseURL: "https://staging.api.example.com"
      productionPublicBaseURL: "https://production.api.example.com"

apiVersion: capabilities.3scale.net/v1beta1
kind: Product
metadata:
  name: product1
spec:
  name: "OperatedProduct 1"
  deployment:
    apicastSelfManaged:
      stagingPublicBaseURL: "https://staging.api.example.com"
      productionPublicBaseURL: "https://production.api.example.com"

Copy to Clipboard

Toggle word wrap

8.9.2. Defining product application plans
Link kopieren

Using Openshift Container Platform with your newly created 3scale tenant, define desired application plans in your product custom resource, by using the applicationPlans object.

Consider this observation:

applicationPlans map key names will be used as system_name. In the example below: plan01 and plan02.

Note

setupFee and costMonth are generic 3scale concepts. You must enter details for these when you create an application plan in the 3scale user interface. See Configuring an application plan with your pricing rules.

Procedure

Add application plans to the new 3scale product, as in this example:

apiVersion: capabilities.3scale.net/v1beta1
kind: Product
metadata:
  name: product1
spec:
  name: "OperatedProduct 1"
  applicationPlans:
    plan01:
      name: "My Plan 01"
      setupFee: "14.56"
    plan02:
      name: "My Plan 02"
      trialPeriod: 3
      costMonth: 3

apiVersion: capabilities.3scale.net/v1beta1
kind: Product
metadata:
  name: product1
spec:
  name: "OperatedProduct 1"
  applicationPlans:
    plan01:
      name: "My Plan 01"
      setupFee: "14.56"
    plan02:
      name: "My Plan 02"
      trialPeriod: 3
      costMonth: 3

Copy to Clipboard

Toggle word wrap

8.9.3. Defining limits for product application plans
Link kopieren

Using Openshift Container Platform with your newly created 3scale tenant, define desired limits for your product application plans, by using the applicationPlans.limits list.

Consider these observations:

period, value and metricMethodRef are required fields.
The metricMethodRef reference can be either a product or a backend reference. Use the optional backend field to reference the owner of the backend metric.

Procedure

Define limits for the application plans of an 3scale product, as in this example:

apiVersion: capabilities.3scale.net/v1beta1
kind: Product
metadata:
  name: product1
spec:
  name: "OperatedProduct 1"
  metrics:
    hits:
      description: Number of API hits
      friendlyName: Hits
      unit: "hit"
  applicationPlans:
    plan01:
      name: "My Plan 01"
      limits:
        - period: month
          value: 300
          metricMethodRef:
            systemName: hits
            backend: backendA
        - period: week
          value: 100
          metricMethodRef:
            systemName: hits

apiVersion: capabilities.3scale.net/v1beta1
kind: Product
metadata:
  name: product1
spec:
  name: "OperatedProduct 1"
  metrics:
    hits:
      description: Number of API hits
      friendlyName: Hits
      unit: "hit"
  applicationPlans:
    plan01:
      name: "My Plan 01"
      limits:
        - period: month
          value: 300
          metricMethodRef:
            systemName: hits
            backend: backendA
        - period: week
          value: 100
          metricMethodRef:
            systemName: hits

Copy to Clipboard

Toggle word wrap

8.9.4. Defining pricing rules for product application plans
Link kopieren

Using Openshift Container Platform with your newly created 3scale tenant, define desired pricing rules for your product application plans, by using the applicationPlans.pricingRules list.

Consider these observations:

from, to, pricePerUnit and metricMethodRef are required fields.
from and to will be validated. For any rule, values of from less than to and overlapping ranges for the same metric are not allowed.
The metricMethodRef reference can be either a product or a backend reference. Use the optional backend field to reference the owner of the backend metric.

Procedure

Define pricing rules for the application plans of an 3scale product, as in this example:

apiVersion: capabilities.3scale.net/v1beta1
kind: Product
metadata:
  name: product1
spec:
  name: "OperatedProduct 1"
  metrics:
    hits:
      description: Number of API hits
      friendlyName: Hits
      unit: "hit"
  applicationPlans:
    plan01:
      name: "My Plan 01"
      pricingRules:
        - from: 1
          to: 100
          pricePerUnit: "15.45"
          metricMethodRef:
            systemName: hits
        - from: 1
          to: 300
          pricePerUnit: "15.45"
          metricMethodRef:
            systemName: hits
            backend: backendA

apiVersion: capabilities.3scale.net/v1beta1
kind: Product
metadata:
  name: product1
spec:
  name: "OperatedProduct 1"
  metrics:
    hits:
      description: Number of API hits
      friendlyName: Hits
      unit: "hit"
  applicationPlans:
    plan01:
      name: "My Plan 01"
      pricingRules:
        - from: 1
          to: 100
          pricePerUnit: "15.45"
          metricMethodRef:
            systemName: hits
        - from: 1
          to: 300
          pricePerUnit: "15.45"
          metricMethodRef:
            systemName: hits
            backend: backendA

Copy to Clipboard

Toggle word wrap

8.9.5. Defining product authentication using OpenID Connect
Link kopieren

You can deploy a Product custom resource for a 3scale product that uses OpenID Connect (OIDC) for authentication for any OAuth 2.0 flow. 3scale integrates with third-party Identity Providers (IdP), such as OpenID Connect, to authenticate API requests. For more information about OpenID Connect, see OpenID Connect integration. After integration with a third-party IdP, you will have two types of data to include with the product custom resource:

issuerType: The keycloak value when using Red Hat Single Sign-On (RH-SSO) and the rest value when integrating with the third-party IdP.
issuerEndpoint: A URL with the necessary credentials in it.

Prerequisites

You must configure RH-SSO. See Configuring Red Hat Single Sign-On.
You must Configure HTTP integration with third-party Identity Providers.

Note

The credentials CLIENT_ID and CLIENT_CREDENTIALS provided in issuerEndpoint must have sufficient permissions to manage other clients in the realm.

Procedure

Determine the endpoint issuerEndpoint, which defines the location of your OpenID Provider and use this format in the product custom resource:
```
https://<client_id>:<client_secret>@<host>:<port_number>/auth/realms/<realm_name>`
```
```
https://<client_id>:<client_secret>@<host>:<port_number>/auth/realms/<realm_name>`
```
Copy to Clipboard Toggle word wrap

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"

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

Create the resource you just defined. For example:
```
oc create -f product1.yaml
```
```
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
```
```
product.capabilities.3scale.net/product1 created
```
Copy to Clipboard Toggle word wrap

Additional resources

Product CRD Reference.

8.9.6. Defining product metrics
Link kopieren

Using Openshift Container Platform with your newly created 3scale tenant, define desired metrics in your product custom resource, by using the metrics object.

Consider these observations:

metrics map key names will be used as system_name. In the example below: metric01 and hits.
metrics map key names must be unique among all metrics and methods.
unit and friendlyName are required fields.
If you do not add a hits metric, it will be created by the operator.

Procedure

Add product metrics to the new 3scale backend, as in this example:

apiVersion: capabilities.3scale.net/v1beta1
kind: Product
metadata:
  name: product1
spec:
  name: "OperatedProduct 1"
  metrics:
    metric01:
      friendlyName: Metric01
      unit: "1"
    hits:
      description: Number of API hits
      friendlyName: Hits
      unit: "hit"

apiVersion: capabilities.3scale.net/v1beta1
kind: Product
metadata:
  name: product1
spec:
  name: "OperatedProduct 1"
  metrics:
    metric01:
      friendlyName: Metric01
      unit: "1"
    hits:
      description: Number of API hits
      friendlyName: Hits
      unit: "hit"

Copy to Clipboard

Toggle word wrap

8.9.7. Defining product methods
Link kopieren

Using Openshift Container Platform with your newly created 3scale tenant, define desired methods in your product custom resource, by using the methods object.

Consider these observations:

methods map key names will be used as system_name. In the example below: Method01 and Method02.
methods map key names must be unique among all metrics and methods.
friendlyName is a required field.

Procedure

Add methods to the new 3scale product, as in this example:

apiVersion: capabilities.3scale.net/v1beta1
kind: Product
metadata:
  name: product1
spec:
  name: "OperatedProduct 1"
  methods:
    method01:
      friendlyName: Method01
    method02:
      friendlyName: Method02

apiVersion: capabilities.3scale.net/v1beta1
kind: Product
metadata:
  name: product1
spec:
  name: "OperatedProduct 1"
  methods:
    method01:
      friendlyName: Method01
    method02:
      friendlyName: Method02

Copy to Clipboard

Toggle word wrap

8.9.8. Defining product mapping rules
Link kopieren

Using Openshift Container Platform with your newly created 3scale tenant, define desired mapping rules in your product custom resource, by using the mappingRules object.

Consider these observations:

httpMethod, pattern, increment and metricMethodRef are required fields.
metricMethodRef holds a reference to the existing metric or method map key name system_name. In the example below, hits.

Procedure

Add product mapping rules to the new 3scale backend, as in this example:

apiVersion: capabilities.3scale.net/v1beta1
kind: Product
metadata:
  name: product1
spec:
  name: "OperatedProduct 1"
  metrics:
    hits:
      description: Number of API hits
      friendlyName: Hits
      unit: "hit"
  methods:
    method01:
      friendlyName: Method01
  mappingRules:
    - httpMethod: GET
      pattern: "/pets"
      increment: 1
      metricMethodRef: hits
    - httpMethod: GET
      pattern: "/cars"
      increment: 1
      metricMethodRef: method01

apiVersion: capabilities.3scale.net/v1beta1
kind: Product
metadata:
  name: product1
spec:
  name: "OperatedProduct 1"
  metrics:
    hits:
      description: Number of API hits
      friendlyName: Hits
      unit: "hit"
  methods:
    method01:
      friendlyName: Method01
  mappingRules:
    - httpMethod: GET
      pattern: "/pets"
      increment: 1
      metricMethodRef: hits
    - httpMethod: GET
      pattern: "/cars"
      increment: 1
      metricMethodRef: method01

Copy to Clipboard

Toggle word wrap

8.9.9. Defining product backend usage
Link kopieren

Using Openshift Container Platform with your newly created 3scale tenant, define desired backends to be added to a product declaratively, by applying the backendUsages object.

Consider these observations:

path is a required field.
backendUsages map key names are references to the backend’s system_name. In the example below: backendA and backendB.

Procedure

Add a backend to a product to define its usage declaratively, as in this example:

apiVersion: capabilities.3scale.net/v1beta1
kind: Product
metadata:
  name: product1
spec:
  name: "OperatedProduct 1"
  backendUsages:
    backendA:
      path: /A
    backendB:
      path: /B

apiVersion: capabilities.3scale.net/v1beta1
kind: Product
metadata:
  name: product1
spec:
  name: "OperatedProduct 1"
  backendUsages:
    backendA:
      path: /A
    backendB:
      path: /B

Copy to Clipboard

Toggle word wrap

8.9.10. Configuring gateway responses in 3scale Product custom resources
Link kopieren

As a 3scale administrator, you can configure a Product custom resource to specify the gateway responses to requests to the exposed API for that API product. After you deploy the CR, 3scale ensures that the gateway returns the responses and error messages you specify.

In a Product CR, the gatewayResponse object contains the responses that you want the gateway to return.

Procedure

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"

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

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
```
```
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
```
```
product.capabilities.3scale.net/product1 created
```
Copy to Clipboard Toggle word wrap

8.9.11. Configuring policy chains in 3scale Product custom resources
Link kopieren

As a 3scale administrator, you can configure a Product custom resource to specify the policy chain that you want to apply to that API product. After you deploy the CR, 3scale applies the configured policies to requests to the product’s upstream, exposed API.

Procedure

In a new or deployed Product CR, configure one or more policies in the policies object. For example:
```
  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
```
```
  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
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 custom resource links to. To identify policy names, see the documentation for the relevant policy in Administering the API Gateway, APIcast standard policies.
- 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
```
```
3scale policies export api-provider-account-one my-api-product-one
```
Copy to Clipboard Toggle word wrap
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
```
```
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
```
```
product.capabilities.3scale.net/product1 created
```
Copy to Clipboard Toggle word wrap

8.9.12. Status of the product custom resource
Link kopieren

The status field shows resource information useful for the end user. It is not intended to be updated manually and it is synchronized on every change of the resource.

These are the attributes of the status field:

productId: The internal identifier of a 3scale product.
conditions: Represents the status.Conditions Kubernetes common pattern. It has these types, or states:
- Failed: An error occurred during synchronization. The operation will retry.
- Synced: The product has been successfully synchronized.
- Invalid: Invalid object. This is not a transient error, but it reports about an invalid specification and it should be changed. The operator will not retry.
- Orphan: The specification references a resource that does not exist. The operator will retry.
observedGeneration: Confirms that the status information is updated with the latest resource specification.
state: The 3scale product internal state read from the 3scale API.
providerAccountHost: The 3scale provider account URL to which the backend is synchronized.

Example of a synchronized resource:

status:
  conditions:
  - lastTransitionTime: "2020-10-21T18:07:01Z"
    status: "False"
    type: Failed
  - lastTransitionTime: "2020-10-21T18:06:54Z"
    status: "False"
    type: Invalid
  - lastTransitionTime: "2020-10-21T18:07:01Z"
    status: "False"
    type: Orphan
  - lastTransitionTime: "2020-10-21T18:07:01Z"
    status: "True"
    type: Synced
  observedGeneration: 1
  productId: 2555417872138
  providerAccountHost: https://3scale-admin.example.com
  state: incomplete

status:
  conditions:
  - lastTransitionTime: "2020-10-21T18:07:01Z"
    status: "False"
    type: Failed
  - lastTransitionTime: "2020-10-21T18:06:54Z"
    status: "False"
    type: Invalid
  - lastTransitionTime: "2020-10-21T18:07:01Z"
    status: "False"
    type: Orphan
  - lastTransitionTime: "2020-10-21T18:07:01Z"
    status: "True"
    type: Synced
  observedGeneration: 1
  productId: 2555417872138
  providerAccountHost: https://3scale-admin.example.com
  state: incomplete

Copy to Clipboard

Toggle word wrap

8.9.13. The product custom resource linked to a tenant account
Link kopieren

When the 3scale operator finds new 3scale resources, the LookupProviderAccount process starts with the purpose of identifying the tenant owning the resource.

The process checks tenant credential sources. If none is found, an error is raised.

The following steps describe how the process verifies the tenant credential sources:

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

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"

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

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

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

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.

8.10. Deploying 3scale CustomPolicyDefinition custom resources
Link kopieren

You can use a CustomPolicyDefinition CRD to configure your custom policy in a 3scale product from the Admin Portal.

When the 3scale operator finds a new CustomPolicyDefinition CR, the operator identifies the tenant that owns the CR as described in How the 3scale operator identifies the tenant that a custom resource links to.

Prerequisites

The 3scale operator is installed.
You have a custom policy file ready to be deployed.
You have already injected the custom policy in the gateway.

Procedure

Define a CustomPolicyDefinition custom resource and save it in, for example, the my-apicast-custom-policy-definition.yaml file:

apiVersion: capabilities.3scale.net/v1beta1
kind: CustomPolicyDefinition
metadata:
  name: custompolicydefinition-sample
spec:
  version: "0.1"
  name: "APIcast Example Policy"
  schema:
    name: "APIcast Example Policy"
    version: "0.1"
    $schema: "http://apicast.io/policy-v1/schema#manifest#"
    summary: "This is just an example."
    configuration:
      type: object
      properties: {}

apiVersion: capabilities.3scale.net/v1beta1
kind: CustomPolicyDefinition
metadata:
  name: custompolicydefinition-sample
spec:
  version: "0.1"
  name: "APIcast Example Policy"
  schema:
    name: "APIcast Example Policy"
    version: "0.1"
    $schema: "http://apicast.io/policy-v1/schema#manifest#"
    summary: "This is just an example."
    configuration:
      type: object
      properties: {}

Copy to Clipboard

Toggle word wrap

Deploy the CustomPolicyDefinition CR:

oc create -f my-apicast-custom-policy-definition.yaml

oc create -f my-apicast-custom-policy-definition.yaml

Copy to Clipboard

Toggle word wrap

Additional resources

CustomPolicyDefinition CRD Reference.

8.11. Deploying a tenant custom resource
Link kopieren

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:

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>
  Copy to Clipboard Toggle word wrap
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>
```
```
oc create secret generic ecorp-admin-secret --from-literal=admin_password=<admin password value>
```
Copy to Clipboard Toggle word wrap
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}"
  Copy to Clipboard Toggle word wrap

Procedure

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

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

Copy to Clipboard

Toggle word wrap

Create the tenant resource:
```
oc create -f <yaml-name>
```
```
oc create -f <yaml-name>
```
Copy to Clipboard Toggle word wrap
- 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"

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

Copy to Clipboard

Toggle word wrap

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

8.12. Managing 3scale developers by deploying custom resources
Link kopieren

As a 3scale administrator, you can use custom resources (CRs) to deploy developer accounts that group together individual developer users. These accounts let you organize and manage developer access to 3scale-managed APIs in the Developer Portal.

A tenant can contain any number of developer accounts and each developer account links to exactly one tenant. A developer account can contain any number of developer users and each developer user links to exactly one developer account. The tenant plan determines any limits on how many developer accounts you can create and how many developer users can be grouped in each developer account.

To use developer custom resources, 3scale must have been installed by the 3scale operator. You can deploy developer custom resources in only the namespace that contains the 3scale operator. Deployment of developer custom resources is an alternative to managing developers by using the 3scale Admin Portal or the 3scale internal API.

Important

When you create developer accounts or developer users by deploying custom resources you cannot use the Admin Portal or the internal 3scale API to update those developer accounts or developer users. It is important to be aware of this because after you deploy a developer CR, the Admin Portal displays the new developer account or new developer user in its Accounts page. If you try to use the Admin Portal or API to update a developer account or developer user that was deployed with a CR, the 3scale operator reverts the changes to reflect the deployed CR. This is a limitation that is expected to be removed in a future release. You can, however, use the Admin Portal or API to delete a developer account or developer user that you created by deploying a CR.

8.12.1. Prerequisites
Link kopieren

3scale was installed by the 3scale operator.
Access token with read and write permissions in the Account Management API scope, which provides administrator privileges for 3scale.

8.12.2. Managing 3scale developer accounts by deploying DeveloperAccount custom resources
Link kopieren

When you use the 3scale operator to install 3scale you can deploy DeveloperAccount and DeveloperUser custom resources (CRs). These CRs let you create and update accounts for developer access to 3scale-managed APIs in the Developer Portal.

To deploy a new DeveloperAccount CR, you must also deploy a DeveloperUser CR for a user who has the admin role. The procedure provided here is for deploying a new DeveloperAccount CR. After you deploy a DeveloperAccount CR, the procedure for updating or deleting it is the same as for any other CR.

You can deploy CRs only in the namespace that contains the 3scale operator.

Prerequisites

An understanding of how the 3scale operator identifies the tenant that a custom resource links to.
If you are creating a DeveloperAccount custom resource that does not link to the default tenant in the 3scale instance that is in the same namespace then the namespace that will contain the DeveloperAccount CR contains a secret that identifies the tenant that the DeveloperAccount CR links to. The name of the secret is one of the following:
- threescale-provider-account
- User defined
This secret contains the URL for a 3scale instance and a token that contains credentials for access to one tenant in that 3scale instance.
You have the user name, password, and email address for at least one developer user who will have the admin role in the new DeveloperAccount CR.

Procedure

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"
```
```
apiVersion: v1
kind: Secret
metadata:
  name: myusername01
stringData:
  password: "123456"
```
Copy to Clipboard Toggle word wrap
Create the secret. For example:
```
oc create -f myusername01.yaml
```
```
oc create -f myusername01.yaml
```
Copy to Clipboard Toggle word wrap
For the given example, the output would be:
```
secret/myusername01 created
```
```
secret/myusername01 created
```
Copy to Clipboard Toggle word wrap
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
```
```
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.
Create the resource you just defined. For example:
```
oc create -f developeruser01.yaml
```
```
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
```
```
developeruser.capabilities.3scale.net/developeruser01 created
```
Copy to Clipboard Toggle word wrap

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

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

Copy to Clipboard

Toggle word wrap

Create the resource you just defined. For example:

oc create -f developeraccount01.yaml

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

developeraccount.capabilities.3scale.net/developeraccount01 created

Copy to Clipboard

Toggle word wrap

Next steps

It takes a few seconds for the 3scale operator to update the 3scale configuration to reflect new or updated custom resources. To check whether the operator is propagating custom resource information successfully, check the DeveloperAccount custom resource status field or run the oc wait command, for example:

oc wait --for=condition=Ready --timeout=30s developeraccount/developeraccount1

oc wait --for=condition=Ready --timeout=30s developeraccount/developeraccount1

Copy to Clipboard

Toggle word wrap

In case of failure, the custom resource’s status field indicates if the error is transient or permanent, and provides an error message that helps fix the problem.

Notify any new developer users that they can log in to the Developer Portal. You might also need to communicate their log-in credentials.

You can update or delete a deployed DeveloperAccount custom resource in the same way that you update or delete any other custom resource. However, when you delete a DeveloperAccount CR, the 3scale operator does not actually delete it. If you try to deploy a new DeveloperAccount CR that has the same name as a DeveloperAccount CR that you deleted, you receive a message that a DeveloperAccount CR with that name already exists. You must specify a different name for the new DeveloperAccount CR.

8.12.3. Managing 3scale developer users by deploying DeveloperUser custom resources
Link kopieren

When you use the 3scale operator to install 3scale you can deploy DeveloperUser custom resources (CRs) for managing developer access to 3scale-managed APIs in the Developer Portal. The procedure provided here is for deploying a new DeveloperUser CR. After you deploy a DeveloperUser CR, the procedure for updating or deleting it is the same as for any other CR.

You can deploy CRs only in the namespace that contains the 3scale operator.

Prerequisites

An understanding of how the 3scale operator identifies the tenant that a custom resource links to.
There is at least one deployed DeveloperAccount custom resource that contains at least one deployed DeveloperUser CR for a user who has the admin role. If you are creating a DeveloperUser custom resource that does not link to the default tenant in the 3scale instance that is in the same namespace then the namespace that will contain the DeveloperUser CR contains a secret that identifies the tenant that the DeveloperUser CR links to. The name of the secret is one of the following:
- threescale-provider-account
- User defined
This secret contains the URL for a 3scale instance and a token that contains credentials for access to one tenant in that 3scale instance.
For a new DeveloperUser custom resource, you have that developer’s user name, password, and email address.

Procedure

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. For example, the myusername02.yaml file might contain:
```
apiVersion: v1
kind: Secret
metadata:
  name: myusername02
stringData:
  password: "987654321"
```
```
apiVersion: v1
kind: Secret
metadata:
  name: myusername02
stringData:
  password: "987654321"
```
Copy to Clipboard Toggle word wrap
Create the secret. For example:
```
oc create -f myusername02.yaml
```
```
oc create -f myusername02.yaml
```
Copy to Clipboard Toggle word wrap
For the given example, the output would be:
```
secret/myusername02 created
```
```
secret/myusername02 created
```
Copy to Clipboard Toggle word wrap

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

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 user name (specified in the metadata.name field), the user name, 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.

Create the resource you just defined. For example:
```
oc create -f developefuser02.yaml
```
```
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
```
```
developeruser.capabilities.3scale.net/developeruser02 created
```
Copy to Clipboard Toggle word wrap

Next steps

It takes a few seconds for the 3scale operator to update the 3scale configuration to reflect new or updated custom resources. To check whether the operator is propagating custom resource information successfully, check the DeveloperUser custom resource status field or run the oc wait command, for example:

oc wait --for=condition=Ready --timeout=30s developeruser/developeruser02

oc wait --for=condition=Ready --timeout=30s developeruser/developeruser02

Copy to Clipboard

Toggle word wrap

In case of failure, the custom resource’s status field indicates if the error is transient or permanent, and provides an error message that helps fix the problem.

Notify any new developer users that they can log in to the Developer Portal. You might also need to communicate their log-in credentials.

You can update or delete a deployed DeveloperUser custom resource in the same way that you update or delete any other custom resource. However, when you delete a DeveloperUser CR, the 3scale operator does not actually delete it. If you try to deploy a new DeveloperUser CR that has the same account name, user name, or email as a DeveloperUser CR that you deleted, you receive a message that the DeveloperUser CR already exists. You must specify a different developer user account name, user name, or email for the new DeveloperUser CR.

8.13. Limitations of 3scale operator capabilities
Link kopieren

In Red Hat 3scale API Management 2.11, 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.
Deletion of DeveloperAccount or DeveloperUser custom resources is not reconciled. While the operator receives the deletion event, the operator does not act on the event. The developer account or developer user remains. If you try to create a new developer account or developer user with the same account name, username or email address as a custom resource that you deleted, you receive an error that the account already exists. You must specify different parameters to create the account.
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.

8.14. Additional resources
Link kopieren

For more information, check the following guides:

Dieser Inhalt ist in der von Ihnen ausgewählten Sprache nicht verfügbar.

8.1. General prerequisites
Link kopieren

8.2. Application capabilities via the 3scale operator
Link kopieren

8.3. Deploying your first 3scale product and backend
Link kopieren

8.4. Promoting a product’s APIcast configuration
Link kopieren

8.5. How the 3scale operator identifies the tenant that a custom resource links to
Link kopieren

8.6. Deploying 3scale OpenAPI custom resources
Link kopieren

8.6.1. Deploying a 3scale OpenAPI custom resource that imports an OAS document from a secret
Link kopieren

8.6.2. Features of 3scale OpenAPI custom resource definitions
Link kopieren

8.6.3. Import rules when defining OpenAPI custom resources
Link kopieren

8.6.4. Deploying a 3scale OpenAPI custom resource that imports an OAS document from a URL
Link kopieren

8.6.5. Additional resources
Link kopieren

8.7. Deploying 3scale ActiveDoc custom resources
Link kopieren

8.7.1. Deploying a 3scale ActiveDoc custom resource that imports an OAS document from a secret
Link kopieren

8.7.2. Features of 3scale ActiveDoc custom resource definitions
Link kopieren

8.7.3. Deploying a 3scale ActiveDoc custom resource that imports an OAS document from a URL
Link kopieren

8.7.4. Additional resources
Link kopieren

8.10. Deploying 3scale CustomPolicyDefinition custom resources
Link kopieren

8.11. Deploying a tenant custom resource
Link kopieren

8.12. Managing 3scale developers by deploying custom resources
Link kopieren

8.12.1. Prerequisites
Link kopieren

8.12.2. Managing 3scale developer accounts by deploying DeveloperAccount custom resources
Link kopieren

8.12.3. Managing 3scale developer users by deploying DeveloperUser custom resources
Link kopieren

8.13. Limitations of 3scale operator capabilities
Link kopieren

8.14. Additional resources
Link kopieren

Lernen

Testen, kaufen und verkaufen

Communitys

Über Red Hat Dokumentation

Mehr Inklusion in Open Source

Über Red Hat

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

Dieser Inhalt ist in der von Ihnen ausgewählten Sprache nicht verfügbar.

Chapter 8. Using the 3scale operator to configure and provision 3scale

8.1. General prerequisitesLink kopierenLink in die Zwischenablage kopiert!

8.2. Application capabilities via the 3scale operatorLink kopierenLink in die Zwischenablage kopiert!

8.3. Deploying your first 3scale product and backendLink kopierenLink in die Zwischenablage kopiert!

8.4. Promoting a product’s APIcast configurationLink kopierenLink in die Zwischenablage kopiert!

8.5. How the 3scale operator identifies the tenant that a custom resource links toLink kopierenLink in die Zwischenablage kopiert!

8.6. Deploying 3scale OpenAPI custom resourcesLink kopierenLink in die Zwischenablage kopiert!

8.6.1. Deploying a 3scale OpenAPI custom resource that imports an OAS document from a secretLink kopierenLink in die Zwischenablage kopiert!

8.6.2. Features of 3scale OpenAPI custom resource definitionsLink kopierenLink in die Zwischenablage kopiert!

8.6.3. Import rules when defining OpenAPI custom resourcesLink kopierenLink in die Zwischenablage kopiert!

8.6.4. Deploying a 3scale OpenAPI custom resource that imports an OAS document from a URLLink kopierenLink in die Zwischenablage kopiert!

8.6.5. Additional resourcesLink kopierenLink in die Zwischenablage kopiert!

8.7. Deploying 3scale ActiveDoc custom resourcesLink kopierenLink in die Zwischenablage kopiert!

8.7.1. Deploying a 3scale ActiveDoc custom resource that imports an OAS document from a secretLink kopierenLink in die Zwischenablage kopiert!

8.7.2. Features of 3scale ActiveDoc custom resource definitionsLink kopierenLink in die Zwischenablage kopiert!

8.7.3. Deploying a 3scale ActiveDoc custom resource that imports an OAS document from a URLLink kopierenLink in die Zwischenablage kopiert!

8.7.4. Additional resourcesLink kopierenLink in die Zwischenablage kopiert!

8.8. Backend custom resources related to capabilitiesLink kopierenLink in die Zwischenablage kopiert!

8.8.1. Deploying backend custom resources related to capabilitiesLink kopierenLink in die Zwischenablage kopiert!

8.8.2. Defining backend metricsLink kopierenLink in die Zwischenablage kopiert!

8.8.3. Defining backend methodsLink kopierenLink in die Zwischenablage kopiert!

8.8.4. Defining backend mapping rulesLink kopierenLink in die Zwischenablage kopiert!

8.8.5. Status of the backend custom resourceLink kopierenLink in die Zwischenablage kopiert!

8.8.6. The backend custom resource linked to a tenant accountLink kopierenLink in die Zwischenablage kopiert!

8.9. Product custom resources related to capabilitiesLink kopierenLink in die Zwischenablage kopiert!

8.9.1. Deploying product custom resources related to capabilitiesLink kopierenLink in die Zwischenablage kopiert!

8.9.1.1. Deploying a basic product custom resourceLink kopierenLink in die Zwischenablage kopiert!

8.9.1.2. Deploying a product with APIcast hostedLink kopierenLink in die Zwischenablage kopiert!

8.9.1.3. Deploying a product with APIcast self-managedLink kopierenLink in die Zwischenablage kopiert!

8.9.2. Defining product application plansLink kopierenLink in die Zwischenablage kopiert!

8.9.3. Defining limits for product application plansLink kopierenLink in die Zwischenablage kopiert!

8.9.4. Defining pricing rules for product application plansLink kopierenLink in die Zwischenablage kopiert!

8.9.5. Defining product authentication using OpenID ConnectLink kopierenLink in die Zwischenablage kopiert!

8.9.6. Defining product metricsLink kopierenLink in die Zwischenablage kopiert!

8.9.7. Defining product methodsLink kopierenLink in die Zwischenablage kopiert!

8.9.8. Defining product mapping rulesLink kopierenLink in die Zwischenablage kopiert!

8.9.9. Defining product backend usageLink kopierenLink in die Zwischenablage kopiert!

8.9.10. Configuring gateway responses in 3scale Product custom resourcesLink kopierenLink in die Zwischenablage kopiert!

8.9.11. Configuring policy chains in 3scale Product custom resourcesLink kopierenLink in die Zwischenablage kopiert!

8.9.12. Status of the product custom resourceLink kopierenLink in die Zwischenablage kopiert!

8.9.13. The product custom resource linked to a tenant accountLink kopierenLink in die Zwischenablage kopiert!

8.10. Deploying 3scale CustomPolicyDefinition custom resourcesLink kopierenLink in die Zwischenablage kopiert!

8.11. Deploying a tenant custom resourceLink kopierenLink in die Zwischenablage kopiert!

8.12. Managing 3scale developers by deploying custom resourcesLink kopierenLink in die Zwischenablage kopiert!

8.12.1. PrerequisitesLink kopierenLink in die Zwischenablage kopiert!

8.12.2. Managing 3scale developer accounts by deploying DeveloperAccount custom resourcesLink kopierenLink in die Zwischenablage kopiert!

8.12.3. Managing 3scale developer users by deploying DeveloperUser custom resourcesLink kopierenLink in die Zwischenablage kopiert!

8.13. Limitations of 3scale operator capabilitiesLink kopierenLink in die Zwischenablage kopiert!

8.14. Additional resourcesLink kopierenLink in die Zwischenablage kopiert!

Lernen

Testen, kaufen und verkaufen

Communitys

Über Red Hat Dokumentation

Mehr Inklusion in Open Source

Über Red Hat

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

8.1. General prerequisites
Link kopieren

8.2. Application capabilities via the 3scale operator
Link kopieren

8.3. Deploying your first 3scale product and backend
Link kopieren

8.4. Promoting a product’s APIcast configuration
Link kopieren

8.5. How the 3scale operator identifies the tenant that a custom resource links to
Link kopieren

8.6. Deploying 3scale OpenAPI custom resources
Link kopieren

8.6.1. Deploying a 3scale OpenAPI custom resource that imports an OAS document from a secret
Link kopieren

8.6.2. Features of 3scale OpenAPI custom resource definitions
Link kopieren

8.6.3. Import rules when defining OpenAPI custom resources
Link kopieren

8.6.4. Deploying a 3scale OpenAPI custom resource that imports an OAS document from a URL
Link kopieren

8.6.5. Additional resources
Link kopieren

8.7. Deploying 3scale ActiveDoc custom resources
Link kopieren

8.7.1. Deploying a 3scale ActiveDoc custom resource that imports an OAS document from a secret
Link kopieren

8.7.2. Features of 3scale ActiveDoc custom resource definitions
Link kopieren

8.7.3. Deploying a 3scale ActiveDoc custom resource that imports an OAS document from a URL
Link kopieren

8.7.4. Additional resources
Link kopieren

8.8. Backend custom resources related to capabilities
Link kopieren

8.8.1. Deploying backend custom resources related to capabilities
Link kopieren

8.8.2. Defining backend metrics
Link kopieren

8.8.3. Defining backend methods
Link kopieren

8.8.4. Defining backend mapping rules
Link kopieren

8.8.5. Status of the backend custom resource
Link kopieren

8.8.6. The backend custom resource linked to a tenant account
Link kopieren

8.9. Product custom resources related to capabilities
Link kopieren

8.9.1. Deploying product custom resources related to capabilities
Link kopieren

8.9.1.1. Deploying a basic product custom resource
Link kopieren

8.9.1.2. Deploying a product with APIcast hosted
Link kopieren

8.9.1.3. Deploying a product with APIcast self-managed
Link kopieren

8.9.2. Defining product application plans
Link kopieren

8.9.3. Defining limits for product application plans
Link kopieren

8.9.4. Defining pricing rules for product application plans
Link kopieren

8.9.5. Defining product authentication using OpenID Connect
Link kopieren

8.9.6. Defining product metrics
Link kopieren

8.9.7. Defining product methods
Link kopieren

8.9.8. Defining product mapping rules
Link kopieren

8.9.9. Defining product backend usage
Link kopieren

8.9.10. Configuring gateway responses in 3scale Product custom resources
Link kopieren

8.9.11. Configuring policy chains in 3scale Product custom resources
Link kopieren

8.9.12. Status of the product custom resource
Link kopieren

8.9.13. The product custom resource linked to a tenant account
Link kopieren

8.10. Deploying 3scale CustomPolicyDefinition custom resources
Link kopieren

8.11. Deploying a tenant custom resource
Link kopieren

8.12. Managing 3scale developers by deploying custom resources
Link kopieren

8.12.1. Prerequisites
Link kopieren

8.12.2. Managing 3scale developer accounts by deploying DeveloperAccount custom resources
Link kopieren

8.12.3. Managing 3scale developer users by deploying DeveloperUser custom resources
Link kopieren

8.13. Limitations of 3scale operator capabilities
Link kopieren

8.14. Additional resources
Link kopieren