The origin: borrowing from evolutionary computing

The term comes from genetic algorithm design. In evolutionary computing, a fitness function defines what "better" means so that solutions can gradually emerge through small changes across generations. The classic example: when using a genetic algorithm to optimise wing design, the fitness function assesses wind resistance, weight, air flow, and other desirable characteristics. At each generation, the engineer asks: is this closer to or further away from the goal?

Ford, Parsons and Kua borrow this concept for software:

An architectural fitness function provides an objective integrity assessment of some architectural characteristic(s).

In software, fitness functions check that developers preserve important architectural characteristics; the "-ilities" architects care about: scalability, security, performance, maintainability, resilience.

The core idea

An evolutionary architecture supports guided, incremental change across multiple dimensions. The key word is guided. Without guidance, incremental change is just drift. Fitness functions are what provide the guidance.

The fitness function protects the various architectural characteristics required for the system. These requirements differ greatly across systems and organisations: some require intense security; others require significant throughput or low latency; others need resilience to failure. A crucial early architecture decision is to define which dimensions matter most for a given system, based on business drivers, technical capabilities, and scale.

Why this matters

Most teams have implicit architectural goals: "the system should be fast", "services should be loosely coupled", "we should be secure". The problem is that implicit goals erode. Nobody notices the slow degradation until a characteristic has already failed.

Fitness functions make the implicit explicit. They turn architectural aspirations into verifiable checks. Automated where possible, manual where necessary.

A key insight: improving one architectural dimension can accidentally harm another. Improving performance with caching might harm data freshness or security. Fitness functions act as guardrails that detect these tradeoff violations before they reach production.

Categorising fitness functions

The book defines several dimensions for classifying fitness functions:

Atomic vs Holistic

• Atomic — tests one particular aspect of the architecture in isolation. Example: a unit test checking for cyclic dependencies in a package, or a code metric that checks cyclomatic complexity.
• Holistic — tests a combination of architectural aspects, assessing interactions between different concerns. Example: testing the number of concurrent users within a certain latency range while caching is enabled — this simultaneously checks scalability and data freshness. Holistic functions are harder to build but capture what atomic ones miss.

Triggered vs Continuous vs Temporal

• Triggered — executed in response to a specific event: a developer running a unit test, a CI pipeline stage, a QA person performing exploratory testing.
• Continuous — constant verification of architectural aspects. Monitoring and alerting are the classic examples. Netflix's Chaos Monkey — which runs in production and randomly terminates instances — is a continuous holistic fitness function that forces teams to build resilient services.
• Temporal — have a particular time component. Example: a reminder to check whether important security updates have been performed, or a scheduled dependency check that alerts on outdated libraries.

Static vs Dynamic

• Static — fixed predefined acceptable values. Binary pass/fail (a unit test), or a threshold (latency must be < 200ms).
• Dynamic — acceptable values depend on context. Acceptable latency might depend on actual system scale; security requirements might vary based on the regulatory environment.

Automated vs Manual

• Automated — unit tests, deployment pipeline checks, stress tests, chaos engineering. Ideally as much automation as possible.
• Manual — some things can't be automated (legal approval requirements, certain QA processes). Some things aren't automated yet. The goal is to push the boundary toward automation over time.

What fitness functions look like in practice

Fitness functions encompass existing engineering practices but also extend beyond them:

The best fitness functions are automated and triggered: they give feedback at the point of change, not weeks later. Place them in the deployment pipeline. Fast atomic functions early, slow holistic functions later.

Deployment pipelines as the enforcement mechanism

Fitness functions only work if they're part of the delivery workflow. The deployment pipeline is where they live:

1. Early stages — fast, atomic checks: architecture tests (phpat, ts-arch), code metrics, linting, security scanning, contract tests.
2. Middle stages — integration and performance tests, holistic triggered functions.
3. Later stages / production — continuous monitoring, chaos engineering, temporal reminders.

As Thoughtworks puts it: "creating the desired fitness functions — and including them in appropriate delivery pipelines — communicates these metrics as an important aspect of enterprise architecture."

The four layers of fitness (from NILUS)

A useful framing from practice splits fitness functions across four layers:

1. Structural fitness — code dependencies, database access patterns, API contracts, service boundaries.
2. Behavioural fitness — latency, resilience, throughput, consistency, recovery behaviour.
3. Operational fitness — deployment independence, observability coverage, runbook readiness, SLO compliance.
4. Semantic fitness — bounded context integrity, event naming quality, policy ownership, domain model consistency.

Most teams start at structural (the easiest to automate) and never reach semantic. But semantic fitness functions (checking that your domain model remains coherent as it evolves) are often the most valuable for long-lived systems.

Systems thinking

Dr. Russell Ackoff's quote captures the deeper point:

A system is never the sum of its parts. It is the product of the interaction of its parts.

Fitness functions that only measure individual components miss the point. The interesting failures happen at integration boundaries — between services, between teams, between intentions and reality. Holistic fitness functions (end-to-end latency, deployment frequency, change failure rate) capture what atomic ones cannot.

How I'm applying this

This connects directly to work I care about:

• Platform modernisations I've designed and implemented were operational fitness: bringing reliability through automated deployment pipelines, observability and monitoring, and runbook readiness. I just called it "keeping things running."
• ADRs capture the decisions. Fitness functions verify those decisions are still holding. Decisions and verification go hand in hand.
• Kent Beck's Test Desiderata is itself a fitness function for test quality — a checklist of characteristics that tests should exhibit (isolated, deterministic, fast, behavioural, structure-insensitive, specific, predictive).
• DORA metrics (deployment frequency, lead time, change failure rate, MTTR) are fitness functions for delivery capability.
• Code health metrics (as described in the Loveholidays case from Tropeçando 120) are fitness functions that enabled their AI-first shift — they invested in code health metrics before adopting AI, which is exactly the fitness-function-first approach.
• phpat (PHP, as a PHPStan extension) and ts-arch (TypeScript) — writing architecture rules as unit tests that run in CI is the purest implementation of triggered atomic fitness functions.

The pattern: define what matters, measure it, enforce it automatically, and revisit periodically. Architecture that can't be verified can't evolve — it can only decay.

Further reading

• Foreword to Building Evolutionary Architectures — Martin Fowler's foreword to the book, framing fitness functions as the mechanism to monitor architectural state in an evolutionary style.
• Fitness function-driven development — Paula Paul & Rosemary Wang apply the TDD mindset to architecture: write the fitness function first, then develop to pass it.
• Governing data products using fitness functions — Extending fitness functions into Data Mesh governance (2024).
• Building Evolutionary Architectures, 2nd Edition — The book.

Part of my reading notes on Building Evolutionary Architectures (Ford, Parsons, Kua).

Chapter 1: Software Architecture

Despite our best efforts, software becomes harder to change over time. For a variety of reasons, the parts that comprise software systems defy easy modifications, becoming more brittle and intractable over time. Changes in software projects are usually driven by a reevaluation of functionality and/or scope. But another type of change occurs outside the control of architects and long-term planners. Though architects like to be able to strategically plan for the future, the constantly changing software development ecosystem makes that difficult. Since we can't avoid change, we need to exploit it.

— On Evolutionary Architecture

An evolutionary architecture supports guided, incremental changes across multiple dimensions.

— Definition of Evolutionary Architecture

Related: Ralph Johnson on Architecture (via Fowler, 2003)

These quotes from Ralph Johnson (from [[2026-04-24 - Martin Fowler - Who Needs an Architect|Who Needs an Architect?]]) are foundational to the ideas in this book:

"In most successful software projects, the expert developers working on that project have a shared understanding of the system design. This shared understanding is called 'architecture.' [...] the architecture only includes the components and interfaces that are understood by all the developers."

— Architecture as a social construct, not a diagram.

"There is no theoretical reason that anything is hard to change about software. If you pick any one aspect of software then you can make it easy to change, but we don't know how to make everything easy to change. Making something easy to change makes the overall system a little more complex, and making everything easy to change makes the entire system very complex. Complexity is what makes software hard to change. That, and duplication."

— The fundamental tension that evolutionary architectures try to navigate: change vs complexity.

"Software is not limited by physics, like buildings are. It is limited by imagination, by design, by organization. In short, it is limited by properties of people, not by properties of the world. 'We have met the enemy, and he is us.'"

— The constraint is us, not the technology.

Chapter 2: Fitness Functions

An evolutionary architecture supports guided, incremental change across multiple dimensions.

-- on FItness Functions, chapter 2

The fitness function protects the various archutectural characteristics required for the system. The specific architectural requirements differ greatly across systems and organizations, based on business drivers, technical capabilities, and a host of other factors. Some systems require intense security; others require significant throughput factors.

-- on Fitness Functions, chapter 2

A system is never the sum of its parts. It is the product of the interaction of its parts.

-- Dr. Russel Ackoff

Check https://rafael.bernard-araujo.com/refactoring-patterns/introduce-parameter-object

There are PHP and Rust implemenation examples.

Serverless apps are fantastic for automatic scaling, but there’s a catch: they expect you to be stateless. Most web applications, however, rely on sessions to remember users and persist state. Traditional PHP session handlers store data on the filesystem, which doesn’t play nicely with ephemeral AWS Lambda instances. Your sessions vanish as soon as the instance disappears.

The usual fix? Fire up a Redis cluster. Works, but suddenly you’ve added infrastructure, ongoing maintenance, and extra costs. Your “serverless” app feels a lot less serverless.

What if we could manage sessions without touching Redis or any other server?

In this post, we’ll show you how to build a truly serverless PHP app using Bref, Symfony, and DynamoDB for session management. Along the way, you’ll see:

• A custom DynamoDB-backed session handler that replaces filesystem sessions
• How to deploy your app via Lambda Function URLs using AWS CDK
• Storing CSRF tokens in DynamoDB for fully stateless operation
• Single-table design patterns for efficient multi-entity storage

By the end, you’ll know not just how to implement this architecture, but also when it makes sense and what trade-offs you’re accepting.

The Challenge: Sessions in Serverless

Before we dive into the solution, let’s understand why traditional PHP sessions fail in serverless environments.

