[WIP] First draft of Kube ingress topic (#476)

* First draft of Kube ingress topic * Update with procedure that works * Update to use web UI to create Kube objects * Add Beta2 workaround * Fix note syntax * Add ingress topic to TOC
2018-02-02 08:52:56 -08:00 · 2018-02-02 08:52:56 -08:00 · 2b89c15715
parent ed2099b79b
commit 2b89c15715
6 changed files with 339 additions and 1 deletions
--- a/_data/toc.yaml
+++ b/_data/toc.yaml
@ -1755,6 +1755,8 @@ manuals:
        path: /ee/ucp/kubernetes/
      - title: Deploy a Compose-based app
        path: /ee/ucp/kubernetes/deploy-with-compose/
+      - title: Deploy an ingress controller
+        path: /ee/ucp/kubernetes/deploy-ingress-controller/        
    - title: API reference
      path: /reference/ucp/3.0/api/
      nosync: true
--- a/ee/ucp/authorization/isolate-nodes.md
+++ b/ee/ucp/authorization/isolate-nodes.md
@ -101,7 +101,7 @@ You need two grants to control access to nodes and container resources:
 Create two grants for team access to the two collections:

 1.  Navigate to the **Grants** page and click **Create Grant**.
-2.  In the left pane, click **Collections**, and in the **Swarm** collection,
+2.  In the left pane, click **Resource Sets**, and in the **Swarm** collection,
    click **View Children**.
 3.  In the **Prod** collection, click **View Children**.
 4.  In the **Webserver** collection, click **Select Collection**.
--- a/ee/ucp/images/deploy-ingress-controller-1.png
+++ b/ee/ucp/images/deploy-ingress-controller-1.png
--- a/ee/ucp/images/deploy-ingress-controller-2.png
+++ b/ee/ucp/images/deploy-ingress-controller-2.png
--- a/ee/ucp/images/deploy-ingress-controller-3.png
+++ b/ee/ucp/images/deploy-ingress-controller-3.png
--- a/ee/ucp/kubernetes/deploy-ingress-controller.md
+++ b/ee/ucp/kubernetes/deploy-ingress-controller.md
@ -0,0 +1,336 @@
+---
+title: Deploy an ingress controller for a Kubernetes app
+description: Learn how to enable routing for a Kubernetes workload in Docker Enterprise Edition.
+keywords: UCP, Docker EE, Kubernetes, ingress, routing
+ui_tabs:
+- version: ucp-3.0
+  orlower: false
+---
+{% if include.version=="ucp-3.0" %}
+
+When you deploy your Kubernetes app on a Docker EE cluster, you may want to
+expose a service that enables external users to connect to it. Also, you may
+want network communication to reference named hosts, instead of IP addresses.
+Kubernetes provides *ingress controllers* to enable these functions. 
+
+Use an ingress controller when you want to: 
+
+- give your Kubernetes app an externally-reachable URL,
+- load-balance traffic to your app, or
+- offer name-based hosting.
+
+Kubernetes provides an NGINX ingress controller that you can use in a Docker EE
+cluster, without modifications. 
+Learn about [ingress in Kubernetes](https://v1-8.docs.kubernetes.io/docs/concepts/services-networking/ingress/).
+
+> Routing for Swarm apps
+>
+> To enable similar features for Swarm apps, see [Layer 7 routing](../interlock/index.md).
+{: .important}
+
+## Create the Kubernetes namespace for the ingress controller
+
+1.  Navigate to the **Namespaces** page and click **Create**.
+2.  In the **Object YAML** editor, append the following text.
+    ```yaml
+    metadata:
+      name: ingress-nginx
+    ```
+
+    The finished YAML should look like this. 
+
+    ```yaml
+    apiVersion: v1
+    kind: Namespace
+    metadata:
+      name: ingress-nginx
+    ```
+3.  Click **Create**.
+4.  In the **ingress-nginx** namespace, click the **More options** icon,
+    and in the context menu, select **Set Context**.
+
+    ![](../images/deploy-ingress-controller-1.png){: .with-border}
+
+## Create a grant
+
+> Docker EE 2.0 Beta2
+>
+> In Beta2, default service accounts have limited or no permissions, and all
+> other service accounts have full admin-scoped privileges. Instead of creating
+> a grant, create a service account named `nginx-service-account` in the
+> `ingress-nginx` namespace.
+> 
+> ```yaml
+> apiVersion: v1
+> kind: ServiceAccount
+> metadata:
+>   name: nginx-service-account
+>   namespace: ingress-nginx
+> ```
+> 
+> Skip to the [Install the NGINX ingress controller](#install-the-nginx-ingress-controller) procedure.
+
+The default service account that's associated with the `ingress-nginx`
+namespace needs access to Kubernetes resources, so create a grant with
+`Restricted Control` permissions.
+
+1.  Navigate to the **Grants** page and click **Create Grant**.
+2.  In the left pane, click **Resource Sets**, and in the **Type** section,
+    click **Namespaces**.
+3.  Enable the **Apply grant to all existing and new namespaces** option.
+4.  In the left pane, click **Roles**. In the **Role** dropdown, select
+    **Restricted Control**.
+5.  In the left pane, click **Subjects**, and select **Service Account**.
+6.  In the **Namespace** dropdown, select **ingress-nginx**, and in the
+    **Service Account** dropdown., select **default**.
+7.  Click **Create**.
+
+> Ingress and role-based access control
+>
+> Docker EE has an access control system that differs from Kubernetes RBAC.
+> If your ingress controller has access control requirements, you need to 
+> create corresponding UCP grants. Learn to
+> [migrate Kubernetes roles to Docker EE authorization](../authorization/migrate-kubernetes-roles.md).
+{: .important}
+
+## Install the NGINX ingress controller
+
+The cluster is ready for the ingress controller deployment, which has three
+main components:
+
+- a simple HTTP server, named `default-http-backend`,
+- an ingress controller, named `nginx-ingress-controller`, and
+- a service that exposes the app, named `ingress-nginx`.
+
+Navigate to the **Create Kubernetes Object** page, and in the **Object YAML** 
+editor, paste the following YAML.
+
+> Docker EE 2.0 Beta2
+> 
+> Uncomment `serviceAccountName: nginx-service-account` to use the
+> service account that you created previously.
+
+```yaml
+apiVersion: extensions/v1beta1
+kind: Deployment
+metadata:
+  name: default-http-backend
+  labels:
+    app: default-http-backend
+  namespace: ingress-nginx
+spec:
+  replicas: 1
+  template:
+    metadata:
+      labels:
+        app: default-http-backend
+    spec:
+      terminationGracePeriodSeconds: 60
+      containers:
+      - name: default-http-backend
+        # Any image is permissable as long as:
+        # 1. It serves a 404 page at /
+        # 2. It serves 200 on a /healthz endpoint
+        image: gcr.io/google_containers/defaultbackend:1.4
+        livenessProbe:
+          httpGet:
+            path: /healthz
+            port: 8080
+            scheme: HTTP
+          initialDelaySeconds: 30
+          timeoutSeconds: 5
+        ports:
+        - containerPort: 8080
+        resources:
+          limits:
+            cpu: 10m
+            memory: 20Mi
+          requests:
+            cpu: 10m
+            memory: 20Mi
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: default-http-backend
+  namespace: ingress-nginx
+  labels:
+    app: default-http-backend
+spec:
+  ports:
+  - port: 80
+    targetPort: 8080
+  selector:
+    app: default-http-backend
+---
+kind: ConfigMap
+apiVersion: v1
+metadata:
+  name: nginx-configuration
+  namespace: ingress-nginx
+  labels:
+    app: ingress-nginx
+---
+kind: ConfigMap
+apiVersion: v1
+metadata:
+  name: tcp-services
+  namespace: ingress-nginx
+---
+kind: ConfigMap
+apiVersion: v1
+metadata:
+  name: udp-services
+  namespace: ingress-nginx
+---
+apiVersion: extensions/v1beta1
+kind: Deployment
+metadata:
+  name: nginx-ingress-controller
+  namespace: ingress-nginx 
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: ingress-nginx
+  template:
+    metadata:
+      labels:
+        app: ingress-nginx
+      annotations:
+        prometheus.io/port: '10254'
+        prometheus.io/scrape: 'true' 
+    spec:
+      # Beta2 only: Uncomment the following line 
+      # serviceAccountName: nginx-service-account
+      initContainers:
+      - command:
+        - sh
+        - -c
+        - sysctl -w net.core.somaxconn=32768; sysctl -w net.ipv4.ip_local_port_range="1024 65535"
+        image: alpine:3.6
+        imagePullPolicy: IfNotPresent
+        name: sysctl
+        securityContext:
+          privileged: true
+      containers:
+        - name: nginx-ingress-controller
+          image: quay.io/kubernetes-ingress-controller/nginx-ingress-controller:0.10.2
+          args:
+            - /nginx-ingress-controller
+            - --default-backend-service=$(POD_NAMESPACE)/default-http-backend
+            - --configmap=$(POD_NAMESPACE)/nginx-configuration
+            - --tcp-services-configmap=$(POD_NAMESPACE)/tcp-services
+            - --udp-services-configmap=$(POD_NAMESPACE)/udp-services
+            - --annotations-prefix=nginx.ingress.kubernetes.io
+          env:
+            - name: POD_NAME
+              valueFrom:
+                fieldRef:
+                  fieldPath: metadata.name
+            - name: POD_NAMESPACE
+              valueFrom:
+                fieldRef:
+                  fieldPath: metadata.namespace
+          ports:
+          - name: http
+            containerPort: 80
+          - name: https
+            containerPort: 443
+          livenessProbe:
+            failureThreshold: 3
+            httpGet:
+              path: /healthz
+              port: 10254
+              scheme: HTTP
+            initialDelaySeconds: 10
+            periodSeconds: 10
+            successThreshold: 1
+            timeoutSeconds: 1
+          readinessProbe:
+            failureThreshold: 3
+            httpGet:
+              path: /healthz
+              port: 10254
+              scheme: HTTP
+            periodSeconds: 10
+            successThreshold: 1
+            timeoutSeconds: 1
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: ingress-nginx
+  namespace: ingress-nginx
+spec:
+  type: NodePort
+  ports:
+  - name: http
+    port: 80
+    targetPort: 80
+    protocol: TCP
+  - name: https
+    port: 443
+    targetPort: 443
+    protocol: TCP
+  selector:
+    app: ingress-nginx
+```
+
+## Inspect the installation
+
+The `default-http-backend` provides a simple service that serves a 404 page
+at `/` and serves 200 on the `/healthz` endpoint.
+
+1.  Navigate to the **Controllers** page and confirm that the
+    **default-http-backend** and **nginx-ingress-controller** objects are
+    scheduled. 
+
+    > Scheduling latency
+    >
+    > It may take several seconds for the HTTP backend and the ingress controller's
+    > `Deployment` and `ReplicaSet` objects to be scheduled.
+    { .important }
+
+    ![](../images/deploy-ingress-controller-2.png){: .with-border}
+
+2.  When the workload is running, navigate to the **Load Balancers** page
+    and click the **ingress-nginx** service.
+
+    ![](../images/deploy-ingress-controller-3.png){: .with-border}
+
+3.  In the details pane, click the first URL in the **Ports** section.
+
+    A new page opens, displaying `default backend - 404`.
+
+## Inspect the installation in the CLI
+
+From the command line, confirm that the deployment is running by using
+`curl` with the URL that's shown on the details pane of the **ingress-nginx**
+service.
+
+```bash
+curl -I http://<ucp-ip>:<ingress port>/
+```
+
+This command returns the following result.
+
+```
+HTTP/1.1 404 Not Found
+Server: nginx/1.13.8
+```
+
+Test the server's health ping service by appending `/healthz` to the URL.
+
+```bash
+curl -I http://<ucp-ip>:<ingress port>/healthz
+```
+
+This command returns the following result.
+
+```
+HTTP/1.1 200 OK
+Server: nginx/1.13.8
+```
+
+{% endif %}