From 3f76089f0805882ce5aac04d52ef76522a2eba9b Mon Sep 17 00:00:00 2001 From: Guillaume Boutry Date: Fri, 6 Mar 2026 20:24:54 +0100 Subject: [PATCH] Document manifest and storage backend operations Signed-off-by: Guillaume Boutry --- .custom_wordlist.txt | 1 + .../deploy-pure-storage-backend.rst | 81 +++++++++++++ .../enable-a-gated-storage-backend.rst | 106 ++++++++++++++++++ how-to/operations/index.rst | 2 + reference/manifest-file-reference.rst | 47 ++++++++ 5 files changed, 237 insertions(+) create mode 100644 how-to/operations/deploy-pure-storage-backend.rst create mode 100644 how-to/operations/enable-a-gated-storage-backend.rst diff --git a/.custom_wordlist.txt b/.custom_wordlist.txt index f4d465d..76ba7d9 100644 --- a/.custom_wordlist.txt +++ b/.custom_wordlist.txt @@ -128,6 +128,7 @@ auth balancers balancer's backend +backends backport backported br diff --git a/how-to/operations/deploy-pure-storage-backend.rst b/how-to/operations/deploy-pure-storage-backend.rst new file mode 100644 index 0000000..5b12f26 --- /dev/null +++ b/how-to/operations/deploy-pure-storage-backend.rst @@ -0,0 +1,81 @@ +Deploy a Pure Storage backend +============================= + +Overview +-------- + +Use this procedure to deploy a Pure Storage backend for Cinder. The backend is +deployed as the ``cinder-volume-purestorage`` charm. + +Requirements +------------ + +You will need: + +* a bootstrapped Canonical OpenStack deployment with storage capability already + in place +* network connectivity from the storage nodes to the Pure Storage array +* a valid Pure Storage API token +* a backend instance name that satisfies Juju application naming rules, + for example ``pure-prod`` + +Inspect the available options +----------------------------- + +If you want to review the supported configuration keys before deploying the +backend, run: + +.. code-block:: text + + sunbeam storage options purestorage + +Create the backend configuration +-------------------------------- + +You can provide the backend settings in a YAML file or pass the equivalent CLI +options directly to the deployment command. The required keys are ``san-ip`` +and ``pure-api-token``. + +For example, create a file named ``purestorage.yaml`` with the following +content: + +.. code-block:: yaml + + san-ip: 192.0.2.10 + pure-api-token: 01234567-89ab-cdef-0123-456789abcdef + protocol: iscsi + volume-backend-name: pure-iscsi + backend-availability-zone: az1 + pure-iscsi-cidr: 192.0.2.0/24 + +Set ``protocol`` to ``iscsi``, ``fc``, or ``nvme`` to match your deployment. +For NVMe/TCP deployments, you can also set ``pure-nvme-cidr`` and +``pure-nvme-transport``. Set ``pure-nvme-transport`` to ``tcp``. + +Deploy the backend +------------------ + +Deploy the backend with the backend type (``purestorage``), a +Juju-compatible backend instance name, and the configuration file: + +.. code-block:: text + + sunbeam storage add purestorage pure-prod --config-file purestorage.yaml + +If you prefer not to use a file, pass the equivalent options directly on the +command line. + +Verify the backend +------------------ + +Check that the backend has been added: + +.. code-block:: text + + sunbeam storage list + +To inspect the deployed backend in more detail, run: + +.. code-block:: text + + sunbeam storage show pure-prod diff --git a/how-to/operations/enable-a-gated-storage-backend.rst b/how-to/operations/enable-a-gated-storage-backend.rst new file mode 100644 index 0000000..eeaec4a --- /dev/null +++ b/how-to/operations/enable-a-gated-storage-backend.rst @@ -0,0 +1,106 @@ +Enable and deploy a gated storage backend +========================================= + +Use this procedure to unlock a gated in-tree storage backend in the CLI and +then deploy it. For general information about feature gates, see +:doc:`Manage experimental features `. + +.. note:: + + Pure Storage is generally available and does not require a feature gate. + Add it directly with ``sunbeam storage add purestorage ...``. + +List the available feature gates +-------------------------------- + +List the gates that are available in your deployment: + +.. code:: text + + sunbeam list-feature-gates + +Identify the gate key for the storage backend that you want to deploy. Current +gated in-tree storage backends use keys such as +``feature.storage.dellsc`` and ``feature.storage.hitachi``. + +Enable the storage backend gate +------------------------------- + +Unlock the backend by setting its feature gate to ``true``: + +.. code:: text + + sudo snap set openstack feature.storage.=true + +Replace ```` with the storage backend name, for example +``dellsc`` or ``hitachi``. + +.. note:: + + Unlocking the gate makes the backend visible in the CLI. It does not deploy + the backend. + +Verify that the backend is unlocked +----------------------------------- + +Run the feature gate command again and confirm that the **Unlocked** column is +set for your storage backend: + +.. code:: text + + sunbeam list-feature-gates + +If the backend does not appear immediately in the CLI, start a new command +invocation and check again. + +In local multi-node deployments, gate changes propagate automatically across +nodes in roughly 5 to 10 seconds. In MAAS deployments, you may need to run the +same ``snap set`` command on each node even though the gate state is still +stored in the cluster database. + +Review the backend options in the CLI +--------------------------------------- + +After the gate is unlocked, confirm that the backend is now exposed by +the storage commands: + +.. code:: text + + sunbeam storage add --help + +or: + +.. code:: text + + sunbeam storage options + +Use ``sunbeam storage options `` to review the configuration fields +required by the backend before you create its YAML configuration file. + +Deploy the backend +------------------ + +Add the backend by using the backend type, an instance name, and a backend +configuration file: + +.. code:: text + + sunbeam storage add --config-file .yaml + +For example, to deploy a Hitachi backend: + +.. code:: text + + sunbeam storage add hitachi hitachi-prod --config-file hitachi.yaml + +Verify the deployment +--------------------- + +List deployed storage backends and confirm that the new backend is present: + +.. code:: text + + sunbeam storage list + +Once deployed, the backend remains managed separately from the feature gate +state. diff --git a/how-to/operations/index.rst b/how-to/operations/index.rst index 007ed03..debccd0 100644 --- a/how-to/operations/index.rst +++ b/how-to/operations/index.rst @@ -5,6 +5,8 @@ Operations :maxdepth: 2 cluster-upgrades + deploy-pure-storage-backend + enable-a-gated-storage-backend live-migration maintenance-mode manage-experimental-features diff --git a/reference/manifest-file-reference.rst b/reference/manifest-file-reference.rst index 9907bcd..7a040e4 100644 --- a/reference/manifest-file-reference.rst +++ b/reference/manifest-file-reference.rst @@ -406,3 +406,50 @@ manifest file will all its supported keys. # Base64 encoded certificate for unit CSR Unique ID: subject certificate: ... + storage: + + # Storage is keyed by backend type, then by instance name. + # Current backend types are dellsc, hitachi, and purestorage. + dellsc: + : + config: + san-ip: + san-username: + san-password: + protocol: [fc, iscsi] + # Shared storage config fields. + volume-backend-name: + backend-availability-zone: + # Additional Dell Storage Center options also use kebab-case. + # Same structure as core.software. + software: {} + + hitachi: + : + config: + hitachi-storage-id: + hitachi-pools: ,,... + san-ip: + san-username: + san-password: + protocol: [fc, iscsi] + volume-backend-name: + backend-availability-zone: + # Additional Hitachi options also use kebab-case. + # Same structure as core.software. + software: {} + + purestorage: + : + config: + san-ip: + pure-api-token: + protocol: [iscsi, fc, nvme] + pure-iscsi-cidr: + pure-nvme-cidr: + pure-nvme-transport: tcp + volume-backend-name: + backend-availability-zone: + # Additional Pure Storage options also use kebab-case. + # Same structure as core.software. + software: {}