diff --git a/docs/guides/deploy.md b/docs/guides/deploy.md index d9b2b373..47eedd20 100644 --- a/docs/guides/deploy.md +++ b/docs/guides/deploy.md @@ -1,26 +1,27 @@ # Deploy the AWS Gateway API Controller on Amazon EKS -This Deployment Guide provides an end-to-end procedure to install the AWS Gateway API Controller with [Amazon Elastic Kubernetes Service](https://aws.amazon.com/eks/). +This Deployment Guide provides an end-to-end procedure to install the AWS Gateway API Controller with [Amazon Elastic Kubernetes Service](https://aws.amazon.com/eks/). -Amazon EKS is a simple, recommended way of preparing a cluster for running services with AWS Gateway API Controller, however the AWS Gateway API Controller can be used on any Kubernetes cluster on AWS. Check out the [Advanced Configurations](advanced-configurations.md) section below for instructions on how to install and run the controller on self-hosted Kubernetes clusters on AWS. +Amazon EKS is a simple, recommended way of preparing a cluster for running services with the AWS Gateway API Controller. However, the AWS Gateway API Controller can be used on any Kubernetes cluster on AWS. Check out the [Advanced Configurations](advanced-configurations.md) section below for instructions on how to install and run the controller on self-hosted Kubernetes clusters on AWS. ### Prerequisites Install these tools before proceeding: 1. [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2-linux.html), -2. `kubectl` - [the Kubernetes CLI](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/), -3. `helm` - [the package manager for Kubernetes](https://helm.sh/docs/intro/install/), -4. `eksctl`- [the CLI for Amazon EKS](https://docs.aws.amazon.com/eks/latest/userguide/setting-up.html), -5. `jq` - [CLI to manipulate json files](https://jqlang.github.io/jq/). +2. `kubectl` – [the Kubernetes CLI](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/), +3. `helm` – [the package manager for Kubernetes](https://helm.sh/docs/intro/install/), +4. `eksctl` – [the CLI for Amazon EKS](https://docs.aws.amazon.com/eks/latest/userguide/setting-up.html), +5. `jq` – [CLI to manipulate JSON files](https://jqlang.github.io/jq/). ### Setup Set your AWS Region and Cluster Name as environment variables. See the [Amazon VPC Lattice FAQs](https://aws.amazon.com/vpc/lattice/faqs/) for a list of supported regions. - ```bash linenums="1" - export AWS_REGION= - export CLUSTER_NAME= - ``` + +```bash +export AWS_REGION= +export EKS_CLUSTER_NAME= +``` **Install Gateway API CRDs** @@ -29,51 +30,55 @@ The latest Gateway API CRDs are available [here](https://gateway-api.sigs.k8s.io **Create a cluster (optional)** You can easily create a cluster with `eksctl`, the CLI for Amazon EKS: - ```bash - eksctl create cluster --name $CLUSTER_NAME --region $AWS_REGION - ``` + +```bash +eksctl create cluster --name ${EKS_CLUSTER_NAME} --region $AWS_REGION +``` **Allow traffic from Amazon VPC Lattice** -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](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html) for details. Lattice has both an IPv4 and IPv6 prefix lists available. +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](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html) for details. Lattice has both IPv4 and IPv6 prefix lists available. + +1. Configure the EKS nodes' security group to receive traffic from the VPC Lattice network. -1. Configure the EKS nodes' security group to receive traffic from the VPC Lattice network. +```bash +CLUSTER_SG= +``` - ```bash - CLUSTER_SG= - ``` - !!!Note - If you have created the cluster with `eksctl create cluster --name $CLUSTER_NAME --region $AWS_REGION` command, you can use this command to export the Security Group ID: +!!!Note + If you have created the cluster with the `eksctl create cluster --name ${EKS_CLUSTER_NAME} --region $AWS_REGION` command, you can use the following command to export the Security Group ID: - ```bash - CLUSTER_SG=$(aws eks describe-cluster --name $CLUSTER_NAME --output json| jq -r '.cluster.resourcesVpcConfig.clusterSecurityGroupId') - ``` +```bash +CLUSTER_SG=$(aws eks describe-cluster --name ${EKS_CLUSTER_NAME} --output json | jq -r '.cluster.resourcesVpcConfig.clusterSecurityGroupId') +``` - ```bash linenums="1" - 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" - ``` +```bash +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" +``` **Set up IAM permissions** -The AWS Gateway API Controller needs to have necessary permissions to operate. +The AWS Gateway API Controller needs to have the necessary permissions to operate. + +1. 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: -1. 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: +```bash +curl https://raw.githubusercontent.com/aws/aws-application-networking-k8s/main/files/controller-installation/recommended-inline-policy.json -o recommended-inline-policy.json - ```bash linenums="1" - curl https://raw.githubusercontent.com/aws/aws-application-networking-k8s/main/files/controller-installation/recommended-inline-policy.json -o recommended-inline-policy.json - - aws iam create-policy \ - --policy-name VPCLatticeControllerIAMPolicy \ - --policy-document file://recommended-inline-policy.json +aws iam create-policy \ + --policy-name VPCLatticeControllerIAMPolicy \ + --policy-document file://recommended-inline-policy.json - export VPCLatticeControllerIAMPolicyArn=$(aws iam list-policies --query 'Policies[?PolicyName==`VPCLatticeControllerIAMPolicy`].Arn' --output text) - ``` +export VPCLatticeControllerIAMPolicyArn=$(aws iam list-policies --query 'Policies[?PolicyName==`VPCLatticeControllerIAMPolicy`].Arn' --output text) +``` + +2. Create the `aws-application-networking-system` namespace: -1. Create the `aws-application-networking-system` namespace: -```bash +```bash +curl -o aws-application-networking-system.yaml https://raw.githubusercontent.com/aws/aws-application-networking-k8s/main/files/controller-installation/deploy-namesystem.yaml kubectl apply -f https://raw.githubusercontent.com/aws/aws-application-networking-k8s/main/files/controller-installation/deploy-namesystem.yaml ``` @@ -81,126 +86,125 @@ You can choose from [Pod Identities](https://docs.aws.amazon.com/eks/latest/user === "Pod Identities (recommended)" - **Set up the Pod Identities Agent** +**Set up the Pod Identities Agent** - To use Pod Identities, we need to [set up the Agent](https://docs.aws.amazon.com/eks/latest/userguide/pod-id-agent-setup.html) and to configure the controller's Kubernetes Service Account to assume necessary permissions with EKS Pod Identity. +To use Pod Identities, set up the [Pod Identity Agent](https://docs.aws.amazon.com/eks/latest/userguide/pod-id-agent-setup.html) and configure the controller's Kubernetes Service Account to assume necessary permissions with EKS Pod Identity. - !!!Note "Read if you are using a custom node role" - The node role needs to have permissions for the Pod Identity Agent to do the `AssumeRoleForPodIdentity` action in the EKS Auth API. Follow [the documentation](https://docs.aws.amazon.com/eks/latest/userguide/pod-id-agent-setup.html) if you are not using the AWS managed policy [AmazonEKSWorkerNodePolicy](https://docs.aws.amazon.com/eks/latest/userguide/security-iam-awsmanpol.html#security-iam-awsmanpol-AmazonEKSWorkerNodePolicy). +!!!Note "Read if you are using a custom node role" + The node role needs to have permissions for the Pod Identity Agent to perform the `AssumeRoleForPodIdentity` action in the EKS Auth API. Follow [the documentation](https://docs.aws.amazon.com/eks/latest/userguide/pod-id-agent-setup.html) if you are not using the AWS managed policy [AmazonEKSWorkerNodePolicy](https://docs.aws.amazon.com/eks/latest/userguide/security-iam-awsmanpol.html#security-iam-awsmanpol-AmazonEKSWorkerNodePolicy). +1. Run the following AWS CLI command to create the Pod Identity addon: - 1. Run the following AWS CLI command to create the Pod Identity addon. - ```bash - aws eks create-addon --cluster-name $CLUSTER_NAME --addon-name eks-pod-identity-agent --addon-version v1.0.0-eksbuild.1 - ``` - ```bash - kubectl get pods -n kube-system | grep 'eks-pod-identity-agent' - ``` +```bash +aws eks create-addon --cluster-name ${EKS_CLUSTER_NAME} --addon-name eks-pod-identity-agent --addon-version v1.0.0-eksbuild.1 +``` - **Assign role to Service Account** +```bash +kubectl get pods -n kube-system | grep 'eks-pod-identity-agent' +``` - Create an IAM role and associate it with a Kubernetes service account. +**Assign role to Service Account** - 1. Create a Service Account. +1. Create a Service Account: - ```bash - cat >gateway-api-controller-service-account.yaml <gateway-api-controller-service-account.yaml <trust-relationship.json < eks-pod-identity-trust-relationship.json <