From 54b2926f9e4b65241a256bb529226aefaa373f8b Mon Sep 17 00:00:00 2001
From: Florian Haas <florian@cleura.com>
Date: Thu, 2 May 2024 11:11:57 +0200
Subject: [PATCH] feat: Add reference information for volume types, fix related
 howto

In the reference section, add a new subsection about volume types.
Explain the cbs and cbs-encrypted volume types, their encryption
support, and quality-of-service (QoS) caps.

In addition, update the volume encryption how-to guide to also refer
to the updated type names.
---
 docs/howto/openstack/cinder/encrypted-volumes.md | 10 +++++-----
 docs/reference/.pages                            |  1 +
 docs/reference/index.md                          |  2 ++
 docs/reference/volumes/index.md                  | 15 +++++++++++++++
 4 files changed, 23 insertions(+), 5 deletions(-)
 create mode 100644 docs/reference/volumes/index.md

diff --git a/docs/howto/openstack/cinder/encrypted-volumes.md b/docs/howto/openstack/cinder/encrypted-volumes.md
index 7f2ab222a..da232e1b6 100644
--- a/docs/howto/openstack/cinder/encrypted-volumes.md
+++ b/docs/howto/openstack/cinder/encrypted-volumes.md
@@ -20,9 +20,9 @@ $ openstack volume type list
 +--------------------------------------+-----------------------+-----------+
 | ID                                   | Name                  | Is Public |
 +--------------------------------------+-----------------------+-----------+
-| a479a6b0-b283-41a5-b38b-5b08e7f902ca | volumes_hdd_encrypted | True      |
+| a479a6b0-b283-41a5-b38b-5b08e7f902ca | cbs-encrypted         | True      |
 | d9dfa98a-238d-4ca0-9abf-701fceb05623 | __DEFAULT__           | True      |
-| 86796611-fb12-4628-b6b1-e09469e301d7 | volumes_hdd           | True      |
+| 86796611-fb12-4628-b6b1-e09469e301d7 | cbs                   | True      |
 +--------------------------------------+-----------------------+-----------+
 ```
 
@@ -31,12 +31,12 @@ $ openstack volume type list
 
 To create a volume with encryption, you need to explicitly specify the
 `--type` option to the `openstack volume create` command. The
-following example creates a volume using the `volumes_hdd_encrypted`
+following example creates a volume using the `cbs-encrypted`
 type, naming it `enc_drive` and setting its size to 10 GiB:
 
 ```console
 $ openstack volume create \
-  --type volumes_hdd_encrypted \
+  --type cbs-encrypted \
   --size 10 \
   enc_drive
 +---------------------+--------------------------------------+
@@ -58,7 +58,7 @@ $ openstack volume create \
 | snapshot_id         | None                                 |
 | source_volid        | None                                 |
 | status              | creating                             |
-| type                | volumes_hdd_encrypted                |
+| type                | cbs-encrypted                        |
 | updated_at          | None                                 |
 | user_id             | 966ad341f4e14920b5f589f900246ccc     |
 +---------------------+--------------------------------------+
diff --git a/docs/reference/.pages b/docs/reference/.pages
index 1643abc5f..618f95f0d 100644
--- a/docs/reference/.pages
+++ b/docs/reference/.pages
@@ -4,6 +4,7 @@ nav:
   - features
   - limitations
   - flavors
+  - volumes
   - images
   - quotas
   - versions
diff --git a/docs/reference/index.md b/docs/reference/index.md
index beaf719d2..9c9c09ab8 100644
--- a/docs/reference/index.md
+++ b/docs/reference/index.md
@@ -11,6 +11,8 @@ It serves to provide general reference information about {{brand}} services.
 
 * The **[Flavors](flavors/index.md)** reference explains our naming convention for pre-defined CPU/RAM/disk configurations ("flavors") for server instances, and their availability across {{brand}} regions.
 
+* The **[Volume Types](volumes/index.md)** reference lists the available persistent block storage ("volume") types.
+
 * Our **[Service Version Matrix](versions/index.md)** lists the open source software versions running in our {{brand}} regions.
 
 ## API reference
diff --git a/docs/reference/volumes/index.md b/docs/reference/volumes/index.md
new file mode 100644
index 000000000..bfe0a855a
--- /dev/null
+++ b/docs/reference/volumes/index.md
@@ -0,0 +1,15 @@
+# Volume types
+
+The following volume types are available in {{brand}} for persistent block storage devices ("volumes") managed by OpenStack Cinder.
+
+If you create a volume without specifying a volume type, then the default volume type applies.
+
+The maximum IOPS specification is essentially a cap, which creates an upper bound for individual device performance under *ideal* conditions.
+Actual IOPS may vary based on system load and utilization.
+
+| Volume type name               | Default          | [Encryption](../../howto/openstack/cinder/encrypted-volumes.md) | max IOPS |
+| ------------------------------ | -----            | -----                                                           | -----    |
+| `cbs`                          | :material-check: | :material-close:                                                | 10000    |
+| `cbs-encrypted`                | :material-close: | :material-check:                                                | 10000    |
+
+It is possible --- though somewhat involved --- to [change the type of an existing volume](../../howto/openstack/cinder/retype-volumes.md) (also known as retyping).