DEV Community: Mark Gerald Martins

Terraform CDK + Go: Building a Complete Serverless API Project (Part 1)

Mark Gerald Martins — Tue, 02 Sep 2025 00:10:39 +0000

🚀 Infrastructure as Code in action!

If you already use Terraform but want the power of programming languages like Go, you’ll love this tutorial I just published.

I show you step by step how to build a complete Serverless API on AWS with Lambda + API Gateway + DynamoDB + S3, using Terraform CDK (CDKTF).

File‑by‑file, hands‑on guide to build a serverless Orders API on AWS with Terraform CDK (CDKTF) + Go. We’ll create every folder and file under terraform/, explain what each piece does, and deploy. Part 2 (coming soon) will add CI/CD with GitHub Actions for both the API and the CDKTF code using GitOps.

Why CDKTF (CDK for Terraform) is great

Type‑safe infra in Go (structs, IDE autocomplete, refactors).
Reusable modules/constructs instead of huge .tf files.
Still Terraform under the hood (plan/apply, state backends, providers).
Easy to grow into multi‑stack projects.

What we’ll build

A small Orders API backed by AWS Lambda (Go), exposed by API Gateway HTTP API, storing data in DynamoDB, plus an S3 bucket to host the Lambda artifact (api.zip).

Endpoints in the app (outside scope here) include: /orders, /orders/:orderId, /orders/:orderId/items, etc. We’ll focus on the infra.

Requirements

Go ≥ 1.21/1.22
Node.js + npm (for the CDKTF CLI)
Terraform CLI ≥ 1.5
AWS CLI configured (profile or env vars)

Install CDKTF CLI:

npm i -g cdktf-cli@latest
cdktf --version

Repo context

Base project: go-serverless-api-terraform (contains the Go API code). We’ll create all infra files under terraform/ (matching the branch terraform-cdk-go).

Clone and enter:

git clone https://github.com/markgerald/go-serverless-api-terraform.git
cd go-serverless-api-terraform
mkdir -p terraform && cd terraform

Final folder layout (everything we’ll create now)

terraform/
├─ cdktf.json
├─ go.mod
├─ go.sum             # (auto‑generated)
├─ .env.sample
├─ main.go            # App entrypoint: reads env, builds stack, synths
├─ infra/
│  └─ infra.go        # Stack wiring (provider, modules, outputs)
└─ modules/
   ├─ dynamodb/
   │  └─ dynamodb.go  # Orders + Order Items tables
   ├─ s3/
   │  └─ bucket.go    # Artifact bucket + PAB + versioning/encryption
   ├─ iam/
   │  └─ role.go      # Lambda execution role + policies
   ├─ lambda/
   │  └─ lambda.go    # Lambda from S3 object + env vars
   └─ apigateway/
      └─ api.go       # HTTP API + integration + routes + stage + permission

We’ll build this tree step by step ⬇️

1) `cdktf.json` — project config

Create terraform/cdktf.json:

{
  "language": "go",
  "app": "go run main.go",
  "terraformProviders": [
    "hashicorp/aws@~> 6.0"
  ],
  "context": {
    "awsRegion": "us-east-1"
  }
}

Adjust awsRegion to your default. We’ll still allow overriding via AWS_REGION.

2) `go.mod` — module + dependencies

Create terraform/go.mod:

module terraform

go 1.22

require (
    github.com/aws/constructs-go/constructs/v10 v10.3.0
    github.com/cdktf/cdktf-provider-aws-go/aws/v21 v21.0.0
    github.com/hashicorp/terraform-cdk-go/cdktf v0.21.0
)

Fetch deps:

go mod tidy

3) `.env.sample` — variables used by the stack

Create terraform/.env.sample:

# Common
AWS_REGION=us-east-1
AWS_PROFILE=
ENV=dev

# DynamoDB
TABLE_ORDERS=orders
TABLE_ORDER_ITEMS=order_items

# S3 artifact bucket
S3_BUCKET_PREFIX=go-lambda-artifacts
S3_VERSIONING=false      # true/false
S3_FORCE_DESTROY=false   # true/false (careful!)
S3_ENCRYPTION=NONE       # NONE|AES256|KMS
S3_KMS_KEY_ID=

# Lambda
LAMBDA_NAME=go-lambda-api
LAMBDA_RUNTIME=provided.al2023
LAMBDA_HANDLER=bootstrap
LAMBDA_MEMORY=128
LAMBDA_TIMEOUT=10
LAMBDA_S3_KEY=api.zip

Copy to .env and export, or set directly in your shell before running.

4) `main.go` — entrypoint (reads env, builds stack, synths)

Create terraform/main.go:

package main

import (
    "log"
    "os"

    "github.com/aws/jsii-runtime-go"
    "github.com/hashicorp/terraform-cdk-go/cdktf"

    "terraform/infra"
)

func getenv(k, def string) string {
    if v := os.Getenv(k); v != "" {
        return v
    }
    return def
}

