apx-aws-lambda

AWS Lambda for Action Platform: the aws/lambda deploy target (SAM), its overlay, read-only tools and commands, and an IAM-only connect stack for your AWS account so that no AWS key ever lives on the platform, on a machine or in a repository — and nothing of ours runs in the account. apx- is the prefix every Action Platform extension carries.

action-platform plugin install aws-lambda
action-platform cloud set aws/lambda        # overlay files come from this plugin
action-platform deploy --dry-run            # preflight: credentials, sam validate
action-platform deploy                      # sam build + sam deploy --config-env <stage>
action-platform diagnose

Contents

• What the plugin does
• Credentials without keys
  • A connected account (recommended)
  • Updating the connect stack
  • A role of your own (OIDC)
  • The AWS CLI's own credentials
• Where the deploy runs
• Tools and commands
• Requirements
• Development

What the plugin does

[deploy] in platform.toml:

[deploy]
target = "aws/lambda"
region = "us-east-1"          # optional; samconfig.toml / AWS_REGION otherwise
health = "/health"            # optional; checked through the HTTP API after the deploy, "" skips it

Deploying itself goes through the core's deploy / rollback / diagnose, which drive the target.

Credentials without keys

The target looks for credentials in this order:

A connected account (recommended)

One CloudFormation stack, IAM only — no function, no table, nothing to upgrade. AWS itself trusts the platform's OIDC tokens; the token's session tag keeps each deploy inside its app.

1. Create the stack — once per AWS account, with an IAM user or role that may create IAM resources (not the root account). On the platform: Plugins → AWS Lambda → Configure → Connect AWS. The button copies a command and opens AWS CloudShell, behind the AWS sign-in; paste the command and press Enter. It downloads this release's connect/template.yaml from GitHub, deploys it as the stack action-platform-connect in us-east-1 with the platform's url and the organization's slug, and prints the account ID.

Without the button, the same stack from a machine logged in to the account:

action-platform aws-lambda connect https://platform.example.com acme      # --region, --stack-name, --oidc-provider-arn

or in the console: CloudFormation → Create stack → Upload a template file → apx_aws_lambda/connect/template.yaml, parameters IssuerUrl (the platform's public url) and Organization (its slug), acknowledge IAM.

2. Tell the platform — Plugins → AWS Lambda → Configure → AWS account ID = the 12 digits the command printed (the stack's DeployRoleArn output works too). Every app of the organization whose platform.toml says target = "aws/lambda" deploys from then on; nothing to register per app.

What the stack creates:

How a deploy runs: the platform signs a token for the app with the claim https://aws.amazon.com/tags → principal_tags.action-platform:prefix = ap-<org>-<project>-<app>; the target assumes the deploy role with it, names the stack ap-<org>-<project>-<app>-<scope>, passes PermissionsBoundaryArn and RolePath=/action-platform/<prefix>/ to the overlay's template and tags the stack with the prefix, so the execution role SAM creates carries the boundary and the tag and lives under the app's path. The path, not the name, tells an app's roles apart: CloudFormation cuts a generated role name to 64 characters, which can drop the prefix from it. sam delete removes that role with the stack. Who may deploy which app is the platform's decision — it only signs a token for an app the job or the caller is for.

Readiness simulates the deploy role with the session tag, the boundary and iam:PassedToService as context entries, and flags an overlay without the PermissionsBoundaryArn or RolePath parameter. An app whose overlay predates them applies it again: Configuration → Deploy target, or action-platform cloud set aws/lambda. The stack's policy is the one place to widen or narrow what deploys may do.

Updating the connect stack

The command pins the template to the plugin's release. After the platform moves to a plugin whose connect template changed, run Connect AWS again (or action-platform aws-lambda connect …): CloudFormation updates action-platform-connect in place, and the account ID stays the same.

A role of your own (OIDC)

Instead of the connect stack, register the platform as an identity provider once per account and write the trust policy yourself:

aws iam create-open-id-connect-provider --url https://platform.example.com --client-id-list sts.amazonaws.com

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "Federated": "arn:aws:iam::123456789012:oidc-provider/platform.example.com" },
    "Action": "sts:AssumeRoleWithWebIdentity",
    "Condition": {
      "StringEquals": { "platform.example.com:aud": "sts.amazonaws.com" },
      "StringLike": { "platform.example.com:sub": "org:acme:project:shop:app:orders" }
    }
  }]
}

requirements/policy.json from the overlay is a starting permission policy. Then:

[deploy]
target = "aws/lambda"
role_arn = "arn:aws:iam::123456789012:role/shop-deploy"

sub is org:<org>:project:<project>:app:<app> for a deploy the platform runs; org:<org> plus an actor claim for action-platform deploy from a logged-in machine (StringLike with org:acme:* covers both).

The AWS CLI's own credentials

With neither role_arn nor a connected account, aws and sam use what the machine has: aws sso login, a profile, an instance role. Still no key in a file when you use SSO — but nothing ties the identity to one app.

Where the deploy runs

Independent of how credentials are obtained:

Tools and commands

Requirements

• aws and sam — on PATH when present; otherwise the awscli and aws-sam-cli packages the plugin depends on run as python -m, which is how the hosted platform deploys without the CLIs in its image.
• AWS_REGION or region under [deploy].
• Network: *.amazonaws.com.
• Connecting the account: credentials for it that may create IAM resources, once — AWS CloudShell through the Connect AWS button, the console, or aws for action-platform aws-lambda connect.
• action-platform 0.32.0 or newer: the Connect AWS button is an option action of the core.

Development

pip install -e ".[dev]"
pytest

The tests fake aws and sam; nothing reaches AWS.