Image.ref output incompatible with AWS Lambda imageUri - includes both tag and digest

[tnorlund]

Describe what happened

When using docker_build.Image to build and push images to ECR for AWS Lambda functions, the ref output provides a format that AWS Lambda doesn't accept. The ref output returns repo:tag@sha256:digest, but AWS Lambda's imageUri parameter only accepts either:

• repo:tag (tag only)
• repo@sha256:digest (digest only)

Using the ref output directly causes Lambda to throw:
InvalidParameterValueException:

Source image <ACCT_ID>.dkr.ecr.us-east-1.amazonaws.com/<REPO_NAME>:latest@sha256:fd33b63053cbeabf0dc833cb4c19098f62625c382e7fd262063a54d59d5fbf51 is not valid. Provide a valid source image.

Sample program

import pulumi
import pulumi_aws as aws
import pulumi_docker_build as docker_build
from pulumi_aws.lambda_ import Function

# Create ECR repository
ecr_repo = aws.ecr.Repository("my-repo")

# Get ECR auth token
ecr_auth_token = aws.ecr.get_authorization_token_output()

# Build and push image
docker_image = docker_build.Image(
      "my-image",
      context={"location": "./app"},
      dockerfile={"location": "./app/Dockerfile"},
      platforms=["linux/arm64"],
      push=True,
      registries=[{
          "address": ecr_repo.repository_url.apply(lambda url: url.split("/")[0]),
          "password": ecr_auth_token.password,
          "username": ecr_auth_token.user_name,
      }],
      tags=[ecr_repo.repository_url.apply(lambda url: f"{url}:latest")],
)

# This FAILS with InvalidParameterValueException
lambda_func = Function(
      "my-lambda",
      package_type="Image",
      image_uri=docker_image.ref,  # Returns repo:tag@digest format
      role=lambda_role.arn,
)

Log output

No response

Affected Resource(s)

No response

Output of pulumi about

CLI          v3.148.0
aws          v7.1.0
docker-build v0.0.7
python       3.12

Additional context

I'm new to this package, and I'd like to suggest either:

1. Add a new output like digest_uri that returns the repo@digest format suitable for Lambda
2. Document this limitation in the AWS ECR example
3. Add a helper method/property that formats the URI for Lambda compatibility

This issue affects anyone using docker_build.Image with AWS Lambda functions. The documentation at https://www.pulumi.com/registry/packages/docker-build/api-docs/image/#push-to-aws-ecr-with-caching shows using ref for exports, but doesn't mention this Lambda incompatibility.

The ref output format (repo:tag@digest) is valid for many Docker operations, but AWS Lambda specifically requires either the tag format or the digest format, not both combined.

Contributing

Vote on this issue by adding a 👍 reaction.
To contribute a fix for this issue, leave a comment (and link to your pull request, if you've opened one already).

[tnorlund]

For anyone encountering this issue, here's the workaround we're currently using:

# Instead of using .ref directly, manually construct the digest-only format
lambda_func = Function(
    "my-lambda",
    package_type="Image",
    image_uri=pulumi.Output.all(
        ecr_repo.repository_url,
        docker_image.digest
    ).apply(
        lambda args: f"{args[0].split(':')[0]}@{args[1]}"
    ),
    role=lambda_role.arn,
)

This constructs a URI in the format repo@sha256:digest which AWS Lambda accepts.

[mjeffryes]

Thanks for pointing this out @tnorlund. As you point out (and I think it's mentioned in the docs too), the ref output, while convenient in some cases, is not really universally applicable. Especially because the Image resource allows multiple tags and multiple destination repos for the push. (The

So building the URI you need from the digest output as you do in the workaround is the best way to go for now. But I do hear you that it's kind of clumsy that you need 6 lines to construct the image_uri for the lambda! (You can almost get it down to one line with pulumi.Output.format("{0}@{1}", ecr_repo.repository_url, docker_image.digest), except for needing to split ecr_repo.repository_url...)

A challenge with introducing a digest_uri output is that it would have a similar limitation to the ref output when there are multiple push destinations. Another thing we could probably do though would be to include some helper functions for building URIs eg. make_image_uri(ecr_repo.repository_url, docker_image.digest) or possibly even doker_image.make_image_uri(ecr_repo.repository_url)? That would probably make the resulting program more readable.

[tnorlund]

@mjeffryes Thanks for the response! I wanted to share my experience and ask for advice on the best approach.

The workaround I shared is the only way I've been able to get Pulumi to force Lambda to update with the newest image. It feels fragile...

1. Is there a recommended pattern for ensuring Lambda functions properly detect image changes during updates?
2. Is there something I'm missing about how to properly trigger Lambda updates when using container images?

For context, I'm using multiple Lambda functions that share an image, and ensuring they all update correctly when the image changes has been challenging. Looking for best practices here.

[mjeffryes]

@tnorlund There's nothing particularly fragile about the way you've constructed the image_uri from the digest and repository_url. You're using output.all and output.apply correctly so that pulumi can track the dependency between the resources. You can share the computed uri across all the lambdas or wrap up the logic in a helper function if that feels cleaner. eg:

def construct_image_uri(repo_url, digest):
    return pulumi.Output.all(repo_url, digest).apply(
        lambda args: f"{args[0].split(':')[0]}@{args[1]}"
    )

ecr_repo = aws.ecr.Repository("my-repo")

# Get ECR auth token
ecr_auth_token = aws.ecr.get_authorization_token_output()

# Build and push image
docker_image = docker_build.Image(...)

image_uri=construct_image_uri(ecr_repo.repository_url, docker_image.digest)

# Make as many lambdas as you like pointing to this uri 
lambda_func1 = Function(
      "my-lambda-1",
      package_type="Image",
      image_uri=image_uri, 
      role=lambda_role.arn,
)

lambda_func2 = Function(
      "my-lambda-2",
      package_type="Image",
      image_uri=image_uri, 
      role=lambda_role.arn,
)

...

[mjeffryes]

FWIW that construct_image_uri function could also be written as:

def construct_image_uri(repo_url, digest):
    clean_repo_url = repo_url.apply(lambda url: url.split(':')[0])
    return pulumi.Output.format("{0}@{1}", clean_repo_url, digest)

if that feels any more clear.