func main() {
    // Read env (with sane defaults)
    cfg := infra.Config{
        AwsRegion:        getenv("AWS_REGION", "us-east-1"),
        AwsProfile:       os.Getenv("AWS_PROFILE"),
        Env:              getenv("ENV", "dev"),
        TableOrders:      getenv("TABLE_ORDERS", "orders"),
        TableOrderItems:  getenv("TABLE_ORDER_ITEMS", "order_items"),
        S3BucketPrefix:   getenv("S3_BUCKET_PREFIX", "go-lambda-artifacts"),
        S3Versioning:     getenv("S3_VERSIONING", "false"),
        S3ForceDestroy:   getenv("S3_FORCE_DESTROY", "false"),
        S3Encryption:     getenv("S3_ENCRYPTION", "NONE"),
        S3KmsKeyID:       os.Getenv("S3_KMS_KEY_ID"),
        LambdaName:       getenv("LAMBDA_NAME", "go-lambda-api"),
        LambdaRuntime:    getenv("LAMBDA_RUNTIME", "provided.al2023"),
        LambdaHandler:    getenv("LAMBDA_HANDLER", "bootstrap"),
        LambdaMemory:     getenv("LAMBDA_MEMORY", "128"),
        LambdaTimeout:    getenv("LAMBDA_TIMEOUT", "10"),
        LambdaS3Key:      getenv("LAMBDA_S3_KEY", "api.zip"),
    }

    app := cdktf.NewApp(nil)

    if _, err := infra.NewStack(app, "infra", &cfg); err != nil {
        log.Fatalf("failed to build stack: %v", err)
    }

    app.Synth() // generates cdktf.out/stacks/infra
    log.Printf("Synth complete. Now: cd cdktf.out/stacks/infra && terraform init")
}

5) `infra/infra.go` — wire provider + modules + outputs

Create folder and file:

mkdir -p infra && touch infra/infra.go

Add:

package infra

import (
    "fmt"

    "github.com/aws/constructs-go/constructs/v10"
    "github.com/aws/jsii-runtime-go"
    "github.com/hashicorp/terraform-cdk-go/cdktf"

    awsprovider "github.com/cdktf/cdktf-provider-aws-go/aws/v21/provider"

    mddb "terraform/modules/dynamodb"
    mds3 "terraform/modules/s3"
    mdrole "terraform/modules/iam"
    mdlambda "terraform/modules/lambda"
    mdapi "terraform/modules/apigateway"
)

type Config struct {
    AwsRegion, AwsProfile string
    Env string

    TableOrders, TableOrderItems string

    S3BucketPrefix  string
    S3Versioning    string // "true"/"false"
    S3ForceDestroy  string // "true"/"false"
    S3Encryption    string // NONE|AES256|KMS
    S3KmsKeyID      string

    LambdaName, LambdaRuntime, LambdaHandler string
    LambdaMemory, LambdaTimeout, LambdaS3Key string
}

func NewStack(scope constructs.Construct, id string, cfg *Config) (cdktf.TerraformStack, error) {
    stack := cdktf.NewTerraformStack(scope, jsii.String(id))

    // Provider
    awsprovider.NewAwsProvider(stack, jsii.String("aws"), &awsprovider.AwsProviderConfig{
        Region:  jsii.String(cfg.AwsRegion),
        Profile: nilIfEmpty(cfg.AwsProfile),
    })

    // S3 bucket for artifacts
    bucket := mds3.NewArtifactBucket(stack, "Artifacts", &mds3.BucketConfig{
        Prefix:       cfg.S3BucketPrefix,
        Env:          cfg.Env,
        Versioning:   cfg.S3Versioning == "true" || cfg.S3Versioning == "1",
        ForceDestroy: cfg.S3ForceDestroy == "true" || cfg.S3ForceDestroy == "1",
        Encryption:   cfg.S3Encryption,
        KmsKeyID:     cfg.S3KmsKeyID,
    })

    // DynamoDB tables
    tables := mddb.NewTables(stack, "Tables", &mddb.TablesConfig{
        OrdersName:     cfg.TableOrders,
        OrderItemsName: cfg.TableOrderItems,
    })

    // IAM role for Lambda
    role := mdrole.NewLambdaRole(stack, "LambdaRole")

    // Lambda function from S3 object
    fn := mdlambda.NewApiLambda(stack, "ApiLambda", &mdlambda.LambdaConfig{
        Name:       cfg.LambdaName,
        Runtime:    cfg.LambdaRuntime,
        Handler:    cfg.LambdaHandler,
        Memory:     cfg.LambdaMemory,
        Timeout:    cfg.LambdaTimeout,
        S3Bucket:   bucket.Name(),
        S3Key:      cfg.LambdaS3Key,
        Env:        cfg.Env,
        TableOrders:     tables.OrdersName(),
        TableOrderItems: tables.OrderItemsName(),
        RoleArn:    role.Arn(),
    })

    // API Gateway HTTP API + routes + integration + permission
    api := mdapi.NewHttpApi(stack, "HttpApi", &mdapi.ApiConfig{
        Env:          cfg.Env,
        LambdaArn:    fn.Arn(),
        LambdaName:   fn.FunctionName(),
    })

    // Outputs
    cdktf.NewTerraformOutput(stack, jsii.String("api_url"), &cdktf.TerraformOutputConfig{
        Value: api.Endpoint(),
    })

    cdktf.NewTerraformOutput(stack, jsii.String("artifact_bucket"), &cdktf.TerraformOutputConfig{
        Value: bucket.Name(),
    })

    return stack, nil
}

