Skip to content

fix: use alias for versioned lambda functions #6767

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
anatolzak wants to merge 6 commits into
base: dev
Choose a base branch
from
Open

fix: use alias for versioned lambda functions #6767

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
0e3e96d
Route versioned functions through a stable alias
anatolzak Apr 18, 2026
207829d
fix
anatolzak Apr 19, 2026
0a7d668
Compute targetArn and qualifier lazily via getters
anatolzak May 1, 2026
5f2231e
Respect explicit versioning: false on durable functions
anatolzak May 1, 2026
1e105c1
Inline args.url in normalizeUrl
anatolzak May 1, 2026
6cf7667
feat(function): allow transforming the LatestAlias resource
anatolzak May 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
132 changes: 88 additions & 44 deletions platform/src/components/aws/function.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1309,6 +1309,12 @@ export interface FunctionArgs {
/**
* Enable versioning for the function.
*
* :::caution
* If you're wiring this function to an event source by passing its ARN,
* use `fn.targetArn` rather than `fn.arn`. Using `fn.arn` invokes
* `$LATEST` and bypasses the alias that routes to the published version.
* :::
*
* :::note
* Durable functions enable this by default.
* :::
Expand Down Expand Up @@ -1476,6 +1482,12 @@ export interface FunctionArgs {
* This property is meant to be used internally by [Workflow](/docs/component/aws/workflow).
* Prefer the component if you want to use the [SDK](/docs/component/aws/workflow#sdk) or if you are not very familiar with durable functions limitations.
* :::
*
* :::caution
* If you're wiring this function to an event source by passing its ARN,
* use `fn.targetArn` rather than `fn.arn`. Using `fn.arn` invokes
* `$LATEST` and bypasses the alias that routes to the published version.
* :::
*/
durable?:
| boolean
Expand All @@ -1500,6 +1512,11 @@ export interface FunctionArgs {
* Transform the Lambda Function resource.
*/
function?: Transform<lambda.FunctionArgs>;
/**
* Transform the Lambda Alias resource. This is only created when versioning
* is enabled (via `versioning: true` or `durable: true`).
*/
alias?: Transform<lambda.AliasArgs>;
/**
* Transform the IAM Role resource.
*/
Expand Down Expand Up @@ -1712,6 +1729,8 @@ export class Function extends Component implements Link.Linkable {
private logGroup: Output<cloudwatch.LogGroup | undefined>;
private urlEndpoint: Output<string | undefined>;
private eventInvokeConfig?: lambda.FunctionEventInvokeConfig;
private alias: Output<lambda.Alias | undefined>;
private isVersioningEnabled: Output<boolean>;

private static readonly encryptionKey = lazy(
() =>
Expand Down Expand Up @@ -1781,7 +1800,8 @@ export class Function extends Component implements Link.Linkable {
const logGroup = createLogGroup();
const zipAsset = createZipAsset();
const fn = createFunction();
const urlEndpoint = createUrl();
const isVersioningEnabled = fn.publish.apply((publish) => Boolean(publish));
Copy link
Copy Markdown
Collaborator

@vimtor vimtor Apr 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you can also define versioning with versioning: true

Copy link
Copy Markdown
Contributor Author

@anatolzak anatolzak May 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@vimtor fn.publish is the resolved truth on the underlying aws.lambda.Function. Upstream at function.ts:2659, it's set to args.versioning || Boolean(args.durable), so checking fn.publish covers both paths in one expression

const alias = createLatestAlias();
createProvisioned();
const eventInvokeConfig = createEventInvokeConfig();

Expand All @@ -1790,8 +1810,14 @@ export class Function extends Component implements Link.Linkable {
this.function = fn;
this.role = role;
this.logGroup = logGroup;
this.urlEndpoint = urlEndpoint;
this.eventInvokeConfig = eventInvokeConfig;
this.alias = alias;
this.isVersioningEnabled = isVersioningEnabled;

const urlEndpoint = this.qualifier.apply((qualifier) =>
createUrl(qualifier),
);
this.urlEndpoint = urlEndpoint;

const buildInput = output({
functionID: name,
Expand Down Expand Up @@ -2700,7 +2726,25 @@ export class Function extends Component implements Link.Linkable {
);
}

function createUrl() {
function createLatestAlias() {
return isVersioningEnabled.apply((isVersioningEnabled) => {
if (!isVersioningEnabled) return;

return new lambda.Alias(
...transform(
args.transform?.alias,
`${name}LatestAlias`,
{
functionName: fn.name,
functionVersion: fn.version,
},
{ parent },
),
);
});
}

function createUrl(qualifier: string | undefined) {
return url.apply((url) => {
if (url === undefined) return output(undefined);

Expand All @@ -2712,23 +2756,10 @@ export class Function extends Component implements Link.Linkable {
([oac, authorization]) => oac || authorization === "iam",
);

/**
* Lambda Function URLs only accept alias names in the explicit `qualifier`
* field. Durable functions with URLs therefore need an alias target here,
* even when the underlying function is still on `$LATEST`.
* See https://github.com/hashicorp/terraform-provider-aws/issues/31459
*/
const qualifier = durable
? new lambda.Alias(`${name}Durable`, {
functionName: fn.arn,
functionVersion: fn.version,
}).name
: undefined;

const fnUrl = new lambda.FunctionUrl(
`${name}Url`,
{
functionName: durable ? fn.arn : fn.name,
functionName: fn.name,
qualifier,
authorizationType: isIam.apply((isIam) =>
isIam ? "AWS_IAM" : "NONE",
Expand All @@ -2738,7 +2769,7 @@ export class Function extends Component implements Link.Linkable {
),
cors: url.cors,
},
{ parent },
{ parent, deleteBeforeReplace: false },
);

if (!url.route) {
Expand All @@ -2750,6 +2781,7 @@ export class Function extends Component implements Link.Linkable {
{
action: "lambda:InvokeFunctionUrl",
function: fn.name,
qualifier,
principal: "*",
functionUrlAuthType: "NONE",
},
Expand All @@ -2760,6 +2792,7 @@ export class Function extends Component implements Link.Linkable {
{
action: "lambda:InvokeFunction",
function: fn.name,
qualifier,
principal: "*",
invokedViaFunctionUrl: true,
},
Expand All @@ -2778,6 +2811,7 @@ export class Function extends Component implements Link.Linkable {
{
action: "lambda:InvokeFunctionUrl",
function: fn.name,
qualifier,
principal: "cloudfront.amazonaws.com",
sourceArn: distributionArn,
},
Expand All @@ -2788,6 +2822,7 @@ export class Function extends Component implements Link.Linkable {
{
action: "lambda:InvokeFunction",
function: fn.name,
qualifier,
principal: "cloudfront.amazonaws.com",
sourceArn: distributionArn,
invokedViaFunctionUrl: true,
Expand All @@ -2800,6 +2835,7 @@ export class Function extends Component implements Link.Linkable {
{
action: "lambda:InvokeFunctionUrl",
function: fn.name,
qualifier,
principal: "*",
functionUrlAuthType: "NONE",
},
Expand All @@ -2810,6 +2846,7 @@ export class Function extends Component implements Link.Linkable {
{
action: "lambda:InvokeFunction",
function: fn.name,
qualifier,
principal: "*",
invokedViaFunctionUrl: true,
},
Expand Down Expand Up @@ -2952,6 +2989,10 @@ export class Function extends Component implements Link.Linkable {
* The Function Event Invoke Config resource if retries are configured.
*/
eventInvokeConfig: this.eventInvokeConfig,
/**
* The Lambda Alias. Available when `versioning` or `durable` is enabled.
*/
alias: this.alias,
};
}

Expand Down Expand Up @@ -2983,18 +3024,21 @@ export class Function extends Component implements Link.Linkable {
return this.function.arn;
}

/** @internal */
private get useQualifiedTarget() {
return this.function.publish.apply(
(publish) => (publish ?? false) || this.durable,
);
}

/** @internal */
/**
* The ARN to use when wiring this function to an event source.
*
* When versioning is enabled, this points to the Lambda alias that routes
* to the currently published version. Otherwise it falls back to the
* function ARN.
*
* Prefer this over `arn` when passing the function to an event source, so
* invocations go through the alias instead of `$LATEST`.
*/
public get targetArn() {
return this.useQualifiedTarget.apply((useQualifiedTarget) =>
useQualifiedTarget ? this.function.qualifiedArn : this.arn,
);
return this.alias.apply((alias) => {
if (alias) return alias.arn;
return this.function.arn;
});
}

/** @internal */
Expand All @@ -3006,23 +3050,21 @@ export class Function extends Component implements Link.Linkable {

/** @internal */
public get targetInvokeArn() {
return this.useQualifiedTarget.apply((useQualifiedTarget) =>
useQualifiedTarget
? this.function.qualifiedInvokeArn
: this.function.invokeArn,
return this.alias.apply((alias) =>
alias ? alias.invokeArn : this.function.invokeArn,
);
}

/** @internal */
public get targetResponseStreamingInvokeArn() {
return this.useQualifiedTarget.apply((useQualifiedTarget) =>
useQualifiedTarget
return this.alias.apply((alias) =>
alias
? all([
this.arn,
this.function.qualifiedArn,
alias.arn,
this.function.responseStreamingInvokeArn,
]).apply(([arn, qualifiedArn, responseStreamingInvokeArn]) =>
responseStreamingInvokeArn.replace(arn, qualifiedArn),
]).apply(([arn, aliasArn, responseStreamingInvokeArn]) =>
responseStreamingInvokeArn.replace(arn, aliasArn),
)
: this.function.responseStreamingInvokeArn,
);
Expand Down Expand Up @@ -3110,11 +3152,7 @@ export class Function extends Component implements Link.Linkable {
properties: {
name: this.name,
url: this.urlEndpoint,
...(this.durable
? {
qualifier: this.qualifier,
}
: {}),
qualifier: this.qualifier,
},
include: [
permission({
Expand All @@ -3132,7 +3170,13 @@ export class Function extends Component implements Link.Linkable {
]
: []),
],
resources: [this.durable ? interpolate`${this.arn}:*` : this.arn],
resources: this.isVersioningEnabled.apply((isVersioningEnabled) =>
this.durable
? [interpolate`${this.arn}:*`]
: isVersioningEnabled
? [this.arn, interpolate`${this.arn}:*`]
: [this.arn],
),
}),
],
};
Expand Down
7 changes: 6 additions & 1 deletion platform/src/components/aws/workflow.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -272,7 +272,12 @@ export interface WorkflowArgs
* ID generation inside durable operations like `ctx.step()`.
*
* :::caution
* Workflow handlers have versioning enabled. Deploying an update won't update existing running workflows.
Copy link
Copy Markdown
Collaborator

@vimtor vimtor Apr 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we should keep the versioned behaviour. i don't understand why we changed this

Copy link
Copy Markdown
Contributor Author

@anatolzak anatolzak May 1, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@vimtor The versioned behavior is unchanged. The main reason durable workflows version the handler is so that an in-flight execution resumes on the same code it started on. That's preserved: the lanbda API captures the resolved version at execution start and pins all resumes/retries to that captured version, regardless of whether the alias is later moved.

What the alias buys us, beyond what a pinned numeric version gives, is decoupling the handler identity from the deployed version. If you ship a bad release and need to roll back, you just point the alias at the previous version, and no consumers have to be updated. Any newly-started executions immediately run against the rolled-back version. With a pinned qualifiedArn, every consumer (URL, event sources, API GW, SDK qualifier, etc.) would have to be re-wired to roll back.

It also opens the door to weighted aliases: you can split traffic across two versions of a workflow handler for A/B tests or canary rollouts without touching any client. None of that is possible if consumers point at a specific numeric version.

The doc rewrite just makes the mechanism explicit and adds the $LATEST escape hatch. No behavior regression.

* The workflow SDK invokes the handler through an alias. Each execution is pinned
* to the version the alias points to when it starts, and stays pinned across resumes
* and retries — so deploying an update won't affect already-running workflows.
*
* To resume on the latest code, invoke the function directly via the Lambda SDK
* with the `$LATEST` qualifier. Not recommended for production.
* :::
*
* Before using workflows in production, review the
Expand Down
1 change: 1 addition & 0 deletions platform/src/components/component.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -147,6 +147,7 @@ export class Component extends ComponentResource {
"aws:cognito/identityPoolRoleAttachment:IdentityPoolRoleAttachment",
"aws:cognito/identityProvider:IdentityProvider",
"aws:cognito/userPoolClient:UserPoolClient",
"aws:lambda/alias:Alias",
"aws:lambda/eventSourceMapping:EventSourceMapping",
"aws:lambda/functionEventInvokeConfig:FunctionEventInvokeConfig",
"aws:lambda/functionUrl:FunctionUrl",
Expand Down
Loading