1 | import { Grant, IGrantable } from '@aws-cdk/aws-iam';
|
2 | import { IKey } from '@aws-cdk/aws-kms';
|
3 | import { IResource, Resource, Size, RemovalPolicy } from '@aws-cdk/core';
|
4 | import { Construct } from 'constructs';
|
5 | import { IInstance } from './instance';
|
6 | /**
|
7 | * Block device
|
8 | */
|
9 | export interface BlockDevice {
|
10 | /**
|
11 | * The device name exposed to the EC2 instance
|
12 | *
|
13 | * For example, a value like `/dev/sdh`, `xvdh`.
|
14 | *
|
15 | * @see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/device_naming.html
|
16 | */
|
17 | readonly deviceName: string;
|
18 | /**
|
19 | * Defines the block device volume, to be either an Amazon EBS volume or an ephemeral instance store volume
|
20 | *
|
21 | * For example, a value like `BlockDeviceVolume.ebs(15)`, `BlockDeviceVolume.ephemeral(0)`.
|
22 | */
|
23 | readonly volume: BlockDeviceVolume;
|
24 | /**
|
25 | * If false, the device mapping will be suppressed.
|
26 | * If set to false for the root device, the instance might fail the Amazon EC2 health check.
|
27 | * Amazon EC2 Auto Scaling launches a replacement instance if the instance fails the health check.
|
28 | *
|
29 | * @default true - device mapping is left untouched
|
30 | */
|
31 | readonly mappingEnabled?: boolean;
|
32 | }
|
33 | /**
|
34 | * Base block device options for an EBS volume
|
35 | */
|
36 | export interface EbsDeviceOptionsBase {
|
37 | /**
|
38 | * Indicates whether to delete the volume when the instance is terminated.
|
39 | *
|
40 | * @default - true for Amazon EC2 Auto Scaling, false otherwise (e.g. EBS)
|
41 | */
|
42 | readonly deleteOnTermination?: boolean;
|
43 | /**
|
44 | * The number of I/O operations per second (IOPS) to provision for the volume.
|
45 | *
|
46 | * Must only be set for {@link volumeType}: {@link EbsDeviceVolumeType.IO1}
|
47 | *
|
48 | * The maximum ratio of IOPS to volume size (in GiB) is 50:1, so for 5,000 provisioned IOPS,
|
49 | * you need at least 100 GiB storage on the volume.
|
50 | *
|
51 | * @see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html
|
52 | *
|
53 | * @default - none, required for {@link EbsDeviceVolumeType.IO1}
|
54 | */
|
55 | readonly iops?: number;
|
56 | /**
|
57 | * The EBS volume type
|
58 | * @see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html
|
59 | *
|
60 | * @default {@link EbsDeviceVolumeType.GP2}
|
61 | */
|
62 | readonly volumeType?: EbsDeviceVolumeType;
|
63 | }
|
64 | /**
|
65 | * Block device options for an EBS volume
|
66 | */
|
67 | export interface EbsDeviceOptions extends EbsDeviceOptionsBase {
|
68 | /**
|
69 | * Specifies whether the EBS volume is encrypted.
|
70 | * Encrypted EBS volumes can only be attached to instances that support Amazon EBS encryption
|
71 | *
|
72 | * @see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSEncryption.html#EBSEncryption_supported_instances
|
73 | *
|
74 | * @default false
|
75 | */
|
76 | readonly encrypted?: boolean;
|
77 | /**
|
78 | * The ARN of the AWS Key Management Service (AWS KMS) CMK used for encryption.
|
79 | *
|
80 | * You have to ensure that the KMS CMK has the correct permissions to be used by the service launching the ec2 instances.
|
81 | *
|
82 | * @see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSEncryption.html#ebs-encryption-requirements
|
83 | *
|
84 | * @default - If encrypted is true, the default aws/ebs KMS key will be used.
|
85 | */
|
86 | readonly kmsKey?: IKey;
|
87 | }
|
88 | /**
|
89 | * Block device options for an EBS volume created from a snapshot
|
90 | */
|
91 | export interface EbsDeviceSnapshotOptions extends EbsDeviceOptionsBase {
|
92 | /**
|
93 | * The volume size, in Gibibytes (GiB)
|
94 | *
|
95 | * If you specify volumeSize, it must be equal or greater than the size of the snapshot.
|
96 | *
|
97 | * @default - The snapshot size
|
98 | */
|
99 | readonly volumeSize?: number;
|
100 | }
|
101 | /**
|
102 | * Properties of an EBS block device
|
103 | */
|
104 | export interface EbsDeviceProps extends EbsDeviceSnapshotOptions, EbsDeviceOptions {
|
105 | /**
|
106 | * The snapshot ID of the volume to use
|
107 | *
|
108 | * @default - No snapshot will be used
|
109 | */
|
110 | readonly snapshotId?: string;
|
111 | }
|
112 | /**
|
113 | * Describes a block device mapping for an EC2 instance or Auto Scaling group.
|
114 | */
|
115 | export declare class BlockDeviceVolume {
|
116 | readonly ebsDevice?: EbsDeviceProps | undefined;
|
117 | readonly virtualName?: string | undefined;
|
118 | /**
|
119 | * Creates a new Elastic Block Storage device
|
120 | *
|
121 | * @param volumeSize The volume size, in Gibibytes (GiB)
|
122 | * @param options additional device options
|
123 | */
|
124 | static ebs(volumeSize: number, options?: EbsDeviceOptions): BlockDeviceVolume;
|
125 | /**
|
126 | * Creates a new Elastic Block Storage device from an existing snapshot
|
127 | *
|
128 | * @param snapshotId The snapshot ID of the volume to use
|
129 | * @param options additional device options
|
130 | */
|
131 | static ebsFromSnapshot(snapshotId: string, options?: EbsDeviceSnapshotOptions): BlockDeviceVolume;
|
132 | /**
|
133 | * Creates a virtual, ephemeral device.
|
134 | * The name will be in the form ephemeral{volumeIndex}.
|
135 | *
|
136 | * @param volumeIndex the volume index. Must be equal or greater than 0
|
137 | */
|
138 | static ephemeral(volumeIndex: number): BlockDeviceVolume;
|
139 | /**
|
140 | * @param ebsDevice EBS device info
|
141 | * @param virtualName Virtual device name
|
142 | */
|
143 | protected constructor(ebsDevice?: EbsDeviceProps | undefined, virtualName?: string | undefined);
|
144 | }
|
145 | /**
|
146 | * Supported EBS volume types for blockDevices
|
147 | */
|
148 | export declare enum EbsDeviceVolumeType {
|
149 | /**
|
150 | * Magnetic
|
151 | */
|
152 | STANDARD = "standard",
|
153 | /**
|
154 | * Provisioned IOPS SSD - IO1
|
155 | */
|
156 | IO1 = "io1",
|
157 | /**
|
158 | * Provisioned IOPS SSD - IO2
|
159 | */
|
160 | IO2 = "io2",
|
161 | /**
|
162 | * General Purpose SSD - GP2
|
163 | */
|
164 | GP2 = "gp2",
|
165 | /**
|
166 | * General Purpose SSD - GP3
|
167 | */
|
168 | GP3 = "gp3",
|
169 | /**
|
170 | * Throughput Optimized HDD
|
171 | */
|
172 | ST1 = "st1",
|
173 | /**
|
174 | * Cold HDD
|
175 | */
|
176 | SC1 = "sc1",
|
177 | /**
|
178 | * General purpose SSD volume (GP2) that balances price and performance for a wide variety of workloads.
|
179 | */
|
180 | GENERAL_PURPOSE_SSD = "gp2",
|
181 | /**
|
182 | * General purpose SSD volume (GP3) that balances price and performance for a wide variety of workloads.
|
183 | */
|
184 | GENERAL_PURPOSE_SSD_GP3 = "gp3",
|
185 | /**
|
186 | * Highest-performance SSD volume (IO1) for mission-critical low-latency or high-throughput workloads.
|
187 | */
|
188 | PROVISIONED_IOPS_SSD = "io1",
|
189 | /**
|
190 | * Highest-performance SSD volume (IO2) for mission-critical low-latency or high-throughput workloads.
|
191 | */
|
192 | PROVISIONED_IOPS_SSD_IO2 = "io2",
|
193 | /**
|
194 | * Low-cost HDD volume designed for frequently accessed, throughput-intensive workloads.
|
195 | */
|
196 | THROUGHPUT_OPTIMIZED_HDD = "st1",
|
197 | /**
|
198 | * Lowest cost HDD volume designed for less frequently accessed workloads.
|
199 | */
|
200 | COLD_HDD = "sc1",
|
201 | /**
|
202 | * Magnetic volumes are backed by magnetic drives and are suited for workloads where data is accessed infrequently, and scenarios where low-cost
|
203 | * storage for small volume sizes is important.
|
204 | */
|
205 | MAGNETIC = "standard"
|
206 | }
|
207 | /**
|
208 | * An EBS Volume in AWS EC2.
|
209 | */
|
210 | export interface IVolume extends IResource {
|
211 | /**
|
212 | * The EBS Volume's ID
|
213 | *
|
214 | * @attribute
|
215 | */
|
216 | readonly volumeId: string;
|
217 | /**
|
218 | * The availability zone that the EBS Volume is contained within (ex: us-west-2a)
|
219 | */
|
220 | readonly availabilityZone: string;
|
221 | /**
|
222 | * The customer-managed encryption key that is used to encrypt the Volume.
|
223 | *
|
224 | * @attribute
|
225 | */
|
226 | readonly encryptionKey?: IKey;
|
227 | /**
|
228 | * Grants permission to attach this Volume to an instance.
|
229 | * CAUTION: Granting an instance permission to attach to itself using this method will lead to
|
230 | * an unresolvable circular reference between the instance role and the instance.
|
231 | * Use {@link IVolume.grantAttachVolumeToSelf} to grant an instance permission to attach this
|
232 | * volume to itself.
|
233 | *
|
234 | * @param grantee the principal being granted permission.
|
235 | * @param instances the instances to which permission is being granted to attach this
|
236 | * volume to. If not specified, then permission is granted to attach
|
237 | * to all instances in this account.
|
238 | */
|
239 | grantAttachVolume(grantee: IGrantable, instances?: IInstance[]): Grant;
|
240 | /**
|
241 | * Grants permission to attach the Volume by a ResourceTag condition. If you are looking to
|
242 | * grant an Instance, AutoScalingGroup, EC2-Fleet, SpotFleet, ECS host, etc the ability to attach
|
243 | * this volume to **itself** then this is the method you want to use.
|
244 | *
|
245 | * This is implemented by adding a Tag with key `VolumeGrantAttach-<suffix>` to the given
|
246 | * constructs and this Volume, and then conditioning the Grant such that the grantee is only
|
247 | * given the ability to AttachVolume if both the Volume and the destination Instance have that
|
248 | * tag applied to them.
|
249 | *
|
250 | * @param grantee the principal being granted permission.
|
251 | * @param constructs The list of constructs that will have the generated resource tag applied to them.
|
252 | * @param tagKeySuffix A suffix to use on the generated Tag key in place of the generated hash value.
|
253 | * Defaults to a hash calculated from this volume and list of constructs. (DEPRECATED)
|
254 | */
|
255 | grantAttachVolumeByResourceTag(grantee: IGrantable, constructs: Construct[], tagKeySuffix?: string): Grant;
|
256 | /**
|
257 | * Grants permission to detach this Volume from an instance
|
258 | * CAUTION: Granting an instance permission to detach from itself using this method will lead to
|
259 | * an unresolvable circular reference between the instance role and the instance.
|
260 | * Use {@link IVolume.grantDetachVolumeFromSelf} to grant an instance permission to detach this
|
261 | * volume from itself.
|
262 | *
|
263 | * @param grantee the principal being granted permission.
|
264 | * @param instances the instances to which permission is being granted to detach this
|
265 | * volume from. If not specified, then permission is granted to detach
|
266 | * from all instances in this account.
|
267 | */
|
268 | grantDetachVolume(grantee: IGrantable, instances?: IInstance[]): Grant;
|
269 | /**
|
270 | * Grants permission to detach the Volume by a ResourceTag condition.
|
271 | *
|
272 | * This is implemented via the same mechanism as {@link IVolume.grantAttachVolumeByResourceTag},
|
273 | * and is subject to the same conditions.
|
274 | *
|
275 | * @param grantee the principal being granted permission.
|
276 | * @param constructs The list of constructs that will have the generated resource tag applied to them.
|
277 | * @param tagKeySuffix A suffix to use on the generated Tag key in place of the generated hash value.
|
278 | * Defaults to a hash calculated from this volume and list of constructs. (DEPRECATED)
|
279 | */
|
280 | grantDetachVolumeByResourceTag(grantee: IGrantable, constructs: Construct[], tagKeySuffix?: string): Grant;
|
281 | }
|
282 | /**
|
283 | * Properties of an EBS Volume
|
284 | */
|
285 | export interface VolumeProps {
|
286 | /**
|
287 | * The value of the physicalName property of this resource.
|
288 | *
|
289 | * @default The physical name will be allocated by CloudFormation at deployment time
|
290 | */
|
291 | readonly volumeName?: string;
|
292 | /**
|
293 | * The Availability Zone in which to create the volume.
|
294 | */
|
295 | readonly availabilityZone: string;
|
296 | /**
|
297 | * The size of the volume, in GiBs. You must specify either a snapshot ID or a volume size.
|
298 | * See {@link https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ec2-ebs-volume.html}
|
299 | * for details on the allowable size for each type of volume.
|
300 | *
|
301 | * @default If you're creating the volume from a snapshot and don't specify a volume size, the default is the snapshot size.
|
302 | */
|
303 | readonly size?: Size;
|
304 | /**
|
305 | * The snapshot from which to create the volume. You must specify either a snapshot ID or a volume size.
|
306 | *
|
307 | * @default The EBS volume is not created from a snapshot.
|
308 | */
|
309 | readonly snapshotId?: string;
|
310 | /**
|
311 | * Indicates whether Amazon EBS Multi-Attach is enabled.
|
312 | * See {@link https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-volumes-multi.html#considerations|Considerations and limitations}
|
313 | * for the constraints of multi-attach.
|
314 | *
|
315 | * @default false
|
316 | */
|
317 | readonly enableMultiAttach?: boolean;
|
318 | /**
|
319 | * Specifies whether the volume should be encrypted. The effect of setting the encryption state to true depends on the volume origin
|
320 | * (new or from a snapshot), starting encryption state, ownership, and whether encryption by default is enabled. For more information,
|
321 | * see {@link https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSEncryption.html#encryption-by-default|Encryption by Default}
|
322 | * in the Amazon Elastic Compute Cloud User Guide.
|
323 | *
|
324 | * Encrypted Amazon EBS volumes must be attached to instances that support Amazon EBS encryption. For more information, see
|
325 | * {@link https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSEncryption.html#EBSEncryption_supported_instances|Supported Instance Types.}
|
326 | *
|
327 | * @default false
|
328 | */
|
329 | readonly encrypted?: boolean;
|
330 | /**
|
331 | * The customer-managed encryption key that is used to encrypt the Volume. The encrypted property must
|
332 | * be true if this is provided.
|
333 | *
|
334 | * Note: If using an {@link aws-kms.IKey} created from a {@link aws-kms.Key.fromKeyArn()} here,
|
335 | * then the KMS key **must** have the following in its Key policy; otherwise, the Volume
|
336 | * will fail to create.
|
337 | *
|
338 | * {
|
339 | * "Effect": "Allow",
|
340 | * "Principal": { "AWS": "<arn for your account-user> ex: arn:aws:iam::00000000000:root" },
|
341 | * "Resource": "*",
|
342 | * "Action": [
|
343 | * "kms:DescribeKey",
|
344 | * "kms:GenerateDataKeyWithoutPlainText",
|
345 | * ],
|
346 | * "Condition": {
|
347 | * "StringEquals": {
|
348 | * "kms:ViaService": "ec2.<Region>.amazonaws.com", (eg: ec2.us-east-1.amazonaws.com)
|
349 | * "kms:CallerAccount": "0000000000" (your account ID)
|
350 | * }
|
351 | * }
|
352 | * }
|
353 | *
|
354 | * @default The default KMS key for the account, region, and EC2 service is used.
|
355 | */
|
356 | readonly encryptionKey?: IKey;
|
357 | /**
|
358 | * Indicates whether the volume is auto-enabled for I/O operations. By default, Amazon EBS disables I/O to the volume from attached EC2
|
359 | * instances when it determines that a volume's data is potentially inconsistent. If the consistency of the volume is not a concern, and
|
360 | * you prefer that the volume be made available immediately if it's impaired, you can configure the volume to automatically enable I/O.
|
361 | *
|
362 | * @default false
|
363 | */
|
364 | readonly autoEnableIo?: boolean;
|
365 | /**
|
366 | * The type of the volume; what type of storage to use to form the EBS Volume.
|
367 | *
|
368 | * @default {@link EbsDeviceVolumeType.GENERAL_PURPOSE_SSD}
|
369 | */
|
370 | readonly volumeType?: EbsDeviceVolumeType;
|
371 | /**
|
372 | * 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,
|
373 | * and 500 IOPS/GiB for both PROVISIONED_IOPS_SSD_IO2 and GENERAL_PURPOSE_SSD_GP3.
|
374 | * See {@link https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ec2-ebs-volume.html}
|
375 | * for more information.
|
376 | *
|
377 | * This parameter is valid only for PROVISIONED_IOPS_SSD, PROVISIONED_IOPS_SSD_IO2 and GENERAL_PURPOSE_SSD_GP3 volumes.
|
378 | *
|
379 | * @default None -- Required for io1 and io2 volumes. The default for gp3 volumes is 3,000 IOPS if omitted.
|
380 | */
|
381 | readonly iops?: number;
|
382 | /**
|
383 | * Policy to apply when the volume is removed from the stack
|
384 | *
|
385 | * @default RemovalPolicy.RETAIN
|
386 | */
|
387 | readonly removalPolicy?: RemovalPolicy;
|
388 | }
|
389 | /**
|
390 | * Attributes required to import an existing EBS Volume into the Stack.
|
391 | */
|
392 | export interface VolumeAttributes {
|
393 | /**
|
394 | * The EBS Volume's ID
|
395 | */
|
396 | readonly volumeId: string;
|
397 | /**
|
398 | * The availability zone that the EBS Volume is contained within (ex: us-west-2a)
|
399 | */
|
400 | readonly availabilityZone: string;
|
401 | /**
|
402 | * The customer-managed encryption key that is used to encrypt the Volume.
|
403 | *
|
404 | * @default None -- The EBS Volume is not using a customer-managed KMS key for encryption.
|
405 | */
|
406 | readonly encryptionKey?: IKey;
|
407 | }
|
408 | /**
|
409 | * Common behavior of Volumes. Users should not use this class directly, and instead use ``Volume``.
|
410 | */
|
411 | declare abstract class VolumeBase extends Resource implements IVolume {
|
412 | abstract readonly volumeId: string;
|
413 | abstract readonly availabilityZone: string;
|
414 | abstract readonly encryptionKey?: IKey;
|
415 | grantAttachVolume(grantee: IGrantable, instances?: IInstance[]): Grant;
|
416 | grantAttachVolumeByResourceTag(grantee: IGrantable, constructs: Construct[], tagKeySuffix?: string): Grant;
|
417 | grantDetachVolume(grantee: IGrantable, instances?: IInstance[]): Grant;
|
418 | grantDetachVolumeByResourceTag(grantee: IGrantable, constructs: Construct[], tagKeySuffix?: string): Grant;
|
419 | private collectGrantResourceArns;
|
420 | private calculateResourceTagValue;
|
421 | }
|
422 | /**
|
423 | * Creates a new EBS Volume in AWS EC2.
|
424 | */
|
425 | export declare class Volume extends VolumeBase {
|
426 | /**
|
427 | * Import an existing EBS Volume into the Stack.
|
428 | *
|
429 | * @param scope the scope of the import.
|
430 | * @param id the ID of the imported Volume in the construct tree.
|
431 | * @param attrs the attributes of the imported Volume
|
432 | */
|
433 | static fromVolumeAttributes(scope: Construct, id: string, attrs: VolumeAttributes): IVolume;
|
434 | readonly volumeId: string;
|
435 | readonly availabilityZone: string;
|
436 | readonly encryptionKey?: IKey;
|
437 | constructor(scope: Construct, id: string, props: VolumeProps);
|
438 | protected validateProps(props: VolumeProps): void;
|
439 | }
|
440 | export {};
|