func nilIfEmpty(s string) *string {
    if s == "" {
        return nil
    }
    return jsii.String(s)
}

6) Modules — one file at a time

Create the modules tree:

mkdir -p modules/dynamodb modules/s3 modules/iam modules/lambda modules/apigateway

6.1) `modules/dynamodb/dynamodb.go`

package dynamodb

import (
    "github.com/aws/constructs-go/constructs/v10"
    "github.com/aws/jsii-runtime-go"
    "github.com/hashicorp/terraform-cdk-go/cdktf"
    dynamodbtable "github.com/cdktf/cdktf-provider-aws-go/aws/v21/dynamodbtable"
    ddbpitr "github.com/cdktf/cdktf-provider-aws-go/aws/v21/dynamodbtablepointintimerecovery"
)

type TablesConfig struct {
    OrdersName     string
    OrderItemsName string
}

type Tables struct {
    orders     dynamodbtable.DynamodbTable
    orderItems dynamodbtable.DynamodbTable
}

func NewTables(scope constructs.Construct, id string, cfg *TablesConfig) *Tables {
    s := constructs.NewConstruct(scope, jsii.String(id))

    orders := dynamodbtable.NewDynamodbTable(s, jsii.String("Orders"), &dynamodbtable.DynamodbTableConfig{
        Name:        jsii.String(cfg.OrdersName),
        BillingMode: jsii.String("PAY_PER_REQUEST"),
        HashKey:     jsii.String("id"),
        Attribute: &[]*dynamodbtable.DynamodbTableAttribute{{
            Name: jsii.String("id"), Type: jsii.String("S"),
        }},
    })
    ddbpitr.NewDynamodbTablePointInTimeRecovery(s, jsii.String("OrdersPITR"), &ddbpitr.DynamodbTablePointInTimeRecoveryConfig{
        TableName: orders.Name(),
        Enabled:   jsii.Bool(true),
    })

    items := dynamodbtable.NewDynamodbTable(s, jsii.String("OrderItems"), &dynamodbtable.DynamodbTableConfig{
        Name:        jsii.String(cfg.OrderItemsName),
        BillingMode: jsii.String("PAY_PER_REQUEST"),
        HashKey:     jsii.String("order_id"),
        RangeKey:    jsii.String("id"),
        Attribute: &[]*dynamodbtable.DynamodbTableAttribute{
            { Name: jsii.String("order_id"), Type: jsii.String("S") },
            { Name: jsii.String("id"),       Type: jsii.String("S") },
        },
    })
    ddbpitr.NewDynamodbTablePointInTimeRecovery(s, jsii.String("OrderItemsPITR"), &ddbpitr.DynamodbTablePointInTimeRecoveryConfig{
        TableName: items.Name(),
        Enabled:   jsii.Bool(true),
    })

    return &Tables{orders: orders, orderItems: items}
}

func (t *Tables) OrdersName() *string     { return t.orders.Name() }
func (t *Tables) OrderItemsName() *string { return t.orderItems.Name() }

6.2) `modules/s3/bucket.go`

package s3

import (
    "fmt"

    "github.com/aws/constructs-go/constructs/v10"
    "github.com/aws/jsii-runtime-go"
    s3bucket "github.com/cdktf/cdktf-provider-aws-go/aws/v21/s3bucket"
    s3pab "github.com/cdktf/cdktf-provider-aws-go/aws/v21/s3bucketpublicaccessblock"
    s3ver "github.com/cdktf/cdktf-provider-aws-go/aws/v21/s3bucketversioning"
    s3serverenc "github.com/cdktf/cdktf-provider-aws-go/aws/v21/s3bucketserverSideencryptionconfiguration"
)

type BucketConfig struct {
    Prefix       string
    Env          string
    Versioning   bool
    ForceDestroy bool
    Encryption   string // NONE|AES256|KMS
    KmsKeyID     string
}

type Bucket struct {
    bucket s3bucket.S3Bucket
}

