Use API management policies with the Apigee APIM Operator for Kubernetes

This page applies to Apigee, but not to Apigee hybrid.

View Apigee Edge documentation.

This page describes how to modify the Google Kubernetes Engine (GKE) Gateway running in your cluster to apply Apigee API management policies using Apigee APIM Operator for Kubernetes (Preview).

Before you begin

Before you begin this task, make sure to complete the following steps:

Confirm that your GKE cluster has a Workload Identity configured. See Create a workload identity for the required steps.
Confirm that your cluster has a GKE Gateway configured and working. See Deploying gateways for more details.
Install the APIM Operator. See Install Apigee APIM Operator for Kubernetes for installation instructions.

Required roles

If you assigned the required roles to your service account as described in Install the Apigee APIM Operator for Kubernetes, no additional IAM roles or permissions are required to complete these tasks.

You can choose to authorize actions on resources in your Google Kubernetes Engine cluster using the built-in role-based access control (RBAC) mechanism in Kubernetes. For more information, see Authorize actions in clusters using role-based access control.

Overview

The following sections describe the steps required to modify your GKE Gateway to use Apigee policies using APIM Operator. In this walkthrough, you will:

Define the APIM Extension policy.
Define the API product.
Define the API operation set.
Test the Apigee service extension.
View Apigee API Analytics in the Google Cloud console.

Define the APIM Extension policy

In this step, you will define the APIM Extension policy and apply it to the GKE Gateway running in your cluster. This policy governs all traffic going through the Gateway and its associated HTTPRoutes, operating similarly to a flowhook at the environment level in Apigee today.

Define the APIM Extension policy:

Create a new file named global-ext-lb1-apim-policy.yaml in the apim namespace.
Copy the following content into the new file:
```
# global-ext-lb1-apim-policy.yaml
apiVersion: apim.googleapis.com/v1alpha1
kind: APIMExtensionPolicy
metadata:
  name: global-ext-lb1-apim-policy 
  namespace: apim
spec:
  apigeeenv: ENV_NAME
  location: global
  failOpen: false
  timeout: 1000ms
  targetRef: # identifies the Gateway where the extension should be applied
    name: global-ext-lb1 
    kind: Gateway
    namespace: default
```
Where ENV_NAME is the name of the Apigee environment created in the optional installation step Create an Apigee environment.
If you did not create the environment during installation, confirm the name of the environment created by the APIM Operator during installation. You can view all available environments in the Apigee UI in the Google Cloud console. The new environment's name will begin with the prefix apim-enabled-dep-env.

Go to to the Apigee Environments page in the Google Cloud console:
Environments
Apply the policy:
```
kubectl -n apim apply -f global-ext-lb1-apim-policy.yaml
```
Once the yaml is applied, the APIM Operator creates networking resources in the background.
Check the status of the API Extension policy using the following command:
```
kubectl -n apim get APIMExtensionPolicy
```
The output should look similar to the following, with a State of RUNNING:
```
NAME                         STATE      ERRORMESSAGE
global-ext-lb1-apim-policy   RUNNING  
```
Note: It may take up to five minutes for the policy to propagate to all load balancer instances.
Use the following command to send a request to the Gateway:
```
curl GATEWAY_IP_ADDRESS/get -k -H "Host: HOST_NAME"
```
Where:
- GATEWAY_IP_ADDRESS is the IP address of the Gateway. You can retrieve the Gateway IP address using the following command, where GATEWAY_NAME is the name of the Gateway:
```
kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME -o=jsonpath="{.status.addresses[0].value}"
```
- HOST_NAME is the hostname defined in the Gateway's HTTPRoute.
The request should fail with a response similar to the following:
```
{"fault":{"faultstring":"Raising fault. Fault name : RF-insufficient-request-raise-fault","detail":{"errorcode":"steps.raisefault.RaiseFault"}}}
```
This indicates that the Apigee extension policy is active and that API key enforcement and access token verification is active.

Define the API Product

Define the API product:

Create a new file named api-product.yaml in the apim namespace.

Copy the following content into the new file:

# api-product.yaml
  apiVersion: apim.googleapis.com/v1alpha1
  kind: APIProduct
  metadata:
    name: api-product
    namespace: apim
  spec:
    approvalType: auto
    description: Http bin GET calls
    displayName: api-product
    enforcementRefs:
      - name: global-ext-lb1-apim-policy
        kind: APIMExtensionPolicy
        group: apim.googleapis.com
        namespace: apim
    attributes:
      - name: access
        value: private

Apply the file to the Gateway using the following command::
```
kubectl -n apim apply -f api-product.yaml
```

Define the API operation set

Define the API operation set for the API product created in the previous step:

Create a new file named apim-policies.yaml in the apim namespace.

Copy the following content into the new file. This file defines a quota policy and the available rest operations for the API product defined in the previous step:

# apim-policies.yaml
  apiVersion: apim.googleapis.com/v1alpha1
  kind: APIOperationSet
  metadata:
    name: item-set
  spec:
    apiProductRefs:
      - name: api-product
        kind: APIProduct
        group: apim.googleapis.com
        namespace: apim
    quota:
      limit: 10
      interval: 1
      timeUnit: minute
    restOperations:
      - name: GetItems
        path: /get
        methods:
          - GET

Apply the file to the Gateway:

kubectl -n apim apply -f apim-policies.yaml

