Chapter 3. Installing APIcast

Procedure

1. Download a ready to use Podman container image from the Red Hat registry:

   $ podman pull registry.redhat.io/3scale-amp2/apicast-gateway-rhel8:3scale2.13

2. Run APIcast in a Podman:

   $ podman run --name apicast --rm -p 8080:8080 -e THREESCALE_PORTAL_ENDPOINT=https://<access_token>@<domain>-admin.3scale.net registry.redhat.io/3scale-amp2/apicast-gateway-rhel8:3scale2.13

   Here, <access_token> is the Access Token for the 3scale Account Management API. You can use the Provider Key instead of the access token. <domain>-admin.3scale.net is the URL of your 3scale Admin Portal.

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

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

Procedure

1. Write Lua code that defines the custom environment that you want to inject. For example, the following env1.lua file shows a custom logging policy that the APIcast operator loads for all services.

   local cjson = require('cjson')
   local PolicyChain = require('apicast.policy_chain')
   local policy_chain = context.policy_chain
   
   local logging_policy_config = cjson.decode([[
   {
     "enable_access_logs": false,
     "custom_logging": "\"{{request}}\" to service {{service.id}} and {{service.name}}"
   }
   ]])
   
   policy_chain:insert( PolicyChain.load_policy('logging', 'builtin', logging_policy_config), 1)
   
   return {
     policy_chain = policy_chain,
     port = { metrics = 9421 },
   }

2. Create a secret from the Lua file that defines the custom environment. For example:

   $ oc create secret generic custom-env-1 --from-file=./env1.lua

   A secret can contain multiple custom environments. Specify the –from-file option for each file that defines a custom environment. The operator loads each custom environment.

3. Define an APIcast custom resource that references the secret you just created. The following example shows only content relative to referencing the secret that defines the custom environment.

   apiVersion: apps.3scale.net/v1alpha1
   kind: APIcast
   metadata:
     name: apicast1
   spec:
     customEnvironments:
       - secretRef:
           name: custom-env-1

   An APIcast custom resource can reference multiple secrets that define custom environments. The operator loads each custom environment.

4. Create the APIcast custom resource that adds the custom environment. For example, if you saved the APIcast custom resource in the apicast.yaml file, run the following command:

   $ oc apply -f apicast.yaml

Procedure

1. Create a secret from the files that define one custom policy. For example:

   $ oc create secret generic my-first-custom-policy-secret \
    --from-file=./apicast-policy.json \
    --from-file=./init.lua \
    --from-file=./my-first-custom-policy.lua

   If you have more than one custom policy, create a secret for each custom policy. A secret can contain only one custom policy.

2. Define an APIcast custom resource that references the secret you just created. The following example shows only content relative to referencing the secret that defines the custom policy.

   apiVersion: apps.3scale.net/v1alpha1
   kind: APIcast
   metadata:
     name: apicast1
   spec:
     customPolicies:
       - name: my-first-custom-policy
         version: "0.1"
         secretRef:
           name: my-first-custom-policy-secret

   An APIcast custom resource can reference multiple secrets that define custom policies. The operator loads each custom policy.

3. Create the APIcast custom resource that adds the custom policy. For example, if you saved the APIcast custom resource in the apicast.yaml file, run the following command:

   $ oc apply -f apicast.yaml

Procedure

1. Define a secret that contains your OpenTracing configuration details in stringData.config. This is the only valid value for the attribute that contains your OpenTracing configuration details. Any other specification prevents APIcast from receiving your OpenTracing configuration details. The folowing example shows a valid secret definition:

   apiVersion: v1
   kind: Secret
   metadata:
     name: myjaeger
   stringData:
     config: |-
         {
         "service_name": "apicast",
         "disabled": false,
         "sampler": {
           "type": "const",
           "param": 1
         },
         "reporter": {
           "queueSize": 100,
           "bufferFlushInterval": 10,
           "logSpans": false,
           "localAgentHostPort": "jaeger-all-in-one-inmemory-agent:6831"
         },
         "headers": {
           "jaegerDebugHeader": "debug-id",
           "jaegerBaggageHeader": "baggage",
           "TraceContextHeaderName": "uber-trace-id",
           "traceBaggageHeaderPrefix": "testctx-"
         },
         "baggage_restrictions": {
             "denyBaggageOnInitializationFailure": false,
             "hostPort": "127.0.0.1:5778",
             "refreshInterval": 60
         }
         }
   type: Opaque

2. Create the secret. For example, if you saved the previous secret definition in the myjaeger.yaml file, you would run the following command:

   $ oc create -f myjaeger.yaml

3. Define an APIcast custom resource that specifies the OpenTracing attributes. In the CR definition, set the spec.tracingConfigSecretRef.name attribute to the name of the secret that contains your OpenTracing configuration details. The following example shows only content relative to configuring OpenTracing.

   apiVersion: apps.3scale.net/v1alpha1
   kind: APIcast
   metadata:
     name: apicast1
   spec:
     ...
     openTracing:
       enabled: true
       tracingConfigSecretRef:
         name: myjaeger
       tracingLibrary: jaeger
   ...

4. Create the APIcast custom resource that configures OpenTracing. For example, if you saved the APIcast custom resource in the apicast1.yaml file, you would run the following command:

   $ oc apply -f apicast1.yaml