AssetManifestBuilder

Build an asset manifest from assets added to a stack.

This class does not need to be used by app builders; it is only necessary for building Stack Synthesizers.

Initializers

import ros_cdk_core
ros_cdk_core.AssetManifestBuilder()

Name	Type	Description

Methods

Name	Description
`add_docker_image_asset`	Add a docker asset source and destination to the manifest.
`add_file_asset`	Add a file asset source and destination to the manifest.
`default_add_docker_image_asset`	Add a docker image asset to the manifest with default settings.
`default_add_file_asset`	Add a file asset to the manifest with default settings.
`emit_manifest`	Write the manifest to disk, and add it to the synthesis session.

`add_docker_image_asset`

def add_docker_image_asset(
  stack: Stack,
  source_hash: str,
  cache_disabled: bool = None,
  cache_from: typing.List[DockerCacheOption] = None,
  cache_to: DockerCacheOption = None,
  directory: str = None,
  docker_build_args: typing.Mapping[str] = None,
  docker_build_secrets: typing.Mapping[str] = None,
  docker_build_ssh: str = None,
  docker_build_target: str = None,
  docker_file: str = None,
  docker_outputs: typing.List[str] = None,
  executable: typing.List[str] = None,
  network_mode: str = None,
  platform: str = None,
  region: str = None,
  image_tag: str,
  repository_name: str
) -> DockerImageDestination

Add a docker asset source and destination to the manifest.

sourceHash should be unique for every source.

stack^Required

Type: Stack

source_hash^Required

Type: str

cache_disabled^Optional

Type: bool
Default: cache is used

Disable the cache and pass --no-cache to the docker build command.

cache_from^Optional

Type: typing.List[ros_cdk_assembly_schema.DockerCacheOption]
Default: no cache from options are passed to the build command

Cache from options to pass to the docker build command.

https://docs.docker.com/build/cache/backends/

cache_to^Optional

Type: ros_cdk_assembly_schema.DockerCacheOption
Default: no cache to options are passed to the build command

Cache to options to pass to the docker build command.

https://docs.docker.com/build/cache/backends/

directory^Optional

Type: str
Default: Exactly one of directory and executable is required

The directory containing the Docker image build instructions.

This path is relative to the asset manifest location.

docker_build_args^Optional

Type: typing.Mapping[str]
Default: No additional build arguments

Additional build arguments.

Only allowed when directory is set.

docker_build_secrets^Optional

Type: typing.Mapping[str]
Default: No additional build secrets

Additional build secrets.

Only allowed when directory is set.

docker_build_ssh^Optional

Type: str
Default: No ssh flag is set

SSH agent socket or keys.

Requires building with docker buildkit.

docker_build_target^Optional

Type: str
Default: The last stage in the Dockerfile

Target build stage in a Dockerfile with multiple build stages.

Only allowed when directory is set.

docker_file^Optional

Type: str
Default: "Dockerfile"

The name of the file with build instructions.

Only allowed when directory is set.

docker_outputs^Optional

Type: typing.List[str]
Default: no outputs are passed to the build command (default outputs are used)

Outputs.

https://docs.docker.com/engine/reference/commandline/build/#custom-build-outputs

executable^Optional

Type: typing.List[str]
Default: Exactly one of directory and executable is required

A command-line executable that returns the name of a local Docker image on stdout after being run.

network_mode^Optional

Type: str
Default: no networking mode specified

Networking mode for the RUN commands during build. Requires Docker Engine API v1.25+.

Specify this property to build images on a specific networking mode.

platform^Optional

Type: str
Default: current machine platform

Platform to build for. Requires Docker Buildx.

Specify this property to build images on a specific platform/architecture.

region^Optional

Type: str
Default: Current region

The region where this asset will need to be published.

image_tag^Required

Type: str

Tag of the image to publish.

repository_name^Required

Type: str

Name of the ECR repository to publish to.

`add_file_asset`

def add_file_asset(
  stack: Stack,
  source_hash: str,
  executable: typing.List[str] = None,
  packaging: FileAssetPackaging = None,
  path: str = None,
  region: str = None,
  bucket_name: str,
  object_key: str
) -> FileDestination

Add a file asset source and destination to the manifest.

sourceHash should be unique for every source.

stack^Required

Type: Stack

source_hash^Required

Type: str

executable^Optional

Type: typing.List[str]
Default: Exactly one of executable and path is required.

External command which will produce the file asset to upload.

packaging^Optional

Type: ros_cdk_assembly_schema.FileAssetPackaging
Default: FILE

Packaging method.

Only allowed when path is specified.

path^Optional

Type: str
Default: Exactly one of executable and path is required.

The filesystem object to upload.

This path is relative to the asset manifest location.

region^Optional

Type: str
Default: Current region

The region where this asset will need to be published.

bucket_name^Required

Type: str

The name of the bucket.

object_key^Required

Type: str

The destination object key.

`default_add_docker_image_asset`

def default_add_docker_image_asset(
  stack: Stack,
  source_hash: str,
  asset_name: str = None,
  directory_name: str = None,
  docker_build_args: typing.Mapping[str] = None,
  docker_build_sac_rets: typing.Mapping[str] = None,
  docker_build_ssh: str = None,
  docker_build_target: str = None,
  docker_cache_disabled: bool = None,
  docker_cache_from: typing.List[DockerCacheOption] = None,
  docker_cache_to: DockerCacheOption = None,
  docker_file: str = None,
  docker_outputs: typing.List[str] = None,
  executable: typing.List[str] = None,
  network_mode: str = None,
  platform: str = None,
  repository_name: str,
  docker_tag_prefix: str = None
) -> DockerImageDestination

