Merge branch 'docs-serverless-updates' into 'master'

Docs serverless updates

See merge request gitlab-org/gitlab-ce!25497

7 files changed, 114 insertions, 43 deletions

diff --git a/doc/install/kubernetes/preparation/tiller.md b/doc/install/kubernetes/preparation/tiller.md
index 107df074b3b..88e287bb44f 100644
--- a/doc/install/kubernetes/preparation/tiller.md
+++ b/doc/install/kubernetes/preparation/tiller.md
@@ -54,19 +54,25 @@ Some clusters require authentication to use `kubectl` to create the Tiller roles
 
 #### Upload the RBAC config as an admin user (GKE)
 
-For GKE, you need to grab the admin credentials:
+For GKE, you need to obtain the admin credentials. This command will output the admin password:
 
 ```
 gcloud container clusters describe <cluster-name> --zone <zone> --project <project-id> --format='value(masterAuth.password)'
 ```
 
-This command will output the admin password. We need the password to authenticate with `kubectl` and create the role.
+Use the admin password to set the admin credentials. Replace the password value below with the output value from the above step:
 
 ```
-kubectl --username=admin --password=xxxxxxxxxxxxxx create -f rbac-config.yaml
+kubectl config set-credentials admin --username=admin --password=xxxxxxxxxxxxxx
 ```
 
-#### Upload the RBAC config (Other clusters)
+Once credentials have been set, create the role:
+
+```
+kubectl --user=admin create -f rbac-config.yaml
+```
+
+#### Upload the RBAC config (Non-GKE clusters)
 
 For other clusters like Amazon EKS, you can directly upload the RBAC configuration.
 
diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md
index 42aa6840609..0797eb3b0de 100644
--- a/doc/user/project/clusters/index.md
+++ b/doc/user/project/clusters/index.md
@@ -86,15 +86,20 @@ To add an existing Kubernetes cluster to your project:
 1. Click **Add Kubernetes cluster**.
 1. Click **Add an existing Kubernetes cluster** and fill in the details:
     - **Kubernetes cluster name** (required) - The name you wish to give the cluster.