func NewArtifactBucket(scope constructs.Construct, id string, cfg *BucketConfig) *Bucket {
    s := constructs.NewConstruct(scope, jsii.String(id))
    name := fmt.Sprintf("%s-%s", cfg.Prefix, cfg.Env)

    b := s3bucket.NewS3Bucket(s, jsii.String("ArtifactsBucket"), &s3bucket.S3BucketConfig{
        Bucket:       jsii.String(name),
        ForceDestroy: jsii.Bool(cfg.ForceDestroy),
    })

    s3pab.NewS3BucketPublicAccessBlock(s, jsii.String("PAB"), &s3pab.S3BucketPublicAccessBlockConfig{
        Bucket:                b.Bucket(),
        BlockPublicAcls:       jsii.Bool(true),
        BlockPublicPolicy:     jsii.Bool(true),
        IgnorePublicAcls:      jsii.Bool(true),
        RestrictPublicBuckets: jsii.Bool(true),
    })

    s3ver.NewS3BucketVersioning(s, jsii.String("Versioning"), &s3ver.S3BucketVersioningConfig{
        Bucket: b.Bucket(),
        VersioningConfiguration: &s3ver.S3BucketVersioningVersioningConfiguration{
            Status: jsii.String(ifThen(cfg.Versioning, "Enabled", "Suspended")),
        },
    })

    if cfg.Encryption == "AES256" || cfg.Encryption == "KMS" {
        var rule *s3serverenc.S3BucketServerSideEncryptionConfigurationRule
        if cfg.Encryption == "AES256" {
            rule = &s3serverenc.S3BucketServerSideEncryptionConfigurationRule{
                ApplyServerSideEncryptionByDefault: &s3serverenc.S3BucketServerSideEncryptionConfigurationRuleApplyServerSideEncryptionByDefault{
                    SseAlgorithm: jsii.String("AES256"),
                },
            }
        } else {
            rule = &s3serverenc.S3BucketServerSideEncryptionConfigurationRule{
                ApplyServerSideEncryptionByDefault: &s3serverenc.S3BucketServerSideEncryptionConfigurationRuleApplyServerSideEncryptionByDefault{
                    SseAlgorithm: jsii.String("aws:kms"),
                    KmsMasterKeyId: nilIfEmpty(cfg.KmsKeyID),
                },
            }
        }
        s3serverenc.NewS3BucketServerSideEncryptionConfiguration(s, jsii.String("Enc"), &s3serverenc.S3BucketServerSideEncryptionConfigurationConfig{
            Bucket: b.Bucket(),
            Rule:   &[]*s3serverenc.S3BucketServerSideEncryptionConfigurationRule{rule},
        })
    }

    return &Bucket{bucket: b}
}

func (b *Bucket) Name() *string { return b.bucket.Bucket() }

func ifThen[T any](cond bool, a, b T) T { if cond { return a }; return b }
func nilIfEmpty(s string) *string { if s == "" { return nil }; return jsii.String(s) }

6.3) `modules/iam/role.go`

package iam

import (
    "github.com/aws/constructs-go/constructs/v10"
    "github.com/aws/jsii-runtime-go"
    iamrole "github.com/cdktf/cdktf-provider-aws-go/aws/v21/iamrole"
    iampa "github.com/cdktf/cdktf-provider-aws-go/aws/v21/iamrolepolicyattachment"
)

type Role struct{ role iamrole.IamRole }

func NewLambdaRole(scope constructs.Construct, id string) *Role {
    s := constructs.NewConstruct(scope, jsii.String(id))

    assume := `{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"Service":"lambda.amazonaws.com"},"Action":"sts:AssumeRole"}]}`

    r := iamrole.NewIamRole(s, jsii.String("LambdaExecRole"), &iamrole.IamRoleConfig{
        Name:             jsii.String("orders-api-lambda-role"),
        AssumeRolePolicy: jsii.String(assume),
    })

    // Basic logging
    iampa.NewIamRolePolicyAttachment(s, jsii.String("BasicLogs"), &iampa.IamRolePolicyAttachmentConfig{
        Role:      r.Name(),
        PolicyArn: jsii.String("arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole"),
    })

    return &Role{role: r}
}

func (r *Role) Arn() *string { return r.role.Arn() }

Keep policies minimal. If your handler needs DynamoDB access directly, attach the specific permissions here later.

6.4) `modules/lambda/lambda.go`

package lambda

import (
    "github.com/aws/constructs-go/constructs/v10"
    "github.com/aws/jsii-runtime-go"
    lambdafn "github.com/cdktf/cdktf-provider-aws-go/aws/v21/lambdafunction"
)

type LambdaConfig struct {
    Name, Runtime, Handler string
    Memory, Timeout        string // keep as string for simplicity

    S3Bucket *string
    S3Key    string

    Env               string
    TableOrders       *string
    TableOrderItems   *string
    RoleArn           *string
}

type Fn struct{ fn lambdafn.LambdaFunction }

