diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index 8e03d116b81..9f9b2da23e1 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -1,9 +1,7 @@ # Group-level Kubernetes clusters > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/34758) in GitLab 11.6. - -CAUTION: **Warning:** -Group Cluster integration is currently in **Beta**. +> Group Cluster integration is currently in [Beta](https://about.gitlab.com/handbook/product/#alpha-beta-ga). ## Overview diff --git a/doc/user/project/clusters/serverless/img/function-execution.png b/doc/user/project/clusters/serverless/img/function-execution.png new file mode 100644 index 00000000000..93b0b6d802d Binary files /dev/null and b/doc/user/project/clusters/serverless/img/function-execution.png differ diff --git a/doc/user/project/clusters/serverless/img/serverless-page.png b/doc/user/project/clusters/serverless/img/serverless-page.png index 5d808fc2d4f..960d6e736d6 100644 Binary files a/doc/user/project/clusters/serverless/img/serverless-page.png and b/doc/user/project/clusters/serverless/img/serverless-page.png differ diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index a1e5735670a..da6f4df01df 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -1,9 +1,7 @@ # Serverless > Introduced in GitLab 11.5. - -CAUTION: **Caution:** -Serverless is currently in [alpha](https://about.gitlab.com/handbook/product/#alpha). +> Serverless is currently in [alpha](https://about.gitlab.com/handbook/product/#alpha). Run serverless workloads on Kubernetes using [Knative](https://cloud.google.com/knative/). @@ -34,10 +32,10 @@ To run Knative on Gitlab, you will need: 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. -1. **`serverless.yml`** (for [functions only](#deploying-functions)): When using serverless to deploy functions, the `serverless.yml` file +1. **`serverless.yaml`** (for [functions only](#deploying-functions)): When using serverless to deploy functions, the `serverless.yaml` 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 +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`. ## Installing Knative via GitLab's Kubernetes integration @@ -75,11 +73,16 @@ The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22. > Introduced in GitLab 11.6. -Using functions is useful for initiating, responding, or triggering independent +Using functions is useful for dealing with 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: +Currently the following [runtimes](https://gitlab.com/triggermesh/runtimes) are offered: + +- node.js +- kaniko + +In order to deploy functions to your Knative instance, the following files 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: @@ -97,11 +100,16 @@ In order to deploy functions to your Knative instance, the following templates m - 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: + The `gitlab-ci.yml` template creates a `Deploy` stage with a `functions` job that invokes the `tm` CLI with the required parameters. + +2. `serverless.yaml`: This file contains the metadata for your functions, + such as name, runtime, and environment. It must be included at the root of your repository. The following is a sample `echo` function which shows the required structure for the file. + + NOTE: **Note:** + The file extension for the `serverless.yaml` file must be specified as `.yaml` in order to the file to be parsed properly. Specifying the extension as `.yml` will not work. ```yaml - service: knative-test + service: my-functions description: "Deploying functions from GitLab using Knative" provider: @@ -111,27 +119,51 @@ In order to deploy functions to your Knative instance, the following templates m FOO: BAR functions: - container: - handler: simple - description: "knative canonical sample" - runtime: https://gitlab.com/triggermesh/runtimes/raw/master/kaniko.yaml + echo: + handler: echo + runtime: https://gitlab.com/triggermesh/runtimes/raw/master/nodejs.yaml + description: "echo function using node.js runtime" 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 + - DIRECTORY=echo environment: - FUNCTION: nodejs + FUNCTION: echo ``` -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 + +The `serverless.yaml` file contains three sections with distinct parameters: + +### `service` + +| Parameter | Description | +|-----------|-------------| +| `service` | Name for the Knative service which will serve the function. | +| `description` | A short description of the `service`. | + + +### `provider` + +| Parameter | Description | +|-----------|-------------| +| `name` | Indicates which provider is used to execute the `serverless.yaml` file. In this case, the TriggerMesh `tm` CLI. | +| `registry-secret` | Indicates which registry will be used to store docker images. The sample function is using the GitLab Registry (`gitlab-registry`). A different registry host may be specified using `registry` key in the `provider` object. If changing the default, update the permission and the secret value on the `gitlab-ci.yml` file | +| `environment` | Includes the environment variables to be passed as part of function execution for **all** functions in the file, where `FOO` is the variable name and `BAR` are he variable contents. You may replace this with you own variables. | + +### `functions` + +In the `serverless.yaml` example above, the function name is `echo` and the subsequent lines contain the function attributes. + + +| Parameter | Description | +|-----------|-------------| +| `handler` | The function's file name. In the example above, both the function name and the handler are the same. | +| `runtime` | The runtime to be used to execute the function. | +| `description` | A short description of the function. | +| `buildargs` | Pointer to the function file in the repo. In the sample the function is located in the `echo` directory. | +| `environment` | Sets an environment variable for the specific function only. | + +After the `gitlab-ci.yml` template has been added and the `serverless.yaml` file has 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**. @@ -149,6 +181,10 @@ The function details can be retrieved directly from Knative on the cluster: 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. + +![function exection](img/function-execution.png) + Currently, the Serverless page presents all functions available in all clusters registered for the project with Knative installed. ## Deploying Serverless applications @@ -190,17 +226,12 @@ deploy: ## Deploy the application with Knative -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**. +With all the pieces in place, the next time a CI pipeline runs, the Knative application will be deployed. Navigate to +**CI/CD > Pipelines** and click the most recent 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. +Use the CI/CD deployment job output to obtain the deployment URL. Once all the stages of the pipeline finish, click the **deploy** stage. ![deploy stage](img/deploy-stage.png)