You're viewing **Apigee Edge** documentation.  
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs). info


This example demonstrates how to use Apigee Adapter for Envoy with Apigee Edge.

## Prerequisites

| Before you begin: |
|---|
| Download and install the Apigee Adapter for Envoy Remote Service and CLI as explained in [Getting started](https://docs.apigee.com/api-platform/envoy-adapter/v2.0.x/getting-started). |

## Overview


This example explains how to use Apigee Adapter for Envoy with Apigee Edge for Public Cloud. API
proxy calls flow through Envoy running as a native application with Edge providing API
management services through the Apigee Remote Service for Envoy.

## Provision Apigee Edge


In this step, you will use the Remote Service CLI to provision Apigee Adapter for Envoy assets
to Apigee Edge. The provisioning command deploys an API proxy to Apigee Edge,
and also sets up a certificate on
Apigee and generates credentials the Remote Service will use to securely
connect from your system to Apigee.

1. Go to the `$CLI_HOME` directory:

   ```
   cd $CLI_HOME
   ```
2. Create the following environment variables. These variables will be used as parameters to the provisioning script:

       export ORG=organization_name
       export ENV=environment_name
       export USER=your_apigee_username
       export PASSWORD=your_apigee_password

   > [!NOTE]
   > The CLI will automatically pick up a username and password from a [.netrc](https://ec.haxx.se/usingcurl-netrc.html) file in your home directory if you have an entry for your management host machine. See also [Using .netrc for credentials](https://docs.apigee.com/api-platform/envoy-adapter/v2.0.x/reference#using-.netrc-for-credentials).


   Where:

   | Variable | Description |
   |---|---|
   | <var translate="no">organization_name</var> | The name of your Apigee organization. |
   | <var translate="no">environment_name</var> | The name of an environment in your organization. |
   | <var translate="no">your_apigee_username</var> | Your Apigee account username. Typically the username is an email address. |
   | <var translate="no">your_apigee_password</var> | Your Apigee password. |

3. Execute the following command to provision the remote service proxy on Apigee Edge:

   > [!NOTE]
   > **NOTE:**The command output is redirected to a config file that you will use in a later step.

   > [!WARNING]
   > **IF YOU ARE UPGRADING:** If you are upgrading an existing Apigee Adapter for Envoy, you must add the `--force-proxy-install` flag to the `provision` command. This flag forces the Apigee proxy to be replaced with the latest proxy.


   If you are **not** upgrading, use this command to provision Apigee:

   ```
   $CLI_HOME/apigee-remote-service-cli provision --legacy --mfa $MFA \
     --username $USER --password $PASSWORD --organization $ORG --environment $ENV > config.yaml
   ```


   If you are upgrading, use this command with the `--force-proxy-install` flag to provision Apigee:

   ```
   $CLI_HOME/apigee-remote-service-cli provision --legacy --force-proxy-install --mfa $MFA \
     --username $USER --password $PASSWORD --organization $ORG --environment $ENV > config.yaml
   ```
4. Check the contents of the `config.yaml` file. It should look something like this:

   ```
   # Configuration for apigee-remote-service-envoy (platform: SaaS)
   # generated by apigee-remote-service-cli provision on 2020-08-26 09:43:41
   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: apigee-remote-service-envoy
     namespace: apigee
   data:
     config.yaml: |
       tenant:
         internal_api: https://istioservices.apigee.net/edgemicro
         remote_service_api: https://my-username-test.apigee.net/remote-service
         org_name: my-org
         env_name: my-env
         key: f7e09c32f827cab87b8ce43842ed8467ffd2c58e6f795241e38fe7b1aec7664
         secret: 1cb5cca00dfb433cb80b32837451fce4bf694633cddbb73d704517e12b35e75
      ...
   ```


   The key and secret values are used to validate the requests from the Remote Service Proxy
   to Apigee Edge.

## Run the Apigee Remote Service for Envoy service


You can run the Remote Service either as a native binary
or on Docker.

### Run the service natively

Execute the service binary with the config file that was output by the provisioning command:

```
$REMOTE_SERVICE_HOME/apigee-remote-service-envoy -c config_file_path/config.yaml
```

<br />

### Run the service on Docker


Docker images are published with release tags. For this install, use the latest version. There
are three image variations to choose from:

| Variation | Image |
|---|---|
| Google distroless | `google/apigee-envoy-adapter:v2.0.0` |
| Ubuntu | `google/apigee-envoy-adapter:v2.0.0-ubuntu` |
| Ubuntu with Boring Crypto | `google/apigee-envoy-adapter:v2.0.0-boring` |

For example, to run the scratch image with your local `config.yaml` available as `/config.yaml`
via a volume mount, use this command:

```
docker run -v ./config.yaml:/config.yaml google/apigee-envoy-adapter:v2.0.0
```

> [!NOTE]
> **Note:** The Docker image runs as a non-root user. Make sure it is granted read permission to the `config.yaml` file.

## Create sample configuration files


Generate an Envoy configuration file using the CLI:

1. Make sure you are in the `$ENVOY_HOME` directory.
2. List the available configuration templates:

   ```
   $CLI_HOME/apigee-remote-service-cli samples templates
   ```
3.
   Execute the samples command. For <var translate="no">TEMPLATE</var>, substitute one of the supported Envoy templates:

   ```
   $CLI_HOME/apigee-remote-service-cli samples create --template TEMPLATE -c ./config.yaml
   ```


   The command creates the file `./samples/envoy-config.yaml`.


For more information, see [Samples command](https://docs.apigee.com/api-platform/envoy-adapter/v2.0.x/reference#samples-command).

## Install and run the Envoy proxy


Follow these steps to install and run the Envoy proxy:

1. Download an Envoy [binary](https://www.getenvoy.io/) or [build](https://www.envoyproxy.io/docs/envoy/latest/install/building) it, or use [Docker](https://www.envoyproxy.io/docs/envoy/latest/install/building#pre-built-binaries).
2. Run Envoy using a sample configuration file that you generated previously for the `httpbin.org` service:

   ```
   envoy -c ./samples/envoy-config.yaml
   ```

   > [!NOTE]
   > **NOTE:** To configure for a different service, use the [Samples command](https://docs.apigee.com/api-platform/envoy-adapter/v2.0.x/reference#samples-command) and substitute values for your service in the CLI.

## Test the installation

1. Configure an API product and get an API key as explained in [How to obtain an API key](https://docs.apigee.com/api-platform/envoy-adapter/v2.0.x/operation#how-to-obtain-an-api-key).
2. Call the `httpbin` service without an API key:

   ```
   curl -i http://localhost:8080/headers -H "HOST:httpbin.org"
   ```

   > [!NOTE]
   > **Note:** You must include the `HOST` header and set it to the remote service host that was set in the API product.

   The service is now being managed by Apigee, and because you did not supply an API key,
   the call returns the following error.

   ```
   curl -i http://localhost:8080/headers -H "HOST:httpbin.org"
   HTTP/1.1 403 Forbidden
   date: Tue, 12 May 2020 17:51:36 GMT
   server: envoy
   content-length: 0
   x-envoy-upstream-service-time: 11
   ```
3. Make an API call using the key:

       export APIKEY=YOUR_API_KEY
       curl -i http://localhost:8080/headers \
       -H "HOST:httpbin.org" -H "x-api-key: $APIKEY"


   The call should succeed with a 200 status and returning a list of headers in the response.
   For example:

   ```
   curl -i httpbin.default.svc.cluster.local/headers -H "x-api-key: kyOTalNNLMPfOSy6rnVeclmVSL6pA2zS"
   HTTP/1.1 200 OK
   server: envoy
   date: Tue, 12 May 2020 17:55:34 GMT
   content-type: application/json
   content-length: 828
   access-control-allow-origin: *
   access-control-allow-credentials: true
   x-envoy-upstream-service-time: 301

   {
     "headers": {
       "Accept": "*/*",
       "Content-Length": "0",
       "Host": "httpbin.default.svc.cluster.local",
       "User-Agent": "curl/7.70.0-DEV",
       "X-Api-Key": "kyOTalNNLMPfOSy6rneclmVSL6pA2zS",
       "X-Apigee-Accesstoken": "",
       "X-Apigee-Api": "httpbin.default.svc.cluster.local",
       "X-Apigee-Apiproducts": "httpbin",
       "X-Apigee-Application": "httpbin",
       "X-Apigee-Authorized": "true",
       "X-Apigee-Clientid": "kyOTalNNLMPfOSy6rVeclmVSL6pA2zS",
       "X-Apigee-Developeremail": "user@example.com",
       "X-Apigee-Environment": "test",
       "X-Apigee-Organization": "my-org",
       "X-Apigee-Scope": "",
       "X-B3-Parentspanid": "1476f9a2329bbdfa",
       "X-B3-Sampled": "0",
       "X-B3-Spanid": "1ad5c19bfb4bc96f",
       "X-B3-Traceid": "6f329a34e8ca07811476f9a2329bbdfa"
     }
   }
   ```

## Next steps


API traffic to the `httpbin` service is now managed by Apigee. Here are
some features you can explore and try:

- If you configured your API product as explained in [How to obtain an API key](https://docs.apigee.com/api-platform/envoy-adapter/v2.0.x/operation#how-to-obtain-an-api-key), the quota limit was set to 5 requests per minute. Try calling the `httpbin` service a few more times to trigger the quota. When the quota is depleted, an HTTP status 403 error is returned.
- Access Apigee Analytics in the Edge UI. Go to **Analyze \> API Metrics \> API
  Proxy Performance**.
- Generate and use [JWT tokens](https://docs.apigee.com/api-platform/envoy-adapter/v2.0.x/operation#using-jwt-based-authentication) to authenticate API calls.
- Use the CLI to manage, create tokens, and control bindings. For CLI details, see the [Reference](https://docs.apigee.com/api-platform/envoy-adapter/v2.0.x/reference).