Chapter 8. Using the 3scale API Management operator to configure and provision 3scale As a Red Hat 3scale API Management 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). Note In the Admin Portal, services and resources are visible, but do not make updates there. Likewise, do not make updates using the internal 3scale API to update services and resources. Making updates using methods other than a CR will cause the operator to revert changes, keeping the configuration unchanged. This chapter includes details about how operator application capabilities work and how to use the operator to deploy custom resources: Your first 3scale API Management product and backend Promoting a product's APIcast configuration Backend custom resources related to capabilities Product custom resources related to capabilities Tenant custom resources Developer account 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 API Management 2.15 On-Premises instance 3scale API Management operator installed . OpenShift Container Platform 4 with a user account that has administrator privileges in the OpenShift cluster. For more information about supported configurations, see the Red Hat 3scale API Management Supported Configurations page. 8.2. Application capabilities via the 3scale API Management 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 API Management product and backend Using OpenShift Container Platform (OCP) 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 Portal URL address and the access token. Procedure Create a secret for the 3scale provider account using the credentials from the 3scale Admin Portal. For example: adminURL=https://3scale-admin.example.com and token=123456 . USD 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 (CR) and possible values, see the Backend custom resource definition (CRD) reference . Create a custom resource: USD 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 CR and possible values, see the Product CRD Reference . Create a custom resource: USD oc create -f product1.yaml Additionally, you can update an existing product CRD to link to a backend: USD oc apply -f product.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: USD oc wait --for=condition=Synced --timeout=-1s backend/backend1 USD 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. Note ProxyConfigPromote objects only take effect when created. After creation, any updates on them are not reconciled. proxyConfigPromote only processes the promotion of configurations if there are actual configuration changes. If no changes are detected, proxyConfigPromote will enter an error state. In this state, an error message will be displayed on the Custom Resource (CR), and the user must manually remove the CR, even if it is marked for deletion. 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 to true : 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 field spec.deleteCR to true : 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: USD oc get proxyconfigpromote proxyconfigpromote-sample -o yaml The output should show the status is Ready or Failed : apiVersion: capabilities.3scale.net/v1beta1 kind: ProxyConfigPromote metadata: name: proxyconfigpromote-sample spec: productCRName: product1-sample status: conditions: - lastTransitionTime: '2023-09-05T07:15:11Z' message: >- 3scale product has been successfully promoted, any further interactions with this CR (apart from deletion) won't be applied status: 'True' type: Ready latestStagingVersion: 1 productId: '7' apiVersion: capabilities.3scale.net/v1beta1 kind: ProxyConfigPromote metadata: name: proxyconfigpromote-sample spec: productCRName: product1-sample status: conditions: - lastTransitionTime: '2023-09-05T07:48:08Z' message: >- cannot promote to production as no product changes detected. Delete this proxyConfigPromote CR, then introduce changes to configuration, and then create a new proxyConfigPromote CR status: 'True' type: Failed latestProductionVersion: 1 latestStagingVersion: 1 productId: '6' Note If you do not make changes in the proxy configuration, you get a Failed output status of the ProxyConfigPromote CR with one the following messages: When promoting to stage: cannot promote to staging as no product changes detected. Delete this proxyConfigPromote CR, then introduce changes to configuration, and then create a new proxyConfigPromote CR . When promoting to production: cannot promote to production as no product changes detected. Delete this proxyConfigPromote CR, then introduce changes to configuration, and then create a new proxyConfigPromote CR . Follow the instruction in the message to complete your procedure. 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 ProxyConfigPromote CRD Reference 8.5. How the 3scale API Management 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: USD 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. In the 3scale CR, specify spec.providerAccountRef and set it to the name of a local reference to an OpenShift Secret that identifies the tenant. In the following 3scale DeveloperAccount CR example, mytenant is the secret: apiVersion: capabilities.3scale.net/v1beta1 kind: DeveloperAccount metadata: name: developeraccount-simple-sample spec: orgName: Ecorp providerAccountRef: name: mytenant 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 CR 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 API Management 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.15 On-Premises instance. An OAS document that defines your API. An understanding of how an OpenAPI CR links to a tenant. apiKey and openIdConnect/oauth2 are the supported security schemes. OpenID Connect and OAuth2 limitations To configure 3scale in the OpenAPI specification, you must provide the following data in the OpenAPI custom resource (CR): OpenID Connect (OIDC) issuerType : Define the issuer type, which defaults to rest . You can override this parameter in the OpenAPI CR. Define the issuerEndpoint , as a plain value URL, or the issuerEndpointRef secret with the issuerEndpoint URL. If you define the issuerEndpoint plain value in the CR, it takes precedence over issuerEndpointRef secret. The issuerEndpoint format depends on the OpenID Provider setup. For Red Hat Single Sign-On it is https://<CLIENT_ID>:<CLIENT_SECRET>@:/auth/realms/<REALM_NAME> . Flows Object: When you define the oauth2 security scheme, the OpenAPI document includes the flows. However, when the security scheme is OpenID Connect, the OpenAPI document does not provide the flows. In this case, the OpenAPI CR can provide them. 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 . Note The operator reads only the content in the secret. The operator does not read the field name in the secret. Prerequisites You understand How the 3scale operator identifies the tenant that a custom resource links to . Procedure Define a secret that contains an OAS document. For example, you might create the myoasdoc1.yaml with this content: openapi: "3.0.2" info: title: "some title" description: "some description" version: "1.0.0" paths: /pet: get: operationId: "getPet" responses: 405: description: "invalid input" Create the secret. For example: USD 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 the myopenapicr1.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: USD oc create -f myopenapicr1.yaml For the given example, the output would be: USD 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 its basePath component of servers[0].url element. The OpenAPI CRD supports a single top level security requirement, however it does not support operational level security. The OpenAPI CRD supports the apiKey and the openIdConnect/oauth2 security schemes. Additional resources Product custom resources related to capabilities OpenAPI CRD Reference OpenID Connect and OAuth2 example Object Names and IDs 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. Configuring OpenID Connect and OAuth2 Red Hat 3scale API Management requires additional information not included in the OpenAPI Specification (OAS). You must provide this information in the OpenAPI custom resource (CR), specifically the following: OpenID Connect Issuer Type Defaults to rest , but it can be overridden from the OpenAPI CR. OpenID Connect Issuer Endpoint Reference (Secret) 3scale requires that the issuer URL includes a client secret. Flows object When the security scheme is OAuth2, the flows are provided by the OpenAPI document. However, for the OpenID Connect (OIDC) security scheme, the OpenAPI document does not provide the flows. There are 4 flows parameters for OIDC only: standardFlowEnabled implicitFlowEnabled serviceAccountsEnabled directAccessGrantsEnabled . OIDC issuer secret You have previously setup Issuer Client. RHSSO/keycloak realm and client are using it in the secret example. issuerEndpoint format is https://<client-id>:<client-secret>@<host>:<port>/auth/realms/<realm-name> . The format is described in the 3scale Portal/Products page - AUTHENTICATION SETTINGS - OpenID Connect Issuer . The <client-secret> value is taken from the Issuer Client in Realm/Clients/ClientID/Credentials/Secret . Procedure Create the secret, for example, my-secret.yaml , with the following content: kind: Secret apiVersion: v1 metadata: name: my-secret namespace: 3scale-test data: issuerEndpoint: https://3scale-zync:some-secret@keycloak-rhsso-test.example.com/auth/realms/petstore type: Opaque Apply the secret with the following command: USD oc apply -f my-secret.yaml Create the OpenAPI CR for OIDC and OAuth2, for example, openapi-example.yaml , with the following content: apiVersion: capabilities.3scale.net/v1beta1 kind: OpenAPI metadata: generation: 1 name: openapi-example spec: openapiRef: url: "https://example.com/petstore.yaml" privateAPISecretToken: "xxxx" oidc: issuerType: keycloak issuerEndpointRef: name: my-secret jwtClaimWithClientID: azp jwtClaimWithClientIDType: plain authenticationFlow: standardFlowEnabled: true implicitFlowEnabled: true serviceAccountsEnabled: true directAccessGrantsEnabled: true gatewayResponse: errorStatusAuthFailed: 403 Apply the OpenAPI CR for OIDC and OAuth2 with the following command: USD oc apply -f <openapi-cr-file>.yaml Note The OIDC field is optional in the OpenAPI CR, applicable only for OpenID Connect. issuerEndpointRef should reference a secret containing the issuerEndpoint Table 8.1. OIDC specification field description Field Required Description issuerType no Valid values: [ keycloak , rest ]. Defaults to rest . issuerEndpoint no issuerEndpoint can be defined in issuerEndpointRef or as plain value. The format of this endpoint is determined on your OpenID provider setup. For Red Hat single sign-on: https://<client-id>:<client-secret>@<host>:<port>/auth/realms/<realm-name> issuerEndpointRef no The secret that contains issuerEndpoint . jwtClaimWithClientID no JSON Web Token (JWT) Claim with ClientID that contains the clientID. Defaults to azp . jwtClaimWithClientIDType no jwtClaimWithClientIDType sets to process the ClientID Token Claim value as a string or as a liquid template. Valid values: plain, liquid. Defaults to plain . authenticationFlow no Flows object: When the security scheme is OAuth2, the flows are provided by the OpenAPI document. However, for the OIDC security scheme, the OpenAPI document does not provide the flows. In that case, the OpenAPI CR can provide those. There are 4 flows parameters for OIDC only: standardFlowEnabled , implicitFlowEnabled , serviceAccountsEnabled , directAccessGrantsEnabled . gatewayResponse no Specifies custom gateway response on errors. See GatewayResponseSpec . Define the issuerEndpointRef or issuerEndpoint in OIDC specification, however you can define both fields. If issuerEndpoint plain value is defined in the CR, it will be used as precedence over issuerEndpointRef secret. The format of issuerEndpoint is determined on your OpenID Provider setup: In the 3scale Admin Portal, navigate to [Your_product_name] > Integration > Settings . Under Authentication , click the OpenID Connect Issuer option. Check the OpenID Connect Issuer Type . The following is an OpenAPI CR example where issuerEndpoint is defined both as plain value and in secret. The plain value is used: apiVersion: capabilities.3scale.net/v1beta1 kind: OpenAPI metadata: generation: 1 name: openapi-example spec: openapiRef: url: "https://example.com/petstore.yaml" oidc: issuerType: keycloak issuerEndpoint: https://3scale-zync:some-secret@keycloak-rhsso-test.example.com/auth/realms/petstore issuerEndpointRef: name: my-secret jwtClaimWithClientID: azp jwtClaimWithClientIDType: plain authenticationFlow: standardFlowEnabled: true implicitFlowEnabled: true serviceAccountsEnabled: true directAccessGrantsEnabled: true If the OpenAPI CR specification is OIDC, but the securitySchemes type in OAS is oauth2 , then the CR OIDC Authentication Flows parameters will be ignored, and Product OIDC Authentication Flows will be set to match oauth2 flows as defined in OAS: standardFlowEnabled is true if OAuth2 authorizationCode is defined implicitFlowEnabled is true if OAuth2 implicit is defined serviceAccountsEnabled is true if OAuth2 clientCredentials is defined directAccessGrantsEnabled is true if OAuth2 password is defined An example of OAS securitySchemes definition that allows selection of all Product OIDC Authentication Flows. Note: Define OIDC in the OpenAPI CR: securitySchemes: myOauth: description: This API uses OAuth 2 with the implicit grant flow. link:https://api.example.com/docs/auth:[More information] flows: password: scopes: read_pets: read your pets write_pets: modify pets in your account tokenUrl: https://api.example.com/oauth2/token implicit: authorizationUrl: https://example.com/api/oauth/dialog scopes: write_pets: modify pets in your account read_pets: read your pets authorizationCode: authorizationUrl: https://example.com/api/oauth/dialog tokenUrl: https://example.com/api/oauth/token scopes: write_pets: modify pets in your account read_pets: read your pets clientCredentials: tokenUrl: https://example.com/api/oauth/token scopes: write_pets: modify pets in your account read_pets: read your pets type: oauth2 Additional resources 3scale product reference 8.6.5. Deploying a 3scale API Management 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 the OpenAPI CR contains a secret that identifies the tenant that the OpenAPI CR links to. The name of the secret is one of the following: threescale-provider-account User defined This secret contains the URL for a 3scale instance and a token that contains credentials for access to one tenant in that 3scale instance. Procedure In your OpenShift account, navigate to Operators > Installed operators . Click the 3scale operator. Choose the YAML tab. Create an OpenAPI custom resource (CR). For example: apiVersion: capabilities.3scale.net/v1beta1 kind: OpenAPI metadata: name: openapi1 spec: openapiRef: url: "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml" providerAccountRef: name: mytenant 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.6. Additional resources OpenAPI Specification OpenAPI CRD Reference Deploying optional tenants custom resource OpenID Connect and OAuth2 example 8.7. Deploying 3scale API Management 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.15 On-Premises instance. An OAS document that defines your API. OAS 3.0.2 is the only supported version with the ActiveDocs custom resource definition (CRD). An understanding of how an ActiveDoc CR links to a tenant. 8.7.1. Deploying a 3scale API Management 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 . Note The operator reads only the content in the secret. The operator does not read the field name in the secret. For example, data is structured in key: value pairs, where value represents the content of a file and key is the file name. The file name is ignored by the operator in this context of ActiveDoc CRD. The operator reads only the content of the file. Prerequisites You understand How the 3scale API Management 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: USD 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 the myactivedoccr1.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: USD oc create -f myactivedoccr1.yaml For the given example, the output would be: USD 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 API Management OpenAPI 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 or https format Optionally, you can link the ActiveDoc CR with a 3scale product using the productSystemName field. The value must be the system_name of the 3scale product's CR. You can publish or hide the ActiveDoc document in 3scale using the published field. By default, this is set to be hidden . You can skip OpenAPI 3.0 validation using the skipSwaggerValidations field. By default, the ActiveDoc CR is validated. Additional resources Product custom resources related to capabilities ActiveDoc CRD Reference 8.7.3. Deploying a 3scale API Management 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 You understand How the 3scale operator identifies the tenant that a custom resource links to . Procedure In your OpenShift account, navigate to Operators > Installed operators . Click the 3scale operator. Click the Active Doc tab. Create an ActiveDoc CR. For example: apiVersion: capabilities.3scale.net/v1beta1 kind: ActiveDoc metadata: name: myactivedoccr1 spec: openapiRef: url: "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml" providerAccountRef: name: mytenant Optional. For self-managed APIcast, in the ActiveDoc CR, set the productionPublicBaseURL and stagingPublicBaseURL fields to the URLs for your deployment. For example: apiVersion: capabilities.3scale.net/v1beta1 kind: ActiveDoc metadata: name: myactivedoccr1 spec: openapiRef: url: "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml" productionPublicBaseURL: "https://production.my-gateway.example.com" stagingPublicBaseURL: "https://staging.my-gateway.example.com" 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 OpenAPI Specification ActiveDoc CRD Reference Deploying optional tenants custom resource 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 (OCP) 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, and 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 . 8.8.2. Defining backend metrics Using Openshift Container Platform (OCP) with your newly created 3scale tenant, define desired backend metrics in your backend custom resource (CR). Consider these observations: metrics map key names will be used as system_name . In the example below: metric01 , metric02 and hits . metrics map key names must be unique among all metrics and methods. unit and friendlyName are required fields. If you do not add a hits metric, this metric will be created by the operator. Procedure Add backend metrics to the new 3scale backend, as in this example: apiVersion: capabilities.3scale.net/v1beta1 kind: Backend metadata: name: backend-1 spec: name: "My Backend Name" privateBaseURL: "https://api.example.com" metrics: metric01: friendlyName: Metric01 unit: "1" metric02: friendlyName: Metric02 unit: "1" hits: description: Number of API hits friendlyName: Hits unit: "hit 8.8.3. Defining backend methods Using OpenShift Container Platform (OCP) with your newly created 3scale tenant, define desired backend methods in your backend custom resource (CR). Consider these observations: methods map key names will be used as system_name . In the example below: Method01 and Method02 . methods map key names must be unique among all metrics and methods. friendlyName is a required field. Procedure Add backend methods to the new 3scale backend, as in this example: apiVersion: capabilities.3scale.net/v1beta1 kind: Backend metadata: name: backend-1 spec: name: "My Backend Name" privateBaseURL: "https://api.example.com" methods: method01: friendlyName: Method01 method02: friendlyName: Method02 8.8.4. Defining backend mapping rules Using OpenShift Container Platform (OCP) with your newly created 3scale tenant, define desired backend mapping rules in your backend custom resource (CR). Consider these observations: httpMethod , pattern , increment and metricMethodRef are required fields. metricMethodRef holds a reference to the existing metric or method map key name system_name . In the example below, hits . Procedure Add backend mapping rules to the new 3scale backend, as in this example: apiVersion: capabilities.3scale.net/v1beta1 kind: Backend metadata: name: backend-1 spec: name: "My Backend Name" privateBaseURL: "https://api.example.com" mappingRules: - httpMethod: GET pattern: "/pets" increment: 1 metricMethodRef: hits - httpMethod: GET pattern: "/pets/id" increment: 1 metricMethodRef: hits metrics: hits: description: Number of API hits friendlyName: Hits unit: "hit" 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 to every change of the resource. These are the attributes of the status field: backendId The internal identifier of a 3scale backend. conditions Represents the status.Conditions Kubernetes common pattern. It has these types, or states: Invalid The combination of configuration in the BackendSpec is not supported. This is not a transient error, but indicates a state that must be fixed before progress can be made. Synced The backend has been successfully synchronized. Failed An error occurred during synchronization. observedGeneration It is a helper field to confirm that the status information is updated with the latest resource specification. Example of a synchronized resource: status: backendId: 59978 conditions: - lastTransitionTime: "2020-06-22T10:50:33Z" status: "False" type: Failed - lastTransitionTime: "2020-06-22T10:50:33Z" status: "False" type: Invalid - lastTransitionTime: "2020-06-22T10:50:33Z" status: "True" type: Synced observedGeneration: 2 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 and token=123456 : USD 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.8.7. Deleting Backend custom resources You can delete a backend entity by deleting the Backend custom resource (CR) that manages it. When you delete a Backend CR, the 3scale operator updates deployed Product CRs that refer to the deleted backend. Updates are in these attributes: backendUsages applicationPlans These attributes no longer refer to the deleted backend. Important The only way to delete an API backend defined by a Backend CR is to follow the procedure described here. Do not use the Admin Portal nor the 3scale API to delete a backend that was deployed as a CR. Prerequisites 3scale administrator permissions or an OpenShift role that has delete permissions in the namespace that contains the Backend CR you want to delete. To identify who can delete a particular Backend CR, run the oc policy who-can delete command. For example, if the name in the CR is mybackend , run this command: USD oc policy who-can delete product.capabilities.3scale.net/mybackend The Backend CR to be deleted links to a valid tenant. Procedure Run the oc delete command to delete a Backend CR. For example, if you deployed a Backend that was defined in the mybackend.yaml file, you would run the following command: USD oc delete -f mybackend.yaml Alternatively, you can run the oc delete command and specify the name of the backend as specified in its definition. For example: USD oc delete backend.capabilities.3scale.net/mybackend 8.9. Product custom resources related to capabilities Using OpenShift Container Platform (OCP) 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 (OCP) 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 . Additionally, you can specify the APIcast deployment mode for each product that you create. There are two alternatives: APIcast hosted APIcast self-managed 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 (OCP) with your newly created 3scale tenant, define desired application plans in your product custom resource (CR), by using the applicationPlans object. Consider this observation: applicationPlans map key names will be used as system_name . In the example below: plan01 and plan02 . Note setupFee and costMonth are generic 3scale concepts. You must enter details for these when you create an application plan in the 3scale user interface. See Configuring an application plan with your pricing rules . Procedure Add application plans to the new 3scale product, as in this example: apiVersion: capabilities.3scale.net/v1beta1 kind: Product metadata: name: product1 spec: name: "OperatedProduct 1" applicationPlans: plan01: name: "My Plan 01" setupFee: "14.56" plan02: name: "My Plan 02" trialPeriod: 3 costMonth: 3 8.9.3. Defining limits for product application plans Using OpenShift Container Platform (OCP) with your newly created 3scale tenant, define desired limits for your product application plans, by using the applicationPlans.limits list. Consider these observations: period , value and metricMethodRef are required fields. The metricMethodRef reference can be either a product or a backend reference. Use the optional backend field to reference the owner of the backend metric. Procedure Define limits for the application plans of an 3scale product, as in this example: apiVersion: capabilities.3scale.net/v1beta1 kind: Product metadata: name: product1 spec: name: "OperatedProduct 1" metrics: hits: description: Number of API hits friendlyName: Hits unit: "hit" applicationPlans: plan01: name: "My Plan 01" limits: - period: month value: 300 metricMethodRef: systemName: hits backend: backendA - period: week value: 100 metricMethodRef: systemName: hits 8.9.4. Defining pricing rules for product application plans Using OpenShift Container Platform (OCP) with your newly created 3scale tenant, define desired pricing rules for your product application plans, by using the applicationPlans.pricingRules list. Consider these observations: from , to , pricePerUnit and metricMethodRef are required fields. from and to will be validated. For any rule, values of from less than to and overlapping ranges for the same metric are not allowed. The metricMethodRef reference can be either a product or a backend reference. Use the optional backend field to reference the owner of the backend metric. Procedure Define pricing rules for the application plans of an 3scale product, as in this example: apiVersion: capabilities.3scale.net/v1beta1 kind: Product metadata: name: product1 spec: name: "OperatedProduct 1" metrics: hits: description: Number of API hits friendlyName: Hits unit: "hit" applicationPlans: plan01: name: "My Plan 01" pricingRules: - from: 1 to: 100 pricePerUnit: "15.45" metricMethodRef: systemName: hits - from: 1 to: 300 pricePerUnit: "15.45" metricMethodRef: systemName: hits backend: backendA 8.9.5. Defining product authentication using OpenID Connect You can deploy a Product custom resource (CR) 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 CR: issuerType : The keycloak value when using Red Hat single sign-on (SSO) or Red Hat build of Keycloak, and the rest value when integrating with the third-party IdP. issuerEndpoint : A URL with the necessary credentials in it. Prerequisites You must configure SSO. See Configuring Red Hat single sign-on . You must Configure HTTP integration with third-party Identity Providers . Note The credentials CLIENT_ID and CLIENT_CREDENTIALS provided in issuerEndpoint must have sufficient permissions to manage other clients in the realm. Procedure Determine the endpoint issuerEndpoint , which defines the location of your OpenID Provider and use this format in the product CR: 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: USD oc create -f product1.yaml For the given example, the output would be: USD product.capabilities.3scale.net/product1 created Additional resources Product CRD Reference 8.9.6. Defining product metrics Using OpenShift Container Platform (OCP) with your newly created 3scale tenant, define desired metrics in your product custom resource (CR), by using the metrics object. Consider these observations: metrics map key names will be used as system_name . In the example below: metric01 and hits . metrics map key names must be unique among all metrics and methods. unit and friendlyName are required fields. If you do not add a hits metric, it will be created by the operator. Procedure Add product metrics to the new 3scale backend, as in this example: apiVersion: capabilities.3scale.net/v1beta1 kind: Product metadata: name: product1 spec: name: "OperatedProduct 1" metrics: metric01: friendlyName: Metric01 unit: "1" hits: description: Number of API hits friendlyName: Hits unit: "hit" 8.9.7. Defining product methods Using OpenShift Container Platform (OCP) with your newly created 3scale tenant, define desired methods in your product custom resource, by using the methods object. Consider these observations: methods map key names will be used as system_name . In the example below: Method01 and Method02 . methods map key names must be unique among all metrics and methods. friendlyName is a required field. Procedure Add methods to the new 3scale product, as in this example: apiVersion: capabilities.3scale.net/v1beta1 kind: Product metadata: name: product1 spec: name: "OperatedProduct 1" methods: method01: friendlyName: Method01 method02: friendlyName: Method02 8.9.8. Defining product mapping rules Using OpenShift Container Platform (OCP) with your newly created 3scale tenant, define desired mapping rules in your product custom resource (CR), by using the mappingRules object. Consider these observations: httpMethod , pattern , increment and metricMethodRef are required fields. metricMethodRef holds a reference to the existing metric or method map key name system_name . In the example below, hits . Procedure Add product mapping rules to the new 3scale backend, as in this example: apiVersion: capabilities.3scale.net/v1beta1 kind: Product metadata: name: product1 spec: name: "OperatedProduct 1" metrics: hits: description: Number of API hits friendlyName: Hits unit: "hit" methods: method01: friendlyName: Method01 mappingRules: - httpMethod: GET pattern: "/pets" increment: 1 metricMethodRef: hits - httpMethod: GET pattern: "/cars" increment: 1 metricMethodRef: method01 8.9.9. Defining product backend usage Using OpenShift Container Platform (OCP) with your newly created 3scale tenant, define desired backends to be added to a product declaratively, by applying the backendUsages object. Consider these observations: path is a required field. backendUsages map key names are references to the backend's system_name . In the example below: backendA and backendB . Procedure Add a backend to a product to define its usage declaratively, as in this example: apiVersion: capabilities.3scale.net/v1beta1 kind: Product metadata: name: product1 spec: name: "OperatedProduct 1" backendUsages: backendA: path: /A backendB: path: /B 8.9.10. Configuring gateway responses in 3scale API Management 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 the gatewayResponse object. The following example shows response configuration for an Apicast hosted deployment with an authentication mode called userKey : apiVersion: capabilities.3scale.net/v1beta1 kind: Product metadata: name: product1 spec: name: "OperatedProduct 1" deployment: apicastHosted: authentication: userkey: gatewayResponse: errorStatusAuthFailed: 500 errorHeadersAuthFailed: "text/plain; charset=mycharset" errorAuthFailed: "My custom reponse body" errorStatusAuthMissing: 500 errorHeadersAuthMissing: "text/plain; charset=mycharset" errorAuthMissing: "My custom reponse body" errorStatusNoMatch: 501 errorHeadersNoMatch: "text/plain; charset=mycharset" errorNoMatch: "My custom reponse body" errorStatusLimitsExceeded: 502 errorHeadersLimitsExceeded: "text/plain; charset=mycharset" errorLimitsExceeded: "My custom reponse body" Deploy the Product CR that contains the gateway responses. For example, if you updated the product1.yaml file, you would run the following command: USD 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 API Management Product custom resources As a 3scale administrator, you can configure a Product custom resource (CR) to specify the policy chain that you want to apply to that API product. After you deploy the CR, 3scale applies the configured policies to requests to the product's upstream, exposed API. Procedure In a new or deployed Product CR, configure one or more policies in the policies object. For example: With configuration from value apiVersion: capabilities.3scale.net/v1beta1 kind: Product metadata: name: product1 spec: name: "OperatedProduct 1" policies: - configuration: http_proxy: http://example.com https_proxy: https://example.com enabled: true name: camel version: builtin - configuration: {} enabled: true name: apicast version: builtin With configuration from secret apiVersion: v1 kind: Secret metadata: name: my-config-policy type: Opaque stringData: configuration: "{\"http_proxy\":\"http://secret.com\"}" --- apiVersion: capabilities.3scale.net/v1beta1 kind: Product metadata: name: product2 spec: name: "OperatedProduct 2" policies: - configurationRef: name: my-config-policy enabled: true name: camel version: builtin - configuration: {} enabled: true name: apicast version: builtin For each policy, specify these fields: configuration is a pair of empty braces when a policy has no parameters. When a policy has parameters, specify them here. For the names of any parameters that you need to specify, see the documentation for the relevant policy in Administering the API Gateway, APIcast standard policies . enabled is a Boolean switch for turning the policy on or off. name identifies the policy. This is a unique name in the scope of the tenant that the Product CR links to. To identify policy names, see the documentation for the relevant policy in Standard policies to change default 3scale API Management APIcast behavior . version is builtin for standard policies or a user-defined string for custom policies. For example, you could set the version of a custom policy to 1.0 . If a Product CR does not specify the apicast policy, the operator adds it. If a policy chain is already defined in the Admin Portal, you can run the 3scale toolbox export command to export the policy chain in .yaml format. You can paste the export output into a Product CR. For example, if api-provider-account-one is the name of your 3scale provider account, and my-api-product-one is the name of the product whose policy chain you want to export, you would run the following command: USD 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 the product1.yaml file, you would run the following command: USD oc create -f product1.yaml For the given example, the output would be: USD 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 the status.Conditions Kubernetes common pattern. It has these types, or states: Failed An error occurred during synchronization. The operation will retry. Synced The product has been successfully synchronized. Invalid Invalid object. This is not a transient error, but it reports about an invalid specification and it should be changed. The operator will not retry. Orphan The specification references a resource that does not exist. The operator will retry. observedGeneration Confirms that the status information is updated with the latest resource specification. state The 3scale product internal state read from the 3scale API. providerAccountHost The 3scale provider account URL to which the backend is synchronized. Example of a synchronized resource: status: conditions: - lastTransitionTime: "2020-10-21T18:07:01Z" status: "False" type: Failed - lastTransitionTime: "2020-10-21T18:06:54Z" status: "False" type: Invalid - lastTransitionTime: "2020-10-21T18:07:01Z" status: "False" type: Orphan - lastTransitionTime: "2020-10-21T18:07:01Z" status: "True" type: Synced observedGeneration: 1 productId: 2555417872138 providerAccountHost: https://3scale-admin.example.com state: incomplete 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 and token=123456 : USD 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.14. Deleting Product custom resources You can delete a 3scale product entity by deleting the custom resource (CR) that manages it. When you delete a Product CR the 3scale operator does not update objects that refer to the deleted product. Important The only way to delete an API product defined by a Product CR is to follow the procedure described here. Do not use the Admin Portal nor the 3scale API to delete a product that was deployed as a CR. Prerequisites 3scale administrator permissions or an OpenShift role that has delete permissions in the namespace that contains the CR you want to delete. To identify who can delete a particular Product CR, run the oc policy who-can delete command. For example, if the name in the CR is myproduct , run this command: USD oc policy who-can delete product.capabilities.3scale.net/myproduct The Product CR to be deleted links to a valid tenant. Procedure Run the oc delete command to delete a Product CR. For example, if you deployed a Product that was defined in the myproduct.yaml file, you would run the following command: USD oc delete -f myproduct.yaml Alternatively, you can run the oc delete command and specify the name of the product as specified in its definition. For example: USD oc delete product.capabilities.3scale.net/myproduct 8.10. Application custom resources related to capabilities Using OpenShift Container Platform (OCP) in your newly created tenant, you will configure an application, for its corresponding application plan. Prerequisites The same installation requirements as listed in General prerequisites , in addition to the following: A 3scale developer account . A 3scale product . An application plan . 8.10.1. Deploying application custom resources related to capabilities Using OpenShift Container Platform (OCP) in your newly created tenant, you will configure a new application. Procedure In your OpenShift account, navigate to Installed Operators . Click on Red Hat Integration - 3scale . In the Application tab, click Create application . Choose the YAML View. Create a 3scale application pointing to a specific application plan: For example: apiVersion: capabilities.3scale.net/v1beta1 kind: Application metadata: name: example namespace: 3scale_project_name spec: accountCR: name: developer_account applicationPlanName: application_plan_name productCR: name: product_custom_resource name: application_name description: describe_your_application To save your changes, click Create . Wait a few seconds to have the application created both in OpenShift, as well as in your 3scale account. Then, you can perform the following verifications: Confirm that the application has been created in OpenShift, by checking in the 3scale Application Overview . The Ready condition value should be True . Go to your 3scale account, and you will see that the application has been created. In the example above, you will see a new application by the unique name you have given it. 8.10.2. Deleting application custom resources You can delete an application entity by deleting the Application custom resource (CR) that manages it. Important The only way to delete an API application defined by an Application CR is to follow the procedure described here. Do not use the Admin Portal nor the 3scale API to delete an application that was deployed as a CR. Prerequisites 3scale administrator permissions or an OpenShift role that has delete permissions in the namespace that contains the Application CR you want to delete. To identify who can delete a particular Application CR, run the oc policy who-can delete command. For example, if the name in the CR is myapplication , run this command: USD oc policy who-can delete application.capabilities.3scale.net/myapplication The Application CR to be deleted links to a valid tenant. Procedure Run the oc delete command to delete an Application CR. For example, if you deployed an Application CR that was defined in the myapplication.yaml file, you would run the following command: USD oc delete -f myapplication.yaml Alternatively, you can run the oc delete command and specify the name of the application as specified in its definition. For example: USD oc delete application.capabilities.3scale.net/myapplication 8.11. Deploying 3scale API Management CustomPolicyDefinition custom resources You can use a CustomPolicyDefinition custom resource definition (CRD) to configure your custom policy in a 3scale product from the Admin Portal. When the 3scale operator finds a new CustomPolicyDefinition custom resource (CR), the operator identifies the tenant that owns the CR as described in How the 3scale API Management 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 CR and save it in, for example, the my-apicast-custom-policy-definition.yaml file: apiVersion: capabilities.3scale.net/v1beta1 kind: CustomPolicyDefinition metadata: name: custompolicydefinition-sample spec: version: "0.1" name: "APIcast Example Policy" schema: name: "APIcast Example Policy" version: "0.1" USDschema: "http://apicast.io/policy-v1/schema#manifest#" summary: "This is just an example." configuration: type: object properties: {} Deploy the CustomPolicyDefinition CR: USD oc create -f my-apicast-custom-policy-definition.yaml Additional resources CustomPolicyDefinition CRD Reference . 8.12. Deploying a tenant custom resource A Tenant custom resource (CR) is also known as the Provider Account . When you deploy an APIManager CR you are using the 3scale operator to deploy 3scale. A default 3scale installation includes a default tenant ready to be used. Optionally, you can create other tenants by deploying Tenant CR. Prerequisites General prerequisites An OpenShift role that has create permission in the new Tenant CR namespace. Procedure Navigate to the OpenShift project in which 3scale is installed. For example, if the name of the project is my-3scale-project , run the following command: USD oc project my-3scale-project Create a secret that contains the password for the 3scale admin account for the new tenant. In the definition of the Tenant CR, set the passwordCredentialsRef attribute to the name of this secret. In the example of a Tenant CR definition in step 4, ADMIN_SECRET is the placeholder for this secret. The following command provides an example of creating the secret: USD oc create secret generic ecorp-admin-secret --from-literal=admin_password=<admin password value> Obtain the 3scale master account hostname. When you deploy 3scale by using the operator, the master account has a fixed URL with this pattern: master.USD{wildcardDomain} If you have access to the namespace where 3scale is installed, you can obtain the master account hostname with this command: USD oc get routes --field-selector=spec.to.name==system-master -o jsonpath="{.items[].spec.host}" In the example of a Tenant CR definition in step 4, MASTER_HOSTNAME is the placeholder for this name. Create a file that defines the new Tenant CR. In the definition of the Tenant CR, set the masterCredentialsRef.name attribute to system-seed . You can perform tenant management tasks only by using the 3scale master account credentials, preferably an access token. During deployment of an APIManager CR, the operator creates the secret that contains master account credentials. The name of the secret is system-seed . If 3scale is installed in cluster wide mode, you can deploy the new tenant in a namespace that is different from the namespace that contains 3scale. To do this, set masterCredentialsRef.namespace to the namespace that contains the 3scale installation. The following example assumes that 3scale is installed in cluster wide mode. apiVersion: capabilities.3scale.net/v1alpha1 kind: Tenant metadata: generation: 3 name: <ecorp_tenant> namespace: <namespace_in_which_to_create_tenant-CR> spec: email: admin@ecorp.com masterCredentialsRef: name: system-seed namespace: <namespace-where-3scale-is-deployed> organizationName: ECorp passwordCredentialsRef: name: <admin_secret> namespace: <namespace_in_which_to_create_tenant-CR> systemMasterUrl: https://<master_hostname> tenantSecretRef: name: <tenant_secret> namespace: <namespace_in_which_to_create_tenant-CR> username: tenant2FromCR1 Create the Tenant CR. For example, if you saved the example CR in the mytenant.yaml file, you would run: USD oc create -f mytenant.yaml As a result of this command: The operator deploys a tenant in the 3scale installation pointed to by the setting of the spec.systemMasterUrl attribute. The 3scale operator creates a secret that contains credentials for the new tenant. The name of the secret is the value you specified for the tenantSecretRef.name attribute. This secret contains the new tenant`s admin URL and access token. As a reference, this is an example of the secret that the operator creates: apiVersion: v1 kind: Secret metadata: name: <tenant_secret> type: Opaque stringData: adminURL: https://my3scale-admin.example.com:443 token: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" You can now deploy Product , Backend , OpenAPI , DeveloperAccount , and DeveloperUser CRs that link to your new tenant. Extending the capabilities of a Tenant CR You can set the following optional parameters in your 3scale Tenant via the Tenant CR: fromEmail supportEmail financeSupportEmail siteAccessCode Procedure Update the tenant info parameters in your 3scale Tenant via the Tenant CR: apiVersion: capabilities.3scale.net/v1alpha1 kind: Tenant metadata: generation: 3 name: <ecorp_tenant> namespace: <namespace_in_which_to_create_tenant-CR> spec: email: admin@ecorp.com masterCredentialsRef: name: system-seed namespace: <namespace-where-3scale-is-deployed> organizationName: ECorp passwordCredentialsRef: name: <admin_secret> namespace: <namespace_in_which_to_create_tenant-CR> systemMasterUrl: https://<master_hostname> tenantSecretRef: name: <tenant_secret> namespace: <namespace_in_which_to_create_tenant-CR> username: <tenant2FromCR1> fromEmail: <tenant2FromCR1>@ecorp.com supportEmail: <tenant2Support>@ecorp.com financeSupportEmail: <tenant2FinanceSupport>@ecorp.com siteAccessCode: <abc123> Apply the change to the Tenant CR: USD oc apply -f mytenant.yaml Deleting a Tenant CR Do not delete a tenant in the Admin Portal if you deployed that tenant with a Tenant CR. If you do, the operator creates another tenant by using the CR for the tenant that you tried to delete. To delete a deployed Tenant CR, you can specify the name of the file that contains the resource definition, for example: USD oc delete -f mytenant.yaml Alternatively, you can run the oc delete command, specify the name in the Tenant CR and also specify the tenant's namespace. For example: USD oc delete tenant.capabilities.3scale.net mytenant -n mynamespace When you delete a tenant, the 3scale operator does the following: Hides the tenant from the 3scale installation. Deletes the deployed CRs that the tenant owns. Marks the tenant to be deleted after 15 days. After you delete a tenant, you cannot recover it. You have 15 days to back up any resources that the tenant owned and you can do this only in the Admin Portal. After 15 days, 3scale deletes the tenant. To comply with data protection laws, some data is kept for future reference. Additional resources Tenant CRD Reference 8.13. Managing 3scale API Management 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. Important When you create developer accounts or developer users by deploying custom resources you cannot use the Admin Portal or the internal 3scale API to update those developer accounts or developer users. It is important to be aware of this because after you deploy a developer CR, the Admin Portal displays the new developer account or new developer user in its Accounts page. If you try to use the Admin Portal or API to update a developer account or developer user that was deployed with a CR, the 3scale operator reverts the changes to reflect the deployed CR. This is a limitation that is expected to be removed in a future release. You can, however, use the Admin Portal or API to delete a developer account or developer user that you created by deploying a CR. 8.13.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.13.2. Managing 3scale API Management 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 custom resources 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 custom resources only in the namespace that contains the 3scale operator. Prerequisites An understanding of how the 3scale API Management operator identifies the tenant that a custom resource links to . If you are creating a DeveloperAccount CR that does not link to the default tenant in the 3scale instance that is in the same namespace, then the namespace that will contain the DeveloperAccount CR contains a secret that identifies the tenant that the DeveloperAccount CR links to. The name of the secret is one of the following: threescale-provider-account User defined This secret contains the URL for a 3scale instance and a token that contains credentials for access to one tenant in that 3scale instance. You have the username, password, and email address for at least one developer user who will have the admin role in the new DeveloperAccount CR. Procedure In the namespace that contains the 3scale operator, create and save a resource file that defines a secret that contains the user name and password for a developer user who will have the admin role in the new developer account resource. For example, the myusername01.yaml file might contain: apiVersion: v1 kind: Secret metadata: name: myusername01 stringData: password: "123456" Create the secret. For example: USD oc create -f myusername01.yaml For the given example, the output would be: USD secret/myusername01 created Create and save a .yaml file that defines a DeveloperUser CR for a developer who has the admin role. This DeveloperUser CR is required for the 3scale operator to deploy a new DeveloperAccount CR. For example, the developeruser01.yaml file might contain: apiVersion: capabilities.3scale.net/v1beta1 kind: DeveloperUser metadata: name: developeruser01 spec: username: myusername01 email: myusername01@example.com passwordCredentialsRef: name: myusername01 role: admin developerAccountRef: name: developeraccount1 providerAccountRef: name: mytenant In a DeveloperUser CR: The developer user account name, user name, and email must be unique in the tenant that the containing DeveloperAccount links to. The developer account name that you specify here must match the name of the DeveloperAccount CR that you are deploying in this procedure. It does not matter whether you create the DeveloperAccount CR before or after you create this DeveloperUser CR. The tenant that a DeveloperUser CR links to must be the same tenant that the specified DeveloperAccount CR links to. Create the resource you just defined. For example: USD oc create -f developeruser01.yaml For the given example, the output would be: USD developeruser.capabilities.3scale.net/developeruser01 created Create and save a .yaml file that defines a DeveloperAccount CR. In this .yaml file, the spec.OrgName field must specify an organization name. For example, the developeraccount01.yaml file might contain: apiVersion: capabilities.3scale.net/v1beta1 kind: DeveloperAccount metadata: name: developeraccount01 spec: orgName: Ecorp providerAccountRef: name: mytenant Create the resource you just defined. For example: USD oc create -f developeraccount01.yaml For the given example, the output would be: USD developeraccount.capabilities.3scale.net/developeraccount01 created 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 CR status field or run the oc wait command, for example: USD 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 a deployed DeveloperAccount CR in the same way that you update any other custom resource. For example, in the OpenShift project that contains the tenant that owns the DeveloperAccount CR that you want to update, you would run the following command to update the devaccount1 CR: USD oc edit developeraccount devaccount1 Additional resources Deleting DeveloperAccount or DeveloperUser custom resources DeveloperAccount CRD Reference DeveloperUser CRD Reference 8.13.3. Managing 3scale API Management 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 CR that contains at least one deployed DeveloperUser CR for a user who has the admin role. If you are creating a DeveloperUser CR that does not link to the default tenant in the 3scale instance that is in the same namespace, then the namespace that will contain the DeveloperUser CR contains a secret that identifies the tenant that the DeveloperUser CR links to. The name of the secret is one of the following: threescale-provider-account User defined This secret contains the URL for a 3scale instance and a token that contains credentials for access to one tenant in that 3scale instance. For a new DeveloperUser CR, you have that developer's username, 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 username and password for a developer user. For example, the myusername02.yaml file might contain: apiVersion: v1 kind: Secret metadata: name: myusername02 stringData: password: "987654321" Create the secret. For example: USD oc create -f myusername02.yaml For the given example, the output would be: USD secret/myusername02 created Create and save a .yaml file that defines a DeveloperUser CR. In the spec.role field, specify admin or member . For example, the developeruser02.yaml file might contain: apiVersion: capabilities.3scale.net/v1beta1 kind: DeveloperUser metadata: name: developeruser02 spec: username: myusername02 email: myusername02@example.com passwordCredentialsRef: name: myusername02 role: member developerAccountRef: name: developeraccount1 providerAccountRef: name: mytenant In a DeveloperUser CR: The developer username (specified in the metadata.name field), the username, and email must be unique in the tenant that the containing DeveloperAccount links to. The developerAccountRef field must specify the name of a deployed DeveloperAccount CR. The tenant that a DeveloperUser CR links to must be the same tenant that the specified DeveloperAccount CR links to. Create the resource you just defined. For example: USD oc create -f developefuser02.yaml For the given example, the output would be: USD developeruser.capabilities.3scale.net/developeruser02 created 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 CR status field or run the oc wait command, for example: USD 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 a deployed DeveloperUser CR in the same way that you update any other custom resource. Additional resources Deleting DeveloperAccount or DeveloperUser custom resources DeveloperUser CRD Reference 8.13.4. Deleting DeveloperAccount or DeveloperUser custom resources You can delete a 3scale developer entity by deleting the custom resource (CR) that manages it. When you delete a DeveloperAccount CR the 3scale operator also deletes any DeveloperUser CRs that link to the deleted DeveloperAccount CR. Important The only way to delete a developer account or developer user defined by a custom resource is to follow the procedure described here. Do not use the Admin Portal nor the 3scale API to delete a developer entity that was deployed as a custom resource. Prerequisites 3scale administrator permissions or an OpenShift role that has delete permissions in the namespace that contains the custom resource you want to delete. To confirm that you can delete a particular custom resource, run the oc auth can-i delete command. For example, if the name in the DeveloperAccount CR is devaccount1 , run this command: USD oc auth can-i delete developeraccount.capabilities.3scale.net/devaccount1 -n my-namespace The DeveloperAccount or DeveloperUser CR to be deleted links to a valid tenant. Procedure In the OpenShift project that contains the tenant that the custom resource links to, run the oc delete command to delete a DeveloperAccount or DeveloperUser CR. For example, if you deployed a DeveloperAccount CR that was defined in the devaccount1.yaml file, you would run the following command: USD oc delete -f devaccount1.yaml Alternatively, you can run the oc delete command and specify the name of the CR as specified in its definition. For example: USD oc delete developeraccount.capabilities.3scale.net/devaccount1 8.14. Limitations of 3scale API Management operator capabilities In Red Hat 3scale API Management 2.15, 3scale operator contains these limitations with capabilities: Single sign-on (SSO) authentication for the Admin Portal. SSO authentication for the Developer Portal. 3scale operator CRD holding OAS3 does not reference as source of truth for 3scale product configuration. 8.15. Additional resources For more information, check the following guides: Backend CRD Reference Product CRD Reference CustomPolicyDefinition CRD Reference Tenant CRD Reference

