Installing Apigee Adapter for Istio 1.0.x

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

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.

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

The instructions that follow explain how to install a version of Istio that includes Apigee Adapter. If you already have Istio installed in your cluster, and simply want to upgrade the exiting Istio Mixer component with the Apigee-built Mixer, go to Upgrade an exiting Istio with Apigee Adapter.

Get the Helm package manager

The adapter installation uses the Helm package manager for Kubernetes. To install and configure Helm, follow the instructions in the Helm Quickstart Guide. You must have the Helm client and the Tiller server components installed, as explained in the Helm docs.

Download the Adapter software

Download the software to your system:

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

You are now ready to install the adapter with Istio.

Install Istio using Helm

The following steps explain how to create a new Istio installation with the Apigee Adapter included. Use these steps if you do not currently have Istio installed.

cd to the directory where Istio is installed on your system: For example:
```
cd $PATH_TO_PARENT_DIR/istio-1.0.7
```
Export an environment variable with the path to the apigee-istio-adapter directory:
```
export APIGEE_ADAPTER=$PATH_TO_PARENT_DIR/apigee-istio-adapter
```
Be sure that Tiller is running in the kube-system namespace:

kubectl get pods -n kube-system

If Tiller isn't running, refer to Installation with Helm in the Istio docs for help.
Use one of these Helm command options. For more information on these options, see Installation with Helm in the Istio docs.

Note: The Helm command options are the same as the ones described in Installation with Helm; however, for the adapter, you need to add the parameter --values $APIGEE_ADAPTER/install/mixer/helm.yaml to the command.
1. Option 1:
```
helm install install/kubernetes/helm/istio --name istio \
--namespace istio-system --values $APIGEE_ADAPTER/install/mixer/helm.yaml
```
2. Option 2:
```
helm template install/kubernetes/helm/istio --name istio \
--namespace istio-system --values $APIGEE_ADAPTER/install/mixer/helm.yaml > istio.yaml
```
View the Istio services deployed in the cluster:
```
kubectl get service -n istio-system
```
View the Istio pods and be sure they are all running:
```
kubectl get pods -n istio-system
```
See also Verifying the installation on the Istio doc site.

Next, you will provision required components for your Apigee Edge organization and deploy a "hello world" application to the service mesh and test it.

Upgrade an existing Istio with the Apigee Mixer

If you already have Istio installed, then follow these steps to replace the existing istio-mixer component with the Mixer that has the Apigee Adapter built into it.

Check to see if you have the Apigee Mixer installed or not. The following commands provide the information about the Istio Mixer container image currently deployed in the Istio environment.
```
kubectl get deployment/istio-policy -n istio-system -o yaml | grep image.*istio-mixer
kubectl get deployment/istio-telemetry -n istio-system -o yaml | grep image.*istio-mixer
```
If you see this output, then the Apigee mixer is installed, and you can skip the rest of these steps:

image: gcr.io/apigee-api-management-istio/istio-mixer:1.0.7

If you do not have the Apigee Adapter installed, install it using these commands:

kubectl -n istio-system set image deployment/istio-telemetry mixer=gcr.io/apigee-api-management-istio/istio-mixer:istio_version
kubectl -n istio-system set image deployment/istio-policy mixer=gcr.io/apigee-api-management-istio/istio-mixer:istio_version

where: istio_version is the version of Istio that you are running.

For example:

kubectl -n istio-system set image deployment/istio-telemetry mixer=gcr.io/apigee-api-management-istio/istio-mixer:1.0.7
kubectl -n istio-system set image deployment/istio-policy mixer=gcr.io/apigee-api-management-istio/istio-mixer:1.0.7

If you are using Helm, add the parameter --set mixer-image=gcr.io/apigee-api-management-istio/istio-mixer:istio_version to the install command.

Now, repeat Step 1 to verify that the Apigee Adapter is installed.

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.

cd to the directory where the Apigee adapter is installed: apigee-istio-adapter.
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
```
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
```
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 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] > samples/apigee/handler.yaml
```
With a token:
```
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
```
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.

cd to the directory where the Apigee adapter is installed: apigee-istio-adapter.
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
```
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
```
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 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
```
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.

cd to the Istio installation directory on your system. For example:
```
cd $PATH_TO_PARENT_DIR/istio-1.0.7
```
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
```

Run this command to deploy the test service:

kubectl apply -f samples/helloworld/helloworld.yaml

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.

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
Set an environment variable with the external IP address:
```
export HELLOWORLD_URL=IP_ADDRESS<104.154.82.135
```
For example:

export HELLOWORLD_URL=104.154.82.135

Note: If you are running Istio locally with minikube, refer to this Apigee Community post for the correct command syntax to replace steps 5 and 6.
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.

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

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

Close the file.

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

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.

Note: If you see a successful "Hello" response instead of the authorization error, that may indicate a problem with the Adapter's configuration. If this happens, try restarting the mixer pod(s). For details, see this troubleshooting topic: Debug Authorization check ignored in Istio 1.0.2.

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

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

Select Publish > Developers in the side navigation menu.
Click + Developer.
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.

Select Publish > API Products in the side navigation menu.
Click + API Product. The Product Details page appears.
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
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.
In the lower half of the page, click + Add Custom Resource.
Set the resource to / (a single slash).
Also in the lower part of the page, click + API Proxy.
Select the proxy named istio-auth.
Click + Istio Service.
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:
Click Save.

4. Create a Developer App

Select Publish > Apps in the side navigation menu.
Click + App. The Developer App Details page appears.
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.
In the Credentials section, click + Product and select the product you created: hello-istio-product.
Click Save.
You're back on the page that lists all the Developer apps.
Select the app you just created, hello-istio-app.
Click Show next to the Consumer Key.
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.

Name	`hello-istio-product`
Display Name	`Istio Apigee Test Product`
Environment	`test` and `prod`
Access	`Public`
Key Approval Type	`Automatic`

Name	`hello-istio-app`
Display Name	`Istio Apigee Test App`
Developer	Select the test developer you created or any developer will be fine.