func NewApiLambda(scope constructs.Construct, id string, c *LambdaConfig) *Fn {
    s := constructs.NewConstruct(scope, jsii.String(id))

    mem := toNum(c.Memory, 128)
    tout := toNum(c.Timeout, 10)

    fn := lambdafn.NewLambdaFunction(s, jsii.String("Fn"), &lambdafn.LambdaFunctionConfig{
        FunctionName: jsii.String(c.Name),
        Role:         c.RoleArn,
        Runtime:      jsii.String(c.Runtime),
        Handler:      jsii.String(c.Handler),
        MemorySize:   jsii.Number(float64(mem)),
        Timeout:      jsii.Number(float64(tout)),
        S3Bucket:     c.S3Bucket,
        S3Key:        jsii.String(c.S3Key),
        Environment: &lambdafn.LambdaFunctionEnvironment{
            Variables: &map[string]*string{
                "ENV":               jsii.String(c.Env),
                "TABLE_ORDERS":      c.TableOrders,
                "TABLE_ORDER_ITEMS": c.TableOrderItems,
            },
        },
        Architectures: &[]*string{jsii.String("x86_64")},
    })

    return &Fn{fn: fn}
}

func (f *Fn) Arn() *string          { return f.fn.Arn() }
func (f *Fn) FunctionName() *string { return f.fn.FunctionName() }

func toNum(s string, def int) int { if s == "" { return def }; var n int; _, _ = fmt.Sscanf(s, "%d", &n); if n==0 {return def}; return n }

6.5) `modules/apigateway/api.go`

package apigateway

import (
    "github.com/aws/constructs-go/constructs/v10"
    "github.com/aws/jsii-runtime-go"
    api "github.com/cdktf/cdktf-provider-aws-go/aws/v21/apigatewayv2api"
    integ "github.com/cdktf/cdktf-provider-aws-go/aws/v21/apigatewayv2integration"
    route "github.com/cdktf/cdktf-provider-aws-go/aws/v21/apigatewayv2route"
    stage "github.com/cdktf/cdktf-provider-aws-go/aws/v21/apigatewayv2stage"
    lperm "github.com/cdktf/cdktf-provider-aws-go/aws/v21/lambdapermission"
)

type ApiConfig struct {
    Env string
    LambdaArn  *string
    LambdaName *string
}

type Http struct {
    api api.Apigatewayv2Api
}

func NewHttpApi(scope constructs.Construct, id string, c *ApiConfig) *Http {
    s := constructs.NewConstruct(scope, jsii.String(id))

    a := api.NewApigatewayv2Api(s, jsii.String("Api"), &api.Apigatewayv2ApiConfig{
        Name:         jsii.String("orders-http"),
        ProtocolType: jsii.String("HTTP"),
    })

    ig := integ.NewApigatewayv2Integration(s, jsii.String("Integration"), &integ.Apigatewayv2IntegrationConfig{
        ApiId:                a.Id(),
        IntegrationType:      jsii.String("AWS_PROXY"),
        IntegrationUri:       c.LambdaArn,
        PayloadFormatVersion: jsii.String("2.0"),
    })

    // Minimal routes mapped to the Lambda (expand as needed)
    route.NewApigatewayv2Route(s, jsii.String("Orders"), &route.Apigatewayv2RouteConfig{
        ApiId:    a.Id(),
        RouteKey: jsii.String("ANY /orders"),
        Target:   jsii.String("integrations/" + *ig.Id()),
    })
    route.NewApigatewayv2Route(s, jsii.String("OrderItems"), &route.Apigatewayv2RouteConfig{
        ApiId:    a.Id(),
        RouteKey: jsii.String("ANY /orders/{orderId}/items"),
        Target:   jsii.String("integrations/" + *ig.Id()),
    })

    stage.NewApigatewayv2Stage(s, jsii.String("Stage"), &stage.Apigatewayv2StageConfig{
        ApiId:      a.Id(),
        Name:       jsii.String(c.Env),
        AutoDeploy: jsii.Bool(true),
    })

    lperm.NewLambdaPermission(s, jsii.String("AllowApiGw"), &lperm.LambdaPermissionConfig{
        Action:       jsii.String("lambda:InvokeFunction"),
        FunctionName: c.LambdaName,
        Principal:    jsii.String("apigateway.amazonaws.com"),
        SourceArn:    a.Arn(),
    })

    return &Http{api: a}
}

func (h *Http) Endpoint() *string { return h.api.ApiEndpoint() }

7) Build & upload the Lambda artifact (`api.zip`)

From the repo root (not inside terraform/), build the custom runtime binary and zip it:

GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o bootstrap ./
zip api.zip bootstrap

After the artifact bucket exists (next section step 4), upload:

aws s3 cp api.zip s3://<S3_BUCKET_PREFIX>-<ENV>/<LAMBDA_S3_KEY>
# ex.: aws s3 cp api.zip s3://go-lambda-artifacts-dev/api.zip

8) Synthesize & apply with Terraform

From terraform/:

# 1) Synthesize CDKTF -> Terraform JSON
GOFLAGS=-mod=mod go run ./main.go

# 2) Initialize Terraform in the synthesized stack
cd cdktf.out/stacks/infra
terraform init

# 3) First create only the artifact bucket (so you can upload api.zip)
terraform apply -target=aws_s3_bucket.ArtifactsBucket -auto-approve

