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)
  • 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

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 your own AWS credentials (not the root account). Either 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; or from a machine:

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

2. Tell the platform — Plugins → AWS Lambda → Configure → Deploy role ARN = the stack's DeployRoleArn output. 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>-dev|prod, passes PermissionsBoundaryArn to the overlay's template and tags the stack with the prefix, so the execution role SAM creates carries both the boundary and the tag. 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 and the boundary as context entries, and flags an overlay without the PermissionsBoundaryArn parameter (apply the overlay again). The stack's policy is the one place to widen or narrow what deploys may do: edit and update the stack.

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, once — the console, or aws for action-platform aws-lambda connect.

Development

pip install -e ".[dev]"
pytest

The tests fake aws and sam; nothing reaches AWS.