Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

cherry pick #3121 to branch release-2.4 and update the version to 2.4.7 #3122

Merged
merged 1 commit into from
Mar 24, 2023
Merged

cherry pick #3121 to branch release-2.4 and update the version to 2.4.7 #3122

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 54 additions & 46 deletions docs/deploy/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,42 +1,42 @@
# Load Balancer Controller Installation
# AWS Load Balancer Controller installation

The Load Balancer controller (LBC) provisions AWS Network Load Balancer (NLB) and Application Load Balancer (ALB) resources. The LBC watches for new service or ingress kubernetes resources, and configures AWS resources.
The AWS Load Balancer controller (LBC) provisions AWS Network Load Balancer (NLB) and Application Load Balancer (ALB) resources. The LBC watches for new `service` or `ingress` Kubernetes resources and configures AWS resources.

The LBC is supported by AWS. Some clusters may using legacy "in-tree" functionality to provision AWS load balancers. The AWS Load Balancer Controller should be installed instead.
The LBC is supported by AWS. Some clusters may be using the legacy "in-tree" functionality to provision AWS load balancers. The AWS Load Balancer Controller should be installed instead.

!!!question "Existing AWS ALB Ingress Controller users"
AWS ALB Ingress controller must be uninstalled before installing AWS Load Balancer Controller.
Please follow our [migration guide](upgrade/migrate_v1_v2.md) to do migration.
The AWS ALB Ingress controller must be uninstalled before installing the AWS Load Balancer Controller.
Please follow our [migration guide](upgrade/migrate_v1_v2.md) to do a migration.

## Supported Kubernetes Versions
## Supported Kubernetes versions
* AWS Load Balancer Controller v2.0.0~v2.1.3 requires Kubernetes 1.15+
* AWS Load Balancer Controller v2.2.0~v2.3.1 requires Kubernetes 1.16-1.21
* AWS Load Balancer Controller v2.4.0+ requires Kubernetes 1.19+

## Deployment Considerations
## Deployment considerations

### Additional Requirements for non-EKS clusters:
### Additional requirements for non-EKS clusters:

