Menu Close
Settings Close

Language and Page Formatting Options

Chapter 4. Mapping API environments in 3scale

An API provider gives access to the APIs it owns through the 3scale Admin Portal. You may deploy the API back ends in many environments. These back-end environments can include the following:

  • Different environments used for development, quality assurance, staging, and production.
  • Different environments used for teams or departments that manage their own set of API back ends.

A Red Hat 3scale API Management service can represent a single API or subset of an API, but can also be used to map and manage different API back-end environments.

This chapter covers the following topics:

  • Setting up the environments.
  • Setting up the number of gateways being used.
  • Configuring THREESCALE_PORTAL_ENDPOINT and the public base URL using more than two environments.

    • For example, development, quality assurance, or production environment.
  • Operations on how to copy/promote from one environment to another.

    • For example, promoting quality assurance to production.

4.1. Service per environment

This method uses a separate 3scale service for each API back-end environment. In each service you can configure a production gateway and a staging gateway, so these changes to the gateway configuration can be tested safely and promoted to the production configuration as you would with your API back-ends services.

Production Service => Production Service APIcast gateway => Production Service API upstream.
Staging Service => Staging Service APIcast gateway => Staging Service API backend.

The private base URL for both the production and staging gateway is set to the API back end in the environment being mapped for which this 3scale service is being configured as shown in the following examples:

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

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


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.

4.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 services within a single tenant.
  • Create a 1-to-1 mapping between environments and tenants with one or more services 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.

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.

4.3. Mixed approach

The approaches described in Section 4.2, “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

4.4. APIcast gateway

A 3scale on-premises installation offers multiple choices for APIcast gateways:

  • Each 3scale installation comes with two built-in APIcast gateways, for staging and production.
  • Additional APIcast gateways can be deployed externally to the OpenShift cluster on which the 3scale instance is running.

4.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 Section 4.4, “APIcast gateway” 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>

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


The THREESCALE_PORTAL_ENDPOINT is used by APIcast to download the configuration. Given that a separate APIcast gateway is used for each tenant that maps to an API back-end environment, the THREESCALE_PORTAL_ENDPOINT is set to the Admin Portal for the tenant that contains all the service configurations specific to that API back-end 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.