Test the Apigee service extension

In this step, you will use the Apigee UI in Google Cloud console to test the Apigee service extension and the Apigee extension policy applied to your Gateway.

Testing set up

Set up the API resources you need for testing:

Go to to the Apigee API management page in the Google Cloud console:
Apigee API management
Select the Apigee organization where you installed the APIM Operator.
Create a developer:
1. Select Distribution > Developers.
2. On the Developers page, click + Create.
3. In the Add developer page, complete the required fields using any values you wish.
4. Click Add.
Create an App:
1. Select Distribution> Apps.
2. On the Apps page, click + Create
3. On the Create App page, complete the required fields in the App Details section using the following values:
  - App name: demo-app
  - Developer: Select the developer you created in the previous step, or another developer from the list.
4. In the App Credentials section, click + Add Credential.
5. In the Credential section, complete the required fields in the Credential Details section with the following values:
  - Credential name: demo-credential
  - Credential type: Select API Key.
6. Click Create.
7. In the Products section, click + Add products.
8. Select the api-product-1 created in the previous step.
9. Click Add.
10. Click Create.
In the App Details page, in the Credential section, click to display the value of the Key.
Copy the Key value. You will use this key to make API calls to your service in a later step.
In the App Details page, in the Credential section, click to display the value of the App Secret.
Copy the App secret value. You will use this value to generate an access token in a later step.

Test API key enforcement

Use the following command to send a request to your Gateway using the API key obtained in an earlier step:

curl GATEWAY_IP_ADDRESS/get -H "Host: HOST_NAME" -H "x-api-key: API_KEY" -k

Where:

GATEWAY_IP_ADDRESS is the IP address of the Gateway. You can retrieve the Gateway IP address using the following command, where GATEWAY_NAME is the name of the Gateway:
```
kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME -o=jsonpath="{.status.addresses[0].value}"
```
HOST_NAME is the hostname defined in the Gateway's HTTPRoute.
API_KEY is the API key value obtained in Testing set up.

The request should succeed and return a response similar to the following:

{
  "args": {}, 
  "headers": {
    "Accept": "*/*", 
    "Host": "apigee-apim-operator-test.apigee.net", 
    "User-Agent": "curl/8.7.1", 
    "X-Api-Key": "f0N6sXXXclGXXXe0oP5XXXdA20PjgrP2x8xXXh7z4XXXKiYt", 
    "X-Cloud-Trace-Context": "bb3a768787099bda628781188bfb318b/15554891713516675739"
  }, 
  "origin": "34.54.193.72", 
  "url": "https://34.54.193.72/get"
}

Test quota enforcement

To test the quota enforcement defined in your APIM extension policy, send the request from the previous step to the Gateway ten times within the span of one minute.

You can run the following script to generate the requests:

#!/bin/sh
for i in $(seq 1 11); do
    curl GATEWAY_IP_ADDRESS/get -H "Host: HOST_NAME" -H "x-api-key: API_KEY" -k
    sleep 1
done

Where:

GATEWAY_IP_ADDRESS is the IP address of the Gateway. You can retrieve the Gateway IP address using the following command, where GATEWAY_NAME is the name of the Gateway:
```
kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME -o=jsonpath="{.status.addresses[0].value}"
```
HOST_NAME is the hostname defined in the Gateway's HTTPRoute.
API_KEY is the API key value obtained in Testing set up.

This action should trigger a quota violation and raise a fault similar to the following:

{"fault":{"faultstring":"Rate limit quota violation. Quota limit  exceeded. Identifier : _default","detail":{"errorcode":"policies.ratelimit.QuotaViolation"}}}

Test rest operations enforcement

To test the rest operations enforcement, use the following command to send a request to the Gateway using a URL that is not in the API operation set:

curl GATEWAY_IP_ADDRESS/post -H "Host: HOST_NAME" -H "x-api-key: API_KEY" -k

Where:

GATEWAY_IP_ADDRESS is the IP address of the Gateway. You can retrieve the Gateway IP address using the following command, where GATEWAY_NAME is the name of the Gateway:
```
kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME -o=jsonpath="{.status.addresses[0].value}"
```
HOST_NAME is the hostname defined in the Gateway's HTTPRoute.
API_KEY is the API key value obtained in Testing set up.

The request should fail with a response similar to the following:

{"fault":{"faultstring":"Invalid ApiKey for given resource","detail":{"errorcode":"oauth.v2.InvalidApiKeyForGivenResource"}}}

View Apigee API Analytics in the Google Cloud console

You can view the API traffic handled by the GKE Gateway and the APIMExtensionPolicy you installed using Apigee API Analytics in the Google Cloud console:

Go to the Apigee API management page in the Google Cloud console:
Apigee API management
Select the Apigee organization where you installed the APIM Operator.
Select Analytics > API metrics in the side navigation menu.
In the API Proxy Performance tab, choose the environment you created in the optional installation step Create an Apigee environment, or the environment created by the APIM Operator during installation. The environment's name will begin with the prefix apigee-ext-proc-enabled-env.
Observe the API traffic recorded.

Troubleshoot

If you encounter issues when using API management policies with APIM Operator, see Troubleshoot the APIM Operator for solutions to common errors.

What's next

Learn how to Add policies to the GKE Gateway.
Learn how to Uninstall the Apigee APIM Operator for Kubernetes.