aws-cdk-lib/aws-ec2/lib/volume.d.ts

Version 2 of the AWS Cloud Development Kit library

import { Construct } from 'constructs';
import { IInstance } from './instance';
import { Grant, IGrantable } from '../../aws-iam';
import { IKey } from '../../aws-kms';
import { IResource, Resource, Size, RemovalPolicy } from '../../core';
/**
 * Block device
 */
export interface BlockDevice {
    /**
     * The device name exposed to the EC2 instance
     *
     * For example, a value like `/dev/sdh`, `xvdh`.
     *
     * @see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/device_naming.html
     */
    readonly deviceName: string;
    /**
     * Defines the block device volume, to be either an Amazon EBS volume or an ephemeral instance store volume
     *
     * For example, a value like `BlockDeviceVolume.ebs(15)`, `BlockDeviceVolume.ephemeral(0)`.
     */
    readonly volume: BlockDeviceVolume;
    /**
     * If false, the device mapping will be suppressed.
     * If set to false for the root device, the instance might fail the Amazon EC2 health check.
     * Amazon EC2 Auto Scaling launches a replacement instance if the instance fails the health check.
     *
     * @default true - device mapping is left untouched
     */
    readonly mappingEnabled?: boolean;
}
/**
 * Base block device options for an EBS volume
 */
export interface EbsDeviceOptionsBase {
    /**
     * Indicates whether to delete the volume when the instance is terminated.
     *
     * @default - true for Amazon EC2 Auto Scaling, false otherwise (e.g. EBS)
     */
    readonly deleteOnTermination?: boolean;
    /**
     * The number of I/O operations per second (IOPS) to provision for the volume.
     *
     * Must only be set for `volumeType`: `EbsDeviceVolumeType.IO1`
     *
     * The maximum ratio of IOPS to volume size (in GiB) is 50:1, so for 5,000 provisioned IOPS,
     * you need at least 100 GiB storage on the volume.
     *
     * @see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html
     *
     * @default - none, required for `EbsDeviceVolumeType.IO1`
     */
    readonly iops?: number;
    /**
     * The EBS volume type
     * @see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html
     *
     * @default `EbsDeviceVolumeType.GENERAL_PURPOSE_SSD` or `EbsDeviceVolumeType.GENERAL_PURPOSE_SSD_GP3` if
     * `@aws-cdk/aws-ec2:ebsDefaultGp3Volume` is enabled.
     */
    readonly volumeType?: EbsDeviceVolumeType;
    /**
     * The throughput to provision for a `gp3` volume.
     *
     * Valid Range: Minimum value of 125. Maximum value of 1000.
     *
     * `gp3` volumes deliver a consistent baseline throughput performance of 125 MiB/s.
     * You can provision additional throughput for an additional cost at a ratio of 0.25 MiB/s per provisioned IOPS.
     *
     * @see https://docs.aws.amazon.com/ebs/latest/userguide/general-purpose.html#gp3-performance
     *
     * @default - 125 MiB/s.
     */
    readonly throughput?: number;
}
/**
 * Block device options for an EBS volume
 */
export interface EbsDeviceOptions extends EbsDeviceOptionsBase {
    /**
     * Specifies whether the EBS volume is encrypted.
     * Encrypted EBS volumes can only be attached to instances that support Amazon EBS encryption
     *
     * @see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSEncryption.html#EBSEncryption_supported_instances
     *
     * @default false
     */
    readonly encrypted?: boolean;
    /**
     * The ARN of the AWS Key Management Service (AWS KMS) CMK used for encryption.
     *
     * You have to ensure that the KMS CMK has the correct permissions to be used by the service launching the ec2 instances.
     *
     * @see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSEncryption.html#ebs-encryption-requirements
     *
     * @default - If encrypted is true, the default aws/ebs KMS key will be used.
     */
    readonly kmsKey?: IKey;
}
/**
 * Block device options for an EBS volume created from a snapshot
 */
export interface EbsDeviceSnapshotOptions extends EbsDeviceOptionsBase {
    /**
     * The volume size, in Gibibytes (GiB)
     *
     * If you specify volumeSize, it must be equal or greater than the size of the snapshot.
     *
     * @default - The snapshot size
     */
    readonly volumeSize?: number;
}
/**
 * Properties of an EBS block device
 */
export interface EbsDeviceProps extends EbsDeviceSnapshotOptions, EbsDeviceOptions {
    /**
     * The snapshot ID of the volume to use
     *
     * @default - No snapshot will be used
     */
    readonly snapshotId?: string;
}
/**
 * Describes a block device mapping for an EC2 instance or Auto Scaling group.
 */
