Installing Apigee Adapter for Istio 1.1.x

This topic explains how to set up, configure, and test the Apigee Adapter for Istio 1.1.x.

Audience

Throughout the Apigee Adapter for Istio documentation, we assume you have a basic understanding of both Kubernetes and Istio. We also assume that you are an Apigee Edge user and understand basic Apigee concepts such as API Proxies, Products, Developer Apps, and API keys.

Installation for Istio 1.1.x

Complete these tasks to install the Apigee Adapter for Istio. These install steps require you to be on Istio 1.1.x.

Prerequisites

You need to complete the following prerequisites before installing the Apigee Adapter with Istio.

You must have an Apigee account

To configure and use the Apigee Adapter, you must have an Apigee account, and you'll need to know your organization name, username (typically your Apigee account email address), and account password.

Kubernetes cluster requirements

The minimum requirements for your Kubernetes cluster are listed below.

  • Kubernetes version 1.11 or later
  • kubectl version 1.9 or later

If you need help creating a Kubernetes cluster, see Setup on the Kubernetes doc site.

Installing Istio

As of Istio 1.1.x, a custom Mixer image in no longer required. Instead, the Apigee Adapter can simply run as a stand-alone service and configuration can tell Mixer how to call it.

  1. Follow the official Istio installation instructions to install Istio in your cluster.

  2. Be sure that policy control is explicitly enabled. See Enabling Policy Enforcement for more details.

Download the Adapter software

Download the software to your system:

  1. Download the Apigee Adapter for Istio release package for your operating system.
  2. Unzip the release file.
  3. Rename the root folder to: apigee-istio-adapter.

You are now ready to install the adapter with Istio.

Provision components on Edge Public Cloud

If you are on Edge Public Cloud, follow these steps to provision the components that the adapter needs to communicate with Apigee Edge. Provisioning installs a proxy in your Apigee Edge organization, sets up a certificate, and generates credentials that you'll need later when you configure the adapter.

  1. cd to the directory where the Apigee adapter is installed: apigee-istio-adapter.
  2. Add the apigee-istio command executable to the PATH so that you can access it easily.

  3. Run the following command to provision Apigee Edge, redirecting the output to a file. You will use this file later when you configure the adapter. The command requires authentication. You can use your Apigee username/password for basic authentication, or you can authenticate with an OAuth or SAML token.

    With basic auth:

    apigee-istio provision --grpc -u [username] -p [password] -o [organization] \
    -e [environment] > samples/apigee/grpc/handler.yaml
    

    With a token:

    apigee-istio provision --grpc -t [token] -o [organization] \
    -e [environment] > samples/apigee/grpc/handler.yaml
    

    Where the parameters organization, environment, username, and password are your Apigee account values. The username is typically your Apigee account email address. If used, the token parameter is a value you must generate. For information on generating tokens, see Using get_token and Access the management API with SAML.

    apigee-istio picks up the username and password, or token, automatically if you have a .netrc file in your home directory. For details, see Using .netrc for credentials.

    Example

    apigee-istio provision -o docs -e test -u jdoe@example.com \
    -p abc123 > samples/apigee/handler.yaml
    

    Sample output

    You can see the output in samples/apigee/handler.yaml. The "spec" block at the end of the output is important. It includes a key and secret that you'll need to configure the Apigee adapter. The values in your output file will be different from those shown below.

    # Istio handler configuration for Apigee gRPC adapter for Mixer
    apiVersion: config.istio.io/v1alpha2
    kind: handler
    metadata:
      name: apigee-handler
      namespace: istio-system
    spec:
      adapter: apigee
      connection:
        address: apigee-adapter:5000
      params:
        apigee_base: https://istioservices.apigee.net/edgemicro
        customer_base: https://myorg-env.apigee.net/istio-auth
        org_name: myorg
        env_name: myenv
        key: 06a40b65005d03ea24c0d53de69ab795590b0c332526e97fed549471bdea00b9
        secret: 93550179f344150c6474956994e0943b3e93a3c90c64035f378dc05c98389633   
    
  4. Go to the section Install a test service.

Provision components on Edge Private Cloud

