Chapter 3. Installing APIcast

APIcast is an NGINX based API gateway used to integrate your internal and external API services with the Red Hat 3scale API Management Platform. APIcast does load balancing by using round-robin.

In this guide you will learn about deployment options, environments provided, and how to get started.

Prerequisites

APIcast is not a standalone API gateway. It needs connection to 3scale API Manager.

To install APIcast, perform the steps outlined in the following sections:

3.1. APIcast deployment options

You can use hosted or self-managed APIcast. In both cases, APIcast must be connected to the rest of the 3scale API Management platform:

  • Embedded APIcast: Two APIcast gateways (staging and production) come by default with the 3scale API Management installation. They come pre-configured and ready to use out-of-the-box.
  • Self-managed APIcast: You can deploy APIcast wherever you want. Here are a few recommended options to deploy APIcast:

3.2. APIcast environments

By default, when you create a 3scale account, you get embedded APIcast in two different environments:

  • Staging: Intended to be used only while configuring and testing your API integration. When you have confirmed that your setup is working as expected, then you can choose to deploy it to the production environment. The OpenShift template sets the parameters of the Staging APIcast in a way that the configuration is reloaded on each API call (APICAST_CONFIGURATION_LOADER: lazy, APICAST_CONFIGURATION_CACHE: 0). It is useful to test the changes in APIcast configuration quickly.
  • Production: This environment is intended for production use. The following parameters are set for the Production APIcast in the OpenShift template: APICAST_CONFIGURATION_LOADER: boot, APICAST_CONFIGURATION_CACHE: 300. This means that the configuration will be fully loaded when APIcast is started, and will be cached for 300 seconds (5 minutes). After 5 minutes the configuration will be reloaded. This means that when you promote the configuration to production, it may take up to 5 minutes to be applied, unless you trigger a new deployment of APIcast.

3.3. Configuring the integration settings

As a 3scale administrator, configure the integration settings for the environment you require 3scale to run in.

Prerequisites

A 3scale account with administrator privileges.

Procedure

  1. Navigate to [Your_API_name] > Integration > Settings.
  2. Under Deployment, the default options are as follows:

    • Deployment Option: APIcast 3scale managed
    • Authentication mode: API key.
  3. Change to your preferred option.
  4. To save your changes, click Update Product.

3.4. Configuring your service

You must declare your API back-end in the Private Base URL field, which is the endpoint host of your API back-end. APIcast will redirect all traffic to your API back-end after all authentication, authorization, rate limits and statistics have been processed.

This section will guide you through configuring your service:

3.4.1. Declaring the API backend

Typically, the Private Base URL of your API will be something like https://api-backend.yourdomain.com:443, on the domain that you manage (yourdomain.com). For instance, if you were integrating with the Twitter API the Private Base URL would be https://api.twitter.com/.

In this example, you will use the Echo API hosted by 3scale, a simple API that accepts any path and returns information about the request (path, request parameters, headers, etc.). Its Private Base URL is https://echo-api.3scale.net:443.

Procedure

  • Test your private (unmanaged) API is working. For example, for the Echo API you can make the following call with curl command:

    curl "https://echo-api.3scale.net:443"

    You will get the following response:

    {
        "method": "GET",
        "path": "/",
        "args": "",
        "body": "",
        "headers": {
          "HTTP_VERSION": "HTTP/1.1",
          "HTTP_HOST": "echo-api.3scale.net",
          "HTTP_ACCEPT": "*/*",
          "HTTP_USER_AGENT": "curl/7.51.0",
          "HTTP_X_FORWARDED_FOR": "2.139.235.79, 10.0.103.58",
          "HTTP_X_FORWARDED_HOST": "echo-api.3scale.net",
          "HTTP_X_FORWARDED_PORT": "443",
          "HTTP_X_FORWARDED_PROTO": "https",
          "HTTP_FORWARDED": "for=10.0.103.58;host=echo-api.3scale.net;proto=https"
        },
        "uuid": "ee626b70-e928-4cb1-a1a4-348b8e361733"
      }

3.4.2. Configuring the authentication settings