# 4) Upload the artifact (in another shell, see step 7)
aws s3 cp api.zip s3://<S3_BUCKET_PREFIX>-<ENV>/<LAMBDA_S3_KEY>

# 5) Apply the rest
terraform apply

Grab the API URL from the Terraform outputs or the AWS console (API Gateway → Stages → your ENV).

Destroy when done:

terraform destroy

If the bucket has objects, set S3_FORCE_DESTROY=true and re‑apply before destroying.

Notes & pitfalls

Runtime: provided.al2023 + handler bootstrap (custom Go runtime).
Keep IAM policies tight; start basic and iterate with least privilege.
S3 bucket names are global; prefix-env helps avoid collisions.
Consider configuring an S3 backend + DynamoDB locks later for team state.

Example backend (add in infra.NewStack when ready):

cdktf.NewS3Backend(stack, &cdktf.S3BackendConfig{
  Bucket: jsii.String("tf-state-bucket"),
  Key:    jsii.String("serverless-api/terraform.tfstate"),
  Region: jsii.String("us-east-1"),
  DynamoDbTable: jsii.String("terraform-locks"),
})

Full project link

The complete, ready‑to‑run code lives here (same structure as above):

➡️ https://github.com/markgerald/go-serverless-api-terraform/tree/terraform-cdk-go

Coming in Part 2

GitHub Actions pipelines for:
- Building, testing and releasing the Go API artifact
- Synthesizing and deploying CDKTF changes
GitOps: PR‑driven infra changes with plans as checks, environments, and approvals.

GO - Função Lambda para converter audio a partir do S3(AWS) - ffmpeg

Mark Gerald Martins — Mon, 17 Apr 2023 18:03:43 +0000

Atuei em um projeto pessoal, onde necessitei fazer a conversão de um arquivo wav(audio de qualidade maxima, sem compressão) para mp3.

Neste post, vou demonstrar o passo a passo, como fazer de forma "assíncrona", a partir de um upload para um bucket no S3(serviço de armazenamento de arquivos) da AWS.

No desenho abaixo, segue um contexto do que será feito e explicado neste post:

Criando Buckets

Em seu console da AWS, vá até o service S3, crie 2 novos buckets. O primeiro bucket, será o destino do upload do arquivo de áudio "bruto", no format .wav. O segundo, será para o arquivo comprimido e convertido para .mp3. No meu caso, usei estes nomes:

Criando Lambda

Sim, vamos já proceder na criação da função lambda que será responsável por converter os arquivos de audio bruto, para formado de audio compactado. Para isso, em seu AWS Console, na busca procuro por Lambda. Clique em Create Function

Vamos utilizar a linguagem GO, conforme a tela abaixo:

Permissões de acesso Lambda - S3

Será necessário a criação de uma Police, e atrelá-la a Role criada na criação da lambda.

