Skip to content

[DO NOT MERGE] Add the AWS.ToolExtras.LambdaPSRuntime PowerShell module - #2619

Draft
jnunn-aws wants to merge 370 commits into
masterfrom
jnunn-aws/lambdapsruntime
Draft

jnunn-aws wants to merge 370 commits into
masterfrom
jnunn-aws/lambdapsruntime

Conversation

@jnunn-aws

@jnunn-aws jnunn-aws commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Issue #, if available:

Description of changes:

Adds AWS.ToolExtras.LambdaPSRuntime, a PowerShell module that scaffolds, builds, deploys and invokes PowerShell Lambda functions on a custom runtime: a layer, a self-contained .zip, a container image or a customer-managed runtime. It publishes to the PowerShell Gallery. No NuGet package changes.

Read first

  • CHANGELOG.md: its conflict resolution against master, in 2a730efcf, is one of two changes no staging PR reviewed.
  • .github/workflows/execute-release.yml: the other. It adds the module's pipeline to the end of PIPELINE_NAMES.

Behavior

  • PR CI now runs the module's Pester tests and analyzer on amd64 and arm64, with no AWS calls. Release pipelines that load ci.buildspec.yml skip them, so a failing module test can't block an aws-lambda-dotnet release. The module's own pipeline runs them.
  • Execute Release now also starts the module's release pipeline, aws-lambda-dotnet-lambdapsruntime, after the existing three.
  • Outside PowerShell/CustomRuntime/, only CHANGELOG.md, PowerShell/README.md, .github/workflows/execute-release.yml, buildtools/build.proj and buildtools/ci.buildspec.yml change, and the last three change public CI and release. No existing line is removed, except the PIPELINE_NAMES line it extends.

Testing

lambdapsruntime-tests with AWS.Tools 5.0.340: 2640 passed, 0 failed, 5 skipped.

Review evidence

Each of the 367 commits before 2a730efcf, where this branch syncs with master, came through one of 46 merged aws/aws-lambda-dotnet-staging PRs, each with 2 or 3 approvals. The one exception, 0741c9e58, is an earlier sync with master that changes nothing: git show --cc 0741c9e58 prints no diff. This check prints each PR with its approval count, with gh read access to staging:

R=aws/aws-lambda-dotnet-staging
for c in $(git rev-list 742414bc4..2a730efcf^1); do
  gh api repos/$R/commits/$c/pulls --jq '.[]|select(.merged_at)|.number' | grep . || echo "NONE $c" >&2
done | sort -un | while read n; do
  gh pr view $n -R $R --json latestReviews --jq "\"$n \([.latestReviews[]|select(.state==\"APPROVED\")]|length)\""
done

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

jnunn-aws and others added 30 commits November 2, 2026 13:36
…epository, and leaves the login to ecr-login when docker uses it

- docker login runs before New-ECRRepository, so a failed login creates no repository and writes no
  policy. A declined create or -WhatIf still skips the login.
- When the docker config (DOCKER_CONFIG, or .docker in the home folder) gives this registry's
  credHelpers entry, or else credsStore, as ecr-login, docker login is skipped: that helper supplies
  ECR tokens and cannot store a login, so the login always failed.
- The unencrypted-token warning names the file docker reports (the config file when it names none),
  and suggests the OS credential stores as well as the ECR credential helper.
- The help describes the new order, and documents the known limit for two deploys that share one
  repository at the same time (the last policy write wins).
Tests: the failed-login, ecr-login and file-name cases fail before the change; the cases where docker
login still runs pass on both. Coverage only: -WhatIf on an existing repository, and a create error
other than already-exists. Every test runs with an empty DOCKER_CONFIG of its own.
…ove the docker stand-in they add

AfterAll calls Remove-LambdaPSDockerStub, so the stand-in docker and its PATH entry don't outlive the
file.
…n ARN; the condition check's example runs

- Merge-LambdaPSEcrPullPolicy -RuntimeArn takes runtime/<name> with no '/' or whitespace after it, so a
  version ARN (runtime/<name>/version/<v>) fails at binding. Test: a version ARN is refused; the
  trailing-newline test still holds.
- Test-LambdaPSPullConditionMet's example passes a literal condition and runtime ARN.
… warns that the ECR credential helper ignores the given credentials, and reads a relative DOCKER_CONFIG from the PowerShell location

- docker login runs the docker program found on PATH (Get-Command -CommandType Application), so a
  session function or alias named docker never receives the ECR token. No program gives DockerNotFound.
- When the docker config hands the registry to ecr-login and -CredentialParameter is given, a warning
  says the push uses the helper's own AWS credential chain, names AWS_PROFILE and the -ProfileName value,
  and says a -Credential object cannot be passed to it. The help and the unencrypted-token warning say
  the same.
- A relative DOCKER_CONFIG is resolved against the current PowerShell location, where docker starts.
- -AccountId and -RuntimeArn take the same patterns as Merge-LambdaPSEcrPullPolicy, so a bad value fails
  before anything is created.
- One pair of quotes around the file docker names in its unencrypted-token message is dropped.
Tests: the session-function, credential-helper warning and relative-config cases fail before the change;
no warning without credentials passes on both. The docker tests run a stand-in script, reached through
the module's docker lookup.
…such as ecr:BatchGet* as covering the pull, and throws, naming ECR's 10,240-character limit, when the merged policy would exceed it
…sitory

LambdaPSRuntime (6/8): ECR repository and pull policy
Part 7 of 8 of the stacked pull requests for AWS.ToolExtras.LambdaPSRuntime.
…ntime deploy's help

-IncludeModule refuses AWSPowerShell and AWSPowerShell.NetCore, which are too
large to package for Lambda. The error list names AWSPowerShellModuleNotSupported
in the scaffold and modules stage, and the -IncludeModule help says to name the
AWS.Tools.* modules instead.
… the -IncludeModule help

AWSPowerShell is the Windows PowerShell module and doesn't run in PowerShell 7;
AWSPowerShell.NetCore holds every AWS service and is over 600 MB. The help gave
"too large to package" for both.
…he runtime deploy's preflight

An arm64 image installs pwsh from a tarball checked against a pinned SHA256. For
a pwsh version with none, the deploy passed -WhatIf and then replaced -ProjectPath
before the build refused it, with advice to edit a Dockerfile the next run would
replace. The preflight now refuses it first, under -WhatIf too, with
PwshArm64HashNotPinned and deploy advice: -Architecture x86_64, or a -PwshVersion
with a pinned arm64 hash.
…give its cause as something to check

RuntimeVersionNotActive for a FAILED version told the user to rebuild with
Build-LambdaPSRuntimeImage, which the deploy had just used, and didn't say that
the version now exists, so a rerun under the same name is refused. It now says
to check the image's media type, and, as the architecture-mismatch error does,
to publish under a new -RuntimeVersion or remove the version.
…s it, and narrow the help's tag guarantee

The InvalidRepositoryName messages and the -RepositoryName defaulting help give
ECR's own rule: '/'-separated parts of lowercase letters and digits joined by one
'.', one '_', two '_' or any number of '-'. Their tests use names every version
of that rule refuses. The help says the RuntimeVersionExists check covers only
this runtime's versions, so a -RepositoryName shared with another runtime can
still have its tag moved. The Publish seam's help says it looks the runtime up
before creating it; the -Region case example is US-EAST-1; and one help line is
rewrapped.
…d warn when the alias stage alone is declined

The build-and-push stage names the Lambda pull grant it adds to the repository
policy, and the publish stage says when it also creates the runtime. The scaffold
stage says existing contents are deleted only when the directory has any.
Declining only the alias stage now warns that the alias was not moved, with the
command to move it, and the help says RuntimeAlias is the alias requested. The
version timeout names the deploy's alias in its Update-LMCRuntimeAlias command
(Publish-LambdaPSRuntimeVersion takes an optional -RuntimeAlias). New tests cover
declining a middle stage under -Confirm.
… error list

An -IncludeModule name that is a wildcard or a path is refused with
ModuleNameInvalid; the help's scaffold and modules errors now name it.
…credentials in the runtime deploy

A deploy script that set its region with Set-DefaultAWSRegion or its credentials
with Set-AWSCredential in its own scope, rather than the global one, had them
ignored: the module's calls could not see them. The deploy passes its caller's
session state to the region and credential helpers, so they are used as an
AWS.Tools cmdlet in that script would use them. A test also pins the closest
valid repository names: a runtime name such as 'my--rt' or 'my__rt' is a valid
ECR repository name and is used as the default.
… refusal's advice

PwshArm64HashNotPinned listed every pinned arm64 version, so for
-PowerShellVersion 7.4 it also suggested 7.5.11 and 7.6.6, which then fail with
PwshVersionMismatch. It names only versions of the -PowerShellVersion line, and
none when that line has no pinned arm64 hash. The lookup uses
Get-LambdaPSPwshArchiveHash.
…tate can't be read during the wait

A Get-LMCRuntimeVersion failure other than not-found during the wait (access
denied, throttling) surfaced as the service's error alone, after the runtime and
version were created; a rerun was then refused, saying nothing was built. It is
RuntimeVersionWaitFailed, keeping the service error as the inner exception: the
version was created, its state couldn't be read, and the same Get-LMCRuntimeVersion
and Update-LMCRuntimeAlias commands as the timeout. The FAILED message also names
a pull the repository policy doesn't grant as a cause to check.
…ore any AWS call