You can configure authentication settings for your API in the AUTHENTICATION section under [Your_product_name] > Integration > Settings.

Table 3.1. Optional authentication fields

FieldDescription

Auth user key

Set the user key associated with the credentials location.

Credentials location

Define whether credentials are passed as HTTP headers, query parameters or as HTTP basic authentication.

Host Header

Define a custom Host request header. This is required if your API backend only accepts traffic from a specific host.

Secret Token

Used to block direct developer requests to your API backend. Set the value of the header here, and ensure your backend only allows calls with this secret header.

Furthermore, you can configure the GATEWAY RESPONSE error codes under [Your_product_name] > Integration > Settings. Define the Response Code, Content-type, and Response Body for the errors: Authentication failed, Authentication missing, and No match.

Table 3.2. Response codes and default response body

Response codeResponse body

403

Authentication failed

403

Authentication parameters missing

404

No Mapping Rule matched

429

Usage limit exceeded

3.4.3. Configuring the API test call

Configuring the API involves testing the backends with a product and promoting the APIcast configuration to staging and production environments to make tests based on request calls.

For each product, requests get redirected to their corresponding backend according to the path. This path is configured when you add the backend to the product. For example, if you have two backends added to a product, each backend has its own path.

Prerequisites

Procedure

  1. Promote an APIcast configuration to Staging, by navigating to [Your_product_name] > Integration > Configuration.
  2. Under APIcast Configuration, you will see the mapping rules for each backend added to the product. Click Promote v.[n] to Staging APIcast.

    • v.[n] indicates the version number to be promoted.
  3. Once promoted to staging, you can promote to Production. Under Staging APIcast, click Promote v.[n] to Production APIcast.

    • v.[n] indicates the version number to be promoted.
  4. To test requests to your API in the command line, use the command provided in Example curl for testing.

    • The curl command example is based on the first mapping rule in the product.

When testing requests to your API, you can modify the mapping rules by adding methods and metrics.

Every time you modify the configuration and before making calls to your API, make sure you promote to the Staging and Production environments. When there are pending changes to be promoted to the Staging environment, you will see an exclamation mark in the Admin Portal, next to the Integration menu item.

3scale Hosted APIcast gateway does the validation of the credentials and applies the rate limits that you defined for the application plan of your API. If you make a call without credentials, or with invalid credentials, you will see the error message, Authentication failed.

3.5. Installing the APIcast operator

This guide provides steps for installing the APIcast operator through the OpenShift Container Platform (OCP) console.

Procedure

  1. Log in to the OCP console using an account with administrator privileges.
  2. Create new project operator-test in Projects > Create Project.
  3. Click Operators > Installed Operators
  4. Type apicast in the Filter by keyword box to find the APIcast operator. Do not use the community version.
  5. Click the APIcast operator. You will see information about the APIcast operator.
  6. Click Install. The Create Operator Subscription page opens.
  7. Click Subscribe to accept all of the default selections on the Create Operator Subscription page.

    1. The subscription upgrade status is shown as Up to date.
  8. Click Operators > Installed Operators to verify that the APIcast operator ClusterServiceVersion (CSV) status displays to InstallSucceeded in the operator-test project.

3.6. Deploying an APIcast gateway self-managed solution using the operator

This guide provides steps for deploying an APIcast gateway self-managed solution using the APIcast operator via the Openshift Container Platform console.

Prerequisites

Procedure

  1. Log in to the OCP console using an account with administrator privileges.
  2. Click Operators > Installed Operators.
  3. Click the APIcast Operator from the list of Installed Operators.
  4. Click the APIcast > Create APIcast.

3.6.1. APICast deployment and configuration options

You can deploy and configure an APIcast gateway self-managed solution using two approaches:

3.6.1.1. Providing a 3scale system endpoint

