Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #1834 from serverless/sls-vars
Serverless Variables
- Loading branch information
Showing
39 changed files
with
1,051 additions
and
1,678 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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) |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,151 @@ | ||
| # 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 | ||
| - Recursively reference properties of any type from other YAML/JSON files | ||
| - Recursively nest variable references within each other for ultimate flexibility | ||
| - Combine multiple variable references to overwrite each other | ||
|
|
||
| ## 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 when you run `serverless deploy --stage dev`. So when you deploy, the function name will always include the stage you're deploying to. | ||
|
|
||
| ## Recursively Self-Reference serverless.yml Properties | ||
| To self-reference properties in `serverless.yml`, you'll need to use the `${self:someProperty}` syntax in your `serverless.yml` configuration file. This functionality is recursive, so you can go as deep in the object tree as you want. Here's an example: | ||
|
|
||
| ```yml | ||
| service: new-service | ||
| provider: aws | ||
| custom: | ||
| globalSchedule: rate(10 minutes) | ||
|
|
||
| functions: | ||
| hello: | ||
| handler: handler.hello | ||
| events: | ||
| - schedule: ${self:custom.globalSchedule} | ||
| 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. | ||
|
|
||
| ## Recursively Reference Variables in Other Files | ||
| To reference variables in other YAML or JSON files, you'll need to use the `${file(./myFile.yml):someProperty}` syntax in your `serverless.yml` configuration file. This functionality is recursive, so you can go as deep in that file as you want. Here's an example: | ||
|
|
||
| ```yml | ||
|
|
||
| # myCustomFile.yml | ||
|
|
||
| globalSchedule: rate(10 minutes) | ||
|
|
||
| ``` | ||
|
|
||
|
|
||
| ```yml | ||
| # serverless.yml | ||
| service: new-service | ||
| provider: aws | ||
| custom: ${file(./myCustomFile.yml)} # You can reference the entire file | ||
| functions: | ||
| hello: | ||
| handler: handler.hello | ||
| events: | ||
| - schedule: ${file(./myCustomFile.yml):globalSchedule} # Or you can reference a specific property | ||
| world: | ||
| handler: handler.world | ||
| events: | ||
| - schedule: ${self:custom.globalSchedule} # This would also work in this case | ||
|
|
||
| ``` | ||
|
|
||
| In the previous example you're referencing the entire `myCustomFile.yml` file in the `custom` property. You just need to pass the path relative to your service directory. You can also request specific properties in that file as shown in the `schedule` property. It's completely recursive and you can go as deep as you want. | ||
|
|
||
| ## Nesting Variable References | ||
| The Serverless variable system allows you to nest variable references within each other for ultimate flexibility. So you can reference certain variables based on other variables. Here's an example: | ||
|
|
||
| ```yml | ||
| service: new-service | ||
| provider: aws | ||
| custom: | ||
| myFlexibleArn: ${env:${opt:stage}_arn} | ||
|
|
||
| functions: | ||
| hello: | ||
| handler: handler.hello | ||
|
|
||
| ``` | ||
|
|
||
| In the previous example, if you pass `dev` as a stage option, the framework will look for the `dev_arn` environment variable. If you pass `production`, the framework will look for `production_arn`, and so on. This allows you to creatively use multiple variables by using a certain naming pattern without having to update the values of these variables constantly. You can go as deep as you want in your nesting, and can reference variables at any level of nesting from any source (env, opt, self or file). | ||
|
|
||
| ## Overwriting Variables | ||
| The Serverless framework gives you an intuitive way to reference multiple variables as a fallback strategy in case one of the variables is missing. This way you'll be able to use a default value from a certain source, if the variable from another source is missing. | ||
|
|
||
| For example, if you want to reference the stage you're deploying to, but you don't want to keep on providing the `stage` option in the CLI. What you can do in `serverless.yml` is: | ||
|
|
||
|
|
||
| ```yml | ||
| service: new-service | ||
| provider: | ||
| name: aws | ||
| stage: dev | ||
| custom: | ||
| myStage: ${opt:stage, self:provider.stage} | ||
|
|
||
| functions: | ||
| hello: | ||
| handler: handler.hello | ||
| ``` | ||
|
|
||
| What this says is to use the `stage` CLI option if it exists, if not, use the default stage (which lives in `provider.stage`). So during development you can safely deploy with `serverless deploy`, but during production you can do `serverless deploy --stage production` and the stage will be picked up for you without having to make any changes to `serverless.yml`. | ||
|
|
||
| This overwrite functionality is super powerful. You can have as many variable references as you want, from any source you want, and each of them can be of different type and different name. | ||
|
|
||
| # Migrating serverless.env.yml | ||
| Previously we used the `serverless.env.yml` file to track Serverless Variables. It was a completely different system with different concepts. To migrate your variables from `serverless.env.yml`, you'll need to decide where you want to store your variables. | ||
|
|
||
| * Using a config file: You can still use `serverless.env.yml`, but the difference now is that you can structure the file however you want, and you'll need to reference each variable/property correctly in `serverless.yml`. For more info, you can check the file reference section above. | ||
| * Using the same `serverless.yml` file: You can store your variables in `serverless.yml` if they don't contain sensitive data, and then reference them elsewhere in the file using `self:someProperty`. For more info, you can check the self reference section above. | ||
| * Using environment variables: You can instead store your variables in environment variables and reference them with `env.someEnvVar`. For more info, you can check the environment variable reference section above. | ||
| * Making your variables stage/region specific: `serverless.env.yml` allowed you to have different values for the same variable based on the stage/region you're deploying to. You can achieve the same result by using the nesting functionality of the new variable system. For example, if you have two different ARNs, one for `dev` stage and the other for `prod` stage, you can do the following: `${env:${opt:stage}_arn}`. This will make sure the correct env var is referenced based on the stage provided as an option. Of course you'll need to export both `dev_arn` and `prod_arn` env vars on your local system. | ||
|
|
||
| Now you don't need `serverless.env.yml` at all, but you can still use it if you want. It's just not required anymore. Migrating to the new variable system is easy and you just need to know how the new system works and make small adjustments to how you store & reference your variables. | ||
|
|
||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.