A -ProjectPath the caller can't list was taken as empty: the deploy raised raw
access-denied errors, called STS and Get-LMCRuntime, and only then failed in the
scaffolder. It lists the folder with -ErrorAction Stop and refuses one it can't
list with TargetNotReadable (the scaffolder's message), before any AWS call. The
help's error list names TargetNotReadable and layer 3's ModuleFolderIncomplete.
…rsion that is still being created, and none for an alias already on it
…go, and match the function deploy's region and profile help
…d read the pinned list from Config/pwsh.psd1
…defaults to 'default' instead of 'production', which reads as an SDLC environment
…t comment say Lambda now rejects an architecture mismatch when the function is created; the module checks first, so the error names the runtime alias
…deploy

LambdaPSRuntime (7/8): Runtime version publishing and alias deploy
…integration tests

Part 8 of 8 of the stacked pull requests for AWS.ToolExtras.LambdaPSRuntime.
…und function, which keeps its live handler and alias and runs the new code

The redeploy changes the handler code and manifest.json (another script and alias), and checks that Get-LMFunctionConfiguration reads back the same handler and RuntimeConfig, that both manifest warnings are written, and that the invoke returns the new output. The runtime deploy is given its region in upper case, and every ARN after it must be lowercase.

Co-Authored-By: Claude <noreply@anthropic.com>
…ERSHELL_RUNTIME_JSON_DEPTH uses 100 and writes a warning to the function log

Co-Authored-By: Claude <noreply@anthropic.com>
jnunn-aws and others added 27 commits November 17, 2026 19:23
LambdaPSRuntime: Deploy: Refuse names that leave CMR resources stuck
… releases name a newer release, a bare 7.6 fails before the region lookup, and the marker's release/line check moves to Build-LambdaPSRuntimePackage
… layers to check reserved paths

Its Dockerfile must match the template, so the base is always provided:al2023. The check downloaded about 42 MB per build and could not fire.
…release in the mocked package repository

PR 290 refuses a -PwshVersion the repository doesn't list.
LambdaPSRuntime: Build and push runtime images without Docker
…version

PR 307's no-Docker additions use -PowerShellVersion 7.4.* or an exact release instead of -PwshVersion.
…n the host's ships a precompiled PowerShellLambdaContext.dll

It is compiled with the same pwsh release for the host's architecture, fetched and SHA256-checked
like the bundled one. If that fetch fails, the runtime compiles it at cold start, as before.
On arm64 this cuts about 1 s from every cold start.
…d of the bundled pwsh runs, such as on macOS or Windows, ships a PowerShellLambdaContext.dll compiled with the running pwsh of the same line

The DLL references only System.Runtime, so any release of the line compiles one every release of
it loads (checked both ways between pwsh 7.6.6 and 7.6.9).
…count when -RuntimeName is the runtime's ARN

A runtime ARN is used as given, so the owner grants only lambda:GetRuntimeAlias and
lambda:AssociateRuntimeAlias; the README shows the grant and the deploy.
LambdaPSRuntime: Multi-tenant functions in deploy, invoke and runtime
…account also needs the runtime alias actions

Lambda checks both policies across accounts (cmr-permissions.html).
…' into lambda-ps-pga-role-on-create

# Conflicts:
#	PowerShell/CustomRuntime/src/AWS.ToolExtras.LambdaPSRuntime/Private/Get-LambdaPSFunctionBinding.ps1
#	PowerShell/CustomRuntime/src/AWS.ToolExtras.LambdaPSRuntime/Private/Publish-LambdaPSFunction.ps1
#	PowerShell/CustomRuntime/src/AWS.ToolExtras.LambdaPSRuntime/Public/New-LambdaPSFunctionDeployment.ps1
LambdaPSRuntime: Deploy: Require -Role only to create the function
…xt type only after a trial compile succeeds, so a host where it can't compile warns instead of failing the build

The Build tests that expect no DLL mock it out, so they also pass on a pwsh 7.4 host.
…pt runtime project keeps the runtime files it was scaffolded with
…t type with the running pwsh of the same line before downloading the bundled release's host build

A DLL compiled by one release of a line loads in the others (checked between pwsh 7.4.6 and 7.4.22,
and 7.6.6 and 7.6.9), so the ~70 MB download is needed only when the running pwsh is of another line.
…, and -PowerShellVersion is marked as accepting wildcards

A result's PowerShellVersion now round-trips into -PowerShellVersion (normj).
LambdaPSRuntime: Docs: Known limitations for kept runtime projects
LambdaPSRuntime: Build: Precompile the context type for no-Docker images of any architecture
…version

PR 313's new precompile tests use -PowerShellVersion '7.4.*' and the result's PowerShellVersion, as this branch requires.
…mePackage bundles the pinned release, and leading zeros are refused

Per ashishdhingra's review: the arm64 and no-Docker preflight names the newest pinned release, and the marker's line check moves into Get-LambdaPSProjectMarker so every caller gets it.
LambdaPSRuntime: Deploy: Bind functions to a runtime in another account
LambdaPSRuntime: Deploy: One -PowerShellVersion parameter for the PowerShell release
Resolves CHANGELOG.md: the LambdaPSRuntime entry stays above the newest release heading.
@jnunn-aws jnunn-aws added the Release Not Needed Add this label if a PR does not need to be released. label Nov 20, 2026
Matches AWSLambdaPSCore's release path. Last in the list, so a failure
to read it can't stop the other pipelines from starting.
…e module's suite

A failing module test must not block an aws-lambda-dotnet release. The
module's own pipeline runs the suite; PR CI still runs it here.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Release Not Needed Add this label if a PR does not need to be released.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant