feat(core): allow mounting existing or volume copy volumes

[cgatt]

Issue # (if applicable)

Closes #32805
Closes #20601

Reason for this change

This change is to better support image bundling in atypical (e.g. CI, DinD) environments by allowing volumes to be mounted using the more portable "Volume Copy" method, or to mount an existing volume. This supports use cases such as caching dependencies in CI environments to reduce asset bundling times.

Description of changes

The primary change made was the addition of two new DockerVolume varients (VolumeCopyDockerVolume and ExistingDockerVolume), facilitated by the new DockerVolumeHelper private class. This replaces the old asset-staging private classes AssetBundlingBindMount and AssetBundlingVolumeCopy, reproducing all the behaviours in a more flexible manner.
The decision to move these utility functions to private/bundling.ts was to better encapsulate the docker related behaviours and abstract them away from the asset management.

This currently uses a discriminated union type to clearly show which properties are required for each volume type. This passes linting, but if it's an issue it can be implemented just as an extension to the DockerVolume interface. However, I'm unsure how to best provide a clear developer experience with this approach.

How It Works

The interfaces for DockerRunOptions.volumes and the related BundlingOptions.volumes have been changed to accept VolumeCopyDockerVolume and ExistingDockerVolume as well as the existing DockerVolume type. The BundlingDockerImage.run() function has been modified slightly to instantiate a DockerVolumeHelper, which accepts the docker run options and uses them to prepare the volumes passed in, creating the volume command strings that run then uses.

If any if the passed volumes are VOLUME_COPY volumes, a copyContainer is spun up with each VOLUME_COPY volume atttached anonymously. The input copy is then performed using the same approach from AssetBundlingVolumeCopy. As these volumes are mounted to the primary container via --volumes-from, them being anonymous doesnt matter and makes creation and deletion of the helper more atomic, reducing the possibility of orphaned volumes or containers. Error handling has been added in multiple places to further prevent this happening in the case of a build failure.

BundlingDockerImage.run() makes use of the volume commands from DockerVolumeHelper to complete its image run, then runs DockerVolumeHelper.cleanup() to copy any outputs from the volume copy volumes, and delete the container (using the -v option to remove attach anonymous volumes).

Describe any new or updated permissions being added

N/A - All changes are at bundling time only

Description of how you validated changes

Unit tests were added to cover the new expected volume behaviours, and existing tests updated to match any changes to argument order. Tests were made to cover the new helper class and new error handling cleanup behaviour. No integration tests were made or modified as this is a local/bundling change,

Checklist

• My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

---

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

[aws-cdk-automation]

The pull request linter fails with the following errors:

❌ Features must contain a change to a README file.
❌ Features must contain a change to an integration test file and the resulting snapshot.

If you believe this pull request should receive an exemption, please comment and provide a justification. A comment requesting an exemption should contain the text Exemption Request. Additionally, if clarification is needed, add Clarification Request to a comment.

✅ A exemption request has been requested. Please wait for a maintainer's review.

[cgatt]

Exemption Request (Integration Test): Unsure what sort of integration test would be beneficial here, as it's a synth time change.

Clarification Request (Readme): Happy to add a writeup, but the current DockerImage volume and mounting behaviour has no docs, so I wasnt sure where it would be appropriate to put it.

[aws-cdk-automation]

AWS CodeBuild CI Report

• CodeBuild project: AutoBuildv2Project1C6BFA3F-wQm2hXv2jqQv
• Commit ID: 06dda4d
• Result: SUCCEEDED
• Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

[QuantumNeuralCoder]

Hi
I am beginning to review this now. Need help with some answers from you. The changes around private/asset-staging and bundling are major refactors and breaking. is there an alternative way this can be implemented without breaking backward compatibility.

Please also add a README. Let me know if any questions. The descriptions in this issue are a good explanation.

[QuantumNeuralCoder]

Please add a readme. Please help ans the questions posed above.

[cgatt]

Hi I am beginning to review this now. Need help with some answers from you. The changes around private/asset-staging and bundling are major refactors and breaking. is there an alternative way this can be implemented without breaking backward compatibility.

Please also add a README. Let me know if any questions. The descriptions in this issue are a good explanation.

Thanks for having a look. I'm happy to add docs and tests, just let me know where is appropriate as there are currently no docs around these features for me to modify. If making a new readme is appropriate, I'll do that.

