Skip to content

Latest commit

 

History

History
154 lines (122 loc) · 8.13 KB

README.md

File metadata and controls

154 lines (122 loc) · 8.13 KB
Raw

cfn-resolver-lib

Build Status codecov depend bot npm version

JavaScript library that resolves and evaluates values in AWS CloudFormation templates based on the provided stack parameters and produces the JS object representation of the resolved CFN template.

Did you ever had to debug what's wrong with your AWS CloudFormation template and why your stack deployment fails? Your YAML/JSON could contain some logic with all kinds of nested intrinsic functions and CFN pseudo parameters and sometimes this can get even more complex when you use a tool (e.g. AWS CDK) that generates the file for you.

If you have more than couple of these in your templates it is quite time consuming to figure out which exactly caused the deployment to fail. This simple tool (cfn-resolver-lib and cfn-resolver-cli) tries to mitigate the issue by evaluating these logic and provide the final exact values that will be used in deployment time.

cfn-resolver can help you

  • understand your CFN template better
  • troubleshoot CloudFormation deployment issues faster
  • secure your IaC with unit tests that assert on exact values before actually deploying anything
    • e.g. your unit test now can assert that the s3_reader IAM user has access to prod-uswest2-redshift-log S3 bucket in us-west-2 region in your prod stack.

CLI and Examples

Check out cfn-resolver-cli

How to use?

Install the npm package

npm i cfn-resolver-lib

Write your JavaScript code:

const NodeEvaluator = require('cfn-resolver-lib');

const stackParameters = {
  RefResolvers:
  {
      "AWS::Region": "us-west-2",
      "AWS::Partition": "aws",
      "AWS::AccountId": "000000111111",
      "Stage": "prod",
      "AWS::StackId": "MyEvaluatedFakeStackUsWest2"
  }
};

const resolvedObj = new NodeEvaluator(cloufFormationTemplateDeseralizedObj, stackParameters).evaluateNodes();

Alternative usage: create NodeEvaluator instance once and reuse multiple times for different parameter sets:

const NodeEvaluator = require('cfn-resolver-lib');

const nodeEvaluator = new NodeEvaluator(cloufFormationTemplateDeseralizedObj);

const stackParameters1 = {
  RefResolvers:
  {
      "AWS::Region": "us-west-2",
      "AWS::Partition": "aws",
      "AWS::AccountId": "000000111111",
      "Stage": "prod",
      "AWS::StackId": "MyEvaluatedFakeStackUsWest2"
  }
};

const stackParameters2 = {
  RefResolvers:
  {
      "AWS::Region": "us-east-1",
      "AWS::Partition": "aws",
      "AWS::AccountId": "000000112222",
      "Stage": "beta",
      "AWS::StackId": "MyEvaluatedFakeStackUsEast1"
  }
};

const resolvedObj1 = nodeEvaluator.evaluateNodes(stackParameters1);
const resolvedObj2 = nodeEvaluator.evaluateNodes(stackParameters2);

Extensibility & Customization

You can pass additional resolver maps to the NodeEvaluator instance, just like RefResolvers to customize or override the built-in behaviour.

Fn::GetAtt resolution

By default the tool tries to resolve the attributes of resources that are defined within the template itself, but you have the opportunity to override the behaviour for specific cases. Just define the Fn::GetAtt resolver map for custom attribute resolution:

{
    "Fn::GetAttResolvers": {
      MyResourceLogicalId1: {
        "AttribeteKey1": "TheOverridenAttributeValue"
      }
  }
}

ARN resolution

With Fn::GetAtt you can refer to ARN of an other resource defined in the template. The tool supports ARN resolution for some of the most common AWS CloudFormation resource types (Lambda function, SQS queue, SNS topic, S3 bucket, DyanmoDB Table, etc), but user can provide additional ARN shemas to NodeEvaulator intance:

{ 
  "ArnSchemas": {
    "AWS::DynamoDB::Table": "arn:${Partition}:dynamodb:${Region}:${Account}:table/${TableName}"
  }
}

The ${Partition}, ${Region} and ${Region} placeholders will be resolved by using the stack parameters. The last placeholder of the arn schema (in the above example ${TableName}) will be resolved from the attribute from the resource (if both the resource and its attribute can be found in the template).

Fn::ImportValue resolvers

Define your Fn::ImportValue resolvers in the parameter map as the following:

{ 
  "Fn::ImportValueResolvers": {
    "OtherStacksExportedKey1": "MyFakeImportedValue1"
  }
}

Supported Features

Unsported Features

Roadmap

  • Enchance Fn::Sub to work with template parameter names, resource logical IDs, resource attributes intrinsic-function-reference-importvalue.html
  • Support Fn::Base64
  • Support Fn::Cidr
  • Add linter/debugging features by identified valudation errors and warnings found during template evaluation (e.g. like cfn-lint)

Contribution

Feel free to implement any missing features or fix bugs. In any case don't forget to add unit tests.