Using Docker for Edge Microgateway

This topic explains how to run Edge Microgateway in a Docker container. The steps covered in this topic assume a basic understanding of Docker, Docker commands, and Edge Microgateway setup and configuration. For more information, refer to the documentation for Docker and Edge Microgateway

Prerequisites

Before running Edge Microgateway in a Docker container, you must do the following tasks:

  • Configure Edge Microgateway for your Apigee organization/environment:

    edgemicro configure -o your_org -e your_env -u your_username

    For more details on configuration, see Part 1: Configure Edge Microgateway.

  • After performing the configuration steps, locate the configuration file. The default location is here:

    $HOME/.edgemicro/your_org-your_env-config.yaml

    where your_org and your_env are the organization and environment you used when you ran the edgemicro config command. You will need this file when you start Edge Microgateway in a Docker container.

  • Be sure you have the key and secret credentials that were returned when you ran the edgemicro config command. For example:

    The following credentials are required to start edge micro
      key: d9c34e1aff68ed969273c016699eabf48780e4f652242e72fc88a43e21252cb0
      secret: 3bc95a71c86a3c8ce04537fbcb788158731t51dfc6cdec13b7c05aa0bd969430
    
  • Before you start Edge Microgateway in a Docker container, you need to create (or have created) the Apigee Edge entities that are required to make authenticated API proxy calls. These entities include an Edge Microgateway-aware proxy, an API Product, a Developer, and a Developer App. For complete instructions, see Create entities on Apigee Edge.

