Manage HTTP APIs with the ACK APIGatewayv2 Controller

Create and invoke an Amazon APIGateway HTTP API using Amazon Elastic Kubernetes Service (EKS).

The ACK service controller for Amazon APIGatewayv2 lets you manage HTTP APIs and VPC Links directly from Kubernetes. This guide will show you how to create and invoke an HTTP API using a single Kubernetes resource manifest.

In this tutorial we will invoke a single public endpoint by fronting it with an HTTP API. We create a Route with GET HTTP method and an HTTP_PROXY Integration forwarding traffic to the public endpoint. We also create an auto-deployable Stage which will deploy the HTTP API and make it invokable.

To invoke many endpoints using the single HTTP API, add multiple Routes and Integrations to the same API.

Setup

Although it is not necessary to use Amazon Elastic Kubernetes Service (Amazon EKS) with ACK, this guide assumes that you have access to an Amazon EKS cluster. If this is your first time creating an Amazon EKS cluster, see Amazon EKS Setup. For automated cluster creation using eksctl, see Getting started with Amazon EKS - eksctl.

Prerequisites

This guide assumes that you have:

  • Created an EKS cluster with Kubernetes version 1.16 or higher.
  • AWS IAM permissions to create roles and attach policies to roles.
  • Installed the following tools on the client machine used to access your Kubernetes cluster:
    • AWS CLI - A command line tool for interacting with AWS services.
    • kubectl - A command line tool for working with Kubernetes clusters.
    • eksctl - A command line tool for working with EKS clusters.
    • Helm 3.8+ - A tool for installing and managing Kubernetes applications.

Install the ACK service controller for APIGatewayv2

Log into the Helm registry that stores the ACK charts:

aws ecr-public get-login-password --region us-east-1 | helm registry login --username AWS --password-stdin public.ecr.aws

Deploy the ACK service controller for Amazon APIGatewayv2 using the apigatewayv2-chart Helm chart. Resources should be created in the us-east-1 region:

helm install --create-namespace -n ack-system oci://public.ecr.aws/aws-controllers-k8s/apigatewayv2-chart --version=0.0.17 --generate-name --set=aws.region=us-east-1

For a full list of available values to the Helm chart, please review the values.yaml file.

Configure IAM permissions

Once the service controller is deployed configure the IAM permissions for the controller to invoke the APIGatewayv2 API. For full details, please review the AWS Controllers for Kubernetes documentation for how to configure the IAM permissions. If you follow the examples in the documentation, use the value of apigatewayv2 for SERVICE.

Create HTTP API

Execute the following command to create a manifest containing all the APIGatewayv2 custom resources and submit this manifest to EKS cluster using kubectl.

Referencing Resources

Notice that the ACK custom resources reference each other using “*Ref” fields inside the manifest and the user does not have to worry about finding APIID, IntegrationID when creating the K8s resource manifests.

Refer to API Reference for APIGatewayv2 to find the supported reference fields.

API_NAME="ack-api"
INTEGRATION_NAME="ack-integration"
INTEGRATION_URI="https://httpbin.org/get"
ROUTE_NAME="ack-route"
ROUTE_KEY_NAME="ack-route-key"
STAGE_NAME="ack-stage"

cat <<EOF > apigwv2-httpapi.yaml
apiVersion: apigatewayv2.services.k8s.aws/v1alpha1
kind: API
metadata:
  name: "${API_NAME}"
spec:
  name: "${API_NAME}"
  protocolType: HTTP

---

apiVersion: apigatewayv2.services.k8s.aws/v1alpha1
kind: Integration
metadata:
  name: "${INTEGRATION_NAME}"
spec:
  apiRef:
    from:
      name: "${API_NAME}"
  integrationType: HTTP_PROXY
  integrationURI: "${INTEGRATION_URI}"
  integrationMethod: GET
  payloadFormatVersion: "1.0"

---

apiVersion: apigatewayv2.services.k8s.aws/v1alpha1
kind: Route
metadata:
  name: "${ROUTE_NAME}"
spec:
  apiRef:
    from:
      name: "${API_NAME}"
  routeKey: "GET /${ROUTE_KEY_NAME}"
  targetRef:
    from:
      name: "${INTEGRATION_NAME}"

---

apiVersion: apigatewayv2.services.k8s.aws/v1alpha1
kind: Stage
metadata:
  name: "${STAGE_NAME}"