Regarding breaking changes, the private/* classes are not exported or exposed and so are not part of the interface, meaning this isnt a breaking change. This could be implemented without the refactor, but I feel that that would be a less logical final layout - the volume mounting behaviour is coupled with the bundling behaviour, and so should be part of the private bundling utils, not part of asset staging. This refactor cleans up that dependency tree to reduce coupling - asset staging depends on bundling, while bundling no longer has any references to asset staging.

I would also appreciate feedback or comments on the typing. I've used Typescript union types as they passed linting and build checks, and give the best developer experience in Typescript, but can also rewrite this a number of other ways (a single large interface with validation checks to ensure the required sets of properties are passed, or separate arrays for volume copy and existing volume mounts, completely separate from the current "volumes" array. both of these are a worse dev experience, but will work if there are restrictions on union types.

Cheers,
Chris

[QuantumNeuralCoder]

Apologies for the delay in response. I suspect that heterogenous typing will cause issues in languages like Java wrt backward compatibility but havent been able to confirm it. Please expect a response by EOW.

[cgatt]

Apologies for the delay in response. I suspect that heterogenous typing will cause issues in languages like Java wrt backward compatibility but havent been able to confirm it. Please expect a response by EOW.

Any update on this?

[iliapolo]

@cgatt apologies for the delayed response. Please see my comments.

Also - I think we need an integration test for this. Granted, a lot of the bundling code can be covered by unit tests, but I still think we have a integ test gap that I would like us to not exacerbate.

It should be pretty straight forward to add a few more tests similar to:

https://github.com/aws/aws-cdk/blob/main/packages/%40aws-cdk-testing/framework-integ/test/aws-s3-assets/test/integ.assets.bundling.docker-opts.ts

Thanks for all the work you're putting into this!

[iliapolo]

As you already surmised, this is a problem because it provides a poor user experience for static languages, where this translates into an generic Object type.

Before we consider alternatives, I have some questions.

VolumeCopyDockerVolume

Why do we need this new type? Both DockerVolume and VolumeCopyDockerVolume offer the same functionality: expose path X on the host machine as path Y inside the container.

So from a properties standpoint, they both should have the same properties. Looking at the code you described in the linked issue:

const codeAsset = new AssetStaging(this, 'CodeAsset', {
  sourcePath: path.resolve('mule'),
  exclude: ['target/*', 'bin/*', '*.class', '*.jar'],
  bundling: {
    image: DockerImage.fromRegistry('public.ecr.aws/docker/library/alpine'),
    bundlingFileAccess: BundlingFileAccess.VOLUME_COPY,
    volumes: [{
      hostPath: '~/.m2',
      containerPath: '/root/.m2',
    }],
  },
});

It seems like we can just apply the bundlingFileAccess for the additional volume configuration as well. I'm not sure I see a use-case for having each individual volume define its own "exposure" mechanism.

ExistingDockerVolume

This one seems to be addressing a different issue/use-case - i'm not opposed to it, but I would prefer for it to be a separate PR.

As for the implementation, lets drop the union type and instead change DockerVolume to support existing volumes, as proposed by @SamStephens in the issue:

• Change hostPath to be optional.
• Add a volumeName optional property to indicate we want an existing volume.
• Validate mutual exclusivity of hostPath and volumeName.

Its not the best experience because it creates a runtime validation instead of compile time, but is still preferable over union types.

[iliapolo]

Actually I prefer these individual helper classes over the proposed DockerVolumeHelper - even at the expense of some duplication. Since volume commands differ so much between the two options, a common helper class makes it harder to reason through.

[iliapolo]

Then why would we define a VolumeCopy volume if we aren't copying anything?

[iliapolo]

I don't think this capability is really related to what this PR is trying to address. There is also no test for it.

In general I don't think we need this, it poses a slight shift in how we think about bundling. Currently, the bundling mechanism takes N inputs and produces 1 output - thats clear and easy to reason about. Allowing for M outputs makes it more complex and I don't see a reason for it.

If you have a clear use case in mind - please elaborate on it, preferably in a different issue/PR.

[iliapolo]

What happened to this command? How come we don't need docker volume create anymore?

[iliapolo]

@cgatt

Clarification Request (Readme): Happy to add a writeup, but the current DockerImage volume and mounting behaviour has no docs, so I wasnt sure where it would be appropriate to put it.

Yeah there's no good place for it right now...Lets see how this PR ends up and then decide whether to add a blurb somewhere or exempt it.

[github-actions]

This PR has not received a response in a while. If you want to keep this issue open, please leave a comment below and auto-close will be canceled.