Motivation
CDK is a great framework by AWS that allows you to define cloud infrastructure as code (IaC). You can use your favourite programming language such as TypeScript, Python, Java, Golang to define your resources. This feature is particularly convenient as it automates the generation of CloudFormation templates in a readable and more manageable way.
However, not every AWS resource can be mapped directly to a CloudFormation template using CDK. In my particular case I had to create secure SSM parameters from within CDK. Typically this is how you create a SSM parameter in CloudFormation:
In ❶ you specify the type of the SSM parameter:
-
standard (
String
)- simple key-value string pair
- does not support versioning
-
advanced (
StringList
)- key-value pairs with additional metadata
- does support versioning
-
secure string (
SecureString
)- similar to standard parameters but the data is encrypted at rest using AWS KMS
- this is used for storing sensitive data such as passwords, API keys and other credentials
Depending on the stack action, CloudFormation sends your function a Create, Update, or Delete event. Because each event is handled differently, make sure that there are no unintended behaviors when any of the three event types is received.
-- Source
Custom resources can be used in an AWS CloudFormation stack to create, update, delete some resources that are not available as a native CFN (CloudFormation) resource. This could be SSL certificates that need to be generated in a certain way, custom DNS records or anything outside AWS. The Lambda function will take care of the lifecycle management of that specific resource.
In CDK you would create your custom resource which has a so called provider
attached (in our case it's a Lambda function) meant to implement the logic whenever the resource is created, updated or deleted. After cdk synth
a new CloudFormation template for the CDK stack is created. Whenever a resource is created/updated/deleted a new CloudFormation event will occur. This event will be sent to the Lambda function which eventually will create/update/delete SSM parameters based on the event's properties.
This gives you enough flexibility to define what should happen when certain events occur. Let's dig into deeper into the specifics.
Of course you can jump right away to the Github repository:
dorneanu / aws-custom-resource-golang
AWS Lambda baked AWS custom resource PoC in Golang
AWS custom resources using Golang, Lambda and TypeScript.
Motivation
This is ready-to-deploy proof of concept leveraging Golang to efficiently handle the lifecycle management
of so called AWS custom resources. This repository exemplifies how to use these to create SSM parameters of type
SecureString
in CDK. You can, of course, use this repository as a template for more advanced custom resources.
Deployment
Make sure you first install all dependencies:
-
go
binary npm
Then clone this repository:
$ git clone https://github.com/dorneanu/aws-custom-resource-golang
Then install all npm
dependencies:
$ cd deployments
$ npm i --save-dev
added 310 packages in 3s
30 packages are looking for funding
run `npm fund` for details
I always recommend to first run cdk diff
before deploying. This way you can review the
changes before it’s to late:
$ npx
…AWS Lambda
Basic template
As mentioned before the custom resource should be baked by an AWS Lambda function. This is how you would write the basic function structure:
Some explanations:
- The
main
function will call a lambda handler ➌ - Before
main
gets executed theinit
function will be executed first ❷- it will try to connect to AWS and populate the global variable defined at ❶
- within
lambdaHandler
we also have to make sure check for the right CFN custom resource type ❹
Custom resource handler
Supposing we use a custom type called SSMCustomResourceHandler
we can have a main entrypoint (in this example called HandleSSMCustomResource
) where we call a different method depending on the events request type ❶.
Each method will apply trigger different sorts of operations. This is what will happen whenever a new custom resource is created:
Create
should create a new SSM parameter (of type SecureString
) based on the information contained within the CloudFormation event. In ❶ I use a helper function to extract a property out of the event
. Once we have the ssmPath
we also set the physicalResourceID
to that value ❷. Afterwards we will call PutParameter
which should create a new SSM parameter.
The CloudFormation event contains much information. This is what it looks like:
{
"RequestType": "Create",
"RequestID": "b37cee19-f52d-4801-89f0-eed1be454756",
"ResponseURL": "",
"ResourceType": "AWS::CloudFormation::CustomResource",
"PhysicalResourceID": "",
"LogicalResourceID": "SSMCredential63DBA3F67",
"StackID": "arn:aws:cloudformation:eu-central-1:xxxx:stack/CustomResourcesGolang/a0de3b10-c3e1-11ed-9d97-02c",
"ResourceProperties": {
"ServiceToken": "arn:aws:lambda:eu-central-1:xxxxxxxxxxxx:function:CustomResourcesGolang-ProviderframeworkonEvent83C1-Dt9Jv3RwL9KT",
"key": "/testing6",
"value": "some-secret-value"
},
"OldResourceProperties": {}
}
CDK
Now that we know how to deal with CloudFormation events and how to manage the custom resource, let's deep-dive into DevOps and setup a small CDK application. Usually I would write the CDK part in Python but for this project I've setup my very first CDK application in TypeScript 😏. Let's start with the basic template.
Deployment Stack
The deployment stack I've defined which resources/components should be created:
So my CDK application will:
- create a new CloudFormation stack called
DeploymentsStack
❶ - create a new IAM role ❷
- used to attach it to the lambda function
- here we define the IAM policies required to operate on SSM parameters
- add several IAM policies to the IAM role ➌
- create a new AWS Lambda function ❹
- create a so called provider ❺ which is responsible for the lifecycle management of the custom resources in AWS
- in our case this is our lambda function
- I'm not sure if this can be something different 😕
Custom resource
In the previous section I've mentioned SSMCredential
which is our new custom resource to implement a SSM parameter of type SecureString
.
- the
SSMCredentialProps
define the arguments ❶ to be passed to the custom resource-
key
: the parameter's name -
value
: the value the parameter should hold
-
- the custom resource itself is of type
SSMCredential
❷- it has a
constructor
- inside it a new CDK custom resource is being initialized ➌
- the serviceToken is the ARN of the provider which implements this custom resource type.
- additionally we pass in the arguments ❺ (as properties)
- it has a
And this is how it's used withing the previously defined DeploymentsStack
:
Screenshots
As pictures say more than words, let's have a look at some screenshots to better understand what's happening under the hood. Doing so you might get a better understanding of the workflow and all the involved components that are created by CDK.
Testing
Unit tests {#unit-tests}
The SSMCustomResourceHandler structure has a SSM client in order to PUT and DELETE parameters:
I use my own interface for the SSM parameter API as this can be easily mocked out when writing unit tests:
Now I can use the SSMParameterApiImpl
as a mocked client as it satisfies the SSMParameterAPI
interface:
All we have to do now is to create a cfn.Event and call the Create method of the SSMHandlerCustomResource class:
func TestPutParameter(t *testing.T) {
mockedAPI := SSMParameterApiImpl{}
ssmHandler := SSMCustomResourceHandler{
ssmClient: mockedAPI,
}
// Create new SSM parameter
cfnEvent := cfn.Event{
RequestType: "Create",
RequestID: "xxx",
ResponseURL: "some-url-here",
ResourceType: "AWS::CloudFormation::CustomResource",
PhysicalResourceID: "",
LogicalResourceID: "SSMCredentialTesting1",
StackID: "arn:aws:cloudformation:eu-central-1:9999999:stack/CustomResourcesGolang",
ResourceProperties: map[string]interface{}{
"ServiceToken": "arn:aws:lambda:eu-central-1:9999999:function:CustomResourcesGolang-Function",
"key": "/testing3",
"value": "some-secret-value",
},
}
_, _, _ = ssmHandler.Create(context.TODO(), cfnEvent)
}
Integration tests
I've used AWS SAM to locally invoke the Lambda function created via CDK. Make sure you have aws-sam-cli
installed on your machine.
After the initial call aws-sam
will first download the Docker image for your function:
...
Invoking /main (go1.x)
Local image was not found.
Removing rapid images for repo public.ecr.aws/sam/emulation-go1.x
...
Afterwards invoking the Lambda locally is quite easy:
$ cdk synth
$ sam local invoke -t cdk.out/CustomResourcesGolang.template.json GolangCustomResources
...
Mounting /home/victor/work/repos/aws-custom-resource-golang/deployments/cdk.out/asset.1ac1b002ba7d09e11c31702e1724d092e837796c2ed40541947abdfc6eb75947 as /var/task:ro,delegated, inside runt
ime container
2023/03/31 11:42:29 Starting lambda
2023/03/31 11:42:29 event: cfn.Event{RequestType:"", RequestID:"", ResponseURL:"", ResourceType:"", PhysicalResourceID:"", LogicalResourceID:"", StackID:"", ResourceProperties:map[string]in
terface {}(nil), OldResourceProperties:map[string]interface {}(nil)}
2023/03/31 11:42:29 sending status failed: Unknown resource type:
Put "": unsupported protocol scheme "": Error
null
{"errorMessage":"Put \"\": unsupported protocol scheme \"\"","errorType":"Error"}END RequestId: 93eed487-2441-4d41-a0b6-d939efeab99f
REPORT RequestId: 93eed487-2441-4d41-a0b6-d939efeab99f Init Duration: 0.30 ms Duration: 224.84 ms Billed Duration: 225 ms Memory Size: 128 MB Max Memory Used: 128 M
Of course you need to specify a payload to your function. You can store your payload (of type CloudFormation event) as a JSON file:
$ cat tests/create.json
{
"RequestType": "Create",
"RequestID": "9bf90339-c6f0-47ff-ad67-e19226facf6e",
"ResponseURL": "https://some-url",
"ResourceType": "AWS::CloudFormation::CustomResource",
"PhysicalResourceID": "",
"LogicalResourceID": "SSMCredential21D358858",
"StackID": "arn:aws:cloudformation:eu-central-1:xxxxxxxxxxxx:stack/CustomResourcesGolang/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"ResourceProperties": {
"ServiceToken": "arn:aws:lambda:eu-central-1:xxxxxxxxxxxx:function:CustomResourcesGolang-ProviderframeworkonEvent83C1-Dt9Jv3RwL9KT",
"key": "/test/testing12345",
"value": "some-secret-value"
},
"OldResourceProperties": {}
}
Then you can specify the JSON file
$ sam local invoke -t cdk.out/CustomResourcesGolang.template.json GolangCustomResources -e ../tests/create.json
Invoking /main (go1.x)
Local image is up-to-date
Using local image: public.ecr.aws/lambda/go:1-rapid-x86_64.
Mounting /home/victor/work/repos/aws-custom-resource-golang/deployments/cdk.out/asset.1ac1b002ba7d09e11c31702e1724d092e837796c2ed40541947abdfc6eb75947 as /var/task:ro,delegated, inside runt
ime container
START RequestId: cb8c7882-269c-434e-ace1-f6958940ee2e Version: $LATEST
2023/03/31 11:48:16 Starting lambda
2023/03/31 11:48:16 event: cfn.Event{RequestType:"Create", RequestID:"9bf90339-c6f0-47ff-ad67-e19226facf6e", ResponseURL:"https://some-file", ResourceType:"AWS::CloudFormation::CustomResour
ce", PhysicalResourceID:"", LogicalResourceID:"SSMCredential21D358858", StackID:"arn:aws:cloudformation:eu-central-1:xxxxxxxxxxxx:stack/CustomResourcesGolang/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxx", ResourceProperties:map[string]interface {}{"ServiceToken":"arn:aws:lambda:eu-central-1:xxxxxxxxxxxx:function:CustomResourcesGolang-ProviderframeworkonEvent83C1-Dt9Jv3RwL9KT", "key":
"/test/testing12345", "value":"some-secret-value"}, OldResourceProperties:map[string]interface {}{}}
2023/03/31 11:48:16 Creating SSM parameter
2023/03/31 11:48:16 Put parameter into SSM: /test/testing12345
Put "https://some-file": dial tcp: lookup some-file on 192.168.179.1:53: no such host: Error
null
END RequestId: cb8c7882-269c-434e-ace1-f6958940ee2e
REPORT RequestId: cb8c7882-269c-434e-ace1-f6958940ee2e Init Duration: 0.13 ms Duration: 327.24 ms Billed Duration: 328 ms Memory Size: 128 MB Max Memory Used: 128 MB
{"errorMessage":"Put \"https://some-file\": dial tcp: lookup some-file on 192.168.179.1:53: no such host","errorType":"Error"}%
This one fails coz I didn't specify any valid ResponseURL
.
Conclusion
I think this approach opens a lot of possibilities to create advanced custom resources based on your needs. You could for example use custom resources to deploy resources across multiple accounts. For Security reasons you could enforce several compliance policies and monitor for compliance deviations. Or you could use some 3rd-party APIs to pass data back and forth (e.g. user management, product stocks etc.)
As you have control over the logic implemented in the AWS Lambda function and therefore define how your custom resources should be managed, the possibilities are endless. Have fun creating your own custom resources!
Resources
General
- 2023-02-07 ◦ aws-doc-sdk-examples/gov2 at main · awsdocs/aws-doc-sdk-examples · GitHub
- 2023-01-31 ◦ CloudFormation needs physicalResourceId for custom-resources.AwsSdkCall when used in custom-resources.AwsCustomResource as onDelete property · Issue #5796 · aws/aws-cdk · GitHub
- 2023-01-20 ◦ Create AWS Custom Resources in Go | by Mo Asgari | Medium
- 2023-01-20 ◦ github.com/aws-cdk-examples/typescript/custom-resource
Security
- 2023-04-06 ◦ Welcome to the Jungle: Pentesting AWS
Top comments (0)