DEV Community

Cover image for AWS Custom resources with Lambda and Golang
Victor Dorneanu
Victor Dorneanu

Posted on • Originally published at blog.dornea.nu on

AWS Custom resources with Lambda and Golang

#go #cdk #aws #typescript

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:

Resources: MySSMParameter: Type: "AWS::SSM::Parameter" Properties: Type: "String" ❶ Name: "/my/ssm/parameter" Value: "myValue" Description: "Description"
Enter fullscreen mode Exit fullscreen mode
Sample CloudFormation template for creating SSM parameters

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.

image

Workflow sequence

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:

GitHub logo 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.

📖 You can read more on my blog at AWS Custom resources with Lambda and Golang.

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

I always recommend to first run cdk diff before deploying. This way you can review the changes before it’s to late:

$ npx
…
Enter fullscreen mode Exit fullscreen mode
View on GitHub

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:

package main import ( "context" "encoding/json" "fmt" "github.com/aws/aws-lambda-go/cfn" ) // Global AWS session variable var awsSession aws.Config // ❶ // init will setup the AWS session func init() { // ❷ cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRegion("eu-central-1")) if err != nil { log.Fatalf("unable to load SDK config, %v", err) } awsSession = cfg } // lambdaHandler handles incoming CloudFormation events // and is of type cfn.CustomResourceFunction func lambdaHandler(ctx context.Context, event cfn.Event) (string, map[string]interface{}, error) { var physicalResourceID string responseData := map[string]interface{}{} switch event.ResourceType { // ❹ case "AWS::CloudFormation:CustomResource": customResourceHandler := NewSSMCustomResourceHandler(awsSession) return customResourceHandler.HandleEvent(ctx,event) default: return "",nil, fmt.Errorf("Unknown resource type: %s", event.ResourceType) } return physicalResourceID, nil, nil } // main function func main() { // From : https://github.com/aws/aws-lambda-go/blob/main/cfn/wrap.go // // LambdaWrap returns a CustomResourceLambdaFunction which is something lambda.Start() // will understand. The purpose of doing this is so that Response Handling boiler // plate is taken away from the customer and it makes writing a Custom Resource // simpler. // // func myLambda(ctx context.Context, event cfn.Event) (physicalResourceID string, data map[string]interface{}, err error) { // physicalResourceID = "arn:...." // return // } // // func main() { // lambda.Start(cfn.LambdaWrap(myLambda)) // } lambda.Start(cfn.LambdaWrap(lambdaHandler)) // ➌ }
Enter fullscreen mode Exit fullscreen mode
Sample CloudFormation template for creating SSM parameters

Some explanations:

  • The main function will call a lambda handler ➌
  • Before main gets executed the init 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 

