Skip to content
v2.278.0

AssetStagingProps Struct ​

Initialization properties for AssetStaging.

Example ​

ts
// The code below shows an example of how to instantiate this type.
// The values are placeholders you should change.
import * as cdk from 'aws-cdk-lib';

declare const dockerImage: cdk.DockerImage;
declare const localBundling: cdk.ILocalBundling;
const assetStagingProps: cdk.AssetStagingProps = {
  sourcePath: 'sourcePath',

  // the properties below are optional
  assetHash: 'assetHash',
  assetHashType: cdk.AssetHashType.SOURCE,
  bundling: {
    image: dockerImage,

    // the properties below are optional
    bundlingFileAccess: cdk.BundlingFileAccess.VOLUME_COPY,
    command: ['command'],
    entrypoint: ['entrypoint'],
    environment: {
      environmentKey: 'environment',
    },
    local: localBundling,
    network: 'network',
    outputType: cdk.BundlingOutput.ARCHIVED,
    platform: 'platform',
    securityOpt: 'securityOpt',
    user: 'user',
    volumes: [{
      containerPath: 'containerPath',
      hostPath: 'hostPath',

      // the properties below are optional
      consistency: cdk.DockerVolumeConsistency.CONSISTENT,
    }],
    volumesFrom: ['volumesFrom'],
    workingDirectory: 'workingDirectory',
  },
  exclude: ['exclude'],
  extraHash: 'extraHash',
  follow: cdk.SymlinkFollowMode.NEVER,
  ignoreMode: cdk.IgnoreMode.GLOB,
};
python
# The code below shows an example of how to instantiate this type.
# The values are placeholders you should change.
import aws_cdk as cdk

# docker_image: cdk.DockerImage
# local_bundling: cdk.ILocalBundling

asset_staging_props = cdk.AssetStagingProps(
    source_path="sourcePath",

    # the properties below are optional
    asset_hash="assetHash",
    asset_hash_type=cdk.AssetHashType.SOURCE,
    bundling=cdk.BundlingOptions(
        image=docker_image,

        # the properties below are optional
        bundling_file_access=cdk.BundlingFileAccess.VOLUME_COPY,
        command=["command"],
        entrypoint=["entrypoint"],
        environment={
            "environment_key": "environment"
        },
        local=local_bundling,
        network="network",
        output_type=cdk.BundlingOutput.ARCHIVED,
        platform="platform",
        security_opt="securityOpt",
        user="user",
        volumes=[cdk.DockerVolume(
            container_path="containerPath",
            host_path="hostPath",

            # the properties below are optional
            consistency=cdk.DockerVolumeConsistency.CONSISTENT
        )],
        volumes_from=["volumesFrom"],
        working_directory="workingDirectory"
    ),
    exclude=["exclude"],
    extra_hash="extraHash",
    follow=cdk.SymlinkFollowMode.NEVER,
    ignore_mode=cdk.IgnoreMode.GLOB
)
java
// The code below shows an example of how to instantiate this type.
// The values are placeholders you should change.
import software.amazon.awscdk.*;

DockerImage dockerImage;
ILocalBundling localBundling;

AssetStagingProps assetStagingProps = AssetStagingProps.builder()
        .sourcePath("sourcePath")

        // the properties below are optional
        .assetHash("assetHash")
        .assetHashType(AssetHashType.SOURCE)
        .bundling(BundlingOptions.builder()
                .image(dockerImage)

                // the properties below are optional
                .bundlingFileAccess(BundlingFileAccess.VOLUME_COPY)
                .command(List.of("command"))
                .entrypoint(List.of("entrypoint"))
                .environment(Map.of(
                        "environmentKey", "environment"))
                .local(localBundling)
                .network("network")
                .outputType(BundlingOutput.ARCHIVED)
                .platform("platform")
                .securityOpt("securityOpt")
                .user("user")
                .volumes(List.of(DockerVolume.builder()
                        .containerPath("containerPath")
                        .hostPath("hostPath")

                        // the properties below are optional
                        .consistency(DockerVolumeConsistency.CONSISTENT)
                        .build()))
                .volumesFrom(List.of("volumesFrom"))
                .workingDirectory("workingDirectory")
                .build())
        .exclude(List.of("exclude"))
        .extraHash("extraHash")
        .follow(SymlinkFollowMode.NEVER)
        .ignoreMode(IgnoreMode.GLOB)
        .build();
