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