// handleSSMCustomResource decides what to do in case of CloudFormation event func (s SSMCustomResourceHandler) HandleSSMCustomResource(ctx context.Context, event cfn.Event) (string, map[string]interface{}, error) { switch event.RequestType { // ❶ case cfn.RequestCreate: return s.Create(ctx, event) case cfn.RequestUpdate: return s.Update(ctx, event) case cfn.RequestDelete: return s.Delete(ctx, event) default: return "", nil, fmt.Errorf("Unknown request type: %s", event.RequestType) } }
Enter fullscreen mode Exit fullscreen mode
The main handler of the Lambda function

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 creates a new SSM parameter func (s SSMCustomResourceHandler) Create(ctx context.Context, event cfn.Event) (string, map[string]interface{}, error) { var physicalResourceID string // Get custom resource parameter from event ssmPath, err := strProperty(event, "key") // ❶ if err != nil { return physicalResourceID, nil, fmt.Errorf("Couldn't extract credential's key: %s", err) } physicalResourceID = ssmPath // ❷ ssmValue, err := strProperty(event, "value") // ❶ if err != nil { return physicalResourceID, nil, fmt.Errorf("Couldn't extract credential's value: %s", err) } // Put new parameter ➌ _, err = s.ssmClient.PutParameter(context.Background(), &ssm.PutParameterInput{ Name: aws.String(ssmPath), Value: aws.String(ssmValue), Type: types.ParameterTypeSecureString, Overwrite: aws.Bool(true), }) log.Printf("Put parameter into SSM: %s", physicalResourceID) if err != nil { return physicalResourceID, nil, fmt.Errorf("Couldn't put parameter (%s): %s\n", ssmPath, err) } return physicalResourceID, nil, nil }
Enter fullscreen mode Exit fullscreen mode
Create method of the SSMCustomResourceHandler

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": {} }
Enter fullscreen mode Exit fullscreen mode

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:

import * as cdk from "aws-cdk-lib"; import * as path from "path"; import * as customResources from "aws-cdk-lib/custom-resources"; import * as lambda from "aws-cdk-lib/aws-lambda"; import * as iam from 'aws-cdk-lib/aws-iam'; import { spawnSync, SpawnSyncOptions } from "child_process"; import { Construct } from "constructs"; import { SSMCredential } from "./custom-resource"; export class DeploymentsStack extends cdk.Stack { // ❶ constructor(scope: Construct, id: string, props?: cdk.StackProps) { super(scope, id, props); // Build the Golang based Lambda function const lambdaPath = path.join(__dirname, "../../"); // Create IAM role const iamRole = new iam.Role(this, 'Role', {...}); // ❷ // Add further policies to IAM role iamRole.addToPolicy(...); // ➌ // Create Lambda function const lambdaFunc = new lambda.Function(this, "GolangCustomResources", {...}); // ❹ // Create a new custom resource provider const provider = new customResources.Provider(this, "Provider", {...}); // ❺ // Create custom resource new SSMCredential(this, "SSMCredential1", provider, {...}); // ❻ } }
Enter fullscreen mode Exit fullscreen mode
deployments-stack.ts

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.

import * as path from "path"; import * as cdk from "aws-cdk-lib"; import * as customResources from "aws-cdk-lib/custom-resources"; import { Construct } from "constructs"; import fs = require("fs"); export interface SSMCredentialProps { // ❶ key: string; value: string; } // SSMCredential is an AWS custom resource // // Example code from: https://github.com/aws-samples/aws-cdk-examples/blob/master/typescript/custom-resource/my-custom-resource.ts export class SSMCredential extends Construct { // ❷ public readonly response: string; constructor( scope: Construct, id: string, provider: customResources.Provider, props: SSMCredentialProps ) { super(scope, id); const resource = new cdk.CustomResource(this, id, { // ➌ serviceToken: provider.serviceToken, // ❹ properties: props, // ❺ }); this.response = resource.getAtt("Response").toString(); } }
Enter fullscreen mode Exit fullscreen mode
custom-resource.ts
  • 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)

And this is how it's used withing the previously defined DeploymentsStack:

import { SSMCredential } from "./custom-resource"; ... export class DeploymentsStack extends cdk.Stack { constructor(scope: Construct, id: string, props?: cdk.StackProps) { super(scope, id, props); ... // Create a new custom resource provider const provider = new customResources.Provider(this, "Provider", { onEventHandler: lambdaFunc, }); // Create custom resource new SSMCredential(this, "SSMCredential1", provider, { key: "/test/testing", value: "some-secret-value", }); } }
Enter fullscreen mode Exit fullscreen mode
How to use a SSMCredential in your CDK stack

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.

image

The CloudFormation stack in the AWS console. Here we have created 2 custom resources of type SSMCredential.

image

The SSM parameters created by the Lambda function are of type SecureString.

image

Each SSM parameter has a tag (stackID) assigned.

Testing

Unit tests {#unit-tests}

The SSMCustomResourceHandler structure has a SSM client in order to PUT and DELETE parameters:

// SSMParameterAPI defines an interface for the SSM API calls // I use this interface in order to be able to mock out the SSM client and implement unit tests properly. // // Also check https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/gov2/ssm type SSMParameterAPI interface { DeleteParameter(ctx context.Context, params *ssm.DeleteParameterInput, optFns ...func(*ssm.Options)) (*ssm.DeleteParameterOutput, error) PutParameter(ctx context.Context, params *ssm.PutParameterInput, optFns ...func(*ssm.Options)) (*ssm.PutParameterOutput, error) } type SSMCustomResourceHandler struct { ssmClient SSMParameterAPI }
Enter fullscreen mode Exit fullscreen mode
In aws_custom_resource.go

I use my own interface for the SSM parameter API as this can be easily mocked out when writing unit tests:

// SSMParameterApiImpl is a mock for SSMParameterAPI type SSMParameterApiImpl struct{} // PutParameter func (s SSMParameterApiImpl) PutParameter(ctx context.Context, params *ssm.PutParameterInput, optFns ...func(*ssm.Options)) (*ssm.PutParameterOutput, error) { output := &ssm.PutParameterOutput{} return output, nil } // DeleteParameter func (s SSMParameterApiImpl) DeleteParameter(ctx context.Context, params *ssm.DeleteParameterInput, optFns ...func(*ssm.Options)) (*ssm.DeleteParameterOutput, error) { output := &ssm.DeleteParameterOutput{} return output, nil }
Enter fullscreen mode Exit fullscreen mode
In aws_custom_resource_test.go

Now I can use the SSMParameterApiImpl as a mocked client as it satisfies the SSMParameterAPI interface:

func TestPutParameter(t *testing.T) { mockedAPI := SSMParameterApiImpl{} ssmHandler := SSMCustomResourceHandler{ ssmClient: mockedAPI, } ... }
Enter fullscreen mode Exit fullscreen mode
In aws_custom_resource_test.go

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) }
Enter fullscreen mode Exit fullscreen mode

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 ...
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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": {} }
Enter fullscreen mode Exit fullscreen mode

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"}%
Enter fullscreen mode Exit fullscreen mode

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

Security

Golang

Top comments (0)