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.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: