Chapter 8. Using the 3scale operator to configure and provision 3scale
As a 3scale administrator, you can use the 3scale operator to configure 3scale services and provision 3scale resources. You use the operator in the OpenShift Container Platform (OCP) user interface. Using the operator is an alternative to configuring and provisioning 3scale in the Admin Portal or by using the 3scale internal API.
When you use the 3scale operator to configure a service or provision a resource the only way to update that service or resource is to update its custom resource (CR). While new services and resources appear in the Admin Portal, you cannot update the service or resource in the Admin Portal or by using the internal 3scale API. If you try to, the operator reverts updates and the CR remains as it was.
3scale operator for capabilities is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.
This chapter includes details about how operator application capabilities work and how to use the operator to deploy custom resources:
Additionally, there is information about the limitations of capabilities when using the 3scale operator.
8.1. General prerequisites
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
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.
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
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
andtoken=123456
.oc create secret generic threescale-provider-account --from-literal=adminURL=https://3scale-admin.example.com --from-literal=token=123456
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"
- 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
Configure the 3scale product:
Create a product with all the default settings applied to the previously created backend:
apiVersion: capabilities.3scale.net/v1beta1 kind: Product metadata: name: product1 spec: name: "OperatedProduct 1" systemName: "operatedproduct1" backendUsages: backend1: path: /
- Once you create the file, the operator will confirm if the step was successful.
- For more details about the fields of the Product custom resource and possible values, see the Product CRD Reference.
Create a custom resource:
oc create -f product1.yaml
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
8.4. Promoting a product’s APIcast configuration
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.
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
To promote the APIcast configuration to the production environment, set the optional field
spec.production
totrue
:apiVersion: capabilities.3scale.net/v1beta1 kind: ProxyConfigPromote metadata: name: proxyconfigpromote-sample spec: productCRName: product1-sample production: true
To delete the
ProxyConfigPromote object
after a successful promotion, set the optional fieldspec.deleteCR
totrue
:apiVersion: capabilities.3scale.net/v1beta1 kind: ProxyConfigPromote metadata: name: proxyconfigpromote-sample spec: productCRName: product1-sample deleteCR: true
To check the status condition of the file, type the following command:
oc get proxyconfigpromote proxyconfigpromote-sample -o yaml
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
Create the custom resource:
oc create -f proxyconfigpromote-sample.yaml
For the given example, the output would be:
proxyconfigpromote.capabilities.3scale.net/proxyconfigpromote-sample created
Additional resources
8.5. How the 3scale operator identifies the tenant that a custom resource links to
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
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.
-
The 3scale CR specifies the
In the 3scale CR, specify
spec.providerAccountRef
and set it to the name of a local reference to an OpenShiftSecret
that identifies the tenant. In the following 3scaleDeveloperAccount
CR example,mytenant
is the secret:apiVersion: capabilities.3scale.net/v1beta1 kind: DeveloperAccount metadata: name: developeraccount-simple-sample spec: orgName: Ecorp providerAccountRef: name: mytenant
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"
-
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
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
Deploy an OpenAPI
custom resource (CR) so that you can create 3scale backends and products.
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"
Create the secret. For example:
$ oc create secret generic myoasdoc1 --from-file myoasdoc1.yaml secret/myoasdoc1 created
Define your
OpenAPI
CR. Be sure to specify a reference to the secret that contains your OAS document. For example, you might create themyopenapicr1.yaml
file:apiVersion: capabilities.3scale.net/v1beta1 kind: OpenAPI metadata: name: myopenapicr1 spec: openapiRef: secretRef: name: myoasdoc1
Create the resource you just defined. For example:
$ oc create -f myopenapicr1.yaml
For the given example, the output would be:
openapi.capabilities.3scale.net/myopenapicr1 created
8.6.2. Features of 3scale OpenAPI custom resource definitions
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 itsbasePath
component ofservers[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 theapiKey
security scheme.
Additional resources
8.6.3. Import rules when defining OpenAPI custom resources
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
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"
8.6.4. Deploying a 3scale OpenAPI custom resource that imports an OAS document from a URL
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 theOpenAPI
CR contains a secret that identifies the tenant that theOpenAPI
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
-
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
8.7. Deploying 3scale ActiveDoc custom resources
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
Deploy an ActiveDoc
custom resource (CR) so that you can create 3scale backends and products.
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"
Procedure
Create the secret. For example:
$ oc create secret generic myoasdoc1 --from-file myoasdoc1.yaml secret/myoasdoc1 created
Define your
ActiveDoc
CR. Be sure to specify a reference to the secret that contains your OAS document. For example, you might create themyactivedoccr1.yaml
file:apiVersion: capabilities.3scale.net/v1beta1 kind: ActiveDoc metadata: name: myactivedoccr1 spec: name: "Operated ActiveDoc From secret" activeDocOpenAPIRef: secretRef: name: myoasdoc1
Create the resource you just defined. For example:
$ oc create -f myactivedoccr1.yaml
For the given example, the output would be:
activedoc.capabilities.3scale.net/myactivedoccr1 created
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
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
orhttps
format
-
Optionally, you can link the
ActiveDoc
CR with a 3scale product using theproductSystemName
field. The value must be thesystem_name
of the 3scale product’s CR. -
You can publish or hide the
ActiveDoc
document in 3scale using thepublished
field. By default, this is set to behidden
. -
You can skip OpenAPI 3.0 validation using the
skipSwaggerValidations
field. By default, theActiveDoc
CR is validated.
Additional resources
8.7.3. Deploying a 3scale ActiveDoc custom resource that imports an OAS document from a URL
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
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
Optional. For self-managed APIcast, in the
ActiveDoc
CR, set theproductionPublicBaseURL
andstagingPublicBaseURL
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"
-
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
8.8. Backend custom resources related to capabilities
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
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>"
For example:
apiVersion: capabilities.3scale.net/v1beta1 kind: Backend metadata: name: backend-1 spec: name: "My Backend Name" privateBaseURL: "https://api.example.com"
- 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:
-
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
. -
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
.
-
Confirm that the backend has been created in OpenShift, by checking in the 3scale Backend Overview page that the Synced condition is marked as
8.8.2. Defining backend metrics
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 assystem_name
. In the example below:metric01
,metric02
andhits
. -
metrics
map key names must be unique among all metrics and methods. -
unit
andfriendlyName
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
8.8.3. Defining backend methods
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 assystem_name
. In the example below:Method01
andMethod02
. -
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
8.8.4. Defining backend mapping rules
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
andmetricMethodRef
are required fields. -
metricMethodRef
holds a reference to the existing metric or method map key namesystem_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"
8.8.5. Status of the backend custom resource
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 thestatus.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.
-
Invalid: The combination of configuration in the
-
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
8.8.6. The backend custom resource linked to a tenant account
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
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"
Checks the default threescale-provider-account secret. For example:
adminURL=https://3scale-admin.example.com
andtoken=123456
:oc create secret generic threescale-provider-account --from-literal=adminURL=https://3scale-admin.example.com --from-literal=token=123456
- 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
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
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
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>"
For example:
apiVersion: capabilities.3scale.net/v1beta1 kind: Product metadata: name: product1 spec: name: "OperatedProduct 1"
- 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:
-
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
. -
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
.
-
Confirm that the product has been created in OpenShift, by checking in the 3scale Product Overview page that the Synced condition is marked as
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
Configure your product with APIcast hosted:
apiVersion: capabilities.3scale.net/v1beta1 kind: Product metadata: name: product1 spec: name: "OperatedProduct 1" deployment: apicastHosted: {}
8.9.1.3. Deploying a product with APIcast self-managed
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"
8.9.2. Defining product application plans
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 assystem_name
. In the example below:plan01
andplan02
.
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
8.9.3. Defining limits for product application plans
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
andmetricMethodRef
are required fields. -
The
metricMethodRef
reference can be either a product or a backend reference. Use the optionalbackend
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
8.9.4. Defining pricing rules for product application plans
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
andmetricMethodRef
are required fields. -
from
andto
will be validated. For any rule, values offrom
less thanto
and overlapping ranges for the same metric are not allowed. -
The
metricMethodRef
reference can be either a product or a backend reference. Use the optionalbackend
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
8.9.5. Defining product authentication using OpenID Connect
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
: Thekeycloak
value when using Red Hat Single Sign-On (RH-SSO) and therest
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.
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>`
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"
Create the resource you just defined. For example:
oc create -f product1.yaml
For the given example, the output would be:
product.capabilities.3scale.net/product1 created
Additional resources
8.9.6. Defining product metrics
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 assystem_name
. In the example below:metric01
andhits
. -
metrics
map key names must be unique among all metrics and methods. -
unit
andfriendlyName
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"
8.9.7. Defining product methods
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 assystem_name
. In the example below:Method01
andMethod02
. -
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
8.9.8. Defining product mapping rules
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
andmetricMethodRef
are required fields. -
metricMethodRef
holds a reference to the existing metric or method map key namesystem_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
8.9.9. Defining product backend usage
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’ssystem_name
. In the example below:backendA
andbackendB
.
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
8.9.10. Configuring gateway responses in 3scale Product custom resources
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 thegatewayResponse
object. The following example shows response configuration for an Apicast hosted deployment with an authentication mode calleduserKey
: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"
Deploy the
Product
CR that contains the gateway responses. For example, if you updated theproduct1.yaml
file, you would run the following command:oc create -f product1.yaml
For the given example, the output would be:
product.capabilities.3scale.net/product1 created
8.9.11. Configuring policy chains in 3scale Product custom resources
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 thepolicies
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
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 theProduct
custom resource links to. To identify policy names, see the documentation for the relevant policy in Administering the API Gateway, APIcast standard policies. version
isbuiltin
for standard policies or a user-defined string for custom policies. For example, you could set the version of a custom policy to1.0
.If a
Product
CR does not specify theapicast
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 theexport
output into aProduct
CR. For example, ifapi-provider-account-one
is the name of your 3scale provider account, andmy-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
-
Deploy the
Product
CR that contains the policy chain. For example, if you updated theproduct1.yaml
file, you would run the following command:oc create -f product1.yaml
For the given example, the output would be:
product.capabilities.3scale.net/product1 created
8.9.12. Status of the product custom resource
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 thestatus.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
8.9.13. The product custom resource linked to a tenant account
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
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"
Checks the default threescale-provider-account secret. For example:
adminURL=https://3scale-admin.example.com
andtoken=123456
:oc create secret generic threescale-provider-account --from-literal=adminURL=https://3scale-admin.example.com --from-literal=token=123456
- 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
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, themy-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: {}
Deploy the
CustomPolicyDefinition
CR:oc create -f my-apicast-custom-policy-definition.yaml
Additional resources
8.11. Deploying a tenant custom resource
A tenant custom resource is also known as the Provider Account.
Creating the APIManager custom resource indicates the operator to deploy 3scale. A default 3scale installation includes a default tenant ready to be used. Optionally, you may create other tenants creating tenant custom resource objects.
Prerequisites
To deploy a new tenant in your 3scale instance, you need some preparation steps:
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>
-
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
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>
Get the 3scale master account hostname: MASTER_HOSTNAME. When you deploy 3scale using the operator, the master account has a fixed URL with this pattern:
master.${wildcardDomain}
If you have access to the namespace where 3scale is installed, get the master account hostname:
oc get routes --field-selector=spec.to.name==system-master -o jsonpath="{.items[].spec.host}"
Procedure
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
Create the tenant resource:
oc create -f <yaml-name>
- This command triggers the creation of a new tenant in your 3scale solution.
- The 3scale operator will create a new secret and store the new tenant credentials in the secret.
-
The new tenant
provider_key
andadmin domain url
will be stored in a secret. -
The secret location can be specified using the
tenantSecretRef
tenant specification key.
As a reference, this is an example of the created secret content:
apiVersion: v1 kind: Secret metadata: name: tenant-secret type: Opaque stringData: adminURL: https://my3scale-admin.example.com:443 token: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
For more details about the fields of tenant custom resource and possible values, see the Tenant CRD Reference.
8.12. Managing 3scale developers by deploying custom resources
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.
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
- 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
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 theDeveloperAccount
CR contains a secret that identifies the tenant that theDeveloperAccount
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 newDeveloperAccount
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, themyusername01.yaml
file might contain:apiVersion: v1 kind: Secret metadata: name: myusername01 stringData: password: "123456"
Create the secret. For example:
oc create -f myusername01.yaml
For the given example, the output would be:
secret/myusername01 created
Create and save a
.yaml
file that defines aDeveloperUser
CR for a developer who has theadmin
role. ThisDeveloperUser
CR is required for the 3scale operator to deploy a newDeveloperAccount
CR. For example, thedeveloperuser01.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
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 theDeveloperAccount
CR before or after you create thisDeveloperUser
CR. -
The tenant that a
DeveloperUser
CR links to must be the same tenant that the specifiedDeveloperAccount
CR links to.
-
The developer user account name, user name, and email must be unique in the tenant that the containing
Create the resource you just defined. For example:
oc create -f developeruser01.yaml
For the given example, the output would be:
developeruser.capabilities.3scale.net/developeruser01 created
Create and save a
.yaml
file that defines aDeveloperAccount
CR. In this.yaml
file, thespec.OrgName
field must specify an organization name. For example, thedeveloperaccount01.yaml
file might contain:apiVersion: capabilities.3scale.net/v1beta1 kind: DeveloperAccount metadata: name: developeraccount01 spec: orgName: Ecorp providerAccountRef: name: mytenant
Create the resource you just defined. For example:
oc create -f developeraccount01.yaml
For the given example, the output would be:
developeraccount.capabilities.3scale.net/developeraccount01 created
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
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.
Additional resources
8.12.3. Managing 3scale developer users by deploying DeveloperUser custom resources
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 deployedDeveloperUser
CR for a user who has theadmin
role. If you are creating aDeveloperUser
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 theDeveloperUser
CR contains a secret that identifies the tenant that theDeveloperUser
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"
Create the secret. For example:
oc create -f myusername02.yaml
For the given example, the output would be:
secret/myusername02 created
Create and save a
.yaml
file that defines aDeveloperUser
CR. In thespec.role
field, specifyadmin
ormember
. For example, thedeveloperuser02.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
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 containingDeveloperAccount
links to. -
The
developerAccountRef
field must specify the name of a deployedDeveloperAccount
CR. -
The tenant that a
DeveloperUser
CR links to must be the same tenant that the specifiedDeveloperAccount
CR links to.
-
The developer user name (specified in the
Create the resource you just defined. For example:
oc create -f developefuser02.yaml
For the given example, the output would be:
developeruser.capabilities.3scale.net/developeruser02 created
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
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.
Additional resources
8.13. Limitations of 3scale operator capabilities
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
For more information, check the following guides: