diff --git a/docs/README.md b/docs/README.md index 92dc96417..583b9c8e7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -30,10 +30,10 @@ You may also take a look at our [code of conduct](/code_of_conduct.md). ## User documentation -- [Understanding Serverless and its configuration files](understanding-serverless) +- [Understanding Serverless and the configuration file](understanding-serverless) - [Serverless services and functions](understanding-serverless/services-and-functions.md) - [serverless.yml](understanding-serverless/serverless-yml.md) - - [serverless.env.yml](understanding-serverless/serverless-env-yml.md) + - [Serverless variables](understanding-serverless/serverless-variables.md) - [How to build your Serverless services](guide) - [Installing Serverless](guide/installation.md) - [Provider account setup](guide/provider-account-setup.md) diff --git a/docs/guide/creating-a-service.md b/docs/guide/creating-a-service.md index 6076f792a..bf4678c67 100644 --- a/docs/guide/creating-a-service.md +++ b/docs/guide/creating-a-service.md @@ -13,7 +13,7 @@ To create a service with a `nodejs` runtime running on `aws` just pass the `aws- serverless create --template aws-nodejs ``` -This will create a service and generate `serverless.yml`, `serverless.env.yml` and `handler.js` files in the current +This will create a service and generate `serverless.yml` and `handler.js` files in the current working directory. ## Open the service inside your editor @@ -23,7 +23,6 @@ favorite editor. You'll see the following files: - `serverless.yml` -- `serverless.env.yml` - `handler.js` ### [`serverless.yml`](../understanding-serverless/serverless-yml.md) @@ -34,15 +33,6 @@ This is our core service file. You can see the name of our service, the provider If you want to learn more about the [`serverless.yml`](../understanding-serverless/serverless-yml.md) file you might want check out our [in depth guide](../understanding-serverless/serverless-yml.md) about it. -### [`serverless.env.yml`](../understanding-serverless/serverless-env-yml.md) - -This file includes all the environment variables Serverless uses. It automatically creates environment variables for a -default stage called `dev` and a default region called `us-east-1`. Those variables will be referenced and used as a -default later on for deployment. - -If you want to learn more about the [`serverless.env.yml`](../understanding-serverless/serverless-env-yml.md) file you -might want check out our [in depth guide](../understanding-serverless/serverless-env-yml.md) about it. - ### `handler.js` The `handler.js` file includes a function skeleton which returns a simple message. The function definition in diff --git a/docs/guide/deploying-a-service.md b/docs/guide/deploying-a-service.md index 9b047900f..731d4b027 100644 --- a/docs/guide/deploying-a-service.md +++ b/docs/guide/deploying-a-service.md @@ -9,8 +9,7 @@ Make sure that you're still in the service directory. Run `serverless deploy` to start the deployment process. Serverless will now deploy the whole service (with all it's functions and events which we'll add soon) to the -services cloud provider. It will use the default `stage` and `region` settings which are defined in -[`serverless.env.yml`](../understanding-serverless/serverless-env-yml.md). +services cloud provider. It will use the default `stage` and `region` settings. The default stage is `dev` and default region is `us-east-1`. You can change the default stage and region in your `serverless.yml` file by setting the `stage` and `region` properties inside a `default` object as the following example shows: diff --git a/docs/understanding-serverless/README.md b/docs/understanding-serverless/README.md index 40fba9d67..75b5b5ced 100644 --- a/docs/understanding-serverless/README.md +++ b/docs/understanding-serverless/README.md @@ -1,13 +1,10 @@ # Understanding Serverless Here we'll take a deep dive into the internals of Serverless and understand what a service is and how functions relate -to a service. - -Additionally we look at the Serverless key pieces of each service which are the [`serverless.yml`](serverless-yml.md) -and [`serverless.env.yml`](serverless-env-yml.md) files. +to a service and we'll explore the `serverless.yml` configuration file. ## Table of contents - [Serverless services and functions](services-and-functions.md) - [serverless.yml](serverless-yml.md) -- [serverless.env.yml](serverless-env-yml.md) +- [Serverless variables](serverless-variables.md) diff --git a/docs/understanding-serverless/serverless-env-yml.md b/docs/understanding-serverless/serverless-env-yml.md deleted file mode 100644 index 61aac9384..000000000 --- a/docs/understanding-serverless/serverless-env-yml.md +++ /dev/null @@ -1,25 +0,0 @@ -# serverless.env.yml - -The `serverless.env.yml` file includes environment specific configuration. This includes listing your stages and their -regions. It also manages variables at 3 levels ordered by priority: - -1. Region Variables: For a specific region in a specific stage. -2. Stage Variables: For a specific stage. -3. Common Variables: For all stages and regions. - - -```yml -vars: - someVar: 1 -stages: - dev: - vars: - someVar: 2 - regions: - us-east-1: - vars: - someVar: 3 -``` - -Notice that you have the same variable defined in as common, stage and region variable. In that case the region variable -will be used. If you removed the region variable, the stage variable will be used... and so on. diff --git a/docs/understanding-serverless/serverless-variables.md b/docs/understanding-serverless/serverless-variables.md new file mode 100644 index 000000000..e017298e9 --- /dev/null +++ b/docs/understanding-serverless/serverless-variables.md @@ -0,0 +1,67 @@ +# Serverless Variables +The Serverless framework provides a powerful variable system to give your `serverless.yml` configuration file extra flexibility. With Serverless Variables, you'll be able to do the following: + +- Reference & load variables from environment variables +- Reference & load variables from CLI options +- Recursively reference properties of any type from the same `serverless.yml` file + +## Referencing Environment Variables +To reference environment variables, you'll need to use the `${env.SOME_VAR}` syntax in your `serverless.yml` configuration file. Here's an example: + +```yml +service: new-service +provider: aws +functions: + hello: + name: ${env.FUNC_PREFIX}-hello + handler: handler.hello + world: + name: ${env.FUNC_PREFIX}-world + handler: handler.world + +``` + +In the previous example you're dynamically adding a prefix to the function names by referencing the `FUNC_PREFIX` env var. So you can easily change that prefix for all functions by changing the `FUNC_PREFIX` env var. + +## Referencing CLI Options +To reference CLI options that you passed, you'll need to use the `${opt.some_option}` syntax in your `serverless.yml` configuration file. Here's an example: + +```yml +service: new-service +provider: aws +functions: + hello: + name: ${opt.stage}-hello + handler: handler.hello + world: + name: ${opt.stage}-world + handler: handler.world + +``` + +In the previous example you're dynamically adding a prefix to the function names by referencing the `stage` option that you pass in the CLI. So when you deploy, the function name will always include the stage you're deploying to. + +## Referencing CLI Options +To reference CLI options that you passed, you'll need to use the `${opt.some_option}` syntax in your `serverless.yml` configuration file. Here's an example: + +```yml +service: new-service +provider: aws +custom: + globalSchedule: rate(10 minutes) + +functions: + hello: + name: ${opt.stage}-hello + handler: handler.hello + events: + - schedule: ${self.custom.globalSchedule} + world: + name: ${opt.stage}-world + handler: handler.world + events: + - schedule: ${self.custom.globalSchedule} + +``` + +In the previous example you're setting a global schedule for all functions by referencing the `globalSchedule` property in the same `serverless.yml` file. This way, you can easily change the schedule for all functions whenever you like. \ No newline at end of file diff --git a/docs/understanding-serverless/services-and-functions.md b/docs/understanding-serverless/services-and-functions.md index 624dc52ec..99e8b1f00 100644 --- a/docs/understanding-serverless/services-and-functions.md +++ b/docs/understanding-serverless/services-and-functions.md @@ -4,9 +4,8 @@ A *Serverless service* is a group of one or multiple functions and any resources functions together, it's easier to share code and resources between those functions. Services are also designed to be completely independent, which helps teams develop more quickly without waiting for others. -Each *Serverless service* contains two configuration files: +Each *Serverless service* configuration is managed in the [`serverless.yml`](./serverless-yml.md) file. The main responsibilities of this file are: -### [`serverless.yml`](./serverless-yml.md) - Declares a Serverless service - Defines one or multiple functions in the service - Defines the provider the service will be deployed to (and the runtime if provided) @@ -14,11 +13,7 @@ Each *Serverless service* contains two configuration files: - Defines events that trigger each function to execute (e.g. HTTP requests) - Defines one set of resources (e.g. 1 AWS CloudFormation stack) required by the functions in this service - Events listed in the `events` section may automatically create the resources required for the event upon deployment - -### [`serverless.env.yml`](./serverless-env-yml.md) - - Defines stages for this service - - Defines regions for each stage - - Defines Serverless variables + - Allow flexible configuration using Serverless Variables. ## Example @@ -31,7 +26,6 @@ users |__ lib // contains logic |__ users.js // single handler file, requires lib |__ serverless.yml - |__ serverless.env.yml |__ node_modules |__ package.json ``` @@ -43,21 +37,8 @@ service: users provider: name: aws runtime: nodejs4.3 - memorySize: ${memoryVar} # reference a Serverless variable + memorySize: ${env.memoryVar} # Serverless Variable referencing an env var functions: create: handler: users.create -``` - -### [`serverless.env.yml`](./serverless-env-yml.md) - -```yml -vars: - memoryVar: 512 -stages: - dev: - vars: - regions: - us-east-1: - vars: -``` +``` \ No newline at end of file