Procedure

  1. Create an OpenShift secret that contains 3scale System Admin Portal endpoint information:

    oc create secret generic ${SOME_SECRET_NAME} --from-literal=AdminPortalURL=${MY_3SCALE_URL}
    • ${SOME_SECRET_NAME} is the name of the secret and can be any name you want as long as it does not conflict with an existing secret.
    • ${MY_3SCALE_URL} is the URI that includes your 3scale access token and 3scale System portal endpoint. For more details, see THREESCALE_PORTAL_ENDPOINT

      Example

      oc create secret generic 3scaleportal --from-literal=AdminPortalURL=https://access-token@account-admin.3scale.net

      For more information about the contents of the secret see the Admin portal configuration secret reference.

  2. Create the OpenShift object for APIcast

    apiVersion: apps.3scale.net/v1alpha1
    kind: APIcast
    metadata:
      name: example-apicast
    spec:
      adminPortalCredentialsRef:
        name: SOME_SECRET_NAME

    The spec.adminPortalCredentialsRef.name must be the name of the existing OpenShift secret that contains the 3scale system Admin Portal endpoint information.

  3. Verify the APIcast pod is running and ready, by confirming that the readyReplicas field of the OpenShift Deployment associated with the APIcast object is 1. Alternatively, wait until the field is set with:

    $ echo $(oc get deployment apicast-example-apicast -o jsonpath='{.status.readyReplicas}')
    1
3.6.1.1.1. Verifying the APIcast gateway is running and available

Procedure

  1. Ensure the OpenShift Service APIcast is exposed to your local machine, and perform a test request. Do this by port-forwarding the APIcast OpenShift Service to localhost:8080:

    oc port-forward svc/apicast-example-apicast 8080
  2. Make a request to a configured 3scale service to verify a successful HTTP response. Use the domain name configured in Staging Public Base URL or Production Public Base URL settings of your service. For example:

    $ curl 127.0.0.1:8080/test -H "Host: myhost.com"
3.6.1.1.2. Exposing APIcast externally via a Kubernetes Ingress

To expose APIcast externally via a Kubernetes Ingress, set and configure the exposedHost section. When the host field in the exposedHost section is set, this creates a Kubernetes Ingress object. The Kubernetes Ingress object can then be used by a previously installed and existing Kubernetes Ingress Controller to make APIcast accessible externally.

To learn what Ingress Controllers are available to make APIcast externally accessible and how they are configured see the Kubernetes Ingress Controllers documentation.

The following example to expose APIcast with the hostname myhostname.com:

apiVersion: apps.3scale.net/v1alpha1
kind: APIcast
metadata:
  name: example-apicast
spec:
  ...
  exposedHost:
    host: "myhostname.com"
  ...

The example creates a Kubernetes Ingress object on the port 80 using HTTP. When the APIcast deployment is in an OpenShift environment, the OpenShift default Ingress Controller will create a Route object using the Ingress object APIcast creates which allows external access to the APIcast installation.

You may also configure TLS for the exposedHost section. Details about the available fields in the following table:

Table 3.3. APIcastExposedHost reference table

json/yaml fieldTypeRequiredDefault valueDescription

host

string

Yes

N/A

Domain name being routed to the gateway

tls

[]extensions.IngressTLS

No

N/A

Array of ingress TLS objects. See more on TLS.

3.6.1.2. Providing a configuration secret

Procedure

  1. Create a secret with the configuration file:

    $ curl https://raw.githubusercontent.com/3scale/APIcast/master/examples/configuration/echo.json -o $PWD/config.json
    
    oc create secret generic apicast-echo-api-conf-secret --from-file=$PWD/config.json

    The configuration file must be called config.json. This is an APIcast CRD reference requirement.

    For more information about the contents of the secret see the Admin portal configuration secret reference.

  2. Create an APIcast custom resource:

    $ cat my-echo-apicast.yaml
    apiVersion: apps.3scale.net/v1alpha1
    kind: APIcast
    metadata:
      name: my-echo-apicast
    spec:
      exposedHost:
        host: YOUR DOMAIN
      embeddedConfigurationSecretRef:
        name: apicast-echo-api-conf-secret
    
    $ oc apply -f my-echo-apicast.yaml
    1. The following is an example of an embedded configuration secret:

      apiVersion: v1
      kind: Secret
      metadata:
        name: SOME_SECRET_NAME
      type: Opaque
      stringData:
        config.json: |
          {
            "services": [
              {
                "proxy": {
                  "policy_chain": [
                    { "name": "apicast.policy.upstream",
                      "configuration": {
                        "rules": [{
                          "regex": "/",
                          "url": "http://echo-api.3scale.net"
                        }]
                      }
                    }
                  ]
                }
              }
            ]
          }
  3. Set the following content when creating the APIcast object:

    apiVersion: apps.3scale.net/v1alpha1
    kind: APIcast
    metadata:
      name: example-apicast
    spec:
      embeddedConfigurationSecretRef:
        name: SOME_SECRET_NAME

    The spec.embeddedConfigurationSecretRef.name must be the name of the existing OpenShift secret that contains the configuration of the gateway.

  4. Verify the APIcast pod is running and ready, by confirming that the readyReplicas field of the OpenShift Deployment associated with the APIcast object is 1. Alternatively, wait until the field is set with:

    $ echo $(oc get deployment apicast-example-apicast -o jsonpath='{.status.readyReplicas}')
    1
