kes

### Table of Contents - [Config](#config) - [parse](#parse) - [flatten](#flatten) - [Kes](#kes) - [describeStack](#describestack) - [updateSingleLambda](#updatesinglelambda) - [compileCF](#compilecf) - [uploadToS3](#uploadtos3) - [uploadCF](#uploadcf) - [waitFor](#waitfor) - [cloudFormation](#cloudformation) - [validateTemplate](#validatetemplate) - [describeCF](#describecf) - [deleteCF](#deletecf) - [opsStack](#opsstack) - [upsertStack](#upsertstack) - [deployStack](#deploystack) - [createStack](#createstack) - [updateStack](#updatestack) - [deleteStack](#deletestack) - [Lambda](#lambda) - [buildS3Path](#builds3path) - [getHash](#gethash) - [zipLambda](#ziplambda) - [uploadLambda](#uploadlambda) - [zipAndUploadLambda](#zipanduploadlambda) - [process](#process) - [updateSingleLambda](#updatesinglelambda-1) - [localRun](#localrun) - [zip](#zip) - [exec](#exec) - [configureAws](#configureaws) - [fileToString](#filetostring) - [mergeYamls](#mergeyamls) - [determineKesClass](#determinekesclass) - [failure](#failure) - [success](#success) - [getSystemBucket](#getsystembucket) ## Config This class handles reading and parsing configuration files. It primarily reads `config.yml` and `.env` files **Parameters** - `options` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** a js object that includes required options. - `options.stack` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** the stack name - `options.deployment` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the deployment name (optional, default `null`) - `options.region` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the aws region (optional, default `'us-east-1'`) - `options.profile` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the profile name (optional, default `null`) - `options.kesFolder` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the path to the kes folder (optional, default `'.kes'`) - `options.configFile` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the path to the config.yml (optional, default `'config.yml'`) - `options.envFile` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the path to the .env file (optional, default `'.env'`) - `options.cfFile` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the path to the CF template (optional, default `'cloudformation.template.yml'`) - `stack` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Stack name - `deployment` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Deployment name - `configFile` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** path to the config.yml file - `envFile` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** path to the .env file (optional) **Examples** ```javascript const config = new Config('mystack', 'dev', '.kes/config.yml', '.kes/.env'); ``` ### parse Main method of the class. It parses a configuration and returns it as a JS object. **Examples** ```javascript const configInstance = new Config(null, null, 'path/to/config.yml', 'path/to/.env'); config = configInstance.parse(); ``` Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** the configuration object ### flatten Return a javascript object (not a class instance) of the config class Returns **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** a javascript object version of the class ## Kes The main Kes class. This class is used in the command module to create the CLI interface for kes. This class can be extended in order to override and modify the behavior of kes cli. **Parameters** - `config` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** an instance of the Config class (config.js) **Examples** ```javascript const { Kes, Config } = require('kes'); const options = { stack: 'myStack' }; const config = new Config(options); const kes = new Kes(config); // create a new stack kes.deployStack() .then(() => describeCF()) .then(() => updateSingleLambda('myLambda')) .catch(e => console.log(e)); ``` ### describeStack Describe CF stacks by calling the describeStacks CF SDK function. If the describeStacks call gets throttled by AWS, retry the describeStacks operation **Parameters** - `stackName` stack name Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)>** promise that resolves to an Object with information about the CF stack ### updateSingleLambda Updates code of a deployed lambda function **Parameters** - `name` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the name of the lambda function defined in config.yml Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)** returns the promise of an AWS response object ### compileCF Compiles a CloudFormation template in Yaml format. Reads the configuration yaml from `.kes/config.yml`. Writes the template to `.kes/cloudformation.yml`. Uses `.kes/cloudformation.template.yml` as the base template for generating the final CF template. Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)** returns the promise of an AWS response object ### uploadToS3 This is just a wrapper around AWS s3.upload method. It uploads a given string to a S3 object. **Parameters** - `bucket` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the s3 bucket name - `key` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the path and name of the object - `body` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the content of the object Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)** returns the promise of an AWS response object ### uploadCF Uploads the Cloud Formation template to a given S3 location Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)** returns the promise of an AWS response object ### waitFor Wait for the current stack and log the current outcome **Parameters** - `wait` Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)** undefined ### cloudFormation Calls CloudFormation's update-stack or create-stack methods Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)** returns the promise of an AWS response object ### validateTemplate Validates the CF template Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)** returns the promise of an AWS response object ### describeCF Describes the cloudformation stack deployed Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)** returns the promise of an AWS response object ### deleteCF Deletes the current stack Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)** undefined ### opsStack Generic create/update method for CloudFormation Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)** returns the promise of an AWS response object ### upsertStack [Deprecated] Creates a CloudFormation stack for the class instance If exists, will update the existing one Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)** returns the promise of an AWS response object ### deployStack Creates a CloudFormation stack for the class instance If exists, will update the existing one Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)** returns the promise of an AWS response object ### createStack [Deprecated] Creates a CloudFormation stack for the class instance Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)** returns the promise of an AWS response object ### updateStack [Deprecated] Updates an existing CloudFormation stack for the class instance Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)** returns the promise of an AWS response object ### deleteStack Deletes the main stack Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)** returns the promise of an AWS response object ## Lambda Copy, zip and upload lambda functions to S3 **Parameters** - `config` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** the configuration object - `kesFolder` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the path to the `.kes` folder - `bucket` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the S3 bucket name - `key` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the main folder to store the data in the bucket (stack) ### buildS3Path Adds hash value, bucket name, and remote and local paths for lambdas that have source value. If a s3Source is usaed, only add remote and bucket values **Parameters** - `lambda` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** the lambda object Returns **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** the lambda object ### getHash calculate the hash value for a given path **Parameters** - `folderName` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** directory path - `method` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** hash type, default to shasum Returns **[buffer](https://nodejs.org/api/buffer.html)** hash value ### zipLambda zip a given lambda function source code **Parameters** - `lambda` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** the lambda object Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)** returns the promise of the lambda object ### uploadLambda Uploads the zipped lambda code to a given s3 bucket if the zip file already exists on S3 it skips the upload **Parameters** - `lambda` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** the lambda object. It must have the following properties - `lambda.bucket` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the s3 buckt name - `lambda.remote` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the lambda code's key (path and filename) on s3 - `lambda.local` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the zip files location on local machine Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)** returns the promise of updated lambda object ### zipAndUploadLambda Zips and Uploads a lambda function. If the source of the function is already zipped and uploaded, it skips the step only updates the lambda config object. **Parameters** - `lambda` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** the lambda object. Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)** returns the promise of updated lambda object ### process Zips and Uploads lambda functions in the configuration object. If the source of the function is already zipped and uploaded, it skips the step only updates the lambda config object. If the lambda config includes a link to zip file on S3, it skips the whole step. Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)** returns the promise of updated configuration object ### updateSingleLambda Uploads the zip code of a single lambda function to AWS Lambda **Parameters** - `name` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** name of the lambda function Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)** returns AWS response for lambda code update operation ## localRun A simple helper for running a function if `local` is passed as argument **Parameters** - `func` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** A javascript function **Examples** ```javascript // test.js const { localRun } = require('kes'); localRun(() => { console.log('my function'); }); // result // $ node test.js local // my function ``` Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** returns the result of the function call ## zip Zips a list of files or directories **Parameters** - `zipFile` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** filename and path where the zip file is stored - `srcList` **[array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)** array of files and directories paths - `dstPath` **type** for directories whether to put the directories at root of the zip file or relative to your path on the local machine Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)** ## exec Executes shell commands synchronously and logs the stdout to console. **Parameters** - `cmd` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Bash command - `verbose` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** whether to post stdout to console (optional, default `true`) Returns **[Buffer](https://nodejs.org/api/buffer.html)** The command's stdout in for of Buffer ## configureAws Updates region of an AWS configuration and point to the correct of profile on ~/.aws/credentials file if necessary **Parameters** - `region` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** AWS region (optional, default `'us-east-1'`) - `profile` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** aws credentials profile name (optional, default `null`) - `role` ## fileToString Checks if the input is a file, if it is a file, it reads it and return the content, otherwise just pass the input as an output **Parameters** - `file` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** A file path or a string Returns **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** String content of a given file ## mergeYamls Merges two yaml files. The merge is done using lodash.merge and it happens recursively. Meaning that values of file2 will replace values of file 1 if they have the same key. **Parameters** - `file1` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Yaml path to file 1 or file 1 string - `file2` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Yaml path to file 2 or file 2 string Returns **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Merged Yaml file in string format ## determineKesClass Based on the information passed from the CLI by the commander module this function determines whether to use the default Kes class or use the override class provided by the user **Parameters** - `options` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** The options passed by the commander library - `Kes` **Class** the default kes class Returns **Class** Kes class ## failure In case of error logs the error and exit with error 1 **Parameters** - `e` **[Error](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error)** error object ## success Exists the process when called ## getSystemBucket Discover and returns the system bucket used for deployment **Parameters** - `config` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** cumulus config object Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** name of the bucket