└── docs ├── README.md ├── configuration-validation.md ├── examples-and-tutorials.md ├── getting-started.md ├── guides ├── README.md ├── compose.md ├── dashboard │ ├── README.md │ ├── cicd │ │ ├── README.md │ │ ├── best-practices.md │ │ ├── branch-deployments.md │ │ ├── custom-scripts.md │ │ ├── faq.md │ │ ├── mono-repo.md │ │ ├── notifications.md │ │ ├── preview-deployments.md │ │ ├── private-packages.md │ │ ├── running-in-your-own-cicd.md │ │ ├── running-tests.md │ │ └── troubleshooting.md │ ├── concepts.md │ ├── monitoring │ │ ├── README.md │ │ ├── metrics.md │ │ ├── sdk │ │ │ ├── README.md │ │ │ ├── nodejs.md │ │ │ └── python.md │ │ ├── traces.md │ │ └── troubleshoot.md │ ├── output-variables.md │ └── providers.md ├── deployment-bucket.md ├── license-keys.md ├── observability │ ├── README.md │ ├── axiom-api-tokens.png │ ├── axiom.md │ └── dashboard.md ├── parameters.md ├── plugins │ ├── README.md │ ├── cli-output.md │ ├── creating-plugins.md │ ├── custom-commands.md │ ├── custom-configuration.md │ ├── custom-variables.md │ └── extending-configuration.md ├── sam.md ├── state.md ├── upgrading-v4.md ├── variables │ ├── README.md │ ├── aws │ │ ├── README.md │ │ ├── cf-stack.md │ │ ├── s3.md │ │ └── ssm.md │ ├── cli-options.md │ ├── core.md │ ├── env-vars.md │ ├── file.md │ ├── git.md │ ├── hashicorp │ │ ├── README.md │ │ ├── terraform.md │ │ └── vault.md │ ├── javascript.md │ └── self.md └── workflow.md ├── menu.json ├── providers └── aws │ ├── README.md │ ├── cli-reference │ ├── README.md │ ├── deploy-function.md │ ├── deploy-list.md │ ├── deploy.md │ ├── dev.md │ ├── info.md │ ├── invoke-local.md │ ├── invoke.md │ ├── login.md │ ├── logs.md │ ├── metrics.md │ ├── package.md │ ├── plugin-install.md │ ├── plugin-uninstall.md │ ├── print.md │ ├── remove.md │ ├── rollback-function.md │ ├── rollback.md │ └── support.md │ ├── events │ ├── README.md │ ├── activemq.md │ ├── alb.md │ ├── alexa-skill.md │ ├── alexa-smart-home.md │ ├── apigateway.md │ ├── cloudfront.md │ ├── cloudwatch-event.md │ ├── cloudwatch-log.md │ ├── cognito-user-pool.md │ ├── event-bridge.md │ ├── http-api.md │ ├── iot-fleet-provisioning.md │ ├── iot.md │ ├── kafka.md │ ├── msk.md │ ├── rabbitmq.md │ ├── s3.md │ ├── schedule.md │ ├── sns.md │ ├── sqs.md │ ├── streams.md │ └── websocket.md │ ├── examples │ └── README.md │ └── guide │ ├── README.md │ ├── building.md │ ├── credentials.md │ ├── deploying.md │ ├── events.md │ ├── functions.md │ ├── iam.md │ ├── intro.md │ ├── layers.md │ ├── packaging.md │ ├── resources.md │ ├── serverless.yml.md │ ├── services.md │ └── testing.md └── tutorial.md /docs/README.md: -------------------------------------------------------------------------------- 1 | 16 | 17 | 18 | 19 | ### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/) 20 | 21 | 22 | 23 | # Serverless Framework - An Introduction 24 | 25 | ## Philosophy 26 | 27 | **_Build applications that demand attention, not maintenance._** 28 | 29 | In 2014, AWS Lambda was introduced offering a more efficient compute service in the cloud. With features like auto-scaling and no cost when idle, AWS Lambda offers a compute experience that demands so little maintenance it feels _"serverless"_. 30 | 31 | Months later, the Serverless Framework was created to streamline the deployment of various use-cases on AWS Lambda. The Serverless Framework introduced the concept of _"serverless architectures"_, a transformative approach to building applications on the cloud, integrating AWS Lambda and cloud infrastructure with similar "serverless" qualities, to enable developers to create entire applications that scale massively with minimal maintenance. 32 | 33 | Today, the Serverless Framework continues to be the original, leading and most trusted tool for enterprises and start-ups building serverless architectures. Renowned Fortune 500 companies such as the _New York Times_, _Nike_, and _EA Games_ utilize it, while numerous startups have reached unicorn valuations and achieved notable exits using the Framework. These successes have been accomplished with relatively small engineering teams, leveraging the power of serverless architectures. 34 | 35 | The mission of the Serverless Framework is to empower all developers to build more and manage less. 36 | 37 | ## Overview 38 | 39 | The Serverless Framework consists of a Command Line Interface and an optional Dashboard, and helps you deploy code and infrastructure together on Amazon Web Services, while increasingly supporting other cloud providers. The Framework is a YAML-based experience that uses simplified syntax to help you deploy complex infrastructure patterns easily, without needing to be a cloud expert. It is developed and maintained by Serverless Inc., a specialized software company based in San Francisco, California. Initially launched as an open-source project, the Framework has since transitioned to a SaaS product to better support its scalability and the extensive infrastructure capabilities it offers. 40 | 41 | ## Highlights 42 | 43 | - **Empowerment:** Innovate faster by spending less time on infrastructure management. 44 | - **Versatility:** Tackle diverse serverless use cases, from APIs and scheduled tasks to web sockets and data pipelines. 45 | - **Infra & Code:** Streamline development with code and infrastructure deployment handled together. 46 | - **Ease of Use:** Deploy complex applications without deep cloud infrastructure expertise, thanks to approachable YAML configuration. 47 | - **Language Agnostic:** Develop in your preferred language – Node.js, Python, Java, Go, C#, Ruby, Swift, Kotlin, PHP, Scala, or F# – the Framework supports them all. 48 | - **Full Lifecycle:** Build, deploy, monitor, update, and troubleshoot serverless applications with ease. 49 | - **Scalable Organization:** Structure large projects and teams efficiently with built-in support for stages and project composition. 50 | - **Plugin Ecosystem:** Extend and modify the Framework's functionality with a rich plugin ecosystem. 51 | - **Vibrant Community:** Get support and connect with a passionate community of Serverless developers. 52 | 53 | ## Next Steps 54 | 55 | Get started with the Serverless Framework on AWS [via this guide](https://serverless.com/framework/docs/getting-started/). 56 | 57 | Have questions? Join thousands of other developers in our [Slack Channel](https://serverless.com/slack). 58 | 59 | After that, we recommend you... 60 | 61 | - [Learn Serverless Framework's Core Concepts](https://www.serverless.com/framework/docs/providers/aws/guide/intro) 62 | - [Get inspiration from these Serverless Framework Templates](https://github.com/serverless/examples) 63 | - [Discover all of the events that can trigger AWS Lambda functions](https://www.serverless.com/framework/docs/providers/aws/guide/events) 64 | - [Bookmark Serverless Framework's `serverless.yml` guide](https://www.serverless.com/framework/docs/providers/aws/guide/serverless.yml) 65 | - [Search the plugins registry to extend Serverless Framework](https://www.serverless.com/plugins) 66 | -------------------------------------------------------------------------------- /docs/configuration-validation.md: -------------------------------------------------------------------------------- 1 | 14 | 15 | # Service configuration validation 16 | 17 | The framework validates service configuration with the help of [AJV](https://ajv.js.org/) (JSON-schema validation engine). 18 | 19 | If you were presented with configuration error (or a warning, depending on `configValidationMode` setting) it could mean that: 20 | 21 | - Service configuration is invalid and you need to correct an issue related to your serverless.yml 22 | - Configuration related to external plugin does not have an associated JSON Schema. In such cases, please report the issue with the plugin author and provide them the details on how to extend validation schema in order to permanently correct the issue. 23 | - However unlikely, there may be a bug (or missing) schema configuration for the framework. If you believe this to be the case please report at [https://github.com/serverless/serverless/issues/new](https://github.com/serverless/serverless/issues/new?template=bug_report.md) 24 | 25 | **Note**: In a warning mode (with `configValidationMode: warn` set in configuration) Framework commands are not blocked in any way, e.g. `sls deploy` will still attempt to deploy the service normally (still depending on the source of the warning, success of a deployment may vary) 26 | 27 | When the setting is not explicitly specified, serverless defaults to `configValidationMode: warn`. If you find this functionality problematic, you may also turn it off with `configValidationMode: off` setting. 28 | 29 | ## Configuration 30 | 31 | Add `configValidationMode` to your service configuration with one of the following values: 32 | 33 | | Value | Effect | 34 | | ----- | ----------------------------------------------------- | 35 | | error | Fail invoked command and output configuration errors. | 36 | | warn | Output configuration errors in form of warnings. | 37 | | off | Suppress configuration errors. | 38 | -------------------------------------------------------------------------------- /docs/examples-and-tutorials.md: -------------------------------------------------------------------------------- 1 | 13 | 14 | # Serverless Framework Examples and Tutorials 15 | 16 | ## Serverless Framework Examples 17 | 18 | The simplest way to get started with Serverless Framework is to create a project based on the **built-in templates**. To do so, run the `serverless` command and choose a template from the list: 19 | 20 | ```shell 21 | serverless 22 | ``` 23 | 24 | You can also find more examples and templates in the [**Serverless Examples registry**](https://www.serverless.com/examples). 25 | 26 | The examples registry is a collection of official examples, as well as examples contributed by the community. You can publish your examples by adding them to the [examples GitHub repository](https://github.com/serverless/examples). 27 | 28 | ## Serverless Framework Tutorials 29 | 30 | Check out the ["Your First Serverless Framework Project" tutorial](tutorial.md). It will guide you to create your first serverless application. 31 | 32 | You can explore more Serverless Framework tutorials in the [**Guides & tutorials** blog category](https://www.serverless.com/category/guides-and-tutorials). 33 | -------------------------------------------------------------------------------- /docs/guides/README.md: -------------------------------------------------------------------------------- 1 | 16 | 17 | 18 | 19 | ### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/guides/) 20 | 21 | 22 | 23 | # Serverless Framework User Guides 24 | 25 | Welcome to the Serverless Framework User Guides! 26 | 27 | [Get started with Serverless Framework](/framework/docs/getting-started) 28 | 29 | If you have questions, join the [chat in Slack](https://serverless.com/slack) or [post over on the forums](https://forum.serverless.com/) 30 | -------------------------------------------------------------------------------- /docs/guides/dashboard/README.md: -------------------------------------------------------------------------------- 1 | 7 | 8 | 9 | 10 | ### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/guides/dashboard/) 11 | 12 | 13 | 14 | # Serverless Framework Dashboard 15 | 16 | The [Serverless Framework Dashboard](https://app.serverless.com/) is a SaaS solution that augments the Serverless Framework CLI to provide a powerful, unified experience to develop, deploy, test, secure and monitor your serverless applications, across all AWS accounts. 17 | 18 | The aim of the Serverless Framework and its Dashboard is to offer a seamless, integrated development experience for you and your team throughout the entire lifecycle of your serverless applications. We hope it's a breath of fresh air compared to the complexity of interacting with the AWS Console across several accounts, directly. 19 | 20 | ## Features 21 | 22 | - **Deployments:** Easily see all Serverless Framework deployments made by you and your team, via CI/CD or local installations of the CLI, across all of your AWS accounts, in one place. Quickly check who made the deployment, what the status is, how it may have failed, see git metadata, serverless.yml, outputs, and much more. 23 | 24 | - **Secrets:** Set and share secrets in one place, for use within your Serverless Framework `serverless.yml` files. This works across all AWS accounts, so it's ideal for making secrets easy to use without wrestling with AWS permissions to access them. Secrets are encrypted and secure by default. 25 | 26 | - **Observability:** The richest and slickest observability solution for AWS Lambda on the market. We've spent years crafting an observability solution that developers love, specializing in AWS Lambda. Set-up requires zero effort and you will instantly get rich Metrics, Traces, Logs and Alerts, just deploy with the Serverless Framework. The Observability features also support non-Serverless Framework deployed AWS Lambda functions. Simply connect your AWS accounts and you'll be able to instrument all of the AWS Lambda functions in them. 27 | 28 | - **Providers:** Providers make it easy to manage deployment access to your AWS accounts. Each Provider connects to 1 AWS account, and you can assign it to specific Services, Stages, or set a Provider as a default across an entire AWS account. This enables your team to never have to deal with local AWS credentials. Providers use an AWS IAM Role to connect to your account and provide short-term credentials for every deployment, which is more secure by default. 29 | 30 | - **CI/CD:** CI/CD optimized for Serverless Framework that works out-of-the-box. Simply connect it to Github or BitBucket to enable automated deployments. Set up preview deployments for branches, and much more. 31 | 32 | ## Minimum Version Requirements 33 | 34 | To use Serverless Framework Dashboard, you must be using Serverless Framework CLI version 1.48.0 or later. 35 | 36 | For Serverless Framework's new Observability offering, you must use version 3.35.0 or later. 37 | 38 | ## Set-Up 39 | 40 | If you don't already have a Serverless Framework account, create a new account at [https://app.serverless.com](https://app.serverless.com). 41 | 42 | If you don't have existing Serverless Framework Services, follow the [Getting Started with the Serverless Framework and AWS](../../getting-started.md) guide. This will help you get a Serverless Framework Service deployed to AWS, and enabled with the Dashboard. 43 | 44 | If you have existing Serverless Framework Services, in the directory with your Service's `serverless.yml` file, run the `serverless` command. This will walk you through the setup process, including setting up your AWS account credentials and creating an organization and application from the Dashboard. Once completed, you'll notice that the `org` and `app` fields will be added to your `serverless.yml` to indicate the org/app to which this service belongs. 45 | 46 | You can also add the configuration manually to your `serverless.yml` files within your Serverless Framework Services to connect to the Dashboard. 47 | 48 | ```YAML 49 | 50 | org: # Your Serverless Framework Org name (e.g. acme-inc) 51 | app: # A parent namespce for this Service and related Services App name (e.g. mobile-app), to improve Serverless Framework Dashboard organization 52 | 53 | ``` 54 | 55 | You must deploy your Service with the above configuration in your YAML file to have it show in the Dashboard. Run serverless deploy to do this. 56 | 57 | If you want to enable Observability (metrics, traces, logs) for your AWS Lambda functions within Serverless Framework Dashboard, you will have to add the following in the stages block of your serverless.yml: 58 | 59 | ```yml 60 | stages: 61 | prod: 62 | observability: true # turn on observability in the "prod" Stage. 63 | dev: 64 | observability: true # turn on observability in the "dev" Stage. 65 | default: 66 | observability: false # turn off observability for all other Stages. 67 | ``` 68 | 69 | To set up Observability, Serverless Framework will automatically create an AWS IAM Role within the AWS account you deployed to, giving Serverless Inc permission to AWS Cloudwatch and more. [You can transparently see the permissions this role requires in Github](https://github.com/serverless/console/blob/main/instrumentation/aws/iam-role-cfn-template.yaml) 70 | -------------------------------------------------------------------------------- /docs/guides/dashboard/cicd/README.md: -------------------------------------------------------------------------------- 1 | 17 | 18 | 19 | 20 | ### [Read this on the main serverless docs site](https://serverless.com/framework/docs/guides/cicd/) 21 | 22 | 23 | 24 | # CI/CD 25 | 26 | Serverless CI/CD enables you to automatically test and deploy services from Github. 27 | 28 | ## Requirements 29 | 30 | Before you setup your CI/CD workflow, make sure you meet the following requirements: 31 | 32 | 1. **Must have your Serverless Framework project checked into Github**. Currently Github and BitBucket are supported as a VCS providers. Your project, including the serverless.yml file, must be checked into a repo. 33 | 2. **Must be deployed on AWS**. The dashboard currently only supports AWS as a cloud service provider. Other cloud service providers are a work in progress. 34 | 3. **Must use the Node or Python runtime**. Currently only Serverless Framework projects using the Node or Python runtimes are supported. Other runtimes may work but are not officially supported. 35 | 36 | ## Getting Started in 3 steps 37 | 38 | ### Step 1: Link your AWS Account 39 | 40 | As is the case with deployments from the Serverless Framework CLI, Serverless CI/CD requires access to your AWS Account in order to deploy your services. To make this process as secure as possible, Serverless CI/CD will generate short-lived credentials to your AWS account on each deployment. This is done by creating an AWS Access Role in your AWS account and associating it with a Provider in the Serverless Framework Dashboard. 41 | 42 | If you’ve already set up an AWS Access Role with a Provider, you can skip this step. Otherwise, please go through the instructions on our [Provider documentation page](../dashboard/providers.md) to help set one up. 43 | 44 | ### Step 2: Connect to Github 45 | 46 | 1. Login to [https://app.serverless.com/](https://app.serverless.com/). 47 | 2. Navigate to the app which contains the service you want to deploy and click the menu icon (...) on the right hand side and choose "settings" 48 | 3. In the “connect to git” section, click “connect to Github” or "connect to BitBucket" and follow the instructions to authenticate and install the Serverless Framework app. 49 | 4. In the “repository settings” section, select the repository and base directory if needed containing your service. The service name specified in the serverless.yml must match the service you are configuring. 50 | 5. In the "branch deploys" section, you can choose to map a specific branch in your repo to the correct stage. When code is merged to that branch it then deploys using that stage and its associated Provider (and parameters). 51 | 6. Changes will be automatically saved when you make them 52 | 53 | That’s it! You do not have to create any configuration files in your repository or define your test commands or your 54 | deployment commands. 55 | 56 | Your service will now deploy from the master branch and you’ll see all the test results, logs, safeguard pass/fail 57 | status, and deployment details. 58 | 59 | ### Step 3: Deploy from a Github branch 60 | 61 | Now that you are setup to deploy all changes to the master branch to the dev stage for your service, go ahead and make a 62 | commit and navigate to “deployments” in the dashboard. You will be able to see the new test and deployment. 63 | -------------------------------------------------------------------------------- /docs/guides/dashboard/cicd/best-practices.md: -------------------------------------------------------------------------------- 1 | 14 | 15 | 16 | 17 | ### [Read this on the main serverless docs site](https://serverless.com/framework/docs/guides/cicd/best-practices/) 18 | 19 | 20 | 21 | # Serverless CI/CD Best Practices 22 | 23 | Serverless Framework provides a lot of capabilities out of the box to help you manage and deploy 24 | your services. As your teams grow and the number of services grow, it can be difficult to know 25 | the best way to organize your services for scale. 26 | 27 | To help you manage and deploy your services at scale, check out the 28 | [Serverless CI/CD Workflow Guide](https://www.serverless.com/guide-ci-cd) for our recommendations 29 | on organizing your apps, services, repos and automating your release process. 30 | -------------------------------------------------------------------------------- /docs/guides/dashboard/cicd/branch-deployments.md: -------------------------------------------------------------------------------- 1 | 15 | 16 | 17 | 18 | ### [Read this on the main serverless docs site](https://serverless.com/framework/docs/guides/cicd/branch-deployments/) 19 | 20 | 21 | 22 | # Branch Deployments 23 | 24 | Branch deployments enable you to automatically deploy a service to a stage from a branch in your Github repository. Every commit to this branch is automatically deployed. 25 | 26 | ## Adding a branch deployment 27 | 28 | To add a new branch deployment, in the "branch deploys" section of the CI/CD settings, select the Github branch containing the `serverless.yml` from the "source branch" column for each "target stage". Commits from the "source branch" will automatically be deployed to the "target stage". 29 | 30 | ## Add a stage to a branch deployment 31 | 32 | You can assign a stage to each branch deployment, but ensure that a valid provider is set for this service. 33 | -------------------------------------------------------------------------------- /docs/guides/dashboard/cicd/custom-scripts.md: -------------------------------------------------------------------------------- 1 | 14 | 15 | 16 | 17 | ### [Read this on the main serverless docs site](https://serverless.com/framework/docs/guides/cicd/custom-scripts/) 18 | 19 | 20 | 21 | # Custom scripts 22 | 23 | Serverless Framework runs three primary operations on your repository when you have CI/CD configured: (1) install NPM packages via `npm install`, (2) run tests, if present, with `npm test`, and (3) deploy your service using `sls deploy`. You can run custom scripts before or after each of these steps if you need to customize the pipeline further. 24 | 25 | To run custom scripts before & after NPM install and running tests, use the lifecycle hooks built into `scripts` of your `package.json` file. The `preinstall`, `postinstall`, `pretest`, and `posttest`, scripts are run automatically at each of these steps. 26 | 27 | To run custom scripts before or after deployment, you can use the [serverless-plugin-scripts](https://github.com/mvila/serverless-plugin-scripts) plugin to run the scripts at various points of the `serverless deploy` lifecycle, including before deployment and on finalize. 28 | 29 | **Before npm install** 30 | 31 | To run a script before `npm install`, set the script in `preinstall` in your `package.json`. 32 | 33 | ```json 34 | { 35 | "name": "demo-serverless", 36 | "version": "1.0.0", 37 | "scripts": { 38 | "preinstall": "" 39 | } 40 | } 41 | ``` 42 | 43 | **After npm install** 44 | 45 | To run a script after `npm install`, set the script in `postinstall` in your `package.json`. 46 | 47 | ```json 48 | { 49 | "name": "demo-serverless", 50 | "version": "1.0.0", 51 | "scripts": { 52 | "postinstall": "" 53 | } 54 | } 55 | ``` 56 | 57 | **Before npm test** 58 | 59 | To run a script before `npm test`, set the script in `pretest` in your `package.json`. 60 | 61 | ```json 62 | { 63 | "name": "demo-serverless", 64 | "version": "1.0.0", 65 | "scripts": { 66 | "pretest": "" 67 | } 68 | } 69 | ``` 70 | 71 | **After npm test** 72 | 73 | To run a script after `npm test`, set the script in `posttest` in your `package.json`. 74 | 75 | ```json 76 | { 77 | "name": "demo-serverless", 78 | "version": "1.0.0", 79 | "scripts": { 80 | "posttest": "" 81 | } 82 | } 83 | ``` 84 | 85 | **Before serverless deploy** 86 | 87 | To run a script before `serverless deploy` starts the deployment add this to your `serverless.yml`. 88 | 89 | ```yaml 90 | plugins: 91 | - serverless-plugin-scripts 92 | custom: 93 | scripts: 94 | hooks: 95 | 'before:deploy:deploy': 96 | ``` 97 | 98 | **After serverless deploy** 99 | 100 | To run a script after `serverless deploy` completes a deployment add this to your `serverless.yml`. 101 | 102 | ```yaml 103 | plugins: 104 | - serverless-plugin-scripts 105 | custom: 106 | scripts: 107 | hooks: 108 | 'deploy:finalize': 109 | ``` 110 | 111 | ## Additional lifecycle hooks 112 | 113 | NPM provide additional lifecycle hooks you can run as well, additional documentation can be found here, [https://docs.npmjs.com/misc/scripts](https://docs.npmjs.com/misc/scripts). 114 | 115 | Serverless Framework provides additional lifecycle hooks as “serverless deploy” is running, you can find more information about additional hooks in the [serverless-plugin-scripts](https://github.com/mvila/serverless-plugin-scripts) docs. 116 | -------------------------------------------------------------------------------- /docs/guides/dashboard/cicd/faq.md: -------------------------------------------------------------------------------- 1 | 16 | 17 | 18 | 19 | ### [Read this on the main serverless docs site](https://serverless.com/framework/docs/guides/cicd/faq/) 20 | 21 | 22 | 23 | # Frequently Asked Questions 24 | 25 | ## Is there a free tier? 26 | 27 | Yes. No credit card required, just sign up. Free tier only supports public 28 | repos. Upgrade to a paid tier to use CI/CD with private repos. 29 | 30 | ## Do you support preview deployments from pull requests? 31 | 32 | Yes! You can add preview deployments to your CI/CD Settings. This will 33 | automatically test and deploy your service from a pull request. The results will 34 | be posted in the pull request status. You can also setup auto deletion of 35 | deployed resources for preview deployments so that “sls remove” is automatically 36 | run when your feature branch is merged and deleted. 37 | 38 | ## Can I deploy for multiple branches? 39 | 40 | Yes! Add other branch deployments to configure from any branch to any stage. We 41 | see a lot of folks deploy to a staging environment from the master branch, and 42 | to production from a production branch. 43 | 44 | ## Can I use different AWS Accounts for each Stage? 45 | 46 | Yes! You can use deployment profiles to add as many AWS Accounts as you would 47 | like, and map them to individual stages in your application. 48 | 49 | ## Is it just for Serverless Framework? 50 | 51 | Yes! Serverless CI/CD is designed around the Serverless Framework to provide a 52 | seamless experience for developers. Anything you can deploy with the Serverless 53 | Framework you can deploy with Serverless CI/CD. The Serverless Framework is 54 | extensible with Plugins , so it works with a broad range of services. 55 | 56 | ## Are all runtimes supported? 57 | 58 | Only the most popular runtimes, Node and Python, are currently supported. These 59 | two runtimes account for about 90% of all serverless services. Support for other 60 | runtimes is coming soon. 61 | 62 | ## Does Serverless CI/CD support AWS, Azure and GCP? 63 | 64 | Only AWS is supported at this time; however, support for other cloud service 65 | providers is coming. 66 | 67 | ## Do I need to host, manage, or operate any agents? 68 | 69 | Nope! Serverless CI/CD is a 100% SaaS and managed for you. 70 | -------------------------------------------------------------------------------- /docs/guides/dashboard/cicd/mono-repo.md: -------------------------------------------------------------------------------- 1 | 14 | 15 | 16 | 17 | ### [Read this on the main serverless docs site](https://serverless.com/framework/docs/guides/cicd/mono-repo/) 18 | 19 | 20 | 21 | # Mono-repo support using Trigger Directories 22 | 23 | When first getting started with a Serverless Framework project it is common to have a single `serverless.yml` file in a single Github repo. As the project grows it is common to split up the single mono-service into micro-services in individual `serverless.yml` files by placing them into different directories in the same repo. In some cases, another directory may exist (e.g. `/shared`) which may contain shared libraries used by those services. 24 | 25 | As an example, you may end up with a directory structure like this: 26 | 27 | - `/service1` 28 | - `/service2` 29 | - `/shared` 30 | 31 | In this case, there is a `/service1/serverless.yml` and a `/service2/serverless.yml`. The services in those two directories may have a dependency on code defined in the `/shared` directory. We want to avoid redeploying ALL services every time any of the files change. Instead, we want to run tests and redeploy when the relevant changes are made, in particular: 32 | 33 | - If there is a change in `/service1` only deploy `/service1/serverless.yml`. 34 | - If there is a change in `/service2` only deploy `/service2/serverless.yml`. 35 | - If there is a change in `/shared` deploy both `/service1/serverless.yml` and `/service2/serverless.yml`. 36 | 37 | In your Serverless CI/CD settings there is a section called “Trigger Directories”. This enables you to limit the changes in a git commit which trigger a deployment by identifying the directories containing the relevant changes. A deployment will occur only if changes in the specified directories are identified. If the changes are in a different directory, the service will not be deployed. 38 | 39 | By default the option **Always trigger a deployment** is checked, which causes ALL changes in the repository to trigger a deployment, which means that all services will get redeployed. Instead we want to uncheck the option and only trigger deployments if changes are detected in the relevant directories. 40 | 41 | Once unchecked, the base directory is added by default. This means that only changes in `/service1` will cause `/service1/serverless.yml` to be deployed, and `/service2` for `/service2/serverless.yml` respectively. Additionally we also want to deploy both services if changes in `/shared` are detected. As such, we’ll add `./shared` as a trigger directory to both services. 42 | 43 | With this configuration the changes in `/service2` will not cause `/service1` to be redeployed, and vice-versa and changes to `/shared` will result in both services getting deployed. 44 | -------------------------------------------------------------------------------- /docs/guides/dashboard/cicd/notifications.md: -------------------------------------------------------------------------------- 1 | 16 | 17 | 18 | 19 | ### [Read this on the main serverless docs site](https://serverless.com/framework/docs/guides/cicd/notifications/) 20 | 21 | 22 | 23 | # Notifications 24 | 25 | Serverless Framework has integrated Slack, email, SNS and webhook notifications for CI/CD status updates. 26 | 27 | Notifications for CI/CD events are not setup by default, so you will not get notified of deployments starting, 28 | completing of failing. These notifications must be added manually. 29 | 30 | Notifications for CI/CD events are configured the same way as they are for [monitoring](../../../guides/dashboard/cicd/notifications.md). 31 | 32 | You can subscribe to three different CI/CD events in the "Add notifications" dialog: 33 | 34 | - deployment started 35 | - deployment succeeded 36 | - deployment failed 37 | 38 | These three events apply to both branch deployments and preview deployments. 39 | -------------------------------------------------------------------------------- /docs/guides/dashboard/cicd/preview-deployments.md: -------------------------------------------------------------------------------- 1 | 15 | 16 | 17 | 18 | ### [Read this on the main serverless docs site](https://serverless.com/framework/docs/guides/cicd/preview-deployments/) 19 | 20 | 21 | 22 | # Preview Deployment 23 | 24 | Preview deployments enable you to deploy on every pull request. As a part of the pull request review process, it is helpful to have an instance of your serverless application deployed. A pull request will trigger the deployment and all subsequent commits on that branch will also be deployed. 25 | 26 | To enable preview deployments, check "Enable preview deploys" in the "preview deploys" section of the CI/CD Settings. 27 | 28 | You must also select the "target pull request branch", a branch from your Github repository. Only pull requests to this branch will be deployed. 29 | 30 | ## Using branch name as stages 31 | 32 | Each deployment must target a specific stage and use a specific deployment profile. By default, the stage value will be set to the name of the branch. 33 | 34 | In the "preview deploys" section, under "advanced settings", you can change the "stage" option. The default is "use branch name as stage", but you can also select a specific stage to target as well. However, if you use any option other than "use branch name as stage", then two different pull requests will be deployed to the same stage. 35 | 36 | The deployment profile associated with the "default" stage in your application will be used if you select "use branch name as stage". If you select a specific stage, then the deployment profile associated with that stage will be used. 37 | 38 | As development teams, we often have multiple pull requests and branches open at once. If we deploy those branches to the same stage then the deployments will override each other. 39 | 40 | To avoid this collision, you have the convenient option to "use branch name as stage", which ensures that each pull request will deploy to a unique stage. Since the stage is not pre-configured and may not yet exist at the time of deployment, the default deployment profile will be used. In this case, ensure that the default deployment profile is configured with an [AWS Access Role](../../../guides/dashboard/providers.md). 41 | 42 | If you use the "use branch name as stage", you may also want to reference the branch name in your configuration using [Variables](/framework/docs/guides/variables/). Since the stage name matches the branch name, you can use the `${sls:stage}` variable in your `serverless.yml` to reference the stage name, which will match the branch name. 43 | 44 | Branch names may also include characters such as `/` which are invalid characters for stage names. Invalid characters are replaced with `-` in Serverless CI/CD. For example, a branch `feature/ph-api` will be normalized as `feature-ph-api`. 45 | 46 | ## Automatically deleting preview deployments (recommended) 47 | 48 | The recommended method for deleting preview service instances is to select "Destroy stage and resources when branch is deleted". If the changes in the PR are accepted then they will be merged and then the branch is deleted. If the changes are rejected the branch is also deleted. Whenever the branch is deleted, Serverless Framework will automatically run `sls remove` on this service instance. 49 | 50 | ## Manually deleting preview deployments 51 | 52 | Alternatively you can delete service via the CLI. To delete the service instance you must run `sls remove` from the CLI in the repository containing the `serverless.yml` file. The `org`, `app`, `stage`, and `region` must all match the service instance you intend to delete. 53 | -------------------------------------------------------------------------------- /docs/guides/dashboard/cicd/private-packages.md: -------------------------------------------------------------------------------- 1 | 15 | 16 | 17 | 18 | ### [Read this on the main serverless docs site](https://serverless.com/framework/docs/guides/cicd/private-packages/) 19 | 20 | 21 | 22 | # Using private package managers 23 | 24 | If your Serverless Framework project has a dependency on a private package manager, like NPM, you will need the CI/CD 25 | service to authenticate with the private package manager service. 26 | 27 | For example, if you are using NPM follow the "[Using private packages in a CI/CD workflow](https://docs.npmjs.com/using-private-packages-in-a-ci-cd-workflow)" 28 | guide to create an authentication token. Following this process you will obtain a token to use as an environment 29 | variable. Other private package managers for NPM or other runtimes (e.g. Python) also typically provide a method for 30 | authentication using environment variables in a CI/CD environment. 31 | 32 | To set an environment variable use the [Parameters](../../../guides/parameters.md) feature and create a variable called 33 | `NPM_TOKEN` containing your private registry token. Parameters defined in the deployment profiles associated with the 34 | application and stage are loaded in the Serverless CI/CD service as environment variables. 35 | -------------------------------------------------------------------------------- /docs/guides/dashboard/cicd/running-in-your-own-cicd.md: -------------------------------------------------------------------------------- 1 | 17 | 18 | 19 | 20 | ### [Read this on the main serverless docs site](https://serverless.com/framework/docs/guides/cicd/running-in-your-own-cicd/) 21 | 22 | 23 | 24 | # Deploy in your own CI/CD 25 | 26 | If you have an existing CI/CD service and you do not wish to use the CI/CD service provided by Serverless, you can still deploy from your existing CI/CD service while using the other features of the Serverless Framework Dashboard. 27 | 28 | Configuring your CI/CD pipeline is split between configuring the environment and the build step. Configuring the environment only needs to be performed once across all service deployments while the build step must be configured to run on each deploy. 29 | 30 | ## Configure the environment 31 | 32 | Complete the steps in this guide to install the Serverless Framework open-source CLI and configure authentication. 33 | 34 | ### Install Node.js and NPM 35 | 36 | Your CI/CD environment must have Node.js and NPM installed as they are prerequisites for the Serverless Framework CLI. Follow the instructions below to install Node.js and NPM. You must install **version 6.x or later** of Node.js. 37 | 38 | [https://nodejs.org/en/download/package-manager/](https://nodejs.org/en/download/package-manager/) 39 | 40 | ### Install the Serverless Framework open-source CLI 41 | 42 | In your CI/CD environment install Serverless Framework open-source CLI as it is later used to perform the deploy. 43 | 44 | ```sh 45 | npm install -g serverless 46 | ``` 47 | 48 | ### Create an Access Key in the Serverless Framework Dashboard 49 | 50 | When using the the Serverless Framework open-source CLI with Serverless Framework Dashboard locally you must first authenticate with the `serverless login` command. The `serverless login` command will open up a browser where you are prompted for your Serverless Framework Dashboard username and password. Since your CI/CD environment is non-interactive, you will need to authenticate the CLI using an access token instead. 51 | 52 | Follow these steps to create an access token: 53 | 54 | 1. Login to the dashboard at https://app.serverless.com/ 55 | 2. Open the username dropdown in the upper-right corner. 56 | 3. Select "personal access keys" from the dropdown. 57 | 4. Click “+ add” button. 58 | 5. Provide a name and press “Create” 59 | 6. You will be presented with the access key on the new page. 60 | 61 | **Note**: The access token has permission to the org; however, it is associated with your account. If your account is deleted, then the access token will be revoked too. 62 | 63 | ### Configure environment variables 64 | 65 | In the previous step you obtained an access token from the Serverless Framework Dashboard which you will now set in your CI/CD environment so that the Serverless Framework open-source CLI can authenticate with the Serverless Framework Dashboard. 66 | 67 | Set the following environment variable in your CI/CD environment: 68 | 69 | - `SERVERLESS_ACCESS_KEY`: Your Serverless Framework Dashboard access token from previous step. 70 | 71 | ## Configure the build step 72 | 73 | Your CI/CD pipeline is now ready to deploy the service. This step should be configured to run on every deploy. 74 | 75 | ```sh 76 | npm install # installs all plugins and packages 77 | serverless deploy # deploys your service 78 | ``` 79 | -------------------------------------------------------------------------------- /docs/guides/dashboard/cicd/running-tests.md: -------------------------------------------------------------------------------- 1 | 16 | 17 | 18 | 19 | ### [Read this on the main serverless docs site](https://serverless.com/framework/docs/guides/cicd/running-tests/) 20 | 21 | 22 | 23 | # Running Tests 24 | 25 | The Serverless Framework will automatically run tests for each deployment by running `npm test`. The tests must pass, return `0`, before the service is deployed. If the tests fail, then the service will not be deployed. 26 | 27 | The tests only run if a `test` script is present in the `package.json` file, like in the example below: 28 | 29 | ```json 30 | { 31 | "name": "my-serverless-project", 32 | "version": "1.0.0", 33 | "description": "", 34 | "main": "index.js", 35 | "scripts": { 36 | "test": "echo \"Error: no test specified\" && exit 1" 37 | }, 38 | "author": "", 39 | "license": "ISC" 40 | } 41 | ``` 42 | 43 | The tests will be skipped if the `npm test` command returns `Error: no test specified`. This is the response from `npm` if no `test` script is defined. It is also the default value of the `test` script when you initialize a new package.json via `npm init`. 44 | 45 | ## Running Node tests 46 | 47 | If you are using Node for your runtime, then all the dependencies will automatically be installed using `npm install` before tests are run. 48 | 49 | Update the `tests` script to run your node test suite (e.g. `mocha`). 50 | 51 | ## Running Python tests 52 | 53 | If you are using Python we recommend using the [serverless-python-requirements](https://github.com/UnitedIncome/serverless-python-requirements) plugin to install the dependencies from `requirements.txt`. 54 | 55 | If you are not using the serverless-python-requirements plugin, then you can install the requirements by adding the `postinstall` script to `package.json`. 56 | 57 | ```json 58 | { 59 | "name": "demo-python", 60 | "version": "1.0.0", 61 | "scripts": { 62 | "postinstall": "pip3 install -r requirements.txt", 63 | "test": "pytest" 64 | }, 65 | "devDependencies": { 66 | "serverless-python-requirements": "^5.0.1" 67 | } 68 | } 69 | ``` 70 | 71 | You must update the `test` script in `package.json` to run your Python tests suite (e.g. `pytest`). 72 | -------------------------------------------------------------------------------- /docs/guides/dashboard/cicd/troubleshooting.md: -------------------------------------------------------------------------------- 1 | 15 | 16 | 17 | 18 | ### [Read this on the main serverless docs site](https://serverless.com/framework/docs/guides/cicd/troubleshooting/) 19 | 20 | 21 | 22 | # Troubleshooting CI/CD Settings 23 | 24 | In the setup process the Serverless Framework will authenticate you with Github with the OAuth application flow, and install the Serverless Github application to access the repositories. If there are problems with either of these, you can reset the state of the integration. 25 | 26 | ## Reset the OAuth access 27 | 28 | 1. Go to the [Authorized GitHub Apps in Github](https://github.com/settings/apps/authorizations) and click "Revoke" next to "Serverless". This will revoke the keys used by the Serverless Framework Dashboard to access Github on your behalf. 29 | 2. Go through Steps 1-4 above to access the deployment settings. You will be prompted to "connect github repository". Authenticate with Github again. 30 | 3. You will be prompted with the install instructions. If you did not uninstall the Github application, then you do not need to update these settings. You can close the window. 31 | 4. You will need to refresh the deployment settings page. 32 | 33 | ## Configure or reset the installed application 34 | 35 | 1. Go to the [Installed Github Apps in Github](https://github.com/settings/installations) and click “Configure” for the “Serverless” app. Here you can update the access settings or uninstall the application. 36 | 2. You can update the “Repository access” settings, to make sure that Serverless has access to the repositories you want to deploy. 37 | 3. You can also Uninstall the application. 38 | 4. If you uninstall the application, then you can go to follow steps 1-4 to get to the deployment settings page. Refresh this page. 39 | 5. Below the “repository” dropdown the message “If you do not see your repository, install the Serverless application in Github” will be displayed. Follow the “install the Serverless application” link to reinstall the Serverless Github application. 40 | -------------------------------------------------------------------------------- /docs/guides/dashboard/concepts.md: -------------------------------------------------------------------------------- 1 | 7 | 8 | 9 | 10 | ### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/guides/orgs/) 11 | 12 | 13 | 14 | # Orgs & Members 15 | 16 | ## Creating an Org 17 | 18 | An org is a unique tenant within Serverless Framework Dashboard. When you sign 19 | up, Serverless Framework Dashboard generates a default org name which you can 20 | change. You can create any number of orgs. Members can be added to an org, and a 21 | member can belong to multiple orgs. 22 | 23 | ## Adding Team Members 24 | 25 | Serverless Framework Dashboard currently supports the following basic roles 26 | which are shared across your org. 27 | 28 | - **Owner** - Owner of the account. Can add other contributors and access the 29 | Org Settings. Only one owner per account can be present. 30 | - **Contributor** - Contributors can use all of Serverless Framework Dashboard 31 | but can not add other users or access the Org Settings directly. 32 | 33 | ## Changing Org Name 34 | 35 | Org names can be changed from the Org Settings section of Serverless Framework 36 | Dashboard. Keep in mind that org names do need to be globally unique across 37 | Serverless, so your desired organization name may not be available. 38 | 39 | ## Using Serverless Dashboard Orgs 40 | 41 | If you have an existing Serverless Framework Dashboard org and you log into 42 | Serverless Framework Dashboard you will automatically start using your existing 43 | org. Additionally if you are a member of a Serverless Framework Dashboard org 44 | you will automatically be made a member of that org in Serverless Framework 45 | Dashboard. 46 | -------------------------------------------------------------------------------- /docs/guides/dashboard/monitoring/metrics.md: -------------------------------------------------------------------------------- 1 | 14 | 15 | 16 | 17 | ### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/guides/monitoring/metrics/) 18 | 19 | 20 | 21 | # Metrics 22 | 23 | Metrics is a Serverless Dashboard feature which enables viewing metrics across 24 | AWS Accounts and Lambda functions. 25 | 26 | To get started you need to [add an AWS Account integration](./README.md). 27 | 28 | Once instrumentation is enabled, go to the **Metrics** page to view all of your 29 | AWS Lambda function metrics including durations, invocations, and event counts. 30 | 31 | Currently Metrics are supported on the Node.js 12+ and Python 3.8+ runtimes on 32 | AWS Lambda only. Support for other runtimes is coming soon. 33 | 34 | ## Metric Aggregation 35 | 36 | Metrics are automatically aggregated on the charts over an interval as small as 37 | 1 minute, and as large as 1 day, depending on the time interval you select. As 38 | such, the metrics are only available in aggregate, not as individual data 39 | points. 40 | 41 | ## Available Charts 42 | 43 | The metrics page features a number of charts, including Invocations, Uncaught 44 | Errors, and more. The title of each chart provides a tooltip with a detailed 45 | description of the metric. 46 | 47 | You can also hover over individual bars to get a detailed breakdown of the 48 | metrics for that point in time. 49 | 50 | Majority of the charts are interactive. You can click on the chart, which will 51 | send you to the Trace Explorer to view the full chart and individual traces 52 | which meat the same filter criteria. 53 | 54 | ## Saving Views 55 | 56 | From the title, you can select to create a new custom view of the Metrics. All 57 | the filters will be saved with that view. This enables you to create views for 58 | specific use cases. When filters are updated, they are saved in the view. 59 | 60 | ## Filters 61 | 62 | Applying filters to the metrics view allows you to narrow in on 63 | specific functions, or use cases that are of interest to you. Filters can be 64 | saved as a shared views to collaborate with team mates on specific searches. 65 | 66 | - **Resources** - Filter for specific AWS Resources in any of the integrated 67 | AWS Accounts. Currently this only supports AWS Lambda, but other AWS resources 68 | will be made available soon. 69 | - **Namespace** - Namespaces are configured on individual AWS Lambda functions 70 | on the AWS Integrations page. Filtering by namespace allows you to filter the 71 | metrics based on the namespaces that were configured on the functions for which 72 | the metric applies. 73 | - **Environment** - Like namespaces, environments are configured on the AWS 74 | Integration page for each AWS Lambda function. The are also automatically 75 | determined from the CloudFormation stack if applicable. Filtering by environment 76 | allows you to filter the metrics based on the environments that were configured 77 | on the functions for which the metric applies. 78 | - **Region** - Region is the specific AWS Region of the Lambda function. 79 | - **AWS Account** - If you have multiple AWS Account integrations in your 80 | org, you can filter for metrics for individual AWS Accounts. 81 | - **Events** - Individual invocations may produce multiple errors or warnings. 82 | The Serverless SDK may also produce errors and warnings. Filtering by Events 83 | enables filtering for invocations which include any of the selected Event types. 84 | You can find more details about Event types on the [Trace Explorer](./traces#event-types.md). 85 | - **Cold start** - Filters for metrics on AWS Lambda invocations that were a 86 | cold start. 87 | - **Duration** - Filters based on the AWS Lambda response duration. 88 | - **Custom Tags** - Filters for metrics on invocations that had the provided 89 | custom tags. Custom tags on traces, errors, and warnings are all queried. Use 90 | the [Node.js](./sdk/nodejs.md) or [Python](./sdk/python.md) Serverless SDK to 91 | set custom tags. 92 | -------------------------------------------------------------------------------- /docs/guides/dashboard/monitoring/sdk/README.md: -------------------------------------------------------------------------------- 1 | 15 | 16 | 17 | 18 | ### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/guides/sdk/) 19 | 20 | 21 | 22 | # Serverless Framework SDK 23 | 24 | When using the Serverless Framework Dashboard, the Framework automatically injects the `serverless_sdk` module into your lambda package and wraps your lambda to automatically instrument all the monitoring features in the Dashboard. 25 | 26 | It also has certain features you can use directly in your lambda such as capturing an error in the Dashboard without causing your lambda to error and custom function spans. 27 | 28 | [NodeJS Documentation](./nodejs.md) 29 | 30 | [Python Documentation](./python.md) 31 | 32 | ## Advanced Span Configuration 33 | 34 | For most of the SDK configuration, like turning on/off span collection, follow the 35 | [Monitoring Configuration](../README.md/#configuration) instructions to modify your 36 | serverless.yml appropriately. 37 | 38 | If needed, you can configure HTTP span collection with the following environment variables 39 | 40 | - `SERVERLESS_ENTERPRISE_SPANS_CAPTURE_HOSTS` - `*` by default. Set to a comma delimited list of host names to capture. 41 | - `SERVERLESS_ENTERPRISE_SPANS_IGNORE_HOSTS` - not set by default. Set to comma delimited list of hostnames to not capture. 42 | - `SERVERLESS_ENTERPRISE_SPANS_CAPTURE_AWS_SDK_HTTP` - not set by default. Set to any value to also capture HTTP spans for requests from `botocore` or `aws-sdk`. 43 | -------------------------------------------------------------------------------- /docs/guides/dashboard/monitoring/traces.md: -------------------------------------------------------------------------------- 1 | 16 | 17 | 18 | 19 | ### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/guides/monitoring/trace-explorer/) 20 | 21 | 22 | 23 | # Traces 24 | 25 | Traces, Spans, Logs, and Events are captured and made available in Trace 26 | Explorer for your AWS Lambda functions when [Instrumentation](./README.md#set-up-via-serverless-framework-dashboard-ui) 27 | is enabled. 28 | 29 | Serverless Dashboard provides a set of tools to analyzing Traces. 30 | 31 | ## Trace Explorer List 32 | 33 | Similar to the [Metrics View](./metrics.md), the Trace Explorer provides a 34 | starting point for troubleshooting AWS Lambda function invocations across your 35 | org. You can use the rich filters to narrow in on errors, warnings, and 36 | performance issues across all of your AWS Lambda functions across your org. 37 | 38 | ## Filters 39 | 40 | Filtering allows you to narrow in on particular behavior and time frame for 41 | to isolate invocations. You can filter on: 42 | 43 | - **Event Types** - Errors and Warnings can be captured in the trace, these 44 | includes user defined as well as SDK defined errors and warnings. More details 45 | on each Event type is available below. 46 | - **Event Messages** - When an Event like an error or warning is captured, a 47 | message string is saved with the Event. You can filter for the Traces based on 48 | the Event messages that were captured in the trace. Traces are filtered if any 49 | of the Events in the Trace contained the message string. 50 | - **Resource** - You can select the specific resource by AWS ARN, like a 51 | specific Lambda function. 52 | - **Environment**, **Namespace** - These properties are inferred from the 53 | CloudFormation stack when Instrumentation is added, or they are set manually 54 | on the Integration settings page. Once set, you can filter the traces based on 55 | these properties set on the function. 56 | - **AWS Account**, **Region** - Serverless Dashboard collects information for all 57 | instrumented Lambda functions across AWS accounts and regions; you can filter 58 | on any of these properties. 59 | - **Timeframe** - Any timeframe within the last 30 days can be used. 60 | 61 | ## Event Types 62 | 63 | - **Uncaught Error** (`ERROR_TYPE_UNCAUGHT`) - The Lambda function handler had a 64 | fatal error and caused the invocation to fail. 65 | - **Caught Error** (`ERROR_TYPE_CAUGHT_USER`) - The Lambda function handler had 66 | an error that was captured using the SDK, structured logging library (e.g. Pino, 67 | AWS Lambda PowerTools, Winston), or standard out (e.g. `console.error`). 68 | - **Warning** (`WARNING_TYPE_USER`) - The Lambda function handler had a warning 69 | that was captured using the SDK, structured logging library (e.g. Pino, AWS 70 | Lambda PowerTools, Winston), or standard out (e.g. `console.warn`). 71 | - **SDK Error** (`ERROR_TYPE_CAUGHT_SDK_USER`) - An SDK usage error that was 72 | reported due to misuse of the SDK. These errors do not cause handler failures, 73 | but misusage of the SDK may result in partial collection. For example, using the 74 | `setTag` method with invalid inputs will result in this type of error, and the 75 | tag will not be set. 76 | - **SDK Warning** (`WARNING_TYPE_SDK_USER`) - A warning reported by the SDK due 77 | to user misuse in the handler, but not due to misuse of the SDK. For example, if 78 | both a callback and Promise resolution is attached this will cause unwanted 79 | side-effects on the SDK. 80 | 81 | ## Trace Details 82 | 83 | Trace Details provides a way to look at the details of an individual AWS Lambda 84 | Invocation trace, including the spans, tags, logs, and events. 85 | 86 | The Trace details are deep-linked so you can easily share the URL with your 87 | team when collaboratively troubleshooting. 88 | 89 | The pane on the right, the Inspector, presents the details about the Trace. If 90 | a Span, or an Events are selected from the timeline, then the Inspector will 91 | show details about the selected item. 92 | 93 | The Inspector for the trace will present details about the trace as tags. These 94 | tags include information about the runtime, like `Cold Start`, `Request ID`, 95 | and `Arch`, as well as metrics like `Memory Used`, `Billed ms`, `Invoke`. Check 96 | out the tooltips for details on each of the tags. 97 | 98 | ### Spans 99 | 100 | A Trace contains a set of Spans associated with and displayed in the style of a 101 | Gantt chart. This chart provides you with context for when, and how long various 102 | subsequent interactions took. 103 | 104 | A span can be selected from the timeline to view the details of the span in the 105 | Inspector. 106 | 107 | ### Logs 108 | 109 | Logs are also collected and made available in the Trace details. To view the 110 | logs for the Lambda invocation, select the root span, `aws.lambda`. 111 | 112 | If the logs are structured and formatted as JSON, they will be parsed and 113 | displayed with pretty formatting. 114 | 115 | ### Events 116 | 117 | Events, like Spans, are displayed on the timeline. Events can be selected to 118 | view the details. 119 | 120 | Events include a `name`, `message`, and `stack` when available. The Node.js and 121 | Python Serverless SDKs capture the stacktraces for all requests when possible. 122 | It also captures `Error` objects, so the `name`, `message`, and `stack` from the 123 | `Error` are made available as an error in the Inspector. 124 | -------------------------------------------------------------------------------- /docs/guides/dashboard/output-variables.md: -------------------------------------------------------------------------------- 1 | 7 | 8 | 9 | 10 | ### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/guides/output-variables/) 11 | 12 | 13 | 14 | # Outputs 15 | 16 | The Serverless Framework Dashboard helps you refactor large serverless applications by decoupling the shared services from the dependent services. The new outputs feature allows you to define output key/values in a `serverless.yml` and then reference those key/values in other `serverless.yml` files. The key/values are published to Serverless Framework Dashboard when you deploy, and they are loaded in other services when they are deployed. 17 | 18 | ## Define outputs for shared services 19 | 20 | Define new outputs by adding a dictionary (key/value pairs) to the `outputs:` field in the `serverless.yml` file. The values can include any value supported by YAML, including strings, integers, lists (arrays), and dictionaries (key/value pairs). The dictionaries can also be nested to any depth. 21 | 22 | **serverless.yml** 23 | 24 | ```yaml 25 | outputs: 26 | my-key: my-value 27 | my-availability-zones: 28 | - us-east-1a 29 | - us-east-1b 30 | my-table-name: DynamoDbTable-${self:custom.stage} 31 | ``` 32 | 33 | The values will be interpolated and saved when the service is deployed. The values are saved as a part of the service instance so they are associated with the service, stage and region. 34 | 35 | ## Use outputs in dependent services 36 | 37 | Outputs can be consumed from other services with they `${output}` variable. The reference must be formatted as `.`, where the `` references another service in the same application, stage and region and the `` references the dictionary key from the `outputs:`. The `` can also be nested to reference nested values from the dictionary. 38 | 39 | **serverless.yml** 40 | 41 | ```yaml 42 | ${output:my-service.var-key} 43 | ``` 44 | 45 | or, to reference a service in a different app, stage or region, specify it like this: 46 | 47 | ```yaml 48 | ${output:appname:stagename:regionname:my-service.var-key} 49 | ``` 50 | 51 | So, for example: 52 | 53 | ```yaml 54 | ${output:another-app:dev:us-east-1:my-service.var-key} 55 | ``` 56 | 57 | You can also omit any of app, stage or region by leaving it empty like this, which only specifies 58 | stage: 59 | 60 | ```yaml 61 | ${output::dev::my-service.var-key} 62 | ``` 63 | 64 | ## Use outputs from the command line 65 | 66 | Outputs can also be accessed on the CLI. You can use this at development time to look up the outputs without opening the dashboard, or in your CI/CD pipeline to use the outputs in custom scripts. 67 | 68 | ### List outputs 69 | 70 | ``` 71 | sls output list 72 | [--org ] 73 | [--app ] 74 | [--service ] 75 | [--stage ] 76 | [--region ] 77 | ``` 78 | 79 | If you are in a working directory with a `serverless.yml` then the outputs will be listed for the org, app, and service specified in the serverless.yml file. 80 | 81 | If you are not in a working directory, without a `serverless.yml`, or if you want to access outputs from another org, app, service, or stage, you can pass in the optional flags. 82 | 83 | ### Get an output 84 | 85 | ``` 86 | sls output get 87 | --name 88 | [--org ] 89 | [--app ] 90 | [--service ] 91 | [--stage ] 92 | [--region region] 93 | ``` 94 | 95 | Individual outputs can also be accessed from the CLI using the `output get` sub-command. This command requires the `--name ` flag to identify the output name. 96 | 97 | It is possible for the output value to be a json object, in which case, we recommend using a tool like [jq](https://stedolan.github.io/jq/) to parse the JSON. 98 | 99 | Like the `sls output list` command, you can optionally specify a different org, app, service, stage or region using flags. 100 | 101 | ## View outputs in the dashboard 102 | 103 | The outputs for a service are made available on two different pages of the Serverless Framework Dashboard. 104 | 105 | The current outputs for a given service instance are available in the **OUTPUTS** section of the service instance view. This will show the key/values which are currently available. 106 | 107 | The historic outputs for a given service instance are available as a part of the deployment record which is available in the **activity & insights** section of the service instance view after a deployment. 108 | -------------------------------------------------------------------------------- /docs/guides/observability/README.md: -------------------------------------------------------------------------------- 1 | 7 | 8 | 9 | 10 | ### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/guides/observability) 11 | 12 | 13 | 14 | # Observability 15 | 16 | Observability is a crucial aspect of managing and maintaining your serverless applications. It provides insights into the behavior, performance, and health of your services. The Serverless Framework allows you to automatically configure observability for your services. 17 | 18 | ## Enabling Observability 19 | 20 | The Serverless Framework supports multiple observability providers. You can configure it to work with your preferred provider using the `observability` property within the `stages` block in your `serverless.yml` file. 21 | Below is an example of how to enable the Serverless Dashboard observability feature for the `prod` stage: 22 | 23 | ```yaml 24 | stages: 25 | prod: 26 | observability: dashboard 27 | ``` 28 | 29 | ## Configuring Observability 30 | 31 | For more granular control, you can specify the observability key as an object and include additional properties. In this configuration, the `provider` key is required, and you must specify the desired provider. 32 | 33 | ```yaml 34 | stages: 35 | prod: 36 | observability: 37 | provider: dashboard 38 | # additional configuration options for the chosen provider 39 | exampleSetting: customValue 40 | ``` 41 | 42 | ## Next Steps 43 | 44 | Learn more about configuring and using our supported observability providers: 45 | 46 | - [Serverless Dashboard](./dashboard) 47 | - [Axiom](./axiom) 48 | -------------------------------------------------------------------------------- /docs/guides/observability/axiom-api-tokens.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/serverless/serverless/main/docs/guides/observability/axiom-api-tokens.png -------------------------------------------------------------------------------- /docs/guides/observability/dashboard.md: -------------------------------------------------------------------------------- 1 | 7 | 8 | 9 | 10 | ### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/guides/observability/dashboard) 11 | 12 | 13 | 14 | # Serverless Dashboard 15 | 16 | The Serverless Dashboard is a powerful tool that provides insights into the behavior, performance, and health of your serverless applications. It allows you to monitor and troubleshoot your services, set up alerts, and view logs. 17 | 18 | ## Enabling Serverless Dashboard 19 | 20 | To enable the Serverless Dashboard for your service: 21 | 22 | 1. If you don't already have a Serverless Framework account, create a new account at https://app.serverless.com. 23 | 2. Add the `app` and `org` top-level properties in your `serverless.yml` file if they are not already specified. 24 | 3. Add the `observability` property to the `stages` block in your `serverless.yml` file and use `dashboard` or `true` value as the provider. 25 | 26 | ```yaml 27 | # Ensure these properties are present to connect to the Dashboard 28 | org: my-org 29 | app: my-app 30 | 31 | # Control observability instrumentation settings under stages 32 | stages: 33 | prod: 34 | observability: true # or observability: dashboard 35 | ``` 36 | 37 | To learn more about the Serverless Dashboard, visit the [Serverless Dashboard Monitoring & Observability documentation](../dashboard/monitoring/README.md). 38 | -------------------------------------------------------------------------------- /docs/guides/parameters.md: -------------------------------------------------------------------------------- 1 | 16 | 17 | 18 | 19 | ### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/guides/parameters) 20 | 21 | 22 | 23 | # Parameters 24 | 25 | Parameters can be defined in `serverless.yml`, [Serverless Dashboard](https://app.serverless.com) or passed via CLI with `--param="="` flag. They can be used for example to: 26 | 27 | - adapt the configuration based on the stage 28 | - store secrets securely 29 | - share configuration values between team members 30 | 31 | ## CLI parameters 32 | 33 | Parameters can be passed directly via CLI `--param` flag, following the pattern `--param="="`: 34 | 35 | ``` 36 | serverless deploy --param="domain=myapp.com" --param="key=value" 37 | ``` 38 | 39 | Parameters can then be used via the `${param:XXX}` variables: 40 | 41 | ```yaml 42 | provider: 43 | environment: 44 | APP_DOMAIN: ${param:domain} 45 | KEY: ${param:key} 46 | ``` 47 | 48 | ## Stage parameters 49 | 50 | `stages` allows you to set Parameters and other configuration details in a Stage-specific way. This is the new, preferred method for defining Parameters, which was launched in V.4. We'll be launching many features for the `stages` property, so we recommend embracing it. 51 | 52 | Parameters can be defined **for each stage** in `serverless.yml` under the `stages..params` key: 53 | 54 | ```yaml 55 | stages: 56 | prod: 57 | params: 58 | domain: myapp.com 59 | dev: 60 | params: 61 | domain: preview.myapp.com 62 | ``` 63 | 64 | Use the `default` key to define parameters that apply to all stages by default: 65 | 66 | ```yaml 67 | stages: 68 | default: 69 | params: 70 | domain: ${sls:stage}.preview.myapp.com 71 | prod: 72 | params: 73 | domain: myapp.com 74 | dev: 75 | params: 76 | domain: preview.myapp.com 77 | ``` 78 | 79 | Parameters can then be used via the `${param:XXX}` variables: 80 | 81 | ```yaml 82 | provider: 83 | environment: 84 | APP_DOMAIN: ${param:domain} 85 | ``` 86 | 87 | The variable will be resolved based on the current stage. 88 | 89 | ## Params property 90 | 91 | You can also set stage-specific parameters using the `params` top-level property, as show below. However, using the `stages` top-level property as shown above is the preferred and recommended way of setting parameters in the Serverless Framework V4. 92 | 93 | ```yml 94 | # serverless.yml 95 | 96 | params: 97 | default: 98 | domain: ${sls:stage}.myapi.com 99 | prod: 100 | domain: myapi.com 101 | dev: 102 | domain: dev.myapi.com 103 | ``` 104 | 105 | ## Serverless Dashboard parameters 106 | 107 | [Serverless Dashboard](https://www.serverless.com/secrets) lets you create and manage parameters, which is perfect for storing secrets securely or sharing configuration values across team members. 108 | 109 | On top of that, Dashboard parameters can be stored on the service (applies to all stages) or on a specific instance (applies to a specific stage). 110 | 111 | Dashboard parameters are treated as sensitive values, they are always encrypted at rest, and only decrypted during deployment or to view them in the dashboard. 112 | 113 | Just like any other parameter, they can be used in `serverless.yml` via the `${param:XXX}` variables: 114 | 115 | ```yaml 116 | provider: 117 | environment: 118 | STRIPE_SECRET_KEY: ${param:stripeSecret} 119 | ``` 120 | 121 | ### Creating Serverless Dashboard parameters 122 | 123 | Parameters can be created in the [Dashboard](https://app.serverless.com/) at the service level (applies to all stages) or instance level (stage-specific). 124 | 125 | To manage parameters on a service, go to the **apps** section of the dashboard, and select **settings** under the **...** menu. 126 | 127 | To manage parameters on an instance, go to the **app** section of the dashboard, select the instance, and go to the **params** tab. 128 | 129 | ## Inheritance and overriding 130 | 131 | Parameters can be defined in `serverless.yml` per stage, as well as in Serverless Dashboard on the service or the instance (stage). Here is the priority used to resolve a `${param:XXX}` variable: 132 | 133 | - First, look in params passed with `--param` CLI flag 134 | - If not found, then look in `stages..params` in `serverless.yml` 135 | - If not found, then look in `stages.default.params` in `serverless.yml` 136 | - If not found, then look in the instance's parameters in the Dashboard 137 | - If not found, then look in the service's parameters in the Dashboard 138 | - If not found, throw an error, or use the fallback value if one was provided: `${param:XXX, 'default value'}` 139 | 140 | This gives you flexibility to mix `serverless.yml` parameters as well as secure Serverless Dashboard parameters. 141 | 142 | This is especially useful in development when deploying to ephemeral stages (e.g. "feature-x"). The stage might not have any parameter, therefore it will default to the parameters set on the service. However, in other stages, like "prod", or "staging", you may override the service-level parameters with stage-level parameters to use values unique to that stage. 143 | -------------------------------------------------------------------------------- /docs/guides/plugins/README.md: -------------------------------------------------------------------------------- 1 | 7 | 8 | 9 | 10 | ### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/guides/plugins) 11 | 12 | 13 | 14 | # Plugins 15 | 16 | A plugin is custom JavaScript code that extends the Serverless Framework with new features. 17 | 18 | If you or your organization have a specific workflow, install a pre-written plugin or write one to customize the Framework to your needs. 19 | 20 | Since the Serverless Framework is a group of "core" plugins, custom plugins are written exactly the same way as core plugins. Learn more about [creating a custom plugin](./creating-plugins.md). 21 | 22 | Explore existing plugins in the [Serverless Framework Plugins repository](https://www.serverless.com/plugins). 23 | 24 | ## Installing plugins 25 | 26 | Plugins are installed per service. They are not applied globally. 27 | 28 | To install a plugin, run the following command in a service directory: 29 | 30 | ``` 31 | serverless plugin install -n custom-serverless-plugin 32 | ``` 33 | 34 | This command will install the plugin via NPM and register it in `serverless.yml`. 35 | 36 | You can also install the plugin manually via NPM: 37 | 38 | ``` 39 | npm install --save-dev custom-serverless-plugin 40 | ``` 41 | 42 | and then register it in `serverless.yml` in the `plugins` section: 43 | 44 | ```yml 45 | # serverless.yml file 46 | 47 | plugins: 48 | - custom-serverless-plugin 49 | ``` 50 | 51 | Some plugins require extra configuration. The `custom` section in `serverless.yml` is where you can add extra configuration for plugins (the plugin's documentation will tell you if you need to add anything there): 52 | 53 | ```yml 54 | plugins: 55 | - custom-serverless-plugin 56 | 57 | custom: 58 | customkey: customvalue 59 | ``` 60 | 61 | Note for plugin authors: read [Extending the configuration](./custom-configuration.md) to learn how to enhance `serverless.yml` with configuration validation. 62 | 63 | ## Service local plugin 64 | 65 | If you are working on a plugin, or have a plugin that is just designed for one project, it can be loaded from local files: 66 | 67 | ```yml 68 | plugins: 69 | - ./local-directory/custom-serverless-plugin 70 | ``` 71 | 72 | The path must start with `./` and is relative to the root of your service. 73 | 74 | ## Load Order 75 | 76 | Keep in mind that the order you define your plugins matters. Serverless loads all the core plugins, and then the custom plugins in the order you've defined them. 77 | 78 | ```yml 79 | # serverless.yml 80 | 81 | plugins: 82 | - plugin1 83 | - plugin2 84 | ``` 85 | 86 | In this case `plugin1` is loaded before `plugin2`. 87 | -------------------------------------------------------------------------------- /docs/guides/plugins/custom-commands.md: -------------------------------------------------------------------------------- 1 | 7 | 8 | 9 | 10 | ### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/guides/plugins/custom-commands) 11 | 12 | 13 | 14 | # Custom commands 15 | 16 | Serverless Framework plugins can define custom CLI commands. 17 | 18 | These commands can then be called by users, for example: `serverless my-command`. 19 | 20 | ```javascript 21 | class MyPlugin { 22 | constructor() { 23 | this.commands = { 24 | 'my-command': { 25 | lifecycleEvents: ['resources', 'functions'], 26 | }, 27 | } 28 | } 29 | } 30 | 31 | module.exports = MyPlugin 32 | ``` 33 | 34 | A CLI _Command_ that can be called by a user, e.g. `serverless foo`. A Command has no logic, but simply defines the CLI configuration (e.g. command, parameters) and the _Lifecycle Events_ for the command. Every command defines its own lifecycle events. 35 | 36 | ## Lifecycle events 37 | 38 | By default, a command has no logic. Use _lifecycle event hooks_ to add logic when the command runs: 39 | 40 | ```javascript 41 | class MyPlugin { 42 | constructor() { 43 | this.commands = { 44 | 'my-command': { 45 | lifecycleEvents: ['run'], 46 | }, 47 | } 48 | 49 | this.hooks = { 50 | 'my-command:run': () => { 51 | // Do something 52 | }, 53 | } 54 | } 55 | } 56 | ``` 57 | 58 | For each event, an additional `before` and `after` event is created: 59 | 60 | ```js 61 | this.hooks = { 62 | 'before:my-command:run': () => { 63 | // Before my command runs 64 | }, 65 | 'my-command:run': () => { 66 | // My command runs 67 | }, 68 | 'after:my-command:run': () => { 69 | // After 70 | }, 71 | } 72 | ``` 73 | 74 | Note that a command can define multiple events: these will be called sequentially. 75 | 76 | ## Command options 77 | 78 | Commands can have CLI options: 79 | 80 | - either passed with a double dash (`--`): `serverless my-command --function functionName`. 81 | - or as a shortcut with a single dash (`-`): `serverless my-command -f functionName`. 82 | 83 | Options can be specified in the command definition. The value of the CLI option can be retrieved via the `options` parameter of the plugin: 84 | 85 | ```javascript 86 | class MyPlugin { 87 | constructor(serverless, options) { 88 | this.options = options 89 | 90 | this.commands = { 91 | 'my-command': { 92 | // The 'usage' property is used to display the 'serverless --help' output 93 | usage: 'This is my new custom command!', 94 | lifecycleEvents: ['run'], 95 | options: { 96 | // Define the '--function' option with the '-f' shortcut 97 | function: { 98 | usage: 99 | 'Specify the function you want to handle (e.g. "--function myFunction")', 100 | shortcut: 'f', 101 | required: true, 102 | type: 'string', // Possible values: 'string', 'boolean', 'multiple' 103 | }, 104 | }, 105 | }, 106 | } 107 | 108 | this.hooks = { 109 | 'my-command:run': () => this.run(), 110 | } 111 | } 112 | 113 | run() { 114 | console.log('The option was: ', this.options.function) 115 | } 116 | } 117 | ``` 118 | 119 | If an option is not required, a `default` property can be set in the option definition. 120 | 121 | ## Command naming 122 | 123 | Command names must be unique across all plugins. For example instead of defining a custom `deploy` command, name it `my-company-deploy` instead. 124 | 125 | If a plugin defines a command name that conflicts with Serverless Framework core or another plugin, the CLI will exit with an error. 126 | -------------------------------------------------------------------------------- /docs/guides/plugins/custom-variables.md: -------------------------------------------------------------------------------- 1 | 7 | 8 | 9 | 10 | ### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/guides/plugins/custom-variables) 11 | 12 | 13 | 14 | # Custom variables 15 | 16 | Plugins can register custom variables sources, for example `${foo:some-variable}`. 17 | 18 | Custom sources can be registered via `configurationVariablesSources` as an object with a `resolve` function: 19 | 20 | ```javascript 21 | 'use strict' 22 | 23 | class MyPlugin { 24 | constructor() { 25 | this.configurationVariablesSources = { 26 | foo: { 27 | async resolve({ address }) { 28 | // `address` contains the name of the variable to resolve: 29 | // In `${foo:some-variable}`, address will contain `some-variable`. 30 | 31 | // Resolver is expected to return an object with the value in the `value` property: 32 | return { 33 | // 34 | value: `Resolving variable ${address}`, 35 | } 36 | }, 37 | }, 38 | } 39 | } 40 | } 41 | 42 | module.exports = MyPlugin 43 | ``` 44 | 45 | The variable source defined above (registered via a plugin) can be used as follows: 46 | 47 | ```yaml 48 | service: test 49 | # ... 50 | 51 | custom: 52 | value1: ${foo:bar} 53 | 54 | plugins: 55 | - ./my-plugin 56 | ``` 57 | 58 | The configuration will be resolved into the following: 59 | 60 | ```yaml 61 | service: test 62 | # ... 63 | 64 | custom: 65 | value1: Resolving variable bar 66 | 67 | plugins: 68 | - ./my-plugin 69 | ``` 70 | 71 | ## Variable parameters 72 | 73 | Variable sources can support advanced use cases via parameters: 74 | 75 | ```yaml 76 | service: test 77 | # ... 78 | 79 | custom: 80 | value1: ${foo(one, two):bar} 81 | ``` 82 | 83 | Parameters can be retrieved in the `params` argument: 84 | 85 | ```javascript 86 | class MyPlugin { 87 | constructor() { 88 | this.configurationVariablesSources = { 89 | foo: { 90 | async resolve({ address, params }) { 91 | return { 92 | // In the example below, ${foo(one, two):bar} will 93 | // resolve to "one,two" 94 | value: (params || []).join(','), 95 | } 96 | }, 97 | }, 98 | } 99 | } 100 | } 101 | ``` 102 | 103 | ## Resolving variables, configuration values and options 104 | 105 | It is possible to retrieve other variables, configuration values and CLI options in the variable resolver: 106 | 107 | ```javascript 108 | class MyPlugin { 109 | constructor() { 110 | this.configurationVariablesSources = { 111 | foo: { 112 | async resolve({ resolveVariable, options }) { 113 | // `options` is CLI options 114 | // `resolveVariable` resolves other variables (for example here: `${sls:stage}`) 115 | const stage = await resolveVariable('sls:stage') 116 | // To retrieve a configuration value from serverless.yml, use the `self:xxx` variable source, for example: 117 | // await resolveVariable('self:provider.region') 118 | 119 | return { 120 | value: `The stage is ${stage}`, 121 | } 122 | }, 123 | }, 124 | } 125 | } 126 | } 127 | ``` 128 | -------------------------------------------------------------------------------- /docs/guides/plugins/extending-configuration.md: -------------------------------------------------------------------------------- 1 | 8 | 9 | 10 | 11 | ### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/guides/plugins/extending-configuration) 12 | 13 | 14 | 15 | # Extending and overriding configuration 16 | 17 | Plugins can extend and override the internal configuration. 18 | 19 | To do so, plugins may use the `serverless.extendConfiguration(...)` method. 20 | This is only allowed at pre-init stage of serverless. 21 | The method also takes care of resolving all variables in the given value. But it **does not validate you input** nor the target. Improper usage can cause serverless to fail. 22 | 23 | The `serverless.extendConfiguration(configurationPathKeys, value)` method takes two arguments. 24 | 25 | | Argument | Type | Description | 26 | | ----------------------- | ------------------------- | ------------------------------------------------------------------ | 27 | | `configurationPathKeys` | string[] | Path of the configuration property to set; must not be empty | 28 | | `value` | string \| object \| array | New value of the configuration property in `configurationPathKeys` | 29 | 30 | If configuration in `configurationPathKeys` **does exist** the value will be overwritten. 31 | If configuration in `configurationPathKeys` **does not exist** the whole path will be created. 32 | 33 | You can use it in plugin constructor, or if for some reason configuration extension is resolved asynchronously you may resort to `asyncInit()` method 34 | 35 | ```js 36 | class MyPlugin { 37 | constructor(serverless) { 38 | this.serverless = serverless 39 | 40 | const value = { 41 | myKey: 'myValue', 42 | } 43 | this.serverless.extendConfiguration(['custom', 'myPlugin'], value) 44 | } 45 | } 46 | 47 | module.exports = MyPlugin 48 | ``` 49 | 50 | If your plugin needs merging you need to take care of it yourself. 51 | 52 | ```js 53 | class MyPlugin { 54 | constructor(serverless) { 55 | this.serverless = serverless 56 | 57 | const currentConfig = this.serverless.configurationInput.custom.myPlugin 58 | const value = Object.assign(currentConfig, { 59 | myKey: 'myValue', 60 | }) 61 | this.serverless.extendConfiguration(['custom', 'myPlugin'], value) 62 | } 63 | } 64 | 65 | module.exports = MyPlugin 66 | ``` 67 | -------------------------------------------------------------------------------- /docs/guides/state.md: -------------------------------------------------------------------------------- 1 | 14 | 15 | 16 | 17 | ### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/guides/state) 18 | 19 | 20 | 21 | # Serverless Framework State 22 | 23 | Serverless Framework Compose allows for the orchestration and deployment of multiple services. 24 | A crucial aspect of this is managing the state of each service, which includes storing outputs and other runtime information necessary for the correct operation of services. 25 | This guide covers how to set up and manage state using AWS S3 and AWS SSM. 26 | 27 | ## State Management Overview 28 | 29 | State management in Serverless Framework Compose is crucial for: 30 | 31 | - **Storing Service Outputs**: Save outputs from deployments to share them across services. 32 | - **Ensuring Consistency**: Maintain the state of services across deployments, ensuring that each service can access the necessary data for its operation. 33 | - **Handling Dependencies**: Automatically resolve dependencies between services by referencing shared state. 34 | 35 | Serverless Framework Compose uses AWS S3 to store the state of services and AWS SSM (Systems Manager) to track the location of the state storage. 36 | 37 | ## Zero-Configuration Setup 38 | 39 | The easiest way to manage state in Serverless Framework Compose is through its default, zero-configuration setup. When you don’t specify any state configuration, Serverless Framework Compose automatically handles everything for you. 40 | 41 | ### How It Works 42 | 43 | 1. **Automatic S3 Bucket Creation**: If no state configuration is provided in your `serverless-compose.yml`, Serverless Framework Compose automatically creates an S3 bucket to store the state. 44 | 2. **SSM Parameter Store**: The name and region of the automatically created S3 bucket are stored in AWS SSM Parameter Store in `us-east-1` AWS region, under the parameter `/serverless-framework/state/s3-bucket`. This parameter contains a JSON object with the following keys: 45 | 46 | - `bucketName`: The name of the S3 bucket. 47 | - `bucketRegion`: The AWS region where the bucket is located. 48 | 49 | 3. **Versioning Enabled**: The created S3 bucket will have versioning enabled by default, ensuring that different states over time are maintained and can be rolled back if necessary. 50 | 51 | **Note**: To create the default state bucket, you must have the necessary permissions to put SSM parameters and create versioned S3 buckets. 52 | If you don’t have these permissions, you can set up a [custom state configuration](#custom-state-configuration) to use an existing S3 bucket. 53 | 54 | ### Example 55 | 56 | Assume you have the following serverless-compose.yml with two services: 57 | 58 | ```yaml 59 | services: 60 | service-a: 61 | path: service-a 62 | 63 | service-b: 64 | path: service-b 65 | params: 66 | queueUrl: ${service-a.queueUrl} 67 | ``` 68 | 69 | In this case, without any additional state configuration, Serverless Framework Compose will: 70 | 71 | - Create a versioned S3 bucket to store the state of service-a and service-b. 72 | - Store the name and region of this bucket in SSM Parameter Store. 73 | - Automatically manage the retrieval and updating of this state during deployments. 74 | 75 | #### Deploying Services 76 | 77 | To deploy all services and manage their state automatically: 78 | 79 | ```bash 80 | serverless deploy 81 | ``` 82 | 83 | This command will: 84 | 85 | - Deploy service-a and save its state (like output URLs and ARNs) to the S3 bucket. 86 | - Deploy service-b, retrieve the state from service-a, and inject necessary outputs (e.g., `queueUrl`) as parameters. 87 | 88 | State allows you to execute commands on individual services even if they have dependencies on other services. 89 | When you use commands like 90 | 91 | ```bash 92 | serverless 93 | ``` 94 | 95 | the Framework automatically fetches the necessary input data from the stored state, 96 | making it easy to manage and deploy services with complex interdependencies. 97 | 98 | ## Custom State Configuration 99 | 100 | While the zero-configuration setup is convenient, there may be situations where you want to customize how and where the state is stored. 101 | If you require this level of customization, you can specify custom state management settings in your `serverless-compose.yml`. 102 | Here’s how you can do it: 103 | 104 | ### Using a Custom S3 Bucket 105 | 106 | You can specify an existing S3 bucket for storing the state using Resolvers: 107 | 108 | ```yaml 109 | state: my-s3-state-resolver 110 | 111 | stages: 112 | default: 113 | resolvers: 114 | my-aws-account: 115 | type: aws 116 | my-s3-state-resolver: 117 | type: s3 118 | bucketName: my-custom-state-bucket 119 | 120 | services: 121 | service-a: 122 | path: service-a 123 | 124 | service-b: 125 | path: service-b 126 | params: 127 | queueUrl: ${service-a.queueUrl} 128 | ``` 129 | 130 | In this setup: 131 | 132 | - The `state` field defines the state resolver, which is linked to an existing S3 bucket. 133 | - The Framework will use this bucket instead of creating a new one. **The bucket must be versioned to ensure proper state management.** 134 | 135 | **Note**: For more information on Resolvers, refer to the [Resolvers documentation](variables). 136 | 137 | ## Cleaning Up State 138 | 139 | When you run `serverless remove`, the state stored in the S3 bucket is also deleted, ensuring that no unnecessary data is left in your AWS account. 140 | -------------------------------------------------------------------------------- /docs/guides/variables/aws/README.md: -------------------------------------------------------------------------------- 1 | 15 | 16 | # Resolvers 17 | 18 | - [AWS S3](s3) 19 | - [AWS SSM Parameter Store & Secrets Manager](ssm) 20 | - [AWS CloudFormation Outputs](cf-stack) 21 | 22 | # Configuration options 23 | 24 | | Option | Required | Type | Default | Description | 25 | | ----------------- | :------: | :-----: | :-------: | :------------------------------------------------------------------- | 26 | | `accessKeyId` | No | String | | AWS Access Key ID | 27 | | `secretAccessKey` | No | String | | AWS Secret Access Key | 28 | | `sessionToken` | No | String | | AWS Session Token | 29 | | `region` | No | String | us-east-1 | AWS region | 30 | | `profile` | No | String | | AWS profile name | 31 | | `dashboard` | No | Boolean | true | Whether Serverless Dashboard AWS Provider credentials should be used | 32 | 33 | ## Example 34 | 35 | ```yaml 36 | stages: 37 | default: 38 | resolvers: 39 | aws-account-1: 40 | type: aws 41 | profile: account1-profile-name 42 | region: us-west-2 43 | accessKeyId: ${env:ACCOUNT1_AWS_ACCESS_KEY_ID} 44 | secretAccessKey: ${env:ACCOUNT1_AWS_SECRET_ACCESS_KEY} 45 | dashboard: false 46 | ``` 47 | 48 | # Provider-specific variables 49 | 50 | You can reference AWS-specific values as the source of your variables. Those values are exposed via the Serverless Variables system through: 51 | 52 | 1. `{providerName:}` variable prefix which should be the name of the resolver provider specified in the `resolvers` block (`aws-account-1` in the example above). 53 | 2. `{aws:}` variable prefix which uses the deployment credentials. 54 | 55 | The following variables are available: 56 | 57 | **accountId** 58 | 59 | Account ID of you AWS Account, based on the AWS Credentials that you have configured. 60 | 61 | ```yml 62 | service: new-service 63 | provider: 64 | name: aws 65 | 66 | functions: 67 | func1: 68 | name: function-1 69 | handler: handler.func1 70 | environment: 71 | ACCOUNT_ID: ${aws:accountId} 72 | ``` 73 | 74 | **region** 75 | 76 | The region used by the Serverless CLI. The `${aws:region}` variable is a shortcut for `${opt:region, self:provider.region, "us-east-1"}`. 77 | -------------------------------------------------------------------------------- /docs/guides/variables/aws/cf-stack.md: -------------------------------------------------------------------------------- 1 | 14 | 15 | 16 | 17 | ### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/guides/variables/aws/cf-stack) 18 | 19 | 20 | 21 | # Configuration options 22 | 23 | | Option | Required | Type | Default | Description | 24 | | -------- | :------: | :----: | :--------------------------------: | :---------- | 25 | | `region` | No | String | Inherited from parent AWS resolver | AWS region | 26 | 27 | ## Examples 28 | 29 | ### Default Configuration 30 | 31 | In this example, the `awsAccount1` provider is set up to fetch CloudFormation stack outputs using the default region associated with your deployment. 32 | This setup is useful when your Serverless service needs to dynamically reference values from another service or stack, such as resource names. 33 | The `cf:stackName.outputKey` syntax ensures that you can easily pull outputs from another stack without hard-coding values. 34 | 35 | ```yaml 36 | stages: 37 | default: 38 | resolvers: 39 | awsAccount1: 40 | type: aws 41 | 42 | functions: 43 | hello: 44 | handler: handler.hello 45 | description: ${awsAccount1:cf:another-service.functionPrefix} 46 | ``` 47 | 48 | ### Custom region 49 | 50 | Here, the `awsAccount1` provider is configured with a default region (`us-west-2`), while the `euCf` resolver is set to pull CloudFormation outputs from the `eu-west-1` region. 51 | This is particularly useful when your service needs to integrate with resources or outputs from stacks deployed in different regions. 52 | For instance, if your primary service is deployed in one region but needs to interact with a resource defined in a stack in another region, this setup handles that cross-region reference smoothly. 53 | 54 | ```yaml 55 | stages: 56 | default: 57 | resolvers: 58 | awsAccount1: 59 | type: aws 60 | region: us-west-2 61 | euCf: 62 | type: cf 63 | region: eu-west-1 64 | 65 | functions: 66 | hello: 67 | handler: handler.hello 68 | description: ${awsAccount1:euCf:another-service.functionPrefix} 69 | ``` 70 | 71 | # Classic (Pre-Resolvers) Format 72 | 73 | You can reference CloudFormation stack output values as the source of your variables to use in your service with the `cf:stackName.outputKey` syntax. 74 | It uses the deployment (provider) AWS credentials to access CloudFormation. 75 | For example: 76 | 77 | ```yml 78 | service: new-service 79 | provider: aws 80 | functions: 81 | hello: 82 | name: ${cf:another-service-dev.functionPrefix}-hello 83 | handler: handler.hello 84 | world: 85 | name: ${cf:another-stack.functionPrefix}-world 86 | handler: handler.world 87 | ``` 88 | 89 | In that case, the framework will fetch the values of those `functionPrefix` outputs from the provided stack names and populate your variables. There are many use cases for this functionality and it allows your service to communicate with other services/stacks. 90 | 91 | You can add such custom output to CloudFormation stack. For example: 92 | 93 | ```yml 94 | service: another-service 95 | provider: 96 | name: aws 97 | runtime: nodejs14.x 98 | region: ap-northeast-1 99 | memorySize: 512 100 | functions: 101 | hello: 102 | name: ${self:custom.functionPrefix}hello 103 | handler: handler.hello 104 | custom: 105 | functionPrefix: 'my-prefix-' 106 | resources: 107 | Outputs: 108 | functionPrefix: 109 | Value: ${self:custom.functionPrefix} 110 | Export: 111 | Name: functionPrefix 112 | memorySize: 113 | Value: ${self:provider.memorySize} 114 | Export: 115 | Name: memorySize 116 | ``` 117 | 118 | You can also reference CloudFormation stack in another regions with the `cf(REGION):stackName.outputKey` syntax. For example: 119 | 120 | ```yml 121 | service: new-service 122 | provider: aws 123 | functions: 124 | hello: 125 | name: ${cf(us-west-2):another-service-dev.functionPrefix}-hello 126 | handler: handler.hello 127 | world: 128 | name: ${cf(ap-northeast-1):another-stack.functionPrefix}-world 129 | handler: handler.world 130 | ``` 131 | 132 | You can reference [CloudFormation stack outputs export values](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/outputs-section-structure.html) as well. For example: 133 | 134 | ```yml 135 | # Make sure you set export value in StackA. 136 | 137 | Outputs: 138 | DynamoDbTable: 139 | Value: 140 | "Ref": DynamoDbTable 141 | Export: 142 | Name: DynamoDbTable-${self:custom.stage} 143 | 144 | # Then you can reference the export name in StackB 145 | 146 | provider: 147 | environment: 148 | Table: 149 | 'Fn::ImportValue': 'DynamoDbTable-${self:custom.stage}' 150 | ``` 151 | 152 | ## AWS CloudFormation Pseudo Parameters and Intrinsic functions 153 | 154 | [AWS Pseudo Parameters](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/pseudo-parameter-reference.html) 155 | can be used in values which are passed through as is to CloudFormation template properties. 156 | 157 | Otherwise Serverless Framework has no implied understanding of them and does not try to resolve them on its own. 158 | 159 | Same handling applies to [CloudFormation Intrinsic functions](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference.html) 160 | -------------------------------------------------------------------------------- /docs/guides/variables/cli-options.md: -------------------------------------------------------------------------------- 1 | 7 | 8 | 9 | 10 | ### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/guides/variables/cli-options) 11 | 12 | 13 | 14 | # Reference CLI Options 15 | 16 | To reference CLI options that you passed, use the `${opt: