From 7feeef2faebb2f0bb410c184b04c147f0cbc4d28 Mon Sep 17 00:00:00 2001 From: Nicholas Klick Date: Mon, 16 Sep 2019 16:32:16 -0400 Subject: [PATCH] Document Lambda deploys via GitLab CI/CD --- .../unreleased/document-lambda-deploy.yml | 5 + doc/user/project/clusters/serverless/aws.md | 169 ++++++++++++++++++ doc/user/project/clusters/serverless/index.md | 16 +- 3 files changed, 188 insertions(+), 2 deletions(-) create mode 100644 changelogs/unreleased/document-lambda-deploy.yml create mode 100644 doc/user/project/clusters/serverless/aws.md diff --git a/changelogs/unreleased/document-lambda-deploy.yml b/changelogs/unreleased/document-lambda-deploy.yml new file mode 100644 index 00000000000..c569fbbb280 --- /dev/null +++ b/changelogs/unreleased/document-lambda-deploy.yml @@ -0,0 +1,5 @@ +--- +title: Document Lambda deploys with gitlab-ci +merge_request: 32478 +author: +type: other diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md new file mode 100644 index 00000000000..35f42afbef8 --- /dev/null +++ b/doc/user/project/clusters/serverless/aws.md @@ -0,0 +1,169 @@ +# 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 + +Getting gitlab-ci to work with Serverless Framework is incredibly simple. + +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: + +### 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: + +### Crafting the .gitlab-ci.yml file + +In a `.gitlab-ci.yml` file, place the following code: + +```yaml +image: node:latest + +variables: + AWS_ACCESS_KEY_ID: $AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY: $AWS_SECRET_ACCESS_KEY + +stages: + - build + +staging: + stage: deploy + before_script: + - npm config set prefix /usr/local + - npm install -g serverless + script: + - serverless deploy --stage staging --verbose + environment: staging + +``` + +This example code does the following: + +1. Uses the `node:latest` image for all GitLab CI builds +1. Assigns 2 environment variables to handle your AWS credentials +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: + +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/staging/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/staging/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..3a36bfd9270 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -5,10 +5,22 @@ 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. -- GitLab