diff options
author | Daniel Gruesso <dgruesso@gitlab.com> | 2018-12-14 16:45:31 +0300 |
---|---|---|
committer | Achilleas Pipinellis <axil@gitlab.com> | 2018-12-14 16:45:31 +0300 |
commit | a83b0bb247764c69541ac3b9cc3baa9206eec7d0 (patch) | |
tree | 784cea861b771398ae5ee1c3ce89602d7b0be226 /doc/user | |
parent | 7304d66b8728b16916d90f80abe4b25f03446f29 (diff) |
Serverless Doc Updates
Diffstat (limited to 'doc/user')
-rw-r--r-- | doc/user/project/clusters/serverless/img/deploy-stage.png | bin | 12029 -> 5078 bytes | |||
-rw-r--r-- | doc/user/project/clusters/serverless/img/dns-entry.png | bin | 56600 -> 19583 bytes | |||
-rw-r--r-- | doc/user/project/clusters/serverless/img/install-knative.png | bin | 31222 -> 13243 bytes | |||
-rw-r--r-- | doc/user/project/clusters/serverless/img/knative-app.png | bin | 28998 -> 9493 bytes | |||
-rw-r--r-- | doc/user/project/clusters/serverless/img/serverless-page.png | bin | 31743 -> 11829 bytes | |||
-rw-r--r-- | doc/user/project/clusters/serverless/index.md | 231 |
6 files changed, 163 insertions, 68 deletions
diff --git a/doc/user/project/clusters/serverless/img/deploy-stage.png b/doc/user/project/clusters/serverless/img/deploy-stage.png Binary files differindex dc2f8af9c63..a1e0095bf29 100644 --- a/doc/user/project/clusters/serverless/img/deploy-stage.png +++ b/doc/user/project/clusters/serverless/img/deploy-stage.png diff --git a/doc/user/project/clusters/serverless/img/dns-entry.png b/doc/user/project/clusters/serverless/img/dns-entry.png Binary files differindex 2e7655c6041..678743f256e 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 Binary files differindex a9fcc127240..94f4c84181f 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/knative-app.png b/doc/user/project/clusters/serverless/img/knative-app.png Binary files differindex 54301e1786f..a5b2945f6f4 100644 --- a/doc/user/project/clusters/serverless/img/knative-app.png +++ b/doc/user/project/clusters/serverless/img/knative-app.png diff --git a/doc/user/project/clusters/serverless/img/serverless-page.png b/doc/user/project/clusters/serverless/img/serverless-page.png Binary files differindex 473ee801f10..5d808fc2d4f 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 bdbc4f7f09d..c1f2e844362 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -2,109 +2,204 @@ > Introduced in GitLab 11.5. +CAUTION: **Caution:** +Serverless is currently in [alpha](https://about.gitlab.com/handbook/product/#alpha). + 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, 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 +- [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). +With GitLab serverless, you can deploy both functions-as-a-service (FaaS) and serverless applications. + ## 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. -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 +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). +1. **Helm Tiller:** Helm is a package manager for Kubernetes and is required to install + Knative. +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 [Kaniko](https://github.com/GoogleContainerTools/kaniko) - to build the application and the [TriggerMesh CLI](https://github.com/triggermesh/tm), to simplify the +1. **`gitlab-ci.yml`:** 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. **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. +1. **`serverless.yml`** (for [functions only](#deploying-functions)): When using serverless to deploy functions, the `serverless.yml` file + will contain the information for all the functions being hosted in the repository as well as a reference to the + runtime being used. +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 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. +The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22.50 GB memory. **RBAC must be enabled.** -1. Once Helm has been successfully installed, on the Knative app section, enter the domain to be used with +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". ![install-knative](img/install-knative.png) -1. After the Knative installation has finished, retrieve the Istio Ingress IP address by running the following command: +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: - ```bash - kubectl get svc --namespace=istio-system knative-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip} ' - ``` + ```bash + kubectl get svc --namespace=istio-system knative-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip} ' + ``` - Output: + Output: - ```bash - 35.161.143.124 my-machine-name:~ my-user$ - ``` + ```bash + 35.161.143.124 my-machine-name:~ my-user$ + ``` -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. +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` + pointing the ip address of the ingress. ![dns entry](img/dns-entry.png) +## Deploying Functions + +> Introduced in GitLab 11.6. + +Using functions is useful for initiating, responding, or triggering independent +events without needing to maintain a complex unified infrastructure. This allows +you to focus on a single task that can be executed/scaled automatically and independently. + +In order to deploy functions to your Knative instance, the following templates must be present: + +1. `gitlab-ci.yml`: This template allows to define the stage, environment, and + image to be used for your functions. It must be included at the root of your repository: + + ```yaml + stages: + - deploy + + functions: + stage: deploy + environment: test + image: gcr.io/triggermesh/tm:v0.0.6 + script: + - tm -n "$KUBE_NAMESPACE" set registry-auth gitlab-registry --registry "$CI_REGISTRY" --username "$CI_REGISTRY_USER" --password "$CI_JOB_TOKEN" + - tm -n "$KUBE_NAMESPACE" --registry-host "$CI_REGISTRY_IMAGE" deploy --wait + ``` + +2. `serverless.yml`: This template contains the metadata for your functions, + such as name, runtime, and environment. It must be included at the root of your repository: + + ```yaml + service: knative-test + description: "Deploying functions from GitLab using Knative" + + provider: + name: triggermesh + registry-secret: gitlab-registry + environment: + FOO: BAR + + functions: + container: + handler: simple + description: "knative canonical sample" + runtime: https://gitlab.com/triggermesh/runtimes/raw/master/kaniko.yaml + buildargs: + - DIRECTORY=simple + environment: + SIMPLE_MSG: Hello + + nodejs: + handler: nodejs + runtime: https://gitlab.com/triggermesh/runtimes/raw/master/nodejs.yaml + description: "nodejs fragment" + buildargs: + - DIRECTORY=nodejs + environment: + FUNCTION: nodejs + ``` + +After the templates have been created, each function must be defined as a single +file in your repository. Committing a function to your project will result in a +CI pipeline being executed which will deploy each function as a Knative service. +Once the deploy stage has finished, additional details for the function will +appear under **Operations > Serverless**. + +![serverless page](img/serverless-page.png) + +This page contains all functions available for the project, the URL 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. + +The function details can be retrieved directly from Knative on the cluster: + +```bash +kubectl -n "$KUBE_NAMESPACE" get services.serving.knative.dev +``` + +Currently, the Serverless page presents all functions available in all clusters registered for the project with Knative installed. + +## 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. + +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): + +```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 +``` + ## 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 the **Run Pipeline** button at the upper-right part of the screen. Then, on the +With all the pieces in place, you can create a new CI pipeline to deploy the Knative application. Navigate to +**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 +There are two ways to obtain the URL for the Knative deployment. + +### Using the CI/CD deployment job output + Once all the stages of the pipeline finish, click the **deploy** stage. ![deploy stage](img/deploy-stage.png) @@ -131,7 +226,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 +![knative app](img/knative-app.png) |