Update API management policies with the Apigee APIM Operator for Kubernetes

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

View Apigee Edge documentation.

As your API management needs grow and change, you may need to add new services to your cluster or update existing routes and ingress options. This page describes how to update your cluster to complete the following tasks:

Before you begin

Before you begin this task, make sure to complete the steps described in Apply a policy with the Apigee APIM Operator for Kubernetes. This page assumes that you have set up a Google Kubernetes Engine (GKE) cluster, installed the Apigee APIM Operator for Kubernetes, created a Google Kubernetes Engine (GKE) Gateway, and applied at least one API management policy to the Gateway.

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.

Add a new Gateway and HTTPRoute

In this section, you will add a new Gateway and HTTPRoute to your cluster. In previous task guides, the example configurations used an external GKE Gateway. If multiple Gateways are deployed in the same region they must be of the same type (both external or both internal). For this reason, the example configuration in this guide will also use an external Gateway.

The APIM Operator can be used with either internal or external GKE gateways, but you can't deploy both types of gateways in the same region.

To add a new Gateway and HTTPRoute to your cluster, complete the following steps:

  1. Set up a new external GKE Gateway. For more information and steps, see Deploy an external Gateway.
  2. Create a new file named gateway2.yaml in the apim namespace.
  3. Copy the following content into the new file:
    # gateway2.yaml
    apiVersion: gateway.networking.k8s.io/v1beta1
    kind: Gateway
    metadata:
      name: global-ext-lb2
      spec: null
      gatewayClassName: gke-l7-global-external-managed
      listeners:
        - name: https
          protocol: HTTPS
          allowedRoutes:
            kinds:
              - kind: HTTPRoute
            namespaces:
              from: All
          port: 443
          tls:
            options:
              networking.gke.io/pre-shared-certs: apigee-lb-new-cert-sept
  4. Add a new HTTPRoute for /post to the same file, as highlighted below:
    # gateway2.yaml
      apiVersion: gateway.networking.k8s.io/v1beta1
      kind: HTTPRoute
      metadata:
        name: http-bin-route-post
        namespace: http
      spec:
        parentRefs:
          - kind: Gateway
            name: global-ext-lb2
            namespace: default
        hostnames:
          - HOST_NAME_2
        rules:
          - matches:
              - path:
                  value: /post
            backendRefs:
              - name: httpbin
                port: 80
                namespace: http
  5. Apply the new Gateway and HTTPRoute:
    kubectl apply -f gateway2.yaml
  6. Check the HTTPRoute status using the following command::
    kubectl -n http get HttpRoute

    The output should be similar to the following:

    NAME             HOSTNAMES                                                  AGE
    http-bin-route   ["my-hostname-2"]   12d
    
  7. Check the Gateway status using the following command:
    kubectl get gateway global-ext-lb2

    The output should be similar to the following:

    NAME             CLASS                            ADDRESS        PROGRAMMED   AGE
    global-ext-lb2   gke-l7-global-external-managed   34.54.193.92   True         11d
    

    Confirm that the Address column contains a valid IP address and the status of Programmed is True.

  8. Describe the Gateway to make sure the route is attached:
    kubectl describe gateway global-ext-lb2
  9. The output should be similar to the following:

    ...
    Listeners:
      Attached Routes:  1
      Conditions:
        Last Transition Time:  2024-10-03T03:10:17Z
    ...

    Confirm that the Attached Routes value is 1.

  10. Send a request to the Gateway to verify that the route is working:
    curl -X POST https://GATEWAY_IP_ADDRESS/get -k -H "Host: HOST_NAME"

    Where:

    • GATEWAY_IP_ADDRESS is the IP address of the Gateway, as shown in the Address column of the response returned in Step 7.
    • HOST_NAME is the hostname defined in the Gateway's HTTPRoute.

  11. The output should be similar to the following:
      {
        "args": {}, 
        "headers": {
          "Accept": "*/*", 
          "Host": "apigee-apim-operator-test.apigee.net", 
          "User-Agent": "curl/8.7.1", 
          "X-Cloud-Trace-Context": "2bb8a80e29e80662ff9cb89971c447d9/13083106619927322701"
        }, 
        "origin": "67.164.1.10,34.54.193.72", 
        "url": "https://apigee-apim-operator-test.apigee.net/post"
      }
      
  12. Create a new API Extension Policy that references the HTTPRoute of the new Gateway created in an earlier step:
    1. Create a new file named apim-policy2.yaml in the apim namespace.
    2. Copy the following content into the new file:
      # apim-policy2.yaml
      apiVersion: apim.googleapis.com/v1alpha1
      kind: APIMExtensionPolicy
      metadata:
      name: global-ext-lb2-apim-policy-2
      namespace: apigee
      spec:
      location: global
      failOpen: false
      timeout: 1000ms
      targetRef: # identifies the Gateway where the extension should be installed
        name: global-ext-lb2 
        kind: Gateway
        namespace: default
    3. Apply the new API Extension Policy:
      kubectl apply -f apim-policy2.yaml

      Once the file is applied, the APIM Operator creates networking resources in the background.

    4. Check the status of the API Extension Policy:
      kubectl -n apigee get APIMExtensionPolicy

      The output should be similar to the following:

      NAME                         STATE      ERRORMESSAGE
      global-ext-lb2-apim-policy   RUNNING  
      

      Confirm that the STATE value is RUNNING.

    5. Wait five minutes to ensure the changes propagate to all the load balancer instances, then use the following command to verify that a request to the new Gateway fails:
      curl -X POST https://GATEWAY_IP_ADDRESS/get -k -H "Host: HOSTNAME"

      Where:

      • GATEWAY_IP_ADDRESS is the IP address of the Gateway obtained in an earlier step.
      • 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 means the service extension to Apigee is active and API key and access token verification is enforced. For the steps required to create a Developer App, obtain an API key, and test your new Gateway with the key, see Test the Apigee service extension.

