Chapter 3. Running APIcast on Red Hat OpenShift

download PDF

This tutorial describes how to deploy the APIcast API Gateway on Red Hat OpenShift.


  • You must configure APIcast in your Red Hat 3scale API Management Admin Portal as per Chapter 2, Installing APIcast.
  • Make sure Self-managed Gateway is selected as the deployment option in the integration settings.
  • You should have both staging and production environment configured to proceed.

To run APIcast on Red Hat OpenShift, perform the steps outlined in the following sections:

3.1. Setting up Red Hat OpenShift

If you already have a running OpenShift cluster, you can skip this section. Otherwise, continue reading.

For production deployments you can follow the instructions for OpenShift installation.

In this tutorial the OpenShift cluster will be installed using:

  • Red Hat Enterprise Linux (RHEL) 7
  • Docker containerized environment v1.10.3
  • OpenShift Origin command line interface (CLI) - v1.3.1

Use the following section to set up Red Hat OpenShift:

3.1.1. Installing the Docker containerized environment

Docker-formatted container images provided by Red Hat are released as part of the Extras channel in RHEL. To enable additional repositories, you can use either the Subscription Manager, or yum config manager. See the RHEL product documentation for details.

For a RHEL 7 deployed on a AWS EC2 instance you will use the following the instructions:


  1. List all repositories:

    sudo yum repolist all
  2. Find and enable the *-extras repository:

    sudo yum-config-manager --enable rhui-REGION-rhel-server-extras
  3. Install Docker-formatted container images:

    sudo yum install docker docker-registry
  4. Add an insecure registry of by adding or uncommenting the following line in /etc/sysconfig/docker file:

  5. Start the Docker service:

    sudo systemctl start docker
  6. Verify that the container service is running with the following command:

    sudo systemctl status docker

3.1.2. Starting the OpenShift cluster

To start the OpenShift cluster, do the following:


  1. Download the latest stable release of the client tools (openshift-origin-client-tools-VERSION-linux-64bit.tar.gz) from OpenShift releases page, and place the Linux oc binary extracted from the archive in your PATH.


    The docker command runs as the root user, so you will need to run any oc or docker commands with root privileges.

  2. Open a terminal with a user that has permission to run docker commands and run:

    oc cluster up

    At the bottom of the output you will find information about the deployed cluster:

        -- Server Information ...
          OpenShift server started.
          The server is accessible via web console at:

          You are logged in as:
            User:     developer
            Password: developer
          To login as administrator:
            oc login -u system:admin
  3. Note the IP address that is assigned to your OpenShift server. You will refer to it in the tutorial as OPENSHIFT-SERVER-IP.

3.1.3. Setting up the OpenShift cluster on a remote server (Optional)

If you are deploying the OpenShift cluster on a remote server, you will need to explicitly specify a public hostname and a routing suffix on starting the cluster, so that you will be able to access the OpenShift web console remotely.

For example, if you are deploying on an AWS EC2 instance, you should specify the following options:

oc cluster up

where is the Public Domain, and 54.321.67.89 is the IP of the instance. You will then be able to access the OpenShift web console at

3.2. Deploying APIcast using the OpenShift template

  • You can only deploy APIcast on OpenShift Container Platform (OCP) 3.11 when using templates.
  • Operator-based installations are only supported on OCP version 4.1 and 4.2.
  • For more information about supported configurations, see the Red Hat 3scale API Management Supported Configurations page.

Use the following to deploy APIcast unsing the OpenShift template:


  1. By default you are logged in as developer and can proceed to the next step.

    Otherwise login into OpenShift using the oc login command from the OpenShift Client tools you downloaded and installed in the previous step. The default login credentials are username = "developer" and password = "developer":

    oc login https://OPENSHIFT-SERVER-IP:8443

    You should see Login successful. in the output.

  2. Create your project. This example sets the display name as gateway

    oc new-project "3scalegateway" --display-name="gateway" --description="3scale gateway demo"

    The response should look like this:

    Now using project "3scalegateway" on server ""

    Ignore the suggested next steps in the text output at the command prompt and proceed to the next step below.

  3. Create a new secret to reference your project by replacing <access_token> and <domain> with your own credentials. See below for more information about the <access_token> and <domain>.

    oc create secret generic apicast-configuration-url-secret --from-literal=password=https://<access_token>@<admin_portal_domain>

    Here <access_token> is an Access Token for the 3scale account, and <domain> is the URL of your 3scale Admin Portal.

    The response should look like this:

  4. Create an application for your APIcast gateway from the template, and start the deployment:

    oc new-app -f

    You should see the following messages at the bottom of the output:

        --> Creating resources with label app=3scale-gateway ...
            deploymentconfig "apicast" created
            service "apicast" created
        --> Success
            Run 'oc status' to view your app.

3.3. Creating routes via the OpenShift console

To create routes via the OpenShift console, do the following:


  1. Open the web console for your OpenShift cluster in your browser:


    Use the value specified in --public-hostname instead of OPENSHIFT-SERVER-IP if you started OpenShift cluster on a remote server.

    You will see the login screen for OpenShift.


    You may receive a warning about an untrusted website. This is expected, as you are trying to access the web console through secure protocol, without having configured a valid certificate. While you should avoid this in production environment, for this test setup you can go ahead and create an exception for this address.

  2. Log in using the developer credentials created or obtained in the Setting up Red Hat OpenShift section.

    You will see a list of projects, including the gateway project you created from the command line above.

    Openshift Projects

    If you do not see your gateway project, you probably created it with a different user and will need to assign the policy role to to this user.

  3. Click on the gateway link and you will see the Overview tab.

    OpenShift downloaded the code for APIcast and started the deployment. You may see the message Deployment #1 running when the deployment is in progress.

    When the build completes, the user interface (UI) will refresh and show two instances of APIcast ( 2 pods ) that have been started by OpenShift, as defined in the template.

    Building the Gateway

    Each APIcast instance, upon starting, downloads the required configuration from 3scale using the settings you provided on the Integration page of your 3scale Admin Portal.

    OpenShift will maintain two APIcast instances and monitor the health of both; any unhealthy APIcast instance will automatically be replaced with a new one.

  4. To allow your APIcast instances to receive traffic, you need to create a route. Start by clicking on Create Route.

    Create Route

    Enter the same host you set in 3scale above in the section Public Base URL (without the http:// and without the port) , e.g. gateway.openshift.demo, then click the Create button.

    Configure Route

    For every 3scale product you define, you must create a new route.

Red Hat logoGithubRedditYoutubeTwitter


Try, buy, & sell


About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.