Document GCS, Azure, IBM, and Oracle patch storage backends - #9
Merged
Merged
Conversation
Adds how-to pages for the four new patch storage backends (mirroring the existing S3 page), updates the patch storage overview and the platform configuration reference table with the new backends and options, and adds a guide for migrating patches between storage backends using rsync.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR extends the Livepatch Server documentation to cover additional object storage patch backends (GCS, Azure Blob Storage, IBM COS, OCI Object Storage), updates the platform configuration reference accordingly, and adds a guide for migrating patch data between supported storage backends.
Changes:
- Expanded the patch storage configuration reference with new backend types and their configuration options.
- Added new how-to pages for GCS, Azure, IBM COS, and OCI Object Storage patch storage backends.
- Added a migration guide for copying patch data between storage backends using
rsync/rclone, and updated patch storage index navigation.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/server/reference/platform/configuration.md | Adds new patch-storage backend types/options and expands S3 option descriptions. |
| docs/server/reference/patch-storage/use-oracle-for-patch-storage.md | New how-to page for OCI Object Storage as patch storage. |
| docs/server/reference/patch-storage/use-ibm-for-patch-storage.md | New how-to page for IBM COS as patch storage. |
| docs/server/reference/patch-storage/use-gcs-for-patch-storage.md | New how-to page for GCS as patch storage. |
| docs/server/reference/patch-storage/use-azure-for-patch-storage.md | New how-to page for Azure Blob Storage as patch storage. |
| docs/server/reference/patch-storage/migrating-patch-storage.md | New migration guide describing rsync/rclone-based patch migration. |
| docs/server/reference/patch-storage/index.md | Updates supported backend list and adds new pages to the toctree. |
| docs/.custom_wordlist.txt | Adds new storage/provider terms to the custom spelling wordlist. |
Suppressed comments (3)
docs/server/reference/platform/configuration.md:172
- These required-option references omit the
patch-storage.prefix, which makes them inconsistent with the rest of the table and harder to search for. Consider referencing the full option names.
| `patch-storage.azure-tenant-id` | Entra ID tenant ID, for explicit service principal auth (optional; requires `azure-client-id` and `azure-client-secret`). | `string` |
docs/server/reference/platform/configuration.md:169
- This description references
azure-connection-string, but the config key ispatch-storage.azure-connection-string. Using the full key name keeps references consistent within the table.
| `patch-storage.azure-account-name` | Azure storage account name (not required when `azure-connection-string` is set, which already carries the account name). | `string` |
docs/server/reference/platform/configuration.md:180
- The IBM option descriptions reference
ibm-api-key/ibm-access-keywithout thepatch-storage.prefix, but those shortened keys do not appear elsewhere in the config table. Using the fully-qualified keys avoids confusion.
| `patch-storage.ibm-access-key` | IBM COS HMAC access key (optional; see `ibm-api-key`). | `string` |
| `patch-storage.ibm-secret-key` | IBM COS HMAC secret key (optional; see `ibm-access-key`). | `string` |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.
Suppressed comments (8)
docs/server/reference/platform/configuration.md:162
- In the config reference, the cross-reference
s3-access-keydoes not match an actual configuration key name (the key ispatch-storage.s3-access-key). Using the full key name avoids confusion when readers copy/paste options.
| `patch-storage.s3-secret-key` | AWS secret key (optional; see `s3-access-key`). | `string` |
docs/server/reference/platform/configuration.md:182
- The IBM rows reference unqualified option names (e.g.
ibm-api-key,ibm-access-key) that don’t match the actual config keys in the table. This makes it harder to locate the referenced settings.
| `patch-storage.ibm-access-key` | IBM COS HMAC access key (optional; see `ibm-api-key`). | `string` |
| `patch-storage.ibm-secret-key` | IBM COS HMAC secret key (optional; see `ibm-access-key`). | `string` |
| `patch-storage.ibm-api-key` | IBM Cloud IAM API key (optional; defaults to the ambient VPC Instance Metadata Service). | `string` |
| `patch-storage.ibm-service-instance-id` | IBM COS resource instance ID, required when using `ibm-api-key`. | `string` |
docs/server/reference/platform/configuration.md:188
- The Oracle row references
oracle-config-file, but the actual config key name ispatch-storage.oracle-config-file. Using the full key name keeps the reference consistent with the rest of the table.
| `patch-storage.oracle-profile` | Profile to use within `oracle-config-file` (optional). | `string` |
docs/server/reference/patch-storage/migrating-patch-storage.md:12
- This sentence says “Every patch storage backend supported by Livepatch Server … stores patches as a flat set of files” but it omits the PostgreSQL backend (which is listed as supported elsewhere). Either include PostgreSQL (if applicable) or clarify that this statement is about the non-PostgreSQL/file-based backends.
Every patch storage backend supported by Livepatch Server (filesystem, S3, GCS, Azure, IBM, Oracle, Swift) stores patches as a flat set of files, each keyed by its filename. This means the same set of patch files works unmodified on any backend: migrating between backends is simply a matter of copying the patch files across, then updating [`patch-storage.type`](/server/reference/platform/configuration.md) and its associated options to point at the new backend.
docs/server/reference/platform/configuration.md:166
- The description references
gcs-credentials-file, but the actual key name ispatch-storage.gcs-credentials-file. Using the fully-qualified key name keeps the table unambiguous.
This issue also appears on line 188 of the same file.
| `patch-storage.gcs-credentials-json` | Inline service account JSON key (optional; see `gcs-credentials-file`). | `string` |
docs/server/reference/platform/configuration.md:173
- Several Azure rows reference unqualified option names (e.g.
azure-connection-string,azure-client-id). These names don’t exist as config keys in the table, so readers may not be able to find the correct settings.
This issue also appears on line 179 of the same file.
| `patch-storage.azure-account-name` | Azure storage account name (not required when `azure-connection-string` is set, which already carries the account name). | `string` |
| `patch-storage.azure-account-key` | Azure storage account key (optional; defaults to a managed identity bound to the VM). | `string` |
| `patch-storage.azure-connection-string` | Azure storage connection string (optional alternative to account name/key). | `string` |
| `patch-storage.azure-tenant-id` | Entra ID tenant ID, for explicit service principal auth (optional; requires `azure-client-id` and `azure-client-secret`). | `string` |
| `patch-storage.azure-client-id` | Entra ID application (client) ID, for explicit service principal auth (optional). | `string` |
docs/server/reference/patch-storage/migrating-patch-storage.md:14
- The parenthetical “(so no new patches arrive, and avoid running any manual syncs)” is grammatically awkward because it mixes an explanation with an imperative. Rephrasing improves readability and reduces ambiguity during migrations.
The recommended tool for copying patches is `rsync`, since it performs a checksum-verified copy. Disable patch synchronisation in the config first (so no new patches arrive, and avoid running any manual syncs), then run `rsync` once to copy the existing patches across.
docs/server/reference/patch-storage/index.md:25
- This sentence mixes inconsistent capitalization for backend names (e.g. “s3” vs “Google Cloud Storage (GCS)” above, and “postgresql” vs “Postgresql” in the list). Using consistent capitalization improves scanability in the overview.
In case there is a need to scale out Livepatch on-prem, use one of the object storage backends (s3, gcs, azure, ibm, oracle), postgresql, or swift patch stores. Any patch store should have enough space for storing live kernel patches - currently at least 45GB for all patches, see [this guide](/server/reference/patch-management/patch-sync-filters.md) to filter patches sent to your on-prem instance to specific kernel variants/architectures and lower this requirement.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.
Suppressed comments (8)
docs/server/reference/platform/configuration.md:163
- Several table descriptions reference other config keys using abbreviated names (e.g.
s3-access-key). In this table the keys are otherwise fully-qualified, and these abbreviated references are ambiguous/unsearchable in the docs.
| `patch-storage.s3-access-key` | AWS access key (optional; defaults to the VM's ambient credentials, e.g. an EC2 instance role). | `string` |
| `patch-storage.s3-secret-key` | AWS secret key (optional; see `s3-access-key`). | `string` |
| `patch-storage.s3-assume-role-arn` | IAM role ARN to assume via STS, using the resolved credentials above (optional). | `string` |
docs/server/reference/platform/configuration.md:166
- The
gcs-credentials-jsonrow points togcs-credentials-file, but the referenced key name is abbreviated; using the full key name makes the cross-reference clear and searchable.
| `patch-storage.gcs-credentials-file` | Path to a service account JSON key file (optional; defaults to Application Default Credentials). | `string` |
| `patch-storage.gcs-credentials-json` | Inline service account JSON key (optional; see `gcs-credentials-file`). | `string` |
docs/server/reference/platform/configuration.md:173
- Azure rows reference other keys using abbreviated names (e.g.
azure-connection-string,azure-client-id). Using fully-qualifiedpatch-storage.*keys here avoids confusion and matches the rest of the table's naming.
| `patch-storage.azure-account-name` | Azure storage account name (not required when `azure-connection-string` is set, which already carries the account name). | `string` |
| `patch-storage.azure-account-key` | Azure storage account key (optional; defaults to a managed identity bound to the VM). | `string` |
| `patch-storage.azure-connection-string` | Azure storage connection string (optional alternative to account name/key). | `string` |
| `patch-storage.azure-tenant-id` | Entra ID tenant ID, for explicit service principal auth (optional; requires `azure-client-id` and `azure-client-secret`). | `string` |
| `patch-storage.azure-client-id` | Entra ID application (client) ID, for explicit service principal auth (optional). | `string` |
docs/server/reference/platform/configuration.md:180
- IBM rows cross-reference other options using abbreviated key names (
ibm-api-key,ibm-access-key). Switching to fully-qualifiedpatch-storage.*keys makes the cross-references unambiguous.
| `patch-storage.ibm-access-key` | IBM COS HMAC access key (optional; see `ibm-api-key`). | `string` |
| `patch-storage.ibm-secret-key` | IBM COS HMAC secret key (optional; see `ibm-access-key`). | `string` |
docs/server/reference/patch-storage/migrating-patch-storage.md:12
- This paragraph says “Every patch storage backend supported…” but omits PostgreSQL even though it’s listed as a supported backend elsewhere on this page. Rewording to explicitly describe only the file-based backends avoids an inaccurate blanket statement.
Every patch storage backend supported by Livepatch Server (filesystem, S3, GCS, Azure, IBM, Oracle, Swift) stores patches as a flat set of files, each keyed by its filename. This means the same set of patch files works unmodified on any backend: migrating between backends is simply a matter of copying the patch files across, then updating [`patch-storage.type`](/server/reference/platform/configuration.md) and its associated options to point at the new backend.
docs/server/reference/patch-storage/index.md:25
- This sentence mixes backend names with lowercase driver identifiers (e.g. “s3, gcs”) and also uses the non-standard “postgresql”. Using the proper product names here improves readability and consistency with the list above.
In case there is a need to scale out Livepatch on-prem, use one of the object storage backends (s3, gcs, azure, ibm, oracle), postgresql, or swift patch stores. Any patch store should have enough space for storing live kernel patches - currently at least 45GB for all patches, see [this guide](/server/reference/patch-management/patch-sync-filters.md) to filter patches sent to your on-prem instance to specific kernel variants/architectures and lower this requirement.
docs/server/reference/patch-storage/index.md:17
- Backend names in this list aren’t consistently capitalized/standardized (e.g. “minio”, “Postgresql”). This makes the page look inconsistent with the rest of the docs (e.g. configuration table uses “PostgreSQL” and other pages use “MinIO”).
This issue also appears on line 25 of the same file.
3. S3 (and compatible implementations, e.g. minio)
4. Postgresql
docs/server/reference/patch-storage/migrating-patch-storage.md:30
- Swift is an object storage backend too, but it’s missing from the list here and from the rclone backend examples. Including Swift makes the instructions complete for all file-based object storage backends mentioned earlier.
For the object storage backends (S3, GCS, Azure, IBM, Oracle), mount the bucket or container as a local directory with [rclone](https://rclone.org/), which supports all of these backends (including any S3-compatible endpoint, such as IBM COS or MinIO), then `rsync` into or out of the mount as if it were a normal directory.
1. Disable [`patch-sync`](/server/reference/patch-management/patch-sync-filters.md) in the config so no new patches are synced to the on-prem server, and avoid running any manual syncs, while the migration is in progress.
2. Install rclone and configure a remote for the bucket/container, following [rclone's documentation](https://rclone.org/docs/) for the relevant backend (`s3`, `google cloud storage`, `azureblob`, or `oracle-object-storage`).
3. Mount the remote:
…res from migration guide - Cross-references to other config options in the platform configuration table now use the full patch-storage.* key rather than the bare option name, avoiding ambiguity. - The migrating patches guide now explicitly scopes itself to the file-based storage backends and calls out that the Postgres backend isn't covered, since it stores patches in the database rather than as files.
Copilot stopped reviewing on behalf of
kunalmohan-work due to an error
August 17, 2026 13:34
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 9 out of 9 changed files in this pull request and generated no new comments.
Suppressed comments (2)
docs/server/reference/patch-storage/migrating-patch-storage.md:31
- The rclone backend name for OCI Object Storage appears to be
oracleobjectstorage(no dashes). Usingoracle-object-storagehere may send readers to the wrong docs/config option.
2. Install rclone and configure a remote for the bucket/container, following [rclone's documentation](https://rclone.org/docs/) for the relevant backend (`s3`, `google cloud storage`, `azureblob`, or `oracle-object-storage`).
docs/server/reference/platform/configuration.md:169
- The cross-reference in this row uses
azure-connection-string, but the actual config key in this table ispatch-storage.azure-connection-string. Using the full key name keeps references consistent/searchable and matches the other rows.
| `patch-storage.azure-account-name` | Azure storage account name (not required when `azure-connection-string` is set, which already carries the account name). | `string` |
kunalmohan-work
requested review from
a team,
PrinsonF77,
commercial-systems-bot,
ijansky-canonical and
trollLemon
and removed request for
a team
August 18, 2026 04:46
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
There are a couple of documentation accuracy/consistency issues in newly added/modified content (config key reference and Swift migration coverage) that should be corrected before merging.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Review details
Suppressed comments (6)
Previously missed (6) — in code that hasn't changed since the last review.
docs/server/reference/patch-storage/migrating-patch-storage.md:7
- Line contains whitespace on an otherwise blank line after the front matter. Removing trailing whitespace avoids unnecessary diffs and potential markdown-lint warnings.
docs/server/reference/patch-storage/migrating-patch-storage.md:31 - This guide includes Swift in the list of supported file-based backends, but the object-storage migration section omits Swift from both the backend list and the referenced rclone remote types. This is inconsistent and makes it unclear how Swift migrations should be handled.
docs/server/reference/patch-storage/use-azure-for-patch-storage.md:7 - Line contains whitespace on an otherwise blank line after the front matter. Removing trailing whitespace avoids unnecessary diffs and potential markdown-lint warnings.
docs/server/reference/patch-storage/use-gcs-for-patch-storage.md:7 - Line contains whitespace on an otherwise blank line after the front matter. Removing trailing whitespace avoids unnecessary diffs and potential markdown-lint warnings.
docs/server/reference/patch-storage/use-oracle-for-patch-storage.md:7 - Line contains whitespace on an otherwise blank line after the front matter. Removing trailing whitespace avoids unnecessary diffs and potential markdown-lint warnings.
docs/server/reference/platform/configuration.md:169 - In this table row, the cross-reference uses
azure-connection-string, but the actual config key ispatch-storage.azure-connection-string(as used in the Azure patch-storage page). Using the full key name avoids ambiguity and makes the reference searchable.
- Files reviewed: 10/10 changed files
- Comments generated: 1
- Review effort level: Lite
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: kunalmohan-work <kunal.mohan@canonical.com>
Contributor
There was a problem hiding this comment.
🔵 Needs a closer look
There are a few documentation correctness/consistency issues in the new/updated docs (scope mismatch for Swift, one incorrect config key cross-reference, and stray whitespace lines) that should be fixed before merging.
Review details
Suppressed comments (6)
Previously missed (6) — in code that hasn't changed since the last review.
docs/server/reference/patch-storage/migrating-patch-storage.md:7
- This line contains stray whitespace on an otherwise blank line; remove it to avoid unnecessary markdown-lint diffs/noise.
docs/server/reference/patch-storage/migrating-patch-storage.md:31 - This section omits Swift even though the guide scope explicitly includes it earlier. Either include Swift as a supported object-storage migration target/source here (including the rclone backend name), or remove Swift from the stated scope.
docs/server/reference/patch-storage/use-azure-for-patch-storage.md:7 - This line contains stray whitespace on an otherwise blank line; remove it to avoid unnecessary markdown-lint diffs/noise.
docs/server/reference/patch-storage/use-gcs-for-patch-storage.md:7 - This line contains stray whitespace on an otherwise blank line; remove it to avoid unnecessary markdown-lint diffs/noise.
docs/server/reference/patch-storage/use-oracle-for-patch-storage.md:7 - This line contains stray whitespace on an otherwise blank line; remove it to avoid unnecessary markdown-lint diffs/noise.
docs/server/reference/platform/configuration.md:169 - The cross-reference in this table row uses the unscoped key name
azure-connection-string, but the actual config option ispatch-storage.azure-connection-string. Using the full key name keeps the table consistent and makes the option searchable.
- Files reviewed: 10/10 changed files
- Comments generated: 0 new
- Review effort level: Lite
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
A few documentation statements/terms introduced or impacted by the PR are misleading or incomplete (notably patch-storage encryption guidance, rsync “checksum-verified” wording, and inconsistent ETag terminology).
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Review details
Suppressed comments (2)
Previously missed (2) — in code that hasn't changed since the last review.
docs/server/reference/patch-storage/migrating-patch-storage.md:15
- This sentence says rsync performs a "checksum-verified" copy, but the example commands below don’t enable checksum-based comparison (no
--checksum), and the phrasing can be read as stronger end-to-end verification than rsync provides by default. Consider rewording to avoid implying checksum verification unless you explicitly recommend--checksum.
docs/server/reference/platform/configuration.md:170 - The wording here implies the Azure account key "defaults" to a managed identity, but a managed identity is an alternative auth mechanism rather than a default value for the key. Rephrase to clarify that managed identity is used when no explicit credentials are provided.
- Files reviewed: 9/10 changed files
- Comments generated: 1
- Review effort level: Lite
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The new migration and index docs contain a couple of verified accuracy/consistency issues (rsync checksum claim; Swift omission/capitalization inconsistencies) that should be corrected before approval.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Review details
Suppressed comments (1)
docs/server/reference/patch-storage/index.md:25
- This sentence lists backends in lowercase (s3/gcs/azure/…) while the same page lists them with standard capitalization above (S3/GCS/Azure/…). Consider capitalizing these backend names here as well (and “PostgreSQL”) for consistency and scannability.
In case there is a need to scale out Livepatch on-prem, use one of the object storage backends (s3, gcs, azure, ibm, oracle), postgresql, or swift patch stores. Any patch store should have enough space for storing live kernel patches - currently at least 45GB for all patches, see [this guide](/server/reference/patch-management/patch-sync-filters.md) to filter patches sent to your on-prem instance to specific kernel variants/architectures and lower this requirement.
- Files reviewed: 9/10 changed files
- Comments generated: 3
- Review effort level: Lite
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
A few newly added/edited doc lines have clarity/consistency issues (notably spacing/grammar and a now-underspecified public key reference) that should be corrected before merging.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Review details
Suppressed comments (1)
docs/server/reference/patch-storage/index.md:25
- This sentence uses "postgresql" in lowercase, which is inconsistent with the earlier list item ("PostgreSQL") and can read like the config key/type rather than the database product name.
In case there is a need to scale out Livepatch on-prem, use one of the object storage backends (s3, gcs, azure, ibm, oracle), postgresql, or swift patch stores. Any patch store should have enough space for storing live kernel patches - currently at least 45GB for all patches, see [this guide](/server/reference/patch-management/patch-sync-filters.md) to filter patches sent to your on-prem instance to specific kernel variants/architectures and lower this requirement.
- Files reviewed: 11/12 changed files
- Comments generated: 2
- Review effort level: Lite
Contributor
There was a problem hiding this comment.
🟢 Approval recommended
Only minor documentation consistency/clarity nits were found, with no functional or structural issues in the changes.
Review details
Suppressed comments (2)
docs/server/reference/patch-storage/index.md:25
- The product/backend names in this sentence are lowercased (e.g. "s3", "postgresql") but elsewhere in the same section they’re treated as proper names (e.g. "S3", "PostgreSQL"). This inconsistency makes the list harder to scan and can look like a typo.
In case there is a need to scale out Livepatch on-prem, use one of the object storage backends (s3, gcs, azure, ibm, oracle), postgresql, or swift patch stores. Any patch store should have enough space for storing live kernel patches - currently at least 45GB for all patches, see [this guide](/server/reference/patch-management/patch-sync-filters.md) to filter patches sent to your on-prem instance to specific kernel variants/architectures and lower this requirement.
docs/client/reference/patches/patch-security.md:35
- This bullet no longer explains where the public key comes from. The paragraph below does say the keys are embedded in the client, but making that explicit in the bullet itself prevents readers from assuming they need to download a key from elsewhere.
- Signature algorithm: SHA-512 with RSA
- Canonical's public key
- Files reviewed: 11/12 changed files
- Comments generated: 0 new
- Review effort level: Lite
trollLemon
approved these changes
Sep 4, 2026
danieltoader-canonical
approved these changes
Sep 4, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds how-to pages for the four new patch storage backends (mirroring the existing S3 page), updates the patch storage overview and the platform configuration reference table with the new backends and options, and adds a guide for migrating patches between storage backends using rsync.
CHANGELOG.mdwith relevant non-documentation file changes?