aws / aws/aws-cdk

aws_s3_assets: adjustments to support aws_ssm.CfnDocument attachments

Open
#38,326 1 comment 0 reactions 0 assignees View on GitHub
@aws-cdk/aws-s3-assets feature-request p2
Dominant language
TypeScript
Stars
12.9k
Forks
4.6k
Avg merge
1d 19h
Merged PRs (30d)
74

Description

### Describe the feature

### Use case

`aws_cdk.aws_ssm.CfnDocument` instances with attachments. Note that this requires embedding the SHA256 hash of each attachment within document content.

### Suggestions

1. Dedicated L2 construct for SSM documents. An active [project](https://github.com/cdklabs/cdk-ssm-documents/) already exists but currently [does not address](https://github.com/cdklabs/cdk-ssm-documents/issues/91) this use case.

1. `aws_cdk.BundlingOptions`: currently, `image` is a required parameter. Consider making it optional when `local` is passed and only local bundling is desired. In such a case, it should be an error when the callable passed to local returns `false` and `image` was not provided. Alternatively, define a special "null" image. My current workaround: `aws_cdk.DockerImage.from_registry("")`.

1. `aws_cdk.BundlingOptions`: when `output_type` is `aws_cdk.BundlingOutput.ARCHIVED`, consider setting the value of `aws_s3_assets.Asset.asset_hash` to SHA256 of output zip. Helps for cases that require this but remains idempotent.

1. Expose API for creating reproducible archives and computing SHA256 hashes of streams. Maybe in `aws_cdk.FileSystem`? Such functionality can be composed to solve this use case. Other libraries may exist to fill in these gaps but I think asset zips are reproducible already, so nearly all code for this exists in CDK.

### Use Case

Conveniently supporting SSM document attachments sourced from local assets.

### Proposed Solution

Although CDK does not include a L2 construct for handling SSM documents with attachments, I assumed that `aws_cdk.aws_s3_assets` would complement `aws_ssm.CfnDocument` to ease this task.

To be fair, CDK does make this possible but I could not do it without at least [one external library](https://pypi.org/project/repro-zipfile/) and Python's `hashlib`. These libraries are needlessly redundant because they implement functionality that I think already exists in CDK but is not exposed by its API.

### Other Information

Only solution I could devise was a custom local bundling provider. It has to create a single reproducible zip to achieve idempotency (i.e. prevents needless S3 uploads / stack updates). IIUC, `aws_cdk.aws_s3_assets` already creates reproducible zips but that specific function is not exposed, so I relied on a third-party library for it. Also, I need to compute SHA256 of resulting zip file but `aws_cdk.aws_s3_assets.asset_hash` computes a different SHA256 hash even when `aws_cdk.BundlingOptions.output_type` is `aws_cdk.BundlingOutput.ARCHIVED`.

```python
# stdlib
import hashlib
import pathlib

# CDK
from aws_cdk import (
BundlingOptions,
BundlingOutput,
ILocalBundling,
)
import jsii

# External
from repro_zipfile import ReproducibleZipFile

@jsii.implements(ILocalBundling)
class PyBundle:
def __init__(self, path: str, *args, **kwargs):
super().__init__(*args, **kwargs)
self.path = path
self.digest = ""

def try_bundle(self, output_dir: str, bundling_options: BundlingOptions) -> bool:
if bundling_options.output_type != BundlingOutput.ARCHIVED:
raise ValueError("bundling output must be ARCHIVED", bundling_options)
with pathlib.Path(
output_dir, pathlib.Path(self.path).with_suffix(".zip").name
).open("w+b") as f:
with ReproducibleZipFile(f, "w") as zip:
for py in pathlib.Path(self.path).glob("*.py"):
zip.write(py, arcname=py.name)
f.seek(0)
self.digest = hashlib.file_digest(f, hashlib.sha256).hexdigest()
return True
```

NOTE: above code has a correct `try_bundle()` signature. See [issue #38321](https://github.com/aws/aws-cdk/issues/38321).

### Acknowledgements

- [ ] I may be able to implement this feature request
- [x] This feature might incur a breaking change

### AWS CDK Library version (aws-cdk-lib)

aws-cdk@2.1131.0

### AWS CDK CLI version

2.1131.0 (build 1e9a1e1)

### Environment details (OS name and version, etc.)

Ubuntu 24.04.4 LTS, x86_64, Python 3.12.3

Contributor guide

Open the contributing guide

Research direction

Read the aws_s3_assets.Asset, BundlingOptions, BundlingOutput, and ILocalBundling APIs first, then compare ARCHIVED asset hashing with the SSM attachment SHA256 requirement described here. Done requires an agreed API or construct design that supports local SSM attachment assets without the external reproducible-zip workaround.

Written by the indexing model from the issue text.

Assessment

Tech stack
aws, python, typescript
Domain
cloud, infrastructure
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.