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.
Option 1:
helm install install/kubernetes/helm/istio --name istio \ --namespace istio-system --values $APIGEE_ADAPTER/install/mixer/helm.yaml
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
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 thePATH
. This step allows you to execute theapigee-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
, andpassword
are your Apigee account values. The username is typically your Apigee account email address. If used, thetoken
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 thePATH
. This step allows you to execute theapigee-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
, andpassword
are your Apigee account values. The username is typically your Apigee account email address. If used, thetoken
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
, andpassword
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 thetest
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
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 theapigee-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.
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
andprod
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.