1 | /**
|
2 | * # Kes: Making deployment with CloudFormation Fun
|
3 | *
|
4 | * Kes helps with managing and deploying AWS resources using CloudFormation.
|
5 | *
|
6 | * It makes it much easier to deploy lambda functions and create API gateway resources.
|
7 | *
|
8 | * ## Installation
|
9 | *
|
10 | * ```bash
|
11 | * $ npm install -g kes
|
12 | * $ kes -h
|
13 | *
|
14 | * Usage: kes TYPE COMMAND [options]
|
15 | *
|
16 | * Start a Kes project
|
17 | *
|
18 | * Options:
|
19 | *
|
20 | * -V, --version output the version number
|
21 | * -p, --profile <profile> AWS profile name to use for authentication
|
22 | * --role <role> AWS role arn to be assumed for the deployment
|
23 | * -c, --config <config> Path to config file
|
24 | * --env-file <envFile> Path to env file
|
25 | * --cf-file <cfFile> Path to CloudFormation templateUrl
|
26 | * -t, --template <template> A kes application template used as the base for the configuration
|
27 | * --kes-class <kesClass> Kes Class override
|
28 | * -k, --kes-folder <kesFolder> Path to config folder
|
29 | * -r, --region <region> AWS region
|
30 | * --stack <stack> stack name, defaults to the config value
|
31 | * -d, --deployment <deployment> Deployment name, default to default
|
32 | * -h, --help output usage information
|
33 | *
|
34 | * Commands:
|
35 | * cf [deploy|validate|compile] CloudFormation Operations:
|
36 | * create Creates the CF stack (deprecated, start using deploy)
|
37 | * update Updates the CF stack (deprecated, start using deploy)
|
38 | * upsert Creates the CF stack and Update if already exists (deprected, start using deploy)
|
39 | * deploy Creates the CF stack and Update if already exists
|
40 | * validate Validates the CF stack
|
41 | * compile Compiles the CF stack
|
42 | * lambda <lambdaName> uploads a given lambda function to Lambda service
|
43 | *
|
44 | * ```
|
45 | *
|
46 | * ## Setting Up the First Project
|
47 | *
|
48 | * Go to your project directory and run the following command.
|
49 | *
|
50 | * ```bash
|
51 | * $ npm init
|
52 | * ```
|
53 | *
|
54 | * This will create a `.kes` folder on your project folder. It will include the following files:
|
55 | *
|
56 | * | file | description
|
57 | * | ---- | -------------
|
58 | * |`.env`| This optional file can hold your project secrets and should not be committed
|
59 | * |`cloudformation.template.yml`| A base CF template written with Mustache/Handlebar templating language
|
60 | * |`config.yml`| The main required configuration file for a kes deployment
|
61 | * |`kes.js`| An optional Kes class override that can change how Kes class is used
|
62 | *
|
63 | * The `cloudformation.template.yml` and `config.yml` are required files.
|
64 | * The variables in `config.yml` are parsed and used to generate the `cloudformation.yml`. By default,
|
65 | * the `default` section of the `config.yml` is parsed and used in `cloudformation.template.yml`. If
|
66 | * another deployment is specified in the `config.yml` the values of that deployment overrides the
|
67 | * values of `default`
|
68 | * file which is sent to AWS CloudFormation to create and udpate the stack.
|
69 | *
|
70 | * ### CF Stack Name
|
71 | * The Cloudformation stack name is the same as `stackName` in `config.yml`.
|
72 | *
|
73 | * ### Parameters
|
74 | *
|
75 | * To pass parameters to the CloudFormation template, use the `parameters` key in config.yml. Example:
|
76 | *
|
77 | * ```yaml
|
78 | * # config.yml
|
79 | * default:
|
80 | * stackName: myStack
|
81 | * parameters:
|
82 | * - name: MyParameter
|
83 | * value: someValue
|
84 | * ```
|
85 | *
|
86 | * ```yaml
|
87 | * # cloudformation.template.yml
|
88 | * AWSTemplateFormatVersion: '2010-09-09'
|
89 | * Description: 'stack: {{stackName}} | deployed by Kes'
|
90 | * Parameters:
|
91 | * MyParameter:
|
92 | * Type: String
|
93 | * Description: 'My parameter'
|
94 | * ```
|
95 | *
|
96 | * ### CF Capabailities
|
97 | *
|
98 | * To pass capabilities such as `CAPABILITY_IAM` use `capabilities` key:
|
99 | *
|
100 | * ```yaml
|
101 | * # config.yml
|
102 | * default:
|
103 | * stackName: myStack
|
104 | * parameters:
|
105 | * - name: MyParameter
|
106 | * value: someValue
|
107 | * capabilities:
|
108 | * - CAPABILITY_IAM
|
109 | * ```
|
110 | *
|
111 | * ### CloudFormation Tagging
|
112 | *
|
113 | * To manage tags associated with your CloudFormation stack, use the `tags` key:
|
114 | *
|
115 | * ```yaml
|
116 | * # config.yml
|
117 | * default:
|
118 | * tags:
|
119 | * color: orange
|
120 | * tree: oak
|
121 | * ```
|
122 | *
|
123 | * ### Lambda Functions
|
124 | * To add lambda functions, use `lambdas` key and add them as array object.
|
125 | * The lambda function code can be either a folder or file on your computer
|
126 | * or a zip file on aws.
|
127 | *
|
128 | * **Note:** In version 2.0.0 of kes, the lambda packaging is handled natively in nodejs.
|
129 | * If you point the `source` to a directory, the directory is saved at the root of the zip
|
130 | * package. This changes how handler path should be setup.
|
131 | *
|
132 | * For example, if the `index.js` is located at `/path/to/package/index.js` and
|
133 | * `source: /path/to/package/index.js`, the handler should be `handler: index.handler`.
|
134 | *
|
135 | * **Required Fields:**
|
136 | * - name
|
137 | * - handler
|
138 | * - source/s3Source
|
139 | *
|
140 | * **Env Variables:**
|
141 | * You can add env variables to each lambda function as shown in the example below.
|
142 | *
|
143 | * **Example:**
|
144 | *
|
145 | * ```yaml
|
146 | * # config.yml
|
147 | * default:
|
148 | * stackName: myStack
|
149 | * parameters:
|
150 | * - name: MyParameter
|
151 | * value: someValue
|
152 | * capabilities:
|
153 | * - CAPABILITY_IAM
|
154 | *
|
155 | * lambdas:
|
156 | * - name: myLambda1
|
157 | * handler: index.handler
|
158 | * timeout: 200
|
159 | * source: 'node_modules/someNpmPackage'
|
160 | * - name: myLambda2
|
161 | * handler: package.handler
|
162 | * timeout:100
|
163 | * s3Source:
|
164 | * bucket: mybucket
|
165 | * key: mylambda.zip
|
166 | * envs:
|
167 | * DEBUG: true
|
168 | * ```
|
169 | *
|
170 | * **Note:**
|
171 | *
|
172 | * Adding lambda functions in the config.yml has no effect unless you add
|
173 | * the relevant CF syntax to `cloudformation.template.yml`
|
174 | *
|
175 | * ### Handlebar Helpers
|
176 | * We use [Handlebar](http://handlebarsjs.com/) for templating a CF template.
|
177 | *
|
178 | * **Each**
|
179 | *
|
180 | * ```yaml
|
181 | * # config.yml
|
182 | * default:
|
183 | * myArray:
|
184 | * - name: name1
|
185 | * - name: name2
|
186 | * ```
|
187 | *
|
188 | * ```yaml
|
189 | * # cloudformation.template.yml
|
190 | * Resources:
|
191 | *
|
192 | * {{# each myArray}}
|
193 | * {{name}}:
|
194 | * Type: SomeAWSResource
|
195 | * {{/each}}
|
196 | * ```
|
197 | *
|
198 | * **If/else**
|
199 | *
|
200 | * ```yaml
|
201 | * # config.yml
|
202 | * default:
|
203 | * myArray:
|
204 | * - name: name1
|
205 | * runtime: python2.7
|
206 | * - name: name2
|
207 | * ```
|
208 | *
|
209 | * ```yaml
|
210 | * # cloudformation.template.yml
|
211 | * Resources:
|
212 | *
|
213 | * {{# each myArray}}
|
214 | * {{name}}:
|
215 | * Type: SomeAWSResource
|
216 | * Properties:
|
217 | * Runtime: {{# if runtime}}{{runtime}}{{else}}nodejs6.10{{/if}}
|
218 | * {{/each}}
|
219 | * ```
|
220 | *
|
221 | * **Each for Objects**
|
222 | *
|
223 | * ```yaml
|
224 | * # config.yml
|
225 | * default:
|
226 | * myArray:
|
227 | * - DEBUG: true
|
228 | * ```
|
229 | *
|
230 | * ```yaml
|
231 | * # cloudformation.template.yml
|
232 | * Resources:
|
233 | *
|
234 | * {{# each myArray}}
|
235 | * Lambda:
|
236 | * Type: SomeAWSResource
|
237 | * Properties:
|
238 | * Environments:
|
239 | * - {{@key}}: {{this}}
|
240 | * {{/each}}
|
241 | * ```
|
242 | *
|
243 | * ## Deployment
|
244 | *
|
245 | * To create a CF stack or update and existing one run
|
246 | * ```bash
|
247 | * kes cf deploy
|
248 | * ```
|
249 | *
|
250 | * ### Differenet deployment configurations
|
251 | *
|
252 | * You can configure different values for different deployments. For example you might want to configure your test deployment
|
253 | * differently from your staging and production deployments. Here is how to achieve it:
|
254 | *
|
255 | * ```yaml
|
256 | * # config.yml
|
257 | * default:
|
258 | * stackName: myStack-test
|
259 | * myArray:
|
260 | * - DEBUG: true
|
261 | *
|
262 | * staging:
|
263 | * stackName: myStack-staging
|
264 | * myArray:
|
265 | * - DEBUG: false
|
266 | * ```
|
267 | *
|
268 | * To deploy a stack with the `staging` configuration run:
|
269 | *
|
270 | * ```bash
|
271 | * kes cf deploy --deployment staging
|
272 | * ```
|
273 | *
|
274 | *
|
275 | * ## Deployment Using IAM Role
|
276 | *
|
277 | * You can specify an IAM role for the deployment using `--role` option or by setting `AWS_DEPLOYMENT_ROLE` environment variable.
|
278 | *
|
279 | * **Note:** You still need an aws user with AssumeRole permission for this to work
|
280 | *
|
281 | * ```bash
|
282 | * kes cf deploy --profile myUser --role arn:aws:iam::00000000000:role/myDeplymentRole
|
283 | * ```
|
284 | *
|
285 | * ### Updating One Lambda Function
|
286 | * To update one lambda function outside of CF
|
287 | *
|
288 | * ```bash
|
289 | * kes lambda myLambda
|
290 | * ```
|
291 | *
|
292 | * ## Use Templates
|
293 | * Kes enables you to distribute your AWS applications built with kes using a concept called template. A template is essentially a `.kes` folder with
|
294 | * a `cloudformation.template.yml`, a `config.yml` and a `kes.js` if needed.
|
295 | *
|
296 | * The user of a template can point to your template folder with the `--template` flag and the kes command will use the template to build the cloudformation.yml.
|
297 | *
|
298 | * The user still has the option of creating her own `config.yml` and `cloudformation.template.yml`. Any variables in these files will override existing ones
|
299 | * in the template or append it if it doesn't exist.
|
300 | *
|
301 | * This setup gives users of the templates a great degree of flexibility and ownership.
|
302 | *
|
303 | */
|