Native Envoy example for Apigee and hybrid

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

This example demonstrates how to use Apigee Adapter for Envoy by installing and running Envoy locally, not inside a Kubernetes cluster. You can follow the example in this document for both Apigee and Apigee hybrid installations.

API proxy calls go through Envoy running as a native application. Apigee provides API management services, such as API product and developer app creation. Envoy communicates with the Apigee management plane through the adapter's remote service. The adapter also pushes analytics data to Apigee where you can see it in Apigee Analytics.

Prerequisites

Before you begin:

Check your gcloud configuration

  1. Check that your gcloud configuration is set to the Google Cloud project associated with your Apigee organization.

    To list the current settings. See also gcloud config.

    gcloud config list

    If necessary, set the correct Google Cloud project ID with this command:

    gcloud config set project project-id
  2. You must be authenticated with Google Cloud SDK (gcloud) for your Google Cloud project. See also gcloud auth login.
    gcloud auth login

Provision Apigee

In this step, you will use the Remote Service CLI to provision Apigee Adapter for Envoy assets to Apigee. The provisioning command deploys API proxies used for Apigee adapter operations, 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. (Optional) By default, the adapter looks for default service account credentials in your Google Cloud project for permission to send analytics data to Apigee. If you don't want to use the default service account credentials, you can create a service account and reference its key in the provisioning command. The service account must have the apigee.analyticsAgent role. For instructions, see Creating and managing service accounts.
  3. 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 RUNTIME=host_alias_url
    export NAMESPACE=hybrid_runtime_namespace  ## Apigee hybrid only
    export AX_SERVICE_ACCOUNT=analytics_service_account  ## Optional

    Where:

    Variable Description
    organization_name The name of your Apigee organization.
    environment_name The name of an environment in your organization.
    host_alias_url
    • For Apigee hybrid, a URL that includes the hostAlias for a virtual host defined in your hybrid configuration.
    • For Apigee, a hostname from the environment group that includes the environment. You can find environment groups in the Apigee UI under Admin > Environments > Groups.
    • Note: The URL must start with https://. For example: https://apitest.mydomain.net

    hybrid_runtime_namepace (Apigee hybrid only) The namespace in which the Hybrid runtime components are deployed.

    Note: The default namespace for a hybrid deployment is apigee.

    analytics_service_account (Optional) The path to a Google Cloud service account key JSON file that has the Apigee Analytics Agent role. For a detailed description of this parameter, see Provision command.
  4. If you are not an owner of the Google Cloud project associated with the Apigee organization, be sure that your Google Cloud user account includes either the Apigee Organization Admin role, or both the API Creator and the Deployer roles. See Granting, changing, and revoking access to resources.
  5. Get an access token:
    TOKEN=$(gcloud auth print-access-token);echo $TOKEN
  6. Provision the remote service proxy to Apigee. The command output is redirected to a config file that you will use in a later step.

    If you are not upgrading, use this command to provision Apigee. If you are provisioning to Apigee hybrid, be sure to add the --namespace $NAMESPACE parameter:

    ./apigee-remote-service-cli provision --organization $ORG --environment $ENV \
         --runtime $RUNTIME --analytics-sa $AX_SERVICE_ACCOUNT --token $TOKEN > config.yaml

    If you are upgrading, use this command with the --force-proxy-install flag to provision Apigee. If you are provisioning to Apigee hybrid, be sure to add the --namespace $NAMESPACE parameter:

    ./apigee-remote-service-cli provision --force-proxy-install --organization $ORG --environment $ENV \
         --runtime $RUNTIME --analytics-sa $AX_SERVICE_ACCOUNT --token $TOKEN > config.yaml
  7. Check the contents of the config.yaml file. It should look something like this:
    # Configuration for apigee-remote-service-envoy (platform: Google Cloud)
    # generated by apigee-remote-service-cli provision on 2020-11-20 02:49:28
    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: apigee-remote-service-envoy
      namespace: apigee
    data:
      config.yaml: |
        tenant:
          remote_service_api: https://apitest.mydomain.com/remote-service
          org_name: my-org
          env_name: test
        analytics:
          collection_interval: 10s
        auth:
          jwt_provider_key: https://apitest.mydomain.com/remote-service/token
    ---
    apiVersion: v1
    kind: Secret
    metadata:
      name: my-org-new-test-policy-secret
      namespace: apigee
    type: Opaque
    data:
      remote-service.crt: eyJrZXlzIjpbeyJrdHkiOiJSU0EiLCJhbGci...
      remote-service.key: LS0tLS1CRUdJTiBSU0EgUFJJVkFURS...
      remote-service.properties: a2lkPTIwMjAtMDctMDZ...
    ---
    apiVersion: v1
    kind: Secret
    metadata:
      name: my-org-new-test-analytics-secret
      namespace: apigee
    type: Opaque
    data:
      client_secret.json: ewogICJ0eXBlIjogInNlcnZ...
    ---
    apiVersion: v1
    kind: ServiceAccount
    metadata:
      name: apigee-remote-service-envoy
      namespace: apigee

Run apigee-remote-service-envoy

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

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.3
Ubuntu google/apigee-envoy-adapter:v2.0.3-ubuntu
Ubuntu with Boring Crypto google/apigee-envoy-adapter:v2.0.3-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.3

Create a sample Envoy configuration file

Generate a sample 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 TEMPLATE, 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.

Install and run the Envoy proxy

Follow these steps to install and run the Envoy proxy:

  1. Download an Envoy binary or build it.
  2. Run Envoy using a sample configuration file that you generated previously for the httpbin.org service:
    envoy -c ./samples/envoy-config.yaml

Test the installation

  1. Configure an API product and get an API key as explained in 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"
    

    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 return 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@mydomain.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"
      }
    }

Uninstall Apigee Envoy adapter

To remove an Apigee Envoy adapter installation:

  1. Wherever you chose to have envoy adapter run (natively or on Docker), remove it.
  2. Delete the remote-service and remote-token proxies from your Apigee environment(s). See Deleting an API proxy.
  3. Remove any unused API products or operations used by the Envoy adapter use cases. See Deleting an API product.

Next steps

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

  • Access Apigee Analytics in the Edge UI. Go to Analyze > API Metrics > API Proxy Performance.
  • Explore the CLI options in the Reference.