-    - **Environment scope** (required)- The
+    - **Environment scope** (required) - The
       [associated environment](#setting-the-environment-scope) to this cluster.
     - **API URL** (required) -
       It's the URL that GitLab uses to access the Kubernetes API. Kubernetes
       exposes several APIs, we want the "base" URL that is common to all of them,
       e.g., `https://kubernetes.example.com` rather than `https://kubernetes.example.com/api/v1`.
-    - **CA certificate** (optional) -
-      If the API is using a self-signed TLS certificate, you'll also need to include
-      the `ca.crt` contents here.
+    - **CA certificate** (requried) - A valid Kubernetes certificate is needed to authenticate to the EKS cluster. We will use the certificate created by default. 
+      -  List the secrets with `kubectl get secrets`, and one should named similar to
+       `default-token-xxxxx`. Copy that token name for use below.
+      -  Get the certificate by running this command:
+
+        ```sh
+        kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode
+        ```
     - **Token** -
       GitLab authenticates against Kubernetes using service tokens, which are
       scoped to a particular `namespace`.
@@ -102,36 +107,81 @@ To add an existing Kubernetes cluster to your project:
       [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles)
       privileges.** To create this service account:
 
-      1. Create a `gitlab` service account in the `default` namespace:
+      1. Create a file called `gitlab-admin-service-account.yaml` with contents:
 
-          ```bash
-          kubectl create -f - <<EOF
-            apiVersion: v1
-            kind: ServiceAccount
-            metadata:
-              name: gitlab
-              namespace: default
-          EOF
+          ```yaml
+          apiVersion: v1
+          kind: ServiceAccount
+          metadata:
+            name: gitlab-admin
+            namespace: kube-system
           ```
-      1. Create a cluster role binding to give the `gitlab` service account
-         `cluster-admin` privileges:
+
+      2. Apply the service account to your cluster:
 
           ```bash
-          kubectl create -f - <<EOF
+          kubectl apply -f gitlab-admin-service-account.yaml
+          ```
+
+          Output:
+
+            ```bash
+            serviceaccount "gitlab-admin" created
+            ```
+
+      3. Create a file called `gitlab-admin-cluster-role-binding.yaml` with contents:
+
+          ```yaml
+          apiVersion: rbac.authorization.k8s.io/v1beta1
           kind: ClusterRoleBinding
-          apiVersion: rbac.authorization.k8s.io/v1
           metadata:
-            name: gitlab-cluster-admin
-          subjects:
-          - kind: ServiceAccount
-            name: gitlab
-            namespace: default
+            name: gitlab-admin
           roleRef:
+            apiGroup: rbac.authorization.k8s.io
             kind: ClusterRole
             name: cluster-admin
-            apiGroup: rbac.authorization.k8s.io
-          EOF
+          subjects:
+          - kind: ServiceAccount
+            name: gitlab-admin
+            namespace: kube-system
+          ```
+
+      4. Apply the cluster role binding to your cluster:
+
+          ```bash
+          kubectl apply -f gitlab-admin-cluster-role-binding.yaml
+          ```
+
+          Output:
+
+          ```bash
+          clusterrolebinding "gitlab-admin" created
           ```
+
+      5. Retrieve the token for the `gitlab-admin` service account:
+
+          ```bash
+          kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep gitlab-admin | awk '{print $1}')
+          ```
+
+      Copy the `<authentication_token>` value from the output:
+
+      ```yaml
+      Name:         gitlab-admin-token-b5zv4
+      Namespace:    kube-system
+      Labels:       <none>
+      Annotations:  kubernetes.io/service-account.name=gitlab-admin
+                    kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8
+
+      Type:  kubernetes.io/service-account-token
+
+      Data
+      ====
+      ca.crt:     1025 bytes
+      namespace:  11 bytes
+      token:      <authentication_token>
+      ```
+      
       NOTE: **Note:**
       For GKE clusters, you will need the
       `container.clusterRoleBindings.create` permission to create a cluster
diff --git a/doc/user/project/clusters/serverless/img/app-domain.png b/doc/user/project/clusters/serverless/img/app-domain.png
deleted file mode 100644
index d113dfadd2e..00000000000
--- a/doc/user/project/clusters/serverless/img/app-domain.png
+++ /dev/null
diff --git a/doc/user/project/clusters/serverless/img/dns-entry.png b/doc/user/project/clusters/serverless/img/dns-entry.png
index 678743f256e..351e40b77d5 100644
--- a/doc/user/project/clusters/serverless/img/dns-entry.png
+++ b/doc/user/project/clusters/serverless/img/dns-entry.png
diff --git a/doc/user/project/clusters/serverless/img/install-knative.png b/doc/user/project/clusters/serverless/img/install-knative.png
index 93b1cbe602f..ecc2f8fb481 100644
--- a/doc/user/project/clusters/serverless/img/install-knative.png
+++ b/doc/user/project/clusters/serverless/img/install-knative.png
diff --git a/doc/user/project/clusters/serverless/img/serverless-page.png b/doc/user/project/clusters/serverless/img/serverless-page.png
index 814b8532205..a872fda7740 100644
--- a/doc/user/project/clusters/serverless/img/serverless-page.png
+++ b/doc/user/project/clusters/serverless/img/serverless-page.png
diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md
index fc3a4a757d0..139579a88ff 100644
--- a/doc/user/project/clusters/serverless/index.md
+++ b/doc/user/project/clusters/serverless/index.md
@@ -25,8 +25,12 @@ To run Knative on Gitlab, you will need:
 
 1. **Kubernetes Cluster:** An RBAC-enabled Kubernetes cluster is required to deploy Knative.
     The simplest way to get started is to add a cluster using [GitLab's GKE integration](../index.md#adding-and-creating-a-new-gke-cluster-via-gitlab).
+    The set of minimum recommended cluster specifications to run Knative is 3 nodes, 6 vCPUs, and 22.50 GB memory.
 1. **Helm Tiller:** Helm is a package manager for Kubernetes and is required to install
     Knative.
+1. **GitLab Runner:** A runner is required to run the CI jobs that will deploy serverless
+    applications or functions onto your cluster. You can install the GitLab Runner
+    onto the existing Kubernetes cluster. See [Installing Applications](../index.md#installing-applications) for more information.
 1. **Domain Name:** Knative will provide its own load balancer using Istio. It will provide an
     external IP address for all the applications served by Knative. You will be prompted to enter a
     wildcard domain where your applications will be served. Configure your DNS server to use the
@@ -45,9 +49,9 @@ To run Knative on Gitlab, you will need:
 NOTE: **Note:**
 The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22.50 GB memory. **RBAC must be enabled.**
 
-1. [Add a Kubernetes cluster](../index.md) and install Helm.
-1. Once Helm has been successfully installed, on the Knative app section, enter the domain to be used with
-    your application and click "Install".
+1. [Add a Kubernetes cluster](../index.md) and [install Helm](../index.md#installing-applications).
+1. Once Helm has been successfully installed, scroll down to the Knative app section. Enter the domain to be used with
+    your application/functions (e.g. `example.com`) and click **Install**.
 
     ![install-knative](img/install-knative.png)
 
@@ -66,12 +70,16 @@ The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22.
 
 1. The ingress is now available at this address and will route incoming requests to the proper service based on the DNS
    name in the request. To support this, a wildcard DNS A record should be created for the desired domain name. For example,
-   if your Knative base domain is `knative.info` then you need to create an A record with domain `*.knative.info`
+   if your Knative base domain is `example.com` then you need to create an A record with domain `*.example.com`
    pointing the ip address of the ingress.
 
     ![dns entry](img/dns-entry.png)
 
-## Deploying Functions
+NOTE: **Note:**
+You can deploy either [functions](#deploying-functions) or [serverless applications](#deploying-serverless-applications)
+on a given project but not both. The current implementation makes use of a `serverless.yml` file to signal a FaaS project.
+
+## Deploying functions
 
 > Introduced in GitLab 11.6.
 
@@ -84,7 +92,7 @@ Currently the following [runtimes](https://gitlab.com/triggermesh/runtimes) are
 - node.js
 - kaniko
 
-You can find all the files referenced in this doc in the [functions example project](https://gitlab.com/knative-examples/functions).
+You can find and import all the files referenced in this doc in the **[functions example project](https://gitlab.com/knative-examples/functions)**.
 
 Follow these steps to deploy a function using the Node.js runtime to your Knative instance:
 
@@ -188,16 +196,27 @@ The function details can be retrieved directly from Knative on the cluster:
 kubectl -n "$KUBE_NAMESPACE" get services.serving.knative.dev
 ```
 