3.6.1.2.1. Verifying APIcast gateway is running and available

Procedure

  1. Ensure the OpenShift Service APIcast is exposed to your local machine, and perform a test request. Do this by port-forwarding the APIcast OpenShift Service to localhost:8080:

    oc port-forward svc/apicast-example-apicast 8080
  2. Make a request to a configured 3scale Service to verify a successful HTTP response. Use the domain name configured in Staging Public Base URL or Production Public Base URL settings of your service. For example:

    $  curl 127.0.0.1:8080/test -H "Host: localhost"
    {
      "method": "GET",
      "path": "/test",
      "args": "",
      "body": "",
      "headers": {
        "HTTP_VERSION": "HTTP/1.1",
        "HTTP_HOST": "echo-api.3scale.net",
        "HTTP_ACCEPT": "*/*",
        "HTTP_USER_AGENT": "curl/7.65.3",
        "HTTP_X_REAL_IP": "127.0.0.1",
        "HTTP_X_FORWARDED_FOR": ...
        "HTTP_X_FORWARDED_HOST": "echo-api.3scale.net",
        "HTTP_X_FORWARDED_PORT": "80",
        "HTTP_X_FORWARDED_PROTO": "http",
        "HTTP_FORWARDED": "for=10.0.101.216;host=echo-api.3scale.net;proto=http"
      },
      "uuid": "603ba118-8f2e-4991-98c0-a9edd061f0f0"

3.7. WebSocket protocol support for APIcast

Red Hat 3scale API Management provides support in the APIcast gateway for WebSocket protocol connections to backend APIs.

The following list are points to consider in if you are planning to implement WebSocket protocols:

  • The WebSocket protocol does not support JSON Web Token (JWT).
  • The WebSocket standard does not allow extra-headers.
  • The WebSocket protocol is not part of the HTTP/2 standard.

3.7.1. WebSocket protocol support

The APIcast configuration policy chain is as follows:

"policy_chain": [
  { "name": "apicast.policy.websocket" },
  { "name": "apicast.policy.apicast" }
],

The API backend can be defined as http[s]` or ws[s].

3.8. HTTP/2 in the APIcast gateway

Red Hat 3scale API Management provides APIcast gateway support for HTTP/2 and Remote Procedure Calls (gRPC) connections. The HTTP/2 protocol controls enables data communication between APIcast and the API backend.

Note
  • You cannot use api_key authorization. Use JSON Web Token (JWT) or Headers instead.
  • gRPC endpoint terminates Transport Layer Security (TLS).
  • The gRPC policy (HTTP/2) must be above the APIcast policy in the policy chain.

3.8.1. HTTP/2 protocol support

With HTTP/2 termination, APICast enabled HTTP/2 and backends can be HTTP/1.1 plaintext or TLS.

In HTTP/2 endpoints, where the policy is used, there are some constraints:

  • The endpoint needs to listen on TLS in case this policy does not work expected.
  • gRPC full flow will only work if the TLS policy is enabled.

The APIcast configuration policy chain is as follows:

"policy_chain": [
  { "name": "apicast.policy.grpc" },
  { "name": "apicast.policy.apicast" }
],

3.9. Additional resources

To get information about the latest released and supported version of APIcast, see the articles: