Installing Apigee Adapter for Istio

This topic explains how to set up, configure, and test the Apigee adapter.

Audience

Throughout the Apigee Adapter for Istio documentation, we assume you have a basic understanding of both Kubernetes (kubernetes.io) and Istio (istio.io). 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

Complete these tasks to install the Apigee Adapter for 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.

Install Istio with the Apigee adapter on a Kubernetes cluster

To install Istio on a Kubernetes cluster:

  1. Create your Kubernetes cluster. Follow the Platform Setup instructions for your Kubernetes platform on the Istio doc site. You must use Kubernetes Cluster Version 1.9 or later with RBAC enabled (version 1.10 is recommended). You'll also need the kubectl CLI, version 1.9 or later.

    For example, create a cluster for the Google Cloud Platform (GCP) and grant cluster admin permissions to the current user as described in the Istio documentation at Google Kubernetes Engine.

  2. Download the Apigee Adapter for Istio release package for your operating system.

  3. Unzip the release file.

  4. Rename the root folder to: apigee-istio-adapter.

  5. cd to the root directory: apigee-istio-adapter.

  6. Install Istio. For your convenience, the release package contains sample Istio install files. You can install either with or without mutual TLS (mTLS) enabled:

    1. Install Istio with mutual TLS enabled in the control plane:

      kubectl apply -f samples/istio/istio-demo-auth.yaml
      
    2. Install Istio without mutual TLS in the control plane:

      kubectl apply -f samples/istio/istio-demo.yaml
      

Validate the Istio installation

After the installation completes, use kubectl to validate the installation:

  1. View the Istio services running on the Kubernetes cluster:

    kubectl get service -n istio-system
    
  2. View the Istio pods running on the Kubernetes cluster:

    kubectl get pods -n istio-system
    

Be sure the services are running before you continue. See also Verifying the installation on the Istio doc site.

Provision components on Edge Public Cloud

If you are on Edge Public Cloud, follow these steps to provision 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. This step allows you to execute the apigee-istio command-line interface for the adapter. For example:

    export PATH=$PATH:$PWD/apigee-istio
    
  3. In the next step, you're going to overwrite the file samples/apigee/handler.yaml. So, before you do that, rename the original file:

    cp samples/apigee/handler.yaml samples/apigee/handler.sav
    
  4. Run this script to provision Apigee Edge, redirecting the output to a file. You will use this file later when you configure the adapter.

    The provision command requires authentication. You can use basic authentication (username/password), or you can authenticate with an OAuth or SAML token:

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

    or

    apigee-istio provision -o [organization] -e [environment] -t [token] > 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, 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 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
    
  5. 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 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. This step allows you to execute the apigee-istio command-line interface for the adapter. For example:

    export PATH=$PATH:$PWD/apigee-istio
    
  3. In the next step, you're going to overwrite the file samples/apigee/handler.yaml. So, before you do that, rename the original file:

    cp samples/apigee/handler.yaml samples/apigee/handler.sav
    
  4. Run this script 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 provision command requires authentication. You can use basic authentication (username/password), or you can authenticate with an OAuth or SAML token:

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

    or

    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
    
  5. Go to the section Install a test service.

Install a test service

You will use this simple service later to test and verify that the adapter is functioning properly:

  1. cd to the directory where the Apigee adapter is installed: apigee-istio-adapter.
  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 were to deploy services to a different namespace, you must enable sidecar injection for the namespace before deploying your services. For example, if you deploy the service to the test namespace:

    kubectl label namespace test istio-injection=enabled
    
  3. Run this command to deploy the test service:

    kubectl apply -f samples/istio/helloworld.yaml
    
  4. 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.

  5. 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}'
    <IP_ADDRESS>
    
  6. Set an environment variable with the external IP address:

    export HELLOWORLD_URL=<IP_ADDRESS>
    

    For example:

    export HELLOWORLD_URL=35.224.90.117

  7. 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/istio/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. Open the file samples/apigee/handler.yaml and make sure it contains the information returned by the apigee-istio provision command that you ran previously. You do not need to change anything in the file. Here's an example. Your values will be different than those shown below:

    apiVersion: config.istio.io/v1alpha2
    kind: apigee
    metadata:
      name: apigee-handler
      namespace: istio-system
    spec:
      apigee_base: https://istioservices.apigee.net/edgemicro
      customer_base: https://myorg-test.apigee.net/istio-auth
      org_name: myorg
      env_name: test
      key: 3acfcf6ec5e2014d9cfabee4f7cb4d438ab309ed6de1ebb9cb8f9fb46e45db3f
      secret: 52cf0c44d20c513c4fe6a41f7bb9a489806f3e5af9ddde9ae9d67776a0a3b779
    
  3. Close the file.

  4. Apply the following Apigee adapter configurations to Istio:

    kubectl apply -f samples/apigee/definitions.yaml
    kubectl apply -f samples/apigee/handler.yaml
    kubectl apply -f samples/apigee/rule.yaml
    
  5. 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 lower half of the page, click + Add Custom Resource.

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

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

  8. Select the proxy named istio-auth.

  9. Click + Istio Service.

  10. 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.

    The dialog settings should look like this:

    alt_text

  11. 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 + Product and select the product you created: hello-istio-product.

  5. Click Save.

  6. You're back on the page that lists all the Developer apps.

  7. Select the app you just created, hello-istio-app.

  8. Click Show next to the Consumer Key.

  9. 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.