Deploying the AWS Gateway API Controller¶

Follow these instructions to create a cluster and deploy the AWS Gateway API Controller. Run through them again for a second cluster to use with the extended example shown later.

NOTE: You can get the yaml files used on this page by cloning the AWS Gateway API Controller repository.

Cluster Setup¶

Using EKS Cluster¶

EKS is a simple, recommended way of preparing a cluster for running services with AWS Gateway API Controller.

Set your region and cluster name as environment variables. See the Amazon VPC Lattice FAQs for a list of supported regions. For this example, we use us-west-2:
```
export AWS_REGION=us-west-2
export CLUSTER_NAME=my-cluster
```

You can use an existing EKS cluster or create a new one as shown here:

eksctl create cluster --name $CLUSTER_NAME --region $AWS_REGION

Configure security group to receive traffic from the VPC Lattice network. You must set up security groups so that they allow all Pods communicating with VPC Lattice to allow traffic from the VPC Lattice managed prefix lists. See Control traffic to resources using security groups for details. Lattice has both an IPv4 and IPv6 prefix lists available.

CLUSTER_SG=$(aws eks describe-cluster --name $CLUSTER_NAME --output json| jq -r '.cluster.resourcesVpcConfig.clusterSecurityGroupId')
PREFIX_LIST_ID=$(aws ec2 describe-managed-prefix-lists --query "PrefixLists[?PrefixListName=="\'com.amazonaws.$AWS_REGION.vpc-lattice\'"].PrefixListId" | jq -r '.[]')
aws ec2 authorize-security-group-ingress --group-id $CLUSTER_SG --ip-permissions "PrefixListIds=[{PrefixListId=${PREFIX_LIST_ID}}],IpProtocol=-1"
PREFIX_LIST_ID_IPV6=$(aws ec2 describe-managed-prefix-lists --query "PrefixLists[?PrefixListName=="\'com.amazonaws.$AWS_REGION.ipv6.vpc-lattice\'"].PrefixListId" | jq -r '.[]')
aws ec2 authorize-security-group-ingress --group-id $CLUSTER_SG --ip-permissions "PrefixListIds=[{PrefixListId=${PREFIX_LIST_ID_IPV6}}],IpProtocol=-1"

Create an IAM OIDC provider: See Creating an IAM OIDC provider for your cluster for details.

eksctl utils associate-iam-oidc-provider --cluster $CLUSTER_NAME --approve --region $AWS_REGION

Create a policy (recommended-inline-policy.json) in IAM with the following content that can invoke the gateway API and copy the policy arn for later use:

{
 "Version": "2012-10-17",
 "Statement": [
     {
         "Effect": "Allow",
         "Action": [
             "vpc-lattice:*",
             "ec2:DescribeVpcs",
             "ec2:DescribeSubnets",
             "ec2:DescribeTags",
             "ec2:DescribeSecurityGroups",
             "logs:CreateLogDelivery",
             "logs:GetLogDelivery",
             "logs:DescribeLogGroups",
             "logs:PutResourcePolicy",
             "logs:DescribeResourcePolicies",
             "logs:UpdateLogDelivery",
             "logs:DeleteLogDelivery",
             "logs:ListLogDeliveries",
             "tag:GetResources",
             "firehose:TagDeliveryStream",
             "s3:GetBucketPolicy",
             "s3:PutBucketPolicy"
         ],
         "Resource": "*"
     },
     {
         "Effect" : "Allow",
         "Action" : "iam:CreateServiceLinkedRole",
         "Resource" : "arn:aws:iam::*:role/aws-service-role/vpc-lattice.amazonaws.com/AWSServiceRoleForVpcLattice",
         "Condition" : {
             "StringLike" : {
                 "iam:AWSServiceName" : "vpc-lattice.amazonaws.com"
             }
         }
     },
     {
         "Effect" : "Allow",
         "Action" : "iam:CreateServiceLinkedRole",
         "Resource" : "arn:aws:iam::*:role/aws-service-role/delivery.logs.amazonaws.com/AWSServiceRoleForLogDelivery",
         "Condition" : {
             "StringLike" : {
                 "iam:AWSServiceName" : "delivery.logs.amazonaws.com"
             }
         }
     }
   ]
}

aws iam create-policy \
   --policy-name VPCLatticeControllerIAMPolicy \
   --policy-document file://examples/recommended-inline-policy.json

Create the aws-application-networking-system namespace:

kubectl apply -f examples/deploy-namesystem.yaml

Retrieve the policy ARN:

export VPCLatticeControllerIAMPolicyArn=$(aws iam list-policies --query 'Policies[?PolicyName==`VPCLatticeControllerIAMPolicy`].Arn' --output text)

Create an iamserviceaccount for pod level permission:

eksctl create iamserviceaccount \
   --cluster=$CLUSTER_NAME \
   --namespace=aws-application-networking-system \
   --name=gateway-api-controller \
   --attach-policy-arn=$VPCLatticeControllerIAMPolicyArn \
   --override-existing-serviceaccounts \
   --region $AWS_REGION \
   --approve

IPv6 support¶

IPv6 address type is automatically used for your services and pods if your cluster is configured to use IPv6 addresses.

# To create an IPv6 cluster
eksctl create cluster -f examples/ipv6-cluster.yaml

If your cluster is configured to be dual-stack, you can set the IP address type of your service using the ipFamilies field. For example:

apiVersion: v1
kind: Service
metadata:
  name: ipv4-target-in-dual-stack-cluster
spec:
  ipFamilies:
    - "IPv4"
  selector:
    app: parking
  ports:
    - protocol: TCP
      port: 80
      targetPort: 8090

Using a self-managed Kubernetes cluster¶

You can install AWS Gateway API Controller to a self-managed Kubernetes cluster in AWS.

The controller utilizes IMDS to get necessary information from instance metadata, such as AWS account ID and VPC ID. If your cluster is using IMDSv2, ensure the hop limit is 2 or higher to allow the access from the controller:

aws ec2 modify-instance-metadata-options --http-put-response-hop-limit 2 --region <region> --instance-id <instance-id>

Alternatively, you can manually provide configuration variables when installing the controller, as described in the next section.

Controller Installation¶

Run either kubectl or helm to deploy the controller. Check Environment Variables for detailed explanation of each configuration option.

kubectl apply -f examples/deploy-v1.0.4.yaml

or

# login to ECR
aws ecr-public get-login-password --region us-east-1 | helm registry login --username AWS --password-stdin public.ecr.aws
# Run helm with either install or upgrade
helm install gateway-api-controller \
   oci://public.ecr.aws/aws-application-networking-k8s/aws-gateway-controller-chart\
   --version=v1.0.4 \
   --set=serviceAccount.create=false --namespace aws-application-networking-system \
   # use "debug" for debug level logs
   --set=log.level=info \
   # awsRegion, clusterVpcId, awsAccountId are required for case IMDS is not available.
   --set=awsRegion= \
   --set=clusterVpcId= \
   --set=awsAccountId= \
   # clusterName is required except for EKS cluster.
   --set=clusterName= \
   # When specified, the controller will automatically create a service network with the name.
   --set=defaultServiceNetwork=my-hotel

Create the amazon-vpc-lattice GatewayClass:

kubectl apply -f examples/gatewayclass.yaml

You are all set! Check our Getting Started Guide to try setting up service-to-service communication.