csharp
// Install: dotnet add package Amazon.CDK.Lib
// The code below shows an example of how to instantiate this type.
// The values are placeholders you should change.
using Amazon.CDK;

DockerImage dockerImage;
ILocalBundling localBundling;

var assetStagingProps = new AssetStagingProps {
    SourcePath = "sourcePath",

    // the properties below are optional
    AssetHash = "assetHash",
    AssetHashType = AssetHashType.SOURCE,
    Bundling = new BundlingOptions {
        Image = dockerImage,

        // the properties below are optional
        BundlingFileAccess = BundlingFileAccess.VOLUME_COPY,
        Command = new [] { "command" },
        Entrypoint = new [] { "entrypoint" },
        Environment = new Dictionary<string, string> {
            { "environmentKey", "environment" }
        },
        Local = localBundling,
        Network = "network",
        OutputType = BundlingOutput.ARCHIVED,
        Platform = "platform",
        SecurityOpt = "securityOpt",
        User = "user",
        Volumes = new [] { new DockerVolume {
            ContainerPath = "containerPath",
            HostPath = "hostPath",

            // the properties below are optional
            Consistency = DockerVolumeConsistency.CONSISTENT
        } },
        VolumesFrom = new [] { "volumesFrom" },
        WorkingDirectory = "workingDirectory"
    },
    Exclude = new [] { "exclude" },
    ExtraHash = "extraHash",
    Follow = SymlinkFollowMode.NEVER,
    IgnoreMode = IgnoreMode.GLOB
};
go
// Install: go get github.com/aws/aws-cdk-go/awscdk/v2
// The code below shows an example of how to instantiate this type.
// The values are placeholders you should change.
import "github.com/aws/aws-cdk-go/awscdk"

var dockerImage DockerImage
var localBundling ILocalBundling

assetStagingProps := &AssetStagingProps{
	SourcePath: jsii.String("sourcePath"),

	// the properties below are optional
	AssetHash: jsii.String("assetHash"),
	AssetHashType: cdk.AssetHashType_SOURCE,
	Bundling: &BundlingOptions{
		Image: dockerImage,

		// the properties below are optional
		BundlingFileAccess: cdk.BundlingFileAccess_VOLUME_COPY,
		Command: []*string{
			jsii.String("command"),
		},
		Entrypoint: []*string{
			jsii.String("entrypoint"),
		},
		Environment: map[string]*string{
			"environmentKey": jsii.String("environment"),
		},
		Local: localBundling,
		Network: jsii.String("network"),
		OutputType: cdk.BundlingOutput_ARCHIVED,
		Platform: jsii.String("platform"),
		SecurityOpt: jsii.String("securityOpt"),
		User: jsii.String("user"),
		Volumes: []DockerVolume{
			&DockerVolume{
				ContainerPath: jsii.String("containerPath"),
				HostPath: jsii.String("hostPath"),

				// the properties below are optional
				Consistency: cdk.DockerVolumeConsistency_CONSISTENT,
			},
		},
		VolumesFrom: []*string{
			jsii.String("volumesFrom"),
		},
		WorkingDirectory: jsii.String("workingDirectory"),
	},
	Exclude: []*string{
		jsii.String("exclude"),
	},
	ExtraHash: jsii.String("extraHash"),
	Follow: cdk.SymlinkFollowMode_NEVER,
	IgnoreMode: cdk.IgnoreMode_GLOB,
}

Properties ​

assetHashoptionalstringasset_hashoptionalstrassetHashoptionalStringAssetHashoptionalstringAssetHashoptional*string #
Specify a custom hash for this asset.

Default: based on assetHashType

notes

If assetHashType is set it must be set to AssetHashType.CUSTOM. For consistency, this custom hash will be SHA256 hashed and encoded as hex. The resulting hash will be the asset hash.

NOTE: the hash is used in order to identify a specific revision of the asset, and used for optimizing and caching deployment activities related to this asset such as packaging, uploading to Amazon S3, etc. If you chose to customize the hash, you will need to make sure it is updated every time the asset changes, or otherwise it is possible that some deployments will not be invalidated.

assetHashTypeoptionalAssetHashTypeasset_hash_typeoptionalAssetHashTypeassetHashTypeoptionalAssetHashTypeAssetHashTypeoptionalAssetHashTypeAssetHashTypeoptionalAssetHashType #
Specifies the type of hash to calculate for this asset.

Default: the default is AssetHashType.SOURCE, but if assetHash is explicitly specified this value defaults to AssetHashType.CUSTOM.

If assetHash is configured, this option must be undefined or AssetHashType.CUSTOM.

bundlingoptionalBundlingOptionsbundlingoptionalBundlingOptionsbundlingoptionalBundlingOptionsBundlingoptionalBundlingOptionsBundlingoptionalBundlingOptions #
Bundle the asset by executing a command in a Docker container or a custom bundling provider.

Default: uploaded as-is to S3 if the asset is a regular file or a .zip file, archived into a .zip file and uploaded to S3 otherwise

The asset path will be mounted at /asset-input. The Docker container is responsible for putting content at /asset-output. The content at /asset-output will be zipped and used as the final asset.

excludeoptionalstring[]excludeoptionaltyping.List[str]excludeoptionalList<String>Excludeoptionalstring[]Excludeoptional*[]*string #
File paths matching the patterns will be excluded. See `ignoreMode` to set the matching behavior.

Default: nothing is excluded

notes

Without bundling ​

When used without the bundling property, the asset is just a regular file copy operation. In that case, this controls the files that will be included in the copy. Files matching the exclude patterns will not be included in the copy.

With bundling ​

When used with the bundling property, the asset is produced by a bundling operation. In that case, the value of exclude is only meaningful if the assetHashType is set to AssetHashType.SOURCE, and ignored for other asset hash types. The exclude patterns will be used to determine which files contribute to the asset, and the bundling command is skipped if the source files have not changed since the last bundling operation.

NOTE: The bundling operation still has access to all files in the source path, regardless of the exclude patterns. It is your responsibility to ensure the exclude pattern accurately matches the files the bundling operation will actually access and base its final output on.

For OUTPUT or CUSTOM asset hash types, the exclude pattern is ignored.

extraHashoptionalstringextra_hashoptionalstrextraHashoptionalStringExtraHashoptionalstringExtraHashoptional*string #
Extra information to encode into the fingerprint (e.g. build instructions and other inputs).

Default: hash is only based on the file fingerprint

followoptionalSymlinkFollowModefollowoptionalSymlinkFollowModefollowoptionalSymlinkFollowModeFollowoptionalSymlinkFollowModeFollowoptionalSymlinkFollowMode = SymlinkFollowMode.EXTERNAL #
A strategy for how to handle symlinks.
notes

Symlinks may be copied, materialized or rejected. Note that if symlinks are copied they should be relative; absolute symlinks will lose their meaning if the cloud assembly is moved to another machine.

Without bundling ​

When used without the bundling property, the asset is just a regular file copy operation. In that case, symlinks are materialized or blocked with respect to the source path root as they are being copied.

With bundling ​

When used with the bundling property, the asset is produced by a bundling operation. In that case, the bundling command is fully in charge of producing a set of files in an output directory, and the AssetStaging construct will never affect symlink materialization.

If the assetHashType is AssetHashType.SOURCE, this flag affects what the source hash is based on, and the recommended value is one of SymlinkFollowMode.EXTERNAL or SymlinkFollowMode.BLOCK_EXTERNAL.

If the SymlinkFollowMode.BLOCK_EXTERNAL mode is used:

  • Symlinks pointing outside the source tree will be blocked, but only if using AssetHashType.SOURCE (not for any of the other asset hash types).
  • Symlinks pointing outside the bundle output will be blocked.
ignoreModeoptionalIgnoreModeignore_modeoptionalIgnoreModeignoreModeoptionalIgnoreModeIgnoreModeoptionalIgnoreModeIgnoreModeoptionalIgnoreMode #
What syntax the `exclude` patterns are written in.

Default: IgnoreMode.GLOB for file assets, IgnoreMode.DOCKER for image assets (requires that the @aws-cdk/aws-ecr-assets:dockerIgnoreSupport feature flag is set, which is recommended)

sourcePathstringsource_pathstrsourcePathStringSourcePathstringSourcePath*string required #
The source file or directory to copy from.