CDK Construct for managing SSM Documents
Project description
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
Installation
This package has peer dependencies, which need to be installed along in the expected version.
For TypeScript/NodeJS, add these to your dependencies
in package.json
:
- cdk-ssm-document
- @aws-cdk/aws-cloudformation
- @aws-cdk/aws-iam
- @aws-cdk/aws-lambda
For Python, add these to your requirements.txt
:
- cdk-ssm-document
- aws-cdk.aws-cloudformation
- aws-cdk.aws-iam
- aws-cdk.aws-lambda
Usage
Creating a document from a YAML or JSON file
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
import aws_cdk.core as cdk
from cdk_ssm_document import Document
import fs as fs
import path as path
class TestStack(cdk.Stack):
def __init__(self, scope, id, *, description=None, env=None, stackName=None, tags=None, synthesizer=None, terminationProtection=None, analyticsReporting=None):
super().__init__(scope, id, description=description, env=env, stackName=stackName, tags=tags, synthesizer=synthesizer, terminationProtection=terminationProtection, analyticsReporting=analyticsReporting)
file = path.join(__dirname, "../documents/hello-world.yml")
Document(self, "SSM-Document-HelloWorld",
name="HelloWorld",
content=fs.read_file_sync(file).to_string()
)
Creating a document via inline definition
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
import aws_cdk.core as cdk
from cdk_ssm_document import Document
import fs as fs
import path as path
class TestStack(cdk.Stack):
def __init__(self, scope, id, *, description=None, env=None, stackName=None, tags=None, synthesizer=None, terminationProtection=None, analyticsReporting=None):
super().__init__(scope, id, description=description, env=env, stackName=stackName, tags=tags, synthesizer=synthesizer, terminationProtection=terminationProtection, analyticsReporting=analyticsReporting)
Document(self, "SSM-Document-HelloWorld",
name="HelloWorld",
content={
"schema_version": "2.2",
"description": "Echo Hello World!",
"parameters": {
"text": {
"default": "Hello World!",
"description": "Text to echo",
"type": "String"
}
},
"main_steps": [{
"name": "echo",
"action": "aws:runShellScript",
"inputs": {
"run_command": ["echo \"{{text}}\""
]
},
"precondition": {
"StringEquals": ["platformType", "Linux"
]
}
}
]
}
)
Deploy all YAML/JSON files from a directory
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
import aws_cdk.core as cdk
from cdk_ssm_document import Document
import fs as fs
import path as path
class TestStack(cdk.Stack):
def __init__(self, scope, id, *, description=None, env=None, stackName=None, tags=None, synthesizer=None, terminationProtection=None, analyticsReporting=None):
super().__init__(scope, id, description=description, env=env, stackName=stackName, tags=tags, synthesizer=synthesizer, terminationProtection=terminationProtection, analyticsReporting=analyticsReporting)
dir = path.join(__dirname, "../documents")
files = fs.readdir_sync(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:
-
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
. -
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
-
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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for cdk_ssm_document-1.3.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3b645f773ee77206705741919fccb777bc350313f8f9af264b2281eff27343d3 |
|
MD5 | 3d7445668759cfa7ccba79d04e5b85cf |
|
BLAKE2b-256 | 68da62778b77ec0009ebd36d1a6d6c068c53a3edb5b48dca681d1c359df6e6bf |