Skip to content

promote install instructions to top level menu item, enable mkdocs gh action #1681

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.

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

Merged
merged 4 commits into from
Dec 2, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# AWS Load Balancer controller configuration options
# Controller configuration options
This document covers configuration of the AWS Load Balancer controller

## AWS API Access
Expand Down Expand Up @@ -51,7 +51,8 @@ spec:
- --watch-namespace=default
```

> Currently, you can set only 1 namespace to watch in this flag. See [this Kubernetes issue](https://github.com/kubernetes/contrib/issues/847) for more details.
!!!note ""
Currently, you can set only 1 namespace to watch in this flag. See [this Kubernetes issue](https://github.com/kubernetes/contrib/issues/847) for more details.

## Controller command line flags

Expand Down Expand Up @@ -90,5 +91,7 @@ spec:
WAF Regional:^AssociateWebACL|DisassociateWebACL=0.5:1,WAF Regional:^GetWebACLForResource|ListResourcesForWebACL=1:1,WAFV2:^AssociateWebACL|DisassociateWebACL=0.5:1,WAFV2:^GetWebACLForResource|ListResourcesForWebACL=1:1
```

AWS Web Application Firewall (WAF)

### Instance metadata
If running on EC2, the default values are obtained from the instance metadata service.
115 changes: 115 additions & 0 deletions docs/deploy/installation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,115 @@
# Load Balancer Controller Installation

!!!warning "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.

!!!note "Security updates"
The controller doesn't receive security updates automatically. You need to manually updgrade to a newer version when it becomes available.

## IAM Permissions

#### Setup IAM role for service accounts
The controller runs on the worker nodes, so it needs access to the AWS ALB/NLB resources via IAM permissions.
The IAM permissions can either be setup via IAM roles for ServiceAccount or can be attached directly to the worker node IAM roles.

1. Create IAM OIDC provider
```
eksctl utils associate-iam-oidc-provider \
--region <region-code> \
--cluster <your-cluster-name> \
--approve
```

1. Download IAM policy for the AWS Load Balancer Controller
```
curl -o iam-policy.json https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.1.0/docs/install/iam_policy.json
```

1. Create an IAM policy called AWSLoadBalancerControllerIAMPolicy
```
aws iam create-policy \
--policy-name AWSLoadBalancerControllerIAMPolicy \
--policy-document file://iam-policy.json
```
Take note of the policy ARN that is returned

1. Create a IAM role and ServiceAccount for the AWS Load Balancer controller, use the ARN from the step above
```
eksctl create iamserviceaccount \
--cluster=<cluster-name> \
--namespace=kube-system \
--name=aws-load-balancer-controller \
--attach-policy-arn=arn:aws:iam::<AWS_ACCOUNT_ID>:policy/AWSLoadBalancerControllerIAMPolicy \
--approve
```
Setup IAM manually
If not setting up IAM for ServiceAccount, apply the IAM policies from the following URL at minimum.
```
curl -o iam-policy.json https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.1.0/docs/install/iam_policy.json
```
## Add Controller to Cluster

=== "Via Helm"
### 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.

### Summary

1. Add the EKS chart repo to helm
```
helm repo add eks https://aws.github.io/eks-charts
```
1. Install the TargetGroupBinding CRDs
```
kubectl apply -k "github.com/aws/eks-charts/stable/aws-load-balancer-controller//crds?ref=master"
```
1. Install the helm chart
```
helm install eks/aws-load-balancer-controller
```



=== "Via YAML manifests"
### Install cert-manager
- For Kubernetes 1.16+:
```
kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v1.0.2/cert-manager.yaml
```
- For Kubernetes <1.16:
```
kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v1.0.2/cert-manager-legacy.yaml
```