-The sample function can now be triggered from any HTTP client using a simple `POST` call.
+The sample function can now be triggered from any HTTP client using a simple `POST` call:
+
+  1. Using curl
 
-![function exection](img/function-execution.png)
+      ```bash
+      curl \
+      --header "Content-Type: application/json" \
+      --request POST \
+      --data '{"GitLab":"FaaS"}' \
+      http://functions-echo.functions-1.functions.example.net/
+      ```
+  2. Using a web-based tool (ie. postman, restlet, etc)
+
+      ![function exection](img/function-execution.png)
 
 ## Deploying Serverless applications
 
 > Introduced in GitLab 11.5.
 
 NOTE: **Note:**
-You can reference the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) to get started.
+You can reference and import the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) to get started.
 
 Add the following `.gitlab-ci.yml` to the root of your repository
 (you may skip this step if using the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) mentioned above):
@@ -236,11 +255,7 @@ With all the pieces in place, the next time a CI pipeline runs, the Knative appl
 
 ### Obtain the URL for the Knative deployment
 
-Go to the **Operations > Serverless** page to find the URL for your deployment in the **Domain** column.
-
-![app domain](img/app-domain.png)
-
-Alternatively, use the CI/CD deployment job output to obtain the deployment URL. Once all the stages of the pipeline finish, click the **deploy** stage.
+Go to the **CI/CD > Pipelines** and click on the pipeline that deployed your app. Once all the stages of the pipeline finish, click the **deploy** stage.
 
 ![deploy stage](img/deploy-stage.png)
 
@@ -262,7 +277,7 @@ registry.staging.gitlab.com/danielgruesso/knative
 $ tm -n "$KUBE_NAMESPACE" --config "$KUBECONFIG" deploy service "$CI_PROJECT_NAME" --from-image "$CI_REGISTRY_IMAGE" --wait
 Deployment started. Run "tm -n knative-4342902 describe service knative" to see the details
 Waiting for ready state.......
-Service domain: knative.knative-4342902.knative.info
+Service domain: knative.knative-4342902.example.com
 Job succeeded
 ```