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

Update Serverless docs with livestream feedback

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

3 files changed, 34 insertions, 13 deletions

diff --git a/doc/README.md b/doc/README.md
index 14e8d2edb90..633b4483a53 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -288,6 +288,7 @@ The following documentation relates to the DevOps **Configure** stage:
 | [Installing Applications](user/project/clusters/index.md#installing-applications)                                                  | Deploy Helm, Ingress, and Prometheus on Kubernetes.                       |
 | [Mattermost slash commands](user/project/integrations/mattermost_slash_commands.md)                                                | Enable and use slash commands from within Mattermost.                     |
 | [Protected variables](ci/variables/README.md#protected-variables)                                                                  | Restrict variables to protected branches and tags.                        |
+| [Serverless](user/project/clusters/serverless/index.md)                                                                            | Run serverless workloads on Kubernetes.                                   |
 | [Slack slash commands](user/project/integrations/slack_slash_commands.md)                                                          | Enable and use slash commands from within Slack.                          |
 
 <div align="right">
diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md
index e601d7b2ccc..0c514e005b2 100644
--- a/doc/user/project/clusters/index.md
+++ b/doc/user/project/clusters/index.md
@@ -41,7 +41,7 @@ integration, make sure the following requirements are met:
 
 - A [billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account)
   is set up and you have permissions to access it.
-- The Kubernetes Engine API is enabled. Follow the steps as outlined in the
+- The Kubernetes Engine API and related service are enabled. It should work immediately but may take up to 10 minutes after you create a project. For more information see the
   ["Before you begin" section of the Kubernetes Engine docs](https://cloud.google.com/kubernetes-engine/docs/quickstart#before-you-begin).
 
 ### Creating the cluster
@@ -69,6 +69,7 @@ new Kubernetes cluster to your project:
    - **Number of nodes** - Enter the number of nodes you wish the cluster to have.
    - **Machine type** - The [machine type](https://cloud.google.com/compute/docs/machine-types)
      of the Virtual Machine instance that the cluster will be based on.
+   - **RBAC-enabled cluster** - Leave this checked if using default GKE creation options, see the [RBAC section](#role-based-access-control-rbac-core-only) for more information.
 1. Finally, click the **Create Kubernetes cluster** button.
 
 After a couple of minutes, your cluster will be ready to go. You can now proceed
@@ -226,12 +227,19 @@ applications running on the cluster.
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/24580) in GitLab 11.8.
 
-Domains at the cluster level permit support for multiple domains
-per [multiple Kubernetes clusters](#multiple-kubernetes-clusters-premium). When specifying a domain,
-this will be automatically set as an environment variable (`KUBE_INGRESS_BASE_DOMAIN`) during
-the [Auto DevOps](../../../topics/autodevops/index.md) stages.
+NOTE: **Note:**
+You do not need to specify a base domain on cluster settings when using GitLab Serverless. The domain in that case
+will be specified as part of the Knative installation. See [Installing Applications](#installing-applications).
+
+Specifying a base domain will automatically set `KUBE_INGRESS_BASE_DOMAIN` as an environment variable.
+If you are using [Auto DevOps](../../../topics/autodevops/index.md), this domain will be used for the different
+stages. For example, Auto Review Apps and Auto Deploy.
+
+The domain should have a wildcard DNS configured to the Ingress IP address. After ingress has been installed (see [Installing Applications](#installing-applications)),
+you can either:
 
-The domain should have a wildcard DNS configured to the Ingress IP address.
+- Create an `A` record that points to the Ingress IP address with your domain provider.
+- Enter a wildcard DNS address using a service such as nip.io or xip.io. For example, `192.168.1.1.xip.io`.
 
 ## Access controls
 
diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md
index f7e72efa2ba..2871510d5ed 100644
--- a/doc/user/project/clusters/serverless/index.md
+++ b/doc/user/project/clusters/serverless/index.md
@@ -19,10 +19,15 @@ For more information on Knative, visit the [Knative docs repo](https://github.co
 
 With GitLab serverless, you can deploy both functions-as-a-service (FaaS) and serverless applications.
 
-## Requirements
+## Prerequisites
 
 To run Knative on Gitlab, you will need:
 
+1. **Existing GitLab project:** You will need a GitLab project to associate all resources. The simplest way to get started:
+
+    - If you are planning on deploying functions, clone the [functions example project](https://gitlab.com/knative-examples/functions) to get started.
+    - If you are planning on deploying a serverless application, clone the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) to get started.
+
 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.
@@ -43,6 +48,8 @@ To run Knative on Gitlab, you will need:
     runtime being used.
 1. **`Dockerfile`** (for [applications only](#deploying-serverless-applications): Knative requires a `Dockerfile` in order to build your application. It should be included
     at the root of your project's repo and expose port `8080`.
+1. **Prometheus** (optional): Installing Prometheus allows you to monitor the scale and traffic of your serverless function/application.
+    See [Installing Applications](../index.md#installing-applications) for more information.
 
 ## Installing Knative via GitLab's Kubernetes integration
 
@@ -56,7 +63,7 @@ The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22.
     ![install-knative](img/install-knative.png)
 
 1. After the Knative installation has finished, you can wait for the IP address to be displayed in the
-   **Knative IP Address** field or retrieve the Istio Ingress IP address by running the following command:
+   **Knative IP Address** field (takes up to 5 minutes) or retrieve the Istio Ingress IP address by running the following command:
 
    ```bash
    kubectl get svc --namespace=istio-system knative-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip} '
@@ -68,6 +75,11 @@ The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22.
    35.161.143.124 my-machine-name:~ my-user$
    ```
 
+   NOTE: **Note:**
+   Running `kubectl` commands on your cluster requires setting up access to the cluster first.
+   For clusters created on GKE, see [GKE Cluster Access](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl),
+   for other platforms [Install kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/).
+
 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 `example.com` then you need to create an A record with domain `*.example.com`
@@ -94,7 +106,7 @@ Currently the following [runtimes](https://gitlab.com/triggermesh/runtimes) are
 
 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:
+Follow these steps to deploy a function using the Node.js runtime to your Knative instance (you can skip these steps if you've cloned the example project):
 
 1. Create a directory that will house the function. In this example we will create a directory called `echo` at the root of the project.
 
@@ -188,7 +200,7 @@ appear under **Operations > Serverless**.
 This page contains all functions available for the project, the description for
 accessing the function, and, if available, the function's runtime information.
 The details are derived from the Knative installation inside each of the project's
-Kubernetes cluster.
+Kubernetes cluster. Click on each function to obtain detailed scale and invocation data.
 
 The function details can be retrieved directly from Knative on the cluster:
 
@@ -198,14 +210,14 @@ 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:
 
-  1. Using curl
+  1. Using curl (replace the URL on the last line with the URL of your application):
 
       ```bash
       curl \
       --header "Content-Type: application/json" \
       --request POST \
       --data '{"GitLab":"FaaS"}' \
-      http://functions-echo.functions-1.functions.example.net/
+      <http://functions-echo.functions-1.functions.example.com/>
       ```
   2. Using a web-based tool (ie. postman, restlet, etc)
 
@@ -219,7 +231,7 @@ NOTE: **Note:**
 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):
+(you may skip this step if you've previously cloned the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) mentioned above):
 
 ```yaml
 stages: