1 | # cloudfriend
|
2 |
|
3 | [![Build Status](https://travis-ci.org/mapbox/cloudfriend.svg?branch=master)](https://travis-ci.org/mapbox/cloudfriend)
|
4 |
|
5 | Helper functions for assembling CloudFormation templates in JavaScript
|
6 |
|
7 | ## Intrinsic functions and conditions
|
8 |
|
9 | These are functions that you can use in place of various CloudFormation objects.
|
10 |
|
11 | CloudFriend | CloudFormation
|
12 | --- | ---
|
13 | base64(value) | [Fn::Base64](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-base64.html)
|
14 | findInMap(mapping, key, attr) | [Fn::FindInMap](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-findinmap.html)
|
15 | getAtt(obj, key) | [Fn::GetAtt](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-getatt.html)
|
16 | getAzs(region) | [Fn::GetAZs](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-getavailabilityzones.html)
|
17 | join(delimiter, pieces) | [Fn::Join](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-join.html)
|
18 | split(delimiter, string) | [Fn::Split](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-split.html)
|
19 | select(index, list) | [Fn::Select](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-select.html)
|
20 | ref(name) | [Ref](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html)
|
21 | userData(list) | [Fn::Base64](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-base64.html) and [Fn::Join](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-join.html) with `\n` delimiter
|
22 | and(conditions) | [Fn::And](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-conditions.html#d0e121706)
|
23 | equals(a, b) | [Fn::Equals](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-conditions.html#d0e121788)
|
24 | if(condition, ifTrue, ifFalse) | [Fn::If](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-conditions.html#d0e121863)
|
25 | not(condition) | [Fn::Not](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-conditions.html#d0e122042)
|
26 | or(conditions) | [Fn::Or](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-conditions.html#d0e122130)
|
27 | notEquals(a, b) | [Fn::Not](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-conditions.html#d0e122042) and [Fn::Equals](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-conditions.html#d0e121788)
|
28 | sub(str, variables) | [Fn::Sub](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-sub.html)
|
29 | importValue(sharedValue) | [Fn::ImportValue](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-importvalue.html),
|
30 | arn(service, suffix) | [Fn::Sub](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-sub.html) designed for an ARN
|
31 |
|
32 | ## Pseudo parameters
|
33 |
|
34 | These are static properties of `cloudfriend` that you can use to reference various CloudFormation objects.
|
35 |
|
36 | CloudFriend | CloudFormation
|
37 | --- | ---
|
38 | accountId | [AWS::AccountId](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/pseudo-parameter-reference.html)
|
39 | notificationArns | [AWS::NotificationARNs](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/pseudo-parameter-reference.html)
|
40 | noValue | [AWS::NoValue](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/pseudo-parameter-reference.html)
|
41 | region | [AWS::Region](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/pseudo-parameter-reference.html)
|
42 | stackId | [AWS::StackId](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/pseudo-parameter-reference.html)
|
43 | stackName | [AWS::StackName](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/pseudo-parameter-reference.html)
|
44 | partition | [AWS::Partition](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/pseudo-parameter-reference.html#cfn-pseudo-param-partition)
|
45 | urlSuffix | [AWS::URLSuffix](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/pseudo-parameter-reference.html#cfn-pseudo-param-urlsuffix)
|
46 |
|
47 | ## Shortcuts
|
48 |
|
49 | Cloudfriend contains a library of JS classes that reduce the amount of "boilerplate" CloudFormation that you need to write in order to setup a common set of AWS Resources. See [the shortcuts readme for more information](./lib/shortcuts/readme.md).
|
50 |
|
51 | ## Other helpers
|
52 |
|
53 | method | description
|
54 | --- | ---
|
55 | build(file, opts) | Builds a template defined by a static JavaScript export, a synchronous or an asynchronous function.
|
56 | validate(file) | Uses the `cloudformation:ValidateTemplate` API call to perform rudimentary template validation
|
57 | merge(...template) | Merges templates together. Throws errors if logical names are reused
|
58 |
|
59 | ## CLI tools
|
60 |
|
61 | By installing cloudfriend globally, it can provide you with simple CLI tools for building and validating CloudFormation templates.
|
62 |
|
63 | ```
|
64 | # either...
|
65 | $ git clone https://github.com/mapbox/cloudfriend && cd cloudfriend && npm link
|
66 | # ... or ...
|
67 | $ npm install -g @mapbox/cloudfriend
|
68 | ```
|
69 |
|
70 | Then, to build a template:
|
71 |
|
72 | ```
|
73 | # Prints the template as JSON to stdout
|
74 | $ build-template path/to/template.js
|
75 | ```
|
76 |
|
77 | Or, to validate a template:
|
78 |
|
79 | ```
|
80 | # Make sure that your shell is configured to make AWS requests
|
81 | $ validate-template path/to/template.js
|
82 | ```
|
83 |
|
84 | You may also specify a region for validation:
|
85 |
|
86 | ```
|
87 | # Make sure that your shell is configured to make AWS requests
|
88 | $ validate-template path/to/template.js us-east-1
|
89 | ```
|