Add a docker image asset to the manifest with default settings.

Derive the region from the stack, use the asset hash as the key, and set the prefix.

stack^Required

Type: Stack

source_hash^Required

Type: str

The hash of the contents of the docker build context.

This hash is used throughout the system to identify this image and avoid duplicate work in case the source did not change.

NOTE: this means that if you wish to update your docker image, you must make a modification to the source (e.g. add some metadata to your Dockerfile).

asset_name^Optional

Type: str
Default: no asset name

Unique identifier of the docker image asset and its potential revisions.

Required if using AppScopedStagingSynthesizer.

directory_name^Optional

Type: str
Default: Exactly one of directoryName and executable is required

The directory where the Dockerfile is stored, must be relative to the cloud assembly root.

docker_build_args^Optional

Type: typing.Mapping[str]
Default: no build args are passed

Build args to pass to the docker build command.

Since Docker build arguments are resolved before deployment, keys and values cannot refer to unresolved tokens.

Only allowed when directoryName is specified.

docker_build_sac_rets^Optional

Type: typing.Mapping[str]
Default: no build sACRets are passed

Build sACRets to pass to the docker build command.

Since Docker build sACRets are resolved before deployment, keys and values cannot refer to unresolved tokens.

Only allowed when directoryName is specified.

docker_build_ssh^Optional

Type: str
Default: no ssh arg is passed

SSH agent socket or keys to pass to the docker buildx command.

docker_build_target^Optional

Type: str
Default: no target

Docker target to build to.

Only allowed when directoryName is specified.

docker_cache_disabled^Optional

Type: bool
Default: cache is used

Disable the cache and pass --no-cache to the docker build command.

docker_cache_from^Optional

Type: typing.List[DockerCacheOption]
Default: no cache from args are passed

Cache from options to pass to the docker build command.

docker_cache_to^Optional

Type: DockerCacheOption
Default: no cache to args are passed

Cache to options to pass to the docker build command.

docker_file^Optional

Type: str
Default: no file

Path to the Dockerfile (relative to the directory).

Only allowed when directoryName is specified.

docker_outputs^Optional

Type: typing.List[str]
Default: no build args are passed

Outputs to pass to the docker build command.

executable^Optional

Type: typing.List[str]
Default: Exactly one of directoryName and executable is required

An external command that will produce the packaged asset.

The command should produce the name of a local Docker image on stdout.

network_mode^Optional

Type: str
Default: no networking mode specified

Networking mode for the RUN commands during build. Requires Docker Engine API v1.25+.

Specify this property to build images on a specific networking mode.

platform^Optional

Type: str
Default: no platform specified (the current machine architecture will be used)

Platform to build for. Requires Docker Buildx.

Specify this property to build images on a specific platform.

repository_name^Required

Type: str

Repository name where the docker image asset should be written.

docker_tag_prefix^Optional

Type: str
Default: ''

Prefix to add to the asset hash to make the Docker image tag.

`default_add_file_asset`

def default_add_file_asset(
  stack: Stack,
  source_hash: str,
  deploy_time: bool = None,
  executable: typing.List[str] = None,
  file_name: str = None,
  packaging: FileAssetPackaging = None,
  bucket_name: str,
  bucket_prefix: str = None
) -> FileDestination

Add a file asset to the manifest with default settings.

Derive the region from the stack, use the asset hash as the key, copy the file extension over, and set the prefix.

stack^Required

Type: Stack

source_hash^Required

Type: str

A hash on the content source.

This hash is used to uniquely identify this asset throughout the system. If this value doesn't change, the asset will not be rebuilt or republished.

deploy_time^Optional

Type: bool
Default: false

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 ROS deployment succeeds.

For example, FC Function assets are copied over to FC during deployment. Therefore, it is not necessary to store the asset in OSS bucket, so we consider those deployTime assets.

executable^Optional

Type: typing.List[str]
Default: Exactly one of fileName and executable is required

An external command that will produce the packaged asset.

The command should produce the location of a ZIP file on stdout.

file_name^Optional

Type: str
Default: Exactly one of fileName and executable is required

The path, relative to the root of the cloud assembly, in which this asset source resides.

This can be a path to a file or a directory, depending on the packaging type.

packaging^Optional

Type: FileAssetPackaging
Default: Required if fileName is specified.

Which type of packaging to perform.

bucket_name^Required

Type: str

Bucket name where the file asset should be written.

bucket_prefix^Optional

Type: str
Default: ''

Prefix to prepend to the asset hash.

`emit_manifest`

def emit_manifest(
  stack: Stack,
  session: ISynthesisSession,
  dependencies: typing.List[str] = None
) -> str

Write the manifest to disk, and add it to the synthesis session.

Return the artifact id, which should be added to the additionalDependencies field of the stack artifact.

stack^Required

Type: Stack

session^Required

Type: ISynthesisSession

dependencies^Optional

Type: typing.List[str]

Properties

Name	Type	Description
`has_assets`	`bool`	Whether there are any assets registered in the manifest.

`has_assets`^Required

has_assets: bool

Type: bool

Whether there are any assets registered in the manifest.

AssetManifestBuilder

Initializers

Methods

add_docker_image_asset

add_file_asset

default_add_docker_image_asset

default_add_file_asset

emit_manifest

Properties

has_assetsRequired

`add_docker_image_asset`

`add_file_asset`

`default_add_docker_image_asset`

`default_add_file_asset`

`emit_manifest`

`has_assets`^Required