serverless-s3obj
v0.0.2
Published
resolve object variables in s3 according to suffixes (yml, json)
Downloads
5
Readme
serverless-s3obj
serverless-s3obj is a serverless plugin that provides a means to include
partial yaml
or json
files stored in S3 within your serverless.yml
files. This is an extension of serverless built in s3 variable resolution
which simply interpolates the string body of the s3 object. This makes
it useless for things like snippets of related resources to be included
in your app's resources. s3obj takes things a step further to see if there is
a yml
, yaml
or json
extension to the object's key, and if so, parses it
as such so that you can render the contents into the generated cloudformation
templates underlying your serverless stacks.
Reasons you might want to use serverless-s3obj:
- You have collections of resources that you find yourself defining over and over for common scenarios, such as defining all the cloudformation resources for application load balancers fronting serverless microservices
- You want to distribute reusable snippets for use across an organization
- You want centralized control of portions of so that you can make changes in that central location and have it propagate to all your serverless apps
Usage
1. Create S3 bucket
Create an S3 bucket. How you do that and manage access is up to you, but this
is infrastructure that spans serverless applications, so do it outside of any
serverless.yml
files. For example purposes, we will use the name
infrastructure-bucket
.
2. Push yaml or json templates to your bucket
Again, these are cross-cutting bits of infrastructure-as-code that do not belong
to any one app. How you get the templates into the S3 bucket are up to you.
Maintain any yml
, yaml
or json
extensions the templates might have.
For example, the following snippet of cloudformation creates the security group, application load balancer, target group and listener needed to front an internall serverless app accessible only from your VPC.
Resources:
SecurityGroup:
Type: AWS::EC2::SecurityGroup
Properties:
GroupDescription: Generic HTTP Security Group
SecurityGroupIngress:
- CidrIp: # whatever your VPCs cidr range is for production
FromPort: 80
IpProtocol: tcp
ToPort: 80
VpcId: # whatever your vpc id is for production
LoadBalancer:
Type: AWS::ElasticLoadBalancingV2::LoadBalancer
Properties:
Scheme: internal
SecurityGroups:
- Ref: SecurityGroup
Subnets:
- # one of your private subnet ids for production
- # another of your private subnet ids for production
TargetGroup:
Type: AWS::ElasticLoadBalancingV2::TargetGroup
Properties:
TargetType: lambda
Listener:
Type: AWS::ElasticLoadBalancingV2::Listener
Properties:
DefaultActions:
- TargetGroupArn:
Ref: TargetGroup
Type: forward
LoadBalancerArn:
Ref: LoadBalancer
Port: 80
Protocol: HTTP
Outputs:
DnsName:
Value:
'Fn::GetAtt': [LoadBalancer, DNSName]
ALBName:
Value:
'Fn::GetAtt': [LoadBalancer, LoadBalancerFullName]
If you wanted to make this reusable across serverless applications with s3obj, you might place it at:
s3://infrastructure-bucket/production/alb.yml
You might place an analogous snippet for your development environment at:
s3://infrastructure-bucket/development/alb.yml
3. Use the serverless-s3obj plugin
In your serverless.yml
files, declare the plugin's usage like so:
plugins:
- serverless-s3obj
Make sure the module is installed with npm
, yarn
or whatever you
use.
4. Include templates
In your serverless.yml
files, use the s3obj
variable source to reference
centralized templates and snippets. For the ALB example above, we would have
a line like the following:
resources:
- ${s3obj:infrastructure-bucket/${opt:stage}/alb.yml
5. Reference the resources in templates (if needed)
If the templates and snippets included with s3obj define resources, you
can reference them by their logical name as defined in the template. Again
using our ALB example, we might define some functions in serverless.yml
to
be triggered by alb
events from our application load balancer in our private
subnets:
functions:
hello:
handler: handler.hello
events:
- alb:
listenerArn:
Ref: Listener
priority: 1
conditions:
path: /hello
Note the Ref
to the logical Listener
defined in the snippet stored in
s3 that we defined back in step 2.
6. Deploy your app
Deploy your app like you normally would with the serverless
cli. Whatever
is running the command will need to be able to access the objects in the
s3 bucket you defined. How you manage that is up to you. For example, we
might deploy the app to production using the alb.yml
snippet appropriate for
that environment with:
serverless deploy --stage production
The ${opt:stage}
in our s3obj reference in serverless.yml
below is replaced
with production
and your stacks will stand up a new ALB for your app that can
be used to lock it down to a private subnet:
resources:
- ${s3obj:infrastructure-bucket/${opt:stage}/alb.yml
Contributing
The scope of s3obj is simply to resolve variables sourced with s3obj
from
objects stored in s3. Contributions to that end are welcome. Contributions
that extend that scope will most likely not be accepted. I have no intention or
inclination to maintain something of a larger scope. Feel free to fork and take
in different directions if your needs require it.
Releasing
npm login
# increment version in package.json
yarn build
npm publish
TODO
This is in a very early stage, and for this to be a properly reliable open source tool, the following needs to happen:
- Write tests/specs
- Set up CI/builds