Commands:
oc create secret generic threescale-provider-account --from-literal=adminURL=https://3scale-admin.example.com --from-literal=token=123456
apiVersion: capabilities.3scale.net/v1beta1 kind: Backend metadata: name: backend1 spec: name: "Operated Backend 1" systemName: "backend1" privateBaseURL: "https://api.example.com"
oc create -f backend1.yaml
apiVersion: capabilities.3scale.net/v1beta1 kind: Product metadata: name: product1 spec: name: "OperatedProduct 1" systemName: "operatedproduct1" backendUsages: backend1: path: /
oc create -f product1.yaml
oc apply -f product.yaml
oc wait --for=condition=Synced --timeout=-1s backend/backend1 oc wait --for=condition=Synced --timeout=-1s product/product1
apiVersion: capabilities.3scale.net/v1beta1 kind: ProxyConfigPromote metadata: name: proxyconfigpromote-sample spec: productCRName: product1-sample
apiVersion: capabilities.3scale.net/v1beta1 kind: ProxyConfigPromote metadata: name: proxyconfigpromote-sample spec: productCRName: product1-sample production: true
apiVersion: capabilities.3scale.net/v1beta1 kind: ProxyConfigPromote metadata: name: proxyconfigpromote-sample spec: productCRName: product1-sample deleteCR: true
oc get proxyconfigpromote proxyconfigpromote-sample -o yaml
apiVersion: capabilities.3scale.net/v1beta1 kind: ProxyConfigPromote metadata: name: proxyconfigpromote-sample spec: productCRName: product1-sample status: conditions: - lastTransitionTime: '2023-09-05T07:15:11Z' message: >- 3scale product has been successfully promoted, any further interactions with this CR (apart from deletion) won't be applied status: 'True' type: Ready latestStagingVersion: 1 productId: '7'
apiVersion: capabilities.3scale.net/v1beta1 kind: ProxyConfigPromote metadata: name: proxyconfigpromote-sample spec: productCRName: product1-sample status: conditions: - lastTransitionTime: '2023-09-05T07:48:08Z' message: >- cannot promote to production as no product changes detected. Delete this proxyConfigPromote CR, then introduce changes to configuration, and then create a new proxyConfigPromote CR status: 'True' type: Failed latestProductionVersion: 1 latestStagingVersion: 1 productId: '6'
create -f proxyconfigpromote-sample.yaml
proxyconfigpromote.capabilities.3scale.net/proxyconfigpromote-sample created
oc create secret generic threescale-provider-account --from-literal=adminURL=https://3scale-admin.example.com --from-literal=token=123456
apiVersion: capabilities.3scale.net/v1beta1 kind: DeveloperAccount metadata: name: developeraccount-simple-sample spec: orgName: Ecorp providerAccountRef: name: mytenant
apiVersion: v1 kind: Secret metadata: name: mytenant type: Opaque stringData: adminURL: https://my3scale-admin.example.com:443 token: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
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"
oc create secret generic myoasdoc1 --from-file myoasdoc1.yaml secret/myoasdoc1 created
apiVersion: capabilities.3scale.net/v1beta1 kind: OpenAPI metadata: name: myopenapicr1 spec: openapiRef: secretRef: name: myoasdoc1
oc create -f myopenapicr1.yaml
openapi.capabilities.3scale.net/myopenapicr1 created
openapi: "3.0.2" security: - petstore_api_key: [] components: securitySchemes: petstore_api_key: type: apiKey name: api_key in: header
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"
kind: Secret apiVersion: v1 metadata: name: my-secret namespace: 3scale-test data: issuerEndpoint: https://3scale-zync:some-secret@keycloak-rhsso-test.example.com/auth/realms/petstore type: Opaque
oc apply -f my-secret.yaml
apiVersion: capabilities.3scale.net/v1beta1 kind: OpenAPI metadata: generation: 1 name: openapi-example spec: openapiRef: url: "https://example.com/petstore.yaml" privateAPISecretToken: "xxxx" oidc: issuerType: keycloak issuerEndpointRef: name: my-secret jwtClaimWithClientID: azp jwtClaimWithClientIDType: plain authenticationFlow: standardFlowEnabled: true implicitFlowEnabled: true serviceAccountsEnabled: true directAccessGrantsEnabled: true gatewayResponse: errorStatusAuthFailed: 403
oc apply -f <openapi-cr-file>.yaml
apiVersion: capabilities.3scale.net/v1beta1 kind: OpenAPI metadata: generation: 1 name: openapi-example spec: openapiRef: url: "https://example.com/petstore.yaml" oidc: issuerType: keycloak issuerEndpoint: https://3scale-zync:some-secret@keycloak-rhsso-test.example.com/auth/realms/petstore issuerEndpointRef: name: my-secret jwtClaimWithClientID: azp jwtClaimWithClientIDType: plain authenticationFlow: standardFlowEnabled: true implicitFlowEnabled: true serviceAccountsEnabled: true directAccessGrantsEnabled: true
securitySchemes: myOauth: description: This API uses OAuth 2 with the implicit grant flow. link:https://api.example.com/docs/auth:[More information] flows: password: scopes: read_pets: read your pets write_pets: modify pets in your account tokenUrl: https://api.example.com/oauth2/token implicit: authorizationUrl: https://example.com/api/oauth/dialog scopes: write_pets: modify pets in your account read_pets: read your pets authorizationCode: authorizationUrl: https://example.com/api/oauth/dialog tokenUrl: https://example.com/api/oauth/token scopes: write_pets: modify pets in your account read_pets: read your pets clientCredentials: tokenUrl: https://example.com/api/oauth/token scopes: write_pets: modify pets in your account read_pets: read your pets type: oauth2
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
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"
oc create secret generic myoasdoc1 --from-file myoasdoc1.yaml secret/myoasdoc1 created
apiVersion: capabilities.3scale.net/v1beta1 kind: ActiveDoc metadata: name: myactivedoccr1 spec: name: "Operated ActiveDoc From secret" activeDocOpenAPIRef: secretRef: name: myoasdoc1
oc create -f myactivedoccr1.yaml
activedoc.capabilities.3scale.net/myactivedoccr1 created
apiVersion: capabilities.3scale.net/v1beta1 kind: ActiveDoc metadata: name: myactivedoccr1 spec: openapiRef: url: "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml" providerAccountRef: name: mytenant
apiVersion: capabilities.3scale.net/v1beta1 kind: ActiveDoc metadata: name: myactivedoccr1 spec: openapiRef: url: "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml" productionPublicBaseURL: "https://production.my-gateway.example.com" stagingPublicBaseURL: "https://staging.my-gateway.example.com"
apiVersion: capabilities.3scale.net/v1beta1 kind: Backend metadata: name: <your_backend_OpenShift_name> spec: name: "<your_backend_name>" privateBaseURL: "<your_admin_portal_URL>"
apiVersion: capabilities.3scale.net/v1beta1 kind: Backend metadata: name: backend-1 spec: name: "My Backend Name" privateBaseURL: "https://api.example.com"
apiVersion: capabilities.3scale.net/v1beta1 kind: Backend metadata: name: backend-1 spec: name: "My Backend Name" privateBaseURL: "https://api.example.com" metrics: metric01: friendlyName: Metric01 unit: "1" metric02: friendlyName: Metric02 unit: "1" hits: description: Number of API hits friendlyName: Hits unit: "hit
apiVersion: capabilities.3scale.net/v1beta1 kind: Backend metadata: name: backend-1 spec: name: "My Backend Name" privateBaseURL: "https://api.example.com" methods: method01: friendlyName: Method01 method02: friendlyName: Method02
apiVersion: capabilities.3scale.net/v1beta1 kind: Backend metadata: name: backend-1 spec: name: "My Backend Name" privateBaseURL: "https://api.example.com" 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"
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
apiVersion: capabilities.3scale.net/v1beta1 kind: Backend metadata: name: backend-1 spec: name: "My Backend Name" privateBaseURL: "https://api.example.com" providerAccountRef: name: mytenant
apiVersion: v1 kind: Secret metadata: name: mytenant type: Opaque stringData: adminURL: https://my3scale-admin.example.com:443 token: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
oc create secret generic threescale-provider-account --from-literal=adminURL=https://3scale-admin.example.com --from-literal=token=123456
oc policy who-can delete product.capabilities.3scale.net/mybackend
oc delete -f mybackend.yaml
oc delete backend.capabilities.3scale.net/mybackend
apiVersion: capabilities.3scale.net/v1beta1 kind: Product metadata: name: <your_product_OpenShift_name> spec: name: "<your_product_name>"
apiVersion: capabilities.3scale.net/v1beta1 kind: Product metadata: name: product1 spec: name: "OperatedProduct 1"
apiVersion: capabilities.3scale.net/v1beta1 kind: Product metadata: name: product1 spec: name: "OperatedProduct 1" deployment: apicastHosted: {}
apiVersion: capabilities.3scale.net/v1beta1 kind: Product metadata: name: product1 spec: name: "OperatedProduct 1" deployment: apicastSelfManaged: stagingPublicBaseURL: "https://staging.api.example.com" productionPublicBaseURL: "https://production.api.example.com"
apiVersion: capabilities.3scale.net/v1beta1 kind: Product metadata: name: product1 spec: name: "OperatedProduct 1" applicationPlans: plan01: name: "My Plan 01" setupFee: "14.56" plan02: name: "My Plan 02" trialPeriod: 3 costMonth: 3
apiVersion: capabilities.3scale.net/v1beta1 kind: Product metadata: name: product1 spec: name: "OperatedProduct 1" metrics: hits: description: Number of API hits friendlyName: Hits unit: "hit" applicationPlans: plan01: name: "My Plan 01" limits: - period: month value: 300 metricMethodRef: systemName: hits backend: backendA - period: week value: 100 metricMethodRef: systemName: hits
apiVersion: capabilities.3scale.net/v1beta1 kind: Product metadata: name: product1 spec: name: "OperatedProduct 1" metrics: hits: description: Number of API hits friendlyName: Hits unit: "hit" applicationPlans: plan01: name: "My Plan 01" pricingRules: - from: 1 to: 100 pricePerUnit: "15.45" metricMethodRef: systemName: hits - from: 1 to: 300 pricePerUnit: "15.45" metricMethodRef: systemName: hits backend: backendA
https://<client_id>:<client_secret>@<host>:<port_number>/auth/realms/<realm_name>`
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"
oc create -f product1.yaml
product.capabilities.3scale.net/product1 created
apiVersion: capabilities.3scale.net/v1beta1 kind: Product metadata: name: product1 spec: name: "OperatedProduct 1" metrics: metric01: friendlyName: Metric01 unit: "1" hits: description: Number of API hits friendlyName: Hits unit: "hit"
apiVersion: capabilities.3scale.net/v1beta1 kind: Product metadata: name: product1 spec: name: "OperatedProduct 1" methods: method01: friendlyName: Method01 method02: friendlyName: Method02
apiVersion: capabilities.3scale.net/v1beta1 kind: Product metadata: name: product1 spec: name: "OperatedProduct 1" metrics: hits: description: Number of API hits friendlyName: Hits unit: "hit" methods: method01: friendlyName: Method01 mappingRules: - httpMethod: GET pattern: "/pets" increment: 1 metricMethodRef: hits - httpMethod: GET pattern: "/cars" increment: 1 metricMethodRef: method01
apiVersion: capabilities.3scale.net/v1beta1 kind: Product metadata: name: product1 spec: name: "OperatedProduct 1" backendUsages: backendA: path: /A backendB: path: /B
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"
oc create -f product1.yaml
product.capabilities.3scale.net/product1 created
apiVersion: capabilities.3scale.net/v1beta1 kind: Product metadata: name: product1 spec: name: "OperatedProduct 1" policies: - configuration: http_proxy: http://example.com https_proxy: https://example.com enabled: true name: camel version: builtin - configuration: {} enabled: true name: apicast version: builtin
apiVersion: v1 kind: Secret metadata: name: my-config-policy type: Opaque stringData: configuration: "{\"http_proxy\":\"http://secret.com\"}" --- apiVersion: capabilities.3scale.net/v1beta1 kind: Product metadata: name: product2 spec: name: "OperatedProduct 2" policies: - configurationRef: name: my-config-policy enabled: true name: camel version: builtin - configuration: {} enabled: true name: apicast version: builtin
3scale policies export api-provider-account-one my-api-product-one
oc create -f product1.yaml
product.capabilities.3scale.net/product1 created
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
apiVersion: capabilities.3scale.net/v1beta1 kind: Product metadata: name: product1 spec: name: "OperatedProduct 1" providerAccountRef: name: mytenant
apiVersion: v1 kind: Secret metadata: name: mytenant type: Opaque stringData: adminURL: https://my3scale-admin.example.com:443 token: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
oc create secret generic threescale-provider-account --from-literal=adminURL=https://3scale-admin.example.com --from-literal=token=123456
oc policy who-can delete product.capabilities.3scale.net/myproduct
oc delete -f myproduct.yaml
oc delete product.capabilities.3scale.net/myproduct
apiVersion: capabilities.3scale.net/v1beta1 kind: Application metadata: name: example namespace: 3scale_project_name spec: accountCR: name: developer_account applicationPlanName: application_plan_name productCR: name: product_custom_resource name: application_name description: describe_your_application
oc policy who-can delete application.capabilities.3scale.net/myapplication
oc delete -f myapplication.yaml
oc delete application.capabilities.3scale.net/myapplication
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" USDschema: "http://apicast.io/policy-v1/schema#manifest#" summary: "This is just an example." configuration: type: object properties: {}
oc create -f my-apicast-custom-policy-definition.yaml
oc project my-3scale-project
oc create secret generic ecorp-admin-secret --from-literal=admin_password=<admin password value>
oc get routes --field-selector=spec.to.name==system-master -o jsonpath="{.items[].spec.host}"
apiVersion: capabilities.3scale.net/v1alpha1 kind: Tenant metadata: generation: 3 name: <ecorp_tenant> namespace: <namespace_in_which_to_create_tenant-CR> spec: email: admin@ecorp.com masterCredentialsRef: name: system-seed namespace: <namespace-where-3scale-is-deployed> organizationName: ECorp passwordCredentialsRef: name: <admin_secret> namespace: <namespace_in_which_to_create_tenant-CR> systemMasterUrl: https://<master_hostname> tenantSecretRef: name: <tenant_secret> namespace: <namespace_in_which_to_create_tenant-CR> username: tenant2FromCR1
oc create -f mytenant.yaml
apiVersion: v1 kind: Secret metadata: name: <tenant_secret> type: Opaque stringData: adminURL: https://my3scale-admin.example.com:443 token: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
apiVersion: capabilities.3scale.net/v1alpha1 kind: Tenant metadata: generation: 3 name: <ecorp_tenant> namespace: <namespace_in_which_to_create_tenant-CR> spec: email: admin@ecorp.com masterCredentialsRef: name: system-seed namespace: <namespace-where-3scale-is-deployed> organizationName: ECorp passwordCredentialsRef: name: <admin_secret> namespace: <namespace_in_which_to_create_tenant-CR> systemMasterUrl: https://<master_hostname> tenantSecretRef: name: <tenant_secret> namespace: <namespace_in_which_to_create_tenant-CR> username: <tenant2FromCR1> fromEmail: <tenant2FromCR1>@ecorp.com supportEmail: <tenant2Support>@ecorp.com financeSupportEmail: <tenant2FinanceSupport>@ecorp.com siteAccessCode: <abc123>
oc apply -f mytenant.yaml
oc delete -f mytenant.yaml
oc delete tenant.capabilities.3scale.net mytenant -n mynamespace
apiVersion: v1 kind: Secret metadata: name: myusername01 stringData: password: "123456"
oc create -f myusername01.yaml
secret/myusername01 created
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
oc create -f developeruser01.yaml
developeruser.capabilities.3scale.net/developeruser01 created
apiVersion: capabilities.3scale.net/v1beta1 kind: DeveloperAccount metadata: name: developeraccount01 spec: orgName: Ecorp providerAccountRef: name: mytenant
oc create -f developeraccount01.yaml
developeraccount.capabilities.3scale.net/developeraccount01 created
oc wait --for=condition=Ready --timeout=30s developeraccount/developeraccount1
oc edit developeraccount devaccount1
apiVersion: v1 kind: Secret metadata: name: myusername02 stringData: password: "987654321"
oc create -f myusername02.yaml
secret/myusername02 created
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
oc create -f developefuser02.yaml
developeruser.capabilities.3scale.net/developeruser02 created
oc wait --for=condition=Ready --timeout=30s developeruser/developeruser02
oc auth can-i delete developeraccount.capabilities.3scale.net/devaccount1 -n my-namespace
oc delete -f devaccount1.yaml
oc delete developeraccount.capabilities.3scale.net/devaccount1