Run Edge Micro as a Docker container

  1. Download the Docker image for Edge Microgateway:

    docker pull gcr.io/apigee-microgateway/edgemicro:latest
  2. Before you proceed to the next steps, be sure you have performed all of the steps in the Prerequisites section.

  3. Run the following command to base64-encode the Edge Microgateway configuration file located in $HOME/.edgemicro:

    export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/your_org-your_env-config.yaml`

    where your_org and your_env are the organization and environment you used when you ran the edgemicro config command.

    Remember to place back-ticks (`) around the command. For example:

    export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`
  4. Run Edge Microgateway as a container. The command sets several environment variables that are used by the container runtime to start Edge Microgateway:

    docker run -P -p 8000:8000 -d --name edgemicro \
    -v /var/tmp:/opt/apigee/logs \
    -e EDGEMICRO_PROCESSES=1 \
    -e EDGEMICRO_ORG=your_org \
    -e EDGEMICRO_ENV=your_env \
    -e EDGEMICRO_KEY=your_key \
    -e EDGEMICRO_SECRET=your_secret \
    -e EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG \
    -e SERVICE_NAME=edgemicro \
    --security-opt=no-new-privileges \
    --cap-drop=ALL \
    gcr.io/apigee-microgateway/edgemicro:latest

    Parameters

    To learn more about the parameters, see the Docker run reference.

    Parameter Description
    -P Publish all exposed ports to the host.
    -p Explicitly map a single port or range of ports.
    -d Run in detached mode.
    -v volume -- Volume mount. For logs, expose port 8443 if you are exposing Node.js over TLS. See also VOLUME [shared filesystems.
    EDGEMICRO_ORG The name of the Apigee organization you used to configure Edge Microgateway.
    EDGEMICRO_ENV The name of the Apigee environment you used to configure Edge Microgateway.
    EDGEMICRO_PROCESSES The number of processes to start.
    EDGEMICRO_KEY The key returned when you configured Edge Microgateway.
    EDGEMICRO_SECRET The secret returned when you configured Edge Microgateway.
    EDGEMICRO_CONFIG A variable containing the base64-encoded Edge Microgateway configuration file.
    SERVICE_NAME If you are on Kubernetes, this parameter is auto-populated. Otherwise, you can set it to anything you wish. If you specify nothing, the service name is set to default.
    DEBUG Set to * to enable debugging.
    HTTP_PROXY/HTTPS_PROXY Used to when Edge Microgateway is running behind a firewall and the gateway cannot communicate with Apigee Edge. For more information, see Setting up Edge Microgateway behind a company firewall. For example: HTTP_PROXY=http://10.203.0.1:5187/
    NO_PROXY A comma delimited list of domains that Edge Microgateway should not proxy to. For more information, see Setting up Edge Microgateway behind a company firewall. For example: localhost,127.0.0.1,localaddress,.localdomain.com
    --security-opt https://docs.docker.com/engine/reference/run/#security-configuration
    NODE_EXTRA_CA_CERTS If you are using a CA that's not trusted by default by Node.js, consider using the parameter NODE_EXTRA_CA_CERTS when you run the container. For details, see TLS certificates.
    --cap-drop https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities

    For example:

    docker run -P -p 8000:8000 -d --name edgemicro \
    -v /var/tmp:/opt/apigee/logs \
    -e EDGEMICRO_PROCESS=1 \
    -e EDGEMICRO_ORG=docs \
    -e EDGEMICRO_ENV=test \
    -e EDGEMICRO_KEY=d9c34e1aff68ed969273b016699eabf48780e4f652242e72fc88a23e21252cb0 \
    -e EDGEMICRO_SECRET=3bc95a71c86a3c8ce04137fbcb788158731t51dfc6cdec13b7c05aa0bd969430 \
    -e EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG \
    -e SERVICE_NAME=edgemicro \
    --security-opt=no-new-privileges \
    --cap-drop=ALL \
    gcr.io/apigee-microgateway/edgemicro
  5. To check that the container is running:

    docker ps

    You should see output similar to the following:

    CONTAINER ID    IMAGE         COMMAND                CREATED          STATUS          PORTS                                             NAMES
    8b92e082ea9c    edgemicro    "/tmp/entrypoint.sh"   12 minutes ago   Up 12 minutes    0.0.0.0:8000->8000/tcp, 0.0.0.0:32775->8443/tcp    edgemicro
    

Testing an API call

After you start Edge Microgateway in the container, you can make API calls to it. For example, if the basepath of your API is /hello:

http://localhost:8000/hello

Sample output:

{"error":"missing_authorization","error_description":"Missing Authorization header"}

If you see this response, it means that Edge Microgateway successfully handled the API call. However, by default, Edge Microgateway requires an API key for authentication. In the next section, you will test the API with a valid API key.

Test an API with a valid API key

In the Edge UI, navigate to the Developer App you created previously. In the Developer App page, show the Consumer Key and copy it. This value is the API key. You'll use this key to make authenticated API calls.

Call the API with the x-api-key header as follows. The Consumer Key value you copied from the Developer App is the API key. By default, Edge Microgateway expects you to pass the key in a header called x-api-key, like this:

curl -i http://localhost:8000/hello -H "x-api-key:apikey"

For example:

curl -i http://localhost:8000/hello -H "x-api-key:PydUKRDGIXRqF2xh4usn1FLHbhGKVIz"

If you want to learn more about making authenticated API calls through Edge Microgateway with API keys and OAuth tokens, see Part 4: Secure Edge Microgateway.

Stopping Edge Microgateway

Use the following Docker command to stop Edge Microgateway:

docker stop edgemicro

Restarting Edge Microgateway

After stopping Edge Microgateway, you can restart it with this Docker command:

docker start edgemicro

TLS certificates

The container has a mount point on /opt/apigee/.edgemicro. You can load the certificates on the mount point and refer to them from the org-env-config.yaml file.

Self signed certificates

If you are using a CA that's not trusted by default by Node.js, consider using the parameter NODE_EXTRA_CA_CERTS when you run the container. Set this parameter to the path to a file containing one or more trusted certificates in PEM format.

While we recommend this flag never be used, you could also set NODE_TLS_REJECT_UNAUTHORIZED = 1 to turn off validation.

Adding a custom plugin

You can add new features and capabilities to the microgateway by writing custom plugins. Custom plugins let you interact programmatically with the requests and responses that flow through the microgateway.

You have two options for deploying plugins to an Edge Microgateway instance running in a docker container.

  • Option A: Mount the plugins directory on a volume
  • Option B: Build the plugins into the container

The rest of this section assumes that you are familiar with writing and configuring plugins for a standard Edge Microgateway setup. If not, see Develop custom plugins.

(Prerequisite) Package your plugin(s)

Whether you choose Option A or Option B, you must package custom plugin(s) correctly before deploying them:

  1. Write and test your plugin, according to the directions in Write a simple plugin.

  2. Place your plugin code in the proper directory structure. Plugin directories must follow a set structure. The following example shows the structure you must follow, where response-uppercase and request-headers are the names of folders containing custom plugin code (these names are examples only, your folder names may differ):

    plugin
      |
      |-- plugins
        |
        |- response-uppercase
        |     |- index.js
        |     |- package.json
        |- request-headers
        |     | - index.js
              | - package.json
    
  3. cd to the plugin folder.

  4. In the plugin folder, zip the entire plugins folder:

    zip -r plugins.zip plugins/

Option A: Mount the plugins directory on a volume

In this option, you mount the plugins on the volume /opt/apigee/plugins. Volumes are used to persist data generated by and used by Docker containers. To learn more, see Use volumes

Mount the plugins:

docker run -v /volume/mount:/opt/apigee/plugins [options]

For details on this command and its options, see VOLUME [shared filesystems].

Option B: Build the plugins into the container

In this option, you build the plugins into your container.

1. Create a Docker image

Next, create a Dockerfile to add your plugin code to an Edge Microgateway image.

  1. In the same directory where the zip file is located, create a new file called Dockerfile.
  2. Add the following code to Dockerfile and save the file:

    USER root
    RUN apk update && \
        apk upgrade && \
        apk add zip && \
        mkdir /opt/apigee/customplugins && \
        chown apigee:apigee /opt/apigee/customplugins
    COPY plugins.zip /opt/apigee/customplugins
    RUN su - apigee -c "unzip /opt/apigee/customplugins/plugins.zip -d /opt/apigee/customplugins"
    EXPOSE 8000
    EXPOSE 8443
    USER apigee
    ENTRYPOINT ["entrypoint"]
    
  3. Create a new Edge Microgateway Docker image with your plugins:

    docker build -t image-name .
    

    For example:

    docker build -t edgemicroplugins .
    

2. Update the Edge Microgateway configuration

Now that the plugins are packaged, you need to add them to the Edge Microgateway configuration file.

  1. Open the Edge Microgateway configuration file in an editor:

    $HOME/.edgemicro/org-env-config.yaml
    

    For example:

    vi $HOME/.edgemicro/myorg-test-config.yaml
  2. Add the plugin directory to the configuration file. In the following example the dir attribute specifies the location of the plugin code (which you specified in the Dockerfile). You must also specify the name of the plugin directory, which in the example below is response-uppercase.

    edgemicro:
      ...
      plugins:
        dir: /opt/apigee/plugins
        sequence:
          - oauth
          - response-uppercase
    

3. Start the microgateway

Finally, you must start the microgateway in the container.

  1. Run the following command to base64-encode the Edge Microgateway configuration file located in $HOME/.edgemicro:

    export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/your_org-your_env-config.yaml`

    where your_org and your_env are the organization and environment you used when you ran the edgemicro config command.

    Remember to place back-ticks (`) around the command. For example:

    export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`
  2. Run Edge Microgateway as a container. The command sets several environment variables that are used by the container runtime to start Edge Microgateway:

    docker run -P -p 8000:8000 -d --name edgemicroplugins \
    -e EDGEMICRO_PLUGIN_DIR=/opt/apigee/customplugins/plugins \
    -e EDGEMICRO_ORG=your_org \
    -e EDGEMICRO_ENV=your_env \
    -e EDGEMICRO_KEY=your_key \
    -e EDGEMICRO_SECRET=your_secret \
    -e EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG \
    -e SERVICE_NAME=edgemicroplugins image_name

    For example:

    docker run -P -p 8000:8000 -d --name edgemicroplugins \
    -e EDGEMICRO_PLUGIN_DIR=/opt/apigee/customplugins/plugins \
    -e EDGEMICRO_ORG=docs \
    -e EDGEMICRO_ENV=test \
    -e EDGEMICRO_KEY=d9c34e1aff68ed969273b016699eabf48780e4f652242e72fc88a23e21252cb0 \
    -e EDGEMICRO_SECRET=3bc95a71c86a3c8ce04137fbcb788158731t51dfc6cdec13b7c05aa0bd969430 \
    -e EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG \
    -e SERVICE_NAME=edgemicroplugins edgemicroplugins
  3. Call your API to test the plugin:

    Test that the plugin code executes by calling your API and verifying that the output is as expected:

    curl -i http://localhost:8000/hello -H "x-api-key:apikey"

    For example, the response-uppercase plugin might return a response like this:

    curl -i http://localhost:8000/hello -H "x-api-key:PydUKRDGIXRqF2xh4usn1FLHbhGKVIz"
      HELLO, WORLD!