Document GCS, Azure, IBM, and Oracle patch storage backends - #9
Open
kunalmohan-work wants to merge 6 commits into
Open
Document GCS, Azure, IBM, and Oracle patch storage backends#9kunalmohan-work wants to merge 6 commits into
kunalmohan-work wants to merge 6 commits into
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.
Pull request overview
Copilot reviewed 10 out of 10 changed files in this pull request and generated no new comments.
Suppressed comments (5)
docs/server/reference/platform/configuration.md:170
- The description for
patch-storage.azure-account-keycurrently reads like the key itself “defaults” to a managed identity, which is confusing (managed identity is an auth mechanism, not a key value). Consider wording this as “optional; only required for account name/key auth” to match the actual behavior.
| `patch-storage.azure-account-key` | Azure storage account key (optional; defaults to a managed identity bound to the VM). | `string` |
docs/server/reference/platform/configuration.md:179
patch-storage.ibm-access-keyis an HMAC credential, but its description points readers topatch-storage.ibm-api-key, which is a different auth mechanism. Rewording this as an alternative to the IAM API key (rather than “see …”) is clearer.
| `patch-storage.ibm-access-key` | IBM COS HMAC access key (optional; see `patch-storage.ibm-api-key`). | `string` |
docs/server/how-to-guides/security/harden-your-deployment.md:48
- The “Encrypt patch storage connections” section only mentions S3 and Swift, but this PR adds additional networked patch storage backends (GCS, Azure, IBM COS, OCI). Adding guidance for these backends (or explicitly stating they use HTTPS by default) would keep the hardening guide aligned with the supported options.
For charm deployments, database credentials are obtained through Juju relations (`database` interface with the [PostgreSQL K8s Charm](https://charmhub.io/postgresql-k8s)). TLS for the database connection is managed by the PostgreSQL charm's [TLS integration](https://canonical.com/data/postgresql/docs/16/how-to/network-and-encryption/enable-tls/). The Livepatch charm does not expose separate database credential configuration -- all credentials are exchanged through the Juju relation protocol.
## Encrypt patch storage connections
* **S3**: Set `patch-storage.s3-secure` to `true` to enforce HTTPS for all S3 communication.
docs/server/reference/platform/configuration.md:169
- In this table row, the cross-reference uses
azure-connection-stringinstead of the full config key namepatch-storage.azure-connection-string, which makes it inconsistent with the other rows and harder to search.
This issue also appears in the following locations of the same file:
- line 170
- line 179
| `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/patch-storage/index.md:25
- This sentence refers to backend names in lowercase (e.g., "s3", "gcs"), which is inconsistent with the capitalization used elsewhere on the page (e.g., the numbered list uses "S3" and "Swift"). Using the product names here improves readability.
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.
kunalmohan-work
removed request for
commercial-systems-bot and
ijansky-canonical
August 18, 2026 04:47
trollLemon
approved these changes
Aug 18, 2026
danieltoader-canonical
approved these changes
Aug 18, 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?