1. Ephemeral Storage: Lambda instances can vanish at any time. Writing sessions to /tmp is like storing them in sand. They disappear when the instance is recycled.
2. No Shared Filesystem: Each Lambda invocation runs on its own instance. User A’s session written by instance 1 is invisible to instance 2. That’s a problem if your user expects to stay logged in.
3. Horizontal Scaling Woes: Lambda scales horizontally automatically. Without centralized session storage, each instance is isolated. Consistent session management? Forget it.

The Traditional Solution: Redis/ElastiCache

Most serverless PHP guides suggest Redis. While it works, it comes with headaches:

• Infrastructure complexity: VPCs, subnets, and security groups
• Maintenance burden: Patching, monitoring, capacity planning
• Cold start penalty: VPC-connected Lambdas can take 1–2 extra seconds

Better idea: DynamoDB. It’s fully managed, serverless, and scales automatically. No Redis cluster, no maintenance, just pay for what you use.

Books and Authors App (Serverless Style)

Imagine you’re building a multi-tenant SaaS app, like an internal tool for managing books and authors. Each user needs a session, and each organization manages its own data. DynamoDB’s single-table design can elegantly handle all this. Serverless scaling takes care of traffic spikes automatically.

Here’s what this example demonstrates:

• Multi-entity relationships: Books belong to authors
• CRUD operations: Create, read, update, and delete across related entities
• Session-dependent workflows: Adding/editing books requires authentication
• Real-world complexity: More than a simple counter, less than a full e-commerce platform

Connecting to Real Use Cases

This architecture shines in scenarios like:

• Unpredictable traffic: Seasonal spikes when authors release new books
• Session management: Authors need persistent sessions to edit content
• Cost efficiency: During quiet periods, you pay pennies; during spikes, DynamoDB scales automatically
• Zero maintenance: No Redis clusters to monitor, no database servers to patch

The book management example proves that this approach isn’t just theoretical: it’s production-ready.

Architecture Overview

To build a serverless PHP application that supports sessions, CSRF protection, and persistent data, we follow a stateful/stateless separation pattern. This makes the architecture scalable, cost-efficient, and easy to maintain.

1. Stateful Layer: Persistent Data

This layer is responsible for storing all data that needs to survive beyond a single Lambda invocation.

• DynamoDB Table

  • Uses a single-table design to store sessions, CSRF tokens, users, books, and authors.
  • TTL enabled for automatic session expiration.
  • On-demand billing ensures automatic scaling with traffic.
  • Built-in multi-AZ replication provides high availability.

• Benefits

  • No infrastructure to manage or patch.
  • Automatically scales with unpredictable traffic.
  • Centralized storage simplifies queries and operations.

2. Stateless Layer: Application Logic

This layer runs the application code and handles requests without storing any persistent state locally.

• Lambda Function

  • Runs PHP-FPM via Bref.
  • Handles HTTP requests directly using a Lambda Function URL (HTTPS endpoint).
  • No VPC required to access DynamoDB, reducing cold start latency.

• Static Assets

  • Stored in S3 (optionally served via CloudFront) to keep Lambda stateless.

• Benefits

  • Scales automatically with traffic.
  • Cost-efficient: pay only for actual requests.
  • Stateless logic simplifies deployment and updates.

This design ensures a truly serverless PHP application that handles session state, persistent data, and scalable workloads without the operational overhead of managing Redis or other caching layers.

DynamoDB Session Handler and CSRF Implementation

Session Handler Implementation

In a serverless PHP application, traditional session storage (files or local memory) doesn’t work because Lambda functions are ephemeral. Each invocation may run on a different container, so we need a centralized, persistent session store.

The core of our solution is a custom session handler that implements PHP's SessionHandlerInterface.

How It Works

• Sessions are stored in DynamoDB instead of the filesystem.
• Each session has a unique session_id, which becomes the partition key (PK) in DynamoDB.
• Sessions include the serialized PHP session data and an expiration timestamp (TTL).
• The handler automatically reads/writes session data on session_start() and session_write_close().

Key Features

1. Automatic Expiration
   • DynamoDB TTL ensures sessions are removed automatically after expiration.
2. Atomic Operations
   • PutItem and UpdateItem guarantee consistent writes, even with concurrent requests.
3. Scalable
   • Can handle thousands of concurrent sessions without extra infrastructure.
4. Serverless-friendly
   • No local storage, no Redis, fully compatible with Lambda statelessness.

Implementation

<?php

namespace App\Session;

use AsyncAws\DynamoDb\DynamoDbClient;
use AsyncAws\DynamoDb\Input\DeleteItemInput;
use AsyncAws\DynamoDb\Input\GetItemInput;
use AsyncAws\DynamoDb\Input\PutItemInput;
use AsyncAws\DynamoDb\ValueObject\AttributeValue;

/**
 * A minimal DynamoDB-backed PHP session handler using AsyncAws.
 *
 * Table design (single-table compatible):
 *  - PK: "SESSION"
 *  - SK: "SID#<session_id>"
 *  - data: base64-encoded session payload (string)
 *  - expiresAt: unix epoch seconds (number), enable DynamoDB TTL on this attribute
 *
 * Garbage collection is handled by DynamoDB's TTL, so gc() is a no-op.
 */
class DynamoDbSessionHandler implements \SessionHandlerInterface
{
    private const string PK_VALUE = 'SESSION';
    private const string SK_PREFIX = 'SID#';

    public function __construct(
        private readonly DynamoDbClient $dynamoDb,
        private readonly string $tableName,
        private readonly int $ttlSeconds = 3600,
    ) {}

    public function open(string $path, string $name): bool
    {
        // Nothing to do
        return true;
    }

    public function close(): bool
    {
        // Nothing to do
        return true;
    }

    public function read(string $id): string
    {
        $result = $this->dynamoDb->getItem(new GetItemInput([
            'TableName' => $this->tableName,
            'Key' => [
                'PK' => new AttributeValue(['S' => self::PK_VALUE]),
                'SK' => new AttributeValue(['S' => self::SK_PREFIX . $id]),
            ],
            // Strongly consistent read to reduce stale sessions
            'ConsistentRead' => true,
        ]));

        $item = $result->getItem();
        if (!$item || !isset($item['data'])) {
            return '';
        }

        $encoded = $item['data']->getS();
        if ($encoded === null) {
            return '';
        }

        $payload = base64_decode($encoded, true);
        return $payload === false ? '' : $payload;
    }

    public function write(string $id, string $data): bool
    {
        $expiresAt = time() + $this->ttlSeconds;

        $this->dynamoDb->putItem(new PutItemInput([
            'TableName' => $this->tableName,
            'Item' => [
                'PK' => new AttributeValue(['S' => self::PK_VALUE]),
                'SK' => new AttributeValue(['S' => self::SK_PREFIX . $id]),
                'data' => new AttributeValue(['S' => base64_encode($data)]),
                'expiresAt' => new AttributeValue(['N' => (string) $expiresAt]),
            ],
        ]));

        return true;
    }

    public function destroy(string $id): bool
    {
        $this->dynamoDb->deleteItem(new DeleteItemInput([
            'TableName' => $this->tableName,
            'Key' => [
                'PK' => new AttributeValue(['S' => self::PK_VALUE]),
                'SK' => new AttributeValue(['S' => self::SK_PREFIX . $id]),
            ],
        ]));

        return true;
    }

    public function gc(int $max_lifetime): int|false
    {
        // Rely on DynamoDB TTL to expire items; nothing to scan/delete here.
        return 0;
    }
}

Why it matters?

This approach:

• Keeps your PHP sessions serverless-compatible.
• Avoids cold-start pitfalls associated with local or in-memory session storage.
• Provides a reliable, scalable, and fully managed solution for stateful data in a stateless environment.

CSRF Token Storage

In a serverless environment, CSRF tokens must be handled carefully. Because Lambda executions are stateless, tokens cannot be stored in memory or on the filesystem. Instead, CSRF tokens are persisted in DynamoDB alongside session data.

This approach ensures tokens remain valid and verifiable across multiple Lambda invocations.

How CSRF Tokens Are Stored

Each CSRF token is stored as a dedicated item in the DynamoDB table:

• Tokens are associated with a specific action
• Each token has a unique identifier
• An expiration timestamp is stored for automatic cleanup

This makes CSRF token storage consistent, durable, and serverless-compatible.

Data Model

CSRF tokens follow the same single-table design pattern used elsewhere in the application.

Using a distinct partition key avoids contention and allows tokens to scale independently from session traffic.

Lifecycle

1. A CSRF token is generated when a form is rendered.
2. The token is persisted in DynamoDB.
3. On form submission, the token is retrieved and validated.
4. After validation or expiration, the token is deleted or allowed to expire via TTL.

This lifecycle mirrors traditional CSRF handling while remaining compatible with Lambda’s

Implementation

class DynamoDbCsrfTokenStorage implements CsrfTokenStorageInterface
{
    private const string PK_VALUE = 'CSRF';
    private const string SK_PREFIX = 'TOKEN#';

    public function getToken(string $tokenId): string
    {
        $result = $this->dynamoDb->getItem(new GetItemInput([
            'TableName' => $this->tableName,
            'Key' => [
                'PK' => new AttributeValue(['S' => self::PK_VALUE]),
                'SK' => new AttributeValue(['S' => self::SK_PREFIX . $tokenId]),
            ],
        ]));

        $item = $result->getItem();
        return $item['value']->getS() ?? '';
    }

    public function setToken(string $tokenId, string $token): void
    {
        $expiresAt = time() + $this->ttlSeconds;

        $this->dynamoDb->putItem(new PutItemInput([
            'TableName' => $this->tableName,
            'Item' => [
                'PK' => new AttributeValue(['S' => self::PK_VALUE]),
                'SK' => new AttributeValue(['S' => self::SK_PREFIX . $tokenId]),
                'value' => new AttributeValue(['S' => $token]),
                'expiresAt' => new AttributeValue(['N' => (string) $expiresAt]),
            ],
        ]));
    }
}

This ensures CSRF protection works seamlessly across multiple Lambda invocations.

Symfony Configuration

Configuring Symfony correctly is key for serverless PHP apps to work reliably with Lambda, DynamoDB, and Bref. Here’s how we set it up.

1. Session Storage

We replace the default PHP session handler with our DynamoDBSessionHandler:

# config/packages/framework.yaml
framework:
    session:
        handler_id: App\Session\DynamoDBSessionHandler
        cookie_secure: auto
        cookie_samesite: lax
        cookie_lifetime: 3600  # 1 hour

Notes:

• handler_id points to our custom service.
• cookie_secure: auto ensures HTTPS enforcement on Lambda URLs or custom domains.
• cookie_lifetime aligns with DynamoDB TTL for consistency.

2. Service definition

Register the DynamoDB session handler as a Symfony service:

# config/services.yaml
services:
  App\Session\DynamoDbSessionHandler:
    arguments:
      $tableName: '%book_table_name%'
      $ttlSeconds: '%env(default:session_ttl_seconds:int:SESSION_TTL)%'

• $tableName comes from environment variables to support multiple environments.
• $ttl matches the session lifetime for automatic garbage collection.
  This configuration tells Symfony to use our custom handler for all session operations. The handler is automatically injected with the DynamoDB client through Symfony's autowiring.

3. RequestContextListener

To handle dynamic Lambda Function URLs, we register a listener:

# config/services.yaml
services:
    App\EventListener\RequestContextListener:
        tags:
            - { name: kernel.event_listener, event: kernel.request, method: onKernelRequest }

Purpose:

• Ensures Symfony’s URL generator produces correct URLs.
• Sets proper scheme and host for redirects, forms, and CSRF validation.
• Essential for Lambda Function URLs where host/scheme changes per invocation.

Why It’s Needed

Lambda Function URLs:

• Provide a direct HTTPS endpoint (e.g., https://xyz.lambda-url.us-east-1.on.aws/)
• Are dynamic and unknown at build time
• Require Symfony to know the scheme and host at runtime to generate correct URLs

Without a listener:

• Redirects may point to HTTP instead of HTTPS
• CSRF tokens may fail
• Session cookies might be rejected
• OAuth or SSO integrations could break

Implementation

<?php

namespace App\EventListener;

use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpKernel\Event\RequestEvent;
use Symfony\Component\HttpKernel\KernelEvents;
use Symfony\Component\Routing\RequestContext;

#[AsEventListener(event: KernelEvents::REQUEST, priority: 1024)]
class RequestContextListener
{
    public function __construct(private RequestContext $requestContext) {}

    public function onKernelRequest(RequestEvent $event): void
    {
        if (!$event->isMainRequest()) {
            return;
        }

        $request = $event->getRequest();

        // Force HTTPS for Lambda URLs and set proper context
        if ($request->headers->get('host') && str_contains($request->headers->get('host'), 'lambda-url')) {
            $this->requestContext->setScheme('https');
            $this->requestContext->setHost($request->headers->get('host'));
            $this->requestContext->setHttpPort(80);
            $this->requestContext->setHttpsPort(443);

            $request->server->set('HTTPS', 'on');
            $request->server->set('SERVER_PORT', 443);
            $request->server->set('REQUEST_SCHEME', 'https');
        }
    }
}

The CDK Output Dilemma:

// CDK can output the Lambda URL after deployment
new CfnOutput(this, 'LambdaURL', { 
    value: statelessStack.monolithLambdaFunctionUrl.url 
});
// But this value is only known AFTER deployment completes
// You can't use it as an environment variable in the SAME deployment

Tip: This listener is only necessary if you use the Lambda Function URL as the production endpoint. If you use a custom domain, this can be simplified or skipped.

With this configuration, Symfony becomes serverless-ready, maintaining sessions, CSRF protection, and routing behavior seamlessly while leveraging DynamoDB and Lambda.

Single-Table Design Pattern

All entities (sessions, CSRF tokens, users, books, authors) live in a single DynamoDB table. This simplifies the architecture and enables atomic operations across different entities.

• Why single-table?
  • Reduces infrastructure complexity.
  • Simplifies monitoring and backup.
  • Supports atomic transactions across multiple entity types.
  • Aligns with AWS best practices for DynamoDB.

AWS CDK Infrastructure with Bref

Deploying a serverless Symfony app requires some AWS setup. Using AWS CDK with Bref makes this smooth, maintainable, and repeatable.

Why CDK?

• Infrastructure as code: Everything is versioned and reproducible.
• Integration with Symfony: Easy to link environment variables, DynamoDB, and Lambda functions.
• Bref-friendly: Deploy PHP Lambda layers without manually configuring Lambda functions.

Stateful Stack: DynamoDB Table

import { NestedStack } from "aws-cdk-lib";
import * as ddb from "aws-cdk-lib/aws-dynamodb";

export class BlogAppStatefulStack extends NestedStack {
  public readonly ddb: ddb.Table;

  constructor(scope: Construct, id: string, props: MyNestedStackProps) {
    super(scope, id, props);

    this.ddb = new ddb.Table(this, 'ddb', {
      tableName: `${id}-table`,
      partitionKey: { name: 'PK', type: ddb.AttributeType.STRING },
      sortKey: { name: 'SK', type: ddb.AttributeType.STRING },
      billingMode: ddb.BillingMode.PAY_PER_REQUEST,
      deletionProtection: props.shared.environment === 'prod',
      timeToLiveAttribute: 'expiresAt',
    });
  }
}

Key features:

• Generic Key Schema: PK and SK enable single-table design
• TTL Enabled: expiresAt attribute automatically removes expired items
• Production Protection: Deletion protection enabled for production environments

Stateless Stack: Lambda Function with Bref

import { packagePhpCode, PhpFpmFunction } from "@bref.sh/constructs";
import * as lambda from "aws-cdk-lib/aws-lambda";
import { FunctionUrl } from "aws-cdk-lib/aws-lambda";

export class BlogAppStatelessStack extends NestedStack {
  public readonly monolithLambda: PhpFpmFunction;
  public monolithLambdaFunctionUrl: FunctionUrl;

  private createLambda(props: MyNestedStackProps, staticAssetsBucket: Bucket, ddb: ddb.Table) {
    const lambdaEnvironment = {
      APP_ENV: props.shared.environment,
      APP_SECRET: appSecret,
      ASSET_URL: `https://${staticAssetsBucket.bucketDomainName}/`,
      AWS_LAMBDA_LOG_FORMAT: 'text',
      BOOK_TABLE_NAME: `${props.shared.stackPrefix}-StatefulStack-table`,
    };

    const monolithLambda = new PhpFpmFunction(this, 'App', {
      handler: 'public/index.php',
      phpVersion: '8.4',
      code: packagePhpCode('php', {
        exclude: ['.env.local', 'bin/'],
      }),
      functionName: `${props.shared.stackPrefix}-App`,
      timeout: Duration.seconds(28),
      memorySize: Size.gibibytes(2).toMebibytes(),
      environment: lambdaEnvironment,
    });

    // Create Function URL with no authentication
    const monolithLambdaFunctionUrl = monolithLambda.addFunctionUrl({ 
      authType: lambda.FunctionUrlAuthType.NONE 
    });

    // Grant DynamoDB permissions
    ddb.grantReadWriteData(monolithLambda);

    return { monolithLambda, monolithLambdaFunctionUrl };
  }
}

Lambda Function URL Configuration

Lambda Function URLs provide a simple HTTPS endpoint without needing API Gateway:

const monolithLambdaFunctionUrl = monolithLambda.addFunctionUrl({ 
  authType: lambda.FunctionUrlAuthType.NONE 
});

Benefits of Lambda URLs:

• Simplicity: Direct HTTPS endpoint without API Gateway complexity
• Cost: No API Gateway charges
• Performance: One less hop in the request path
• Built-in HTTPS: Automatic TLS certificate management

Configuration Options:

• authType: NONE: Public access (suitable for web applications)
• authType: AWS_IAM: Requires AWS signature (for service-to-service communication)

Main Stack: Orchestration

export class BlogApp extends Stack {
  constructor(scope: Construct, id: string, props: MyStackProps) {
    super(scope, id, props);

    const stackPrefix = props.shared.envStackPrefix;

    const statefulStack = new BlogAppStatefulStack(
      this, `${stackPrefix}-StatefulStack`, props
    );

    const statelessStack = new BlogAppStatelessStack(
      this, `${stackPrefix}-StatelessStack`, props, statefulStack
    );

    // Output important values
    new CfnOutput(this, 'Lambda', { 
      value: statelessStack.monolithLambda.functionName 
    });
    new CfnOutput(this, 'LambdaURL', { 
      value: statelessStack.monolithLambdaFunctionUrl.url 
    });
    new CfnOutput(this, 'DynamoDb', { 
      value: statefulStack.ddb.tableName 
    });
  }
}

Deployment with CDK

With the infrastructure defined, deploying the application becomes a repeatable and predictable process. This section focuses on how the application is built, deployed, and updated using AWS CDK.

Local Development Environment

Local development mirrors the production setup as closely as possible while remaining lightweight.

• Docker is used to provide a consistent PHP environment.
• A Makefile abstracts common commands to reduce cognitive load.
• Symfony runs locally with the same session and configuration logic used in Lambda.

You can run:

# Pre-requisite - source your aws profile
make up

You can check logs via make logs. And get into the container with make bash. The application will be available at http://localhost:8000, but it might fail to load as there is no existent DynamoDB to connect with. You can check local .env file for environment variables.

Deploying

Deploy the application using standard CDK commands (inside the container):

# Pre-requisite - Bootstrap CDK if this is your first deployment - npx cdk bootstrap aws://<ACCOUNT_ID>/<REGION>
# Install dependencies
npm run deploy

Alternatively, you can use the Makefile command outsite the container:

make deploy

What Gets Created

The deployment creates:

1. DynamoDB table with TTL enabled
2. Lambda function with PHP 8.4 runtime (via Bref)
3. Lambda Function URL for HTTPS access
4. S3 bucket for static assets
5. IAM roles and permissions

The output should be similar to:

BlogApp (sandbox-blog-app): deploying... [1/1]
sandbox-blog-app: creating CloudFormation changeset...

 ✅  BlogApp (sandbox-blog-app)

✨  Deployment time: 148.76s

Outputs:
BlogApp.AssetsBucket = sandbox-blog-app-sandboxbloga-assetsbucket5cb76180-5lu45xsqvuym
BlogApp.DynamoDb = sandbox-BlogApp-StatefulStack-table
BlogApp.Lambda = sandbox-BlogApp-App
BlogApp.LambdaURL = https://kiv7utcwku6gihqgs4bfkeuzma0oaylo.lambda-url.us-east-1.on.aws/
Stack ARN:
arn:aws:cloudformation:us-east-1:973974862728:stack/sandbox-blog-app/9ba92580-e50b-11f0-a602-0afffb8dc1a9

✨  Total time: 163.03s

In this case, https://kiv7utcwku6gihqgs4bfkeuzma0oaylo.lambda-url.us-east-1.on.aws/ is the Lambda public URL.

When you access the URL, you will see a log-in form. You can use the "Register" link to create a login. Use it and you will be able to manage Authors and Books. Try to log out and access the pages directly.

Internally it will execute a series of commands:

# clean
npm run clean && \
# execute php packaging including composer install and npm build for symfony
npm run package:sandbox && \ 
# deploy as a sandbox not requiring approval
NODE_ENV=sandbox cdk deploy --require-approval never

There is a prod version executing make deploy:prod.

Testing the Session Implementation

The application includes a test endpoint to verify session persistence:

#[Route('/session-test', name: 'session_test')]
public function test(Request $request): JsonResponse
{
    $session = $request->getSession();
    $counter = $session->get('counter', 0);
    $session->set('counter', $counter + 1);

    return new JsonResponse([
        'message' => 'Session test',
        'session_id' => $session->getId(),
        'counter' => $session->get('counter'),
        'handler' => get_class($session->getMetadataBag()->getMetadata('handler')),
    ]);
}

Test with curl:

# First request creates session
curl -i -c cookie.txt https://your-lambda-url/session-test

# Subsequent requests increment counter
curl -i -b cookie.txt https://your-lambda-url/session-test
curl -i -b cookie.txt https://your-lambda-url/session-test

# outputs
➜ curl -i -c cookie.txt https://your-lambda-url/session-test
{"message":"Session incremented","session_id":"02b0c08e1ccd5f3ea015a06c69e29d11","counter":1,"handler":"App\\Session\\DynamoDbSessionHandler"}%

➜ curl -i -b cookie.txt https://your-lambda-url/session-test
{"message":"Session incremented","session_id":"02b0c08e1ccd5f3ea015a06c69e29d11","counter":2,"handler":"App\\Session\\DynamoDbSessionHandler"}%

➜ curl -i -b cookie.txt https://your-lambda-url/session-test
{"message":"Session incremented","session_id":"02b0c08e1ccd5f3ea015a06c69e29d11","counter":3,"handler":"App\\Session\\DynamoDbSessionHandler"}%

Performance Considerations

Cold Start Optimization

1. Memory Allocation: Using 2GB memory reduces cold start times
2. Composer Optimization: --no-dev --optimize-autoloader reduces code size
3. PHP 8.4: Latest PHP version with JIT compiler support

DynamoDB Performance

1. Consistent Reads: Ensures session consistency at the cost of slightly higher latency
2. On-Demand Billing: No capacity planning, automatic scaling
3. TTL: Automatic cleanup without scan operations

The serverless model's primary advantage is alignment of costs with actual usage, particularly beneficial for applications with variable or unpredictable traffic patterns. However, actual costs vary significantly based on traffic patterns, request complexity, and specific use cases. It's recommended to use AWS cost estimation tools and monitor actual usage to understand the financial impact for your specific application.

Security Best Practices

Session Security

1. Secure Flag: Ensures cookies only sent over HTTPS
2. SameSite: Protects against CSRF attacks
3. Regenerate ID: After authentication to prevent session fixation

framework:
    session:
        cookie_httponly: true
        cookie_secure: auto
        cookie_samesite: lax

DynamoDB Permissions

The Lambda function requires minimal permissions:

ddb.grantReadWriteData(monolithLambda);

This grants only:

• dynamodb:GetItem
• dynamodb:PutItem
• dynamodb:DeleteItem
• dynamodb:Query
• dynamodb:Scan

No administrative permissions are granted to the Lambda function.

Limitations

While serverless PHP with DynamoDB sessions offers compelling advantages, it's important to understand the limitations and trade-offs. Here's an honest assessment of where this architecture may not be the best fit:

1. Cold Start Latency

The Reality: Lambda cold starts can add 1-3 seconds to the first request after a function has been idle. In practice this occurs for less than 1% of the calls.

Mitigation Strategies:

• Provisioned Concurrency: Pre-warm Lambda instances to eliminate cold starts (adds ~$15/month per instance)
• Keep-Warm Pings: Use CloudWatch Events to invoke functions every 5-10 minutes (adds minimal cost but doesn't help with scaling)
• Larger Memory Allocation: We use 2GB memory which provides faster CPUs, reducing cold start duration
• Optimize Code: Minimize dependencies, use PHP preloading, optimize autoloader

When it's acceptable: Background jobs, internal tools, APIs with relaxed SLAs
When it's problematic: User-facing e-commerce, real-time chat, gaming applications

2. Request Timeout Constraints

The Reality: Our configuration uses 28 seconds timeout (API Gateway compatible), though Lambda supports up to 15 minutes, which Lambda URLs supports.

Not Suitable For:

• Long-running batch jobs: Data exports, report generation, video processing
• Large file uploads: Direct file uploads over 10MB become unreliable
• Complex data migrations: Multi-step transformations requiring minutes to complete
• WebSocket connections: Not supported by Lambda Function URLs (use API Gateway WebSocket instead)

Recommended Alternatives:

• Keep Lambda URL: If API Gateway specific features are not needed, we can use custom domain with Lambda URLs and process up to 15 minutes
• AWS Step Functions: Orchestrate long-running workflows across multiple Lambda invocations
• ECS/Fargate: For truly long-running processes (hours), use containers instead
• Presigned S3 URLs: For large file uploads, let clients upload directly to S3
• SQS + Background Workers: Offload heavy processing to asynchronous queues

3. Session Consistency Edge Cases

The Reality: DynamoDB is eventually consistent by default, but we use ConsistentRead: true to mitigate this.

Why We Use ConsistentRead:

'ConsistentRead' => true,  // Ensures we always get the latest session data

Rare Race Conditions:
Even with consistent reads, race conditions can occur when:

• Simultaneous Writes: User opens multiple tabs, both modify session simultaneously—last write wins
• Write-then-Read Timing: Session written in one Lambda, immediately read by another—minimal delay possible
• Cross-Region Scenarios: If using Global Tables, replication lag can cause stale reads in remote regions

Practical Impact: In 99.9% of cases, consistent reads solve the problem. Edge cases typically affect power users opening many tabs or distributed teams across continents.

Mitigation: For critical operations (e.g., payment processing), use DynamoDB conditional expressions to ensure atomic updates and detect conflicts.

4. DynamoDB Costs at Scale

DynamoDB's pay-per-request pricing is cost-effective at low-to-moderate traffic but pricing characteristics change at high scale.

Assumptions

DynamoDB:

• On-demand billing: $1.25 per million reads/writes
• 1KB session item size
• 1 read + 1 write per request

Redis (ElastiCache):

• t4g.medium: $0.037/hr (~$27/month)
• 1 node sufficient for low-medium traffic
• High traffic may require bigger node(s)

Cost Table

When Fixed Infrastructure (like Redis/ElastiCache) May Become More Cost-Effective:

• Sustained high traffic volumes where fixed costs are fully utilized
• Long-lived sessions with more reads than writes
• Advanced caching features needed beyond simple session storage

Hidden DynamoDB Cost Factors:

• Consistent reads cost more than eventually consistent reads
• Session writes on every request (even if session data unchanged)
• AWS free tier limitations after 12 months

Start with DynamoDB for simplicity and operational efficiency. Monitor costs monthly as traffic grows. If costs become a concern at high scale, evaluate whether fixed infrastructure or caching optimizations make sense for your specific use case.

These limitations are not dealbreakers but they're trade-offs. For the right use cases (bursty traffic, cost-sensitive, minimal ops), the benefits far outweigh the drawbacks.

Conclusion

Building serverless PHP applications doesn't require sacrificing familiar frameworks or patterns. By implementing a custom DynamoDB session handler, we achieve:

• Truly serverless architecture: No Redis, no EFS, pure AWS managed services
• Production-ready session management: Consistent, scalable, and secure
• Cost-effective: Pay only for actual usage
• Developer-friendly: Standard Symfony application with minimal modifications
• Type-safe infrastructure: AWS CDK with TypeScript
• Modern PHP: PHP 8.4 with all latest features
• Local development: Docker-compose for local testing

The combination of Bref for Lambda PHP support, Symfony for application framework, and DynamoDB for stateful storage creates a robust, scalable, and maintainable serverless application architecture.

When Should You Use This Architecture?

Choose this approach when:

• Traffic is unpredictable or bursty (blogs, seasonal apps, internal tools)
• Cost optimization matters more than absolute performance
• Zero operational overhead is a priority
• You need automatic scaling without capacity planning

Common use cases are:

• CMS - Blogs, documentation sites, and knowledge bases with infrequent or sporadic traffic, when sudden spikes are scaled automatically and quite periods costs pennies
• Admin Panels and Internal Tools - Dashboard interfaces, internal reporting tools, and back-office applications with sporadic usage patterns. DynamoDB maintains session state without requiring Redis or similar infrastructure.
• Multi-Tenant SaaS Applications - B2B platforms where each tenant has independent traffic patterns. DynamoDB's single-table design efficiently manages sessions across all tenants without cross-tenant interference.
• API Services with Session Requirements - REST APIs that need stateful operations like OAuth flows, multi-step workflows, or temporary data caching. No Redis clusters to maintain, no session cleanup cron jobs to manage. DynamoDB TTL handles everything automatically.
• Seasonal Applications - Event registration systems, holiday campaign sites, tax filing applications, and other time-bound services.
• Microservices Requiring Session State - Distributed systems where individual services need temporary state management across invocations.

Consider alternatives when:

• You require consistent sub-100ms response times
• Traffic is predictable and sustained at high levels (>10M requests/month)
• Long-running processes or WebSocket connections are needed

The Bigger Picture

This implementation demonstrates that serverless and stateful aren't mutually exclusive. While serverless advocates often emphasize "stateless functions," real-world applications need state management. The key is choosing the right state storage mechanism, and DynamoDB proves that managed, serverless databases can handle session management as effectively as traditional infrastructure, with far less operational burden.

Whether you're building a content management system, an internal admin panel, or a multi-tenant SaaS application, this architecture provides a production-ready foundation. Start simple, monitor costs and performance, and scale confidently knowing your infrastructure will grow with your application without requiring a dedicated ops team.

Resources

• Bref Documentation
• Bref CDK Constructs
• AsyncAws DynamoDB Client
• Symfony Session Documentation
• Lambda Function URLs
• DynamoDB Single-Table Design

Source Code

The complete source code for this application is available at: rafaelbernard/serverless-php-with-bref-symfony-and-dynamodb-session-management/

For detailed technical implementation notes, test coverage reports, and deployment validation, see IMPLEMENTATION_SUMMARY.md in the repository. This document covers:

• Complete test suite (112 tests across PHP and CDK)
• Infrastructure validation details
• Code quality metrics
• Deployment procedures and best practices

Bonus: Guide to Custom Domain Configuration with Route53

Lambda Function URLs provide a quick way to expose your Lambda function over HTTPS, but the auto-generated URL (e.g., https://abc123xyz.lambda-url.us-east-1.on.aws/) isn't branded or memorable. But you can add a Simple CNAME Mapping: Direct Route53 CNAME to Lambda Function URL (easiest, limited SSL control).

This is the quickest and easiest method. Just create a CNAME record pointing to your Lambda Function URL. Best for internal tools, prototypes, and non-production environments.

Prerequisites

Before configuring custom domains, ensure you have:

1. Domain registered in Route53 (or another registrar with ability to update nameservers)
2. Hosted Zone created in Route53 for your domain

Implementation with CDK

Here's how to add a custom domain CNAME record pointing to your Lambda Function URL using AWS CDK:

import * as route53 from 'aws-cdk-lib/aws-route53';
import * as route53Targets from 'aws-cdk-lib/aws-route53-targets';
import * as lambda from 'aws-cdk-lib/aws-lambda';
import { Construct } from 'constructs';

// Assuming you have a Lambda function with Function URL enabled
const myFunction = new lambda.Function(this, 'MyFunction', {
  // ... function configuration
  functionUrlOptions: {
    authType: lambda.FunctionUrlAuthType.NONE, // or AWS_IAM
  },
});

// Get the hosted zone for your domain
const hostedZone = route53.HostedZone.fromLookup(this, 'HostedZone', {
  domainName: 'yourdomain.com',
});

// Create CNAME record pointing to Lambda URL
new route53.CnameRecord(this, 'LambdaUrlCname', {
  zone: hostedZone,
  recordName: 'api', // Creates api.yourdomain.com
  domainName: cdk.Fn.parseDomainName(myFunction.functionUrl), // Extracts hostname from URL
  ttl: cdk.Duration.minutes(5),
  comment: 'CNAME to Lambda Function URL',
});

// Output the custom domain
new cdk.CfnOutput(this, 'CustomDomainUrl', {
  value: `https://api.yourdomain.com`,
  description: 'Custom domain URL for Lambda function',
});

Testing Your CNAME Setup

After creating the CNAME record, verify it works:

# Check DNS propagation
dig api.yourdomain.com

# Test the endpoint
curl -i https://api.yourdomain.com/

# Verify SSL certificate
openssl s_client -connect api.yourdomain.com:443 -servername api.yourdomain.com | grep subject

Expected Results:

• DNS query returns Lambda Function URL hostname as CNAME target
• HTTP request succeeds with same response as Lambda URL
• SSL certificate shows AWS-managed certificate (not your custom domain)

The whole purpose of refactoring is to make us program faster, producing more value with less effort.

and

But I think the most dangerous way that people get trapped is when they try to justify refactoring in terms of "clean code", "good engineering practice", or similar moral reasons. The point of refactoring isn't to show how sparkly a code base is -- it is purely economic. We refactor because it makes us faster -- fastor add features, faster to fix bugs.

-- From Refactoring: Improving the Design of Existing Code (Martin Fowler and Kent Beck), page 56

The first time you do something, you just do it. The second time you do something similar, you wince at the duplication, but you do the duplicate thing anyway. The third time you do something similar, you refactor.

-- Don Roberts

Key aspects of DDD include:

1. Domain Model: A shared understanding of the business logic, defined in terms meaningful to domain experts and developers.

2. Ubiquitous Language: A common language shared by technical and non-technical stakeholders to describe the domain, ensuring clarity and reducing miscommunication.

3. Bounded Contexts: Distinct areas within a larger system where a specific domain model applies. Each context can evolve independently while being integrated with others.

4. Entities and Value Objects: Entities have unique identities, while value objects are immutable and are defined only by their properties.

5. Aggregates: Clusters of related objects treated as a unit, ensuring consistency in business operations.

6. Repositories and Services: Repositories handle data access, while services implement business operations that don’t belong to a single entity.

DDD emphasizes collaboration between developers and domain experts to ensure software design mirrors business processes and terminology.

A particularly important part of DDD is the notion of Strategic Design - how to organize large domains into a network of Bounded Contexts. [1]

Why is this important for your business?

The design it proposes puts our focus on the core domain and the business logic, which makes our product relevant and where it differentiates from competitors. The DDD design boosts the understanding of what our application does instead of which technology (framework, dependencies) it uses.

Domain-Driven Design is an approach to software development that centers the development on programming a domain model that has a rich understanding of the processes and rules of a domain. The name comes from a 2003 book by Eric Evans that describes the approach through a catalog of patterns. Since then a community of practitioners have further developed the ideas, spawning various other books and training courses. The approach is particularly suited to complex domains, where a lot of often-messy logic needs to be organized. [1]

We will see more about how this translates to our code as we understand the key aspects to be expanded in future posts.

Related:
[1] Domain-Driven Design by Martin Fowler
[2] Domain-Driven Design on Wikipedia

Managing secrets securely in AWS Lambda functions is crucial for maintaining the integrity and confidentiality of your applications. AWS provides services like AWS Secrets Manager and AWS Systems Manager Parameter Store to manage secrets. However, frequent retrieval of secrets can introduce latency and additional costs. To optimize this, we can cache secrets using a Lambda Extension.

In this article, we will demonstrate how to use a pre-existing Lambda Extension to cache secrets for a PHP Lambda function using the Bref layer and AWS CDK for deployment.

On a high-level, these are the components involved:

Using the AWS Parameter and Secrets Lambda extension to cache parameters and secrets

The new AWS Parameters and Secrets Lambda extension provides a managed parameters and secrets cache for Lambda functions. The extension is distributed as a Lambda layer that provides an in-memory cache for parameters and secrets. It allows functions to persist values through the Lambda execution lifecycle, and provides a configurable time-to-live (TTL) setting.

When you request a parameter or secret in your Lambda function code, the extension retrieves the data from the local in-memory cache, if it is available. If the data is not in the cache or it is stale, the extension fetches the requested parameter or secret from the respective service. This helps to reduce external API calls, which can improve application performance and reduce cost.

Prerequisites

• AWS Account
• AWS CLI configured
• AWS CDK installed
• PHP installed
• Composer installed

If you have Docker, all requirements are being installed by it.

Repository Overview

The code for this project is available in the following GitHub repository: rafaelbernard/serverless-patterns. The relevant files are located in the lambda-extension-ssm-secrets-cdk-php folder.

Step-by-Step Guide

1. Cloning the Repository

First, clone the repository and navigate to the relevant directory:

git clone --branch rafaelbernard-feature-lambda-extension-ssm-secrets-cdk-php https://github.com/rafaelbernard/serverless-patterns.git
cd serverless-patterns/lambda-extension-ssm-secrets-cdk-php

2. Project Structure

The project structure is as follows:

.
├── assets
│   └── lambda
│       └── lambda.php
├── bin
│   └── cdk.ts
├── cdk
│   └── cdk-stack.ts
├── cdk.json
├── docker-compose.yml
├── Dockerfile
├── example-pattern.json
├── Makefile
├── package.json
├── package-lock.json
├── php
│   ├── composer.json
│   ├── composer.lock
│   └── handlers
│       └── lambda.php
├── README.md
├── run-docker.sh
└── tsconfig.json

3. Setting Up the Lambda Function

The main logic for fetching and caching secrets is in php/handlers/lambda.php:

<?php

use Bref\Context\Context;
use Bref\Event\Http\HttpResponse;
use GuzzleHttp\Client;
use Symfony\Component\HttpFoundation\JsonResponse;

// Responsibilities are simplified into one file for demonstration purposes
// We would have have those methods in a Service class

function getParam(string $parameterPath): string
{
    // Set `withDecryption=true if you also want to retrieve SecureString SSMs
    $url = "http://localhost:2773/systemsmanager/parameters/get?name={$parameterPath}&withDecryption=true";

    try {
        $client = new Client();

        $response = $client->get($url, [
            'headers' => [
                'X-Aws-Parameters-Secrets-Token' => getenv('AWS_SESSION_TOKEN'),
            ]
        ]);

        $data = json_decode($response->getBody());
        return $data->Parameter->Value;
    } catch (\Exception $e) {
        error_log('Error getting parameter => ' . print_r($e, true));
    }
}

function getSecret(string $secretName): stdClass
{
    $url = "http://localhost:2773/secretsmanager/get?secretId={$secretName}";

    try {
        $client = new Client();

        $response = $client->get($url, [
            'headers' => [
                'X-Aws-Parameters-Secrets-Token' => getenv('AWS_SESSION_TOKEN'),
            ]
        ]);

        $data = json_decode($response->getBody());
        return json_decode($data->SecretString);
    } catch (\Exception $e) {
        error_log('Error getting secretsmanager => ' . print_r($e, true));
    }
}

return function ($request, Context $context) {
    $secret = getSecret(getenv('THE_SECRET_NAME'));
    $response = new JsonResponse([
        'status' => 'OK',
        getenv('THE_SSM_PARAM_PATH') => getParam(getenv('THE_SSM_PARAM_PATH')),
        getenv('THE_SECRET_NAME') => [
            'password' => $secret->password,
            'username' => $secret->username,
        ],
    ]);

    return (new HttpResponse($response->getContent(), $response->headers->all()))->toApiGatewayFormatV2();
};

4. Setting Up AWS CDK Stack

The AWS CDK stack is defined in cdk/cdk-stack.ts:

import { CfnOutput, CfnParameter, Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { join } from "path";
import { packagePhpCode, PhpFunction } from "@bref.sh/constructs";
import { FunctionUrlAuthType, LayerVersion, Runtime } from "aws-cdk-lib/aws-lambda";
import { StringParameter } from "aws-cdk-lib/aws-ssm";
import { Policy, PolicyStatement } from 'aws-cdk-lib/aws-iam';
import { Secret } from 'aws-cdk-lib/aws-secretsmanager';

export class CdkStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const stackPrefix = id;

    // May be set as parameter new CfnParameter(this, 'parameterStoreExtensionArn', { type: 'String' });
    const parameterStoreExtensionArn = 'arn:aws:lambda:us-east-1:177933569100:layer:AWS-Parameters-and-Secrets-Lambda-Extension:11';
    const parameterStoreExtension = new CfnParameter(this, 'parameterStoreExtensionArn', { type: 'String', default: parameterStoreExtensionArn });

    const paramTheSsmParam = new StringParameter(this, `${stackPrefix}-TheSsmParam`, {
      parameterName: `/${stackPrefix.toLowerCase()}/ssm/param`,
      stringValue: 'the-value-here',
    });

    // CDK cannot create SecureString
    // You would create the SecureString out of CDK and use the param name here
    // const paramAnSsmSecureStringParam = StringParameter.fromSecureStringParameterAttributes(this, `${stackPrefix}-AnSsmSecureStringParam`, {
    //   parameterName: `/${stackPrefix.toLowerCase()}/ssm/secure-string/params`,
    // });

    const templatedSecret = new Secret(this, 'TemplatedSecret', {
      generateSecretString: {
        secretStringTemplate: JSON.stringify({ username: 'postgres' }),
        generateStringKey: 'password',
        excludeCharacters: '/@"',
      },
    });

    // The param path that will be used to retrieve value by the lambda
    const lambdaEnvironment = {
      THE_SSM_PARAM_PATH: paramTheSsmParam.parameterName,
      THE_SECRET_NAME: templatedSecret.secretName,
      // If you create the SecureString
      // THE_SECURE_SSMPARAM_PATH: paramAnSsmSecureStringParam.parameterName,
    };

    const functionName = `${id}-lambda`;
    const theLambda = new PhpFunction(this, `${stackPrefix}${functionName}`, {
      handler: 'lambda.php',
      phpVersion: '8.3',
      runtime: Runtime.PROVIDED_AL2,
      code: packagePhpCode(join(__dirname, `../assets/lambda`)),
      functionName,
      environment: lambdaEnvironment,
    });

    // Add extension layer
    theLambda.addLayers(
      LayerVersion.fromLayerVersionArn(this, 'ParameterStoreExtension', parameterStoreExtension.valueAsString)
    );

    // Set additional permissions for parameter store
    theLambda.role?.attachInlinePolicy(
      new Policy(this, 'additionalPermissionsForParameterStore', {
        statements: [
          new PolicyStatement({
            actions: ['ssm:GetParameter'],
            resources: [
              paramTheSsmParam.parameterArn,
              // If you create the SecureString
              // paramAnSsmSecureStringParam.parameterArn,
            ],
          }),
        ],
      }),
    )

    templatedSecret.grantRead(theLambda);

    const fnUrl = theLambda.addFunctionUrl({ authType: FunctionUrlAuthType.NONE });

    new CfnOutput(this, 'LambdaUrl', { value: fnUrl.url });
  }
}

5. Deploying with AWS CDK

Make sure you have already AWS variables set and run below command to install required dependancies:

# Using docker -- check run-docker.sh
make up

or

# Using local
npm ci
cd php && composer install --no-scripts && cd -

After that, you will have all dependencies installed. Deploy it executing:

# Using docker
make deploy

or

# Using local
npm run deploy

6. Testing the Lambda Function

The CDK output will have the Lambda function URL, which you can use to test and retrieve the values:

Outputs:
LambdaExtensionSsmSecretsCdkPhpStack.LambdaUrl = https://keamdws766oqzr6dbiindaix3a0fdojb.lambda-url.us-east-1.on.aws/

You should see the secret value and parameter value returned by the Lambda function. Subsequent invocations should retrieve the values from the cache, reducing latency and cost.

{
  "status": "OK",
  "/lambdaextensionssmsecretscdkphpstack/ssm/param": "the-value-here",
  "TemplatedSecret3D98B577-4jOWSbUMCHmF": {
    "password": "!o9GpBzpa>dYdo.Gx3J2!<zd(s-Fg;ev",
    "username": "postgres"
  }
}

Performance benefits

A similar example application written in Python performed three tests, reducing API calls ~98%. I am quoting their findings, as the benefits are the same for this PHP Lambda:

To evaluate the performance benefits of the Lambda extension cache, three tests were run using the open source tool Artillery to load test the Lambda function.

config:
 target: "https://lambda.us-east-1.amazonaws.com"
phases:
  -
duration: 60
arrivalRate: 10
rampTo: 40

Test 1: The extension cache is disabled by setting the TTL environment variable to 0. This results in 1650 GetParameter API calls to Parameter Store over 60 seconds.

Test 2: The extension cache is enabled with a TTL of 1 second. This results in 106 GetParameter API calls over 60 seconds.
Test 3: The extension is enabled with a TTL value of 300 seconds. This results in only 18 GetParameter API calls over 60 seconds.

In test 3, the TTL value is longer than the test duration. The 18 GetParameter calls correspond to the number of Lambda execution environments created by Lambda to run requests in parallel. Each execution environment has its own in-memory cache and so each one needs to make the GetParameter API call.

In this test, using the extension has reduced API calls by ~98%. Reduced API calls results in reduced function execution time, and therefore reduced cost.

7. Clean up

To delete the stack, run:

make bash
npm run destroy

Conclusion

In this article, we demonstrated how to use a pre-existing Lambda Extension to cache secrets for a PHP Lambda function using the Bref layer and AWS CDK for deployment. By caching secrets, we can improve the performance and reduce the cost of our serverless applications. The approach detailed here can be adapted to various use cases, enhancing the efficiency of your AWS Lambda functions.

For more information on the Parameter Store, Secrets Manager, and Lambda extensions, refer to:

• Using Parameter Store parameters in AWS Lambda functions
• Use AWS Secrets Manager secrets in AWS Lambda functions
• Introducing AWS Lambda Extensions
• Caching data and configuration settings with AWS Lambda extensions
• AWS blog on using Lambda Extensions to cache secrets

For more serverless learning resources, visit Serverless Land.

Part 3 is to show the upgrade path to Bref 2 and to achieve more coverage of the AWS resources. We will use DynamoDB, a powerful database for serverless architectures.

Some of those topics seem straightforward to some people, but I would like to avoid guessing that this is known to the audience since I have experienced some PHP developers struggling to put all these together for the first time due to the paradigm change. It should be fun.

Table of contents:

1. What else are we doing?
2. Describing more AWS services - Adding a DynamoDB table
3. Bref upgrade
4. Testing CDK
5. PHP and AWS Services
6. Wrap-up

What else are we doing?

In this section, we'll explore additional functionalities and enhancements to our serverless application. Building upon the foundation laid in Part 2, we'll introduce new features and integrations to further extend the capabilities of our AWS PHP application.

The Part 2 uses the result of the Fibonacci of a provided integer or a random integer from 400 to 1000 (to get a good image and not to overflow integer). This integer is the number of pixels of an image from the bucket and an arbitrary request metadata we are creating. If the image does not exist, the lambda will fetch a random image from the web with that number of pixels, save it and generate the metadata.

The computing complexity is irrelevant because it could be very complex logic or very simple, and the topics we are discussing in this part of the series will use the same design.

The lambda will now search the metadata in a DynamoDB table, saving the metadata when it does not exist. DynamoDB is largely used in Lambda code.

Get the part-3 source-code on GitHub and the diff from part-2.

Describing more AWS services - Adding a DynamoDB Table

DynamoDB plays a crucial role in serverless architectures, offering scalable and high-performance NoSQL database capabilities. In this section, we'll delve into the process of integrating DynamoDB into our AWS CDK stack, expanding our application's data storage and retrieval capabilities.

DynamoDB is a fully managed NoSQL database service provided by AWS, offering seamless integration with other AWS services, automatic scaling, and built-in security features. Its scalability, low latency, and flexible data model make it well-suited for serverless architectures and applications with varying throughput requirements.

    const table = new Table(this, TableName, {
      partitionKey: { name: 'PK', type: AttributeType.STRING },
      sortKey: { name: 'SK', type: AttributeType.STRING },
      removalPolicy: RemovalPolicy.DESTROY,
      tableName: TableName,
    });

Following the same principles for creating other AWS resources, we utilize the AWS CDK to define a DynamoDB table within our stack. Let's dive into the key parameters of the Table constructor:

• partitionKey: This parameter defines the primary key attribute for the DynamoDB table, used to distribute items across partitions for scalability. In our example, { name: 'PK', type: AttributeType.STRING } specifies a partition key named 'PK' with a string type. The naming convention ('PK') is arbitrary and can be tailored to suit your application's needs.
• sortKey: For tables requiring a composite primary key (partition key and sort key), the sortKey parameter comes into play. Here, { name: 'SK', type: AttributeType.STRING } defines a sort key named 'SK' with a string type. Like the partition key, the name and type of the sort key can be customized based on your data model.
• removalPolicy: This parameter determines the behaviour of the DynamoDB table when the CloudFormation stack is deleted. By setting RemovalPolicy.DESTROY, we specify that the table should be deleted (destroyed) along with the stack. Alternatively, you can opt for RemovalPolicy.RETAIN to preserve the table post-stack deletion, which may be useful for retaining data.

By decoupling configuration from implementation, we adhere to SOLID principles, ensuring cleaner and more robust code. This approach fosters flexibility, allowing our code to seamlessly adapt to changes, such as modifications to the table name while maintaining its functionality.

The implementation code is aware that the name will come from an environment variable and will work with that (yes, if you think that test will be easy to write, you are right):

    const lambdaEnvironment = {
      TableName,
      TableArn: table.tableArn,
      BucketName: brefBucket.bucketName,
    };

Bref Upgrade

Bref, the PHP runtime for AWS Lambda, continually evolves to provide developers with the latest features and optimizations. In this section, we'll discuss the upgrade to Bref 2.0 and explore how it enhances the deployment process and performance of our serverless PHP applications.

In this section, we're upgrading our usage of Bref, a PHP runtime for AWS Lambda, to version 2.0. Bref simplifies the deployment of PHP applications to AWS Lambda, enabling us to run PHP code serverlessly.

The upgrade involves modifying our AWS CDK code to utilize the new features and improvements introduced in Bref 2.0. One notable improvement is the automatic selection of the latest layer of the PHP version, which simplifies the deployment process and ensures that our Lambda functions run on the most up-to-date PHP environment available.

  const getLambda = new PhpFunction(this, ${stackPrefix}${functionName}, {
    handler: 'get.php',
    phpVersion: '8.3',
    runtime: Runtime.PROVIDED_AL2,
    code: packagePhpCode(join(__dirname, ../assets/get), {
      exclude: ['test', 'tests'],
    }),
    functionName,
    environment: lambdaEnvironment,
  });

• `PhpFunction` Constructor: We're using the `PhpFunction` constructor provided by Bref to define our Lambda function. This constructor allows us to specify parameters such as the handler file, PHP version, runtime, code location, function name, and environment variables.
• `handler`: Specifies the entry point file for our Lambda function, where the execution starts.
• `phpVersion`: Defines the PHP version to be used by the Lambda function. In this case, we're using PHP version 8.3.
• `runtime`: Indicates the Lambda runtime environment. Here, `Runtime.PROVIDED_AL2` signifies the use of the Amazon Linux 2 operating system.
• `code`: Specifies the location of the PHP code to be deployed to Lambda.
• `functionName`: Sets the name of the Lambda function.
• `environment`: Allows us to define environment variables required by the Lambda function, such as database connection strings or configuration settings.

By upgrading to Bref 2.0 and configuring our Lambda function accordingly, we ensure compatibility with the latest enhancements and optimizations provided by Bref, thereby improving the performance and reliability of our serverless PHP applications on AWS Lambda.

Testing CDK

Ensuring the correctness and reliability of our AWS CDK infrastructure is crucial for maintaining a robust serverless architecture. In this section, we'll delve into testing our CDK resources, focusing on the DynamoDB table we added in the previous section.

As described earlier, we utilized the AWS CDK to provision a DynamoDB table within our serverless stack. Now, let's ensure that the table is configured correctly and behaves as expected by writing tests using the CDK's testing framework.

First, let's revisit how we added the DynamoDB table:

const table = new Table(this, TableName, {
  partitionKey: { name: 'PK', type: AttributeType.STRING },
  sortKey: { name: 'SK', type: AttributeType.STRING },
  removalPolicy: RemovalPolicy.DESTROY,
  tableName: TableName,
});

In this code snippet, we define a DynamoDB table with specified attributes such as partition key, sort key, removal policy, and table name. Now, to ensure that this table is created with the correct configuration, we'll write tests using CDK's testing constructs.

Check the following thest:

test('Should have DynamoDB', () => {
  expectCDK(stack).to(
    haveResource(
      'AWS::DynamoDB::Table',
      {
        "DeletionPolicy": "Delete",
        "Properties": {
          "AttributeDefinitions": [
            {
              "AttributeName": "PK",
              "AttributeType": "S",
            },
            {
              "AttributeName": "SK",
              "AttributeType": "S",
            },
          ],
          "KeySchema": [
            {
              "AttributeName": "PK",
              "KeyType": "HASH",
            },
            {
              "AttributeName": "SK",
              "KeyType": "RANGE",
            },
          ],
          "ProvisionedThroughput": {
            "ReadCapacityUnits": 5,
            "WriteCapacityUnits": 5,
          },
          "TableName": "BrefStory-table",
        },
        "Type": "AWS::DynamoDB::Table",
        "UpdateReplacePolicy": "Delete",
      },
      ResourcePart.CompleteDefinition,
    )
  );
});

This test ensures that the DynamoDB table is created with the correct attribute definitions, key schema, provisioned throughput, table name, and other properties specified during its creation. By writing such tests, we validate that our CDK infrastructure is provisioned accurately and functions as intended.

PHP and AWS Services

Leveraging PHP in a serverless environment opens up new possibilities for interacting with AWS services. In this section, we'll examine how PHP code seamlessly integrates with various AWS services, following best practices for maintaining clean and modular code architecture.

This is the part where we have fewer serverless needs impacting the code, as the PHP code will follow the same logic we might be using to communicate with AWS services on any other platform overall (there are always some specific use cases).

The reuse of the same existing logic is excellent. It leverages the decision to keep using PHP when moving that workload to Serverless, as the bulk of the knowledge and already proven code would remain as-is. We may escape the trap of classifying that PHP code as legacy as if it should be avoided, terminated or halted.

As a side note, a few external layers of our software architecture are touched if a good software architecture was applied before. Therefore, during the implementation of this architectural change, it should be quick to realise how beneficial and time-saving it is to have a well-architectured application with a balanced decision for patterns, principles, and designs to be applied, ultimately giving flexibility to the application and its features.

The handler is simplified now and should accommodate everything to a class in the direction of following SRP, a principle that we are bringing to the code during the code bites:

Applications, domains, infrastructure, etc

Our `PicsumPhotoService` is still orchestrating the business logic. The Single Responsibility Principle and Inversion of Control are applied. We are injecting the specialized services in the constructor:

// readonly class PicsumPhotoService
    public function __construct(
        private HttpClientInterface $httpClient,
        private ImageStorageService $storageService,
        private ImageRepository $repository,
    )
    {
    }

Each specialized service has all its dependencies injected in the constructor as well. We can see the factory instantiation:

    public static function createPicsumPhotoService(): PicsumPhotoService
    {
        return new PicsumPhotoService(
            HttpClient::create(),
            new S3ImageService(
                new S3Client(),
                getenv('BucketName'),
            ),
            new DynamoDbImageRepository(
                new DynamoDbClient(),
                getenv('TableName'),
            ),
        );
    }

The `ImageStorageService` will handle all image operations, connecting to the AWS Service when appropriate and observing business logic details. This is a slim interface:

interface ImageStorageService
{
    public function getImageFromBucket(int $imagePixels): ?array;

    public function saveImage(int $imagePixels, mixed $fetchedImage): void;

    public function createAndPutMetadata(int $imagePixels, array $metadata): PutObjectOutput;
}

Instead of `: PutObjectOutput`, usually we would return a domain object, to not couple the interface with implementation details of using S3 Services, but for simplicity, I did not create a domain object here. It would be preferable though.

The `ImageRepository` will handle all metadata operations. It will save into a repository and observe logic details as well. Following the same principles, this is a slim interface:

interface ImageRepository
{
    public function findImage(int $imagePixels): ImageMetadataItem;

    public function addImageMetadata(ImageMetadataItem $imageMetadataItem): PutItemOutput;
}

The `ImageMetadataItem` is a representation of one of the domain objects we have in our codebase.

readonly class ImageMetadataItem
{
    public function __construct(public int $imagePixels, public array $metadata)
    {
    }

    public function toDynamoDbItem(): array
    {
        return [
            'PK' => new AttributeValue(['S' => 'IMAGE']),
            'SK' => new AttributeValue(['S' => "PIXELS#{$this->imagePixels}"]),
            'pixels' => new AttributeValue(['N' => "{$this->imagePixels}"]),
            'metadata' => new AttributeValue(['S' => json_encode($this->metadata)]),
            ...ConvertToDynamoDb::item($this->metadata),
        ];
    }

    /**
     * @param array $item
     */
    public static function fromDynamoDb(array $item): static
    {
        return new static(
            (int) $item['pixels']->getN(),
            (array) json_decode($item['metadata']->getS()),
        );
    }
}

If you check the implementation details, it operates transparently with all the services, business logic and AWS Services without any high couple with them. There are two utility functions:

• toDynamoDbItem: to transform the object into a valid DynamoDb Item to be added
• fromDynamoDb: to perform the opposite operation, transforming a DynamoDb Item into a domain object

The scope of the operation is very clear and does not bring the domain into dependency on those services, as the domain object can be used independently. It does not block any other way of dealing with it, giving the usage with other types of services, such as different databases or APIs. This is very important to the maintainability of the application without sacrificing the ease of readiness as it keeps the context of the utilities in the right place.

If you check all PHP code carefully, Bref is such a great abstraction layer that, removing the code from the handler file, any other line of code can be used as a lambda or a web application interchangeably without changing any line of code. This is very powerful, as you can imagine how you can leverage and migrate some of the existing code to lambda by just creating a handler that will trigger your existing code, if the code is well structured.

Wrap-up

It would be simple like that. Check more details in the source code, install it and try it yourself. This project is ready to:

• Extend lambda function using Bref
• Upgrade to use Bref 2.0
• Create a DynamoDB table
• Test the stack Cloudformation code
• Separate the PHP logic
• Have PHP communicating with AWS Services

Links:

• https://rafael.bernard-araujo.com/tag/bref-php-aws-story
• https://bref.sh
• https://dev.to/rafaelbernard/a-bref-aws-php-history-part-1-2agn
• https://dev.to/rafaelbernard/a-bref-aws-php-story-part-2-1dhe
• https://github.com/rafaelbernard/bref-initial-php-aws-story/tree/part-3
• https://github.com/rafaelbernard/bref-initial-php-aws-story/compare/tag-part-2...tag-part-3
• https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Introduction.html

Considering AWS services, for most of the options EventBridge Scheduler will be used to manage tasks as it is capable of invoking lots of AWS services. One of them is invoking a containerized application, or ECS task.

Amazon EventBridge Scheduler is a serverless scheduler that allows you to create, run, and manage tasks from one central, managed service. Highly scalable, EventBridge Scheduler allows you to schedule millions of tasks that can invoke more than 270 AWS services and over 6,000 API operations. Without the need to provision and manage infrastructure, or integrate with multiple services, EventBridge Scheduler provides you with the ability to deliver schedules at scale and reduce maintenance costs.
-- https://docs.aws.amazon.com/scheduler/latest/UserGuide/what-is-scheduler.html
(EventBridge Scheduler is recommended to be used instead of CloudWatch Scheduler with EventBridge rules)

I worked on an application running on EC2 to ECS that is still using its cron jobs. Cron jobs were migrated to EventBridge Scheduler. Our CI/CD uses GitHub Actions and Terraform. AWS provides actions that can create and deploy a ECS task definition (the container blueprint) to an ECS service, but there is no action to deploy an ECS task to the EventBridge Scheduler, as the cron task is not executed under a service.

To deploy the new code we have to write some code to the GitHub Action and I think it might benefit others in a similar context. We use Terraform as Infrastructure as a Code, so keep this in mind if you need to adapt to your IaaS solution.

There will be the full Yaml file here but I will comment parts of it separately afterwards.

name: Deploy Scheduled task XYZ

on:
  workflow_dispatch:
    inputs:
      imageHash:
        description: 'Image hash to deploy'
        required: true
        type: string
      environment:
        description: 'Environment to run tests against'
        type: environment
        required: true
        default: test

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

env:
  APP_NAME: application-name-here
  AWS_REGION: "ap-southeast-2"
  ECR_NAME: ecr-name-here
  ECS_CLUSTER: cluster-name-here
  IMAGE_NAME: application-image-name-here
  TASK_NAME: cron-task-name-here

permissions:
  id-token: write
  contents: read    # This is required for actions/checkout

jobs:
  deploy:
    name: Deploy to ${{ inputs.environment }}
    runs-on: ubuntu-latest
    environment: ${{ inputs.environment }}
    env:
      JOB_ENV: ${{ inputs.environment }}
    steps:
      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets[format('iam_role_to_assume_{0}', inputs.environment)] }}
          role-session-name: github-ecr-push-workflow-${{ inputs.environment }}
          aws-region: ${{ env.AWS_REGION }}

      - name: Verify image
        run: aws ecr describe-images --repository-name ${{ inputs.environment }}-${{ env.ECR_NAME }}-${{ env.APP_NAME }} --image-ids imageTag=${{ inputs.imageHash }}

      - name: Login to Amazon ECR
        id: login-ecr
        uses: aws-actions/amazon-ecr-login@v2

      - name: Download the task definition ${{ env.TASK_NAME }}
        run: aws ecs describe-task-definition --task-definition ${{ env.TASK_NAME }} --query taskDefinition > task-definition.json

      - name: Fill in the new image ID in the Amazon ECS task definition ${{ env.TASK_NAME }}
        id: task-def-cron
        uses: aws-actions/amazon-ecs-render-task-definition@v1
        env:
          ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
        with:
          task-definition: task-definition.json
          container-name: ${{ env.TASK_NAME }}
          image: ${{ env.ECR_REGISTRY }}/${{ env.JOB_ENV }}-${{ env.ECR_NAME }}-${{ env.APP_NAME }}:${{ inputs.imageHash }}

      - name: Deploy Amazon ECS task definition ${{ env.TASK_NAME }}
        id: deploy-cron
        uses: aws-actions/amazon-ecs-deploy-task-definition@v1
        with:
          task-definition: ${{ steps.task-def-cron.outputs.task-definition }}
          cluster: ${{ inputs.environment }}-${{ env.ECS_CLUSTER }}

      - name: Checkout infrastructure
        uses: actions/checkout@v4
        with:
          repository: orgnamehere/iaas-repo-here
          ref: main
          path: './working-path'
          token: ${{ secrets.PAT_TOKEN }}

      - name: Update schedule ${{ env.TASK_NAME }}
        working-directory: './working-path'
        env:
          GH_TOKEN: ${{ secrets.PAT_TOKEN }}
          INFRASTRUCTURE_FILE: 'path/to/your/module/terraform-file-here.tf'
          UNESCAPED_ARN: ${{ steps.deploy-cron.outputs.task-definition-arn }}
        run: |
          # Escape regexp non-safe characters from the ARN to prevent sed to fail
          export ESCAPED_ARN=${UNESCAPED_ARN//:/\\:}
          export ESCAPED_ARN=${ESCAPED_ARN//\//\\/}
          echo "Escaped ARN: $ARN"
          # Retrieve <appl-name>:<version> part of the ARN to use in PR 
          export ARRAY_ARN_PARTS=(${UNESCAPED_ARN//\// })
          export VERSION_PART=${ARRAY_ARN_PARTS[1]}
          export COMMIT_MESSAGE="DEPLOY: Deployment on ${{ inputs.environment }} - $VERSION_PART"
          # Use task definition version for branch name
          export BRANCH_NAME="deploy-${VERSION_PART//:/-}"
          git config user.email "deployment-pipeline@example.com"
          git config user.name "Github Actions Pipeline"
          git checkout -b ${BRANCH_NAME}
          sed -i '/task_definition_arn /s/".*/'"\"${ESCAPED_ARN}"\"'/' $INFRASTRUCTURE_FILE
          git add ${{ env.INFRASTRUCTURE_FILE }}
          git commit -m "$COMMIT_MESSAGE"
          git push --set-upstream origin ${BRANCH_NAME}
          gh pr create --fill --body "- [x] $COMMIT_MESSAGE"

This pipeline will create the scheduled task definition, check out the IaaS repository, change the Scheduler task definition ARN and create a PR in the IaaS repository. We are using that also as a way to have approval to deploy to Production, but it can be automated if needed.

Let's comment on some parts:

on:
  workflow_dispatch:
    inputs:
      imageHash:
        description: 'Image hash to deploy'

It is good to separate the image creation from the deployment. This input is required assuming the image was created and published to the registry. This promotes reusability and flexibility.

      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets[format('iam_role_to_assume_{0}', inputs.environment)] }}
          role-session-name: github-ecr-push-workflow-${{ inputs.environment }}
          aws-region: ${{ env.AWS_REGION }}

Environment is a required input and this pipeline can be executed against any environment you defined in your repository.

      - name: Deploy Amazon ECS task definition ${{ env.TASK_NAME }}
        id: deploy-cron
        uses: aws-actions/amazon-ecs-deploy-task-definition@v1
        with:
          task-definition: ${{ steps.task-def-cron.outputs.task-definition }}
          cluster: ${{ inputs.environment }}-${{ env.ECS_CLUSTER }}

Although the action name is "deploy task definition" it will create the task, but not deploy, as this is only possible when you provide a service input (by the time this article is being written). But we are not deploying to a service though, so the action will only create the task definition, but the EventBridge Scheduler remains calling the same task definition it was invoking before the creation of this task definition.

      - name: Checkout infrastructure
        uses: actions/checkout@v4
        with:
          repository: orgnamehere/iaas-repo-here
          ref: main
          path: './working-path'
          token: ${{ secrets.PAT_TOKEN }}

Using AWS CLI was an alternative we considered, but changing the target of the EventBridge scheduler becomes a little bit confusing and brings some cognitive complexity in case we need to change something. We decided then to fetch the IaaS repository and control the task definition version to be the target of the scheduler in Terraform code, so we could also be sure any dependency that the target change could have would be managed by Terraform, instead of another CLI change in this pipeline. We checkout the IaaS repo and save the path as ./working-path to keep the workspace clean. The name is your choice.

      - name: Update schedule ${{ env.TASK_NAME }}
        working-directory: './working-path'
        env:
          GH_TOKEN: ${{ secrets.PAT_TOKEN }}
          INFRASTRUCTURE_FILE: 'path/to/your/module/terraform-file-here.tf'
          UNESCAPED_ARN: ${{ steps.deploy-cron.outputs.task-definition-arn }}
        run: |
          # Escape regexp non-safe characters from the ARN to prevent sed to fail
          export ESCAPED_ARN=${UNESCAPED_ARN//:/\\:}
          export ESCAPED_ARN=${ESCAPED_ARN//\//\\/}
          echo "Escaped ARN: $ARN"
          # Retrieve <appl-name>:<version> part of the ARN to use in PR 
          export ARRAY_ARN_PARTS=(${UNESCAPED_ARN//\// })
          export VERSION_PART=${ARRAY_ARN_PARTS[1]}
          export COMMIT_MESSAGE="DEPLOY: Deployment on ${{ inputs.environment }} - $VERSION_PART"
          # Use task definition version for branch name
          export BRANCH_NAME="deploy-${VERSION_PART//:/-}"
          git config user.email "deployment-pipeline@example.com"
          git config user.name "Github Actions Pipeline"
          git checkout -b ${BRANCH_NAME}
          sed -i '/task_definition_arn /s/".*/'"\"${ESCAPED_ARN}"\"'/' $INFRASTRUCTURE_FILE
          git add ${{ env.INFRASTRUCTURE_FILE }}
          git commit -m "$COMMIT_MESSAGE"
          git push --set-upstream origin ${BRANCH_NAME}
          gh pr create --fill --body "- [x] $COMMIT_MESSAGE"

This is where we use sed to search and replace the ARN in the terraform code. We scape the ARN before applying sed to not mess with the search regexp.

The terraform code expected to be changed will be something like this:

# main.tf
-        task_definition_arn     = "arn:aws:ecs:ap-southeast-2:123456789012:task-definition/task-definition-cron-name:57"
+       task_definition_arn     = "arn:aws:ecs:ap-southeast-2:123456789012:task-definition/task-definition-cron-name:58"

Links:

• https://docs.aws.amazon.com/AmazonECS/latest/userguide/scheduled_tasks-eventbridge-scheduler.html
• https://docs.aws.amazon.com/scheduler/latest/UserGuide/what-is-scheduler.html
• https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html
• https://docs.aws.amazon.com/cli/latest/reference/scheduler/update-schedule.html