Initial draft for serverless page

4 files changed, 106 insertions, 2 deletions

diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md
index 233ed205790..9b9864abe3a 100644
--- a/doc/user/project/clusters/index.md
+++ b/doc/user/project/clusters/index.md
@@ -271,7 +271,8 @@ kubectl get svc --namespace=gitlab-managed-apps ingress-nginx-ingress-controller
 ```
 
 NOTE: **Note:**
-For Istio/Knative, the command will be different:
+For Istio/Knative, use the following command:
+
 ```bash
 kubectl get svc --namespace=istio-system knative-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip} '
 ```
@@ -485,7 +486,13 @@ the deployment variables above, ensuring any pods you create are labelled with
 
 ## Read more
 
-- [Connecting and deploying to an Amazon EKS cluster](eks_and_gitlab/index.md)
+### Integrating Amazon EKS cluster with GitLab
+
+- Learn how to [connect and deploy to an Amazon EKS cluster.](eks_and_gitlab/index.md)
+
+### Serverless
+
+- [Run serverless workloads on Kubernetes with Knative.](serverless/index.md)
 
 [permissions]: ../../permissions.md
 [ee]: https://about.gitlab.com/pricing/
diff --git a/doc/user/project/clusters/serverless/img/install-knative.png b/doc/user/project/clusters/serverless/img/install-knative.png
new file mode 100644
index 00000000000..dd576a9df35
--- /dev/null
+++ b/doc/user/project/clusters/serverless/img/install-knative.png
diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md
new file mode 100644
index 00000000000..b1730868c39
--- /dev/null
+++ b/doc/user/project/clusters/serverless/index.md
@@ -0,0 +1,72 @@
+# Serverless
+
+> Introduced in GitLab 11.5.
+
+Run serverless workloads on Kubernetes using [Knative](https://cloud.google.com/knative/).
+
+## Overview
+
+Knative extends Kubernetes to provide a set of middleware components that are useful to build modern, source-centric, and container-based applications. Knative brings some significant benefits out of the box through its main components:
+
+- [Build:](https://github.com/knative/build) Source-to-container build orchestration
+- [Eventing:](https://github.com/knative/eventing) Management and delivery of events
+- [Serving:](https://github.com/knative/serving) Request-driven compute that can scale to zero
+
+For more information on Knative, visit the [Knative docs repo](https://github.com/knative/docs).
+
+## Requirements
+
+To run Knative on Gitlab, you will need:
+
+1. **Kubernetes:** 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](https://docs.gitlab.com/ee/user/project/clusters/#adding-and-creating-a-new-gke-cluster-via-gitlab). 
+    GitLab recommends 
+1. **Helm Tiller:** Helm is a package manager for Kubernetes and is required to install 
+    all the other applications. It is installed in its own pod inside the cluster which 
+    can run the helm CLI in a safe environment.
+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 
+    external IP address for that domain.
+1. **Serverless `gitlab-ci.yml` Template:** GitLab uses the [TriggerMesh CLI](https://github.com/triggermesh/tm), 
+    a serverless resource management utilty to work with knative objects. The `gitlab-ci.yml` template uses it 
+    to build and deploy knative services and functions. [Access the template here](serverless_ci_yml_template.yml).
+1. **Docker File:** Knative requires a docker file in order to build your application. It should be included 
+    at the root of your project's repo.
+
+## Installing Knative via GitLab's Kubernetes integration
+
+NOTE: **Note:**
+Minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22.50 GB memory. RBAC must be enabled.
+
+You may download the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) to get started.
+
+1. [Add a Kubernetes cluster](https://docs.gitlab.com/ce/user/project/clusters/) 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".
+
+    ![install-knative](img/install-knative.png)
+
+1. After the Knative installation has finished, 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} '
+    ```
+
+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.
+
+    ![dns entry](img/dns-entry)
+
+## Deploying the GitLab Runner (optional)
+
+If the project is on GitLab.com, free shared runners are available and you do not have to deploy one. If a project specific runner is desired, or there are no shared runners, it is easy to deploy one.
+
+Simply click on the "**Install**" button for the GitLab Runner. It is important to note that the runner deployed is set as privileged, which means it essentially has root access to the underlying machine. This is required to build docker images, and so is on by default.
+
+## Deploy the application with Knative
+
+With all the pieces in place, you can simply create a new CI pipeline to deploy the Knative application. Navigate to 
+**CI/CD >> Pipelines** and click on the "**Run Pipeline"** button on the upper right hand side of the screen. On the 
+Pipelines page now click "**Create pipeline**".
\ No newline at end of file
diff --git a/doc/user/project/clusters/serverless/serverless_ci_yml_template.yml b/doc/user/project/clusters/serverless/serverless_ci_yml_template.yml
new file mode 100644
index 00000000000..31f68f223ca
--- /dev/null
+++ b/doc/user/project/clusters/serverless/serverless_ci_yml_template.yml
@@ -0,0 +1,25 @@
+stages:
+  - build
+  - deploy
+  
+variables:
+  DOCKER_DRIVER: overlay2
+
+build:
+  stage: build
+  image: docker:stable-git
+  services:
+  - docker:stable-dind
+  before_script:
+  - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" "$CI_REGISTRY"
+  script:
+    - docker build --pull -t "$CI_REGISTRY_IMAGE" .
+    - docker push "$CI_REGISTRY_IMAGE"
+
+deploy:
+  stage: deploy
+  image: gcr.io/triggermesh/tm@sha256:e3ee74db94d215bd297738d93577481f3e4db38013326c90d57f873df7ab41d5
+  environment: production
+  script:
+    - echo "$CI_REGISTRY_IMAGE"
+    - tm -n "$KUBE_NAMESPACE" --config "$KUBECONFIG" deploy service "$CI_PROJECT_NAME" --from-image "$CI_REGISTRY_IMAGE" --wait