Split documentation

CONTRIBUTING.md

@@ -36,7 +36,7 @@ Ingress collaborators may add "LGTM" (Looks Good To Me) or an equivalent comment
 
 Whether you are a user or contributor, official support channels include:
 
-- GitHub issues: https://github.com/kubernetes/ingress/issues/new
+- GitHub issues: https://github.com/kubernetes/ingress-nginx/issues/new
 - Slack: kubernetes-users room in the [Kubernetes Slack](http://slack.kubernetes.io/)
 - Email: [kubernetes-users](https://groups.google.com/forum/#!forum/kubernetes-users) mailing list
 

deploy/README.md

@@ -0,0 +1,187 @@
+# Installation Guide
+
+## Contents
+
+- [Mandatory commands](#mandatory-commands)
+- [Install without RBAC roles](#install-without-rbac-roles)
+- [Install with RBAC roles](#install-with-rbac-roles)
+- [Custom Provider](#custom-provider)
+  - [minikube](#minikube)
+  - [AWS](#aws)
+  - [GCE - GKE](#gce-gke)
+  - [Azure](#azure)
+  - [Baremetal](#baremetal)
+- [Using Helm](#using-helm)
+- [Verify installation](#verify-installation)
+- [Detect installed version](#detect-installed-version)
+
+## Mandatory commands
+
+```console
+curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/namespace.yaml \
+    | kubectl apply -f -
+
+curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/default-backend.yaml \
+    | kubectl apply -f -
+
+curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/configmap.yaml \
+    | kubectl apply -f -
+
+curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/tcp-services-configmap.yaml \
+    | kubectl apply -f -
+
+curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/udp-services-configmap.yaml \
+    | kubectl apply -f -
+```
+
+## Install without RBAC roles
+
+```console
+curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/without-rbac.yaml \
+    | kubectl apply -f -
+```
+
+## Install with RBAC roles
+
+Please check the [RBAC](rbac.md) document.
+
+```console
+curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/rbac.yaml \
+    | kubectl apply -f -
+
+curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/with-rbac.yaml \
+    | kubectl apply -f -
+```
+
+## Custom Service provider
+
+There are cloud provider specific yaml files
+
+### minikube
+
+```console
+minikube addons enable ingress
+```
+
+### AWS
+
+In AWS we use an Elastic Load Balancer (ELB) to expose the NGINX Ingress controller behind a Service of `Type=LoadBalancer`.
+This setup requires to choose in wich layer (L4 or L7) we want to configure the ELB:
+
+- [Layer 4](https://en.wikipedia.org/wiki/OSI_model#Layer_4:_Transport_Layer): use TCP as the listener protocol for ports 80 and 443.
+- [Layer 7](https://en.wikipedia.org/wiki/OSI_model#Layer_7:_Application_Layer): use HTTP as the listener protocol for port 80 and terminate TLS in the ELB
+
+For L4:
+
+```console
+kubectl apply -f provider/aws/service-l4.yaml
+kubectl apply -f provider/aws/patch-configmap-l4.yaml
+```
+
+For L7:
+
+Change line of the file `provider/aws/service-l7.yaml` replacing the dummy id with a valid one `"arn:aws:acm:us-west-2:XXXXXXXX:certificate/XXXXXX-XXXXXXX-XXXXXXX-XXXXXXXX"`
+Then execute:
+
+```console
+kubectl apply -f provider/aws/service-l7.yaml
+kubectl apply -f provider/aws/patch-configmap-l7.yaml
+```
+
+This example creates an ELB with just two listeners, one in port 80 and another in port 443
+
+![Listeners](../docs/images/listener.png)
+
+If the ingress controller uses RBAC run:
+
+```console
+kubectl apply -f provider/patch-service-with-rbac.yaml
+```
+
+If not run:
+
+```console
+kubectl apply -f provider/patch-service-without-rbac.yaml
+```
+
+### GCE - GKE
+
+```console
+curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/gce-gke/service.yaml \
+    | kubectl apply -f -
+```
+
+If the ingress controller uses RBAC run:
+
+```console
+kubectl apply -f provider/patch-service-with-rbac.yaml
+```
+
+If not run:
+
+```console
+kubectl apply -f provider/patch-service-without-rbac.yaml
+```
+
+**Important Note:** proxy protocol is not supported in GCE/GKE
+
+### Azure
+
+```console
+curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/azure/service.yaml \
+    | kubectl apply -f -
+```
+
+If the ingress controller uses RBAC run:
+
+```console
+kubectl apply -f provider/patch-service-with-rbac.yaml
+```
+
+If not run:
+
+```console
+kubectl apply -f provider/patch-service-without-rbac.yaml
+```
+
+**Important Note:** proxy protocol is not supported in GCE/GKE
+
+### Baremetal
+
+Using [NodePort](https://kubernetes.io/docs/concepts/services-networking/service/#type-nodeport):
+
+```console
+curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/baremetal/service-nodeport.yaml \
+    | kubectl apply -f -
+```
+
+## Using Helm
+
+NGINX Ingress controller can be installed via [Helm](https://helm.sh/) using the chart [stable/nginx](https://github.com/kubernetes/charts/tree/master/stable/nginx-ingress) from the official charts repository. 
+To install the chart with the release name `my-nginx`:
+
+```console
+helm install stable/nginx-ingress --name my-nginx
+```
+
+## Verify installation
+
+To check if the ingress controller pods have started, run the following command:
+
+```console
+kubectl get pods --all-namespaces -l app=ingress-nginx --watch
+```
+
+Once the operator pods are running, you can cancel the above command by typing `Ctrl+C`.
+
+Now, you are ready to create your first ingress.
+
+## Detect installed version
+
+To detect which version of the ingress controller is running, exec into the pod and run `nginx-ingress-controller version` command.
+
+```console
+POD_NAMESPACE=ingress-nginx
+POD_NAME=$(kubectl get pods -n $POD_NAMESPACE -l app=ingress-nginx -o jsonpath={.items[0].metadata.name})
+kubectl exec -it $POD_NAME -n $POD_NAMESPACE /nginx-ingress-controller version
+```

deploy/configmap.yaml

@@ -0,0 +1,7 @@
+kind: ConfigMap
+apiVersion: v1
+metadata:
+  name: nginx-configuration
+  namespace: ingress-nginx
+  labels:
+    app: ingress-nginx

examples/rbac/default-backend.yml → deploy/default-backend.yaml

@@ -3,14 +3,14 @@ kind: Deployment
 metadata:
   name: default-http-backend
   labels:
-    k8s-app: default-http-backend
-  namespace: default
+    app: default-http-backend
+  namespace: ingress-nginx
 spec:
   replicas: 1
   template:
     metadata:
       labels:
-        k8s-app: default-http-backend
+        app: default-http-backend
     spec:
       terminationGracePeriodSeconds: 60
       containers:
@@ -36,16 +36,17 @@ spec:
             cpu: 10m
             memory: 20Mi
 ---
+
 apiVersion: v1
 kind: Service
 metadata:
   name: default-http-backend
-  namespace: default
+  namespace: ingress-nginx
   labels:
-    k8s-app: default-http-backend
+    app: default-http-backend
 spec:
   ports:
   - port: 80
     targetPort: 8080
   selector:
-    k8s-app: default-http-backend
+    app: default-http-backend

deploy/namespace.yaml

@@ -0,0 +1,4 @@
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: ingress-nginx

deploy/provider/aws/patch-configmap-l4.yaml

@@ -0,0 +1,9 @@
+kind: ConfigMap
+apiVersion: v1
+metadata:
+  name: nginx-configuration
+  namespace: ingress-nginx
+  labels:
+    app: ingress-nginx
+data:
+  use-proxy-protocol: "true"

deploy/provider/aws/patch-configmap-l7.yaml

@@ -0,0 +1,9 @@
+kind: ConfigMap
+apiVersion: v1
+metadata:
+  name: nginx-configuration
+  namespace: ingress-nginx
+  labels:
+    app: ingress-nginx
+data:
+  use-proxy-protocol: "false"

deploy/provider/aws/service-l4.yaml

@@ -0,0 +1,20 @@
+kind: Service
+apiVersion: v1
+metadata:
+  name: ingress-nginx
+  namespace: ingress-nginx
+  labels:
+    app: ingress-nginx
+  annotations:
+    service.beta.kubernetes.io/aws-load-balancer-proxy-protocol: '*'
+spec:
+  type: LoadBalancer
+  selector:
+    app: ingress-nginx
+  ports:
+  - name: http
+    port: 80
+    targetPort: http
+  - name: https
+    port: 443
+    targetPort: https

deploy/provider/aws/service-l7.yaml

@@ -0,0 +1,25 @@
+kind: Service
+apiVersion: v1
+metadata:
+  name: ingress-nginx
+  namespace: ingress-nginx
+  labels:
+    app: ingress-nginx
+  annotations:
+    # replace with the correct value of the generated certifcate in the AWS console
+    service.beta.kubernetes.io/aws-load-balancer-ssl-cert: "arn:aws:acm:us-west-2:XXXXXXXX:certificate/XXXXXX-XXXXXXX-XXXXXXX-XXXXXXXX" 
+    # the backend instances are HTTP
+    service.beta.kubernetes.io/aws-load-balancer-backend-protocol: "http"
+    # Map port 443
+    service.beta.kubernetes.io/aws-load-balancer-ssl-ports: "https"
+spec:
+  type: LoadBalancer
+  selector:
+    app: ingress-nginx
+  ports:
+  - name: http
+    port: 80
+    targetPort: http
+  - name: https
+    port: 443
+    targetPort: http

deploy/provider/azure/service.yaml

@@ -0,0 +1,19 @@
+kind: Service
+apiVersion: v1
+metadata:
+  name: ingress-nginx
+  namespace: ingress-nginx
+  labels:
+    app: ingress-nginx
+spec:
+  externalTrafficPolicy: Local
+  type: LoadBalancer
+  selector:
+    app: ingress-nginx
+  ports:
+  - name: http
+    port: 80
+    targetPort: http
+  - name: https
+    port: 443
+    targetPort: http

examples/rbac/nginx-ingress-controller-service.yml → deploy/provider/baremetal/service-nodeport.yml

@@ -1,21 +1,18 @@
 apiVersion: v1
 kind: Service
 metadata:
-  name: nginx-ingress
-  namespace: nginx-ingress
+  name: ingress-nginx
+  namespace: ingress-nginx
 spec:
-# Can also use LoadBalancer type
   type: NodePort
   ports:
   - name: http
-    port: 8080
-    nodePort: 30080
+    port: 80
     targetPort: 80
     protocol: TCP
   - name: https
     port: 443
-    nodePort: 30443
     targetPort: 443
     protocol: TCP
   selector:
-    k8s-app: nginx-ingress-lb
+    app: ingress-nginx

deploy/provider/gce-gke/service.yaml

@@ -0,0 +1,19 @@
+kind: Service
+apiVersion: v1
+metadata:
+  name: ingress-nginx
+  namespace: ingress-nginx
+  labels:
+    app: ingress-nginx
+spec:
+  externalTrafficPolicy: Local
+  type: LoadBalancer
+  selector:
+    app: ingress-nginx
+  ports:
+  - name: http
+    port: 80
+    targetPort: http
+  - name: https
+    port: 443
+    targetPort: http