Para isso acessaremos o console do IAM, sem seguida vamos ao menu Polices > Add Police. Mudaremos o modo para JSON, e vamos inserir o código a seguir:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogStream",
                "logs:CreateLogGroup",
                "logs:PutLogEvents"
            ],
            "Resource": "*"
        },
        {
            "Sid": "VisualEditor1",
            "Effect": "Allow",
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::mgm-wav-files/*"
        },
        {
            "Sid": "VisualEditor2",
            "Effect": "Allow",
            "Action": "s3:PutObject",
            "Resource": "arn:aws:s3:::mgm-mp3-files/*"
        }
    ]
}

A política acima dá permissão de leitura no bucket de arquivos wav e escrita no bucket para arquivos mp3, convertidos. Vamos salvar essa Police.

No console do IAM, vamos ao menu Roles, vamos selecionar a Role criada para a lambda. Em seguida, vamos em Add Permissions > atacch policies. Na buscar, buscar pelo nome da política criada e salvar.

Run time Lambda. O que é isso?

As funções lambda, na linguagem Go(entre outras), rodam em um contexto de ambiente Linux, no caso da distribuição AWS Linux. Nesse contexto, precisamos "carregar" uma lib, que será a responsável por fazer a conversão de áudio.

Essa lib é o FFMPEG. Que trata de vários formatos de mídias, audio, video.

Para isso, utilizaremos uma feature das funções lambda na AWS, chamada Layer, traduzindo: camada

Com uma layer, conseguimos rodar algumas libs em tempo de execução de uma ou mais funções lambda. Como?

Criando Layer FFMPEG

Vamos baixar os binários desta lib em nossa máquina local, e transferir apenas o necessário para um arquivo ZIP, que será inserido em um Lambda Layer.

Para isso, vou utilizar o exemplo abaixo, de ambiente Linux/MacOS:

wget https://johnvansickle.com/ffmpeg/releases/ffmpeg-release-amd64-static.tar.xz

wget https://johnvansickle.com/ffmpeg/releases/ffmpeg-release-amd64-static.tar.xz.md5

md5sum -c ffmpeg-release-amd64-static.tar.xz.md5

tar xvf ffmpeg-release-amd64-static.tar.xz

Após o download e descompactar o arquivo, vamos criar uma nova basta, para copiar o conteudo do binario do ffmpeg, e zipar o conteúdo:

mkdir -p ffmpeg/bin

cp ffmpeg-4.3.1-amd64-static/ffmpeg ffmpeg/bin/

cd ffmpeg

zip -r ../ffmpeg.zip .

Agora, vamos criar uma nova Layer em nosso ambiente de Lambdas na AWS, anexando o arquivo zip criado no passo acima como no exemplo a seguir:

Anexando Layer FFMPEG a nossa função Lambda

Vamos voltar ao menu Functions dentro de Lambda em nosso Console. Na aba code vamos descer a tela, e ir até a sessão Layers e clicar em Add Layer. Vamos preencher e selecionar o formulário, como na imagem abaixo

E (FINALMENTE) vamos ao nosso código!

Para a linguagem Go, não temos um editor online em funções lambda na AWS. Por isso, vamos gerar nosso código localmente, buildá-lo e subir um zip do mesmo via console.

Início de tudo

package main

func main() {
}

Em nosso ambiente local de desenvolvimento em Go, vamos criar uma nova pasta. Nesta pasta, iniciaremos o projeto com o famoso comando "go mod" para criar nosso arquivo de controle de módulos go do Projeto.

Após, iremos criar o arquivo main.go com o seguinte conteúdo:

package main

import "github.com/aws/aws-lambda-go/lambda"

func handler()  {

}
func main() {
    lambda.Start(handler)
}

Acima, importamos a biblioteca oficial lambda, para utilização em Go. Criamos uma função chamada handler onde vamos inserir nossa futura estrutura de conversão de áudio, e abaixo a função main, apenas executa a função handler em ambiente de execução do Lambda.

Agora vamos carregar a biblioteca oficial do s3, para conectar no bucket que irá iniciar a função(essa informação é importante, pois o start traz informações do bucket para a lambda). Em seguida, vamos criar um diretório temporário, dentro do ambiente de execução da lambda, para fazer download do arquivo, onde possa ser manipulado. Em seguida realizar o download, utilizando um log para verificar:

package main

import (
    "context"
    "fmt"
    "github.com/aws/aws-lambda-go/events"
    "github.com/aws/aws-lambda-go/lambda"
    "github.com/aws/aws-sdk-go/aws"
    "github.com/aws/aws-sdk-go/aws/session"
    "github.com/aws/aws-sdk-go/service/s3"
    "github.com/aws/aws-sdk-go/service/s3/s3manager"
    "log"
    "os"
)

func handler(_ context.Context, s3Event events.S3Event) {
    record := s3Event.Records[0]
    key := record.S3.Object.Key
    sess, _ := session.NewSession(&aws.Config{Region: &record.AWSRegion})
    downloader := s3manager.NewDownloader(sess)
    file, err := os.Create(fmt.Sprintf("/tmp/%s", key))
    if err != nil {
        panic(err)
    }
    defer file.Close()
    _, err = downloader.Download(file,
        &s3.GetObjectInput{
            Bucket: &record.S3.Bucket.Name,
            Key:    &key,
        })
    if err != nil {
        panic(err)
    }
    log.Printf("Downloaded %s", file.Name())
}

func main() {
    lambda.Start(handler)
}

Nossa função handler, recebe 2 parâmetros vindos de Context e events, libs da AWS que trazem informações a respeito do bucket que inicia a lambda.
Neste ponto, é interessante que façamos o primeiro upload do código buildado, para realizar um teste "manual". Primeiro vamos criar o build dessa aplicação com o comando:

go build -o main

Em seguida, vamos empacotar o arquivo em um arquivo zip, para realizar o upload:

zip main.zip main

Agora vamos ao console, realizar o upload:

Criando Trigger

Antes de testarmos o código, precisamos criar a trigger ou gatilho, que dará inicio a lambda que criamos.

Dentro da nossa função, no console AWS vamos clicar em Add Trigger.

Vamos preencher o formulário, conforme as 3 imagens abaixo:

Neste ponto, vamos selecionar o bucket dos arquivos brutos:

Em seguida selecionar todos os tipos de entrada de arquivos

Por final, vamos deixar um filtro para somente iniciar a lambda, para arquivos .wav

Primeiro teste

Agora, vamos ao nosso bucket, fazer um upload de arquivo .wav, e verificar o status no CloudWatch, e posteriormente verificar se o arquivo mp3 foi criado no outro bucket.

Acima vemos os 2 buckets utilizados em nosso projeto. Vamos acessar o mgm-wav-files para realizar o upload. Após o upload, vamos acessar o CloudWatch, ir ao meno Logs > Logs Groups. Lá haverá um grupo de log, com nome de nossa Lambda. Em nosso casso está assim:

Entrando em nosso log, vamos procurar se há a mensagem "Downloaded NOMEDOARQUIVO", como a seguir:

Neste caso, tudo certo, vamos continuar!

Convertando arquivo .wav com FFMPEG

Vamos utilizar a funciona a lib nativa Go OS, para utilizar a função exec.Command, que nos possibilita rodar comandos em nível de bash. E a partir dele, usar o ffmpeg para convertar o arquivo .wav para .mp3, gravando-o no diretório temporário criado anteriormente:

outputFile := strings.Replace(file.Name(), filepath.Ext(file.Name()), ".mp3", 1)
    cmd := exec.Command("ffmpeg", "-i", file.Name(), outputFile)
    out, err := cmd.CombinedOutput()
    if err != nil {
        log.Fatalf("cmd.Run() failed with %s\n", err)
    }
    log.Printf("Execution output:\n%s\n", string(out))
    output, err := os.Open(outputFile)
    if err != nil {
        panic(err)
    }

Gravando arquivo convertido em outro bucket

Agora, vamos acessar o arquivo criado, e fazer o upload para o bucket criado, apenas para receber os arquivos convertidos. O código exemplo, existe na documentação da AWS:

//put mp3 file in converted bucket
    destinationBucket := "mgm-mp3-files"
    _, err = s3.New(sess).PutObject(&s3.PutObjectInput{
        Bucket: &destinationBucket,
        Key:    aws.String(filepath.Base(outputFile)),
        Body:   output,
    })
    log.Printf("Copied %s to %s", outputFile, record.S3.Bucket.Name)

Código Final

package main

import (
    "context"
    "fmt"
    "github.com/aws/aws-lambda-go/events"
    "github.com/aws/aws-lambda-go/lambda"
    "github.com/aws/aws-sdk-go/aws"
    "github.com/aws/aws-sdk-go/aws/session"
    "github.com/aws/aws-sdk-go/service/s3"
    "github.com/aws/aws-sdk-go/service/s3/s3manager"
    "log"
    "os"
    "os/exec"
    "path/filepath"
    "strings"
)

func handler(_ context.Context, s3Event events.S3Event) {
    record := s3Event.Records[0]
    key := record.S3.Object.Key
    sess, _ := session.NewSession(&aws.Config{Region: &record.AWSRegion})

    //Download file to a temporary folder
    downloader := s3manager.NewDownloader(sess)
    file, err := os.Create(fmt.Sprintf("/tmp/%s", key))
    if err != nil {
        panic(err)
    }
    defer file.Close()
    _, err = downloader.Download(file,
        &s3.GetObjectInput{
            Bucket: &record.S3.Bucket.Name,
            Key:    &key,
        })
    if err != nil {
        panic(err)
    }
    log.Printf("Downloaded %s", file.Name())

    //transform wav file to a compress mp3 file
    outputFile := strings.Replace(file.Name(), filepath.Ext(file.Name()), ".mp3", 1)
    cmd := exec.Command("ffmpeg", "-i", file.Name(), outputFile)
    out, err := cmd.CombinedOutput()
    if err != nil {
        log.Fatalf("cmd.Run() failed with %s\n", err)
    }
    log.Printf("Execution output:\n%s\n", string(out))
    output, err := os.Open(outputFile)
    if err != nil {
        panic(err)
    }

    //put mp3 file in converted bucket
    destinationBucket := "mgm-mp3-files"
    _, err = s3.New(sess).PutObject(&s3.PutObjectInput{
        Bucket: &destinationBucket,
        Key:    aws.String(filepath.Base(outputFile)),
        Body:   output,
    })
    log.Printf("Copied %s to %s", outputFile, record.S3.Bucket.Name)
}

func main() {
    lambda.Start(handler)
}

PLUS - Mensagem assíncrona de fim da atividade

Por final, vamos fazer com que, ao final da execução do lambda, em caso de sucesso uma fila SQS seja abastecida com uma mensagem, para que consumidores(aplicativos, web, etc..) possam ser avisados do final do processo e disponibilização do arquivo mp3 convertido.

Vamos agora ao console AWS, procurar por SQS. O serviço simples de fila da própria Amazon. Vamos criar um tópico, chamado mp3-ready

Agora, voltando a nossa função lambda, vamos acessar o menu Add Destination.

Nosso formulário deve ser preenchido destga maneira, escolhendo a fila SQS criada(A mensagem de falta de permissão para uso do SQS pelo lambda, será solucionada no próximo passo)

Agora com nosso destino de lambda criado, precisamos dar permissão no IAM para nossa role de execução da lambda, criar mensagem no tópico criado no SQS

Permissão lambda > SQS

No console do IAM, clicar no menu ROLES. Procurar pela role criada para a lambda. Dentro dessa role, vamos no menu Add Permissions > Atacch polices. Na busca, procurar por SQS, e escolher AmazonSQSFullAccess(sabemos que não é o ideal rs.) e clicar em Add Permissions.

Repositório

Repositorio Github