If you are on Edge Private Cloud, follow these steps to provision the components that the adapter needs to communicate with Apigee Edge. Provisioning installs a proxy in your Apigee Edge organization, sets up a certificate, and generates credentials that you'll need later when you configure the adapter.

  1. cd to the directory where the Apigee adapter is installed: apigee-istio-adapter.
  2. Add the apigee-istio command executable to the PATH for easy access.

  3. Run this command to provision Apigee Edge. You redirect the output to a file for convenience -- you will use the output values later when you configure the adapter. The command requires authentication. You can use your Apigee username/password for basic authentication, or you can authenticate with an OAuth or SAML token.

    With basic auth:

    apigee-istio provision -o [organization] -e [environment] -u [username] \
    -p [password] --managementBase [management server URL] > samples/apigee/handler.yaml
    

    With a token:

    apigee-istio provision -o [organization] -e [environment] -u [username] \
    -t [token] --managementBase [management server URL] > samples/apigee/handler.yaml
    

    Where the parameters organization, environment, username, and password are your Apigee account values. The username is typically your Apigee account email address. If used, the token parameter is a value you must generate. For information on generating tokens, see Using get_token and Access the management API with SAML.

    apigee-istio picks up the username and password automatically if you have a .netrc file in your home directory. For details, see Using .netrc for credentials.

    Example

    apigee-istio provision -o docs -e test -u jdoe@example.com -p abc123 \
    --managementBase http://192.162.55.100:8080</code> <code>> samples/apigee/handler.yaml
    

    Where the parameters organization, environment, username, and password are your Apigee account values. The username is typically your Apigee account email address.

    Sample output

    You can see the output in samples/apigee/handler.yaml. The "spec" block at the end of the output is important. It includes a key and secret that you'll need to configure the Apigee adapter. The values in your output file will be different from those shown below.

    # istio handler configuration for apigee adapter
    apiVersion: config.istio.io/v1alpha2
    kind: apigee
    metadata:
      name: apigee-handler
      namespace: istio-system
    spec:
      apigee_base: https://edgemicroservices.apigee.net/edgemicro
      customer_base: https://myorg-myenv.apigee.net/istio-auth
      org_name: myorg
      env_name: myenv
      key: 06a40b65005d03ea24c0d53de69ab795590b0c332526e97fed549471bdea00b9
      secret: 93550179f344150c6474956994e0943b3e93a3c90c64035f378dc05c98389633
    
  4. Go to the section Install a test service.

Install a test service

You will use this simple service later to test and verify that Istio with Apigee Adapter is functioning properly. Later you will configure the adapter with Apigee-specific policy rules.

  1. cd to the Istio installation directory on your system. For example:

    cd $PATH_TO_PARENT_DIR/istio-1.1.2
    
  2. Enable automatic sidecar injection for the default namespace:

    kubectl label namespace default istio-injection=enabled
    

    By default, Istio services are deployed to the default namespace. But if you deploy services to a different namespace, you must enable sidecar injection for that namespace before deploying your services.

  3. Run these to deploy the test service and the gateway:

    kubectl apply -f samples/helloworld/helloworld.yaml
    
  4. Deploy the gateway:

    kubectl apply -f samples/helloworld/helloworld-gateway.yaml
    
  5. After a few moments, verify that the service is deployed. For example:

    kubectl get pods
    
    NAME                                          READY     STATUS            RESTARTS      AGE
    helloworld-v1-55cd697cc8-tff7v   2/2            Running            0                       1m
    helloworld-v2-5df5d6ff46-fkw9s   2/2            Running            0                       1m
    

    Notice that there are two service instances running in each pod. One instance is the helloworld service and the other is the Istio proxy, also called the sidecar proxy.

  6. Use this command to return the external IP address for the load balancer. This is the IP to use to call the test service:

    kubectl -n istio-system get service istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
    

    The output is an IP address. For example: 104.154.82.135

  7. Set an environment variable with the external IP address:

    export HELLOWORLD_URL=IP_ADDRESS

    For example:

    export HELLOWORLD_URL=104.154.82.135

  8. Call the helloworld service as follows:

    curl http://$HELLOWORLD_URL/hello
    

    When the service is deployed (it may take a few moments), you should be able to call its API and receive back a successful "hello" response with Status 200. For example:

    Hello version: v2, instance: helloworld-v2-78f774ff78-zmlzt
    

Troubleshooting a 404 error

If you get a 404 error when you call the helloworld service, the following information may help you troubleshoot the problem.

The helloworld sample service deploys with a helloworld-gateway that uses "*" as the hosts value. You can see this setting in samples/helloworld/helloworld.yaml. If you previously deployed another service (such as the Istio Bookinfo service) with this same gateway hosts value, API calls to the helloworld service will fail with a 404 status.

You can check the configuration of the other service (such as Bookinfo) by examining its configuration file. For example, if you deployed the Bookinfo service to your mesh, you can check the file samples/networking/bookinfo-gateway.yaml. If the other service deploys a gateway with a "*" hosts setting, that is the cause of the problem. To resolve the problem, you can delete the other service's gateway. For example:

