mirror of
https://github.com/serverless/serverless.git
synced 2026-01-25 15:07:39 +00:00
docs for new variables system
This commit is contained in:
Eslam A. Hefnawy
parent
a2d37e7b5a
commit
8daff8f822
@ -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)
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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:
|
||||
|
||||
|
||||
@ -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)
|
||||
|
||||
@ -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.
|
||||
67
docs/understanding-serverless/serverless-variables.md
Normal file
67
docs/understanding-serverless/serverless-variables.md
Normal file
@ -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.
|
||||
@ -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:
|
||||
```
|
||||
```
|
||||
Loading…
x
Reference in New Issue
Block a user