* Ensure subnets are tagged appropriately for auto-discovery to work
* For IP targets, pods must have IPs from the VPC subnets. You can configure `amazon-vpc-cni-k8s` plugin for this purpose.
* For IP targets, pods must have IPs from the VPC subnets. You can configure the [`amazon-vpc-cni-k8s`](https://github.com/aws/amazon-vpc-cni-k8s#readme) plugin for this purpose.

### Using metadata server version 2 (IMDSv2)
If you are using the [IMDSv2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html) you must set the hop limit to 2 or higher in order to allow the AWS Load Balancer Controller to perform the metadata introspection.
### Using the Amazon EC2 instance metadata server version 2 (IMDSv2)
If you are using the [IMDSv2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html), set the hop limit to 2 or higher in order to allow the LBC to perform the metadata introspection.

You can set the IMDSv2 hop limit as follows:
```
aws ec2 modify-instance-metadata-options --http-put-response-hop-limit 2 --region <region> --instance-id <instance-id>
```

Instead of depending on IMDSv2, you alternatively may specify the AWS region and the VPC via the controller flags `--aws-region` and `--aws-vpc-id`.
Instead of depending on IMDSv2, you can specify the AWS Region and the VPC via the controller flags `--aws-region` and `--aws-vpc-id`.

## Configure IAM

The controller runs on the worker nodes, so it needs access to the AWS ALB/NLB APIs via IAM permissions.
The controller runs on the worker nodes, so it needs access to the AWS ALB/NLB APIs with IAM permissions.

The IAM permissions can either be setup via [IAM roles for ServiceAccount (IRSA)](https://docs.aws.amazon.com/emr/latest/EMR-on-EKS-DevelopmentGuide/setting-up-enable-IAM.html) or can be attached directly to the worker node IAM roles. If you are using kops or vanilla k8s, polices must be manually attached to node instances.
The IAM permissions can either be setup using [IAM roles for service accounts (IRSA)](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) or can be attached directly to the worker node IAM roles. This is the recommended method if you're using Amazon EKS. If you're using kOps or self-hosted Kubernetes, you must manually attach polices to node instances.

### Option A: IAM Roles for Service Accounts (IRSA)
### Option A: IAM roles for service accounts (IRSA)

The reference IAM policies contain the following permissive configuration:
```
Expand All @@ -50,7 +50,7 @@ The reference IAM policies contain the following permissive configuration:
},
```

We recommend to further scope down this configuration based on the VPC ID or cluster name resource tag.
We recommend further scoping down this configuration based on the VPC ID or cluster name resource tag.

Example condition for VPC ID:
```
Expand All @@ -70,28 +70,37 @@ Example condition for cluster name resource tag:
}
```

1. Create IAM OIDC provider
1. Create an IAM OIDC provider. You can skip this step if you already have one for your cluster.
```
eksctl utils associate-iam-oidc-provider \
--region <region-code> \
--cluster <your-cluster-name> \
--approve
```

1. Download IAM policy for the AWS Load Balancer Controller
2. Download an IAM policy for the LBC using one of the following commands:<p>
If your cluster is in a US Gov Cloud region:
```
curl -o iam-policy.json https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.4.7/docs/install/iam_policy.json
curl -o iam-policy.json https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.4.7/docs/install/iam_policy_us-gov.json
```
If your cluster is in a China region:
```
curl -o iam-policy.json https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.4.7/docs/install/iam_policy_cn.json
```
If your cluster is in any other region:
```
curl -o iam-policy.json https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.4.7/docs/install/iam_policy.json
```

1. Create an IAM policy called AWSLoadBalancerControllerIAMPolicy
3. Create an IAM policy named `AWSLoadBalancerControllerIAMPolicy`. If you downloaded a different policy, replace `iam-policy` with the name of the policy that you downloaded.
```
aws iam create-policy \
--policy-name AWSLoadBalancerControllerIAMPolicy \
--policy-document file://iam-policy.json
```
Take note of the policy ARN that is returned
Take note of the policy ARN that's returned.

1. Create a IAM role and ServiceAccount for the AWS Load Balancer controller, use the ARN from the step above
4. Create an IAM role and Kubernetes `ServiceAccount` for the LBC. Use the ARN from the previous step.
```
eksctl create iamserviceaccount \
--cluster=<cluster-name> \
Expand All @@ -103,13 +112,13 @@ Example condition for cluster name resource tag:
--approve
```

### Option B: Attach IAM Policies to Nodes
If not setting up IAM for ServiceAccount, apply the IAM policies from the following URL at minimum.
### Option B: Attach IAM policies to nodes
If you're not setting up IAM roles for service accounts, apply the IAM policies from the following URL at a minimum.
```
curl -o iam-policy.json https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.4.7/docs/install/iam_policy.json
```

*IAM permission subset for those who use *TargetGroupBinding* only and don't plan to use the AWS Load Balancer Controller to manage security group rules:*
The following IAM permissions subset is for those using `TargetGroupBinding` only and don't plan to use the LBC to manage security group rules:

```
{
Expand All @@ -134,32 +143,30 @@ curl -o iam-policy.json https://raw.githubusercontent.com/kubernetes-sigs/aws-lo
}
```

## Network configuration


## Network Configuration

Review the [worker nodes security group](https://docs.aws.amazon.com/eks/latest/userguide/sec-group-reqs.html) docs. The node security group must permit incoming traffic on TCP port 9443 from the kubernetes control plane. This is needed for webhook access.
Review the [worker nodes security group](https://docs.aws.amazon.com/eks/latest/userguide/sec-group-reqs.html) docs. Your node security group must permit incoming traffic on TCP port 9443 from the Kubernetes control plane. This is needed for webhook access.

If you use [eksctl](https://eksctl.io/usage/vpc-networking/), this is the default configuration.

## Add Controller to Cluster
## Add controller to cluster

We recommend using the Helm chart. This supports Fargate and facilitates updating the controller.
We recommend using the Helm chart to install the controller. The chart supports Fargate and facilitates updating the controller.

=== "Via Helm"
=== "Helm"

If you want to run the controller on Fargate, use the Helm chart since it does not depend on the cert-manager.
If you want to run the controller on Fargate, use the Helm chart, since it doesn't depend on the `cert-manager`.

### Detailed Instructions
Follow the instructions in [aws-load-balancer-controller](https://github.com/aws/eks-charts/tree/master/stable/aws-load-balancer-controller) helm chart.
### Detailed instructions
Follow the instructions in the [aws-load-balancer-controller](https://github.com/aws/eks-charts/tree/master/stable/aws-load-balancer-controller) Helm chart.

### Summary

1. Add the EKS chart repo to helm
1. Add the EKS chart repo to Helm
```
helm repo add eks https://aws.github.io/eks-charts
```
1. Install the TargetGroupBinding CRDs if upgrading the chart via `helm upgrade`.
2. If upgrading the chart via `helm upgrade`, install the `TargetGroupBinding` CRDs.
```
kubectl apply -k "github.com/aws/eks-charts/stable/aws-load-balancer-controller//crds?ref=master"
```
Expand All @@ -180,19 +187,20 @@ We recommend using the Helm chart. This supports Fargate and facilitates updatin



=== "Via YAML manifests"
### Install cert-manager
=== "YAML manifests"<p>

### Install `cert-manager`

```
kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v1.5.4/cert-manager.yaml
```

### Apply YAML
1. Download spec for load balancer controller.
1. Download the spec for the LBC.
```
wget https://github.com/kubernetes-sigs/aws-load-balancer-controller/releases/download/v2.4.7/v2_4_7_full.yaml
```
1. Edit the saved yaml file, go to the Deployment spec, and set the controller --cluster-name arg value to your EKS cluster name
2. Edit the saved yaml file, go to the Deployment spec, and set the controller `--cluster-name` arg value to your EKS cluster name
```
apiVersion: apps/v1
kind: Deployment
Expand All @@ -207,20 +215,20 @@ We recommend using the Helm chart. This supports Fargate and facilitates updatin
- args:
- --cluster-name=<INSERT_CLUSTER_NAME>
```
1. If you use IAM roles for service accounts, we recommend that you delete the ServiceAccount from the yaml spec. This will preserve the eksctl created iamserviceaccount if you delete the installation section from the yaml spec.
3. If you use IAM roles for service accounts, we recommend that you delete the `ServiceAccount` from the yaml spec. If you delete the installation section from the yaml spec, deleting the `ServiceAccount` preserves the `eksctl` created `iamserviceaccount`.
```
apiVersion: v1
kind: ServiceAccount
```
1. Apply the yaml file
4. Apply the yaml file
```
kubectl apply -f v2_4_7_full.yaml
```
1. Optionally download the default ingressclass and ingressclass params
5. Optionally download the default ingressclass and ingressclass params
```
wget https://github.com/kubernetes-sigs/aws-load-balancer-controller/releases/download/v2.4.7/v2_4_7_ingclass.yaml
```
1. Apply the ingressclass and params
6. Apply the ingressclass and params
```
kubectl apply -f v2_4_7_ingclass.yaml
```
Expand All @@ -229,4 +237,4 @@ We recommend using the Helm chart. This supports Fargate and facilitates updatin

The controller doesn't receive security updates automatically. You need to manually upgrade to a newer version when it becomes available.

This can be done using [`helm upgrade`](https://helm.sh/docs/helm/helm_upgrade/) or another strategy to manage the controller deployment.
You can upgrade using [`helm upgrade`](https://helm.sh/docs/helm/helm_upgrade/) or another strategy to manage the controller deployment.