Merge pull request #197 from coreos/continued_stabilization

Stabilization and move toward 1.0

Author: joshrosso

Makefile

@@ -19,7 +19,7 @@
 
 all: container
 
-TAG?=0.8
+TAG?=1.0-alpha.3
 PREFIX?=quay.io/coreos/alb-ingress-controller
 ARCH?=amd64
 TEMP_DIR:=$(shell mktemp -d)

README.md

@@ -4,13 +4,19 @@
 
 # ALB Ingress Controller
 
-The ALB Ingress Controller satisfies Kubernetes [ingress resources](https://kubernetes.io/docs/user-guide/ingress) by provisioning [Application Load Balancers](https://aws.amazon.com/elasticloadbalancing/applicationloadbalancer) and [Route 53 Resource Record Sets](http://docs.aws.amazon.com/Route53/latest/DeveloperGuide/rrsets-working-with.html).
+**NOTE:** This controller is in alpha state as we attempt to move to our first 1.0 release. The current image version is `1.0-alpha.3`. Please file any issues you find and note the version used.
+
+The ALB Ingress Controller satisfies Kubernetes [ingress resources](https://kubernetes.io/docs/user-guide/ingress) by provisioning [Application Load Balancers](https://aws.amazon.com/elasticloadbalancing/applicationloadbalancer).
 
 This project was originated by [Ticketmaster](https://github.com/ticketmaster) and [CoreOS](https://github.com/coreos) as part of Ticketmaster's move to AWS and CoreOS Tectonic. Learn more about Ticketmaster's Kubernetes initiative from Justin Dean's video at [Tectonic Summit](https://www.youtube.com/watch?v=wqXVKneP0Hg).
 
+## Getting started
+
+To get started with the controller, see our [walkthrough](docs/walkthrough.md).
+
 ## Design
 
-The following diagram details the AWS components this controller creates. It also demonstrates the route ingress traffic takes from the DNS record to the Kubernetes cluster.
+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](docs/imgs/controller-design.png)
 
@@ -32,8 +38,6 @@ using annotations.
 
 **[5]**: [Rules](http://docs.aws.amazon.com/elasticloadbalancing/latest/application/listener-update-rules.html) are created for each path specified in your ingress resource. This ensures traffic to a specific path is routed to the correct Kubernetes Service.
 
-**[6]**: A [Route 53 Resource Record Set](http://docs.aws.amazon.com/Route53/latest/DeveloperGuide/rrsets-working-with.html) is created representing the domain of the ingress resource.
-
 Along with the above, the controller also...
 
 - deletes AWS components when ingress resources are removed from k8s.
@@ -45,35 +49,13 @@ Along with the above, the controller also...
 
 This section details how traffic reaches the cluster.
 
-As seen above, the ingress traffic for controller-managed resources starts at Route 53 DNS, moves
-through the ALB, and reaches the Kubernetes nodes through each service's NodePort. This means that
+As seen above, the ingress traffic for controller-managed resources starts at the ALB and reaches the Kubernetes nodes through each service's NodePort. This means that
 services referenced from ingress resource must be exposed on a node port in order to be to be
 reached by the ALB.
 
-## Installation
-
-The ALB Ingress Controller is installable via `kubectl` or `helm`. Follow one of the two options below to create a [Kubernetes deployment](https://kubernetes.io/docs/user-guide/deployments).
-
-In order to start the controller, it must have appropriate access to AWS APIs. See [AWS API
-Access](docs/configuration.md#aws-api-access) for more information.
-
-### kubectl Install
-
-Deploy a default backend service.
- 
-```
-$ kubectl create -f https://raw.githubusercontent.com/coreos/alb-ingress-controller/master/examples/default-backend.yaml
-```
-
-> Specifying a `--default-backend-service=` is required by Kubernetes ingress controllers. However, the ALB Ingress Controller does not make use of this service.
-
-Deploy the ALB Ingress Controller.
-
-```  
-kubectl create -f https://raw.githubusercontent.com/coreos/alb-ingress-controller/master/examples/alb-ingress-controller.yaml
-```
+## Setup
 
-> The `AWS_REGION` in the above example is set to `us-west-1`. Change this if your cluster is in a different region.
+For details on how to setup the controller and [external-dns](https://github.com/kubernetes-incubator/external-dnsexternal-dns) (for managing Route 53), see [setup](docs/setup.md).
 
 ### Helm App Reqistry Install
 

docs/imgs/controller-design.png

@@ -40,17 +40,11 @@ The ALB Ingress Controller is configured by Annotations on the `Ingress` resourc
 ### Required Annotations
 
 ```
-alb.ingress.kubernetes.io/security-groups
-alb.ingress.kubernetes.io/subnets
 alb.ingress.kubernetes.io/scheme
 ```
 
 Required annotations are:
 
-- **security-groups**: Required. [Security groups](http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/VPC_SecurityGroups.html) that should be applied to the ALB instance. These can be referenced by security group IDs or the name tag associated with each security group. Example ID values are `sg-723a380a,sg-a6181ede,sg-a5181edd`. Example tag values are `appSG, webSG`.
-
-- **subnets**: Required. The subnets where the ALB instance should be deployed. Must include 2 subnets, each in a different [availability zone](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html). These can be referenced by subnet IDs or the name tag associated with the subnet.  Example values for subnet IDs are `subnet-a4f0098e,subnet-457ed533,subnet-95c904cd`. Example values for name tags are: `webSubnet,appSubnet`.
-
 - **scheme**: Defines whether an ALB should be `internal` or `internet-facing`. See [Load balancer scheme](http://docs.aws.amazon.com/elasticloadbalancing/latest/userguide/how-elastic-load-balancing-works.html#load-balancer-scheme) in the AWS documentation for more details.
 
 ### Optional Annotations
@@ -66,6 +60,8 @@ alb.ingress.kubernetes.io/healthcheck-timeout-seconds
 alb.ingress.kubernetes.io/healthy-threshold-count
 alb.ingress.kubernetes.io/unhealthy-threshold-count
 alb.ingress.kubernetes.io/listen-ports
+alb.ingress.kubernetes.io/security-groups
+alb.ingress.kubernetes.io/subnets
 alb.ingress.kubernetes.io/successCodes
 alb.ingress.kubernetes.io/tags
 ```
@@ -92,6 +88,16 @@ Optional annotations are:
 
 - **listen-ports**: Defines the ports the ALB will expose. When omitted, `80` is used for HTTP and `443` is used for HTTPS. Uses a format as follows '[{"HTTP":8080,"HTTPS": 443}]'.
 
+- **security-groups**: [Security groups](http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/VPC_SecurityGroups.html) that should be applied to the ALB instance. These can be referenced by security group IDs or the name tag associated with each security group. Example ID values are `sg-723a380a,sg-a6181ede,sg-a5181edd`. Example tag values are `appSG, webSG`. When the annotation is not present, the controller will create a security group with appropriate ports allowing access to `0.0.0.0/0` and attached to the ALB. It will also create a security group for instances that allows all TCP traffic when the source is the security group created for the ALB.
+
+- **subnets**: The subnets where the ALB instance should be deployed. Must include 2 subnets, each in a different [availability zone](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html). These can be referenced by subnet IDs or the name tag associated with the subnet.  Example values for subnet IDs are `subnet-a4f0098e,subnet-457ed533,subnet-95c904cd`. Example values for name tags are: `webSubnet,appSubnet`. If subnets are not specified the ALB controller will attempt to detect qualified subnets. This qualification is done by locating subnets that match the following criteria.
+
+  - kubernetes.io/cluster/$CLUSTER_NAME where $CLUSTER_NAME is the same cluster name specified on the ingress controller. The value of this tag must be 'shared'.
+    
+  - kubernetes.io/role/alb-ingress the value of this tag should be empty.
+    
+  - After subnets matching the above 2 tags have been located, they are checked to ensure 2 or more are in unique AZs, otherwise the ALB will not be created. If 2 subnets share the same AZ, only 1 of the 2 is used.
+
 - **successCodes**: Defines the HTTP status code that should be expected when doing health checks against the defined `healthcheck-path`. When omitted, `200` is used.
 
 - **tags**: Defines [AWS Tags](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html) that should be applied to the ALB instance and Target groups.

docs/imgs/subnet-tags.png

@@ -0,0 +1,139 @@
+# Setup
+
+This document describes how to setup the alb-ingress-controller using kubectl or helm. Additionally, it details how to setup [external-dns](https://github.com/kubernetes-incubator/external-dns) to work with the controller.
+
+If you'd prefer an end-to-end walkthrough (example) of setup instead, see [the echoservice example](walkthrough.md).
+
+## Prerequisites
+
+This section details what must be setup in order for the controller to run.
+
+### Role Permissions
+
+Adequate roles and policies must be configured in AWS and available to the node(s) running the controller. How access is granted is up to you. Some will attach the needed rights to node's role in AWS. Others will use projects like [kube2iam](https://github.com/jtblin/kube2iam).
+
+An example policy with the minimum rights can be found at [examples/iam-policy.json](../examples/iam-policy.json).
+
+### Subnet Selection
+
+The controller determines subnets to deploy each ALB to based on an annotation or auto-detection.
+
+- annotation: `alb.ingress.kubernetes.io/subnets` may be specified in each ingress resource with the subnet IDs or `Name` tags. This allows for flexibility in where ALBs land. This list of subnets must include 2 or more that exist in unique availability zones. See the [annotations documentation](docs/ingress-resources.md#annotations) for more details.
+
+- auto-detection: When subnet annotations are not present, the controller will attempt to choose the best subnets for deploying the ALBs. It uses the following tag criteria to determine the subnets it should use.
+
+	- `kubernetes.io/cluster/$CLUSTER_NAME`=`shared` where `$CLUSTER_NAME` matches the `CLUSTER_NAME` environment variable from the `alb-ingress-controller.yaml` manifest.
+
+	- `kubernetes.io/role/alb-ingress`=` ` where the value is empty.
+
+### Security Group Selection
+
+The controller determines if it should create and manage security groups or use existing ones in AWS based on the presence of an annotation. When `alb.ingress.kubernetes.io/security-groups` is present, the list of security groups is assigned to the ALB instance. When the annotation is not present, the controller will create a security group with appropriate ports allowing access to `0.0.0.0/0` and attached to the ALB. It will also create a security group for instances that allows all TCP traffic when the source is the security group created for the ALB.
+
+## helm Deployments
+
+You must have the [Helm App Registry plugin](https://coreos.com/apps) installed for these instructions to work.
+
+```
+helm registry install quay.io/coreos/alb-ingress-controller-helm
+```
+
+## kubectl Deployments
+
+1. Setup default-backend-service
+
+	A default backend service is required for every ingress controller. The alb-ingress-controller does not make use of it, but will not be able to run the ingress libraries without it. To get around this, deploy a dummy default backend to the cluster. The following example will deploy one in `kube-system`; you may wish to adjust it.
+ 
+	```
+	$ kubectl create -f https://raw.githubusercontent.com/coreos/alb-ingress-controller/master/examples/default-backend.yaml
+	```
+
+1. Configure the alb-ingress-controller manifest.
+
+	A sample manifest can be found below.
+
+	```  
+	$ wget https://raw.githubusercontent.com/coreos/alb-ingress-controller/master/examples/alb-ingress-controller.yaml
+	```
+
+	At minimum, edit the following variables.
+
+    - `AWS_REGION`: region in AWS this cluster exists.
+
+		```yaml
+		- name: AWS_REGION
+		  value: us-west-1
+		```
+
+	- `CLUSTER_NAME`: name of the cluster. If doing auto-detection of subnets (described in prerequisites above) `CLUSTER_NAME` must match the AWS tags associated with the subnets you wish ALBs to be provisioned.
+
+		```yaml
+		- name: CLUSTER_NAME
+		  value: devCluster
+		```
+
+1. Deploy the alb-ingress-controller manifest.
+
+	```  
+	$ kubectl apply -f alb-ingress-controller.yaml	
+	```
+
+1. Verify the deployment was successful and the controller started.
+
+	```bash
+	$ kubectl logs -n kube-system \
+	    $(kubectl get po -n kube-system | \
+	    egrep -o alb-ingress[a-zA-Z0-9-]+) | \
+	    egrep -o '\[ALB-INGRESS.*$'
+	```
+
+	Should display output similar to the following.
+
+	```
+	[ALB-INGRESS] [controller] [INFO]: Log level read as "", defaulting to INFO. To change, set LOG_LEVEL environment variable to WARN, ERROR, or DEBUG.
+	[ALB-INGRESS] [controller] [INFO]: Ingress class set to alb
+	[ALB-INGRESS] [ingresses] [INFO]: Build up list of existing ingresses
+	[ALB-INGRESS] [ingresses] [INFO]: Assembled 0 ingresses from existing AWS resources
+	```
+
+## external-dns Deployment
+
+[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.
+
+
+1. Ensure your instance has the correct IAM permission required for external-dns. See https://github.com/kubernetes-incubator/external-dns/blob/master/docs/tutorials/aws.md#iam-permissions.
+
+
+1. Download external-dns to manage Route 53.
+
+	```bash
+	$ wget https://raw.githubusercontent.com/coreos/alb-ingress-controller/master/examples/external-dns.yaml
+	```
+
+1. Edit the `--domain-filter` flag to include your hosted zone(s)
+
+	The following example is for a hosted zone test-dns.com
+
+	```yaml
+	args:
+	- --source=service
+	- --source=ingress
+	- --domain-filter=test-dns.com # will make ExternalDNS see only the hosted zones matching provided domain, omit to process all available hosted zones
+	- --provider=aws
+	- --policy=upsert-only # would prevent ExternalDNS from deleting any records, omit to enable full synchronization
+	```
+
+1. Deploy external-dns
+
+	```  
+	$ kubectl apply -f external-dns.yaml	
+	```
+
+1. Verify it deployed successfully.
+
+	```
+	$ kubectl logs -f -n kube-system (kubectl get po -n kube-system | egrep -o 'external-dns[A-Za-z0-9-]+')
+
+	time="2017-09-19T02:51:54Z" level=info msg="config: &{Master: KubeConfig: Sources:[service ingress] Namespace: FQDNTemplate: Compatibility: Provider:aws GoogleProject: DomainFilter:[] AzureConfigFile:/etc/kuberne tes/azure.json AzureResourceGroup: Policy:upsert-only Registry:txt TXTOwnerID:my-identifier TXTPrefix: Interval:1m0s Once:false DryRun:false LogFormat:text MetricsAddress::7979 Debug:false}"
+	time="2017-09-19T02:51:54Z" level=info msg="Connected to cluster at https://10.3.0.1:443"
+	```