volumes

Creates, updates, deletes or gets a volume resource or lists volumes in a region

Overview

Name	`volumes`
Type	Resource
Description	Specifies an Amazon Elastic Block Store (Amazon EBS) volume. When you use CFNlong to update an Amazon EBS volume that modifies ``Iops``, ``Size``, or ``VolumeType``, there is a cooldown period before another operation can occur. This can cause your stack to report being in ``UPDATE_IN_PROGRESS`` or ``UPDATE_ROLLBACK_IN_PROGRESS`` for long periods of time. Amazon EBS does not support sizing down an Amazon EBS volume. CFNlong does not attempt to modify an Amazon EBS volume to a smaller size on rollback. Some common scenarios when you might encounter a cooldown period for Amazon EBS include: + You successfully update an Amazon EBS volume and the update succeeds. When you attempt another update within the cooldown window, that update will be subject to a cooldown period. + You successfully update an Amazon EBS volume and the update succeeds but another change in your ``update-stack`` call fails. The rollback will be subject to a cooldown period. For more information, see [Requirements for EBS volume modifications](https://docs.aws.amazon.com/ebs/latest/userguide/modify-volume-requirements.html). DeletionPolicy attribute To control how CFNlong handles the volume when the stack is deleted, set a deletion policy for your volume. You can choose to retain the volume, to delete the volume, or to create a snapshot of the volume. For more information, see [DeletionPolicy attribute](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-attribute-deletionpolicy.html). If you set a deletion policy that creates a snapshot, all tags on the volume are included in the snapshot.
Id	`awscc.ec2.volumes`

Fields

get (all properties)
list (identifiers only)

Name	Datatype	Description
`multi_attach_enabled`	`boolean`	Indicates whether Amazon EBS Multi-Attach is enabled.<br />CFNlong does not currently support updating a single-attach volume to be multi-attach enabled, updating a multi-attach enabled volume to be single-attach, or updating the size or number of I/O operations per second (IOPS) of a multi-attach enabled volume.
`kms_key_id`	`string`	The identifier of the kms-key-long to use for Amazon EBS encryption. If ``KmsKeyId`` is specified, the encrypted state must be ``true``.<br />If you omit this property and your account is enabled for encryption by default, or Encrypted is set to ``true``, then the volume is encrypted using the default key specified for your account. If your account does not have a default key, then the volume is encrypted using the aws-managed-key.<br />Alternatively, if you want to specify a different key, you can specify one of the following:<br />+ Key ID. For example, 1234abcd-12ab-34cd-56ef-1234567890ab.<br />+ Key alias. Specify the alias for the key, prefixed with ``alias/``. For example, for a key with the alias ``my_cmk``, use ``alias/my_cmk``. Or to specify the aws-managed-key, use ``alias/aws/ebs``.<br />+ Key ARN. For example, arn:aws:kms:us-east-1:012345678910:key/1234abcd-12ab-34cd-56ef-1234567890ab.<br />+ Alias ARN. For example, arn:aws:kms:us-east-1:012345678910:alias/ExampleAlias.
`encrypted`	`boolean`	Indicates 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/ebs/latest/userguide/work-with-ebs-encr.html#encryption-by-default) in the Amazon EBS User Guide.<br />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/ebs/latest/userguide/ebs-encryption-requirements.html#ebs-encryption_supported_instances).
`size`	`integer`	The size of the volume, in GiBs. You must specify either a snapshot ID or a volume size. If you specify a snapshot, the default is the snapshot size. You can specify a volume size that is equal to or larger than the snapshot size.<br />The following are the supported volumes sizes for each volume type:<br />+ ``gp2`` and ``gp3``: 1 - 16,384 GiB<br />+ ``io1``: 4 - 16,384 GiB<br />+ ``io2``: 4 - 65,536 GiB<br />+ ``st1`` and ``sc1``: 125 - 16,384 GiB<br />+ ``standard``: 1 - 1024 GiB
`auto_enable_io`	`boolean`	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.
`outpost_arn`	`string`	The Amazon Resource Name (ARN) of the Outpost.
`availability_zone`	`string`	The ID of the Availability Zone in which to create the volume. For example, ``us-east-1a``.<br />Either ``AvailabilityZone`` or ``AvailabilityZoneId`` must be specified, but not both.
`throughput`	`integer`	The throughput to provision for a volume, with a maximum of 1,000 MiB/s.<br />This parameter is valid only for ``gp3`` volumes. The default value is 125.<br />Valid Range: Minimum value of 125. Maximum value of 1000.
`iops`	`integer`	The number of I/O operations per second (IOPS). For ``gp3``, ``io1``, and ``io2`` volumes, this represents the number of IOPS that are provisioned for the volume. For ``gp2`` volumes, this represents the baseline performance of the volume and the rate at which the volume accumulates I/O credits for bursting.<br />The following are the supported values for each volume type:<br />+ ``gp3``: 3,000 - 16,000 IOPS<br />+ ``io1``: 100 - 64,000 IOPS<br />+ ``io2``: 100 - 256,000 IOPS<br /><br />For ``io2`` volumes, you can achieve up to 256,000 IOPS on [instances built on the Nitro System](https://docs.aws.amazon.com/ec2/latest/instancetypes/ec2-nitro-instances.html). On other instances, you can achieve performance up to 32,000 IOPS.<br />This parameter is required for ``io1`` and ``io2`` volumes. The default for ``gp3`` volumes is 3,000 IOPS. This parameter is not supported for ``gp2``, ``st1``, ``sc1``, or ``standard`` volumes.
`volume_initialization_rate`	`integer`	Specifies the Amazon EBS Provisioned Rate for Volume Initialization (volume initialization rate), in MiB/s, at which to download the snapshot blocks from Amazon S3 to the volume. This is also known as volume initialization. Specifying a volume initialization rate ensures that the volume is initialized at a predictable and consistent rate after creation.<br />This parameter is supported only for volumes created from snapshots. Omit this parameter if:<br />+ You want to create the volume using fast snapshot restore. You must specify a snapshot that is enabled for fast snapshot restore. In this case, the volume is fully initialized at creation.<br />If you specify a snapshot that is enabled for fast snapshot restore and a volume initialization rate, the volume will be initialized at the specified rate instead of fast snapshot restore.<br />+ You want to create a volume that is initialized at the default rate.<br /><br />For more information, see [Initialize Amazon EBS volumes](https://docs.aws.amazon.com/ebs/latest/userguide/initalize-volume.html) in the Amazon EC2 User Guide.<br />Valid range: 100 - 300 MiB/s
`snapshot_id`	`string`	The snapshot from which to create the volume. You must specify either a snapshot ID or a volume size.
`volume_id`	`string`
`volume_type`	`string`	The volume type. This parameter can be one of the following values:<br />+ General Purpose SSD: ``gp2`` \| ``gp3``<br />+ Provisioned IOPS SSD: ``io1`` \| ``io2``<br />+ Throughput Optimized HDD: ``st1``<br />+ Cold HDD: ``sc1``<br />+ Magnetic: ``standard``<br /><br />For more information, see [Amazon EBS volume types](https://docs.aws.amazon.com/ebs/latest/userguide/ebs-volume-types.html).<br />Default: ``gp2``
▶`tags`	`array`	The tags to apply to the volume during creation.
`region`	`string`	AWS region.

Name	Datatype	Description
`volume_id`	`string`
`region`	`string`	AWS region.

For more information, see AWS::EC2::Volume.

Methods

Name	Resource	Accessible by	Required Params
`create_resource`	`volumes`	`INSERT`	`AvailabilityZone, region`
`delete_resource`	`volumes`	`DELETE`	`Identifier, region`
`update_resource`	`volumes`	`UPDATE`	`Identifier, PatchDocument, region`
`list_resources`	`volumes_list_only`	`SELECT`	`region`
`get_resource`	`volumes`	`SELECT`	`Identifier, region`

`SELECT` examples

get (all properties)
list (identifiers only)

Gets all properties from an individual volume.

SELECT
  region,
  multi_attach_enabled,
  kms_key_id,
  encrypted,
  size,
  auto_enable_io,
  outpost_arn,
  availability_zone,
  throughput,
  iops,
  volume_initialization_rate,
  snapshot_id,
  volume_id,
  volume_type,
  tags
FROM awscc.ec2.volumes
WHERE
  region = 'us-east-1' AND
  Identifier = '{{ volume_id }}';

Lists all volumes in a region.

SELECT
  region,
  volume_id
FROM awscc.ec2.volumes_list_only
WHERE
  region = 'us-east-1';

`INSERT` example

Use the following StackQL query and manifest file to create a new volume resource, using stack-deploy.

Required Properties
All Properties
Manifest

/*+ create */
INSERT INTO awscc.ec2.volumes (
  AvailabilityZone,
  region
)
SELECT
  '{{ availability_zone }}',
  '{{ region }}';

/*+ create */
INSERT INTO awscc.ec2.volumes (
  MultiAttachEnabled,
  KmsKeyId,
  Encrypted,
  Size,
  AutoEnableIO,
  OutpostArn,
  AvailabilityZone,
  Throughput,
  Iops,
  VolumeInitializationRate,
  SnapshotId,
  VolumeType,
  Tags,
  region
)
SELECT
  '{{ multi_attach_enabled }}',
  '{{ kms_key_id }}',
  '{{ encrypted }}',
  '{{ size }}',
  '{{ auto_enable_io }}',
  '{{ outpost_arn }}',
  '{{ availability_zone }}',
  '{{ throughput }}',
  '{{ iops }}',
  '{{ volume_initialization_rate }}',
  '{{ snapshot_id }}',
  '{{ volume_type }}',
  '{{ tags }}',
  '{{ region }}';

version: 1
name: stack name
description: stack description
providers:
  - aws
globals:
  - name: region
    value: '{{ vars.AWS_REGION }}'
resources:
  - name: volume
    props:
      - name: multi_attach_enabled
        value: '{{ multi_attach_enabled }}'
      - name: kms_key_id
        value: '{{ kms_key_id }}'
      - name: encrypted
        value: '{{ encrypted }}'
      - name: size
        value: '{{ size }}'
      - name: auto_enable_io
        value: '{{ auto_enable_io }}'
      - name: outpost_arn
        value: '{{ outpost_arn }}'
      - name: availability_zone
        value: '{{ availability_zone }}'
      - name: throughput
        value: '{{ throughput }}'
      - name: iops
        value: '{{ iops }}'
      - name: volume_initialization_rate
        value: '{{ volume_initialization_rate }}'
      - name: snapshot_id
        value: '{{ snapshot_id }}'
      - name: volume_type
        value: '{{ volume_type }}'
      - name: tags
        value:
          - key: '{{ key }}'
            value: '{{ value }}'

`UPDATE` example

Use the following StackQL query and manifest file to update a volume resource, using stack-deploy.

/*+ update */
UPDATE awscc.ec2.volumes
SET PatchDocument = string('{{ {
    "MultiAttachEnabled": multi_attach_enabled,
    "KmsKeyId": kms_key_id,
    "Encrypted": encrypted,
    "Size": size,
    "AutoEnableIO": auto_enable_io,
    "OutpostArn": outpost_arn,
    "AvailabilityZone": availability_zone,
    "Throughput": throughput,
    "Iops": iops,
    "VolumeInitializationRate": volume_initialization_rate,
    "SnapshotId": snapshot_id,
    "VolumeType": volume_type,
    "Tags": tags
} | generate_patch_document }}')
WHERE
  region = '{{ region }}' AND
  Identifier = '{{ volume_id }}';

`DELETE` example

/*+ delete */
DELETE FROM awscc.ec2.volumes
WHERE
  Identifier = '{{ volume_id }}' AND
  region = 'us-east-1';

Permissions

To operate on the volumes resource, the following permissions are required:

Read
Create
Update
List
Delete

ec2:DescribeVolumes,
ec2:DescribeVolumeAttribute,
ec2:DescribeTags

ec2:CreateVolume,
ec2:DescribeVolumes,
ec2:DescribeVolumeAttribute,
ec2:ModifyVolumeAttribute,
ec2:CreateTags,
kms:GenerateDataKeyWithoutPlaintext,
kms:CreateGrant

ec2:ModifyVolume,
ec2:ModifyVolumeAttribute,
ec2:DescribeVolumeAttribute,
ec2:DescribeVolumesModifications,
ec2:DescribeVolumes,
ec2:CreateTags,
ec2:DeleteTags

ec2:DescribeVolumes,
ec2:DescribeTags,
ec2:DescribeVolumeAttribute

ec2:DeleteVolume,
ec2:CreateSnapshot,
ec2:DescribeSnapshots,
ec2:DeleteTags,
ec2:DescribeVolumes

Overview​

Fields​

Methods​

SELECT examples​

INSERT example​

UPDATE example​

DELETE example​

Permissions​