diff options
Diffstat (limited to 'doc/user/project/clusters/serverless')
| -rw-r--r-- | doc/user/project/clusters/serverless/aws.md | 38 | ||||
| -rw-r--r-- | doc/user/project/clusters/serverless/index.md | 71 |
2 files changed, 54 insertions, 55 deletions
diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md index 0de0fd38336..a52d3400aa2 100644 --- a/doc/user/project/clusters/serverless/aws.md +++ b/doc/user/project/clusters/serverless/aws.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Deploying AWS Lambda function using GitLab CI/CD @@ -29,7 +29,7 @@ Alternatively, you can quickly [create a new project with a template](../../../. ### Example -In the following example, you will: +This example shows you how to: 1. Create a basic AWS Lambda Node.js function. 1. Link the function to an API Gateway `GET` endpoint. @@ -49,7 +49,7 @@ Lets take it step by step. #### Creating a Lambda handler function -Your Lambda function will be the primary handler of requests. In this case we will create a very simple Node.js `hello` function: +Your Lambda function is the primary handler of requests. In this case, create a very simple Node.js `hello` function: ```javascript 'use strict'; @@ -72,13 +72,13 @@ Place this code in the file `src/handler.js`. `src` is the standard location for serverless functions, but is customizable should you desire that. -In our case, `module.exports.hello` defines the `hello` handler that will be referenced later in the `serverless.yml` +In our case, `module.exports.hello` defines the `hello` handler to reference later in the `serverless.yml`. You can learn more about the AWS Lambda Node.js function handler and all its various options here: <https://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-handler.html> #### Creating a `serverless.yml` file -In the root of your project, create a `serverless.yml` file that will contain configuration specifics for the Serverless Framework. +In the root of your project, create a `serverless.yml` file containing configuration specifics for the Serverless Framework. Put the following code in the file: @@ -97,9 +97,9 @@ functions: Our function contains a handler and a event. -The handler definition will provision the Lambda function using the source code located `src/handler.hello`. +The handler definition provisions the Lambda function using the source code located `src/handler.hello`. -The `events` declaration will create a AWS API Gateway `GET` endpoint to receive external requests and hand them over to the Lambda function via a service integration. +The `events` declaration creates an AWS API Gateway `GET` endpoint to receive external requests and hand them over to the Lambda function via a service integration. You can read more about the [available properties and additional configuration possibilities](https://www.serverless.com/framework/docs/providers/aws/guide/serverless.yml/) of the Serverless Framework. @@ -141,10 +141,10 @@ For more information please see [Create a custom variable in the UI](../../../.. #### Deploying your function -`git push` the changes to your GitLab repository and the GitLab build pipeline will automatically deploy your function. +`git push` the changes to your GitLab repository and the GitLab build pipeline deploys your function. -In your GitLab deploy stage log, there will be output containing your AWS Lambda endpoint URL. -The log line will look similar to this: +Your GitLab deploy stage log contains output containing your AWS Lambda endpoint URL, +with log lines similar to this: ```plaintext endpoints: @@ -157,7 +157,7 @@ Running the following `curl` command should trigger your function. Your URL should be the one retrieved from the GitLab deploy stage log: ```shell -curl https://u768nzby1j.execute-api.us-east-1.amazonaws.com/production/hello +curl "https://u768nzby1j.execute-api.us-east-1.amazonaws.com/production/hello" ``` That should output: @@ -200,7 +200,7 @@ The `serverless-offline` plugin allows to run your code locally. To run your cod Running the following `curl` command should trigger your function. ```shell -curl http://localhost:3000/hello +curl "http://localhost:3000/hello" ``` It should output: @@ -227,9 +227,9 @@ provider: ``` From there, you can reference them in your functions as well. -Remember to add `A_VARIABLE` to your GitLab CI/CD variables under **Settings > CI/CD > Variables**, and it will get picked up and deployed with your function. +Remember to add `A_VARIABLE` to your GitLab CI/CD variables under **Settings > CI/CD > Variables** to be picked up and deployed with your function. -NOTE: **Note:** +NOTE: Anyone with access to the AWS environment may be able to see the values of those variables persisted in the lambda definition. @@ -309,7 +309,7 @@ GitLab allows developers to build and deploy serverless applications using the c ### Example -In the following example, you will: +This example shows you how to: - Install SAM CLI. - Create a sample SAM application including a Lambda function and API Gateway. @@ -414,8 +414,8 @@ Let’s examine the configuration file more closely: ### Deploying your application -Push changes to your GitLab repository and the GitLab build pipeline will automatically -deploy your application. If your: +Push changes to your GitLab repository and the GitLab build pipeline +deploys your application. If your: - Build and deploy are successful, [test your deployed application](#testing-the-deployed-application). - Build fails, look at the build log to see why the build failed. Some common reasons @@ -444,7 +444,7 @@ To test the application you deployed, please go to the build log and follow the 1. Use curl to test the API. For example: ```shell - curl https://py4rg7qtlg.execute-api.us-east-1.amazonaws.com/Prod/hello/ + curl "https://py4rg7qtlg.execute-api.us-east-1.amazonaws.com/Prod/hello/" ``` Output should be: @@ -496,7 +496,7 @@ listening on `localhost:3000`. Call the `hello` API by running: ```shell -curl http://127.0.0.1:3000/hello +curl "http://127.0.0.1:3000/hello" ``` Output again should be: diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index 603c4bd73b1..fcbf85121b2 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -1,15 +1,15 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Serverless > Introduced in GitLab 11.5. -CAUTION: **Caution:** -Serverless is currently in [alpha](https://about.gitlab.com/handbook/product/#alpha). +WARNING: +Serverless is currently in [alpha](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha). ## Overview @@ -39,9 +39,9 @@ With GitLab Serverless, you can deploy both functions-as-a-service (FaaS) and se ## Prerequisites -To run Knative on GitLab, you will need: +To run Knative on GitLab, you need: -1. **Existing GitLab project:** You will need a GitLab project to associate all resources. The simplest way to get started: +1. **Existing GitLab project:** You need a GitLab project to associate all resources. The simplest way to get started: - If you are planning on [deploying functions](#deploying-functions), clone the [functions example project](https://gitlab.com/knative-examples/functions) to get started. @@ -49,21 +49,21 @@ To run Knative on GitLab, you will need: clone the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) to get started. 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](../add_remove_clusters.md). + The simplest way to get started is to add a cluster using the GitLab [GKE integration](../add_remove_clusters.md). The set of minimum recommended cluster specifications to run Knative is 3 nodes, 6 vCPUs, and 22.50 GB memory. -1. **GitLab Runner:** A runner is required to run the CI jobs that will deploy serverless +1. **GitLab Runner:** A runner is required to run the CI jobs that deploy serverless applications or functions onto your cluster. You can install GitLab Runner onto the existing Kubernetes cluster. See [Installing Applications](../index.md#installing-applications) for more information. -1. **Domain Name:** Knative will provide its own load balancer using Istio. It will provide an - external IP address or hostname 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. **Domain Name:** Knative provides its own load balancer using Istio, and an + external IP address or hostname for all the applications served by Knative. Enter a + wildcard domain to serve your applications. Configure your DNS server to use the external IP address or hostname for that domain. 1. **`.gitlab-ci.yml`:** GitLab uses [Kaniko](https://github.com/GoogleContainerTools/kaniko) to build the application. We also use [GitLab Knative tool](https://gitlab.com/gitlab-org/gitlabktl) CLI to simplify the deployment of services and functions to Knative. 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. + contains the information for all the functions being hosted in the repository as well as a reference + to the runtime being used. 1. **`Dockerfile`** (for [applications only](#deploying-serverless-applications)): Knative requires a `Dockerfile` in order to build your applications. It should be included at the root of your project's repository and expose port `8080`. `Dockerfile` is not require if you plan to build serverless functions @@ -73,7 +73,7 @@ To run Knative on GitLab, you will need: 1. **Logging** (optional): Configuring logging allows you to view and search request logs for your serverless function/application. See [Configuring logging](#configuring-logging) for more information. -## Installing Knative via GitLab's Kubernetes integration +## Installing Knative via the GitLab Kubernetes integration The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22.50 GB memory. **RBAC must be enabled.** @@ -87,12 +87,12 @@ memory. **RBAC must be enabled.** 1. After the Knative installation has finished, you can wait for the IP address or hostname to be displayed in the **Knative Endpoint** field or [retrieve the Istio Ingress Endpoint manually](../../../clusters/applications.md#determining-the-external-endpoint-manually). - NOTE: **Note:** + NOTE: Running `kubectl` commands on your cluster requires setting up access to the cluster first. For clusters created on GKE, see [GKE Cluster Access](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl), for other platforms [Install kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). -1. The Ingress is now available at this address and will route incoming requests to the proper service based on the DNS +1. The Ingress is now available at this address and routes incoming requests to the proper service based on the DNS name in the request. To support this, a wildcard DNS 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 or CNAME record with domain `*.knative.info` pointing the IP address or hostname of the Ingress. @@ -107,7 +107,7 @@ on a given project, but not both. The current implementation makes use of a > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/58941) in GitLab 12.0. -The _invocations_ monitoring feature of GitLab serverless won't work when +The _invocations_ monitoring feature of GitLab serverless is unavailable when adding an existing installation of Knative. It's also possible to use GitLab Serverless with an existing Kubernetes cluster @@ -121,9 +121,9 @@ which already has Knative installed. You must do the following: - For a non-GitLab managed cluster, ensure that the service account for the token provided can manage resources in the `serving.knative.dev` API group. - For a GitLab managed cluster, if you added the cluster in [GitLab 12.1 or later](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30235), - then GitLab will already have the required access and you can proceed to the next step. + then GitLab already has the required access and you can proceed to the next step. - Otherwise, you need to manually grant GitLab's service account the ability to manage + Otherwise, you need to manually grant the GitLab service account the ability to manage resources in the `serving.knative.dev` API group. Since every GitLab service account has the `edit` cluster role, the simplest way to do this is with an [aggregated ClusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#aggregated-clusterroles) @@ -234,12 +234,12 @@ Follow these steps to deploy a function using the Node.js runtime to your Knative instance (you can skip these steps if you've cloned the example project): -1. Create a directory that will house the function. In this example we will +1. Create a directory to house the function. In this example we will create a directory called `echo` at the root of the project. -1. Create the file that will contain the function code. In this example, our file is called `echo.js` and is located inside the `echo` directory. If your project is: +1. Create the file to contain the function code. In this example, our file is called `echo.js` and is located inside the `echo` directory. If your project is: - Public, continue to the next step. - - Private, you will need to [create a GitLab deploy token](../../deploy_tokens/index.md#creating-a-deploy-token) with `gitlab-deploy-token` as the name and the `read_registry` scope. + - Private, you must [create a GitLab deploy token](../../deploy_tokens/index.md#creating-a-deploy-token) with `gitlab-deploy-token` as the name and the `read_registry` scope. 1. `.gitlab-ci.yml`: this defines a pipeline used to deploy your functions. It must be included at the root of your repository: @@ -304,7 +304,7 @@ Explanation of the fields used above: | Parameter | Description | |-----------|-------------| -| `service` | Name for the Knative service which will serve the function. | +| `service` | Name for the Knative service which serves the function. | | `description` | A short description of the `service`. | ### `provider` @@ -349,9 +349,9 @@ The optional `runtime` parameter can refer to one of the following runtime alias | `openfaas/classic/ruby` | OpenFaaS | After the `gitlab-ci.yml` template has been added and the `serverless.yml` file -has been created, pushing a commit 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 +has been created, pushing a commit to your project results in a CI pipeline +being executed which deploys each function as a Knative service. After the +deploy stage has finished, additional details for the function display under **Operations > Serverless**.  @@ -376,7 +376,7 @@ The sample function can now be triggered from any HTTP client using a simple `PO --header "Content-Type: application/json" \ --request POST \ --data '{"GitLab":"FaaS"}' \ - http://functions-echo.functions-1.functions.example.com/ + "http://functions-echo.functions-1.functions.example.com/" ``` 1. Using a web-based tool (such as Postman or Restlet) @@ -443,14 +443,13 @@ To run a function locally: 1. Invoke your function: ```shell - curl http://localhost:8080 + curl "http://localhost:8080" ``` ## Deploying Serverless applications > Introduced in GitLab 11.5. -12345678901234567890123456789012345678901234567890123456789012345678901234567890 Serverless applications are an alternative to [serverless functions](#deploying-functions). They're useful in scenarios where an existing runtime does not meet the needs of an application, such as one written in a language that has no runtime available. @@ -482,7 +481,7 @@ A `serverless.yml` file is not required when deploying serverless applications. ### Deploy the application with Knative -With all the pieces in place, the next time a CI pipeline runs, the Knative application will be deployed. Navigate to +With all the pieces in place, the next time a CI pipeline runs the Knative application deploys. Navigate to **CI/CD > Pipelines** and click the most recent pipeline. ### Function details @@ -498,13 +497,13 @@ rows to bring up the function details page.  -The pod count will give you the number of pods running the serverless function instances on a given cluster. +The pod count gives you the number of pods running the serverless function instances on a given cluster. For the Knative function invocations to appear, [Prometheus must be installed](../index.md#installing-applications). Once Prometheus is installed, a message may appear indicating that the metrics data _is -loading or is not available at this time._ It will appear upon the first access of the +loading or is not available at this time._ It appears upon the first access of the page, but should go away after a few seconds. If the message does not disappear, then it is possible that GitLab is unable to connect to the Prometheus instance running on the cluster. @@ -558,7 +557,7 @@ Or: ## Enabling TLS for Knative services -By default, a GitLab serverless deployment will be served over `http`. To serve +By default, a GitLab serverless deployment is served over `http`. To serve over `https`, you must manually obtain and install TLS certificates. 12345678901234567890123456789012345678901234567890123456789012345678901234567890 @@ -647,7 +646,7 @@ or with other versions of Python. ``` 1. Create certificate and private key files. Using the contents of the files - returned by Certbot, we'll create two files in order to create the + returned by Certbot, create two files in order to create the Kubernetes secret: Run the following command to see the contents of `fullchain.pem`: @@ -767,7 +766,7 @@ or with other versions of Python. 1. Create a Kubernetes secret to hold your TLS certificate, `cert.pem`, and the private key `cert.pk`: - NOTE: **Note:** + NOTE: Running `kubectl` commands on your cluster requires setting up access to the cluster first. For clusters created on GKE, see [GKE Cluster Access](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl). @@ -828,8 +827,8 @@ or with other versions of Python. ``` After your changes are running on your Knative cluster, you can begin using the HTTPS protocol for secure access your deployed Knative services. - In the event a mistake is made during this process and you need to update the cert, you will need to edit the gateway `knative-ingress-gateway` - to switch back to `PASSTHROUGH` mode. Once corrections are made, edit the file again so the gateway will use the new certificates. + In the event a mistake is made during this process and you need to update the cert, you must edit the gateway `knative-ingress-gateway` + to switch back to `PASSTHROUGH` mode. Once corrections are made, edit the file again so the gateway uses the new certificates. ## Using an older version of `gitlabktl` |