spec:
  apiRef:
    from:
      name: "${API_NAME}"
  stageName: "${STAGE_NAME}"
  autoDeploy: true
  description: "auto deployed stage for ${API_NAME}"
EOF

kubectl apply -f apigwv2-httpapi.yaml

The manifest contains 4 APIGatewayv2 custom resources: API, Integration, Route and Stage. When this manifest is submitted using kubectl, it creates corresponding 4 custom resources in the EKS cluster.

The output of above command looks like

api.apigatewayv2.services.k8s.aws/ack-api created
integration.apigatewayv2.services.k8s.aws/ack-integration created
route.apigatewayv2.services.k8s.aws/ack-route created
stage.apigatewayv2.services.k8s.aws/ack-stage created

Describe Custom Resources

View these custom resources using following commands:

kubectl describe api/"${API_NAME}"
kubectl describe integration/"${INTEGRATION_NAME}"
kubectl describe route/"${ROUTE_NAME}"
kubectl describe stage/"${STAGE_NAME}"

Output of describing Route resource looks like

Name:         ack-route
Namespace:    default
Labels:       <none>
Annotations:  <none>
API Version:  apigatewayv2.services.k8s.aws/v1alpha1
Kind:         Route
Metadata:
  Creation Timestamp:  2022-03-08T18:13:16Z
  Finalizers:
    finalizers.apigatewayv2.services.k8s.aws/Route
  Generation:  2
  Resource Version:  116729769
  UID:               0286a10e-0389-4ea8-90ae-890946d5d280
Spec:
  API Key Required:  false
  API Ref:
    From:
      Name:            ack-api
  Authorization Type:  NONE
  Route Key:           GET /ack-route-key
  Target Ref:
    From:
      Name:  ack-integration
Status:
  Ack Resource Metadata:
    Owner Account ID:  ***********
  Conditions:
    Last Transition Time:  2022-03-08T18:13:23Z
    Status:                True
    Type:                  ACK.ReferencesResolved
    Last Transition Time:  2022-03-08T18:13:23Z
    Message:               Resource synced successfully
    Reason:
    Status:                True
    Type:                  ACK.ResourceSynced
  Route ID:                *****
Events:                    <none>
Referencing Resources
ACK controller reads the referenced resources and determines the identifiers, like APIID, from the referenced resources. Find the ACK.ReferencesResolved condition inside the Status of Route, Integration and Stage resources to see the progress of reference resolution.

Invoke HTTP API

Execute the following command to invoke the HTTP API

curl $(kubectl get api/"${API_NAME}" -o=jsonpath='{.status.apiEndpoint}')/"${STAGE_NAME}"/"${ROUTE_KEY_NAME}"

The above commands finds the invocation endpoint from the Api custom resource and appends the required Stage name, Route Key to the url before invoking.

The output should look similar to

{
  "args": {},
  "headers": {
    "Accept": "*/*",
    "Content-Length": "0",
    "Forwarded": "by=****;for=****;host=******.execute-api.us-west-2.amazonaws.com;proto=https",
    "Host": "httpbin.org",
    "User-Agent": "curl/7.64.1",
    "X-Amzn-Trace-Id": "Self=****;Root=****"
  },
  "origin": "****",
  "url": "https://httpbin.org/get"
}

Next steps

The ACK service controller for Amazon APIGatewayv2 is based on the Amazon APIGatewayv2 API.

Refer to API Reference for APiGatewayv2 to find all the supported Kubernetes custom resources and fields.

Note
  • Currently ACK service controller for APIGatewayv2 only supports HTTP APIs.
  • WebSocket API support will be added in future releases.
  • Support for DomainName and APIMapping will also be added in future releases.

Cleanup

Remove all the resource created in this tutorial using kubectl delete command.

kubectl delete -f apigwv2-httpapi.yaml

The output of delete command should look like

api.apigatewayv2.services.k8s.aws "ack-api" deleted
integration.apigatewayv2.services.k8s.aws "ack-integration" deleted
route.apigatewayv2.services.k8s.aws "ack-route" deleted
stage.apigatewayv2.services.k8s.aws "ack-stage" deleted

To remove the APIGatewayv2 ACK service controller, related CRDs, and namespaces, see ACK Cleanup.

To delete your EKS clusters, see Amazon EKS - Deleting a cluster.

Edit this page on GitHub