Skip to content

Commit e185a57

Browse files
kishorjTimothy-Dougherty
kishorj
authored and
Timothy-Dougherty
committed
Installation guide (kubernetes-sigs#1509)
* installation guide * controller configuration options * subnet auto-discovery * update configuration guide * Add documentation from the v1 release * reformat installation guide * reword IAM permissions section
1 parent bb3eb83 commit e185a57

File tree

14 files changed

+663
-24
lines changed

14 files changed

+663
-24
lines changed

‎CONTRIBUTING.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ We also have more documentation on how to get started contributing here:
1111

1212
- [Contributor License Agreement](https://git.k8s.io/community/CLA.md) Kubernetes projects require that you sign a Contributor License Agreement (CLA) before we can accept your pull requests
1313
- [Kubernetes Contributor Guide](http://git.k8s.io/community/contributors/guide) - Main contributor documentation, or you can just jump directly to the [contributing section](http://git.k8s.io/community/contributors/guide#contributing)
14-
- [Contributor Cheat Sheet](https://github.com/kubernetes/community/blob/master/contributors/guide/contributor-cheatsheet/README.md) - Common resources for existing developers
14+
- [Contributor Cheat Sheet](https://git.k8s.io/community/contributors/guide/contributor-cheatsheet.md) - Common resources for existing developers
1515

1616
## Mentorship
1717

‎docs/assets/images/controller-design.png

74 KB
Loading

‎docs/assets/images/subnet-tags.png

38.1 KB
Loading

‎docs/examples/external-dns.yaml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,8 @@ rules:
1414
- apiGroups: [""]
1515
resources: ["pods"]
1616
verbs: ["get","watch","list"]
17-
- apiGroups: ["extensions"]
18-
resources: ["ingresses"]
17+
- apiGroups: ["extensions"]
18+
resources: ["ingresses"]
1919
verbs: ["get","watch","list"]
2020
- apiGroups: [""]
2121
resources: ["nodes"]

‎docs/guide/controller/configurations.md

Lines changed: 93 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,93 @@
1-
TODO: describes the controller configurations, i.e. the controller flags
1+
# AWS Load Balancer controller configuration options
2+
This document covers configuration of the AWS Load Balancer controller
3+
4+
## AWS API Access
5+
To perform operations, the controller must have required IAM role capabilities for accessing and
6+
provisioning ALB resources. There are many ways to achieve this, such as loading `AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY` as environment variables or using [kube2iam](https://github.com/jtblin/kube2iam).
7+
8+
Refer to the [installation guide](installation.md) for installing the controller in your kubernetes cluster and for the minimum required IAM permissions.
9+
10+
## Setting Ingress Resource Scope
11+
You can limit the ingresses ALB ingress controller controls by combining following two approaches:
12+
13+
### Limiting ingress class
14+
Setting the `--ingress-class` argument constrains the controller's scope to ingresses with matching `kubernetes.io/ingress.class` annotation.
15+
This is especially helpful when running multiple ingress controllers in the same cluster. See [Using Multiple Ingress Controllers](https://github.com/nginxinc/kubernetes-ingress/tree/master/examples/multiple-ingress-controllers#using-multiple-ingress-controllers) for more details.
16+
17+
An example of the container spec portion of the controller, only listening for resources with the class "alb", would be as follows.
18+
19+
```yaml
20+
spec:
21+
containers:
22+
- args:
23+
- --ingress-class=alb
24+
```
25+
26+
Now, only ingress resources with the appropriate annotation are picked up, as seen below.
27+
28+
```yaml
29+
apiVersion: extensions/v1beta1
30+
kind: Ingress
31+
metadata:
32+
name: echoserver
33+
namespace: echoserver
34+
annotations:
35+
kubernetes.io/ingress.class: "alb"
36+
spec:
37+
...
38+
```
39+
40+
If the ingress class is not specified, the controller will reconcile Ingress objects without the ingress class specified or ingress class `alb`.
41+
42+
### Limiting Namespaces
43+
Setting the `--watch-namespace` argument constrains the controller's scope to a single namespace. Ingress events outside of the namespace specified are not be seen by the controller.
44+
45+
An example of the container spec, for a controller watching only the `default` namespace, is as follows.
46+
47+
```yaml
48+
spec:
49+
containers:
50+
- args:
51+
- --watch-namespace=default
52+
```
53+
54+
> 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.
55+
56+
## Controller command line flags
57+
58+
!!!warning ""
59+
The --cluster-name flag is mandatory and the value must match the name of the kubernetes cluster. If you specify an incorrect name, the subnet auto-discovery will not work.
60+
61+
|Flag | Type | Default | Description |
62+
|---------------------------------------|---------------------------------|-----------------|-------------|
63+
|aws-api-throttle | AWS Throttle Config | [default value](#Default throttle config ) | throttle settings for AWS APIs, format: serviceID1:operationRegex1=rate:burst,serviceID2:operationRegex2=rate:burst |
64+
|aws-max-retries | int | 10 | Maximum retries for AWS APIs |
65+
|aws-region | string | [instance metadata](#Instance metadata) | AWS Region for the kubernetes cluster |
66+
|aws-vpc-id | string | [instance metadata](#Instance metadata) | AWS VPC ID for the Kubernetes cluster |
67+
|cluster-name | string | | Kubernetes cluster name|
68+
|enable-leader-election | boolean | true | Enable leader election for controller manager. Enabling this will ensure there is only one active controller manager. |
69+
|enable-pod-readiness-gate-inject | boolean | true | If enabled, targetHealth readiness gate will get injected to the pod spec for the matching endpoint pods. |
70+
|enable-shield | boolean | true | Enable Shield addon for ALB |
71+
|enable-waf | boolean | true | Enable WAF addon for ALB |
72+
|enable-wafv2 | boolean | true | Enable WAF V2 addon for ALB |
73+
|ingress-class | string | | Name of the ingress class this controller satisfies |
74+
|ingress-max-concurrent-reconciles | int | 3 | Maximum number of concurrently running reconcile loops for ingress |
75+
|kubeconfig | string | in-cluster config | Path to the kubeconfig file containing authorization and API server information |
76+
|leader-election-id | string | aws-load-balancer-controller-leader | Name of the leader election ID to use for this controller |
77+
|leader-election-namespace | string | | Name of the leader election ID to use for this controller |
78+
|log-level | string | info | Set the controller log level - info, debug |
79+
|metrics-bind-addr | string | :8080 | The address the metric endpoint binds to |
80+
|service-max-concurrent-reconciles | int | 3 | Maximum number of concurrently running reconcile loops for service |
81+
|sync-period | duration | 1h0m0s | Period at which the controller forces the repopulation of its local object stores|
82+
|targetgroupbinding-max-concurrent-reconciles | int | 3 | Maximum number of concurrently running reconcile loops for targetGroupBinding |
83+
|watch-namespace | string | | Namespace the controller watches for updates to Kubernetes objects, If empty, all namespaces are watched. |
84+
|webhook-bind-port | int | 9443 | The TCP port the Webhook server binds to |
85+
86+
87+
### Default throttle config
88+
```
89+
WAF Regional:^AssociateWebACL|DisassociateWebACL=0.5:1,WAF Regional:^GetWebACLForResource|ListResourcesForWebACL=1:1,WAFV2:^AssociateWebACL|DisassociateWebACL=0.5:1,WAFV2:^GetWebACLForResource|ListResourcesForWebACL=1:1
90+
```
91+
92+
### Instance metadata
93+
If running on EC2, the default values are obtained from the instance metadata service.

‎docs/guide/controller/how-it-works.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
# How ALB ingress controller works
1+
# How AWS Load Balancer controller works
22

33
## Design
44

55
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.
66

7-
![controller-design](../../imgs/controller-design.png)
7+
![controller-design](../../assets/images/controller-design.png)
88

99
### Ingress Creation
1010

@@ -32,7 +32,7 @@ Along with the above, the controller also...
3232
recover if the controller were to be restarted.
3333

3434
### Ingress Traffic
35-
ALB Ingress controller supports two traffic modes:
35+
AWS Load Balancer controller supports two traffic modes:
3636
* Instance mode
3737
* IP mode
3838

‎docs/guide/controller/installation.md

Lines changed: 69 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,69 @@
1-
TODO: describes how to install the controller.
1+
# AWS Load Balancer Controller Installation guide
2+
3+
## Via Helm
4+
Follow the instructions in [aws-load-balancer-controller](https://github.com/aws/eks-charts/tree/master/stable/aws-load-balancer-controller) helm chart.
5+
6+
## Via Yaml manifests
7+
8+
### Migrating from AWS ALB Ingress controller
9+
If AWS ALB Ingress controller is installed, refer to [migrating from v1 to v2](../upgrade/migrate_v1_v2.md)
10+
11+
!!!warning ""
12+
AWS ALB Ingress controller must be uninstalled before installing AWS Load Balancer controller.
13+
14+
!!! Note
15+
Existing Ingress resources do not need to be deleted for migration.
16+
17+
### IAM permissions
18+
The controller runs on the worker nodes, so it needs access to the AWS ALB/NLB resources via IAM permissions. The
19+
IAM permissions can either be setup via IAM roles for ServiceAccount or can be attached directly to the worker node IAM roles.
20+
21+
#### Setup IAM for ServiceAccount
22+
1. Create IAM OIDC provider
23+
```
24+
eksctl utils associate-iam-oidc-provider \
25+
--region <region-code> \
26+
--cluster <your-cluster-name> \
27+
--approve
28+
```
29+
1. Download IAM policy for the AWS Load Balancer Controller
30+
```
31+
curl -o iam-policy.json https://raw.githubusercontent.com/kubernetes-sigs/aws-alb-ingress-controller/v2_ga/docs/install/iam_policy.json
32+
```
33+
1. Create an IAM policy called AWSLoadBalancerControllerIAMPolicy
34+
```
35+
aws iam create-policy \
36+
--policy-name AWSLoadBalancerControllerIAMPolicy \
37+
--policy-document file://iam-policy.json
38+
```
39+
Take note of the policy ARN that is returned
40+
41+
1. Create a IAM role and ServiceAccount for the Load Balancer controller, use the ARN from the step above
42+
```
43+
eksctl create iamserviceaccount \
44+
--cluster=<cluster-name> \
45+
--namespace=kube-system \
46+
--name=aws-load-balancer-controller \
47+
--attach-policy-arn=arn:aws:iam::<AWS_ACCOUNT_ID>:policy/AWSLoadBalancerControllerIAMPolicy \
48+
--approve
49+
```
50+
#### Setup IAM manually
51+
If not setting up IAM for ServiceAccount, apply the IAM policies from the following URL at minimum.
52+
```
53+
https://raw.githubusercontent.com/kubernetes-sigs/aws-alb-ingress-controller/v2_ga/docs/install/iam_policy.json
54+
```
55+
56+
#### Upgrading from ALB ingress controller
57+
If migrating from ALB ingress controller, grant [additional IAM permissions](../../install/iam_policy_v1_to_v2_additional.json).
58+
59+
### Install cert-manager
60+
- For Kubernetes 1.16+: `kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v1.0.2/cert-manager.yaml`
61+
- For Kubernetes <1.16: `kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v1.0.2/cert-manager-legacy.yaml`
62+
63+
### Download and apply the yaml spec
64+
- curl -o https://raw.githubusercontent.com/kubernetes-sigs/aws-alb-ingress-controller/v2_ga/config/samples/install_v2_0_0.yaml
65+
- Edit the saved yaml file, go to the Deployment spec, and set the controller --cluster-name arg value to your EKS cluster name
66+
- Apply the yaml file kubectl apply -f install_v2_0_0.yaml
67+
68+
!!!note ""
69+
If you use iamserviceaccount, it is recommended that you delete the ServiceAccount from the yaml spec. Doing so will preserve the eksctl created iamserviceaccount if you delete the installation.

‎docs/guide/controller/subnet_discovery.md

Lines changed: 30 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,30 @@
1-
TODO: describes how to do subnet auto discovery.
1+
# Subnet Auto Discovery
2+
AWS Load Balancer controller auto discovers network subnets for ALB or NLB by default. ALB requires at least two subnets across Availability Zones, NLB requires one subnet.
3+
The subnets must be tagged appropriately for the auto discovery to work. The controller chooses one subnet from each Availability Zone. In case of multiple tagged subnets in
4+
an Availability Zone, the controller will choose the first one in lexicographical order by the Subnet IDs. If you use `eksctl` or an Amazon EKS AWS CloudFormation template to
5+
create your VPC after March 26, 2020, then the subnets are tagged appropriately when they're created. For more information about the Amazon EKS AWS CloudFormation VPC templates,
6+
see [Creating a VPC for your Amazon EKS cluster](https://docs.aws.amazon.com/eks/latest/userguide/create-public-private-vpc.html).
7+
8+
## Public subnets
9+
Public subnets are used for internet-facing load balancers. These subnets must have the following tags:
10+
11+
| Key | Value |
12+
| --------------------------------------- | --------------------- |
13+
| `kubernetes.io/role/elb` | `1` or `` |
14+
15+
## Private subnets
16+
Private subnets are used for internal load balancers. These subnets must have the following tags:
17+
18+
| Key | Value |
19+
| --------------------------------------- | --------------------- |
20+
| `kubernetes.io/role/internal-elb` | `1` or `` |
21+
22+
23+
## Common tag
24+
Both the public and private subnets must be tagged with the cluster name as follows:
25+
26+
| Key | Value |
27+
| --------------------------------------- | --------------------- |
28+
| `kubernetes.io/cluster/${cluster-name}` | `owned` or `shared` |
29+
30+
`${cluster-name}` is the name of the kubernetes cluster

‎docs/guide/ingress/spec.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
# Ingress specification
2-
This document covers how ingress resources work in relation to The ALB Ingress Controller.
2+
This document covers how ingress resources work in relation to The AWS Load Balancer Controller.
33

44
An example ingress, from [example](../../examples/2048/2048-ingress.yaml) is as follows.
55

@@ -24,8 +24,8 @@ spec:
2424
servicePort: 80
2525
```
2626
27-
The host field specifies the eventual Route 53-managed domain that will route to this service.
27+
The host field specifies the eventual Route 53-managed domain that will route to this service.
2828
2929
The service, service-2048, must be of type NodePort in order for the provisioned ALB to route to it.(see [echoserver-service.yaml](../../examples/echoservice/echoserver-service.yaml))
3030
31-
For details on purpose of annotations seen above, see [Annotations](annotation.md).
31+
For details on purpose of annotations seen above, see [Annotations](annotations.md).

‎docs/guide/integrations/external_dns.md

Lines changed: 67 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,67 @@
1-
TODO:
1+
# Setup External DNS
2+
[external-dns](https://github.com/kubernetes-incubator/external-dns) provisions DNS records based on the host information. This project will setup and manage records in Route 53 that point to controller deployed ALBs.
3+
4+
## Prerequisites
5+
### Role Permissions
6+
Adequate roles and policies must be configured in AWS and available to the node(s) running the external-dns. See https://github.com/kubernetes-incubator/external-dns/blob/master/docs/tutorials/aws.md#iam-permissions.
7+
8+
## Installation
9+
1. Download sample `external-dns` manifest
10+
11+
```bash
12+
wget https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.0.0/docs/examples/external-dns.yaml
13+
```
14+
15+
2. Edit the `--domain-filter` flag to include your hosted zone(s)
16+
17+
The following example is for a hosted zone `test-dns.com`:
18+
19+
```yaml
20+
args:
21+
- --source=service
22+
- --source=ingress
23+
- --domain-filter=test-dns.com # will make ExternalDNS see only the hosted zones matching provided domain, omit to process all available hosted zones
24+
- --provider=aws
25+
- --policy=upsert-only # would prevent ExternalDNS from deleting any records, omit to enable full synchronization
26+
- --aws-zone-type=public # only look at public hosted zones (valid values are public, private or no value for both)
27+
- --registry=txt
28+
- --txt-owner-id=my-identifier
29+
```
30+
31+
3. Deploy external-dns
32+
33+
```bash
34+
kubectl apply -f external-dns.yaml
35+
```
36+
37+
4. Verify it deployed successfully.
38+
39+
```bash
40+
kubectl logs -f $(kubectl get po | egrep -o 'external-dns[A-Za-z0-9-]+')
41+
```
42+
43+
Should display output similar to the following:
44+
```
45+
time="2019-12-11T10:26:05Z" level=info msg="config: {Master: KubeConfig: RequestTimeout:30s IstioIngressGateway:istio-system/istio-ingressgateway Sources:[service ingress] Namespace: AnnotationFilter: FQDNTemplate: CombineFQDNAndAnnotation:false Compatibility: PublishInternal:false PublishHostIP:false ConnectorSourceServer:localhost:8080 Provider:aws GoogleProject: DomainFilter:[test-dns.com] ZoneIDFilter:[] AlibabaCloudConfigFile:/etc/kubernetes/alibaba-cloud.json AlibabaCloudZoneType: AWSZoneType:public AWSAssumeRole: AWSBatchChangeSize:4000 AWSBatchChangeInterval:1s AWSEvaluateTargetHealth:true AzureConfigFile:/etc/kubernetes/azure.json AzureResourceGroup: CloudflareProxied:false InfobloxGridHost: InfobloxWapiPort:443 InfobloxWapiUsername:admin InfobloxWapiPassword: InfobloxWapiVersion:2.3.1 InfobloxSSLVerify:true DynCustomerName: DynUsername: DynPassword: DynMinTTLSeconds:0 OCIConfigFile:/etc/kubernetes/oci.yaml InMemoryZones:[] PDNSServer:http://localhost:8081 PDNSAPIKey: PDNSTLSEnabled:false TLSCA: TLSClientCert: TLSClientCertKey: Policy:upsert-only Registry:txt TXTOwnerID:my-identifier TXTPrefix: Interval:1m0s Once:false DryRun:false LogFormat:text MetricsAddress::7979 LogLevel:info TXTCacheInterval:0s ExoscaleEndpoint:https://api.exoscale.ch/dns ExoscaleAPIKey: ExoscaleAPISecret: CRDSourceAPIVersion:externaldns.k8s.io/v1alpha CRDSourceKind:DNSEndpoint ServiceTypeFilter:[] RFC2136Host: RFC2136Port:0 RFC2136Zone: RFC2136Insecure:false RFC2136TSIGKeyName: RFC2136TSIGSecret: RFC2136TSIGSecretAlg: RFC2136TAXFR:false}"
46+
time="2019-12-11T10:26:05Z" level=info msg="Created Kubernetes client https://10.100.0.1:443"
47+
```
48+
49+
## Usage
50+
1. To create a record set in the subdomain, from your ingress which has been created by the ingress-controller, simply add the following annotation in the ingress object specification and apply the manifest:
51+
52+
```yaml
53+
annotations:
54+
kubernetes.io/ingress.class: alb
55+
alb.ingress.kubernetes.io/scheme: internet-facing
56+
57+
# for creating record-set
58+
external-dns.alpha.kubernetes.io/hostname: my-app.test-dns.com # give your domain name here
59+
```
60+
61+
2. Similar entries should appear in the ExternalDNS pod log:
62+
63+
```
64+
time="2019-12-11T10:26:08Z" level=info msg="Desired change: CREATE my-app.test-dns.com A"
65+
time="2019-12-11T10:26:08Z" level=info msg="Desired change: CREATE my-app.test-dns.com TXT"
66+
time="2019-12-11T10:26:08Z" level=info msg="2 record(s) in zone my-app.test-dns.com. were successfully updated"
67+
```

0 commit comments

Comments
 (0)