export declare class BlockDeviceVolume {
    readonly ebsDevice?: EbsDeviceProps | undefined;
    readonly virtualName?: string | undefined;
    /**
     * Creates a new Elastic Block Storage device
     *
     * @param volumeSize The volume size, in Gibibytes (GiB)
     * @param options additional device options
     */
    static ebs(volumeSize: number, options?: EbsDeviceOptions): BlockDeviceVolume;
    /**
     * Creates a new Elastic Block Storage device from an existing snapshot
     *
     * @param snapshotId The snapshot ID of the volume to use
     * @param options additional device options
     */
    static ebsFromSnapshot(snapshotId: string, options?: EbsDeviceSnapshotOptions): BlockDeviceVolume;
    /**
     * Creates a virtual, ephemeral device.
     * The name will be in the form ephemeral{volumeIndex}.
     *
     * @param volumeIndex the volume index. Must be equal or greater than 0
     */
    static ephemeral(volumeIndex: number): BlockDeviceVolume;
    /**
     * @param ebsDevice EBS device info
     * @param virtualName Virtual device name
     */
    protected constructor(ebsDevice?: EbsDeviceProps | undefined, virtualName?: string | undefined);
}
/**
 * Supported EBS volume types for blockDevices
 */
export declare enum EbsDeviceVolumeType {
    /**
     * Magnetic
     */
    STANDARD = "standard",
    /**
     *  Provisioned IOPS SSD - IO1
     */
    IO1 = "io1",
    /**
     *  Provisioned IOPS SSD - IO2
     */
    IO2 = "io2",
    /**
     * General Purpose SSD - GP2
     */
    GP2 = "gp2",
    /**
     * General Purpose SSD - GP3
     */
    GP3 = "gp3",
    /**
     * Throughput Optimized HDD
     */
    ST1 = "st1",
    /**
     * Cold HDD
     */
    SC1 = "sc1",
    /**
     * General purpose SSD volume (GP2) that balances price and performance for a wide variety of workloads.
     */
    GENERAL_PURPOSE_SSD = "gp2",
    /**
     * General purpose SSD volume (GP3) that balances price and performance for a wide variety of workloads.
     */
    GENERAL_PURPOSE_SSD_GP3 = "gp3",
    /**
     * Highest-performance SSD volume (IO1) for mission-critical low-latency or high-throughput workloads.
     */
    PROVISIONED_IOPS_SSD = "io1",
    /**
     * Highest-performance SSD volume (IO2) for mission-critical low-latency or high-throughput workloads.
     */
    PROVISIONED_IOPS_SSD_IO2 = "io2",
    /**
     * Low-cost HDD volume designed for frequently accessed, throughput-intensive workloads.
     */
    THROUGHPUT_OPTIMIZED_HDD = "st1",
    /**
     * Lowest cost HDD volume designed for less frequently accessed workloads.
     */
    COLD_HDD = "sc1",
    /**
     * Magnetic volumes are backed by magnetic drives and are suited for workloads where data is accessed infrequently, and scenarios where low-cost
     * storage for small volume sizes is important.
     */
    MAGNETIC = "standard"
}
/**
 * An EBS Volume in AWS EC2.
 */
export interface IVolume extends IResource {
    /**
     * The EBS Volume's ID
     *
     * @attribute
     */
    readonly volumeId: string;
    /**
     * The availability zone that the EBS Volume is contained within (ex: us-west-2a)
     */
    readonly availabilityZone: string;
    /**
     * The customer-managed encryption key that is used to encrypt the Volume.
     *
     * @attribute
     */
    readonly encryptionKey?: IKey;
    /**
     * Grants permission to attach this Volume to an instance.
     * CAUTION: Granting an instance permission to attach to itself using this method will lead to
     * an unresolvable circular reference between the instance role and the instance.
     * Use `IVolume.grantAttachVolumeToSelf` to grant an instance permission to attach this
     * volume to itself.
     *
     * @param grantee  the principal being granted permission.
     * @param instances the instances to which permission is being granted to attach this
     *                 volume to. If not specified, then permission is granted to attach
     *                 to all instances in this account.
     */
    grantAttachVolume(grantee: IGrantable, instances?: IInstance[]): Grant;
    /**
     * Grants permission to attach the Volume by a ResourceTag condition. If you are looking to
     * grant an Instance, AutoScalingGroup, EC2-Fleet, SpotFleet, ECS host, etc the ability to attach
     * this volume to **itself** then this is the method you want to use.
     *
     * This is implemented by adding a Tag with key `VolumeGrantAttach-<suffix>` to the given
     * constructs and this Volume, and then conditioning the Grant such that the grantee is only
     * given the ability to AttachVolume if both the Volume and the destination Instance have that
     * tag applied to them.
     *
     * @param grantee    the principal being granted permission.
     * @param constructs The list of constructs that will have the generated resource tag applied to them.
     * @param tagKeySuffix A suffix to use on the generated Tag key in place of the generated hash value.
     *                     Defaults to a hash calculated from this volume and list of constructs. (DEPRECATED)
     */
    grantAttachVolumeByResourceTag(grantee: IGrantable, constructs: Construct[], tagKeySuffix?: string): Grant;
    /**
     * Grants permission to detach this Volume from an instance
     * CAUTION: Granting an instance permission to detach from itself using this method will lead to
     * an unresolvable circular reference between the instance role and the instance.
     * Use `IVolume.grantDetachVolumeFromSelf` to grant an instance permission to detach this
     * volume from itself.
     *
     * @param grantee  the principal being granted permission.
     * @param instances the instances to which permission is being granted to detach this
     *                 volume from. If not specified, then permission is granted to detach
     *                 from all instances in this account.
     */
    grantDetachVolume(grantee: IGrantable, instances?: IInstance[]): Grant;
    /**
     * Grants permission to detach the Volume by a ResourceTag condition.
     *
     * This is implemented via the same mechanism as `IVolume.grantAttachVolumeByResourceTag`,
     * and is subject to the same conditions.
     *
     * @param grantee    the principal being granted permission.
     * @param constructs The list of constructs that will have the generated resource tag applied to them.
     * @param tagKeySuffix A suffix to use on the generated Tag key in place of the generated hash value.
     *                     Defaults to a hash calculated from this volume and list of constructs. (DEPRECATED)
     */
    grantDetachVolumeByResourceTag(grantee: IGrantable, constructs: Construct[], tagKeySuffix?: string): Grant;
}
/**
 * Properties of an EBS Volume
 */
export interface VolumeProps {
    /**
     * The value of the physicalName property of this resource.
     *
     * @default The physical name will be allocated by CloudFormation at deployment time
     */
    readonly volumeName?: string;
    /**
     * The Availability Zone in which to create the volume.
     */
    readonly availabilityZone: string;
    /**
     * The size of the volume, in GiBs. You must specify either a snapshot ID or a volume size.
     * See https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-volume.html
     * for details on the allowable size for each type of volume.
     *
     * @default If you're creating the volume from a snapshot and don't specify a volume size, the default is the snapshot size.
     */
    readonly size?: Size;
    /**
     * The snapshot from which to create the volume. You must specify either a snapshot ID or a volume size.
     *
     * @default The EBS volume is not created from a snapshot.
     */
    readonly snapshotId?: string;
    /**
     * Indicates whether Amazon EBS Multi-Attach is enabled.
     * See [Considerations and limitations](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-volumes-multi.html#considerations)
     * for the constraints of multi-attach.
     *
     * @default false
     */
    readonly enableMultiAttach?: boolean;
    /**
     * Specifies whether the volume should be encrypted. The effect of setting the encryption state to true depends on the volume origin
     * (new or from a snapshot), starting encryption state, ownership, and whether encryption by default is enabled. For more information,
     * see [Encryption by Default](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSEncryption.html#encryption-by-default)
     * in the Amazon Elastic Compute Cloud User Guide.
     *
     * Encrypted Amazon EBS volumes must be attached to instances that support Amazon EBS encryption. For more information, see
     * [Supported Instance Types](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSEncryption.html#EBSEncryption_supported_instances).
     *
     * @default false
     */
    readonly encrypted?: boolean;
    /**
     * The customer-managed encryption key that is used to encrypt the Volume. The encrypted property must
     * be true if this is provided.
     *
     * Note: If using an `aws-kms.IKey` created from a `aws-kms.Key.fromKeyArn()` here,
     * then the KMS key **must** have the following in its Key policy; otherwise, the Volume
     * will fail to create.
     *
     *     {
     *       "Effect": "Allow",
     *       "Principal": { "AWS": "<arn for your account-user> ex: arn:aws:iam::00000000000:root" },
     *       "Resource": "*",
     *       "Action": [
     *         "kms:DescribeKey",
     *         "kms:GenerateDataKeyWithoutPlainText",
     *       ],
     *       "Condition": {
     *         "StringEquals": {
     *           "kms:ViaService": "ec2.<Region>.amazonaws.com", (eg: ec2.us-east-1.amazonaws.com)
     *           "kms:CallerAccount": "0000000000" (your account ID)
     *         }
     *       }
     *     }
     *
     * @default The default KMS key for the account, region, and EC2 service is used.
     */
    readonly encryptionKey?: IKey;
    /**
     * Indicates whether the volume is auto-enabled for I/O operations. By default, Amazon EBS disables I/O to the volume from attached EC2
     * instances when it determines that a volume's data is potentially inconsistent. If the consistency of the volume is not a concern, and
     * you prefer that the volume be made available immediately if it's impaired, you can configure the volume to automatically enable I/O.
     *
     * @default false
     */
    readonly autoEnableIo?: boolean;
    /**
     * The type of the volume; what type of storage to use to form the EBS Volume.
     *
     * @default `EbsDeviceVolumeType.GENERAL_PURPOSE_SSD`
     */
    readonly volumeType?: EbsDeviceVolumeType;
    /**
     * The number of I/O operations per second (IOPS) to provision for the volume. The maximum ratio is 50 IOPS/GiB for PROVISIONED_IOPS_SSD,
     * and 500 IOPS/GiB for both PROVISIONED_IOPS_SSD_IO2 and GENERAL_PURPOSE_SSD_GP3.
     * See https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-volume.html
     * for more information.
     *
     * This parameter is valid only for PROVISIONED_IOPS_SSD, PROVISIONED_IOPS_SSD_IO2 and GENERAL_PURPOSE_SSD_GP3 volumes.
     *
     * @default None -- Required for io1 and io2 volumes. The default for gp3 volumes is 3,000 IOPS if omitted.
     */
    readonly iops?: number;
    /**
     * Policy to apply when the volume is removed from the stack
     *
     * @default RemovalPolicy.RETAIN
     */
    readonly removalPolicy?: RemovalPolicy;
    /**
     * The throughput that the volume supports, in MiB/s
     * Takes a minimum of 125 and maximum of 1000.
     * @see https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-volume.html#cfn-ec2-volume-throughput
     * @default - 125 MiB/s. Only valid on gp3 volumes.
     */
    readonly throughput?: number;
}
/**
 * Attributes required to import an existing EBS Volume into the Stack.
 */
export interface VolumeAttributes {
    /**
     * The EBS Volume's ID
     */
    readonly volumeId: string;
    /**
     * The availability zone that the EBS Volume is contained within (ex: us-west-2a)
     */
    readonly availabilityZone: string;
    /**
     * The customer-managed encryption key that is used to encrypt the Volume.
     *
     * @default None -- The EBS Volume is not using a customer-managed KMS key for encryption.
     */
    readonly encryptionKey?: IKey;
}
/**
 * Common behavior of Volumes. Users should not use this class directly, and instead use ``Volume``.
 */
declare abstract class VolumeBase extends Resource implements IVolume {
    abstract readonly volumeId: string;
    abstract readonly availabilityZone: string;
    abstract readonly encryptionKey?: IKey;
    grantAttachVolume(grantee: IGrantable, instances?: IInstance[]): Grant;
    grantAttachVolumeByResourceTag(grantee: IGrantable, constructs: Construct[], tagKeySuffix?: string): Grant;
    grantDetachVolume(grantee: IGrantable, instances?: IInstance[]): Grant;
    grantDetachVolumeByResourceTag(grantee: IGrantable, constructs: Construct[], tagKeySuffix?: string): Grant;
    private collectGrantResourceArns;
    private calculateResourceTagValue;
}
/**
 * Creates a new EBS Volume in AWS EC2.
 */
export declare class Volume extends VolumeBase {
    /**
     * Import an existing EBS Volume into the Stack.
     *
     * @param scope the scope of the import.
     * @param id    the ID of the imported Volume in the construct tree.
     * @param attrs the attributes of the imported Volume
     */
    static fromVolumeAttributes(scope: Construct, id: string, attrs: VolumeAttributes): IVolume;
    readonly volumeId: string;
    readonly availabilityZone: string;
    readonly encryptionKey?: IKey;
    constructor(scope: Construct, id: string, props: VolumeProps);
    protected validateProps(props: VolumeProps): void;
}
export {};