Chapter 6. Mapping API environments in 3scale

An API provider gives access to the APIs managed through the 3scale Admin Portal. You then deploy the API backends in many environments. API backend environments include the following:

  • Different environments used for development, quality assurance (QA), staging, and production.
  • Different environments used for teams or departments that manage their own set of API backends.

A Red Hat 3scale API Management product represents a single API or subset of an API, but it is also used to map and manage different API backend environments.

To find out about mapping API environments for your 3scale product, see the following sections:

6.1. Product per environment

This method uses a separate 3scale Product for each API backend environment. In each product, configure a production gateway and a staging gateway, so the changes to the gateway configuration can be tested safely and promoted to the production configuration as you would with your API backends. 

Production Product => Production Product APIcast gateway => Production Product API upstream
Staging Product => Staging Product APIcast gateway => Staging Product API upstream

Configure the product for the API backend environment as follows:

Development environment

  • Create development backend

    • Name: Dev
    • Private Base URL: URL of the API backend

  • Create Dev product

    • Production Public Base URL: https://dev-api-backend.yourdomain.com
    • Staging Public Base URL: https://dev-api-backend.yourdomain.com
    • Add Dev Backend with a backend path /

QA environment

  • Create QA backend

    • Name: QA
    • Private Base URL: URL of the API backend

  • Create QA product

    • Production Public Base URL: https://qa-api-backend.yourdomain.com
    • Staging Public Base URL: https://qa-api-backend.yourdomain.com
    • Add QA Backend with a backend path /

Production environment

  • Create production backend

    • Name: Prod
    • Private Base URL: URL of the API backend

  • Create Prod product

    • Production Public Base URL: https://prod-api-backend.yourdomain.com
    • Staging Public Base URL: https://prod-api-backend.yourdomain.com
    • Add production Backend with a backend path /

Additional resources

6.2. 3scale On-premises instances

For 3scale On-premises instances, there are multiple ways to set up 3scale to manage API back-end environments.

  • A separate 3scale instance for each API back-end environment
  • A single 3scale instance that uses the multitenancy feature

6.2.1. Separating 3scale instances per environment

In this approach a separate 3scale instance is deployed for each API back-end environment. The benefit of this architecture is that each environment will be isolated from one another, therefore there are no shared databases or other resources. For example, any load testing being done in one environment will not impact the resources in other environments.

Note

This separation of installations has benefits as described above, however, it would require more operational resources and maintenance. These additional resources would be required on the OpenShift administration layer and not necessarily on the 3scale layer.

6.2.2. Separating 3scale tenants per environment

In this approach a single 3scale instance is used but the multitenancy feature is used to support multiple API back ends.

There are two options:

  • Create a 1-to-1 mapping between environments and 3scale products within a single tenant.

  • Create a 1-to-1 mapping between environments and tenants with one or more products per tenant as required.

    • There would be three tenants corresponding to API back-end environments - dev-tenant, qa-tenant, prod-tenant. The benefit of this approach is that it allows for a logical separation of environments but uses shared physical resources.
Note

Shared physical resources will ultimately need to be taken into consideration when analysing the best strategy for mapping API environments to a single installation with multiple tenants.

6.3. 3scale mixed approach

The approaches described in 3scale On-premises instances can be combined. For example:

  • A separate 3scale instance for production
  • A separate 3scale instance with separate tenant for non-production environments in dev and qa

6.4. 3scale with APIcast gateways

For 3scale On-premises instances, there are two alternatives to set up 3scale to manage API backend environments:

  • Each 3scale installation comes with two built-in APIcast gateways, for staging and production.
  • Deploy additional APIcast gateways externally to the OpenShift cluster where 3scale is running.

6.4.1. APIcast built-in default gateways

When APIcast built-in gateways are used, the API back end configured using the above approaches described in 3scale with APIcast gateways will be handled automatically. When a tenant is added by a 3scale Master Admin, a route is created for the tenant in production and staging built-in APIcast gateways. See Understanding multitenancy subdomains

  • <API_NAME>-<TENANT_NAME>-apicast.staging.<WILDCARD_DOMAIN>
  • <API_NAME>-<TENANT_NAME>-apicast.production.<WIDLCARD_DOMAIN>

Therefore, each API back-end environment mapped to a different tenant would get its own route. For example:

  • Dev <API_NAME>-dev-apicast.staging.<WILDCARD_DOMAIN>
  • QA <API_NAME>-qa-apicast.staging.<WILDCARD_DOMAIN>
  • Prod <API_NAME>-prod-apicast.staging.<WILDCARD_DOMAIN>

6.4.2. Additional APIcast gateways

Additional APIcast gateways are those deployed on a different OpenShift cluster than the one on which 3scale instance is running. There is more than one way to set up and use additional APIcast gateways. The value of environment variable THREESCALE_PORTAL_ENDPOINT used when starting APIcast depends how the additional APIcast gateways are set up.

A separate APIcast gateway can be used for each API back-end environment. For example: 

DEV_APICAST -> DEV_TENANT ; DEV_APICAST started with THREESCALE_PORTAL_ENDPOINT = admin portal for DEV_TENANT
QA_APICAST -> QA_TENANT ; QA_APICAST started with THREESCALE_PORTAL_ENDPOINT = admin portal for QA_APICAST
PROD_APICAST -> PROD_TENANT ; PROD_APICAST started with THREESCALE_PORTAL_ENDPOINT = admin portal for PROD_APICAST

The THREESCALE_PORTAL_ENDPOINT is used by APIcast to download the configuration. Each tenant that maps to an API backend environment uses a separate APIcast gateway. The THREESCALE_PORTAL_ENDPOINT is set to the Admin Portal for the tenant containing all the product configurations specific to that API backend environment.

A single APIcast gateway can be used with multiple API back-end environments. In this case THREESCALE_PORTAL_ENDPOINT is set to the Master Admin Portal.

Additional resources

  • For more information about the API provider, see the glossary.
  • For more information about the 3scale product, see the glossary.