chore(aws): start and stop instances with encrypted ebs volumes

.ansible-lint

@@ -3,6 +3,7 @@
 
 offline: true
 warn_list:
-  - 'name[template]'   # Jinja templates should only be at the end of 'name' -- oh come on!
+  - name[template]   # Jinja templates should only be at the end of 'name' -- oh come on!
-  - 'role-name[path]'  # Avoid using paths when importing roles -- yeah, need for testing
+  - role-name[path]  # Avoid using paths when importing roles -- yeah, need for testing
+  - yaml[comments-indentation]
   - package-latest

.markdownlint.yaml

@@ -9,6 +9,7 @@ MD013:  # line-length
   code_blocks: false
 MD033:  # no-inline-html
   allowed_elements:
+    - b
     - br
     - code
     - details

knowledge base/cloud computing/aws/ebs.md

@@ -4,6 +4,7 @@ Persistent [block storage][what is block storage?] for [EC2 Instances][ec2].
 
 1. [TL;DR](#tldr)
 1. [Snapshots](#snapshots)
+1. [Encryption](#encryption)
 1. [Further readings](#further-readings)
    1. [Sources](#sources)
 
@@ -53,6 +54,81 @@ When archived, incremental snapshots are converted to **full snapshots** and mov
 When access to archived snapshots is needed, they need to be restored to the standard tier before use. Restoring can
 take **up to 72h**.
 
+## Encryption
+
+Refer [How Amazon EBS encryption works].
+
+One can encrypt both boot and data volumes.
+
+At the time of writing, only **symmetric** keys are supported.
+
+Volumes attached to supported instance types encrypt the following types of data:
+
+- Data **at rest** inside the volume.
+- Data moving between the volume and the attached instance.
+- Snapshots created from the volume.
+- Volumes created from said snapshots.
+
+Volumes are encrypted with a AES-256 data key.<br/>
+The key is:
+
+1. Generated by KMS.
+1. Encrypted by KMS with another KMS-managed key.
+1. Stored with the volume's information.
+
+EBS automatically creates a unique AWS-managed key in **each** Region where one creates EBS resources, using the
+`aws/ebs` alias. EBS then uses this KMS key for encryption by default.<br/>
+Alternatively, one can use a **symmetric** customer managed encryption key of one's own creation.
+
+EC2 integrates with KMS to encrypt and decrypt EBS volumes in ways that differ depending on whether the original
+snapshot for encrypted volumes is itself encrypted or unencrypted.
+
+<details>
+  <summary>The original snapshot is <b>encrypted</b></summary>
+
+1. EC2 sends a `GenerateDataKeyWithoutPlaintext` request to KMS specifying the KMS key for volume encryption.
+1. If the volume is encrypted using the same key as the snapshot, KMS encrypts that key using that same data key as
+   the snapshot.<br/>
+   If the volume is encrypted using a different KMS key, KMS generates a new data key and encrypts it using the
+   specified key. The encrypted data key is then sent to EBS to be stored with the volume metadata.
+1. When attaching the encrypted volume to an instance, EC2 sends a `CreateGrant` request to KMS to be allowed to
+   decrypt the data key.
+1. KMS decrypts the encrypted data key and sends the decrypted data key to EC2.
+1. EC2 uses the plaintext data key in the Nitro hardware to encrypt disk I/O to the volume.<br/>
+   The plaintext data key persists in memory as long as the volume is attached to the instance.
+
+</details>
+
+<details>
+  <summary>The original snapshot is <b>not</b> encrypted</summary>
+
+1. EC2 sends a `CreateGrant` request to KMS to be allowed to encrypt the volume that is being created from the snapshot.
+1. EC2 sends a `GenerateDataKeyWithoutPlaintext` request to KMS specifying the key chosen for volume encryption.
+1. KMS generates a new data key, encrypts it using the specified key, and sends the encrypted data key to EBS to be
+   stored with the volume metadata.
+1. EC2 sends a `Decrypt` request to KMS to decrypt the encrypted data key, which it then uses to encrypt the volume's
+   data.
+1. When attaching the encrypted volume to an instance, EC2 sends:
+
+   1. A `CreateGrant` request to KMS to be allowed to decrypt the data key.
+   1. A `Decrypt` request to KMS specifying the encrypted data key.
+
+1. KMS decrypts the encrypted data key and sends the decrypted data key back to EC2.
+1. EC2 uses the plaintext data key in the Nitro hardware to encrypt disk I/O to the volume.<br/>
+   The plaintext data key persists in memory as long as the volume is attached to the instance.
+
+When KMS keys become unusable, the effect is **almost immediately** subject to **eventual** consistency.<br/>
+The key state of the impacted KMS keys change to reflect their new condition, and all requests to use those keys in
+cryptographic operations fail.
+
+EC2 uses the **data** key, not the KMS key itself, to encrypt all disk I/O while a volume is attached to
+the instance. As such, there is **no** immediate effect on the EC2 instance or its attached EBS volumes when performing
+an action that makes a key unusable.<br/>
+When the encrypted EBS volume is detached from the instance, however, EBS removes the data key from the Nitro hardware.
+As such, the next time the encrypted EBS volume is attached to an EC2 instance the attachment will fail due EBS being
+unable to use the KMS key to decrypt the volume's encrypted data key. To use the EBS volume again, one must make the KMS
+key usable again.
+
 ## Further readings
 
 - [Amazon Web Services]
@@ -70,6 +146,7 @@ take **up to 72h**.
 - [`describe-volumes`][describe-volumes]
 - [`delete-volume`][delete-volume]
 - [How do I increase or decrease the size of my EBS volume?]
+- [How Amazon EBS encryption works]
 
 <!--
   Reference
@@ -89,6 +166,7 @@ take **up to 72h**.
 [describe-volumes]: https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-volumes.html
 [documentation]: https://docs.aws.amazon.com/ebs/
 [extend the file system after resizing an ebs volume]: https://docs.aws.amazon.com/ebs/latest/userguide/recognize-expanded-volume-linux.html
+[how amazon ebs encryption works]: https://docs.aws.amazon.com/ebs/latest/userguide/how-ebs-encryption-works.html
 [how do i increase or decrease the size of my ebs volume?]: https://repost.aws/knowledge-center/ebs-increase-decrease-volume-size
 [what is block storage?]: https://aws.amazon.com/what-is/block-storage/
 

knowledge base/cloud computing/aws/ec2.md

@@ -121,7 +121,7 @@ If the average CPU usage over a 24-hour period **exceeds** the baseline, instanc
 
 ## Disks
 
-Refer [EBS].
+Refer [EBS] and [Device names for volumes on Amazon EC2 instances].
 
 ## Metrics
 
@@ -209,6 +209,7 @@ TODO
 - [Using AL2023 based Amazon ECS AMIs to host containerized workloads]
 - [Announcing Amazon EC2 per second billing]
 - [How can I send memory and disk metrics from my EC2 instances to CloudWatch?]
+- [Device names for volumes on Amazon EC2 instances]
 
 ### Sources
 
@@ -250,6 +251,7 @@ TODO
 [create an ami from an amazon ec2 instance]: https://docs.aws.amazon.com/toolkit-for-visual-studio/latest/user-guide//tkv-create-ami-from-instance.html
 [describe-images]: https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-images.html
 [describeimages]: https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeImages.html
+[device names for volumes on amazon ec2 instances]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/device_naming.html
 [ec2 image builder]: https://docs.aws.amazon.com/imagebuilder/latest/userguide/what-is-image-builder.html
 [how can i send memory and disk metrics from my ec2 instances to cloudwatch?]: https://repost.aws/knowledge-center/cloudwatch-memory-metrics-ec2
 [how to clone instance ec2]: https://repost.aws/questions/QUOrWudF3vRL2Vqtrv0M9lfQ/how-to-clone-instance-ec2

snippets/aws/other commands.fish

@@ -112,6 +112,17 @@ TOKEN=$(curl -X PUT 'http://169.254.169.254/latest/api/token' -H 'X-aws-ec2-meta
 # IMDSv1
 curl 'http://169.254.169.254/latest/meta-data/iam/security-credentials/s3access'
 
+# Start stopped instances
+# Requires the 'ec2:StartInstances' permission for the instances
+# Also requires the 'kms:GenerateDataKeyWithoutPlaintext' and 'kms:CreateGrant' permissions for the keys used by the
+#   instances, if any.
+#   See https://docs.aws.amazon.com/ebs/latest/userguide/how-ebs-encryption-works.html#how-ebs-encryption-works-encrypted-snapshot
+aws ec2 start-instances --instance-ids 'i-0123456789abcdef0'
+
+# Stop started instances
+# Requires the 'ec2:StopInstances' permission for the instances
+aws ec2 stop-instances --instance-ids 'i-0123456789abcdef0'
+
 
 ###
 # ECR