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:
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.
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>
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.
- 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.