publish

Lambda layer publication implementation - Step 4 of the layer creation workflow.

This module handles the publication phase of AWS Lambda layer deployment, taking the uploaded layer zip file from S3 and creating versioned Lambda layer resources. It represents the fourth and final step in the complete layer workflow:

1. Build: Install dependencies using pip/Poetry/UV builders

2. Package: Structure and compress dependencies into zip file

3. Upload: Deploy zip file to S3 storage

4. Publish: Create versioned Lambda layer from S3 artifact (this module)

Public API Functions:

• publish_layer_version(): Intelligent layer publishing with change detection

Key Features:

• Change Detection: Compares dependency manifests to avoid unnecessary publications

• Version Management: Automatically increments layer versions

• Manifest Backup: Stores dependency manifests for reproducibility

• S3 Integration: Uses existing S3 artifacts for layer creation

Publication Process:

The module implements smart publishing that only creates new layer versions when dependencies have actually changed, determined by comparing local dependency manifests against stored versions from previous publications.

class aws_lambda_artifact_builder.layer.publish.LambdaLayerVersionPublisher(verbose: bool = True, printer: ~typing.Callable[[str], None] = <built-in function print>, path_pyproject_toml: ~pathlib.Path = REQ, s3dir_lambda: S3Path = REQ, layer_build_tool: ~aws_lambda_artifact_builder.constants.LayerBuildToolEnum = REQ, s3_client: S3Client = REQ, layer_name: str = REQ, lambda_client: LambdaClient = REQ, publish_layer_version_kwargs: dict[str, ~typing.Any] | None = None)

Command class for intelligent Lambda layer version publishing (Internal API).

This class implements the layer publication workflow with dependency change detection, ensuring new layer versions are only created when dependencies have actually changed. It follows the Command Pattern established by other builder classes.

Not for direct use: This is an internal command class. Use the public function publish_layer_version() instead.

Key Responsibilities:

• Change Detection: Compare local manifests with previously published versions

• Layer Publication: Create new Lambda layer versions from S3 artifacts

• Manifest Storage: Backup dependency manifests for future comparisons

• Version Management: Handle layer version incrementation automatically

Publication Logic:

The publisher only creates new layer versions when the dependency manifest has changed since the last publication. This prevents unnecessary version proliferation and ensures layer versions represent meaningful dependency updates.

run() → LayerDeployment

Execute the complete layer publication workflow.

step_1_preflight_check()

Perform read-only validation of build environment and project configuration.

step_2_publish_layer_version() → LayerDeployment

Execute the layer publication workflow, creating a new Lambda layer version

step_1_1_ensure_layer_zip_exists()

Verifies that the layer.zip file was successfully uploaded to S3 during the aws_lambda_artifact_builder.layer.upload phase and is available for Lambda layer creation. This is a prerequisite validation before attempting to publish a new layer version.

is_layer_zip_exists() → bool

Check if the layer zip file exists in S3 temporary storage.

Returns:

True if layer.zip exists in S3, False otherwise

step_1_2_ensure_layer_zip_is_consistent()

Validate that the uploaded layer.zip matches the current local manifest.

is_layer_zip_consistent() → bool

Compares the manifest MD5 hash stored in the S3 layer.zip metadata with the MD5 hash of the current local manifest file. This ensures that the uploaded layer artifact corresponds to the current dependency state before creating a new layer version.

Consistency Issues That Can Occur:

• Manifest Modified: Local manifest file was changed after upload

• Wrong Upload: A different project’s layer.zip was uploaded

• Missing Metadata: Upload process failed to store manifest MD5

• Stale Upload: Old layer.zip from previous dependency state

Why This Check Matters:

Without this validation, you might publish a layer version that doesn’t match your current dependencies, leading to runtime errors or unexpected behavior in Lambda functions that use the layer.

Returns:

True if uploaded layer.zip matches current manifest, False otherwise

step_1_3_ensure_dependencies_have_changed()

Check if the local dependency manifest has changed since the last publication This is the core intelligence that prevents unnecessary layer version creation

has_dependency_manifest_changed() → bool

Detect if the local dependency manifest has changed from the last published layer.

This method compares the current local dependency manifest (source of truth) against the manifest stored with the latest published layer version. If they are different, it indicates that dependencies have been updated and a new layer version should be published.

Manifest Comparison Process:

1. Retrieve Latest Version: Get the most recent published layer version

2. Locate Stored Manifest: Find the manifest file stored with that version

3. Content Comparison: Compare local manifest content with stored version

4. Change Detection: Return True if contents differ (change detected)

Deterministic Requirement:

The comparison assumes that dependency manifests are deterministic and reproducible. This means the manifest should contain exact versions and hashes, not loose version constraints.

Good (Deterministic):

atomicwrites==1.4.1 ; python_version >= "3.9.dev0" and python_version < "3.10.dev0"             --hash=sha256:81b2c9071a49367a7f770170e5eec8cb66567cfbbc8c73d20ce5ca4a8d71cf11

Bad (Non-deterministic):

atomicwrites  # Version not pinned

Return Logic:

• True: Dependencies have changed, new layer version needed

• False: Dependencies unchanged, can skip layer publication

• True: No previous layer exists (first publication)

• True: Previous manifest file not found (missing backup)

Returns:

True if local manifest differs from latest published version, False if they are identical (no changes detected)

step_2_1_run_publish_layer_version_api() → tuple[int, str]

Publish a new Lambda layer version using the zip file stored in S3.

This method creates a new versioned Lambda layer by referencing the layer zip file that was previously uploaded to S3 during the upload phase. AWS Lambda automatically assigns the next sequential version number.

Layer Creation Process:

1. S3 Reference: Points Lambda service to the uploaded zip file in S3

2. Version Creation: Lambda automatically increments version number

3. ARN Generation: Returns the full ARN of the newly created layer version

Parameters:

publish_layer_version_kwargs – Optional additional arguments to pass to the Lambda publish_layer_version API call (e.g., Description, CompatibleRuntimes)

Returns:

Tuple of (layer_version_number, layer_version_arn)

step_2_2_upload_dependency_manifest(version: int) → S3Path

Upload the dependency manifest file to S3 for the specified layer version.

This method stores the local dependency manifest (source of truth) alongside the published layer version for future change detection and reproducibility. The stored manifest enables the system to determine if dependencies have changed in subsequent publication attempts.

Storage Strategy:

• Version-Specific: Each layer version gets its own manifest backup

• Content Integrity: Uses write_bytes() to ensure proper eTag generation

• Plain Text: Stored as text/plain for easy inspection and comparison

Important

Uses write_bytes() instead of upload_file() to ensure that the eTag is the MD5 hash of the file content, which is important for content integrity verification.

Parameters:

version – The layer version number to associate the manifest with

Returns:

S3Path where the manifest was stored

class aws_lambda_artifact_builder.layer.publish.LayerDeployment(layer_name: str = REQ, layer_version: int = REQ, layer_version_arn: str = REQ, s3path_manifest: S3Path = REQ)

Data class representing a completed layer deployment (Public API).

This immutable data class encapsulates all the key information about a successfully published Lambda layer version, providing a complete record of the deployment for downstream operations.

Usage:

The LayerDeployment is returned by publish_layer_version() when a new layer version is successfully created. It contains all the identifiers and references needed to work with the published layer.

Attributes:

• layer_name: The name of the Lambda layer

• layer_version: The version number assigned by AWS Lambda

• layer_version_arn: The full ARN of the published layer version

• s3path_manifest: S3 location of the stored dependency manifest