@aws-cdk/aws-imagebuilder-alpha 2.228.0-alpha.0 → 2.229.1-alpha.0

package/lib/container-recipe.d.ts

@@ -0,0 +1,337 @@
+import * as cdk from 'aws-cdk-lib';
+import * as ec2 from 'aws-cdk-lib/aws-ec2';
+import * as iam from 'aws-cdk-lib/aws-iam';
+import * as kms from 'aws-cdk-lib/aws-kms';
+import * as s3 from 'aws-cdk-lib/aws-s3';
+import * as s3assets from 'aws-cdk-lib/aws-s3-assets';
+import { Construct } from 'constructs';
+import { BaseContainerImage, ContainerInstanceImage } from './base-image';
+import { Repository } from './distribution-configuration';
+import { IImageRecipe } from './image-recipe';
+import { OSVersion } from './os-version';
+import { ComponentConfiguration, IRecipeBase } from './recipe-base';
+/**
+ * An EC2 Image Builder Container Recipe.
+ */
+export interface IContainerRecipe extends IRecipeBase {
+    /**
+     * The ARN of the container recipe
+     *
+     * @attribute
+     */
+    readonly containerRecipeArn: string;
+    /**
+     * The name of the container recipe
+     *
+     * @attribute
+     */
+    readonly containerRecipeName: string;
+    /**
+     * The version of the container recipe
+     *
+     * @attribute
+     */
+    readonly containerRecipeVersion: string;
+}
+/**
+ * Properties for creating a Container Recipe resource
+ */
+export interface ContainerRecipeProps {
+    /**
+     * The base image for customizations specified in the container recipe.
+     */
+    readonly baseImage: BaseContainerImage;
+    /**
+     * The container repository where the output container image is stored.
+     */
+    readonly targetRepository: Repository;
+    /**
+     * The name of the container recipe.
+     *
+     * @default a name is generated
+     */
+    readonly containerRecipeName?: string;
+    /**
+     * The version of the container recipe.
+     *
+     * @default 1.0.x
+     */
+    readonly containerRecipeVersion?: string;
+    /**
+     * The description of the container recipe.
+     *
+     * @default None
+     */
+    readonly description?: string;
+    /**
+     * The dockerfile template used to build the container image.
+     *
+     * @default - a standard dockerfile template will be generated to pull the base image, perform environment setup, and
+     * run all components in the recipe
+     */
+    readonly dockerfile?: DockerfileData;
+    /**
+     * The list of component configurations to apply in the image build.
+     *
+     * @default None
+     */
+    readonly components?: ComponentConfiguration[];
+    /**
+     * The KMS key used to encrypt the dockerfile template.
+     *
+     * @default None
+     */
+    readonly kmsKey?: kms.IKey;
+    /**
+     * The working directory for use during build and test workflows.
+     *
+     * @default - the Image Builder default working directory is used. For Linux and macOS builds, this would be /tmp. For
+     * Windows builds, this would be C:/
+     */
+    readonly workingDirectory?: string;
+    /**
+     * The operating system (OS) version of the base image.
+     *
+     * @default - Image Builder will determine the OS version of the base image, if sourced from a third-party container
+     * registry. Otherwise, the OS version of the base image is required.
+     */
+    readonly osVersion?: OSVersion;
+    /**
+     * The block devices to attach to the instance used for building, testing, and distributing the container image.
+     *
+     * @default the block devices of the instance image will be used
+     */
+    readonly instanceBlockDevices?: ec2.BlockDevice[];
+    /**
+     * The image to use to launch the instance used for building, testing, and distributing the container image.
+     *
+     * @default Image Builder will use the appropriate ECS-optimized AMI
+     */
+    readonly instanceImage?: ContainerInstanceImage;
+    /**
+     * The tags to apply to the container recipe
+     *
+     * @default None
+     */
+    readonly tags?: {
+        [key: string]: string;
+    };
+}
+/**
+ * The type of the container being used in the container recipe
+ */
+export declare enum ContainerType {
+    /**
+     * Indicates the container recipe uses a Docker container
+     */
+    DOCKER = "DOCKER"
+}
+/**
+ * The rendered Dockerfile value, for use in CloudFormation.
+ * - For inline dockerfiles, dockerfileTemplateData is the Dockerfile template text
+ * - For S3-backed dockerfiles, dockerfileTemplateUri is the S3 URL
+ */
+export interface DockerfileTemplateConfig {
+    /**
+     * The rendered Dockerfile data, for use in CloudFormation
+     *
+     * @default - none if dockerfileTemplateUri is set
+     */
+    readonly dockerfileTemplateData?: string;
+    /**
+     * The rendered Dockerfile URI, for use in CloudFormation
+     *
+     * @default - none if dockerfileTemplateData is set
+     */
+    readonly dockerfileTemplateUri?: string;
+}
+/**
+ * Helper class for referencing and uploading dockerfile data for the container recipe
+ */
+export declare abstract class DockerfileData {
+    /**
+     * Uploads dockerfile data from a local file to S3 to use as the dockerfile data
+     *
+     * @param scope The construct scope
+     * @param id Identifier of the construct
+     * @param path The local path to the dockerfile data file
+     * @param options S3 asset upload options
+     */
+    static fromAsset(scope: Construct, id: string, path: string, options?: s3assets.AssetOptions): S3DockerfileData;
+    /**
+     * References dockerfile data from a pre-existing S3 object
+     *
+     * @param bucket The S3 bucket where the dockerfile data is stored
+     * @param key The S3 key of the dockerfile data file
+     */
+    static fromS3(bucket: s3.IBucket, key: string): S3DockerfileData;
+    /**
+     * Uses an inline string as the dockerfile data
+     *
+     * @param data An inline string representing the dockerfile data
+     */
+    static fromInline(data: string): DockerfileData;
+    /**
+     * The rendered Dockerfile value, for use in CloudFormation.
+     * - For inline dockerfiles, dockerfileTemplateData is the Dockerfile template text
+     * - For S3-backed dockerfiles, dockerfileTemplateUri is the S3 URL
+     */
+    abstract render(): DockerfileTemplateConfig;
+}
+/**
+ * Helper class for S3-based dockerfile data references, containing additional permission grant methods on the S3 object
+ */
+export declare abstract class S3DockerfileData extends DockerfileData {
+    protected readonly bucket: s3.IBucket;
+    protected readonly key: string;
+    protected constructor(bucket: s3.IBucket, key: string);
+    /**
+     * The rendered Dockerfile S3 URL, for use in CloudFormation
+     */
+    render(): DockerfileTemplateConfig;
+    /**
+     * Grant put permissions to the given grantee for the dockerfile data in S3
+     *
+     * @param grantee The principal
+     */
+    grantPut(grantee: iam.IGrantable): iam.Grant;
+    /**
+     * Grant read permissions to the given grantee for the dockerfile data in S3
+     *
+     * @param grantee The principal
+     */
+    grantRead(grantee: iam.IGrantable): iam.Grant;
+}
+/**
+ * Properties for an EC2 Image Builder container recipe
+ */
+export interface ContainerRecipeAttributes {
+    /**
+     * The ARN of the container recipe
+     *
+     * @default - derived from containerRecipeName
+     */
+    readonly containerRecipeArn?: string;
+    /**
+     * The name of the container recipe
+     *
+     * @default - derived from containerRecipeArn
+     */
+    readonly containerRecipeName?: string;
+    /**
+     * The version of the container recipe
+     *
+     * @default - derived from containerRecipeArn. if a containerRecipeName is provided, the latest version, x.x.x, will
+     * be used.
+     */
+    readonly containerRecipeVersion?: string;
+}
+/**
+ * A new or imported Container Recipe
+ */
+export declare abstract class ContainerRecipeBase extends cdk.Resource implements IContainerRecipe {
+    /**
+     * The ARN of the container recipe
+     */
+    abstract readonly containerRecipeArn: string;
+    /**
+     * The name of the container recipe
+     */
+    abstract readonly containerRecipeName: string;
+    /**
+     * The version of the container recipe
+     */
+    abstract readonly containerRecipeVersion: string;
+    /**
+     * Grant custom actions to the given grantee for the container recipe
+     *
+     * @param grantee The principal
+     * @param actions The list of actions
+     */
+    grant(grantee: iam.IGrantable, ...actions: string[]): iam.Grant;
+    /**
+     * Grant read permissions to the given grantee for the container recipe
+     *
+     * @param grantee The principal
+     */
+    grantRead(grantee: iam.IGrantable): iam.Grant;
+    /**
+     * Indicates whether the recipe is a Container Recipe
+     *
+     * @internal
+     */
+    _isContainerRecipe(): this is IContainerRecipe;
+    /**
+     * Indicates whether the recipe is an Image Recipe
+     *
+     * @internal
+     */
+    _isImageRecipe(): this is IImageRecipe;
+}
+/**
+ * Represents an EC2 Image Builder Container Recipe.
+ *
+ * @see https://docs.aws.amazon.com/imagebuilder/latest/userguide/manage-recipes.html
+ */
+export declare class ContainerRecipe extends ContainerRecipeBase {
+    /** Uniquely identifies this class. */
+    static readonly PROPERTY_INJECTION_ID: string;
+    /**
+     * Import an existing container recipe given its ARN.
+     */
+    static fromContainerRecipeArn(scope: Construct, id: string, containerRecipeArn: string): IContainerRecipe;
+    /**
+     * Import the latest version of an existing container recipe given its name. The provided name must be normalized by
+     * converting all alphabetical characters to lowercase, and replacing all spaces and underscores with hyphens.
+     */
+    static fromContainerRecipeName(scope: Construct, id: string, containerRecipeName: string): IContainerRecipe;
+    /**
+     * Import an existing container recipe by providing its attributes. If the container recipe name is provided as an
+     * attribute, it must be normalized by converting all alphabetical characters to lowercase, and replacing all spaces
+     * and underscores with hyphens.
+     */
+    static fromContainerRecipeAttributes(scope: Construct, id: string, attrs: ContainerRecipeAttributes): IContainerRecipe;
+    /**
+     * Return whether the given object is a ContainerRecipe.
+     */
+    static isContainerRecipe(x: any): x is ContainerRecipe;
+    /**
+     * The ARN of the container recipe
+     */
+    readonly containerRecipeArn: string;
+    /**
+     * The name of the container recipe
+     */
+    readonly containerRecipeName: string;
+    /**
+     * The version of the container recipe
+     */
+    readonly containerRecipeVersion: string;
+    private readonly instanceBlockDevices;
+    constructor(scope: Construct, id: string, props: ContainerRecipeProps);
+    /**
+     * Adds block devices to attach to the instance used for building, testing, and distributing the container image.
+     *
+     * @param instanceBlockDevices - The list of block devices to attach
+     */
+    addInstanceBlockDevice(...instanceBlockDevices: ec2.BlockDevice[]): void;
+    /**
+     * Renders the block devices provided as input to the construct, into the block device mapping structure that
+     * CfnContainerRecipe expects to receive.
+     *
+     * This is rendered at synthesis time, as users can add additional block devices with `addInstanceBlockDevice`, after
+     * the construct has been instantiated.
+     *
+     * @private
+     */
+    private renderBlockDevices;
+    /**
+     * Generates the instance configuration property into the `InstanceConfiguration` type in the  CloudFormation L1
+     * definition.
+     *
+     * @param props The props passed as input to the construct
+     * @private
+     */
+    private buildInstanceConfiguration;
+    private validateContainerRecipeName;
+}