aws_s3_assets: adjustments to support aws_ssm.CfnDocument attachments
- 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
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