Skip to content

Commit 603fbfb

Browse files
d-padmanabhanrlymbur
d-padmanabhan
and
rlymbur
authored
fix formatting issues in deploy.md (#726)
* fix formatting issues in deploy.md * fix formatting issues in deploy.md --------- Co-authored-by: Ryan Lymburner <[email protected]>
1 parent 2426ab4 commit 603fbfb

File tree

1 file changed

+135
-131
lines changed

1 file changed

+135
-131
lines changed

‎docs/guides/deploy.md‎

Lines changed: 135 additions & 131 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,27 @@
11
# Deploy the AWS Gateway API Controller on Amazon EKS
22

3-
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/).
3+
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/).
44

5-
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.
5+
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.
66

77
### Prerequisites
88

99
Install these tools before proceeding:
1010

1111
1. [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2-linux.html),
12-
2. `kubectl` - [the Kubernetes CLI](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/),
13-
3. `helm` - [the package manager for Kubernetes](https://helm.sh/docs/intro/install/),
14-
4. `eksctl`- [the CLI for Amazon EKS](https://docs.aws.amazon.com/eks/latest/userguide/setting-up.html),
15-
5. `jq` - [CLI to manipulate json files](https://jqlang.github.io/jq/).
12+
2. `kubectl` – [the Kubernetes CLI](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/),
13+
3. `helm` – [the package manager for Kubernetes](https://helm.sh/docs/intro/install/),
14+
4. `eksctl` – [the CLI for Amazon EKS](https://docs.aws.amazon.com/eks/latest/userguide/setting-up.html),
15+
5. `jq` – [CLI to manipulate JSON files](https://jqlang.github.io/jq/).
1616

1717
### Setup
1818

1919
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.
20-
```bash linenums="1"
21-
export AWS_REGION=<cluster_region>
22-
export CLUSTER_NAME=<cluster_name>
23-
```
20+
21+
```bash
22+
export AWS_REGION=<eks_cluster_region>
23+
export EKS_CLUSTER_NAME=<EKS_CLUSTER_NAME>
24+
```
2425

2526
**Install Gateway API CRDs**
2627

@@ -29,178 +30,181 @@ The latest Gateway API CRDs are available [here](https://gateway-api.sigs.k8s.io
2930
**Create a cluster (optional)**
3031

3132
You can easily create a cluster with `eksctl`, the CLI for Amazon EKS:
32-
```bash
33-
eksctl create cluster --name $CLUSTER_NAME --region $AWS_REGION
34-
```
33+
34+
```bash
35+
eksctl create cluster --name ${EKS_CLUSTER_NAME} --region $AWS_REGION
36+
```
3537

3638
**Allow traffic from Amazon VPC Lattice**
3739

38-
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.
40+
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.
41+
42+
1. Configure the EKS nodes' security group to receive traffic from the VPC Lattice network.
3943

40-
1. Configure the EKS nodes' security group to receive traffic from the VPC Lattice network.
44+
```bash
45+
CLUSTER_SG=<your_node_security_group>
46+
```
4147

42-
```bash
43-
CLUSTER_SG=<your_node_security_group>
44-
```
45-
!!!Note
46-
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:
48+
!!!Note
49+
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:
4750

48-
```bash
49-
CLUSTER_SG=$(aws eks describe-cluster --name $CLUSTER_NAME --output json| jq -r '.cluster.resourcesVpcConfig.clusterSecurityGroupId')
50-
```
51+
```bash
52+
CLUSTER_SG=$(aws eks describe-cluster --name ${EKS_CLUSTER_NAME} --output json | jq -r '.cluster.resourcesVpcConfig.clusterSecurityGroupId')
53+
```
5154

52-
```bash linenums="1"
53-
PREFIX_LIST_ID=$(aws ec2 describe-managed-prefix-lists --query "PrefixLists[?PrefixListName=="\'com.amazonaws.$AWS_REGION.vpc-lattice\'"].PrefixListId" | jq -r '.[]')
54-
aws ec2 authorize-security-group-ingress --group-id $CLUSTER_SG --ip-permissions "PrefixListIds=[{PrefixListId=${PREFIX_LIST_ID}}],IpProtocol=-1"
55-
PREFIX_LIST_ID_IPV6=$(aws ec2 describe-managed-prefix-lists --query "PrefixLists[?PrefixListName=="\'com.amazonaws.$AWS_REGION.ipv6.vpc-lattice\'"].PrefixListId" | jq -r '.[]')
56-
aws ec2 authorize-security-group-ingress --group-id $CLUSTER_SG --ip-permissions "PrefixListIds=[{PrefixListId=${PREFIX_LIST_ID_IPV6}}],IpProtocol=-1"
57-
```
55+
```bash
56+
PREFIX_LIST_ID=$(aws ec2 describe-managed-prefix-lists --query "PrefixLists[?PrefixListName=='com.amazonaws.$AWS_REGION.vpc-lattice'].PrefixListId" | jq -r '.[]')
57+
aws ec2 authorize-security-group-ingress --group-id $CLUSTER_SG --ip-permissions "PrefixListIds=[{PrefixListId=${PREFIX_LIST_ID}}],IpProtocol=-1"
58+
PREFIX_LIST_ID_IPV6=$(aws ec2 describe-managed-prefix-lists --query "PrefixLists[?PrefixListName=='com.amazonaws.$AWS_REGION.ipv6.vpc-lattice'].PrefixListId" | jq -r '.[]')
59+
aws ec2 authorize-security-group-ingress --group-id $CLUSTER_SG --ip-permissions "PrefixListIds=[{PrefixListId=${PREFIX_LIST_ID_IPV6}}],IpProtocol=-1"
60+
```
5861

5962
**Set up IAM permissions**
6063

61-
The AWS Gateway API Controller needs to have necessary permissions to operate.
64+
The AWS Gateway API Controller needs to have the necessary permissions to operate.
65+
66+
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:
6267

63-
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:
68+
```bash
69+
curl https://raw.githubusercontent.com/aws/aws-application-networking-k8s/main/files/controller-installation/recommended-inline-policy.json -o recommended-inline-policy.json
6470

65-
```bash linenums="1"
66-
curl https://raw.githubusercontent.com/aws/aws-application-networking-k8s/main/files/controller-installation/recommended-inline-policy.json -o recommended-inline-policy.json
67-
68-
aws iam create-policy \
69-
--policy-name VPCLatticeControllerIAMPolicy \
70-
--policy-document file://recommended-inline-policy.json
71+
aws iam create-policy \
72+
--policy-name VPCLatticeControllerIAMPolicy \
73+
--policy-document file://recommended-inline-policy.json
7174

72-
export VPCLatticeControllerIAMPolicyArn=$(aws iam list-policies --query 'Policies[?PolicyName==`VPCLatticeControllerIAMPolicy`].Arn' --output text)
73-
```
75+
export VPCLatticeControllerIAMPolicyArn=$(aws iam list-policies --query 'Policies[?PolicyName==`VPCLatticeControllerIAMPolicy`].Arn' --output text)
76+
```
77+
78+
2. Create the `aws-application-networking-system` namespace:
7479

75-
1. Create the `aws-application-networking-system` namespace:
76-
```bash
80+
```bash
81+
curl -o aws-application-networking-system.yaml https://raw.githubusercontent.com/aws/aws-application-networking-k8s/main/files/controller-installation/deploy-namesystem.yaml
7782
kubectl apply -f https://raw.githubusercontent.com/aws/aws-application-networking-k8s/main/files/controller-installation/deploy-namesystem.yaml
7883
```
7984

8085
You can choose from [Pod Identities](https://docs.aws.amazon.com/eks/latest/userguide/pod-identities.html) (recommended) and [IAM Roles For Service Accounts](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) to set up controller permissions.
8186

8287
=== "Pod Identities (recommended)"
8388

84-
**Set up the Pod Identities Agent**
89+
**Set up the Pod Identities Agent**
8590

86-
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.
91+
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.
8792

88-
!!!Note "Read if you are using a custom node role"
89-
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).
93+
!!!Note "Read if you are using a custom node role"
94+
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).
9095

96+
1. Run the following AWS CLI command to create the Pod Identity addon:
9197

92-
1. Run the following AWS CLI command to create the Pod Identity addon.
93-
```bash
94-
aws eks create-addon --cluster-name $CLUSTER_NAME --addon-name eks-pod-identity-agent --addon-version v1.0.0-eksbuild.1
95-
```
96-
```bash
97-
kubectl get pods -n kube-system | grep 'eks-pod-identity-agent'
98-
```
98+
```bash
99+
aws eks create-addon --cluster-name ${EKS_CLUSTER_NAME} --addon-name eks-pod-identity-agent --addon-version v1.0.0-eksbuild.1
100+
```
99101

100-
**Assign role to Service Account**
102+
```bash
103+
kubectl get pods -n kube-system | grep 'eks-pod-identity-agent'
104+
```
101105

102-
Create an IAM role and associate it with a Kubernetes service account.
106+
**Assign role to Service Account**
103107

104-
1. Create a Service Account.
108+
1. Create a Service Account:
105109

106-
```bash
107-
cat >gateway-api-controller-service-account.yaml <<EOF
108-
apiVersion: v1
109-
kind: ServiceAccount
110-
metadata:
111-
name: gateway-api-controller
112-
namespace: aws-application-networking-system
113-
EOF
114-
kubectl apply -f gateway-api-controller-service-account.yaml
115-
```
110+
```bash
111+
cat >gateway-api-controller-service-account.yaml <<EOF
112+
apiVersion: v1
113+
kind: ServiceAccount
114+
metadata:
115+
name: gateway-api-controller
116+
namespace: aws-application-networking-system
117+
EOF
118+
kubectl apply -f gateway-api-controller-service-account.yaml
119+
```
116120

117-
1. Create a trust policy file for the IAM role.
121+
2. Create a trust policy file for the IAM role:
118122

119-
```bash
120-
cat >trust-relationship.json <<EOF
123+
```bash
124+
cat > eks-pod-identity-trust-relationship.json <<EOF
125+
{
126+
"Version": "2012-10-17",
127+
"Statement": [
121128
{
122-
"Version": "2012-10-17",
123-
"Statement": [
124-
{
125-
"Sid": "AllowEksAuthToAssumeRoleForPodIdentity",
126-
"Effect": "Allow",
127-
"Principal": {
128-
"Service": "pods.eks.amazonaws.com"
129-
},
130-
"Action": [
131-
"sts:AssumeRole",
132-
"sts:TagSession"
133-
]
134-
}
129+
"Sid": "AllowEksAuthToAssumeRoleForPodIdentity",
130+
"Effect": "Allow",
131+
"Principal": {
132+
"Service": "pods.eks.amazonaws.com"
133+
},
134+
"Action": [
135+
"sts:AssumeRole",
136+
"sts:TagSession"
135137
]
136138
}
137-
EOF
138-
```
139+
]
140+
}
141+
EOF
142+
```
139143

140-
1. Create the role.
144+
3. Create the role:
141145

142-
```bash
143-
aws iam create-role --role-name VPCLatticeControllerIAMRole --assume-role-policy-document file://trust-relationship.json --description "IAM Role for AWS Gateway API Controller for VPC Lattice"
144-
aws iam attach-role-policy --role-name VPCLatticeControllerIAMRole --policy-arn=$VPCLatticeControllerIAMPolicyArn
145-
export VPCLatticeControllerIAMRoleArn=$(aws iam list-roles --query 'Roles[?RoleName==`VPCLatticeControllerIAMRole`].Arn' --output text)
146-
```
147-
148-
1. Create the association
146+
```bash
147+
aws iam create-role --role-name VPCLatticeControllerIAMRole --assume-role-policy-document file://teks-pod-identity-trust-relationship.json --description "IAM Role for AWS Gateway API Controller for VPC Lattice"
148+
aws iam attach-role-policy --role-name VPCLatticeControllerIAMRole --policy-arn=$VPCLatticeControllerIAMPolicyArn
149+
export VPCLatticeControllerIAMRoleArn=$(aws iam list-roles --query 'Roles[?RoleName==`VPCLatticeControllerIAMRole`].Arn' --output text)
150+
```
151+
152+
4. Create the association:
149153

150-
```bash
151-
aws eks create-pod-identity-association --cluster-name $CLUSTER_NAME --role-arn $VPCLatticeControllerIAMRoleArn --namespace aws-application-networking-system --service-account gateway-api-controller
152-
```
154+
```bash
155+
aws eks create-pod-identity-association --cluster-name ${EKS_CLUSTER_NAME} --role-arn ${VPCLatticeControllerIAMRoleArn} --namespace aws-application-networking-system --service-account gateway-api-controller
156+
```
153157

154158
=== "IRSA"
155159

156-
You can use AWS IAM Roles for Service Accounts (IRSA) to assign the Controller necessary permissions via a ServiceAccount.
160+
You can use AWS IAM Roles for Service Accounts (IRSA) to assign the controller necessary permissions via a ServiceAccount.
157161

158-
1. Create an IAM OIDC provider: See [Creating an IAM OIDC provider for your cluster](https://docs.aws.amazon.com/eks/latest/userguide/enable-iam-roles-for-service-accounts.html) for details.
159-
```bash
160-
eksctl utils associate-iam-oidc-provider --cluster $CLUSTER_NAME --approve --region $AWS_REGION
161-
```
162+
1. Create an IAM OIDC provider. See [Creating an IAM OIDC provider for your cluster](https://docs.aws.amazon.com/eks/latest/userguide/enable-iam-roles-for-service-accounts.html) for details.
162163

163-
1. Create an iamserviceaccount for pod level permission:
164+
```bash
165+
eksctl utils associate-iam-oidc-provider --cluster ${EKS_CLUSTER_NAME} --approve --region $AWS_REGION
166+
```
164167

165-
```bash linenums="1"
166-
eksctl create iamserviceaccount \
167-
--cluster=$CLUSTER_NAME \
168-
--namespace=aws-application-networking-system \
169-
--name=gateway-api-controller \
170-
--attach-policy-arn=$VPCLatticeControllerIAMPolicyArn \
171-
--override-existing-serviceaccounts \
172-
--region $AWS_REGION \
173-
--approve
174-
```
168+
2. Create an IAM service account for pod-level permission:
169+
170+
```bash
171+
eksctl create iamserviceaccount \
172+
--cluster=${EKS_CLUSTER_NAME} \
173+
--namespace=aws-application-networking-system \
174+
--name=gateway-api-controller \
175+
--attach-policy-arn=$VPCLatticeControllerIAMPolicyArn \
176+
--override-existing-serviceaccounts \
177+
--region $AWS_REGION \
178+
--approve
179+
```
175180

176181
### Install the Controller
177182

178-
1. Run **either** `kubectl` or `helm` to deploy the controller. Check [Environment Variables](../guides/environment.md) for detailed explanation of each configuration option.
183+
Run **either** `kubectl` or `helm` to deploy the controller. Check [Environment Variables](../guides/environment.md) for a detailed explanation of each configuration option.
179184

180-
=== "Helm"
185+
=== "Helm"
181186

182-
```bash linenums="1"
183-
# login to ECR
184-
aws ecr-public get-login-password --region us-east-1 | helm registry login --username AWS --password-stdin public.ecr.aws
185-
# Run helm with either install or upgrade
186-
helm install gateway-api-controller \
187-
oci://public.ecr.aws/aws-application-networking-k8s/aws-gateway-controller-chart \
188-
--version=v1.1.0 \
189-
--set=serviceAccount.create=false \
190-
--namespace aws-application-networking-system \
191-
--set=log.level=info # use "debug" for debug level logs
192-
```
187+
```bash
188+
# login to ECR
189+
aws ecr-public get-login-password --region us-east-1 | helm registry login --username AWS --password-stdin public.ecr.aws
193190

194-
=== "Kubectl"
191+
# Run helm with either install or upgrade
192+
helm install gateway-api-controller \
193+
oci://public.ecr.aws/aws-application-networking-k8s/aws-gateway-controller-chart \
194+
--version=v1.1.0 \
195+
--set=serviceAccount.create=false \
196+
--namespace aws-application-networking-system \
197+
--set=log.level=info # use "debug" for debug level logs
198+
```
195199

196-
```bash
197-
kubectl apply -f https://raw.githubusercontent.com/aws/aws-application-networking-k8s/main/files/controller-installation/deploy-v1.1.0.yaml
198-
```
200+
=== "Kubectl"
199201

202+
```bash
203+
kubectl apply -f https://raw.githubusercontent.com/aws/aws-application-networking-k8s/main/files/controller-installation/deploy-v1.1.0.yaml
204+
```
200205

201206
1. Create the `amazon-vpc-lattice` GatewayClass:
202-
```bash
203-
kubectl apply -f https://raw.githubusercontent.com/aws/aws-application-networking-k8s/main/files/controller-installation/gatewayclass.yaml
204-
```
205-
206207

208+
```bash
209+
kubectl apply -f https://raw.githubusercontent.com/aws/aws-application-networking-k8s/main/files/controller-installation/gatewayclass.yaml
210+
```

0 commit comments

Comments
 (0)