kubectl delete gateway bookinfo-gateway

Or, you can delete the other service entirely.

Configure the Apigee adapter

Now that Istio is installed and running, you need to add rules to configure to the Apigee adapter.

  1. Be sure you are in the directory where the Apigee adapter is installed: apigee-istio-adapter.

  2. Apply the following Apigee adapter configurations to Istio:

    kubectl apply -f samples/apigee/grpc
    
  3. To test the configuration, call the helloworld service. You should receive a PERMISSION_DENIED error.

    curl http://$HELLOWORLD_URL/hello
    PERMISSION_DENIED:apigee-handler.apigee.istio-system:missing authentication
    

    The error indicates that the API call was validated by Apigee and that the adapter is functioning as expected. To make a successful API call, you need to provide an API key. The next section explains how to obtain a key and use it to call the service.

Get an API key

To get an API key, you need to create a Developer, an API Product, and a Developer App in Apigee Edge.

1. Log in to Apigee Edge

  1. Log in to the Edge UI to perform the following steps. Go to https://login.apigee.com/login and log in with your Apigee credentials.
  2. Once your in the UI, select the same organization that you specified previously in Provision Apigee Edge components.

2. Create a Developer

You can use an existing developer for testing, or create a new one as follows:

  1. Select Publish > Developers in the side navigation menu.
  2. Click + Developer.
  3. Fill out the dialog to create a new developer. You can use any developer name/email that you wish.

3. Create an API Product

Follow the Product creation example provided below. You can read more about Product configuration options in About the API product configuration.

  1. Select Publish > API Products in the side navigation menu.
  2. Click + API Product. The Product Details page appears.
  3. Fill out the Product Details page as follows. Do not click Save until instructed to do so.

    Name hello-istio-product
    Display Name Istio Apigee Test Product
    Environment test and prod
    Access Public
    Key Approval Type Automatic
  4. In the Quota field, specify 5 requests every 1 minute.

    A quota specifies the number of request messages that an app is allowed to submit to an API over the course of an hour, day, week, or month. When an app reaches its quota limit, subsequent API calls are rejected. You will test the quota config later when we call the Helloworld service. See also Understanding quotas.

    alt_text

  5. In the API resources section, click Add a proxy.

  6. Select the proxy named istio-auth.

  7. In Paths, enter / (a single slash).

  8. In the lower half of the page, click + Add Custom Resource.

  9. Set the resource to / (a single slash).

  10. Also in the lower part of the page, click + API Proxy.

  11. In Istio services, click Add an Istio service.

  12. Click + Istio Service.

  13. Add the service name helloworld.default.svc.cluster.local. Note that you can also use the apigee-istio binding command to associate the product with an Istio service.

  14. Click Save.

4. Create a Developer App

  1. Select Publish > Apps in the side navigation menu.
  2. Click + App. The Developer App Details page appears.
  3. Fill out the Developer App page as follows. Do not Save until instructed to do so.

    Name hello-istio-app
    Display Name Istio Apigee Test App
    Developer Select the test developer you created or any developer will be fine.
  4. In the Credentials section, click + Add product and select the product you created: hello-istio-product.

  5. Click Create.

  6. Under Credentials, click Show next to the Key.

  7. Copy the value of the Consumer Key. This value is the API key that you will use to make /hello API calls to the helloworld service in your Istio mesh.

Test the API key

Now you can use the "Consumer Key" that you copied from the Developer App to make an API call to the helloworld service:

curl http://$HELLOWORLD_URL/hello -H "x-api-key: [Your consumer key]"

Example:

curl http://$HELLOWORLD_URL/hello -H "x-api-key: XsU1R4zGXz2ERxa0ilYQ5szwuljr5bB"

If successful, the call will return output similar to the following and an HTTP status 200:

Hello version: v1, instance: helloworld-v1-8488567bb6-5cqnf

Test the Quota configuration

Recall that previously you configured a quota of 5 calls per minute in the API product. Let's test the quota config by calling the /hello API multiple times in quick succession. If you call the API more than 5 times in a minute, you'll see the following error:

RESOURCE_EXHAUSTED:apigee-handler.apigee.istio-system:quota exceeded

View analytics in the Edge UI

As the Apigee adapter processes API traffic, it asynchronously sends analytics data to the Apigee Edge Analytics platform. You can view this data in the Apigee Analytics dashboards in the Edge UI. See also About analytics logging.