archive-gh-me/serverless
1
0
Fork 0
mirror of https://github.com/serverless/serverless.git synced 2026-01-25 15:07:39 +00:00
Code Issues Projects Releases Wiki Activity

Merge pull request #1315 from serverless/add-event-sources-concept-to-docs

Browse Source 
Add event sources concept to docs
This commit is contained in:
Philipp Muens 2016-06-14 08:48:40 +02:00 committed by GitHub
commit 76ebd07d8c
4 changed files with 186 additions and 93 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
docs/README.md
View File

@ -18,8 +18,9 @@ Serverless provides (such as service creation, deployment, removal, function inv
- [Event sources](/docs/tutorials/event-sources.md) - Learn how you can extend your services functionality with event
sources
- Concepts
- [plugins](/docs/concepts/plugins.md) - How plugins work
- [services](/docs/concepts/services.md) - Understanding Serverless services
- [event sources](/docs/concepts/event-sources.md) - Understanding different types of event sources
- [plugins](/docs/concepts/plugins.md) - How plugins work
- Plugins
- Core plugins
- [create](/docs/plugins/core/create.md) - Creates a new Serverless service

95
docs/concepts/event-sources.md Normal file
View File

@ -0,0 +1,95 @@
# Event sources
With Serverless you write event driven architectures. An event can be e.g. a HTTP request, a scheduled event or even
an event when someone uploads a file to your S3 bucket.
The `serverless.yaml` file makes it easy to add events to your functions.
Events are provider specific. Your functions can have as many events as you want it to support (even from different providers).
Serverless will take care and translates the events into provider specific resources when you deploy your service to the
provider of choice.
## How to use event sources
Events are defined inside the function of the `serverless.yaml` file.
Here's an example of a `users` function which implements an `S3` bucket event for AWS and a http endpoint for Azure:
```yaml
functions:
users:
handler: users.handler
events:
aws:
s3:
- photos
azure:
http_endpoint:
direction: in
name: req
```
Let's pretend we deploy this function to AWS.
Serverless will create or link the `photos` S3 bucket with the `users`function so the function get's triggered each time
a new file is uploaded or modified in the S3 bucket.
However Serverless will create a HTTP endpoint which will trigger the function every time a request comes in if we deploy
this function to Azure.
## Available event sources
Serverless supports the following event sources:
### AWS
Event sources for Amazon Web Services:
#### S3
Triggers the function every time an object is put or modified in a S3 bucket.
Examples:
```yaml
functions:
resize:
handler: resize
events:
aws:
s3:
- photos
```
```yaml
functions:
users:
handler: users.handler
events:
aws:
s3:
- photos
- personal-files
```
#### Schedule
Schedules the function execution.
Examples:
```yaml
functions:
crawl:
handler: crawl
events:
aws:
schedule: rate(2 hours)
```
```yaml
functions:
aggregate:
handler: statistics.handler
events:
aws:
schedule: rate(10 minutes)
```

30
docs/concepts/plugins.md
View File

@ -5,15 +5,15 @@ can build them, how easily testable they are and how approachable they are for o
The main goals for our plugin system are:
* Separation of CLI configuration and Plugin logic
* We want any plugin author to be able to easily create new commands within the serverless framework and extend
- Separation of CLI configuration and Plugin logic
- We want any plugin author to be able to easily create new commands within the serverless framework and extend
existing commands. To achieve this we need to create a strong separation between CLI and Plugins that has clear
interfaces between each other.
* Separation between logic of different plugins
* Different plugins need to have an easy way to run independently and after each other without defining dependencies
- Separation between logic of different plugins
- Different plugins need to have an easy way to run independently and after each other without defining dependencies
between each other.
* Greater Extensibility
* Plugins need to be able to easily integrate into the lifecycle of a command independent of other Plugins that are
- Greater Extensibility
- Plugins need to be able to easily integrate into the lifecycle of a command independent of other Plugins that are
running and can extend the functionality of Serverless easily.
## Concepts
@ -53,22 +53,22 @@ class HelloWorld {
We automatically put the name of the command in front of lifecycle events when they are used for hooks.
So in a hook the following syntax needs to be used.
* ***CommandName:LifecycleEventName***
- ***CommandName:LifecycleEventName***
Which would be ***deploy:resources*** in a hook definition (which we will show in more detail below).
In addition to the lifecycle events defined here we will create 2 additional events for each:
* ***before:CommandName:LifecycleEventName***
* ***after:CommandName:LifecycleEventName***
- ***before:CommandName:LifecycleEventName***
- ***after:CommandName:LifecycleEventName***
Following the above example we’ll have these lifecycle events:
* ***before:deploy:resources***
* ***deploy:resources***
* ***after:deploy:resources***
* ***before:deploy:functions***
* ***deploy:functions***
* ***after:deploy:functions***
- ***before:deploy:resources***
- ***deploy:resources***
- ***after:deploy:resources***
- ***before:deploy:functions***
- ***deploy:functions***
- ***after:deploy:functions***
These names will be used as hooks to include plugin logic. This allows to set up lifecycle events with generic names,
but still make sure they are only executed for specific commands.

151
docs/concepts/services.md
View File

@ -1,28 +1,26 @@
# Services
A *serverless service* is a group of one or multiple functions and any resources they require. By grouping related
functions together, it's easier to share code and and resources between those functions. Services are also designed to
A *serverless service* is a group of one or multiple functions and any resources they require. By grouping related
functions together, it's easier to share code and 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 which describe it:
* **serverless.yaml**
* Declares a serverless service
* Defines one or multiple functions in the service
* 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` array may automatically create the resources required for the event upon deployment
* Config can be specified for one or more IaaS providers
* Re-usable and publicly shareable
* Contains no author-specific information
- `serverless.yaml`
- Declares a serverless service
- Defines one or multiple functions in the service
- 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` array may automatically create the resources required for the event upon deployment
- Config can be specified for one or more IaaS providers
- Re-usable and publicly shareable
- Contains no author-specific information
* **serverless.meta.yaml**
* Contains author-specific information (not intended for version control)
* Defines stages for this service
* Defines stage-specific variables, which allows adding dynamic values to `serverless.yaml`, and helps keep out
- `serverless.env.yaml`
- Contains author-specific information (not intended for version control)
- Defines stages for this service
- Defines stage-specific variables, which allows adding dynamic values to `serverless.yaml`, and helps keep out
sensitive information
* The following variables are reserved: `service`, `function`, `stage` and `region`
* Specifies profiles or credentials to use per stage
## Examples
@ -36,91 +34,90 @@ users
node_modules
package.json
serverless.yaml
serverless.meta.yaml
serverless.env.yaml
users.js // single handler file, requires lib
```
#### serverless.yaml
```
```yaml
service: users
description: A simple service for creating users
functions:
create:
extend: $${defaults}
handler: users.create
events:
- http_endpoint_aws:
path: users
method: post
defaults:
name_template: ${service}-${stage}-${function}
include:
- ../parent/data.json
exclude:
- .git
aws_lambda_function:
runtime: nodejs4.3
timeout: 6
memory_size: 1024
resources:
- aws_name: ${service}-${stage}-resources
- aws_description: Resources for the ${service} service in the ${project} project.
- aws_dynamodb_table:
name: ${service}-${stage}-users
table_name: ${service}-${stage}-users
provisioned_throughput: 1
key_schema: id
plugins:
- plugin
- additional_plugin
default_providers: &default_providers
aws:
timeout: 6
memorySize: 1024
runtime: nodejs4.3
azure:
disabled: false
functions:
create:
name_template: ${stage}-${service}-${name}
handler: users.create
include:
- lib
- functions
exclude:
- .git
- tmp
events:
aws:
s3:
- firstbucket
- secondbucket
azure:
http_endpoint:
direction: in
name: req
resources:
aws_name_template: ${stage}-${service}-${name}
azure_name_template:
aws_lambda:
AWSTemplateFormatVersion: 2010-09-09
Description: CloudFormation Resources
Resources:
azure_functions:
$ref: ../azure_resources.json
google:
$ref: ../google_resources.yaml
```
#### serverless.meta.yaml
#### serverless.env.yaml
```
```yaml
vars: {}
stages:
dev:
extend: $${defaults}
creds:
awsProfile: # stage specific profile
vars:
stageVariable: helloworld1
regions:
aws_useast1:
creds:
awsProfile: # optional, stage + region specific credentials
vars:
regionVariable: helloworld2
dev:
vars: {}
regions:
aws_useast1:
vars:
iamRoleArnLambda: 'arn:aws:iam::12345678:role/crud-users-dev-IamRoleLambda-DJSKASD143'
defaults:
creds:
awsProfile: default-profile
vars:
project: myApp
```
## Deployment
These deployment steps always occur first:
* The `serverless.yaml` and `serverless.meta.yaml` files are loaded into two objects in memory (e.g., `service`, `meta`)
* If YAML is used, it's converted to JSON
* References using Serverless variable syntax `${}` or Serverless template syntax `$${}` are loaded
* Loop through the `resources` property and collect resources for the targeted provider
- The `serverless.yaml` and `serverless.env.yaml` files are loaded into memory
- If YAML is used, it's converted to JSON
- References using Serverless variable syntax `${}` or Serverless template syntax `$${}` are loaded
- Loop through the `resources` property and collect resources for the targeted provider
### Deployment On Amazon Web Services
If the targeted provider is AWS, and the `serverless.yaml` contains AWS resources, these additional steps occur:
* A default AWS CloudFormation template is loaded.
* All of the resources in the `resources` property are added to that template.
* The compute resources found in the `functions` are added to that template (e.g., AWS Lambda Functions).
* Each event in the `functions.yourFunction.events` property is processed. If it requires resources, these are also
- A default AWS CloudFormation template is loaded.
- All of the resources in the `resources` property are added to that template.
- The compute resources found in the `functions` are added to that template (e.g., AWS Lambda Functions).
- Each event in the `functions.yourFunction.events` property is processed. If it requires resources, these are also
added to the template.
### Deployment On Microsoft Azure