From 338c0397e829f801f6ac6808ddcf67ac23f8555f Mon Sep 17 00:00:00 2001
From: Will Szumski <will@stackhpc.com>
Date: Tue, 2 Jun 2026 12:43:52 +0100
Subject: [PATCH 1/2] Advice for database backups when using Ceph

---
 doc/source/_static/custom.css                 |  6 ++++++
 doc/source/conf.py                            |  3 ++-
 doc/source/operations/database-backups.rst    | 20 +++++++++++++++++++
 .../tools/upload-database-backup-s3.yml       |  2 ++
 4 files changed, 30 insertions(+), 1 deletion(-)
 create mode 100644 doc/source/_static/custom.css

diff --git a/doc/source/_static/custom.css b/doc/source/_static/custom.css
new file mode 100644
index 0000000000..9af7a77ba2
--- /dev/null
+++ b/doc/source/_static/custom.css
@@ -0,0 +1,6 @@
+/* Opt-in wrapping for selected code blocks only. */
+.wrap-long-lines pre {
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  word-break: break-word;
+}
diff --git a/doc/source/conf.py b/doc/source/conf.py
index a6376d3018..e79076178a 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -91,7 +91,8 @@
 # Sphinx are currently 'default' and 'sphinxdoc'.
 # html_theme_path = []
 html_theme = 'sphinx_immaterial'
-# html_static_path = ['static']
+html_static_path = ['_static']
+html_css_files = ['custom.css']
 
 # Add any paths that contain "extra" files, such as .htaccess or
 # robots.txt.
diff --git a/doc/source/operations/database-backups.rst b/doc/source/operations/database-backups.rst
index cff58a3654..2395179cab 100644
--- a/doc/source/operations/database-backups.rst
+++ b/doc/source/operations/database-backups.rst
@@ -24,6 +24,10 @@ These should be set as follows:
 
    s3_mariadb_backup_url: "<s3-endpoint>"
    s3_mariadb_backup_bucket: "<s3-bucket-name>"
+   # Optional. Set when the target is a Ceph S3 endpoint.
+   s3_mariadb_backup_s3_is_ceph: true
+   # Optional. Set to false when server-side encryption is unsupported.
+   s3_mariadb_backup_encrypt: false
 
 .. code-block:: yaml
    :caption: ``$KAYOBE_CONFIG_PATH/environments/$KAYOBE_ENVIRONMENT/secrets.yml``
@@ -31,6 +35,22 @@ These should be set as follows:
    secrets_s3_mariadb_backup_access_key: "<s3-access-key>"
    secrets_s3_mariadb_backup_secret_key: "<s3-secret-access-key"
 
+.. note::
+
+   If backing up to a Ceph cluster that does not support `server-side encryption
+   <https://docs.ceph.com/en/latest/radosgw/encryption/>`__, set:
+
+   .. code-block:: yaml
+
+      s3_mariadb_backup_encrypt: false
+
+   The characteristic error message if encryption is enabled but unsupported is:
+
+   .. code-block:: text
+      :class: wrap-long-lines
+
+      msg: 'Unable to complete PUT operation.: Failed to upload /var/lib/docker/volumes/mariadb_backup/_data/mysqlbackup-29-10-2024-1730194327.qp.xbc.xbs.gz to mybucket/mysqlbackup-29-10-2024-1730194327.qp.xbc.xbs.gz: An error occurred (InvalidRequest) when calling the CreateMultipartUpload operation: Unknown'
+
 You may also want to hook this to run after ``kayobe overcloud database
 backup``:
 
diff --git a/etc/kayobe/ansible/tools/upload-database-backup-s3.yml b/etc/kayobe/ansible/tools/upload-database-backup-s3.yml
index 5efd4c72a5..98377c8bda 100644
--- a/etc/kayobe/ansible/tools/upload-database-backup-s3.yml
+++ b/etc/kayobe/ansible/tools/upload-database-backup-s3.yml
@@ -30,6 +30,8 @@
         object: "{{ item.path | basename }}"
         src: "{{ item.path }}"
         mode: put
+        ceph: "{{ s3_mariadb_backup_s3_is_ceph | default(omit) }}"
+        encrypt: "{{ s3_mariadb_backup_encrypt | default(omit) }}"
         overwrite: different
         validate_certs: False
       become: True

From 200c91665d56cd7b3816749364da2b987211ee00 Mon Sep 17 00:00:00 2001
From: Will Szumski <will@stackhpc.com>
Date: Tue, 2 Jun 2026 13:57:30 +0100
Subject: [PATCH 2/2] Address gemini code review comments

---
 doc/source/operations/database-backups.rst | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/doc/source/operations/database-backups.rst b/doc/source/operations/database-backups.rst
index 2395179cab..02ab7a6f9a 100644
--- a/doc/source/operations/database-backups.rst
+++ b/doc/source/operations/database-backups.rst
@@ -37,8 +37,7 @@ These should be set as follows:
 
 .. note::
 
-   If backing up to a Ceph cluster that does not support `server-side encryption
-   <https://docs.ceph.com/en/latest/radosgw/encryption/>`__, set:
+   If backing up to a Ceph cluster that does not support :ceph-doc:`server-side encryption <radosgw/encryption/>`, set:
 
    .. code-block:: yaml