Skip to content

G
gitlab-ce
Commit 51e07381 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis
Browse files
Options

Merge branch '43959-serverless-tab-docs' into 'master' 

Serverless Doc Updates

Closes #55089

See merge request gitlab-org/gitlab-ce!23640
parents 7304d66b a83b0bb2
Hide whitespace changes
Inline Side-by-side
Showing with 163 additions and 68 deletions
doc/user/project/clusters/serverless/index.md
View file @ 51e07381
......@@ -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)
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7