CDK SSM Document

AWS CDK L3 construct for managing SSM Documents.

CloudFormation's support for SSM Documents currently is lacking updating functionality. Instead of updating a document, CFN will replace it. The old document is destroyed and a new one is created with a different name. This is problematic because:

• When names potentially change, you cannot directly reference a document
• Old versions are permanently lost

This construct provides document support in a way you'd expect it:

• Changes on documents will cerate new versions
• Versions cannot be deleted

Usage

Creating a document from a YAML or JSON file

import cdk = require('@aws-cdk/core');
import { Document } from 'cdk-ssm-document';
import fs = require('fs');
import path = require('path');

export class TestStack extends cdk.Stack {
    constructor(scope: cdk.Construct, id: string, props: cdk.StackProps) {
        super(scope, id, props);

        const file = path.join(__dirname, '../documents/hello-world.yml');
        new Document(this, 'SSM-Document-HelloWorld', {
            name: 'HelloWorld',
            content: fs.readFileSync(file).toString(),
        });
    }
}

Creating a document via inline definition

import cdk = require('@aws-cdk/core');
import { Document } from 'cdk-ssm-document';
import fs = require('fs');
import path = require('path');

export class TestStack extends cdk.Stack {
    constructor(scope: cdk.Construct, id: string, props: cdk.StackProps) {
        super(scope, id, props);

        new Document(this, 'SSM-Document-HelloWorld', {
            name: 'HelloWorld',
            content: {
                schemaVersion: '2.2',
                description: 'Echo Hello World!',
                parameters: {
                    text: {
                        default: 'Hello World!',
                        description: 'Text to echo',
                        type: 'String',
                    },
                },
                mainSteps: [
                    {
                        name: 'echo',
                        action: 'aws:runShellScript',
                        inputs: {
                            runCommand: [
                                'echo "{{text}}"',
                            ],
                        },
                        precondition: {
                            StringEquals: [
                                'platformType',
                                'Linux',
                            ],
                        },
                    },
                ],
            },
        });
    }
}

Deploy all YAML/JSON files from a directory

import cdk = require('@aws-cdk/core');
import { Document } from 'cdk-ssm-document';
import fs = require('fs');
import path = require('path');

export class TestStack extends cdk.Stack {
    constructor(scope: cdk.Construct, id: string, props: cdk.StackProps) {
        super(scope, id, props);

        const dir = path.join(__dirname, '../documents');
        const files = fs.readdirSync(dir);

        for (const i in files) {
            const name = files[i];
            const shortName = name.split('.').slice(0, -1).join('.'); // removes file extension
            const file = `${dir}/${name}`;

            new Document(this, `SSM-Document-${shortName}`, {
                name: shortName,
                content: fs.readFileSync(file).toString(),
            });
        }
    }
}

Using the Lambda as a custom resource in CloudFormation - without CDK

If you're still not convinced to use the AWS CDK, you can still use the Lambda as a custom resource in your CFN template. Here is how:

1. Create a zip file for the Lambda:

   To create a zip from the Lambda source run:

   lambda/build

   This will generate the file lambda/code.zip.

2. Upload the Lambda function:

   Upload this zip file to an S3 bucket via cli, Console or however you like.

   Example via cli:

   aws s3 cp lambda/code.zip s3://example-bucket/code.zip

3. Deploy a CloudFormation stack utilizing the zip as a custom resource provider:

   Example CloudFormation template:

   ---
   AWSTemplateFormatVersion: "2010-09-09"
   Resources:
     SSMDocExecutionRole:
       Type: AWS::IAM::Role
       Properties:
         RoleName: CFN-Resource-Custom-SSM-Document
         AssumeRolePolicyDocument:
           Version: "2012-10-17"
           Statement:
             - Effect: Allow
               Principal:
                 Service: lambda.amazonaws.com
               Action: sts:AssumeRole
         ManagedPolicyArns:
           - arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
           - Ref: SSMDocExecutionPolicy
   
     SSMDocExecutionPolicy:
       Type: AWS::IAM::ManagedPolicy
       Properties:
         ManagedPolicyName: CFN-Resource-Custom-SSM-Document
         PolicyDocument:
           Version: "2012-10-17"
           Statement:
             - Effect: Allow
               Action:
                 - ssm:ListDocuments
                 - ssm:ListTagsForResource
               Resource: "*"
             - Effect: Allow
               Action:
                 - ssm:CreateDocument
                 - ssm:AddTagsToResource
               Resource: "*"
               Condition:
                 StringEquals:
                   aws:RequestTag/CreatedBy: CFN::Resource::Custom::SSM-Document
             - Effect: Allow
               Action:
                 - ssm:DeleteDocument
                 - ssm:DescribeDocument
                 - ssm:GetDocument
                 - ssm:ListDocumentVersions
                 - ssm:ModifyDocumentPermission
                 - ssm:UpdateDocument
                 - ssm:UpdateDocumentDefaultVersion
                 - ssm:AddTagsToResource
                 - ssm:RemoveTagsFromResource
               Resource: "*"
               Condition:
                 StringEquals:
                   aws:ResourceTag/CreatedBy: CFN::Resource::Custom::SSM-Document
   
     SSMDocFunction:
       Type: AWS::Lambda::Function
       Properties:
         FunctionName: CFN-Resource-Custom-SSM-Document-Manager
         Code:
           S3Bucket: example-bucket
           S3Key: code.zip
         Handler: index.handler
         Runtime: nodejs10.x
         Timeout: 3
         Role: !GetAtt SSMDocExecutionRole.Arn
   
     MyDocument:
       Type: Custom::SSM-Document
       Properties:
         Name: MyDocument
         ServiceToken: !GetAtt SSMDocFunction.Arn
         StackName: !Ref AWS::StackName
         UpdateDefaultVersion: true # default: true
         Content:
           schemaVersion: "2.2"
           description: Echo Hello World!
           parameters:
             text:
               type: String
               description: Text to echo
               default: Hello World!
           mainSteps:
             - name: echo
               action: aws:runShellScript
               inputs:
                 runCommand:
                   - echo "{{text}}"
               precondition:
                 StringEquals:
                   - platformType
                   - Linux
         DocumentType: Command # default: Command
         TargetType: / # default: /
         Tags:
           CreatedBy: CFN::Resource::Custom::SSM-Document # required, see above policy conditions