Update an API product

Modify an existing API product to reference the new API Extension Policy:

  1. Create a new file named api-product-2.yaml in the apim namespace.
  2. Copy the following content into the new file:
    # api-product-2.yaml
    apiVersion: apim.googleapis.com/v1alpha1
    kind: APIProduct
    metadata:
    name: api-product-2
    namespace: apigee-apim
    spec:
    approvalType: auto
    description: Http bin GET calls
    displayName: api-product-2
    EnforcementRefs:
      - name: global-ext-lb1-apim-policy 
        kind: APIMExtensionPolicy
        group: apim.googleapis.com
        namespace: apigee-apim
      - name: global-ext-lb2-apim-policy 
        kind: APIMExtensionPolicy
        group: apim.googleapis.com
        namespace: apigee-apim
    attributes:
      - name: access
        value: private
  3. Apply the new API product file:
    kubectl apply -f api-product-2.yaml

    It will take approximately three minutes for the changes to be applied throughout the cluster.

In this example, the EnforcementRefs section of the API product api-product-2 is updated to reference both global-ext-lb1-apim-policy and global-ext-lb2-apim-policy, as shown in the highlighted portions of the yaml.

Create a new API product

Create a new API product:

  1. Create a new file named api-product-2.yaml in the apim namespace.
  2. Copy the following content into the new file:
    # api-product-2.yaml
    apiVersion: apim.googleapis.com/v1alpha1
    kind: APIProduct
    metadata:
     name: api-product-2
     namespace: apigee-apim
    spec:
      approvalType: auto
      description: Http bin GET calls
      displayName: api-product-2
      enforcementRefs:
        - name: global-ext-lb2-apim-policy 
          kind: APIMExtensionPolicy
          group: apim.googleapis.com
          namespace: apim
      attributes:
        - name: access
          value: private
  3. Apply the new API product file:
    kubectl apply -f api-product-2.yaml

    It will take approximately three minutes for the changes to be applied throughout the cluster.

In this example, the EnforcementRefs section of the new API product api-product-2 is created to reference global-ext-lb2-apim-policy, as shown in the highlighted portions of the yaml.

Create a new API operation set

Create a new API operation set:

  1. Create a new file named item-set-post.yaml in the apim namespace.
  2. Copy the following content into the new file:
    # item-set-post.yaml
    apiVersion: apim.googleapis.com/v1alpha1
    kind: APIOperationSet
    metadata:
      name: item-set-post
      namespace: apigee-apim
    spec:
      apiProductRefs:
        - name: api-product-1
          kind: APIProduct
          group: apim.googleapis.com
          namespace: apigee-apim
      quota:
        limit: 1
        interval: 1
        timeUnit: minute
      restOperations:
        - name: PostItems
          path: "/post"
          methods:
          - POST
  3. Apply the new API operation set file:
    kubectl apply -f item-set-post.yaml

    It will take approximately three minutes for the changes to be applied throughout the cluster.

In this example, the restOperations value of the new API operation set item-set-post is created to reference the /post path, as shown in the highlighted portions of the file.

Test the new Gateway configuration

To test the new Gateway configuration, send the following request to the new /post path:

curl -X POST https://GATEWAY_IP_ADDRESS/post -k -H "Host: HOST_NAME"

Where:

  • GATEWAY_IP_ADDRESS is the IP address of the Gateway obtained in an earlier step.
  • HOST_NAME is the hostname defined in the Gateway's HTTPRoute.

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"
}

Troubleshoot

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

What's next