io.cloudshiftdev.awscdk.services.s3.assets.Asset.kt Maven / Gradle / Ivy
The newest version!
@file:Suppress("RedundantVisibilityModifier","RedundantUnitReturnType","RemoveRedundantQualifierName","unused","UnusedImport","ClassName","REDUNDANT_PROJECTION","DEPRECATION")
package io.cloudshiftdev.awscdk.services.s3.assets
import io.cloudshiftdev.awscdk.AssetHashType
import io.cloudshiftdev.awscdk.BundlingOptions
import io.cloudshiftdev.awscdk.CfnResource
import io.cloudshiftdev.awscdk.IAsset
import io.cloudshiftdev.awscdk.IgnoreMode
import io.cloudshiftdev.awscdk.SymlinkFollowMode
import io.cloudshiftdev.awscdk.common.CdkDslMarker
import io.cloudshiftdev.awscdk.services.iam.IGrantable
import io.cloudshiftdev.awscdk.services.s3.IBucket
import kotlin.Boolean
import kotlin.String
import kotlin.Unit
import kotlin.collections.List
import kotlin.jvm.JvmName
import io.cloudshiftdev.constructs.Construct as CloudshiftdevConstructsConstruct
import software.constructs.Construct as SoftwareConstructsConstruct
/**
* An asset represents a local file or directory, which is automatically uploaded to S3 and then can
* be referenced within a CDK application.
*
* Example:
*
* ```
* import io.cloudshiftdev.awscdk.*;
* Asset asset = Asset.Builder.create(this, "BundledAsset")
* .path("/path/to/asset")
* .bundling(BundlingOptions.builder()
* .image(DockerImage.fromRegistry("alpine"))
* .command(List.of("command-that-produces-an-archive.sh"))
* .outputType(BundlingOutput.NOT_ARCHIVED)
* .build())
* .build();
* ```
*/
public open class Asset(
cdkObject: software.amazon.awscdk.services.s3.assets.Asset,
) : CloudshiftdevConstructsConstruct(cdkObject),
IAsset {
public constructor(
scope: CloudshiftdevConstructsConstruct,
id: String,
props: AssetProps,
) :
this(software.amazon.awscdk.services.s3.assets.Asset(scope.let(CloudshiftdevConstructsConstruct.Companion::unwrap),
id, props.let(AssetProps.Companion::unwrap))
)
public constructor(
scope: CloudshiftdevConstructsConstruct,
id: String,
props: AssetProps.Builder.() -> Unit,
) : this(scope, id, AssetProps(props)
)
/**
* Adds CloudFormation template metadata to the specified resource with information that indicates
* which resource property is mapped to this local asset.
*
* This can be used by tools such as SAM CLI to provide local
* experience such as local invocation and debugging of Lambda functions.
*
* Asset metadata will only be included if the stack is synthesized with the
* "aws:cdk:enable-asset-metadata" context key defined, which is the default
* behavior when synthesizing via the CDK Toolkit.
*
* [Documentation](https://github.com/aws/aws-cdk/issues/1432)
* @param resource The CloudFormation resource which is using this asset
* [disable-awslint:ref-via-interface].
* @param resourceProperty The property name where this asset is referenced (e.g. "Code" for
* AWS::Lambda::Function).
*/
public open fun addResourceMetadata(resource: CfnResource, resourceProperty: String) {
unwrap(this).addResourceMetadata(resource.let(CfnResource.Companion::unwrap), resourceProperty)
}
/**
* A hash of this asset, which is available at construction time.
*
* As this is a plain string, it
* can be used in construct IDs in order to enforce creation of a new resource when the content
* hash has changed.
*/
public override fun assetHash(): String = unwrap(this).getAssetHash()
/**
* The path to the asset, relative to the current Cloud Assembly.
*
* If asset staging is disabled, this will just be the original path.
* If asset staging is enabled it will be the staged path.
*/
public open fun assetPath(): String = unwrap(this).getAssetPath()
/**
* The S3 bucket in which this asset resides.
*/
public open fun bucket(): IBucket = unwrap(this).getBucket().let(IBucket::wrap)
/**
* Grants read permissions to the principal on the assets bucket.
*
* @param grantee
*/
public open fun grantRead(grantee: IGrantable) {
unwrap(this).grantRead(grantee.let(IGrantable.Companion::unwrap))
}
/**
* Attribute which represents the S3 HTTP URL of this asset.
*
* For example, `https://s3.us-west-1.amazonaws.com/bucket/key`
*/
public open fun httpUrl(): String = unwrap(this).getHttpUrl()
/**
* Indicates if this asset is a single file.
*
* Allows constructs to ensure that the
* correct file type was used.
*/
public open fun isFile(): Boolean = unwrap(this).getIsFile()
/**
* Indicates if this asset is a zip archive.
*
* Allows constructs to ensure that the
* correct file type was used.
*/
public open fun isZipArchive(): Boolean = unwrap(this).getIsZipArchive()
/**
* Attribute that represents the name of the bucket this asset exists in.
*/
public open fun s3BucketName(): String = unwrap(this).getS3BucketName()
/**
* Attribute which represents the S3 object key of this asset.
*/
public open fun s3ObjectKey(): String = unwrap(this).getS3ObjectKey()
/**
* Attribute which represents the S3 URL of this asset.
*
* For example, `s3://bucket/key`
*/
public open fun s3ObjectUrl(): String = unwrap(this).getS3ObjectUrl()
/**
* A fluent builder for [io.cloudshiftdev.awscdk.services.s3.assets.Asset].
*/
@CdkDslMarker
public interface Builder {
/**
* Specify a custom hash for this asset.
*
* 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.
*
* Default: - based on `assetHashType`
*
* @param assetHash Specify a custom hash for this asset.
*/
public fun assetHash(assetHash: String)
/**
* Specifies the type of hash to calculate for this asset.
*
* If `assetHash` is configured, this option must be `undefined` or
* `AssetHashType.CUSTOM`.
*
* Default: - the default is `AssetHashType.SOURCE`, but if `assetHash` is
* explicitly specified this value defaults to `AssetHashType.CUSTOM`.
*
* @param assetHashType Specifies the type of hash to calculate for this asset.
*/
public fun assetHashType(assetHashType: AssetHashType)
/**
* Bundle the asset by executing a command in a Docker container or a custom bundling provider.
*
* 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.
*
* 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
*
* @param bundling Bundle the asset by executing a command in a Docker container or a custom
* bundling provider.
*/
public fun bundling(bundling: BundlingOptions)
/**
* Bundle the asset by executing a command in a Docker container or a custom bundling provider.
*
* 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.
*
* 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
*
* @param bundling Bundle the asset by executing a command in a Docker container or a custom
* bundling provider.
*/
@kotlin.Suppress("INAPPLICABLE_JVM_NAME")
@JvmName("507668c83b0111ed17916394eec5d6c85b10451e6896b5ff6482fd3d562938bc")
public fun bundling(bundling: BundlingOptions.Builder.() -> Unit)
/**
* Whether or not the asset needs to exist beyond deployment time;
*
* i.e.
* are copied over to a different location and not needed afterwards.
* Setting this property to true has an impact on the lifecycle of the asset,
* because we will assume that it is safe to delete after the CloudFormation
* deployment succeeds.
*
* For example, Lambda Function assets are copied over to Lambda during
* deployment. Therefore, it is not necessary to store the asset in S3, so
* we consider those deployTime assets.
*
* Default: false
*
* @param deployTime Whether or not the asset needs to exist beyond deployment time;.
*/
public fun deployTime(deployTime: Boolean)
/**
* File paths matching the patterns will be excluded.
*
* See `ignoreMode` to set the matching behavior.
* Has no effect on Assets bundled using the `bundling` property.
*
* Default: - nothing is excluded
*
* @param exclude File paths matching the patterns will be excluded.
*/
public fun exclude(exclude: List)
/**
* File paths matching the patterns will be excluded.
*
* See `ignoreMode` to set the matching behavior.
* Has no effect on Assets bundled using the `bundling` property.
*
* Default: - nothing is excluded
*
* @param exclude File paths matching the patterns will be excluded.
*/
public fun exclude(vararg exclude: String)
/**
* A strategy for how to handle symlinks.
*
* Default: SymlinkFollowMode.NEVER
*
* @param followSymlinks A strategy for how to handle symlinks.
*/
public fun followSymlinks(followSymlinks: SymlinkFollowMode)
/**
* The ignore behavior to use for `exclude` patterns.
*
* Default: IgnoreMode.GLOB
*
* @param ignoreMode The ignore behavior to use for `exclude` patterns.
*/
public fun ignoreMode(ignoreMode: IgnoreMode)
/**
* The disk location of the asset.
*
* The path should refer to one of the following:
*
* * A regular file or a .zip file, in which case the file will be uploaded as-is to S3.
* * A directory, in which case it will be archived into a .zip file and uploaded to S3.
*
* @param path The disk location of the asset.
*/
public fun path(path: String)
/**
* A list of principals that should be able to read this asset from S3.
*
* You can use `asset.grantRead(principal)` to grant read permissions later.
*
* Default: - No principals that can read file asset.
*
* @param readers A list of principals that should be able to read this asset from S3.
*/
public fun readers(readers: List)
/**
* A list of principals that should be able to read this asset from S3.
*
* You can use `asset.grantRead(principal)` to grant read permissions later.
*
* Default: - No principals that can read file asset.
*
* @param readers A list of principals that should be able to read this asset from S3.
*/
public fun readers(vararg readers: IGrantable)
}
private class BuilderImpl(
scope: SoftwareConstructsConstruct,
id: String,
) : Builder {
private val cdkBuilder: software.amazon.awscdk.services.s3.assets.Asset.Builder =
software.amazon.awscdk.services.s3.assets.Asset.Builder.create(scope, id)
/**
* Specify a custom hash for this asset.
*
* 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.
*
* Default: - based on `assetHashType`
*
* @param assetHash Specify a custom hash for this asset.
*/
override fun assetHash(assetHash: String) {
cdkBuilder.assetHash(assetHash)
}
/**
* Specifies the type of hash to calculate for this asset.
*
* If `assetHash` is configured, this option must be `undefined` or
* `AssetHashType.CUSTOM`.
*
* Default: - the default is `AssetHashType.SOURCE`, but if `assetHash` is
* explicitly specified this value defaults to `AssetHashType.CUSTOM`.
*
* @param assetHashType Specifies the type of hash to calculate for this asset.
*/
override fun assetHashType(assetHashType: AssetHashType) {
cdkBuilder.assetHashType(assetHashType.let(AssetHashType.Companion::unwrap))
}
/**
* Bundle the asset by executing a command in a Docker container or a custom bundling provider.
*
* 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.
*
* 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
*
* @param bundling Bundle the asset by executing a command in a Docker container or a custom
* bundling provider.
*/
override fun bundling(bundling: BundlingOptions) {
cdkBuilder.bundling(bundling.let(BundlingOptions.Companion::unwrap))
}
/**
* Bundle the asset by executing a command in a Docker container or a custom bundling provider.
*
* 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.
*
* 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
*
* @param bundling Bundle the asset by executing a command in a Docker container or a custom
* bundling provider.
*/
@kotlin.Suppress("INAPPLICABLE_JVM_NAME")
@JvmName("507668c83b0111ed17916394eec5d6c85b10451e6896b5ff6482fd3d562938bc")
override fun bundling(bundling: BundlingOptions.Builder.() -> Unit): Unit =
bundling(BundlingOptions(bundling))
/**
* Whether or not the asset needs to exist beyond deployment time;
*
* i.e.
* are copied over to a different location and not needed afterwards.
* Setting this property to true has an impact on the lifecycle of the asset,
* because we will assume that it is safe to delete after the CloudFormation
* deployment succeeds.
*
* For example, Lambda Function assets are copied over to Lambda during
* deployment. Therefore, it is not necessary to store the asset in S3, so
* we consider those deployTime assets.
*
* Default: false
*
* @param deployTime Whether or not the asset needs to exist beyond deployment time;.
*/
override fun deployTime(deployTime: Boolean) {
cdkBuilder.deployTime(deployTime)
}
/**
* File paths matching the patterns will be excluded.
*
* See `ignoreMode` to set the matching behavior.
* Has no effect on Assets bundled using the `bundling` property.
*
* Default: - nothing is excluded
*
* @param exclude File paths matching the patterns will be excluded.
*/
override fun exclude(exclude: List) {
cdkBuilder.exclude(exclude)
}
/**
* File paths matching the patterns will be excluded.
*
* See `ignoreMode` to set the matching behavior.
* Has no effect on Assets bundled using the `bundling` property.
*
* Default: - nothing is excluded
*
* @param exclude File paths matching the patterns will be excluded.
*/
override fun exclude(vararg exclude: String): Unit = exclude(exclude.toList())
/**
* A strategy for how to handle symlinks.
*
* Default: SymlinkFollowMode.NEVER
*
* @param followSymlinks A strategy for how to handle symlinks.
*/
override fun followSymlinks(followSymlinks: SymlinkFollowMode) {
cdkBuilder.followSymlinks(followSymlinks.let(SymlinkFollowMode.Companion::unwrap))
}
/**
* The ignore behavior to use for `exclude` patterns.
*
* Default: IgnoreMode.GLOB
*
* @param ignoreMode The ignore behavior to use for `exclude` patterns.
*/
override fun ignoreMode(ignoreMode: IgnoreMode) {
cdkBuilder.ignoreMode(ignoreMode.let(IgnoreMode.Companion::unwrap))
}
/**
* The disk location of the asset.
*
* The path should refer to one of the following:
*
* * A regular file or a .zip file, in which case the file will be uploaded as-is to S3.
* * A directory, in which case it will be archived into a .zip file and uploaded to S3.
*
* @param path The disk location of the asset.
*/
override fun path(path: String) {
cdkBuilder.path(path)
}
/**
* A list of principals that should be able to read this asset from S3.
*
* You can use `asset.grantRead(principal)` to grant read permissions later.
*
* Default: - No principals that can read file asset.
*
* @param readers A list of principals that should be able to read this asset from S3.
*/
override fun readers(readers: List) {
cdkBuilder.readers(readers.map(IGrantable.Companion::unwrap))
}
/**
* A list of principals that should be able to read this asset from S3.
*
* You can use `asset.grantRead(principal)` to grant read permissions later.
*
* Default: - No principals that can read file asset.
*
* @param readers A list of principals that should be able to read this asset from S3.
*/
override fun readers(vararg readers: IGrantable): Unit = readers(readers.toList())
public fun build(): software.amazon.awscdk.services.s3.assets.Asset = cdkBuilder.build()
}
public companion object {
public operator fun invoke(
scope: CloudshiftdevConstructsConstruct,
id: String,
block: Builder.() -> Unit = {},
): Asset {
val builderImpl = BuilderImpl(CloudshiftdevConstructsConstruct.unwrap(scope), id)
return Asset(builderImpl.apply(block).build())
}
internal fun wrap(cdkObject: software.amazon.awscdk.services.s3.assets.Asset): Asset =
Asset(cdkObject)
internal fun unwrap(wrapped: Asset): software.amazon.awscdk.services.s3.assets.Asset =
wrapped.cdkObject as software.amazon.awscdk.services.s3.assets.Asset
}
}