From 0cae4c5c72f8737004021075659281e974f73570 Mon Sep 17 00:00:00 2001 From: danielgruesso Date: Fri, 9 Nov 2018 15:35:22 -0500 Subject: Initial draft for serverless page --- .../clusters/serverless/img/install-knative.png | Bin 0 -> 102861 bytes doc/user/project/clusters/serverless/index.md | 72 +++++++++++++++++++++ .../serverless/serverless_ci_yml_template.yml | 25 +++++++ 3 files changed, 97 insertions(+) create mode 100644 doc/user/project/clusters/serverless/img/install-knative.png create mode 100644 doc/user/project/clusters/serverless/index.md create mode 100644 doc/user/project/clusters/serverless/serverless_ci_yml_template.yml (limited to 'doc/user/project/clusters/serverless') 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 Binary files /dev/null and b/doc/user/project/clusters/serverless/img/install-knative.png differ 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 -- cgit v1.2.1 From 417bc01dd347e65c09af7f5fbb272389a67a122d Mon Sep 17 00:00:00 2001 From: danielgruesso Date: Fri, 9 Nov 2018 16:48:46 -0500 Subject: add images and url retrieval section --- .../clusters/serverless/img/deploy-stage.png | Bin 0 -> 34472 bytes .../project/clusters/serverless/img/dns-entry.png | Bin 0 -> 103867 bytes .../clusters/serverless/img/knative-app.png | Bin 0 -> 28998 bytes doc/user/project/clusters/serverless/index.md | 35 ++++++++++++++++++++- 4 files changed, 34 insertions(+), 1 deletion(-) create mode 100644 doc/user/project/clusters/serverless/img/deploy-stage.png create mode 100644 doc/user/project/clusters/serverless/img/dns-entry.png create mode 100644 doc/user/project/clusters/serverless/img/knative-app.png (limited to 'doc/user/project/clusters/serverless') diff --git a/doc/user/project/clusters/serverless/img/deploy-stage.png b/doc/user/project/clusters/serverless/img/deploy-stage.png new file mode 100644 index 00000000000..eed5f948ba0 Binary files /dev/null and b/doc/user/project/clusters/serverless/img/deploy-stage.png differ diff --git a/doc/user/project/clusters/serverless/img/dns-entry.png b/doc/user/project/clusters/serverless/img/dns-entry.png new file mode 100644 index 00000000000..f72ae57718d Binary files /dev/null and b/doc/user/project/clusters/serverless/img/dns-entry.png differ diff --git a/doc/user/project/clusters/serverless/img/knative-app.png b/doc/user/project/clusters/serverless/img/knative-app.png new file mode 100644 index 00000000000..54301e1786f Binary files /dev/null and b/doc/user/project/clusters/serverless/img/knative-app.png differ diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index b1730868c39..74c081531a3 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -69,4 +69,37 @@ Simply click on the "**Install**" button for the GitLab Runner. It is important 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 +Pipelines page now click "**Create pipeline**". + +## Obtain the URL for the Knative deployment + +Once all the stages of the pipeline finish, click on the "deploy" stage + +![deploy stage](img/deploy-stage.png) + +The output will look like this: + +```bash +Running with gitlab-runner 11.5.0~beta.844.g96d88322 (96d88322) + on docker-auto-scale 72989761 +Using Docker executor with image gcr.io/triggermesh/tm@sha256:e3ee74db94d215bd297738d93577481f3e4db38013326c90d57f873df7ab41d5 ... +Pulling docker image gcr.io/triggermesh/tm@sha256:e3ee74db94d215bd297738d93577481f3e4db38013326c90d57f873df7ab41d5 ... +Using docker image sha256:6b3f6590a9b30bd7aafb9573f047d930c70066e43955b4beb18a1eee175f6de1 for gcr.io/triggermesh/tm@sha256:e3ee74db94d215bd297738d93577481f3e4db38013326c90d57f873df7ab41d5 ... +Running on runner-72989761-project-4342902-concurrent-0 via runner-72989761-stg-srm-1541795796-27929c96... +Cloning repository... +Cloning into '/builds/danielgruesso/knative'... +Checking out 8671ad20 as master... +Skipping Git submodules setup +$ echo "$CI_REGISTRY_IMAGE" +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 +Job succeeded +``` + +The second to last line, labeled "**Service domain**" contains the URL for the deployment. Copy and paste the domain into your +browser to see the app live. + +![knative app](img/knative-app.png) \ No newline at end of file -- cgit v1.2.1 From 385576df5784a738634ef44868c5813739099320 Mon Sep 17 00:00:00 2001 From: danielgruesso Date: Fri, 9 Nov 2018 16:52:51 -0500 Subject: fix broken links --- doc/user/project/clusters/serverless/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/user/project/clusters/serverless') diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index 74c081531a3..c67ee25c109 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -57,7 +57,7 @@ You may download the sample [Knative Ruby App](https://gitlab.com/knative-exampl 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) + ![dns entry](img/dns-entry.png) ## Deploying the GitLab Runner (optional) -- cgit v1.2.1 From ddda4f5bd072b043a964c861d6950df20c5a3c4d Mon Sep 17 00:00:00 2001 From: danielgruesso Date: Mon, 12 Nov 2018 15:58:32 -0500 Subject: include ci-yml in body --- .../project/clusters/serverless/img/dns-entry.png | Bin 103867 -> 56600 bytes doc/user/project/clusters/serverless/index.md | 56 ++++++++++++++++----- .../serverless/serverless_ci_yml_template.yml | 25 --------- 3 files changed, 44 insertions(+), 37 deletions(-) delete mode 100644 doc/user/project/clusters/serverless/serverless_ci_yml_template.yml (limited to 'doc/user/project/clusters/serverless') diff --git a/doc/user/project/clusters/serverless/img/dns-entry.png b/doc/user/project/clusters/serverless/img/dns-entry.png index f72ae57718d..2e7655c6041 100644 Binary files a/doc/user/project/clusters/serverless/img/dns-entry.png and b/doc/user/project/clusters/serverless/img/dns-entry.png differ diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index c67ee25c109..3099504ce4a 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -22,15 +22,45 @@ To run Knative on Gitlab, you will need: 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. + all the other applications. 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. **Serverless `gitlab-ci.yml` Template:** GitLab uses [Kaniko](https://github.com/GoogleContainerTools/kaniko) + to build the application and the [TriggerMesh CLI](https://github.com/triggermesh/tm), to simplify the + deployment of knative services and functions. + + 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 below). + + ```yaml + stages: + - build + - deploy + + build: + stage: build + image: + name: gcr.io/kaniko-project/executor:debug + entrypoint: [""] + only: + - master + script: + - echo "{\"auths\":{\"$CI_REGISTRY\":{\"username\":\"$CI_REGISTRY_USER\",\"password\":\"$CI_REGISTRY_PASSWORD\"}}}" > /kaniko/.docker/config.json + - /kaniko/executor --context $CI_PROJECT_DIR --dockerfile $CI_PROJECT_DIR/Dockerfile --destination $CI_REGISTRY_IMAGE + + deploy: + stage: deploy + image: gcr.io/triggermesh/tm@sha256:e3ee74db94d215bd297738d93577481f3e4db38013326c90d57f873df7ab41d5 + only: + - master + environment: production + script: + - echo "$CI_REGISTRY_IMAGE" + - tm -n "$KUBE_NAMESPACE" --config "$KUBECONFIG" deploy service "$CI_PROJECT_NAME" --from-image "$CI_REGISTRY_IMAGE" --wait + ``` + 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. @@ -54,16 +84,18 @@ You may download the sample [Knative Ruby App](https://gitlab.com/knative-exampl 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.png) + Output: -## Deploying the GitLab Runner (optional) + ```bash + 35.161.143.124 my-machine-name:~ my-user$ + ``` -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. +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.example.com` then you need to create an A record with domain `*.knative.example.com` + pointing the ip address of the ingress. -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. + ![dns entry](img/dns-entry.png) ## Deploy the application with Knative diff --git a/doc/user/project/clusters/serverless/serverless_ci_yml_template.yml b/doc/user/project/clusters/serverless/serverless_ci_yml_template.yml deleted file mode 100644 index 31f68f223ca..00000000000 --- a/doc/user/project/clusters/serverless/serverless_ci_yml_template.yml +++ /dev/null @@ -1,25 +0,0 @@ -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 -- cgit v1.2.1 From 9f400c085969855891b92c1aa7d5cfaaaf8c969b Mon Sep 17 00:00:00 2001 From: Daniel Gruesso Date: Tue, 13 Nov 2018 15:10:56 +0000 Subject: trigger build for docs --- doc/user/project/clusters/serverless/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/user/project/clusters/serverless') diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index 3099504ce4a..b44d14d2294 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -6,7 +6,7 @@ Run serverless workloads on Kubernetes using [Knative](https://cloud.google.com/ ## 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: +Knative extends Kubernetes to provide a set of middleware components that are useful to build modern, source-centric, 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 -- cgit v1.2.1 From 37582015977ef6a71f23a1cbb131160aaf9c28f5 Mon Sep 17 00:00:00 2001 From: danielgruesso Date: Tue, 13 Nov 2018 14:38:05 -0500 Subject: correct dockerfile term and update port --- doc/user/project/clusters/serverless/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/user/project/clusters/serverless') diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index b44d14d2294..046564d6015 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -61,8 +61,8 @@ To run Knative on Gitlab, you will need: - tm -n "$KUBE_NAMESPACE" --config "$KUBECONFIG" deploy service "$CI_PROJECT_NAME" --from-image "$CI_REGISTRY_IMAGE" --wait ``` -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. +1. **Dockerfile:** 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. ## Installing Knative via GitLab's Kubernetes integration -- cgit v1.2.1 From 94b9ec52a18d6448ecb21f2e21c2e71e75a0e363 Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Fri, 16 Nov 2018 03:38:59 +0000 Subject: Replace deploy-stage.png with smaller and cropped --- .../clusters/serverless/img/deploy-stage.png | Bin 34472 -> 12029 bytes 1 file changed, 0 insertions(+), 0 deletions(-) (limited to 'doc/user/project/clusters/serverless') diff --git a/doc/user/project/clusters/serverless/img/deploy-stage.png b/doc/user/project/clusters/serverless/img/deploy-stage.png index eed5f948ba0..dc2f8af9c63 100644 Binary files a/doc/user/project/clusters/serverless/img/deploy-stage.png and b/doc/user/project/clusters/serverless/img/deploy-stage.png differ -- cgit v1.2.1 From d3fede240fb1877735a6346b67fa5acd8795e397 Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Fri, 16 Nov 2018 03:55:12 +0000 Subject: minor edits --- doc/user/project/clusters/serverless/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'doc/user/project/clusters/serverless') diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index 046564d6015..bdbc4f7f09d 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -100,12 +100,12 @@ You may download the sample [Knative Ruby App](https://gitlab.com/knative-exampl ## 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**". +**CI/CD >> Pipelines** and click the **Run Pipeline** button at the upper-right part of the screen. Then, on the +Pipelines page, click **Create pipeline**. ## Obtain the URL for the Knative deployment -Once all the stages of the pipeline finish, click on the "deploy" stage +Once all the stages of the pipeline finish, click the **deploy** stage. ![deploy stage](img/deploy-stage.png) @@ -131,7 +131,7 @@ Service domain: knative.knative-4342902.knative.info Job succeeded ``` -The second to last line, labeled "**Service domain**" contains the URL for the deployment. Copy and paste the domain into your +The second to last line, labeled **Service domain** contains the URL for the deployment. Copy and paste the domain into your browser to see the app live. ![knative app](img/knative-app.png) \ No newline at end of file -- cgit v1.2.1