### Apply YAML
1. Download spec for load balancer controller.
```
wget https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.1.0/docs/install/v2_1_0_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
```
apiVersion: apps/v1
kind: Deployment
. . .
name: aws-load-balancer-controller
namespace: kube-system
spec:
. . .
template:
spec:
containers:
- 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.
```
apiVersion: v1
kind: ServiceAccount
```
1. Apply the yaml file
```
kubectl apply -f v2_1_0_full.yaml
```


Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ It supports existing AWS resources provisioned by AWSALBIngressController(>=v1.1
|--------|----------|----------|---------------------------|----------------------|
|All TCP |TCP |0 - 65535 |sg-008c920b1(managed LB SG)|elbv2.k8s.aws/targetGroupBinding=shared| |

3. If you have used podReadinessGate feature, please refer [PodReadinessGate](../controller/pod_readiness_gate.md) for the guide about new readinessGate configuration.
3. If you have used podReadinessGate feature, please refer [PodReadinessGate](../pod_readiness_gate.md) for the guide about new readinessGate configuration.

!!!tip "old pod readinessGate"
once configured properly, AWS Load Balancer Controller will automatically inject the new format of podReadinessGates into your pods, and remove old podReadinessGates if any.
Expand All @@ -61,7 +61,7 @@ foo@bar:~$ kubectl describe deployment -n kube-system alb-ingress-controller |
Existing Ingress resources do not need to be deleted.

3. Install new AWSLoadBalancerController
1. Install AWSLoadBalancerController(v2.0.1) by following the [installation instructions](../controller/installation.md)
1. Install AWSLoadBalancerController(v2.0.1) by following the [installation instructions](../installation.md)
2. Grant [additional IAM policy](../../install/iam_policy_v1_to_v2_additional.json) needed for migration to the controller.

4. Verify all Ingresses works as expected.
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ In this walkthrough, you'll
```

## Setup the AWS Load Balancer controller
1. Refer to the [installation instructions](../controller/installation.md) to setup the controller
1. Refer to the [installation instructions](../deploy/installation.md) to setup the controller

1. Verify the deployment was successful and the controller started.

Expand Down Expand Up @@ -158,7 +158,7 @@ In this walkthrough, you'll

An example of a subnet with the correct tags for the cluster `joshcalico` is as follows.

![subnet-tags](../../assets/images/subnet-tags.png)
![subnet-tags](../assets/images/subnet-tags.png)

1. Deploy the ingress resource for echoserver

Expand Down
65 changes: 0 additions & 65 deletions docs/guide/controller/installation.md

This file was deleted.

2 changes: 1 addition & 1 deletion docs/guide/ingress/annotations.md
Original file line number Diff line number Diff line change
Expand Up @@ -185,7 +185,7 @@ Traffic Routing can be controlled with following annotations:
You must specify at least two subnets in different AZ. both subnetID or subnetName(Name tag on subnets) can be used.

!!!tip
You can enable subnet auto discovery to avoid specify this annotation on every Ingress. See [Subnet Discovery](../controller/subnet_discovery.md) for instructions.
You can enable subnet auto discovery to avoid specify this annotation on every Ingress. See [Subnet Discovery](../../deploy/subnet_discovery.md) for instructions.

!!!example
```
Expand Down
2 changes: 1 addition & 1 deletion docs/guide/service/annotations.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ Traffic Routing can be controlled with following annotations:
the NLB will route traffic to. See [Network Load Balancers](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/network-load-balancers.html#availability-zones) for more details.

!!!tip
Subnets are auto-discovered if this annotation is not specified, see [Subnet Discovery](../controller/subnet_discovery.md) for further details.
Subnets are auto-discovered if this annotation is not specified, see [Subnet Discovery](../../deploy/subnet_discovery.md) for further details.

!!!note ""
You must specify at least one subnet in any of the AZs, both subnetID or subnetName(Name tag on subnets) can be used.
Expand Down
2 changes: 1 addition & 1 deletion docs/guide/tasks/cognito_authentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ Configure Cognito for use with AWS Load Balancer Controller using the following

## AWS Load Balancer Controller Setup

Install the AWS Load Balancer Controller using the [install instructions](../controller/installation.md) with the following caveats.
Install the AWS Load Balancer Controller using the [install instructions](../../deploy/installation.md) with the following caveats.

* When setting up IAM Role Permissions, add the `cognito-idp:DescribeUserPoolClient` permission to the example policy.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

The following diagram details the AWS components this controller creates. It also demonstrates the route ingress traffic takes from the ALB to the Kubernetes cluster.

![controller-design](../../assets/images/controller-design.png)
![controller-design](assets/images/controller-design.png)

### Ingress Creation

Expand Down
31 changes: 18 additions & 13 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,30 +4,35 @@ repo_url: https://github.com/kubernetes-sigs/aws-alb-ingress-controller
strict: true

nav:
- Home: index.md
- Home:
- Welcome: index.md
- How it works: how-it-works.md
- Deployment:
- Installation Guide: deploy/installation.md
- Configurations: deploy/configurations.md
- Subnet Discovery: deploy/subnet_discovery.md
- Pod Readiness Gate: deploy/pod_readiness_gate.md
- Upgrade:
- Migrate v1 to v2: deploy/upgrade/migrate_v1_v2.md
- Guide:
- Controller:
- Installation: guide/controller/installation.md
- Configurations: guide/controller/configurations.md
- Subnet Discovery: guide/controller/subnet_discovery.md
- Pod Readiness Gate: guide/controller/pod_readiness_gate.md
- Ingress:
- Annotations: guide/ingress/annotations.md
- Spec: guide/ingress/spec.md
- Specification: guide/ingress/spec.md
- Certificate Discovery: guide/ingress/cert_discovery.md
- Service:
- NLB-IP mode: guide/service/nlb_ip_mode.md
- Annotations: guide/service/annotations.md
- TargetGroupBinding:
- TargetGroupBinding: guide/targetgroupbinding/targetgroupbinding.md
- Spec: guide/targetgroupbinding/spec.md
- Specification: guide/targetgroupbinding/spec.md
- Tasks:
- Cognito Authentication: guide/tasks/cognito_authentication.md
- SSL Redirect: guide/tasks/ssl_redirect.md
- Walkthrough:
- EchoServer: guide/walkthrough/echo_server.md
- Upgrade:
- Migrate v1 to v2: guide/upgrade/migrate_v1_v2.md
- Examples:
- EchoServer: examples/echo_server.md



plugins:
- search
theme:
Expand All @@ -41,7 +46,7 @@ theme:
text: Roboto
code: Roboto Mono
features:
- tabs
- navigation.tabs
custom_dir: docs/theme_overrides
# Extensions
markdown_extensions:
Expand Down