diff options
Diffstat (limited to 'doc/user/project/clusters/serverless')
-rw-r--r-- | doc/user/project/clusters/serverless/aws.md | 163 | ||||
-rw-r--r-- | doc/user/project/clusters/serverless/index.md | 19 |
2 files changed, 178 insertions, 4 deletions
diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md new file mode 100644 index 00000000000..2c16748a3ee --- /dev/null +++ b/doc/user/project/clusters/serverless/aws.md @@ -0,0 +1,163 @@ +# Deploying AWS Lambda function using GitLab CI/CD + +GitLab allows users to easily deploy AWS Lambda functions and create rich serverless applications. + +GitLab supports deployment of functions to AWS Lambda using a combination of: + +- [Serverless Framework](https://serverless.com) +- GitLab CI/CD + +## Example + +In the following example, you will: + +1. Create a basic AWS Lambda Node.js function. +1. Link the function to an API Gateway `GET` endpoint. + +### Steps + +The example consists of the following steps: + +1. Creating a Lambda handler function +1. Creating a `serverless.yml` file +1. Crafting the `.gitlab-ci.yml` file +1. Setting up your AWS credentials with your GitLab account +1. Deploying your function +1. Testing your function + +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: + +```javascript +'use strict'; + +module.exports.hello = async event => { + return { + statusCode: 200, + body: JSON.stringify( + { + message: 'Your function executed successfully!' + }, + null, + 2 + ), + }; +}; + + +``` + +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` + +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. + +Put the following code in the file: + +```yaml +service: gitlab-example +provider: + name: aws + runtime: nodejs10.x + +functions: + hello: + handler: src/handler.hello + events: + - http: GET hello +``` + +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 `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. + +You can read more about the available properties and additional configuration possibilities of the Serverless Framework here: <https://serverless.com/framework/docs/providers/aws/guide/serverless.yml/> + +### Crafting the .gitlab-ci.yml file + +In a `.gitlab-ci.yml` file, place the following code: + +```yaml +image: node:latest + +stages: + - deploy + +production: + stage: deploy + before_script: + - npm config set prefix /usr/local + - npm install -g serverless + script: + - serverless deploy --stage production --verbose + environment: production +``` + +This example code does the following: + +1. Uses the `node:latest` image for all GitLab CI builds +1. The `deploy` stage: + +- Installs the `serverless framework`. +- Deploys the serverless function to your AWS account using the AWS credentials defined above. + +### Setting up your AWS credentials with your GitLab account + +In order to interact with your AWS account, the .gitlab-ci.yml requires both `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` be defined in your GitLab settings under **Settings > CI/CD > Variables**. +For more information please see: <https://docs.gitlab.com/ee/ci/variables/README.html#via-the-ui> + +NOTE: **Note:** + The AWS credentials you provide must include IAM policies that provision correct access control to AWS Lambda, API Gateway, and CloudFormation resources. + +### Deploying your function + +Deploying your function is very simple, just `git push` to your GitLab repository and the GitLab build pipeline will automatically deploy 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: + +``` +endpoints: + GET - https://u768nzby1j.execute-api.us-east-1.amazonaws.com/production/hello +``` + +### Testing your function + +Running the following `curl` command should trigger your function. + +NOTE: **Note:** + Your url should be the one retrieved from the GitLab deploy stage log. + +```sh +curl https://u768nzby1j.execute-api.us-east-1.amazonaws.com/production/hello +``` + +Should output: + +```json +{ + "message": "Your function executed successfully!" +} +``` + +Hooray! You now have a AWS Lambda function deployed via GitLab CI. + +Nice work! + +## Example code + +To see the example code for this example please follow the link below: + +- [Node.js example](https://gitlab.com/gitlab-org/serverless/examples/serverless-framework-js): Deploy a AWS Lambda Javascript function + API Gateway using Serverless Framework and GitLab CI/CD diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index bcf9a677a40..5d91b01e5b0 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -5,10 +5,21 @@ 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 +Serverless architectures offer Operators and Developers the ability write highly scalable applications without provisioning a single server. + +Gitlab supports several ways deploy Serverless applications in both Kubernetes Environments and also major cloud FAAS environments. + +Currently we support: + +- [Knative](#knative): Build Knative applications with Knative and gitlabktl on GKE +- [AWS Lambda](aws.md): Create serverless applications via the Serverless Framework and gitlab-ci + +## Knative + +Run serverless workloads on Kubernetes using [Knative](https://cloud.google.com/knative/). + 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: - [Serving](https://github.com/knative/serving): Request-driven compute that can scale to zero. @@ -84,7 +95,7 @@ on a given project but not both. The current implementation makes use of a `serv ## Using an existing installation of Knative -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/58941) in GitLab 12.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/58941) in GitLab 12.0. NOTE: **Note:** The "invocations" monitoring feature of GitLab serverless will not work when @@ -102,7 +113,7 @@ You must do the following: 1. Ensure GitLab can manage Knative: - 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-ce/merge_requests/30235), + - 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. Otherwise, you need to manually grant GitLab's service account the ability to manage |