From 148efd03472c3eec57344148e53b348880131250 Mon Sep 17 00:00:00 2001 From: Kunal Mohan Date: Tue, 13 Oct 2026 11:54:55 +0530 Subject: [PATCH 01/11] docs: add patch uploader, cloud storage setup, and migration guides --- docs/.custom_wordlist.txt | 6 + .../deployment/upgrade-a-deployment.md | 120 ++++++++++++++-- .../distribute-patches-offline.md | 134 ++++++++++++++++++ .../how-to-guides/patch-management/index.md | 2 + docs/server/reference/patch-storage/index.md | 48 +++++-- .../use-azure-for-patch-storage.md | 41 +++++- .../use-gcs-for-patch-storage.md | 45 +++++- .../use-ibm-for-patch-storage.md | 47 +++++- .../use-oracle-for-patch-storage.md | 38 ++++- .../patch-storage/use-s3-for-patch-storage.md | 52 +++++-- .../use-swift-for-patch-storage.md | 72 ++++++++++ .../reference/platform/configuration.md | 8 +- 12 files changed, 562 insertions(+), 51 deletions(-) create mode 100644 docs/server/how-to-guides/patch-management/distribute-patches-offline.md create mode 100644 docs/server/reference/patch-storage/use-swift-for-patch-storage.md diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index 7d4197c..251d803 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -9,6 +9,7 @@ Autoscaling aws backend backends +backoff backport bcrypt blocklisted @@ -28,6 +29,7 @@ Diátaxis docstrings? downloader Downloader +downscoped dvipng enablement Enablement @@ -82,6 +84,7 @@ Multipass MyST npm Numpy +OAuth oem OCI Open Graph @@ -97,6 +100,8 @@ PPAs PR PRs preconfigured +presigned +Presigned proxying Pygments pymarkdown @@ -139,6 +144,7 @@ TOC toctree triages txt +uploader ulwazi unapplied uncomment(ing)? diff --git a/docs/server/how-to-guides/deployment/upgrade-a-deployment.md b/docs/server/how-to-guides/deployment/upgrade-a-deployment.md index 3af3f3b..f9ebe3d 100644 --- a/docs/server/how-to-guides/deployment/upgrade-a-deployment.md +++ b/docs/server/how-to-guides/deployment/upgrade-a-deployment.md @@ -1,43 +1,137 @@ --- myst: html_meta: - description: "How to upgrade a Livepatch on-premises deployment." + description: "How to upgrade a Livepatch on-premises deployment, perform database schema migrations, and sync patch publish timestamps." --- - (server-how-to-guides-how-to-upgrade-a-livepatch-on-prem-deployment)= # How to upgrade a deployment -To upgrade the Livepatch on-premises deployment, each application must be upgraded separately: +Upgrading an on-premises Livepatch Server deployment involves updating application binaries, applying database schema migrations, and optionally running a metadata-only sync to backfill patch publish timestamps. + +## Step 1: Update application binaries + +Depending on whether your deployment uses Juju charms or standalone snaps, follow the corresponding procedure. +### Charmed deployments (Juju) + +In charmed deployments, upgrade each component application using `juju refresh`: + +```bash +juju refresh livepatch ``` + +If you manage supporting infrastructure services via Juju, upgrade them as required: + +```bash +juju refresh postgresql juju refresh haproxy +juju refresh ubuntu-advantage ``` +### Standalone snap deployments + +In snap deployments, refresh the server snap: + +```bash +sudo snap refresh canonical-livepatch-server ``` -juju refresh postgresql -``` +## Step 2: Apply database schema upgrades + +When upgrading across major or minor Livepatch Server releases, new database migrations may be required. + +### Charmed deployments + +When a schema upgrade is required, the Livepatch application enters a blocked status visible in `juju status`. Run the `schema-upgrade` action on the leader unit: + +```bash +juju run livepatch/leader schema-upgrade --wait ``` -juju refresh ubuntu-advantage + +```{note} +In Juju v3, `juju run-action` was renamed to `juju run`. See the [Juju documentation on managing actions](https://documentation.ubuntu.com/juju/latest/howto/manage-actions/#run-an-action) for details. ``` +If needed, restart units after the schema upgrade completes: + +```bash +juju run livepatch/ restart --wait ``` -juju refresh livepatch + +### Snap deployments + +For snap deployments, database migrations run automatically during service startup when the updated snap starts. The migration runner acquires an advisory lock on PostgreSQL to ensure that multi-unit or clustered deployments upgrade safely without race conditions. + +You can also run schema migrations manually using the snap command: + +```bash +sudo canonical-livepatch-server.schema-upgrade ``` -After upgrading the Livepatch application, a schema upgrade may be required. This is indicated in the application's status when running `juju status`. In such a case, run: +Check the service logs to verify successful migration: +```bash +sudo journalctl -u snap.canonical-livepatch-server.* -n 100 --no-pager ``` -juju run-action livepatch/leader schema-upgrade --wait + +### Key schema migrations + +Recent Livepatch Server releases introduce database improvements that support the patch uploader and offline distribution workflows: + +- **Migration 086 (`patch_file_tier.publish_time`)**: Adds `publish_time` and `sync_time` tracking to patch tiers, recording the exact point in time when each patch was made available. +- **Migration 088 (`patch_file_filename_index`)**: Adds a dedicated B-tree index on `patch_file.filename` to significantly accelerate duplicate detection and batch lookups during patch uploads. + +## Step 3: Backfill publish timestamps with metadata-only sync + +In earlier Livepatch Server releases, patch tiers did not record the original upstream publish timestamp from Canonical (or initialized it to the local database insertion time). + +If your server has an active upstream connection (`patch-sync.enabled=true`) and you want your on-premises patch catalog to reflect accurate Canonical publish dates (for client queries, KPI reporting, and `patch list` filtering), trigger a **metadata-only sync**. + +### How metadata-only sync works + +Unlike a full patch synchronisation, which downloads multi-gigabyte kernel patch binaries, a metadata-only sync: + +- Queries only metadata from Canonical's upstream server. +- Compares already-known local patches and updates their `publish_time` across all tiers. +- Validates local patch checksums against upstream records. +- Does **not** download binary `.tar.bz2` payloads and does **not** register newly published patches. + +### Run the metadata-only sync + +Trigger the metadata synchronisation job using `livepatch-admin`: + +```bash +livepatch-admin sync trigger --metadata-only --wait ``` -The Livepatch application can also be restarted with the following command: +Flags: +- `--metadata-only`: Refresh publish timestamps and verify checksums of already-known patches without downloading file payloads. +- `--wait`: Block until the background synchronisation job completes (optional). +- `--timeout `: Maximum time to wait for the job (defaults to `10m`). + +If you run without `--wait`, retrieve the job status using the returned job ID: + +```bash +livepatch-admin job-status ``` -juju run-action livepatch/ restart --wait + +Or view recent sync reports: + +```bash +livepatch-admin sync reports --all ``` -> `juju run-action` has been renamed to `juju run` from Juju v3. -> See the [Juju documentation on managing actions](https://documentation.ubuntu.com/juju/latest/howto/manage-actions/#run-an-action) for more details. +## Step 4: Review patch sync tier configuration + +If your deployment synchronises patches from an upstream server, review how tiers are mapped: + +- **Full tier mirror (`patch-sync.sync-tiers=true`)**: Mirrors the entire upstream tier hierarchy locally. Patches are downloaded from upstream `stable` and mapped across all lower local tiers automatically. +- **Single-tier sync (`patch-sync.sync-tiers=false`)**: + - `patch-sync.upstream-tier`: Specifies which tier to request from upstream (defaults to `stable`). + - `patch-sync.ingress-tier`: Specifies the local tier into which synced patches are stored and served (defaults to your first configured tier, such as `edge` or `stable`). + +Run `livepatch-admin tier list` to verify your local tiers and confirm where patches land. + diff --git a/docs/server/how-to-guides/patch-management/distribute-patches-offline.md b/docs/server/how-to-guides/patch-management/distribute-patches-offline.md new file mode 100644 index 0000000..b69aee4 --- /dev/null +++ b/docs/server/how-to-guides/patch-management/distribute-patches-offline.md @@ -0,0 +1,134 @@ +--- +myst: + html_meta: + description: "How to distribute patches to an air-gapped or offline on-premises Livepatch Server using the patch uploader workflow." +--- + +(server-how-to-guides-distribute-patches-offline)= + +# Distribute patches across an air gap + +Livepatch on-premises deployments can operate in fully air-gapped environments without inbound or outbound internet access. The `livepatch-admin` command-line tool provides a complete offline patch distribution workflow: + +1. **Download**: Query and download patches from Canonical's hosted Livepatch Server to a local directory on an internet-connected system. +2. **Transfer**: Move the patch directory across the air gap using approved physical media or secure network boundaries. +3. **Upload**: Upload patches and register their metadata with the air-gapped on-premises Livepatch Server. + +## Prerequisites + +- **On the internet-connected system:** + - An installation of the Livepatch administration tool (`livepatch-admin`). + - An Ubuntu Pro token entitled to Livepatch, attached to the system or available as a machine token. + - Outbound HTTPS network access to `https://livepatch.canonical.com`. + +- **On the air-gapped network:** + - Network connectivity to the on-premises Livepatch Server. + - An authenticated administrator session created with `livepatch-admin login`. + +## Step 1: Query and download patches from the hosted server + +On the internet-connected workstation, list the patches available from Canonical's hosted server. + +### List available patches + +Use `livepatch-admin patch list` to inspect available patches before downloading: + +```bash +livepatch-admin patch list --tier stable +``` + +You can narrow the results using filters: + +- `--kernel `: Filter by kernel release prefix (for example, `5.15.0` or `5.15.0-107.117-generic`). +- `--arch `: Target architecture (`amd64`, `arm64`, `s390x`, `ppc64le`). +- `--flavor `: Kernel flavour (for example, `generic`, `lowlatency`, `aws`, `azure`, `gcp`). +- `--published-after `: RFC 3339 timestamp or `YYYY-MM-DD` date to view patches published after a specific point in time. +- `--published-before `: RFC 3339 timestamp or `YYYY-MM-DD` date to view patches published before a specific point in time. +- `--tier `: Livepatch tier (defaults to `stable`). +- `--format `: Output format (`table`, `json`, `yaml`). + +### Download patches to disk + +Once you identify the required patches, download them to a dedicated directory: + +```bash +livepatch-admin patch download --patch-dir /tmp/livepatch-export --tier stable +``` + +Optional download flags include: + +- `--patch-dir `: Destination directory for downloaded patches (required). +- `--kernel `: Download patches for kernels matching or newer than the specified version prefix (for example, `5.15.0`). +- `--arch `: Restrict downloads to a specific CPU architecture. +- `--flavor `: Restrict downloads to a specific kernel flavour. +- `--concurrency `: Number of simultaneous patch downloads (defaults to `2`). +- `--retry-attempts `: Number of retry attempts with exponential backoff if a download encounters a network interruption (defaults to `3`). + +### Inspect the downloaded directory + +The destination directory contains two types of artifacts: + +```text +/tmp/livepatch-export/ +├── livepatch-5.15.0-107.117-generic-107.1-amd64.tar.bz2 +├── livepatch-5.15.0-107.117-generic-106.1-amd64.tar.bz2 +└── canonical-livepatch-patch-metadata.json +``` + +- **Patch tarballs (`livepatch-*.tar.bz2`)**: Binary payload packages containing kernel livepatch modules. +- **Metadata manifest (`canonical-livepatch-patch-metadata.json`)**: A JSON manifest recording the kernel version, architecture, patch version, SHA-256 checksum, supported kernel list, and original Canonical publish timestamp for every downloaded patch. + +```{important} +Do not alter or delete `canonical-livepatch-patch-metadata.json`. The upload command automatically reads this manifest to preserve original publish timestamps and supported kernel associations in your on-premises database. +``` + +## Step 2: Transfer the directory across the air gap + +Copy the entire export directory—including all `.tar.bz2` archive files and `canonical-livepatch-patch-metadata.json`—to removable media (such as an encrypted USB drive or write-once optical media) or transfer it through your organisation's secure data diode or staging gateway. + +Mount or copy the directory onto a workstation or bastion system with network connectivity to your on-premises Livepatch Server. + +## Step 3: Upload patches to the on-premises server + +Log in to your on-premises Livepatch Server with administrator credentials: + +```bash +livepatch-admin login https://livepatch.internal.example.com +``` + +### Run the upload command + +Navigate to the location of the transferred directory and upload the patches: + +```bash +livepatch-admin patch upload --patch-dir /media/transfer/livepatch-export +``` + +### Command options and flags + +- `--patch-dir `: Local path to the directory containing patch archives (required). +- `--metadata-file `: Path to the metadata manifest. Defaults to `canonical-livepatch-patch-metadata.json` inside `--patch-dir`. + - When the default manifest is present, `livepatch-admin` automatically reads it to register patches with their original upstream publish timestamps and supported kernel lists. + - If the default manifest is absent, `livepatch-admin` scans `--patch-dir`, parses filenames, and generates metadata dynamically, assigning the current system time as the publish timestamp. + - If you pass an explicit `--metadata-file` path and the file is missing, the command immediately terminates with a fatal error. +- `--tier `: Destination tier for the uploaded patches. Defaults to the on-premises server's configured sync tier or the first configured tier (for example, `edge` or `stable`). +- `--concurrency `: Number of parallel file uploads (defaults to `2`). +- `--overwrite`: Unconditionally overwrite existing patches on the server even if filenames or checksums already exist. +- `--cleanup`: Automated failure rollback. If an upload fails or server-side metadata registration encounters an error, any files uploaded during the session are automatically deleted from storage to avoid leaving the server in a partial state. + +### Duplicate detection and checksum validation + +Before uploading, `livepatch-admin` inspects the server's existing patch catalog to prevent redundant transfers or accidental collisions: + +- **Matching checksum**: If the on-premises server already has a patch with an identical filename and matching SHA-256 checksum, the file is automatically skipped. +- **Checksum mismatch**: If a patch file has the same filename as an existing server patch but a differing SHA-256 checksum, the uploader halts processing for that file without modifying storage. It records the mismatch in `/canonical-livepatch-patch-duplicates.json` for administrator review. +- **Force overwrite**: If you intentionally need to replace a mismatched patch, pass the `--overwrite` flag. + +## Storage backend behavior + +`livepatch-admin patch upload` works transparently across all supported storage backends: + +- **Cloud object storage (AWS S3, Google Cloud Storage, Azure Blob Storage, IBM Cloud Object Storage, Oracle Cloud Infrastructure, OpenStack Swift):** The Livepatch Server issues temporary, scoped upload credentials to the administrator client. The client transfers binary payloads directly to cloud object storage using presigned POST policies, SAS tokens, or Pre-Authenticated Requests. Background workers automatically refresh credentials during large batch uploads before expiry. +- **Server-mediated storage (Local Filesystem, PostgreSQL):** The administrator client streams binary payloads directly through the Livepatch Server API (`PUT /v1/admin/patches/file/{filename}`) authenticated by the administrator's session token. + +For details on configuring cloud permissions so your server can generate upload credentials, see the [Patch storage reference](/server/reference/patch-storage/index.md). diff --git a/docs/server/how-to-guides/patch-management/index.md b/docs/server/how-to-guides/patch-management/index.md index 27b80b7..23465e2 100644 --- a/docs/server/how-to-guides/patch-management/index.md +++ b/docs/server/how-to-guides/patch-management/index.md @@ -14,6 +14,7 @@ Fetch, download, proxy, and chain patches across servers. ## In this section - [Fetch patches](/server/how-to-guides/patch-management/fetch-patches.md) +- [Distribute patches across an air gap](/server/how-to-guides/patch-management/distribute-patches-offline.md) - [Use the patch downloader tool](/server/how-to-guides/patch-management/use-the-patch-downloader-tool.md) - [Configure proxy for fetching patches](/server/how-to-guides/patch-management/configure-proxy-for-fetching-patches.md) - [Chain Livepatch Servers](/server/how-to-guides/patch-management/chain-livepatch-servers.md) @@ -24,6 +25,7 @@ Fetch, download, proxy, and chain patches across servers. :hidden: Fetch patches +Distribute patches across an air gap Use the patch downloader tool Configure proxy for fetching patches Chain Livepatch Servers diff --git a/docs/server/reference/patch-storage/index.md b/docs/server/reference/patch-storage/index.md index d0a7bbf..1511e71 100644 --- a/docs/server/reference/patch-storage/index.md +++ b/docs/server/reference/patch-storage/index.md @@ -9,22 +9,45 @@ myst: # Livepatch on-prem patch storage -Livepatch Server supports several different drivers for storing patch files downloaded from livepatch.canonical.com: +Livepatch Server supports several different drivers for storing patch files downloaded from livepatch.canonical.com or uploaded across an air gap: -1. Local filesystem -2. Swift -3. S3 (and compatible implementations, e.g. MinIO) -4. PostgreSQL -5. Google Cloud Storage (GCS) -6. Azure Blob Storage -7. IBM Cloud Object Storage -8. Oracle Cloud Infrastructure (OCI) Object Storage +1. **Local filesystem**: Stores patch files directly on disk. Ideal for single-unit deployments. +2. **PostgreSQL**: Stores patch files as Large Objects directly inside the PostgreSQL database. Suitable for multi-unit clusters without external cloud dependencies. +3. **AWS S3**: Highly scalable object storage for AWS or S3-compatible environments (such as MinIO or Ceph). +4. **Google Cloud Storage (GCS)**: Scalable object storage for Google Cloud Platform. +5. **Azure Blob Storage**: Durable container storage for Microsoft Azure. +6. **IBM Cloud Object Storage (COS)**: Resilient bucket storage for IBM Cloud. +7. **Oracle Cloud Infrastructure (OCI) Object Storage**: High-performance object storage for OCI. +8. **OpenStack Swift**: Scalable object storage for OpenStack environments. -The filesystem patch store is easiest to deploy and suits most configurations. However, if there is a need to scale out the Livepatch Server such as have multiple Livepatch Servers running to handle the load, the filesystem patch store should not be used. +The filesystem patch store is easiest to deploy and suits single-unit configurations. However, when scaling out the Livepatch Server across multiple load-balanced units, use PostgreSQL or one of the object storage backends (S3, GCS, Azure, IBM COS, OCI, Swift). -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. +Any patch store should have enough capacity for storing kernel live patches—currently at least 45GB for the full catalog. See [patch sync filters](/server/reference/patch-management/patch-sync-filters.md) to restrict downloads to specific kernel flavours or architectures and reduce storage requirements. -See the [patch storage](/server/reference/platform/configuration.md) config for all available parameters. +## Authentication and credential models + +Livepatch Server supports native, modern authentication mechanisms for each cloud and enterprise backend: + +| Storage Backend | Authentication Mechanisms | +| --------------- | ------------------------- | +| **Local filesystem** | Local directory path permissions (`patch-storage.filesystem-path`). | +| **PostgreSQL** | Database connection string (`patch-storage.postgres-connection-string`). | +| **AWS S3** | Ambient IAM credentials (EC2 instance profile, IRSA), static access keys (`patch-storage.s3-access-key`, `patch-storage.s3-secret-key`), or STS AssumeRole (`patch-storage.s3-assume-role-arn`). | +| **Google Cloud Storage** | Application Default Credentials (ADC: GCE metadata, GKE Workload Identity), Service Account key file (`patch-storage.gcs-credentials-file`), inline JSON (`patch-storage.gcs-credentials-json`), or Service Account Impersonation (`patch-storage.gcs-impersonate-service-account`). | +| **Azure Blob Storage** | Storage Account Key (`patch-storage.azure-account-key`), Connection String (`patch-storage.azure-connection-string`), Entra ID Service Principal (`patch-storage.azure-tenant-id`, `patch-storage.azure-client-id`, `patch-storage.azure-client-secret`), or Managed Identity (`patch-storage.azure-managed-identity-client-id`). | +| **IBM Cloud Object Storage** | IAM API key with service instance ID (`patch-storage.ibm-api-key`, `patch-storage.ibm-service-instance-id`), or ambient VPC Instance Metadata Service with an optional trusted profile (`patch-storage.ibm-trusted-profile-id`). | +| **OCI Object Storage** | Instance principal authentication (default on OCI compute), or OCI SDK configuration file and profile (`patch-storage.oracle-config-file`, `patch-storage.oracle-profile`). | +| **OpenStack Swift** | Keystone v3 username, API key/password, domain, tenant, and auth URL (`patch-storage.swift-*`). | + +## Upload credentials for the patch uploader + +When administrators use `livepatch-admin patch upload` to distribute patches to an on-premises server across an air gap, the server authorizes uploads depending on the storage driver: + +- **Cloud object storage (S3, GCS, Azure, IBM COS, OCI, Swift):** The Livepatch Server acts as a credential issuer, generating temporary, scoped, upload-only credentials or presigned URLs. The `livepatch-admin` CLI uploads binary archives directly to cloud storage, bypassing the Livepatch Server API for high-bandwidth file transfers. +- **Server-mediated storage (Local Filesystem, PostgreSQL):** The CLI streams files directly to the Livepatch Server API endpoint (`PUT /v1/admin/patches/file/{filename}`) authenticated by the administrator's login token. +- **Upload credential lifetime:** For cloud backends, the duration of temporary upload credentials is configurable via `patch-storage.upload-credential-ttl` (defaults to 15 minutes). Note that Google Cloud STS (GCS) and IBM Cloud IAM issue tokens with a cloud-enforced fixed duration of ~1 hour. + +See the [platform configuration reference](/server/reference/platform/configuration.md) for all available parameters. ```{toctree} :titlesonly: @@ -37,5 +60,6 @@ Use GCS for patch storage Use Azure for patch storage Use IBM COS for patch storage Use OCI Object Storage for patch storage +Use Swift for patch storage Migrate patches between storage backends ``` diff --git a/docs/server/reference/patch-storage/use-azure-for-patch-storage.md b/docs/server/reference/patch-storage/use-azure-for-patch-storage.md index a78efc8..b41b342 100644 --- a/docs/server/reference/patch-storage/use-azure-for-patch-storage.md +++ b/docs/server/reference/patch-storage/use-azure-for-patch-storage.md @@ -8,12 +8,45 @@ myst: # Livepatch on-prem with Azure Blob Storage patch storage +In Microsoft Azure deployments, Azure Blob Storage offers resilient and scalable patch storage for Livepatch on-prem. + To configure this, follow these steps: -- Create a Blob Storage container in the preferred region (best if the region is the same as the deployment's). Care needs to be taken to make the container not publicly writable, as this would pose a significant security risk. -- Choose an authentication method: a storage account name/key pair, a connection string, an Entra ID (Azure AD) service principal, or a managed identity bound to the VM. +- Create a Blob Storage container in your preferred region (ideally the same region as the Livepatch deployment). Ensure the container public access level is set to private. +- Choose an authentication method for the Livepatch Server. +- Assign the required Azure role-based access control (RBAC) roles. - Configure the relevant Azure [config options](/server/reference/platform/configuration.md). -Once this is configured, Livepatch will store and retrieve patch files from the Azure Blob Storage container. +Once configured, Livepatch will store and retrieve patch files from the Azure Blob Storage container. + +## Supported authentication mechanisms + +Livepatch supports several authentication methods for Azure Blob Storage: + +1. **Storage account key:** Set `patch-storage.azure-account-name` and `patch-storage.azure-account-key`. +2. **Storage connection string:** Set `patch-storage.azure-connection-string`. This option supersedes individual account name and key settings. +3. **Microsoft Entra ID service principal:** Configure `patch-storage.azure-tenant-id`, `patch-storage.azure-client-id`, and `patch-storage.azure-client-secret`. +4. **System-assigned managed identity (recommended for Azure):** When running on an Azure Virtual Machine or Azure Kubernetes Service (AKS), omit keys, connection strings, and service principal secrets. Livepatch automatically uses the ambient system-assigned managed identity. +5. **User-assigned managed identity:** When using a user-assigned managed identity instead of the system-assigned default, specify its client ID with `patch-storage.azure-managed-identity-client-id`. + +## Required Azure RBAC roles + +Depending on the chosen authentication method, assign the appropriate Azure RBAC roles to the Livepatch identity: + +### Standard server operations + +For synchronising and serving patches, the identity must have blob read, write, and delete permissions. Assign the following role at the storage account or container scope: + +- **Storage Blob Data Contributor** + +### Temporary upload credentials for the patch uploader + +When an administrator runs `livepatch-admin patch upload`, the Livepatch Server generates container-level Shared Access Signature (SAS) tokens granting write and create capabilities: + +- **When using Account Key or Connection String:** Livepatch signs the SAS token directly using the storage account Shared Key. +- **When using Microsoft Entra ID (Service Principal or Managed Identity):** Livepatch requests a User Delegation Key from Microsoft Entra ID to sign a User Delegation SAS. To enable this, assign: + 1. **Storage Blob Delegator** (or custom role with `Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey/action`) scoped at the storage account level. + 2. **Storage Blob Data Contributor** scoped at the storage account or target container level. + +Upload credential lifetimes are governed by `patch-storage.upload-credential-ttl` (defaults to 15 minutes). -`patch-storage.azure-account-name` is not required when `patch-storage.azure-connection-string` is set, since the connection string already carries the account name and key. When account key, connection string, and service principal credentials are all omitted, a managed identity bound to the VM is used instead (the system-assigned identity by default, or a user-assigned identity selected via `patch-storage.azure-managed-identity-client-id`). diff --git a/docs/server/reference/patch-storage/use-gcs-for-patch-storage.md b/docs/server/reference/patch-storage/use-gcs-for-patch-storage.md index 8f4797b..9548118 100644 --- a/docs/server/reference/patch-storage/use-gcs-for-patch-storage.md +++ b/docs/server/reference/patch-storage/use-gcs-for-patch-storage.md @@ -8,12 +8,49 @@ myst: # Livepatch on-prem with Google Cloud Storage patch storage +In Google Cloud Platform (GCP) deployments, Google Cloud Storage (GCS) provides highly available and scalable patch storage for Livepatch on-prem. + To configure this, follow these steps: -- Create a GCS bucket in the preferred region (best if the region is the same as the deployment's). Care needs to be taken to make the bucket not publicly writable, as this would pose a significant security risk. -- Create a service account with permissions to read and write objects in that bucket, or rely on the credentials already bound to the VM (e.g. the GCE metadata service, or workload identity) if it is granted the required permissions. +- Create a GCS bucket in your preferred region (ideally the same region as the Livepatch deployment). Ensure the bucket is not publicly writable. +- Choose an authentication mechanism for the Livepatch Server service account. +- Grant the required IAM roles to the service account on the bucket. - Configure the relevant GCS [config options](/server/reference/platform/configuration.md). -Once this is configured, Livepatch will store and retrieve patch files from the GCS bucket. +Once configured, Livepatch will store and retrieve patch files from the GCS bucket. + +## Supported authentication mechanisms + +Livepatch supports several authentication methods for Google Cloud Storage: + +1. **Application Default Credentials (ADC, recommended for GCP):** When running on Google Compute Engine (GCE) or Google Kubernetes Engine (GKE) with Workload Identity, Livepatch automatically acquires credentials from the ambient environment. Leave `patch-storage.gcs-credentials-file` and `patch-storage.gcs-credentials-json` unset. +2. **Service account key file:** Specify the absolute path to a service account JSON key file via `patch-storage.gcs-credentials-file`. +3. **Inline service account JSON:** Provide the raw JSON key contents directly using `patch-storage.gcs-credentials-json`. +4. **Service account impersonation:** Set `patch-storage.gcs-impersonate-service-account` to the email of a target service account. Livepatch uses the primary resolved credentials to impersonate that account. + +## Required IAM permissions + +The service account used by the Livepatch Server requires permissions for standard operations and offline patch uploads: + +### Standard server operations + +For synchronising patches and serving them to clients, the service account must have read, write, and delete permissions on the bucket. Assigning the predefined role `roles/storage.objectUser` (or `roles/storage.objectAdmin`) at the bucket level satisfies these requirements: + +- `storage.objects.get` +- `storage.objects.create` +- `storage.objects.delete` +- `storage.objects.list` + +### Temporary upload credentials for the patch uploader + +When an administrator runs `livepatch-admin patch upload`, the Livepatch Server uses the Google Cloud Security Token Service (STS) to generate downscoped OAuth 2.0 bearer access tokens. These tokens are restricted via a Credential Access Boundary (CAB) to objects beginning with the `livepatch-` prefix within the bucket. + +To issue and accept these downscoped upload tokens: + +- The service account must hold `roles/storage.objectUser` on the bucket (both `storage.objects.create` and `storage.objects.delete` are required for overwrite support). +- The service account must have permission to perform token exchanges with Google Cloud STS. + +```{note} +**Upload token lifetime:** Downscoped access tokens issued by Google Cloud STS have a fixed duration of ~1 hour (3600 seconds) enforced by Google Cloud. Configuring `patch-storage.upload-credential-ttl` does not shorten or extend this cloud-enforced token lifetime. +``` -`patch-storage.gcs-credentials-file` and `patch-storage.gcs-credentials-json` are both optional; when both are omitted, Application Default Credentials are used instead. `patch-storage.gcs-impersonate-service-account` is also optional; when set, the resolved credentials are used to impersonate that service account instead of being used directly. diff --git a/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md b/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md index 8650a56..21933a0 100644 --- a/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md +++ b/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md @@ -8,12 +8,51 @@ myst: # Livepatch on-prem with IBM Cloud Object Storage patch storage +In IBM Cloud deployments, IBM Cloud Object Storage (COS) provides secure and scalable patch storage for Livepatch on-prem. + To configure this, follow these steps: -- Create an IBM Cloud Object Storage (COS) bucket in the preferred region (best if the region is the same as the deployment's). Care needs to be taken to make the bucket not publicly writable, as this would pose a significant security risk. -- Choose an authentication method: an IAM API key with a service instance ID, or the ambient VPC Instance Metadata Service if the VM is granted the required trusted profile. +- Create an IBM Cloud Object Storage bucket in your preferred region (ideally the same region as your deployment). Ensure the bucket is not publicly writable. +- Choose an authentication method for the Livepatch Server. +- Grant the required IAM access policies or trusted profiles. - Configure the relevant IBM [config options](/server/reference/platform/configuration.md). -Once this is configured, Livepatch will store and retrieve patch files from the COS bucket. +Once configured, Livepatch will store and retrieve patch files from the IBM COS bucket. + +## Supported authentication mechanisms + +Livepatch supports two IAM-based authentication methods for IBM Cloud Object Storage: + +1. **IAM API key with service instance ID:** Configure `patch-storage.ibm-api-key` and `patch-storage.ibm-service-instance-id`. +2. **VPC Instance Metadata Service (recommended for IBM Cloud VPC):** When running on an IBM Cloud Virtual Server Instance (VSI), omit the API key. Livepatch automatically queries the ambient VPC Instance Metadata Service (IMS) to authenticate. You can optionally bind the instance to a specific trusted profile via `patch-storage.ibm-trusted-profile-id`. + +```{note} +Legacy S3-compatible HMAC credentials (access key and secret key pairs) are unsupported for IBM COS in modern Livepatch releases. IBM Cloud IAM authentication is required. +``` + +## Required IAM access policies and trusted profiles + +Configure IBM Cloud IAM roles for regular patch operations and offline patch uploads: + +### Standard server operations + +For synchronising and serving patches, the Livepatch Server identity (API key or instance trusted profile) must hold the following roles on the COS bucket or service instance: + +- **Reader** (to retrieve objects and list bucket contents) +- **Writer** (or **ObjectWriter**, to write and delete patch files) + +### Temporary upload credentials for the patch uploader + +When an administrator runs `livepatch-admin patch upload`, the Livepatch Server uses the IBM Cloud IAM "assume" grant to exchange its primary identity for a temporary bearer token bound to a dedicated upload trusted profile. + +To configure this: + +1. Create a dedicated IAM Trusted Profile in IBM Cloud. +2. Assign the profile the **Writer** or **ObjectWriter** role scoped to the target COS bucket. +3. Configure trust rules allowing the Livepatch Server identity (the server's API key or its VPC VSI compute identity) to assume the profile. +4. Set `patch-storage.ibm-upload-trusted-profile-id` in your server configuration with the profile ID. + +```{note} +**Upload token lifetime:** Bearer tokens issued via the IBM Cloud IAM assume grant have a fixed session lifetime (typically 1 hour / 3600 seconds) governed by account-level IAM session settings. Configuring `patch-storage.upload-credential-ttl` does not alter this cloud-enforced duration. +``` -Credentials are resolved in the following order of preference: an IAM API key (`patch-storage.ibm-api-key`/`patch-storage.ibm-service-instance-id`), then, if not configured, the ambient VPC Instance Metadata Service (optionally selecting a trusted profile via `patch-storage.ibm-trusted-profile-id`). diff --git a/docs/server/reference/patch-storage/use-oracle-for-patch-storage.md b/docs/server/reference/patch-storage/use-oracle-for-patch-storage.md index a59f786..9979763 100644 --- a/docs/server/reference/patch-storage/use-oracle-for-patch-storage.md +++ b/docs/server/reference/patch-storage/use-oracle-for-patch-storage.md @@ -8,12 +8,42 @@ myst: # Livepatch on-prem with Oracle Cloud Infrastructure Object Storage patch storage +In Oracle Cloud Infrastructure (OCI) deployments, OCI Object Storage provides durable and scalable storage for Livepatch on-prem patches. + To configure this, follow these steps: -- Create an Object Storage bucket in the preferred region (best if the region is the same as the deployment's). Care needs to be taken to make the bucket not publicly writable, as this would pose a significant security risk. -- Choose an authentication method: an OCI config file/profile, or instance principal authentication if the compute instance is granted the required IAM policies. +- Create an Object Storage bucket in your preferred region and tenancy (ideally the same region as the Livepatch deployment). Ensure the bucket access tier is private. +- Choose an authentication method for the Livepatch Server. +- Grant the required OCI IAM policies to the instance dynamic group or user group. - Configure the relevant OCI [config options](/server/reference/platform/configuration.md). -Once this is configured, Livepatch will store and retrieve patch files from the OCI Object Storage bucket. +Once configured, Livepatch will store and retrieve patch files from the OCI Object Storage bucket. + +## Supported authentication mechanisms + +Livepatch supports two authentication methods for OCI Object Storage: + +1. **Instance principal authentication (recommended for OCI):** When running on an OCI compute instance, omit `patch-storage.oracle-config-file`. Livepatch automatically uses the ambient instance principal identity bound to the compute instance. +2. **OCI configuration file:** Set `patch-storage.oracle-config-file` to point to a valid OCI SDK/CLI configuration file containing user credentials, key path, tenancy OCID, and fingerprint. You can optionally specify `patch-storage.oracle-profile` to select a non-default profile within that file. + +## Required OCI IAM policies + +Configure OCI IAM policies for your instance dynamic group (when using instance principals) or user group (when using a config file): + +### Standard server operations + +For synchronising patches and delivering them to clients, the identity requires object read, write, and delete permissions. Add a policy statement such as: + +```text +allow dynamic-group to manage objects in compartment where target.bucket.name = '' +``` + +### Temporary upload credentials for the patch uploader + +When an administrator runs `livepatch-admin patch upload`, the Livepatch Server creates Pre-Authenticated Requests (PAR) with `AnyObjectWrite` permissions scoped to the `livepatch-` prefix. + +To permit PAR creation and subsequent uploads: + +- The IAM policy above (`manage objects`) covers the required permissions: `PAR_CREATE`, `OBJECT_CREATE`, and `OBJECT_INSPECT`. +- Upload credential lifetimes are bounded by `patch-storage.upload-credential-ttl` (defaults to 15 minutes). -`patch-storage.oracle-config-file` (and `patch-storage.oracle-profile`) are optional; when omitted, instance principal authentication is used instead, bound to the OCI compute instance the server runs on. diff --git a/docs/server/reference/patch-storage/use-s3-for-patch-storage.md b/docs/server/reference/patch-storage/use-s3-for-patch-storage.md index 5f80067..7bd551d 100644 --- a/docs/server/reference/patch-storage/use-s3-for-patch-storage.md +++ b/docs/server/reference/patch-storage/use-s3-for-patch-storage.md @@ -4,25 +4,59 @@ myst: description: "Use S3 for patch storage - learn about this topic in Livepatch on-prem." --- - (server-reference-livepatch-on-prem-with-aws-s3-patch-storage)= # Livepatch on-prem with AWS S3 patch storage -In an AWS EC2 deployment of Livepatch on-prem, it makes sense to use S3 for patch storage if the expected number of client machines is high (over 2000). +In an AWS EC2 or Kubernetes deployment of Livepatch on-prem, AWS S3 (or an S3-compatible service such as MinIO or Ceph) provides scalable and durable patch storage. To configure this, follow these steps: -- Create an S3 bucket in the preferred region (best if the region is the same as the deployment's). Care needs to be taken to make the bucket not world-writable as this would pose a significant security risk. -- Create an access point with permissions to perform operations on that S3 bucket. -- Create a programmatic IAM user account with permissions to perform S3 operations. -- Configure the relevant S3 [config options](/server/reference/platform/configuration.md) +- Create an S3 bucket in your preferred region (ideally the same region as your Livepatch deployment). Ensure the bucket is not publicly writable. +- Choose an authentication mechanism for the Livepatch Server. +- Grant the required IAM permissions to the server credentials. +- Configure the relevant S3 [config options](/server/reference/platform/configuration.md). -Once this is configured, Livepatch will store and retrieve patch files from the S3 bucket. +Once configured, Livepatch will store and retrieve patch files from the S3 bucket. -A further improvement is to configure Livepatch on-prem to serve patches from the S3 bucket directly. For that public http access needs to be allowed to that bucket. Set your server's [URL template config](/server/reference/platform/configuration.md) to something resembling: +## Supported authentication mechanisms + +Livepatch supports multiple authentication methods for AWS S3 and S3-compatible storage: + +1. **Ambient IAM credentials (recommended for AWS):** When running on AWS EC2 or EKS, Livepatch automatically retrieves credentials from the ambient environment (EC2 instance metadata or IAM Roles for Service Accounts - IRSA). Leave `patch-storage.s3-access-key` and `patch-storage.s3-secret-key` blank. +2. **Static IAM access keys:** Set `patch-storage.s3-access-key` and `patch-storage.s3-secret-key` explicitly. +3. **STS AssumeRole:** Configure `patch-storage.s3-assume-role-arn` to have Livepatch assume a dedicated IAM role using its primary credentials. You can configure `patch-storage.s3-assume-role-duration` (defaults to 15 minutes) to specify the session lifetime. Note that the target IAM role's `MaxSessionDuration` must be configured at or above this value (AWS default is 1 hour). +4. **S3-compatible storage (MinIO, Ceph):** Set `patch-storage.s3-endpoint` to the service URL, set `patch-storage.s3-use-path-style=true`, and toggle `patch-storage.s3-secure` depending on TLS support. + +## Required IAM permissions + +The credentials used by the Livepatch Server require permissions for two operational roles: + +### Standard server operations + +For synchronising patches from upstream and serving them to clients, the credentials must have: + +- `s3:GetObject` on `arn:aws:s3:::/*` +- `s3:PutObject` on `arn:aws:s3:::/*` +- `s3:DeleteObject` on `arn:aws:s3:::/*` +- `s3:ListBucket` on `arn:aws:s3:::` + +### Temporary upload credentials for the patch uploader + +When an administrator runs `livepatch-admin patch upload`, the Livepatch Server generates temporary AWS SigV4 Presigned POST policies scoped to the `livepatch-*` object prefix. + +To generate valid upload grants: + +- The credentials must have `s3:PutObject` on `arn:aws:s3:::/livepatch-*` (or bucket-wide). +- If using `patch-storage.s3-assume-role-arn`, the primary credentials must have `sts:AssumeRole` on the target role ARN. +- Upload credential lifetimes are bounded by `patch-storage.upload-credential-ttl` (default 15 minutes) or the remaining STS session lifetime. + +## Direct patch delivery from S3 + +To serve patches directly to clients from S3 rather than proxying bytes through the Livepatch Server, set your server's [URL template config](/server/reference/platform/configuration.md) to: ``` -https://.amazonaws.com/{filaname} +https://.s3..amazonaws.com/{filename} ``` + \ No newline at end of file diff --git a/docs/server/reference/patch-storage/use-swift-for-patch-storage.md b/docs/server/reference/patch-storage/use-swift-for-patch-storage.md new file mode 100644 index 0000000..d61894d --- /dev/null +++ b/docs/server/reference/patch-storage/use-swift-for-patch-storage.md @@ -0,0 +1,72 @@ +--- +myst: + html_meta: + description: "Use OpenStack Swift for patch storage - learn about this topic in Livepatch on-prem." +--- + +(server-reference-livepatch-on-prem-with-swift-patch-storage)= + +# Livepatch on-prem with OpenStack Swift patch storage + +In OpenStack cloud environments or deployments with existing Swift object storage, OpenStack Swift provides scalable, multi-unit patch storage for Livepatch on-prem. + +To configure this, follow these steps: + +- Create a Swift container for Livepatch patches. Ensure the container is not publicly readable or writable. +- Configure Keystone credentials for the Livepatch service account. +- Provision a TempURL key on the Swift account or container if using the patch uploader. +- Configure the relevant Swift [config options](/server/reference/platform/configuration.md). + +Once configured, Livepatch will store and retrieve patch files from the Swift container. + +## Supported authentication mechanisms + +Livepatch authenticates to OpenStack Swift using OpenStack Identity (Keystone v3): + +- `patch-storage.swift-auth-url`: The Keystone authentication URL (for example, `https://keystone.example.com:5000/v3`). +- `patch-storage.swift-username`: Username of the service account. +- `patch-storage.swift-api-key`: User password or API key. +- `patch-storage.swift-domain`: Keystone domain (for example, `default`). +- `patch-storage.swift-tenant`: OpenStack project/tenant name. +- `patch-storage.swift-container`: Target container name. +- `patch-storage.swift-region`: OpenStack region (optional). + +## Required permissions and TempURL configuration + +Configure permissions for standard operations and offline patch uploads: + +### Standard server operations + +The Keystone user must have read, write, and delete permissions on the designated container (typically by assigning the `member` or `admin` role in the project). + +### Temporary upload credentials for the patch uploader + +When an administrator runs `livepatch-admin patch upload`, the Livepatch Server issues temporary, prefix-scoped Swift TempURLs (`temp_url_prefix=livepatch-`) that allow direct uploads to the container without exposing the server's long-lived credentials. + +To generate valid TempURL signatures: + +1. Provision a TempURL key on the Swift account or container out-of-band using the OpenStack Swift CLI or API: + + ```bash + # Set at the container level: + swift post --meta "Temp-URL-Key:" + + # Or at the account level: + swift post --meta "Temp-URL-Key:" + ``` + +2. Record the identical secret key in the Livepatch Server configuration: + + ```bash + # Juju charm: + juju config livepatch patch-storage.swift-temp-url-key="" + + # Snap: + sudo snap set canonical-livepatch-server lp.patch-storage.swift-temp-url-key="" + ``` + +```{important} +OpenStack Swift does not allow retrieving existing TempURL keys via its API for security reasons. You must set the key out-of-band and configure the exact matching value in `patch-storage.swift-temp-url-key`. +``` + +TempURL validity duration is controlled by `patch-storage.upload-credential-ttl` (defaults to 15 minutes). diff --git a/docs/server/reference/platform/configuration.md b/docs/server/reference/platform/configuration.md index 34d4489..a05f0af 100644 --- a/docs/server/reference/platform/configuration.md +++ b/docs/server/reference/platform/configuration.md @@ -161,6 +161,7 @@ The following values configure how the server manages patch storage. See the [pa | `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 `patch-storage.s3-access-key`). | `string` | | `patch-storage.s3-assume-role-arn` | IAM role ARN to assume via STS, using the resolved credentials above (optional). | `string` | +| `patch-storage.s3-assume-role-duration` | How long an assumed role's STS session (and any upload credentials issued from it) stays valid before it must be refreshed; only applies when `patch-storage.s3-assume-role-arn` is set. Defaults to the AWS SDK's 15-minute default when unset. AWS STS rejects requests exceeding the target IAM role's own `MaxSessionDuration` setting (AWS default is 1 hour, and can be raised up to 12 hours), so that role setting must independently permit any configured value (optional). | `string` | | `patch-storage.gcs-bucket` | Google Cloud Storage bucket for storing patches. | `string` | | `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 `patch-storage.gcs-credentials-file`). | `string` | @@ -179,11 +180,14 @@ The following values configure how the server manages patch storage. See the [pa | `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 `patch-storage.ibm-api-key`. | `string` | | `patch-storage.ibm-trusted-profile-id` | Trusted profile ID to assume via the ambient VPC Instance Metadata Service (optional; defaults to the instance's default trusted profile). | `string` | +| `patch-storage.ibm-upload-trusted-profile-id` | Dedicated IAM Trusted Profile ID to assume when issuing temporary upload credentials for `livepatch-admin patch upload` (optional). | `string` | | `patch-storage.oracle-bucket` | OCI Object Storage bucket for storing patches. | `string` | | `patch-storage.oracle-namespace` | OCI Object Storage namespace. | `string` | | `patch-storage.oracle-region` | OCI region. | `string` | | `patch-storage.oracle-config-file` | Path to an OCI config file (optional; defaults to instance principal authentication). | `string` | | `patch-storage.oracle-profile` | Profile to use within `patch-storage.oracle-config-file` (optional). | `string` | +| `patch-storage.swift-temp-url-key` | OpenStack Swift account or container TempURL key, used to sign scoped, time-limited upload credentials for `livepatch-admin patch upload`. Because Swift never returns a previously set key, it must be provisioned out-of-band and configured here with the identical secret key (optional). | `string` | +| `patch-storage.upload-credential-ttl` | Duration that temporary, upload-only credentials issued by the server remain valid for cloud storage backends (`s3`, `gcs`, `azure`, `ibm`, `oracle`, `swift`) during `livepatch-admin patch upload` (optional; defaults to `15m`). Has no effect for `filesystem` and `postgres`, which route uploads through the authenticated server API. Note that GCS and IBM COS issue bearer tokens with a cloud-enforced fixed duration of ~1 hour regardless of this setting. | `string` | ### Patch cache @@ -211,7 +215,9 @@ The following values configure how the server synchronises patches from an upstr | `patch-sync.send-machine-reports` | Whether to send machine reports during synchronisation. | `bool` | | `patch-sync.token` | Token for authenticating with an upstream Livepatch Server. | `string` | | `patch-sync.upstream-url` | URL of the upstream server to pull patches from. | `string` | -| `patch-sync.sync-tiers` | Whether to synchronise tiers from the upstream server. | `bool` | +| `patch-sync.sync-tiers` | Whether to mirror the entire upstream tier structure locally instead of synchronising a single tier. Mutually exclusive with `patch-sync.upstream-tier` and `patch-sync.ingress-tier`; when enabled, both are ignored: patches are downloaded from (and synced to) the stable tier, which upstream always holds as the superset of every lower tier's patches, and the already-mirrored tier structure makes each one visible in whichever lower local tiers it belongs to. | `bool` | +| `patch-sync.upstream-tier` | The tier requested from the upstream server. Only used when `patch-sync.sync-tiers` is `false`; defaults to `stable` when unset, since on-prem sync is only available to paid tokens, which upstream always serves from the stable tier. | `string` | +| `patch-sync.ingress-tier` | The local tier into which synced patches are stored and served. Only used when `patch-sync.sync-tiers` is `false`; defaults to the first locally configured tier (for example `edge` or `stable`) when unset. | `string` | | `patch-sync.proxy.enabled` | Whether to use a proxy when synchronising patches. | `bool` | | `patch-sync.proxy.http` | HTTP proxy URL. | `string` | | `patch-sync.proxy.https` | HTTPS proxy URL. | `string` | From 42a406829d198288eb4f4de74c96746573dc8764 Mon Sep 17 00:00:00 2001 From: Kunal Mohan Date: Tue, 13 Oct 2026 14:46:04 +0530 Subject: [PATCH 02/11] address review comments --- .../deployment/upgrade-a-deployment.md | 17 ++--------------- .../distribute-patches-offline.md | 5 +++-- docs/server/reference/patch-storage/index.md | 12 ++++++------ .../patch-storage/use-s3-for-patch-storage.md | 2 +- docs/server/reference/platform/configuration.md | 6 +++--- 5 files changed, 15 insertions(+), 27 deletions(-) diff --git a/docs/server/how-to-guides/deployment/upgrade-a-deployment.md b/docs/server/how-to-guides/deployment/upgrade-a-deployment.md index f9ebe3d..e445697 100644 --- a/docs/server/how-to-guides/deployment/upgrade-a-deployment.md +++ b/docs/server/how-to-guides/deployment/upgrade-a-deployment.md @@ -19,7 +19,7 @@ Depending on whether your deployment uses Juju charms or standalone snaps, follo In charmed deployments, upgrade each component application using `juju refresh`: ```bash -juju refresh livepatch +juju refresh canonical-livepatch-server-k8s --channel= --revision= ``` If you manage supporting infrastructure services via Juju, upgrade them as required: @@ -67,22 +67,9 @@ For snap deployments, database migrations run automatically during service start You can also run schema migrations manually using the snap command: ```bash -sudo canonical-livepatch-server.schema-upgrade +sudo canonical-livepatch-server.schema-upgrade upgrade ``` -Check the service logs to verify successful migration: - -```bash -sudo journalctl -u snap.canonical-livepatch-server.* -n 100 --no-pager -``` - -### Key schema migrations - -Recent Livepatch Server releases introduce database improvements that support the patch uploader and offline distribution workflows: - -- **Migration 086 (`patch_file_tier.publish_time`)**: Adds `publish_time` and `sync_time` tracking to patch tiers, recording the exact point in time when each patch was made available. -- **Migration 088 (`patch_file_filename_index`)**: Adds a dedicated B-tree index on `patch_file.filename` to significantly accelerate duplicate detection and batch lookups during patch uploads. - ## Step 3: Backfill publish timestamps with metadata-only sync In earlier Livepatch Server releases, patch tiers did not record the original upstream publish timestamp from Canonical (or initialized it to the local database insertion time). diff --git a/docs/server/how-to-guides/patch-management/distribute-patches-offline.md b/docs/server/how-to-guides/patch-management/distribute-patches-offline.md index b69aee4..031c656 100644 --- a/docs/server/how-to-guides/patch-management/distribute-patches-offline.md +++ b/docs/server/how-to-guides/patch-management/distribute-patches-offline.md @@ -17,7 +17,7 @@ Livepatch on-premises deployments can operate in fully air-gapped environments w ## Prerequisites - **On the internet-connected system:** - - An installation of the Livepatch administration tool (`livepatch-admin`). + - An installation of the Livepatch administration tool with the `livepatch-admin` alias configured as described in the [administration tool setup guide](/server/how-to-guides/security/setup-administration-tool.md). - An Ubuntu Pro token entitled to Livepatch, attached to the system or available as a machine token. - Outbound HTTPS network access to `https://livepatch.canonical.com`. @@ -93,7 +93,8 @@ Mount or copy the directory onto a workstation or bastion system with network co Log in to your on-premises Livepatch Server with administrator credentials: ```bash -livepatch-admin login https://livepatch.internal.example.com + export LIVEPATCH_URL=https://livepatch.internal.example.com + livepatch-admin login --auth : ``` ### Run the upload command diff --git a/docs/server/reference/patch-storage/index.md b/docs/server/reference/patch-storage/index.md index 1511e71..5d8f2e9 100644 --- a/docs/server/reference/patch-storage/index.md +++ b/docs/server/reference/patch-storage/index.md @@ -13,12 +13,12 @@ Livepatch Server supports several different drivers for storing patch files down 1. **Local filesystem**: Stores patch files directly on disk. Ideal for single-unit deployments. 2. **PostgreSQL**: Stores patch files as Large Objects directly inside the PostgreSQL database. Suitable for multi-unit clusters without external cloud dependencies. -3. **AWS S3**: Highly scalable object storage for AWS or S3-compatible environments (such as MinIO or Ceph). -4. **Google Cloud Storage (GCS)**: Scalable object storage for Google Cloud Platform. -5. **Azure Blob Storage**: Durable container storage for Microsoft Azure. -6. **IBM Cloud Object Storage (COS)**: Resilient bucket storage for IBM Cloud. -7. **Oracle Cloud Infrastructure (OCI) Object Storage**: High-performance object storage for OCI. -8. **OpenStack Swift**: Scalable object storage for OpenStack environments. +3. **AWS S3**: Object storage for AWS or S3-compatible environments (such as MinIO or Ceph). +4. **Google Cloud Storage (GCS)**: Object storage for Google Cloud Platform. +5. **Azure Blob Storage**: Container storage for Microsoft Azure. +6. **IBM Cloud Object Storage (COS)**: Bucket storage for IBM Cloud. +7. **Oracle Cloud Infrastructure (OCI) Object Storage**: Object storage for OCI. +8. **OpenStack Swift**: Object storage for OpenStack environments. The filesystem patch store is easiest to deploy and suits single-unit configurations. However, when scaling out the Livepatch Server across multiple load-balanced units, use PostgreSQL or one of the object storage backends (S3, GCS, Azure, IBM COS, OCI, Swift). diff --git a/docs/server/reference/patch-storage/use-s3-for-patch-storage.md b/docs/server/reference/patch-storage/use-s3-for-patch-storage.md index 7bd551d..8b321dd 100644 --- a/docs/server/reference/patch-storage/use-s3-for-patch-storage.md +++ b/docs/server/reference/patch-storage/use-s3-for-patch-storage.md @@ -53,7 +53,7 @@ To generate valid upload grants: ## Direct patch delivery from S3 -To serve patches directly to clients from S3 rather than proxying bytes through the Livepatch Server, set your server's [URL template config](/server/reference/platform/configuration.md) to: + To serve patches directly to clients from S3 rather than proxying bytes through the Livepatch Server, enable `server.redirect_downloads` and set your server's [URL template config](/server/reference/platform/configuration.md) to a client-readable endpoint. This static template cannot sign requests: a private S3 bucket needs an authenticated delivery mechanism, or client downloads will fail with 403. For publicly readable objects, use: ``` https://.s3..amazonaws.com/{filename} diff --git a/docs/server/reference/platform/configuration.md b/docs/server/reference/platform/configuration.md index a05f0af..86ed353 100644 --- a/docs/server/reference/platform/configuration.md +++ b/docs/server/reference/platform/configuration.md @@ -161,7 +161,7 @@ The following values configure how the server manages patch storage. See the [pa | `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 `patch-storage.s3-access-key`). | `string` | | `patch-storage.s3-assume-role-arn` | IAM role ARN to assume via STS, using the resolved credentials above (optional). | `string` | -| `patch-storage.s3-assume-role-duration` | How long an assumed role's STS session (and any upload credentials issued from it) stays valid before it must be refreshed; only applies when `patch-storage.s3-assume-role-arn` is set. Defaults to the AWS SDK's 15-minute default when unset. AWS STS rejects requests exceeding the target IAM role's own `MaxSessionDuration` setting (AWS default is 1 hour, and can be raised up to 12 hours), so that role setting must independently permit any configured value (optional). | `string` | +| `patch-storage.s3-assume-role-duration` | How long an assumed role's STS session stays valid before it must be refreshed; only applies when `patch-storage.s3-assume-role-arn` is set. Defaults to `15m` when unset. AWS STS rejects requests exceeding the target IAM role's `MaxSessionDuration` (1 hour by default, configurable up to 12 hours). | `string` | | `patch-storage.gcs-bucket` | Google Cloud Storage bucket for storing patches. | `string` | | `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 `patch-storage.gcs-credentials-file`). | `string` | @@ -215,8 +215,8 @@ The following values configure how the server synchronises patches from an upstr | `patch-sync.send-machine-reports` | Whether to send machine reports during synchronisation. | `bool` | | `patch-sync.token` | Token for authenticating with an upstream Livepatch Server. | `string` | | `patch-sync.upstream-url` | URL of the upstream server to pull patches from. | `string` | -| `patch-sync.sync-tiers` | Whether to mirror the entire upstream tier structure locally instead of synchronising a single tier. Mutually exclusive with `patch-sync.upstream-tier` and `patch-sync.ingress-tier`; when enabled, both are ignored: patches are downloaded from (and synced to) the stable tier, which upstream always holds as the superset of every lower tier's patches, and the already-mirrored tier structure makes each one visible in whichever lower local tiers it belongs to. | `bool` | -| `patch-sync.upstream-tier` | The tier requested from the upstream server. Only used when `patch-sync.sync-tiers` is `false`; defaults to `stable` when unset, since on-prem sync is only available to paid tokens, which upstream always serves from the stable tier. | `string` | + | `patch-sync.sync-tiers` | Whether to mirror the upstream tier structure and patch-to-tier assignments locally instead of synchronising a single tier. Enabling this removes existing local tiers and disables local tier management. When enabled, `patch-sync.upstream-tier` and `patch-sync.ingress-tier` are ignored. | `bool` | + | `patch-sync.upstream-tier` | The tier requested from the upstream server when `patch-sync.sync-tiers` is `false`; defaults to `stable` when unset. For on-premises upstream servers, the sync token may restrict the tier that can be retrieved. | `string` | | `patch-sync.ingress-tier` | The local tier into which synced patches are stored and served. Only used when `patch-sync.sync-tiers` is `false`; defaults to the first locally configured tier (for example `edge` or `stable`) when unset. | `string` | | `patch-sync.proxy.enabled` | Whether to use a proxy when synchronising patches. | `bool` | | `patch-sync.proxy.http` | HTTP proxy URL. | `string` | From 5866aa9b5756a71f5195860da336abca86441e3c Mon Sep 17 00:00:00 2001 From: Kunal Mohan Date: Tue, 13 Oct 2026 14:49:45 +0530 Subject: [PATCH 03/11] docs: document patch download metadata flags and auto schema migrations --- .../how-to-guides/deployment/upgrade-a-deployment.md | 12 +++--------- .../patch-management/distribute-patches-offline.md | 2 ++ 2 files changed, 5 insertions(+), 9 deletions(-) diff --git a/docs/server/how-to-guides/deployment/upgrade-a-deployment.md b/docs/server/how-to-guides/deployment/upgrade-a-deployment.md index e445697..ed11fd2 100644 --- a/docs/server/how-to-guides/deployment/upgrade-a-deployment.md +++ b/docs/server/how-to-guides/deployment/upgrade-a-deployment.md @@ -40,11 +40,11 @@ sudo snap refresh canonical-livepatch-server ## Step 2: Apply database schema upgrades -When upgrading across major or minor Livepatch Server releases, new database migrations may be required. +When upgrading across Livepatch Server releases, database schema migrations run automatically during service startup for both charmed and snap deployments. The migration runner acquires an advisory lock on PostgreSQL to ensure that multi-unit or clustered deployments upgrade safely without race conditions. ### Charmed deployments -When a schema upgrade is required, the Livepatch application enters a blocked status visible in `juju status`. Run the `schema-upgrade` action on the leader unit: +In charmed deployments, database migrations run automatically during service startup after a refresh. If the Livepatch application enters a blocked status requiring manual intervention, run the `schema-upgrade` action on the leader unit: ```bash juju run livepatch/leader schema-upgrade --wait @@ -62,13 +62,7 @@ juju run livepatch/ restart --wait ### Snap deployments -For snap deployments, database migrations run automatically during service startup when the updated snap starts. The migration runner acquires an advisory lock on PostgreSQL to ensure that multi-unit or clustered deployments upgrade safely without race conditions. - -You can also run schema migrations manually using the snap command: - -```bash -sudo canonical-livepatch-server.schema-upgrade upgrade -``` +For snap deployments, database migrations also run automatically during service startup when the updated snap starts. ## Step 3: Backfill publish timestamps with metadata-only sync diff --git a/docs/server/how-to-guides/patch-management/distribute-patches-offline.md b/docs/server/how-to-guides/patch-management/distribute-patches-offline.md index 031c656..486db8b 100644 --- a/docs/server/how-to-guides/patch-management/distribute-patches-offline.md +++ b/docs/server/how-to-guides/patch-management/distribute-patches-offline.md @@ -58,6 +58,8 @@ livepatch-admin patch download --patch-dir /tmp/livepatch-export --tier stable Optional download flags include: - `--patch-dir `: Destination directory for downloaded patches (required). +- `--metadata-file `: Name of the metadata manifest file written inside `--patch-dir` (defaults to `canonical-livepatch-patch-metadata.json`). +- `--metadata-only`: Download only the metadata manifest file without downloading patch files. - `--kernel `: Download patches for kernels matching or newer than the specified version prefix (for example, `5.15.0`). - `--arch `: Restrict downloads to a specific CPU architecture. - `--flavor `: Restrict downloads to a specific kernel flavour. From 68c4469bc40c2cd520fa342f1ed67be808dc8655 Mon Sep 17 00:00:00 2001 From: Kunal Mohan Date: Fri, 16 Oct 2026 16:27:58 +0530 Subject: [PATCH 04/11] update docs --- docs/.custom_wordlist.txt | 3 + ...re-the-livepatch-client-with-cloud-init.md | 4 +- .../deployment/deploy-via-juju.md | 4 +- .../deployment/deploy-via-snap.md | 4 +- ...om-reactive-charm-to-k8s-operator-charm.md | 4 +- .../migrate-from-reactive-charm-to-snap.md | 4 +- .../public-clouds/deploying-on-aws.md | 13 ++-- .../public-clouds/deploying-on-azure.md | 19 ++++-- .../deployment/upgrade-a-deployment.md | 8 +-- .../generate-patch-health-report.md | 2 +- .../operations/manage-fleet-of-machines.md | 2 +- ...se-livepatch-client-with-on-prem-server.md | 2 +- .../chain-livepatch-servers.md | 2 +- .../distribute-patches-offline.md | 46 ++++++++------ .../patch-management/fetch-patches.md | 4 +- .../security/setup-administration-tool.md | 25 +++++++- .../how-to-guides/security/setup-tls.md | 4 +- .../patch-management/patch-management.md | 8 +-- .../use-azure-for-patch-storage.md | 19 +++++- .../use-gcs-for-patch-storage.md | 60 +++++++++++++++++-- .../patch-storage/use-s3-for-patch-storage.md | 49 ++++++++++++++- .../reference/platform/configuration.md | 8 +-- .../reference/telemetry/machine-reports.md | 2 +- docs/server/tutorial/livepatch-and-lxd.md | 4 +- .../server/tutorial/livepatch-and-microk8s.md | 8 +-- 25 files changed, 237 insertions(+), 71 deletions(-) diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index 251d803..1bdb794 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -16,6 +16,7 @@ blocklisted blocklisting boolean bugfixes +burstable Canonical('s)? Charmcraft charmstore @@ -30,6 +31,7 @@ docstrings? downloader Downloader downscoped +downscoping dvipng enablement Enablement @@ -92,6 +94,7 @@ openapi otf patchstore PDF +permissionless plaintext plantuml PNG diff --git a/docs/client/how-to-guides/configuration/enable-and-configure-the-livepatch-client-with-cloud-init.md b/docs/client/how-to-guides/configuration/enable-and-configure-the-livepatch-client-with-cloud-init.md index 2a5c0fe..cce9b9a 100644 --- a/docs/client/how-to-guides/configuration/enable-and-configure-the-livepatch-client-with-cloud-init.md +++ b/docs/client/how-to-guides/configuration/enable-and-configure-the-livepatch-client-with-cloud-init.md @@ -75,13 +75,13 @@ Any configuration values that do not require changes should be removed from the The cloud-init module for using the client with an on-premises Livepatch Server is similar to the previous module. Instead of the Pro token, use an auth token generated by the admin tool: ```bash -canonical-livepatch-server-admin.livepatch-admin auth-token [flags] +sudo canonical-livepatch-server-admin.livepatch-admin auth-token [flags] ``` For example: ```bash -canonical-livepatch-server-admin.livepatch-admin auth-token test edge +sudo canonical-livepatch-server-admin.livepatch-admin auth-token test edge ``` This command outputs an auth token that can be used with client machines to apply patches in the `edge` tier. diff --git a/docs/server/how-to-guides/deployment/deploy-via-juju.md b/docs/server/how-to-guides/deployment/deploy-via-juju.md index db18e35..2494f2b 100644 --- a/docs/server/how-to-guides/deployment/deploy-via-juju.md +++ b/docs/server/how-to-guides/deployment/deploy-via-juju.md @@ -129,7 +129,7 @@ Once this has been done, the Livepatch admin tool can be used to authenticate: ``` export LIVEPATCH_URL=http(s)://{haproxy url} -livepatch-admin login -a [username:password] +sudo livepatch-admin login -a [username:password] ``` ### 5. Download patches @@ -139,7 +139,7 @@ The final step before attaching client machines to the server is to download pat To download patches, run: ``` -livepatch-admin sync trigger --wait +sudo livepatch-admin sync trigger --wait ``` ## Enable machine status reporting diff --git a/docs/server/how-to-guides/deployment/deploy-via-snap.md b/docs/server/how-to-guides/deployment/deploy-via-snap.md index 8a67f9a..b3f9f0a 100644 --- a/docs/server/how-to-guides/deployment/deploy-via-snap.md +++ b/docs/server/how-to-guides/deployment/deploy-via-snap.md @@ -121,7 +121,7 @@ sudo snap set canonical-livepatch-server lp.auth.basic.enabled=true Finally, log in with the administrator tool, assuming the example username and password have been used: ``` -canonical-livepatch-server-admin.livepatch-admin login -a admin:admin123 +sudo canonical-livepatch-server-admin.livepatch-admin login -a admin:admin123 ``` ## Synchronize with hosted Livepatch @@ -129,7 +129,7 @@ canonical-livepatch-server-admin.livepatch-admin login -a admin:admin123 Once the on-premises Livepatch Server is running and fully configured, synchronize patches from hosted Livepatch into the server. Run the following within the administrator tool: ``` -canonical-livepatch-server-admin.livepatch-admin sync trigger +sudo canonical-livepatch-server-admin.livepatch-admin sync trigger ``` To set the server to automatically sync patches from Canonical's servers every 12 hours, run: diff --git a/docs/server/how-to-guides/deployment/migrate-from-reactive-charm-to-k8s-operator-charm.md b/docs/server/how-to-guides/deployment/migrate-from-reactive-charm-to-k8s-operator-charm.md index a7e5654..0d606bd 100644 --- a/docs/server/how-to-guides/deployment/migrate-from-reactive-charm-to-k8s-operator-charm.md +++ b/docs/server/how-to-guides/deployment/migrate-from-reactive-charm-to-k8s-operator-charm.md @@ -251,7 +251,7 @@ If the same database is being used for patch storage as for the main Livepatch S After migrating the database, ensure access to the patches by querying for available patches via the admin tool: ```bash -canonical-livepatch-server-admin.livepatch-admin storage patches +sudo canonical-livepatch-server-admin.livepatch-admin storage patches ``` If the migration was successful, a list of patch payloads for each patch version will be displayed. @@ -263,7 +263,7 @@ The `swift` and `s3` patch storage types imply that the patches are stored in a When using object storage, such as AWS S3 or a Swift bucket, relevant connection parameters have been copied over with the configuration migration. The only required action is to refresh the patch storage: ```bash -canonical-livepatch-server-admin.livepatch-admin storage refresh +sudo canonical-livepatch-server-admin.livepatch-admin storage refresh ``` This adds patches found in storage to the distribution records in the Livepatch database. \ No newline at end of file diff --git a/docs/server/how-to-guides/deployment/migrate-from-reactive-charm-to-snap.md b/docs/server/how-to-guides/deployment/migrate-from-reactive-charm-to-snap.md index f7b7f29..064d430 100644 --- a/docs/server/how-to-guides/deployment/migrate-from-reactive-charm-to-snap.md +++ b/docs/server/how-to-guides/deployment/migrate-from-reactive-charm-to-snap.md @@ -233,8 +233,8 @@ The `livepatch-admin` tool is useful for syncing patches from the upstream Livep 1. [Set up the livepatch-admin tool](/server/how-to-guides/security/setup-administration-tool.md) 2. [Fetch patches from the hosted Livepatch Server](/server/how-to-guides/patch-management/fetch-patches.md) -Once the patches have been downloaded, run `livepatch-admin storage refresh` to sync the patch storage and patch data in the database. +Once the patches have been downloaded, run `sudo livepatch-admin storage refresh` to sync the patch storage and patch data in the database. ```{note} -It is recommended to run `livepatch-admin storage refresh` after the database and patch migration, irrespective of the type of patch storage and how the migration was done, as it helps confirm that both the patch data in the database and the patches in the storage are in sync. +It is recommended to run `sudo livepatch-admin storage refresh` after the database and patch migration, irrespective of the type of patch storage and how the migration was done, as it helps confirm that both the patch data in the database and the patches in the storage are in sync. ``` \ No newline at end of file diff --git a/docs/server/how-to-guides/deployment/public-clouds/deploying-on-aws.md b/docs/server/how-to-guides/deployment/public-clouds/deploying-on-aws.md index a99548d..fc6edce 100644 --- a/docs/server/how-to-guides/deployment/public-clouds/deploying-on-aws.md +++ b/docs/server/how-to-guides/deployment/public-clouds/deploying-on-aws.md @@ -20,8 +20,13 @@ To set up the Livepatch Server on AWS using an S3 bucket for patch storage, the * An Ubuntu Pro token stored in the AWS Secrets Vault. * An S3 bucket with the `s3:GetObject` policy. The bucket must be public for clients to download patches, but the policy can be restricted to a range of IP addresses. * An IAM role with the `AWSSecretsManagerClientReadOnlyAccess` role and `AmazonS3ReadOnlyAccess` role. -* An IAM user with Allow effects for the actions `s3:PutObject`, `s3:ListBucket`, and `s3:GetObject` roles for the S3 bucket. +* An IAM user with Allow effects for the actions `s3:PutObject`, `s3:ListBucket`, `s3:GetObject`, and `s3:DeleteObject` roles for the S3 bucket. `s3:DeleteObject` is required for patch removal and uploader rollback. * A secret entry for the IAM user with key-value pairs `S3AccessKey` (for the S3 access key) and `SecretAccessKey` (for the S3 secret key). + +```{note} +The cloud-init template below uses static IAM access keys for the S3 bucket. As an alternative, the server can use the EC2 instance profile attached to the launch template (recommended) or STS AssumeRole. See the [authentication mechanisms](/server/reference/patch-storage/use-s3-for-patch-storage.md#supported-authentication-mechanisms) in the S3 reference for details. +``` + * A load balancer set to internet-facing. * An auto-scaling group using the launch template. * A security group to allow all internet access for HTTP and HTTPS. @@ -66,9 +71,8 @@ write_files: # S3 variables export S3_SECRET_ID= export S3BUCKET= - export S3ENDPOINT= - export S3REGION= - export URLTEMPLATE=https://.s3-.amazonaws.com/{filename} + export S3REGION= + export URLTEMPLATE=https://.s3..amazonaws.com/{filename} - path: /etc/livepatch/database_url permissions: "0600" owner: root:root @@ -135,7 +139,6 @@ runcmd: lp.patch-storage.type=s3 \ lp.server.url-template=$URLTEMPLATE \ lp.patch-storage.s3-bucket="$S3BUCKET" \ - lp.patch-storage.s3-endpoint="$S3ENDPOINT" \ lp.patch-storage.s3-region="$S3REGION" \ lp.patch-storage.s3-secure=true \ lp.patch-storage.s3-access-key="$(cat /etc/livepatch/s3 | jq -r '.S3AccessKey' )" \ diff --git a/docs/server/how-to-guides/deployment/public-clouds/deploying-on-azure.md b/docs/server/how-to-guides/deployment/public-clouds/deploying-on-azure.md index 17f4de5..80dc29c 100644 --- a/docs/server/how-to-guides/deployment/public-clouds/deploying-on-azure.md +++ b/docs/server/how-to-guides/deployment/public-clouds/deploying-on-azure.md @@ -13,7 +13,7 @@ This section details how to deploy the Livepatch Server snap in auto-scaling con ## Required resources -To set up the Livepatch Server on Azure using a filesystem or PostgreSQL (Azure Blob Storage is not yet supported) for patch storage, the following are required: +To set up the Livepatch Server on Azure using an Azure Blob Storage container for patch storage, the following are required. For Blob Storage configuration, see [Use Azure for patch storage](/server/reference/patch-storage/use-azure-for-patch-storage.md). * A VNet with subnets for VMSS, Application Gateway, and PostgreSQL DB. * An Azure Key Vault with access enabled for the VMSS subnet of the VNet. @@ -21,7 +21,7 @@ To set up the Livepatch Server on Azure using a filesystem or PostgreSQL (Azure * A Virtual Machine Scale Set (VMSS) with an instance type with at least two vCPUs and 4 GB RAM, with a cloud-init configuration file as custom data. * An Ubuntu Pro token stored as a secret in Azure Key Vault. * Livepatch Server admin credentials stored in Azure Key Vault Secrets in `:` format. -* A Managed Identity with the `Key Vault Secrets User` role in Azure Key Vault. +* A Managed Identity with the `Key Vault Secrets User` role in Azure Key Vault. For using Azure Blob Storage for patch storage, also assign it the `Storage Blob Data Contributor` and `Storage Blob Delegator` roles on the storage account. * An Application Gateway with a public IP address as an entry point for accessing the Livepatch Server. * A VMSS as a backend pool with the corresponding Managed Identity attached. @@ -39,7 +39,7 @@ Create an Azure-managed PostgreSQL DB with PostgreSQL password authentication. D ### Create the Managed Identity -Create a Managed Identity. This will be assigned to the VMSS to allow access to Azure Key Vault. +Create a Managed Identity. This will be assigned to the VMSS to allow access to Azure Key Vault. To use Azure Blob Storage for patch storage, the same identity is used for storage access — assign the **Storage Blob Data Contributor** and **Storage Blob Delegator** roles on the storage account to it (see the [reference](/server/reference/patch-storage/use-azure-for-patch-storage.md)). ### Create the Azure Key Vault @@ -47,7 +47,7 @@ Create an Azure Key Vault with public access disabled. Allow access from the VMS ### Configure the VMSS -For VMSS, select an instance type with sufficient CPU and memory capacity. The minimum resources required for the Livepatch Server to run efficiently are two vCPUs and 4 GB memory. Avoid using B-series instances. For storage options, the default volume size of 30 GB is sufficient. Assign the Managed Identity to the VMSS to allow access to Azure Key Vault. +For VMSS, select an instance type with sufficient CPU and memory capacity. The minimum resources required for the Livepatch Server to run efficiently are two vCPUs and 4 GB memory. For storage options, the default volume size of 30 GB is sufficient. Assign the Managed Identity to the VMSS to allow access to Azure Key Vault. Configure the VMSS NSG to allow traffic on port 80 from within the VNet. It is recommended not to have public IP addresses assigned to the VMSS VMs. This ensures that VMs can be accessed only through the Application Gateway. Provision a jumpbox in the same VNet with a public IP to access VMs when required. @@ -172,6 +172,17 @@ final_message: The system is up, up to date, and Livepatch Server is active afte Ensure the correct environment variable values are filled in the `write_files` section of the configuration. +### Use Azure Blob Storage + +To use Azure Blob Storage for patch storage, grant the Managed Identity the storage roles as described in [Create the Managed Identity](#create-the-managed-identity), then set the patch storage type to `azure` in the `snap set` command. When using a system-assigned managed identity, no `azure-account-key`, `azure-connection-string`, or service-principal keys are set — the server uses the ambient identity. Note that `patch-storage.azure-account-name` is still required: + +```bash +sudo snap set canonical-livepatch-server \ + lp.patch-storage.type=azure \ + lp.patch-storage.azure-container= \ + lp.patch-storage.azure-account-name= +``` + ### Provision the Application Gateway Provision a Standard V2 (or WAF V2) Application Gateway in the subnet created in the VNet with autoscaling enabled. The minimum instance count should be set according to the expected traffic. Add the VMSS to the backend pool of the Application Gateway and route all traffic to this pool. Use port 80 with `GET /` as the health check endpoint for the VMSS. diff --git a/docs/server/how-to-guides/deployment/upgrade-a-deployment.md b/docs/server/how-to-guides/deployment/upgrade-a-deployment.md index ed11fd2..3239ea3 100644 --- a/docs/server/how-to-guides/deployment/upgrade-a-deployment.md +++ b/docs/server/how-to-guides/deployment/upgrade-a-deployment.md @@ -84,7 +84,7 @@ Unlike a full patch synchronisation, which downloads multi-gigabyte kernel patch Trigger the metadata synchronisation job using `livepatch-admin`: ```bash -livepatch-admin sync trigger --metadata-only --wait +sudo livepatch-admin sync trigger --metadata-only --wait ``` Flags: @@ -96,13 +96,13 @@ Flags: If you run without `--wait`, retrieve the job status using the returned job ID: ```bash -livepatch-admin job-status +sudo livepatch-admin job-status ``` Or view recent sync reports: ```bash -livepatch-admin sync reports --all +sudo livepatch-admin sync reports --all ``` ## Step 4: Review patch sync tier configuration @@ -114,5 +114,5 @@ If your deployment synchronises patches from an upstream server, review how tier - `patch-sync.upstream-tier`: Specifies which tier to request from upstream (defaults to `stable`). - `patch-sync.ingress-tier`: Specifies the local tier into which synced patches are stored and served (defaults to your first configured tier, such as `edge` or `stable`). -Run `livepatch-admin tier list` to verify your local tiers and confirm where patches land. +Run `sudo livepatch-admin tier list` to verify your local tiers and confirm where patches land. diff --git a/docs/server/how-to-guides/operations/generate-patch-health-report.md b/docs/server/how-to-guides/operations/generate-patch-health-report.md index 6e68d10..ad30670 100644 --- a/docs/server/how-to-guides/operations/generate-patch-health-report.md +++ b/docs/server/how-to-guides/operations/generate-patch-health-report.md @@ -11,5 +11,5 @@ myst: To generate a report of how many machines applied (or failed to apply) a specific patch, run: ``` -livepatch-admin report patch-health +sudo livepatch-admin report patch-health ``` \ No newline at end of file diff --git a/docs/server/how-to-guides/operations/manage-fleet-of-machines.md b/docs/server/how-to-guides/operations/manage-fleet-of-machines.md index 1236480..8021985 100644 --- a/docs/server/how-to-guides/operations/manage-fleet-of-machines.md +++ b/docs/server/how-to-guides/operations/manage-fleet-of-machines.md @@ -11,7 +11,7 @@ myst: The Livepatch Server stores information about the status of machines attached to it. This information can be used to identify machines that failed to apply patches. ``` -livepatch-admin report machines [] [] +sudo livepatch-admin report machines [] [] ``` The output of this command contains a list of machines, along with their machine IDs and additional information. diff --git a/docs/server/how-to-guides/operations/use-livepatch-client-with-on-prem-server.md b/docs/server/how-to-guides/operations/use-livepatch-client-with-on-prem-server.md index 298aec9..4114041 100644 --- a/docs/server/how-to-guides/operations/use-livepatch-client-with-on-prem-server.md +++ b/docs/server/how-to-guides/operations/use-livepatch-client-with-on-prem-server.md @@ -22,7 +22,7 @@ In addition, machines require access to the Canonical Snap Store to install the To configure the Livepatch Client to pull patches from the on-premises Livepatch Server, an authorization token is required. To issue one, run: ``` -livepatch-admin auth-token +sudo livepatch-admin auth-token ``` The tier parameter is one of the tiers available on the server. The client downloads patches as they become available in that tier. See [Patch management](/server/reference/patch-management/patch-management.md) for details on managing tiers and patches in the on-premises server. diff --git a/docs/server/how-to-guides/patch-management/chain-livepatch-servers.md b/docs/server/how-to-guides/patch-management/chain-livepatch-servers.md index b6d543d..6bd9393 100644 --- a/docs/server/how-to-guides/patch-management/chain-livepatch-servers.md +++ b/docs/server/how-to-guides/patch-management/chain-livepatch-servers.md @@ -35,7 +35,7 @@ Below, the "upstream" server is referred to as the original Livepatch Server and Using the admin tool: ``` -livepatch-admin sync-tokens add edge my-token +sudo livepatch-admin sync-tokens add edge my-token ``` This will return a token that another on-premises server can use to sync patches. diff --git a/docs/server/how-to-guides/patch-management/distribute-patches-offline.md b/docs/server/how-to-guides/patch-management/distribute-patches-offline.md index 486db8b..9064663 100644 --- a/docs/server/how-to-guides/patch-management/distribute-patches-offline.md +++ b/docs/server/how-to-guides/patch-management/distribute-patches-offline.md @@ -34,7 +34,7 @@ On the internet-connected workstation, list the patches available from Canonical Use `livepatch-admin patch list` to inspect available patches before downloading: ```bash -livepatch-admin patch list --tier stable +sudo livepatch-admin patch list --tier stable ``` You can narrow the results using filters: @@ -49,16 +49,16 @@ You can narrow the results using filters: ### Download patches to disk -Once you identify the required patches, download them to a dedicated directory: +Once you identify the required patches, download them: ```bash -livepatch-admin patch download --patch-dir /tmp/livepatch-export --tier stable +sudo livepatch-admin patch download --tier stable ``` +Patches are downloaded to the admin snap's common directory at `$SNAP_COMMON/patches/` (for example, `/var/snap/canonical-livepatch-server-admin/common/patches/`). The metadata manifest is written to `$SNAP_COMMON/patches/canonical-livepatch-patch-metadata.json`. These locations are fixed and cannot be changed. + Optional download flags include: -- `--patch-dir `: Destination directory for downloaded patches (required). -- `--metadata-file `: Name of the metadata manifest file written inside `--patch-dir` (defaults to `canonical-livepatch-patch-metadata.json`). - `--metadata-only`: Download only the metadata manifest file without downloading patch files. - `--kernel `: Download patches for kernels matching or newer than the specified version prefix (for example, `5.15.0`). - `--arch `: Restrict downloads to a specific CPU architecture. @@ -71,7 +71,7 @@ Optional download flags include: The destination directory contains two types of artifacts: ```text -/tmp/livepatch-export/ +$SNAP_COMMON/patches/ ├── livepatch-5.15.0-107.117-generic-107.1-amd64.tar.bz2 ├── livepatch-5.15.0-107.117-generic-106.1-amd64.tar.bz2 └── canonical-livepatch-patch-metadata.json @@ -86,9 +86,9 @@ Do not alter or delete `canonical-livepatch-patch-metadata.json`. The upload com ## Step 2: Transfer the directory across the air gap -Copy the entire export directory—including all `.tar.bz2` archive files and `canonical-livepatch-patch-metadata.json`—to removable media (such as an encrypted USB drive or write-once optical media) or transfer it through your organisation's secure data diode or staging gateway. +Copy the entire `$SNAP_COMMON/patches/` directory—including all `.tar.bz2` archive files and `canonical-livepatch-patch-metadata.json`—to removable media (such as an encrypted USB drive or write-once optical media) or transfer it through your organisation's secure data diode or staging gateway. -Mount or copy the directory onto a workstation or bastion system with network connectivity to your on-premises Livepatch Server. +Mount or copy the directory onto a workstation or bastion system with network connectivity to your on-premises Livepatch Server, placing it in that system's `$SNAP_COMMON/patches/` directory. ## Step 3: Upload patches to the on-premises server @@ -96,24 +96,26 @@ Log in to your on-premises Livepatch Server with administrator credentials: ```bash export LIVEPATCH_URL=https://livepatch.internal.example.com - livepatch-admin login --auth : + sudo livepatch-admin login --auth : ``` ### Run the upload command -Navigate to the location of the transferred directory and upload the patches: +Upload the patches placed in `$SNAP_COMMON/patches/`: ```bash -livepatch-admin patch upload --patch-dir /media/transfer/livepatch-export +sudo livepatch-admin patch upload ``` ### Command options and flags -- `--patch-dir `: Local path to the directory containing patch archives (required). -- `--metadata-file `: Path to the metadata manifest. Defaults to `canonical-livepatch-patch-metadata.json` inside `--patch-dir`. - - When the default manifest is present, `livepatch-admin` automatically reads it to register patches with their original upstream publish timestamps and supported kernel lists. - - If the default manifest is absent, `livepatch-admin` scans `--patch-dir`, parses filenames, and generates metadata dynamically, assigning the current system time as the publish timestamp. - - If you pass an explicit `--metadata-file` path and the file is missing, the command immediately terminates with a fatal error. +`livepatch-admin patch upload` reads the patch archives and metadata manifest from `$SNAP_COMMON/patches/`: + +- When the metadata manifest (`canonical-livepatch-patch-metadata.json`) is present, `livepatch-admin` automatically reads it to register patches with their original upstream publish timestamps and supported kernel lists. +- If the manifest is absent, `livepatch-admin` scans the directory, parses filenames, and generates metadata dynamically, assigning the current system time as the publish timestamp. + +Available flags: + - `--tier `: Destination tier for the uploaded patches. Defaults to the on-premises server's configured sync tier or the first configured tier (for example, `edge` or `stable`). - `--concurrency `: Number of parallel file uploads (defaults to `2`). - `--overwrite`: Unconditionally overwrite existing patches on the server even if filenames or checksums already exist. @@ -124,9 +126,19 @@ livepatch-admin patch upload --patch-dir /media/transfer/livepatch-export Before uploading, `livepatch-admin` inspects the server's existing patch catalog to prevent redundant transfers or accidental collisions: - **Matching checksum**: If the on-premises server already has a patch with an identical filename and matching SHA-256 checksum, the file is automatically skipped. -- **Checksum mismatch**: If a patch file has the same filename as an existing server patch but a differing SHA-256 checksum, the uploader halts processing for that file without modifying storage. It records the mismatch in `/canonical-livepatch-patch-duplicates.json` for administrator review. +- **Checksum mismatch**: If a patch file has the same filename as an existing server patch but a differing SHA-256 checksum, the uploader halts processing for that file without modifying storage. It records the mismatch in `$SNAP_COMMON/patches/canonical-livepatch-patch-duplicates.json` for administrator review. - **Force overwrite**: If you intentionally need to replace a mismatched patch, pass the `--overwrite` flag. +## Clean up the downloaded patches + +After the patches have been uploaded, remove their local copies with: + +```bash +sudo livepatch-admin patch cleanup +``` + +This deletes the contents of `$SNAP_COMMON/patches/`, including the downloaded patch archives and the metadata manifest. + ## Storage backend behavior `livepatch-admin patch upload` works transparently across all supported storage backends: diff --git a/docs/server/how-to-guides/patch-management/fetch-patches.md b/docs/server/how-to-guides/patch-management/fetch-patches.md index da005f3..e138bb4 100644 --- a/docs/server/how-to-guides/patch-management/fetch-patches.md +++ b/docs/server/how-to-guides/patch-management/fetch-patches.md @@ -13,7 +13,7 @@ The Livepatch application is configured to fetch patch updates every 24 hours. T Patch snapshot downloads can also be manually triggered: ``` -livepatch-admin sync trigger --wait +sudo livepatch-admin sync trigger --wait ``` It is recommended to trigger a patch snapshot download once the server is successfully set up. @@ -23,5 +23,5 @@ It is recommended to trigger a patch snapshot download once the server is succes To verify that the server is receiving the latest patches from the Livepatch Server hosted by Canonical, use the following command. ``` -livepatch-admin sync reports +sudo livepatch-admin sync reports ``` \ No newline at end of file diff --git a/docs/server/how-to-guides/security/setup-administration-tool.md b/docs/server/how-to-guides/security/setup-administration-tool.md index 54cd83c..e5ff499 100644 --- a/docs/server/how-to-guides/security/setup-administration-tool.md +++ b/docs/server/how-to-guides/security/setup-administration-tool.md @@ -20,10 +20,33 @@ For ease of use, alias the admin command: sudo snap alias canonical-livepatch-server-admin.livepatch-admin livepatch-admin ``` +```{note} +Always run `livepatch-admin` commands with `sudo`. The tool writes files to the snap's common directory (for example, `$SNAP_COMMON/patches/`), and it fetches a resource token from the Livepatch client snap. Running commands without elevated privileges can cause permission errors. +``` + +## Downloading patches from Canonical's hosted server + +To download patches from Canonical's hosted Livepatch Server (for example, to sync patches for an on-premises deployment across an air gap), the system running the admin tool must have the Livepatch client enabled: + +``` +sudo pro attach +sudo pro enable livepatch +``` + +The Ubuntu Pro token must be entitled to Livepatch. Attaching the subscription and enabling Livepatch on the VM provides the resource token the admin tool fetches from the client snap when downloading patches. + +```{note} +Downloading patches with the admin tool requires a paid Ubuntu Pro subscription. Free-tier tokens do not allow downloading patches. +``` + ## Authentication The Livepatch administration tool authenticates with the Livepatch Server using Basic Auth (username and password). +```{note} +The `livepatch-admin` tool requires no cloud credentials or other cloud-specific setup. It authenticates with the server using only the administrator username and password via `livepatch-admin login`, regardless of the server's patch storage backend. For example, when uploading patches to a cloud-backed patch store, the server signs the temporary upload credentials itself. +``` + (server-how-to-guides-password-authentication)= ## Password authentication @@ -57,7 +80,7 @@ When logging in with the client, provide the username and password: ``` export LIVEPATCH_URL={haproxy URL or unit IP} -livepatch-admin login --auth : +sudo livepatch-admin login --auth : ``` ## Ubuntu SSO authentication (removed) diff --git a/docs/server/how-to-guides/security/setup-tls.md b/docs/server/how-to-guides/security/setup-tls.md index 00f9a44..ed17408 100644 --- a/docs/server/how-to-guides/security/setup-tls.md +++ b/docs/server/how-to-guides/security/setup-tls.md @@ -61,11 +61,11 @@ If a self-signed certificate is used, the administration tool must be configured The command line option for the Livepatch admin tool accepts either the path to a certificate chain PEM file, or the contents of the certificate chain: ``` -livepatch-admin --ca ./cert.pem login -a (...) +sudo livepatch-admin --ca ./cert.pem login -a (...) ``` ``` -livepatch-admin --ca "$(cat ./cert.pem)" login -a (...) +sudo livepatch-admin --ca "$(cat ./cert.pem)" login -a (...) ``` ### Environment variable diff --git a/docs/server/reference/patch-management/patch-management.md b/docs/server/reference/patch-management/patch-management.md index 2cb7e86..6c9bdbd 100644 --- a/docs/server/reference/patch-management/patch-management.md +++ b/docs/server/reference/patch-management/patch-management.md @@ -17,7 +17,7 @@ The tiers form an ordered list. When the on-premises server pulls patches from C To view the current tier order: ``` -livepatch-admin tier list +sudo livepatch-admin tier list ``` The output resembles: @@ -43,7 +43,7 @@ If validation or a staggered rollout of patches is required, use the patch tiers To promote an individual patch to a different tier: ``` -livepatch-admin patch promote +sudo livepatch-admin patch promote ``` The `patch-version` is the numerical patch version (for example, `57.1`). @@ -53,13 +53,13 @@ The `patch-version` is the numerical patch version (for example, `57.1`). To promote all patches from one tier to another, use the `promote-all` shortcut: ``` -livepatch-admin patch promote-all +sudo livepatch-admin patch promote-all ``` This command is useful during initial setup of Livepatch on-prem, when all patches are imported into the `edge` tier and other tiers are empty. For example: ```text -livepatch-admin patch promote-all edge stable +sudo livepatch-admin patch promote-all edge stable ``` This makes the contents of all tiers from `edge` to `stable` identical. \ No newline at end of file diff --git a/docs/server/reference/patch-storage/use-azure-for-patch-storage.md b/docs/server/reference/patch-storage/use-azure-for-patch-storage.md index b41b342..ee578db 100644 --- a/docs/server/reference/patch-storage/use-azure-for-patch-storage.md +++ b/docs/server/reference/patch-storage/use-azure-for-patch-storage.md @@ -23,6 +23,10 @@ Once configured, Livepatch will store and retrieve patch files from the Azure Bl Livepatch supports several authentication methods for Azure Blob Storage: +```{note} +**`patch-storage.azure-account-name` is required in all authentication modes except when using a connection string** (which already carries the account name). This includes managed identity and service principal modes. +``` + 1. **Storage account key:** Set `patch-storage.azure-account-name` and `patch-storage.azure-account-key`. 2. **Storage connection string:** Set `patch-storage.azure-connection-string`. This option supersedes individual account name and key settings. 3. **Microsoft Entra ID service principal:** Configure `patch-storage.azure-tenant-id`, `patch-storage.azure-client-id`, and `patch-storage.azure-client-secret`. @@ -41,7 +45,7 @@ For synchronising and serving patches, the identity must have blob read, write, ### Temporary upload credentials for the patch uploader -When an administrator runs `livepatch-admin patch upload`, the Livepatch Server generates container-level Shared Access Signature (SAS) tokens granting write and create capabilities: +When an administrator runs `livepatch-admin patch upload`, the Livepatch Server generates container-level Shared Access Signature (SAS) tokens scoped to the `livepatch-` object prefix within the container, granting write and create capabilities for patch uploads: - **When using Account Key or Connection String:** Livepatch signs the SAS token directly using the storage account Shared Key. - **When using Microsoft Entra ID (Service Principal or Managed Identity):** Livepatch requests a User Delegation Key from Microsoft Entra ID to sign a User Delegation SAS. To enable this, assign: @@ -50,3 +54,16 @@ When an administrator runs `livepatch-admin patch upload`, the Livepatch Server Upload credential lifetimes are governed by `patch-storage.upload-credential-ttl` (defaults to 15 minutes). +The `Storage Blob Delegator` role grants the `Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey/action` permission, which the server needs to sign User Delegation SAS tokens when authenticating via Microsoft Entra ID. Without it, `livepatch-admin patch upload` fails with a 403 when using managed identity or service principal auth. + +### Assigning roles per authentication mechanism + +The identity that must hold the roles above depends on the authentication mechanism: + +| Auth mechanism | Identity to assign roles to | +|----------------|-----------------------------| +| Account key / connection string | None (shared-key auth — no RBAC needed) | +| Service principal | The service principal's app ID | +| System-assigned managed identity | The VM/VMSS system-assigned principal ID | +| User-assigned managed identity | The user-assigned identity's principal ID | + diff --git a/docs/server/reference/patch-storage/use-gcs-for-patch-storage.md b/docs/server/reference/patch-storage/use-gcs-for-patch-storage.md index 9548118..1c717e0 100644 --- a/docs/server/reference/patch-storage/use-gcs-for-patch-storage.md +++ b/docs/server/reference/patch-storage/use-gcs-for-patch-storage.md @@ -23,10 +23,32 @@ Once configured, Livepatch will store and retrieve patch files from the GCS buck Livepatch supports several authentication methods for Google Cloud Storage: -1. **Application Default Credentials (ADC, recommended for GCP):** When running on Google Compute Engine (GCE) or Google Kubernetes Engine (GKE) with Workload Identity, Livepatch automatically acquires credentials from the ambient environment. Leave `patch-storage.gcs-credentials-file` and `patch-storage.gcs-credentials-json` unset. -2. **Service account key file:** Specify the absolute path to a service account JSON key file via `patch-storage.gcs-credentials-file`. -3. **Inline service account JSON:** Provide the raw JSON key contents directly using `patch-storage.gcs-credentials-json`. -4. **Service account impersonation:** Set `patch-storage.gcs-impersonate-service-account` to the email of a target service account. Livepatch uses the primary resolved credentials to impersonate that account. +1. **Application Default Credentials (ADC, recommended for GCP):** When running on Google Compute Engine (GCE) or Google Kubernetes Engine (GKE) with Workload Identity, Livepatch automatically acquires credentials from the ambient environment. Leave `patch-storage.gcs-credentials-file` and `patch-storage.gcs-credentials-json` unset. With ADC on GCE, the identity used is the service account attached to the VM instance, so grant `roles/storage.objectUser` on the bucket to that attached service account (verify with `gcloud compute instances describe --format='value(serviceAccounts[0].email)'`). +2. **Service account key file:** Specify the absolute path to a service account JSON key file via `patch-storage.gcs-credentials-file`. When deploying with the snap, the file must live inside the snap's writable area (see the snap note below). +3. **Inline service account JSON:** Provide the raw JSON key contents directly using `patch-storage.gcs-credentials-json`. When deploying with the snap, pass the JSON as a JSON-encoded string (see the snap note below). +4. **Service account impersonation:** Set `patch-storage.gcs-impersonate-service-account` to the email of a target service account. Livepatch uses the primary resolved credentials to impersonate that account. The primary identity must be granted `roles/iam.serviceAccountTokenCreator` on the target service account (see [Required IAM permissions](#required-iam-permissions)). + +````{note} +**Snap deployments are strictly confined.** The livepatch server snap cannot read a service account key file at an arbitrary path (for example `/tmp/gcs-key.json` or `/home/ubuntu/...`). Place the key file inside the snap's common directory and reference that path: + +```bash +sudo mkdir -p /var/snap/canonical-livepatch-server/common +sudo cp gcs-key.json /var/snap/canonical-livepatch-server/common/gcs-key.json +sudo snap set canonical-livepatch-server \ + lp.patch-storage.gcs-credentials-file=/var/snap/canonical-livepatch-server/common/gcs-key.json +``` +```` + +````{note} +**Snap deployments parse inline JSON.** `snap set` auto-parses JSON-looking values into nested objects, so passing the raw key JSON results in the value being stored as a map rather than a string. Pass the key JSON as a JSON-encoded string: + +```bash +sudo snap set canonical-livepatch-server \ + lp.patch-storage.gcs-credentials-json="$(jq -c . gcs-key.json)" +``` + +Verify with `sudo snap get canonical-livepatch-server lp.patch-storage.gcs-credentials-json` — the value must be a quoted JSON string, not a nested object. +```` ## Required IAM permissions @@ -48,9 +70,37 @@ When an administrator runs `livepatch-admin patch upload`, the Livepatch Server To issue and accept these downscoped upload tokens: - The service account must hold `roles/storage.objectUser` on the bucket (both `storage.objects.create` and `storage.objects.delete` are required for overwrite support). -- The service account must have permission to perform token exchanges with Google Cloud STS. +- The service account must hold `roles/iam.serviceAccountTokenCreator` **on itself** (this grants `iam.serviceAccounts.getAccessToken`, required to obtain the root token via `iamcredentials.generateAccessToken`). The STS downscoping exchange itself requires no additional IAM permission. ```{note} **Upload token lifetime:** Downscoped access tokens issued by Google Cloud STS have a fixed duration of ~1 hour (3600 seconds) enforced by Google Cloud. Configuring `patch-storage.upload-credential-ttl` does not shorten or extend this cloud-enforced token lifetime. ``` +### Service account impersonation + +When using service account impersonation (`patch-storage.gcs-impersonate-service-account`), the **target** service account is the identity that actually reads and writes the bucket; the primary (source) identity only obtains tokens for it. + +- Grant the primary identity `roles/iam.serviceAccountTokenCreator` on the target service account (the one named in `patch-storage.gcs-impersonate-service-account`): + + ```bash + gcloud iam service-accounts add-iam-policy-binding \ + \ + --member "serviceAccount:" \ + --role roles/iam.serviceAccountTokenCreator + ``` + +- Grant `roles/storage.objectUser` on the bucket to the **target** service account, since that is the identity that performs the actual storage operations. The source identity only needs the token-creator permission above. + +### Summary of required permissions + +The complete permission set for the server's IAM identity (service account) is: + +| Purpose | Role / permission | Scope | +|---------|-------------------|-------| +| Sync & serve patches | `roles/storage.objectUser` (`storage.objects.get/create/delete/list`) | Bucket | +| Patch uploader — root token for downscoping | `roles/iam.serviceAccountTokenCreator` (`iam.serviceAccounts.getAccessToken`) | On the service account itself | +| Patch uploader — impersonation (optional mode) | `roles/iam.serviceAccountTokenCreator` | On the impersonation target service account, granted to the primary identity | +| Patch uploader — impersonation target storage access | `roles/storage.objectUser` | Bucket, granted to the impersonation target service account | + +There is **no** separate "STS token exchange" permission — that step is permissionless once the root token exists. + diff --git a/docs/server/reference/patch-storage/use-s3-for-patch-storage.md b/docs/server/reference/patch-storage/use-s3-for-patch-storage.md index 8b321dd..e8ce72c 100644 --- a/docs/server/reference/patch-storage/use-s3-for-patch-storage.md +++ b/docs/server/reference/patch-storage/use-s3-for-patch-storage.md @@ -25,7 +25,7 @@ Livepatch supports multiple authentication methods for AWS S3 and S3-compatible 1. **Ambient IAM credentials (recommended for AWS):** When running on AWS EC2 or EKS, Livepatch automatically retrieves credentials from the ambient environment (EC2 instance metadata or IAM Roles for Service Accounts - IRSA). Leave `patch-storage.s3-access-key` and `patch-storage.s3-secret-key` blank. 2. **Static IAM access keys:** Set `patch-storage.s3-access-key` and `patch-storage.s3-secret-key` explicitly. -3. **STS AssumeRole:** Configure `patch-storage.s3-assume-role-arn` to have Livepatch assume a dedicated IAM role using its primary credentials. You can configure `patch-storage.s3-assume-role-duration` (defaults to 15 minutes) to specify the session lifetime. Note that the target IAM role's `MaxSessionDuration` must be configured at or above this value (AWS default is 1 hour). +3. **STS AssumeRole:** Configure `patch-storage.s3-assume-role-arn` to have Livepatch assume a dedicated IAM role using its primary credentials. You can configure `patch-storage.s3-assume-role-duration` (defaults to 15 minutes) to specify the session lifetime. Note that the target IAM role's `MaxSessionDuration` must be configured at or above this value (AWS default is 1 hour), and that values below 15 minutes are rejected by AWS STS (900 seconds is AWS's minimum for `AssumeRole`). The target role's trust policy must also allow the primary identity to assume it (see [Required IAM permissions](#required-iam-permissions)). 4. **S3-compatible storage (MinIO, Ceph):** Set `patch-storage.s3-endpoint` to the service URL, set `patch-storage.s3-use-path-style=true`, and toggle `patch-storage.s3-secure` depending on TLS support. ## Required IAM permissions @@ -51,6 +51,53 @@ To generate valid upload grants: - If using `patch-storage.s3-assume-role-arn`, the primary credentials must have `sts:AssumeRole` on the target role ARN. - Upload credential lifetimes are bounded by `patch-storage.upload-credential-ttl` (default 15 minutes) or the remaining STS session lifetime. +### STS AssumeRole trust policy requirement + +The primary credentials having `sts:AssumeRole` is necessary but not sufficient. The target role's **trust policy** must also list the primary identity (instance role ARN or IAM user ARN) as an allowed principal; without this, AssumeRole fails with 403 even when the caller has the `sts:AssumeRole` permission attached. For example, when the primary credentials come from an EC2 instance profile role `livepatch-server-role`: + +```json +{ + "Version": "2012-10-17", + "Statement": [{ + "Effect": "Allow", + "Principal": {"AWS": "arn:aws:iam:::role/livepatch-server-role"}, + "Action": "sts:AssumeRole" + }] +} +``` + +### Where to attach the S3 policy + +The required S3 actions must be attached to the identity that performs the storage operations, which depends on the authentication mode: + +| Auth mode | Where the S3 policy must be attached | +|-----------|--------------------------------------| +| Ambient IAM | The instance profile role (or IRSA role for EKS) | +| Static keys | The IAM user | +| STS AssumeRole | The target role (the primary identity only needs `sts:AssumeRole` + the trust policy) | + +### Complete IAM policy document + +The following policy covers the server's standard operations and the patch uploader. Replace `` with your bucket name: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"], + "Resource": "arn:aws:s3:::/*" + }, + { + "Effect": "Allow", + "Action": ["s3:ListBucket"], + "Resource": "arn:aws:s3:::" + } + ] +} +``` + ## Direct patch delivery from S3 To serve patches directly to clients from S3 rather than proxying bytes through the Livepatch Server, enable `server.redirect_downloads` and set your server's [URL template config](/server/reference/platform/configuration.md) to a client-readable endpoint. This static template cannot sign requests: a private S3 bucket needs an authenticated delivery mechanism, or client downloads will fail with 403. For publicly readable objects, use: diff --git a/docs/server/reference/platform/configuration.md b/docs/server/reference/platform/configuration.md index 86ed353..42a8296 100644 --- a/docs/server/reference/platform/configuration.md +++ b/docs/server/reference/platform/configuration.md @@ -161,13 +161,13 @@ The following values configure how the server manages patch storage. See the [pa | `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 `patch-storage.s3-access-key`). | `string` | | `patch-storage.s3-assume-role-arn` | IAM role ARN to assume via STS, using the resolved credentials above (optional). | `string` | -| `patch-storage.s3-assume-role-duration` | How long an assumed role's STS session stays valid before it must be refreshed; only applies when `patch-storage.s3-assume-role-arn` is set. Defaults to `15m` when unset. AWS STS rejects requests exceeding the target IAM role's `MaxSessionDuration` (1 hour by default, configurable up to 12 hours). | `string` | +| `patch-storage.s3-assume-role-duration` | How long an assumed role's STS session stays valid before it must be refreshed; only applies when `patch-storage.s3-assume-role-arn` is set. Defaults to `15m` when unset, which is AWS's minimum for `AssumeRole` (900 seconds). AWS STS rejects requests below this minimum or exceeding the target IAM role's `MaxSessionDuration` (1 hour by default, configurable up to 12 hours). | `string` | | `patch-storage.gcs-bucket` | Google Cloud Storage bucket for storing patches. | `string` | -| `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 `patch-storage.gcs-credentials-file`). | `string` | +| `patch-storage.gcs-credentials-file` | Path to a service account JSON key file (optional; defaults to Application Default Credentials). When using the snap, the file must live inside the snap's common directory, for example `/var/snap/canonical-livepatch-server/common/gcs-key.json`. | `string` | +| `patch-storage.gcs-credentials-json` | Inline service account JSON key (optional; see `patch-storage.gcs-credentials-file`). When using the snap, pass the key JSON as a JSON-encoded string (for example `"$(jq -c . gcs-key.json)"`), since `snap set` otherwise parses it into an object. | `string` | | `patch-storage.gcs-impersonate-service-account` | Email of a service account to impersonate, using the resolved credentials above (optional). | `string` | | `patch-storage.azure-container` | Azure Blob Storage container for storing patches. | `string` | -| `patch-storage.azure-account-name` | Azure storage account name (not required when `patch-storage.azure-connection-string` is set, which already carries the account name). | `string` | +| `patch-storage.azure-account-name` | Azure storage account name. Required in all authentication modes except when `patch-storage.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 `patch-storage.azure-client-id` and `patch-storage.azure-client-secret`). | `string` | diff --git a/docs/server/reference/telemetry/machine-reports.md b/docs/server/reference/telemetry/machine-reports.md index a650bae..04ae2a2 100644 --- a/docs/server/reference/telemetry/machine-reports.md +++ b/docs/server/reference/telemetry/machine-reports.md @@ -21,5 +21,5 @@ Machine reports are generated using the Livepatch Admin Tool. See the [admin too Generate a machine report by querying machines by their tier, last applied patch version, or patch state: ``` -livepatch-admin report machines [ []] +sudo livepatch-admin report machines [ []] ``` \ No newline at end of file diff --git a/docs/server/tutorial/livepatch-and-lxd.md b/docs/server/tutorial/livepatch-and-lxd.md index 3efc3ee..d7bbb74 100644 --- a/docs/server/tutorial/livepatch-and-lxd.md +++ b/docs/server/tutorial/livepatch-and-lxd.md @@ -219,7 +219,7 @@ export LIVEPATCH_URL="http://$HAPROXY_ADDRESS" Log in with one of your administrator credentials: ```bash -livepatch-admin login -a admin:admin123 +sudo livepatch-admin login -a admin:admin123 ``` ## Sync patches @@ -227,7 +227,7 @@ livepatch-admin login -a admin:admin123 Download patches from Canonical's hosted Livepatch Server to your on-prem instance: ```bash -livepatch-admin sync trigger --wait +sudo livepatch-admin sync trigger --wait ``` For more information on the admin tool, see the [administration tool setup guide](/server/how-to-guides/security/setup-administration-tool). To limit which patches are downloaded, see the [patch sync filters reference](/server/reference/patch-management/patch-sync-filters). diff --git a/docs/server/tutorial/livepatch-and-microk8s.md b/docs/server/tutorial/livepatch-and-microk8s.md index 420bfa9..6a7d77a 100644 --- a/docs/server/tutorial/livepatch-and-microk8s.md +++ b/docs/server/tutorial/livepatch-and-microk8s.md @@ -247,7 +247,7 @@ Export the Livepatch Server URL and log in: ```bash export LIVEPATCH_URL="http://livepatch.test.com" -livepatch-admin login -a username:password +sudo livepatch-admin login -a username:password ``` ## Sync patches @@ -255,19 +255,19 @@ livepatch-admin login -a username:password Download patches from Canonical's hosted Livepatch Server to your on-prem instance: ```bash -livepatch-admin sync trigger --wait +sudo livepatch-admin sync trigger --wait ``` To verify synced patches: ```bash -livepatch-admin storage patches +sudo livepatch-admin storage patches ``` To check for sync failures: ```bash -livepatch-admin sync report +sudo livepatch-admin sync report ``` To limit which patches are downloaded, see the [patch sync filters reference](/server/reference/patch-management/patch-sync-filters). From 2a787381ab405ad1522bc4f0d3eab7ca62b2b673 Mon Sep 17 00:00:00 2001 From: Kunal Mohan Date: Fri, 16 Oct 2026 16:50:19 +0530 Subject: [PATCH 05/11] remove oracle and ibm from patch uploader support --- .../distribute-patches-offline.md | 8 ++++++-- docs/server/reference/patch-storage/index.md | 5 +++-- .../patch-storage/use-ibm-for-patch-storage.md | 15 ++------------- .../patch-storage/use-oracle-for-patch-storage.md | 11 +++-------- .../patch-storage/use-swift-for-patch-storage.md | 2 +- docs/server/reference/platform/configuration.md | 4 ++-- 6 files changed, 17 insertions(+), 28 deletions(-) diff --git a/docs/server/how-to-guides/patch-management/distribute-patches-offline.md b/docs/server/how-to-guides/patch-management/distribute-patches-offline.md index 9064663..8b89799 100644 --- a/docs/server/how-to-guides/patch-management/distribute-patches-offline.md +++ b/docs/server/how-to-guides/patch-management/distribute-patches-offline.md @@ -141,9 +141,13 @@ This deletes the contents of `$SNAP_COMMON/patches/`, including the downloaded p ## Storage backend behavior -`livepatch-admin patch upload` works transparently across all supported storage backends: +`livepatch-admin patch upload` works across the following storage backends: -- **Cloud object storage (AWS S3, Google Cloud Storage, Azure Blob Storage, IBM Cloud Object Storage, Oracle Cloud Infrastructure, OpenStack Swift):** The Livepatch Server issues temporary, scoped upload credentials to the administrator client. The client transfers binary payloads directly to cloud object storage using presigned POST policies, SAS tokens, or Pre-Authenticated Requests. Background workers automatically refresh credentials during large batch uploads before expiry. +- **Cloud object storage (AWS S3, Google Cloud Storage, Azure Blob Storage, OpenStack Swift):** The Livepatch Server issues temporary, scoped upload credentials to the administrator client. The client transfers binary payloads directly to cloud object storage using presigned POST policies, SAS tokens, or Pre-Authenticated Requests. Background workers automatically refresh credentials during large batch uploads before expiry. - **Server-mediated storage (Local Filesystem, PostgreSQL):** The administrator client streams binary payloads directly through the Livepatch Server API (`PUT /v1/admin/patches/file/{filename}`) authenticated by the administrator's session token. +```{note} +Admin-tool-facilitated patch upload is not yet supported for IBM Cloud Object Storage and OCI Object Storage. +``` + For details on configuring cloud permissions so your server can generate upload credentials, see the [Patch storage reference](/server/reference/patch-storage/index.md). diff --git a/docs/server/reference/patch-storage/index.md b/docs/server/reference/patch-storage/index.md index 5d8f2e9..f1a3772 100644 --- a/docs/server/reference/patch-storage/index.md +++ b/docs/server/reference/patch-storage/index.md @@ -43,9 +43,10 @@ Livepatch Server supports native, modern authentication mechanisms for each clou When administrators use `livepatch-admin patch upload` to distribute patches to an on-premises server across an air gap, the server authorizes uploads depending on the storage driver: -- **Cloud object storage (S3, GCS, Azure, IBM COS, OCI, Swift):** The Livepatch Server acts as a credential issuer, generating temporary, scoped, upload-only credentials or presigned URLs. The `livepatch-admin` CLI uploads binary archives directly to cloud storage, bypassing the Livepatch Server API for high-bandwidth file transfers. +- **Cloud object storage (S3, GCS, Azure, Swift):** The Livepatch Server acts as a credential issuer, generating temporary, scoped, upload-only credentials or presigned URLs. The `livepatch-admin` CLI uploads binary archives directly to cloud storage, bypassing the Livepatch Server API for high-bandwidth file transfers. - **Server-mediated storage (Local Filesystem, PostgreSQL):** The CLI streams files directly to the Livepatch Server API endpoint (`PUT /v1/admin/patches/file/{filename}`) authenticated by the administrator's login token. -- **Upload credential lifetime:** For cloud backends, the duration of temporary upload credentials is configurable via `patch-storage.upload-credential-ttl` (defaults to 15 minutes). Note that Google Cloud STS (GCS) and IBM Cloud IAM issue tokens with a cloud-enforced fixed duration of ~1 hour. +- **IBM COS and OCI Object Storage:** Admin-tool-facilitated patch upload is not supported for these backends just yet. +- **Upload credential lifetime:** For supported cloud backends, the duration of temporary upload credentials is configurable via `patch-storage.upload-credential-ttl` (defaults to 15 minutes). Note that Google Cloud STS (GCS) issues tokens with a cloud-enforced fixed duration of ~1 hour. See the [platform configuration reference](/server/reference/platform/configuration.md) for all available parameters. diff --git a/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md b/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md index 21933a0..e720814 100644 --- a/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md +++ b/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md @@ -32,7 +32,7 @@ Legacy S3-compatible HMAC credentials (access key and secret key pairs) are unsu ## Required IAM access policies and trusted profiles -Configure IBM Cloud IAM roles for regular patch operations and offline patch uploads: +Configure IBM Cloud IAM roles for regular patch operations: ### Standard server operations @@ -41,18 +41,7 @@ For synchronising and serving patches, the Livepatch Server identity (API key or - **Reader** (to retrieve objects and list bucket contents) - **Writer** (or **ObjectWriter**, to write and delete patch files) -### Temporary upload credentials for the patch uploader - -When an administrator runs `livepatch-admin patch upload`, the Livepatch Server uses the IBM Cloud IAM "assume" grant to exchange its primary identity for a temporary bearer token bound to a dedicated upload trusted profile. - -To configure this: - -1. Create a dedicated IAM Trusted Profile in IBM Cloud. -2. Assign the profile the **Writer** or **ObjectWriter** role scoped to the target COS bucket. -3. Configure trust rules allowing the Livepatch Server identity (the server's API key or its VPC VSI compute identity) to assume the profile. -4. Set `patch-storage.ibm-upload-trusted-profile-id` in your server configuration with the profile ID. - ```{note} -**Upload token lifetime:** Bearer tokens issued via the IBM Cloud IAM assume grant have a fixed session lifetime (typically 1 hour / 3600 seconds) governed by account-level IAM session settings. Configuring `patch-storage.upload-credential-ttl` does not alter this cloud-enforced duration. +Admin-tool-facilitated patch upload (`livepatch-admin patch upload`) is not supported for IBM Cloud Object Storage just yet. ``` diff --git a/docs/server/reference/patch-storage/use-oracle-for-patch-storage.md b/docs/server/reference/patch-storage/use-oracle-for-patch-storage.md index 9979763..be7eb6b 100644 --- a/docs/server/reference/patch-storage/use-oracle-for-patch-storage.md +++ b/docs/server/reference/patch-storage/use-oracle-for-patch-storage.md @@ -38,12 +38,7 @@ For synchronising patches and delivering them to clients, the identity requires allow dynamic-group to manage objects in compartment where target.bucket.name = '' ``` -### Temporary upload credentials for the patch uploader - -When an administrator runs `livepatch-admin patch upload`, the Livepatch Server creates Pre-Authenticated Requests (PAR) with `AnyObjectWrite` permissions scoped to the `livepatch-` prefix. - -To permit PAR creation and subsequent uploads: - -- The IAM policy above (`manage objects`) covers the required permissions: `PAR_CREATE`, `OBJECT_CREATE`, and `OBJECT_INSPECT`. -- Upload credential lifetimes are bounded by `patch-storage.upload-credential-ttl` (defaults to 15 minutes). +```{note} +Admin-tool-facilitated patch upload (`livepatch-admin patch upload`) is not supported for OCI Object Storage just yet. +``` diff --git a/docs/server/reference/patch-storage/use-swift-for-patch-storage.md b/docs/server/reference/patch-storage/use-swift-for-patch-storage.md index d61894d..abb10bd 100644 --- a/docs/server/reference/patch-storage/use-swift-for-patch-storage.md +++ b/docs/server/reference/patch-storage/use-swift-for-patch-storage.md @@ -12,7 +12,7 @@ In OpenStack cloud environments or deployments with existing Swift object storag To configure this, follow these steps: -- Create a Swift container for Livepatch patches. Ensure the container is not publicly readable or writable. +- Create a Swift container for Livepatch patches. Ensure the container is not publicly writable. - Configure Keystone credentials for the Livepatch service account. - Provision a TempURL key on the Swift account or container if using the patch uploader. - Configure the relevant Swift [config options](/server/reference/platform/configuration.md). diff --git a/docs/server/reference/platform/configuration.md b/docs/server/reference/platform/configuration.md index 42a8296..2c0e007 100644 --- a/docs/server/reference/platform/configuration.md +++ b/docs/server/reference/platform/configuration.md @@ -180,14 +180,14 @@ The following values configure how the server manages patch storage. See the [pa | `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 `patch-storage.ibm-api-key`. | `string` | | `patch-storage.ibm-trusted-profile-id` | Trusted profile ID to assume via the ambient VPC Instance Metadata Service (optional; defaults to the instance's default trusted profile). | `string` | -| `patch-storage.ibm-upload-trusted-profile-id` | Dedicated IAM Trusted Profile ID to assume when issuing temporary upload credentials for `livepatch-admin patch upload` (optional). | `string` | +| `patch-storage.ibm-upload-trusted-profile-id` | Dedicated IAM Trusted Profile ID to assume when issuing temporary upload credentials for `livepatch-admin patch upload` (optional). Admin-tool-facilitated patch upload is not yet supported for IBM Cloud Object Storage. | `string` | | `patch-storage.oracle-bucket` | OCI Object Storage bucket for storing patches. | `string` | | `patch-storage.oracle-namespace` | OCI Object Storage namespace. | `string` | | `patch-storage.oracle-region` | OCI region. | `string` | | `patch-storage.oracle-config-file` | Path to an OCI config file (optional; defaults to instance principal authentication). | `string` | | `patch-storage.oracle-profile` | Profile to use within `patch-storage.oracle-config-file` (optional). | `string` | | `patch-storage.swift-temp-url-key` | OpenStack Swift account or container TempURL key, used to sign scoped, time-limited upload credentials for `livepatch-admin patch upload`. Because Swift never returns a previously set key, it must be provisioned out-of-band and configured here with the identical secret key (optional). | `string` | -| `patch-storage.upload-credential-ttl` | Duration that temporary, upload-only credentials issued by the server remain valid for cloud storage backends (`s3`, `gcs`, `azure`, `ibm`, `oracle`, `swift`) during `livepatch-admin patch upload` (optional; defaults to `15m`). Has no effect for `filesystem` and `postgres`, which route uploads through the authenticated server API. Note that GCS and IBM COS issue bearer tokens with a cloud-enforced fixed duration of ~1 hour regardless of this setting. | `string` | +| `patch-storage.upload-credential-ttl` | Duration that temporary, upload-only credentials issued by the server remain valid for cloud storage backends (`s3`, `gcs`, `azure`, `swift`) during `livepatch-admin patch upload` (optional; defaults to `15m`). Has no effect for `filesystem` and `postgres`, which route uploads through the authenticated server API. Admin-tool-facilitated patch upload is not yet supported for `ibm` and `oracle`. Note that GCS issues bearer tokens with a cloud-enforced fixed duration of ~1 hour regardless of this setting. | `string` | ### Patch cache From 2ca7a02439f9af9e61c354cb050d82ffba2543d3 Mon Sep 17 00:00:00 2001 From: Kunal Mohan Date: Fri, 16 Oct 2026 18:17:31 +0530 Subject: [PATCH 06/11] address review comments --- .../how-to-guides/deployment/deploy-via-juju.md | 4 +--- .../how-to-guides/deployment/deploy-via-snap.md | 12 ++---------- .../deployment/public-clouds/deploying-on-azure.md | 10 ++++++++-- .../how-to-guides/deployment/upgrade-a-deployment.md | 4 ++-- .../patch-management/distribute-patches-offline.md | 3 +-- .../security/setup-administration-tool.md | 4 +--- .../patch-storage/use-ibm-for-patch-storage.md | 2 +- docs/server/tutorial/livepatch-and-lxd.md | 8 +------- docs/server/tutorial/livepatch-and-microk8s.md | 3 +-- 9 files changed, 18 insertions(+), 32 deletions(-) diff --git a/docs/server/how-to-guides/deployment/deploy-via-juju.md b/docs/server/how-to-guides/deployment/deploy-via-juju.md index 2494f2b..43486d0 100644 --- a/docs/server/how-to-guides/deployment/deploy-via-juju.md +++ b/docs/server/how-to-guides/deployment/deploy-via-juju.md @@ -127,9 +127,7 @@ See the [Administration Tool guide](/server/how-to-guides/security/setup-adminis Once this has been done, the Livepatch admin tool can be used to authenticate: ``` -export LIVEPATCH_URL=http(s)://{haproxy url} - -sudo livepatch-admin login -a [username:password] +sudo livepatch-admin --url http(s)://{haproxy url} login -a [username:password] ``` ### 5. Download patches diff --git a/docs/server/how-to-guides/deployment/deploy-via-snap.md b/docs/server/how-to-guides/deployment/deploy-via-snap.md index b3f9f0a..9dcc45c 100644 --- a/docs/server/how-to-guides/deployment/deploy-via-snap.md +++ b/docs/server/how-to-guides/deployment/deploy-via-snap.md @@ -88,11 +88,7 @@ To manage Livepatch, an administrator tool is available as a snap. Install it wi sudo snap install canonical-livepatch-server-admin ``` -The administrator tool needs to know where the Livepatch Server is hosted. In an all-in-one setup on a single machine, this is `http://localhost:8080`. Export an environment variable as follows: - -``` -export LIVEPATCH_URL=http://localhost:8080 -``` +The administrator tool needs to know where the Livepatch Server is hosted. In an all-in-one setup on a single machine, this is `http://localhost:8080`. Use the `--url` flag in the command to specify the address. ## Set up authentication @@ -160,11 +156,7 @@ To listen for all incoming connections on a different port, run: sudo snap set canonical-livepatch-server lp.server.server-address=0.0.0.0: ``` -Update the `LIVEPATCH_URL` environment variable to ensure the admin tool can still access the server. To access the server from a remote machine, replace `localhost` with the IP address of the machine running the Livepatch Server: - -``` -export LIVEPATCH_URL=http://localhost: -``` +Be sure to include the correct server endpoint with the `livepatch-admin` commands using the `--url` flag. ## Next steps diff --git a/docs/server/how-to-guides/deployment/public-clouds/deploying-on-azure.md b/docs/server/how-to-guides/deployment/public-clouds/deploying-on-azure.md index 80dc29c..e056495 100644 --- a/docs/server/how-to-guides/deployment/public-clouds/deploying-on-azure.md +++ b/docs/server/how-to-guides/deployment/public-clouds/deploying-on-azure.md @@ -17,6 +17,7 @@ To set up the Livepatch Server on Azure using an Azure Blob Storage container fo * A VNet with subnets for VMSS, Application Gateway, and PostgreSQL DB. * An Azure Key Vault with access enabled for the VMSS subnet of the VNet. +* An Azure Storage account and Blob store container with access enabled for the VMSS subnet of the VNet. * An Azure-managed PostgreSQL instance with PostgreSQL 14 or above using password authentication. The username and password stored in Azure Key Vault as a JSON object. * A Virtual Machine Scale Set (VMSS) with an instance type with at least two vCPUs and 4 GB RAM, with a cloud-init configuration file as custom data. * An Ubuntu Pro token stored as a secret in Azure Key Vault. @@ -77,6 +78,10 @@ write_files: export DB_SECRET_ID= export DB_NAME= + # patch store + export STORAGE_ACCOUNT_NAME= + export STORAGE_CONTAINER= + # pro token variables export TOKEN_SECRET_ID= export ADMIN_USER_SECRET_ID= @@ -154,9 +159,10 @@ runcmd: snap set canonical-livepatch-server \ token="$(cat /etc/livepatch/pro_token)" \ lp.database.connection-string="$(cat /etc/livepatch/database_url)" \ - lp.patch-storage.type=postgres \ + lp.patch-storage.type=azure \ lp.server.url-template=$URLTEMPLATE \ - lp.patch-storage.postgres-connection-string="$(cat /etc/livepatch/database_url)" \ + lp.patch-storage.azure-account-name=$STORAGE_ACCOUNT_NAME \ + lp.patch-storage.azure-container=$STORAGE_CONTAINER \ lp.auth.basic.enabled=true \ lp.patch-sync.enabled=true \ lp.patch-sync.interval=12h \ diff --git a/docs/server/how-to-guides/deployment/upgrade-a-deployment.md b/docs/server/how-to-guides/deployment/upgrade-a-deployment.md index 3239ea3..053a695 100644 --- a/docs/server/how-to-guides/deployment/upgrade-a-deployment.md +++ b/docs/server/how-to-guides/deployment/upgrade-a-deployment.md @@ -47,7 +47,7 @@ When upgrading across Livepatch Server releases, database schema migrations run In charmed deployments, database migrations run automatically during service startup after a refresh. If the Livepatch application enters a blocked status requiring manual intervention, run the `schema-upgrade` action on the leader unit: ```bash -juju run livepatch/leader schema-upgrade --wait +juju run canonical-livepatch-server-k8s/leader schema-upgrade --wait ``` ```{note} @@ -57,7 +57,7 @@ In Juju v3, `juju run-action` was renamed to `juju run`. See the [Juju documenta If needed, restart units after the schema upgrade completes: ```bash -juju run livepatch/ restart --wait +juju run canonical-livepatch-server-k8s/ restart --wait ``` ### Snap deployments diff --git a/docs/server/how-to-guides/patch-management/distribute-patches-offline.md b/docs/server/how-to-guides/patch-management/distribute-patches-offline.md index 8b89799..9c23670 100644 --- a/docs/server/how-to-guides/patch-management/distribute-patches-offline.md +++ b/docs/server/how-to-guides/patch-management/distribute-patches-offline.md @@ -95,8 +95,7 @@ Mount or copy the directory onto a workstation or bastion system with network co Log in to your on-premises Livepatch Server with administrator credentials: ```bash - export LIVEPATCH_URL=https://livepatch.internal.example.com - sudo livepatch-admin login --auth : + sudo livepatch-admin --url https://livepatch.internal.example.com login --auth : ``` ### Run the upload command diff --git a/docs/server/how-to-guides/security/setup-administration-tool.md b/docs/server/how-to-guides/security/setup-administration-tool.md index e5ff499..6be9044 100644 --- a/docs/server/how-to-guides/security/setup-administration-tool.md +++ b/docs/server/how-to-guides/security/setup-administration-tool.md @@ -78,9 +78,7 @@ juju config livepatch auth_basic_users="::" When logging in with the client, provide the username and password: ``` -export LIVEPATCH_URL={haproxy URL or unit IP} - -sudo livepatch-admin login --auth : +sudo livepatch-admin --url login --auth : ``` ## Ubuntu SSO authentication (removed) diff --git a/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md b/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md index e720814..619db3d 100644 --- a/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md +++ b/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md @@ -32,7 +32,7 @@ Legacy S3-compatible HMAC credentials (access key and secret key pairs) are unsu ## Required IAM access policies and trusted profiles -Configure IBM Cloud IAM roles for regular patch operations: +Configure IBM Cloud IAM roles for regular patch operations and offline patch uploads: ### Standard server operations diff --git a/docs/server/tutorial/livepatch-and-lxd.md b/docs/server/tutorial/livepatch-and-lxd.md index d7bbb74..839772c 100644 --- a/docs/server/tutorial/livepatch-and-lxd.md +++ b/docs/server/tutorial/livepatch-and-lxd.md @@ -210,16 +210,10 @@ Create a convenient alias: sudo snap alias canonical-livepatch-server-admin.livepatch-admin livepatch-admin ``` -Export the Livepatch Server URL (pointing to the HAProxy address you retrieved earlier): - -```bash -export LIVEPATCH_URL="http://$HAPROXY_ADDRESS" -``` - Log in with one of your administrator credentials: ```bash -sudo livepatch-admin login -a admin:admin123 +sudo livepatch-admin --url http://$HAPROXY_ADDRESS login -a admin:admin123 ``` ## Sync patches diff --git a/docs/server/tutorial/livepatch-and-microk8s.md b/docs/server/tutorial/livepatch-and-microk8s.md index 6a7d77a..b966ae8 100644 --- a/docs/server/tutorial/livepatch-and-microk8s.md +++ b/docs/server/tutorial/livepatch-and-microk8s.md @@ -246,8 +246,7 @@ sudo snap alias canonical-livepatch-server-admin.livepatch-admin livepatch-admin Export the Livepatch Server URL and log in: ```bash -export LIVEPATCH_URL="http://livepatch.test.com" -sudo livepatch-admin login -a username:password +sudo livepatch-admin --url http://livepatch.test.com login -a username:password ``` ## Sync patches From 27c1e8a61b1da8bdf686d02b34e506ac1bada062 Mon Sep 17 00:00:00 2001 From: kunalmohan-work Date: Fri, 16 Oct 2026 18:38:53 +0530 Subject: [PATCH 07/11] Add Azure managed identity client ID to deployment config Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: kunalmohan-work --- .../how-to-guides/deployment/public-clouds/deploying-on-azure.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/server/how-to-guides/deployment/public-clouds/deploying-on-azure.md b/docs/server/how-to-guides/deployment/public-clouds/deploying-on-azure.md index e056495..61a4b93 100644 --- a/docs/server/how-to-guides/deployment/public-clouds/deploying-on-azure.md +++ b/docs/server/how-to-guides/deployment/public-clouds/deploying-on-azure.md @@ -163,6 +163,7 @@ runcmd: lp.server.url-template=$URLTEMPLATE \ lp.patch-storage.azure-account-name=$STORAGE_ACCOUNT_NAME \ lp.patch-storage.azure-container=$STORAGE_CONTAINER \ + lp.patch-storage.azure-managed-identity-client-id="$AZURE_MANAGED_IDENTITY_CLIENT_ID" \ lp.auth.basic.enabled=true \ lp.patch-sync.enabled=true \ lp.patch-sync.interval=12h \ From a262f52b4c097c96b8af4d0e490c088c012aed9a Mon Sep 17 00:00:00 2001 From: Kunal Mohan Date: Fri, 16 Oct 2026 18:47:06 +0530 Subject: [PATCH 08/11] nit fix --- docs/server/how-to-guides/deployment/upgrade-a-deployment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/server/how-to-guides/deployment/upgrade-a-deployment.md b/docs/server/how-to-guides/deployment/upgrade-a-deployment.md index 053a695..4120425 100644 --- a/docs/server/how-to-guides/deployment/upgrade-a-deployment.md +++ b/docs/server/how-to-guides/deployment/upgrade-a-deployment.md @@ -66,7 +66,7 @@ For snap deployments, database migrations also run automatically during service ## Step 3: Backfill publish timestamps with metadata-only sync -In earlier Livepatch Server releases, patch tiers did not record the original upstream publish timestamp from Canonical (or initialized it to the local database insertion time). +In earlier Livepatch Server releases (v2.6.x and below), patch tiers did not record the original upstream publish timestamp from Canonical (or initialized it to the local database insertion time). If your server has an active upstream connection (`patch-sync.enabled=true`) and you want your on-premises patch catalog to reflect accurate Canonical publish dates (for client queries, KPI reporting, and `patch list` filtering), trigger a **metadata-only sync**. From 9cd3e8bfb0356b8a8e7856910360b1a722a70190 Mon Sep 17 00:00:00 2001 From: Kunal Mohan Date: Sat, 17 Oct 2026 02:45:29 +0530 Subject: [PATCH 09/11] add support for oracle --- .../patch-management/distribute-patches-offline.md | 4 ++-- docs/server/reference/patch-storage/index.md | 4 ++-- .../patch-storage/use-azure-for-patch-storage.md | 2 +- .../patch-storage/use-ibm-for-patch-storage.md | 2 +- .../patch-storage/use-oracle-for-patch-storage.md | 14 ++++++++++---- docs/server/reference/platform/configuration.md | 2 +- 6 files changed, 17 insertions(+), 11 deletions(-) diff --git a/docs/server/how-to-guides/patch-management/distribute-patches-offline.md b/docs/server/how-to-guides/patch-management/distribute-patches-offline.md index 9c23670..23e5cfa 100644 --- a/docs/server/how-to-guides/patch-management/distribute-patches-offline.md +++ b/docs/server/how-to-guides/patch-management/distribute-patches-offline.md @@ -142,11 +142,11 @@ This deletes the contents of `$SNAP_COMMON/patches/`, including the downloaded p `livepatch-admin patch upload` works across the following storage backends: -- **Cloud object storage (AWS S3, Google Cloud Storage, Azure Blob Storage, OpenStack Swift):** The Livepatch Server issues temporary, scoped upload credentials to the administrator client. The client transfers binary payloads directly to cloud object storage using presigned POST policies, SAS tokens, or Pre-Authenticated Requests. Background workers automatically refresh credentials during large batch uploads before expiry. +- **Cloud object storage (AWS S3, Google Cloud Storage, Azure Blob Storage, Oracle Cloud Infrastructure, OpenStack Swift):** The Livepatch Server issues temporary, scoped upload credentials to the administrator client. The client transfers binary payloads directly to cloud object storage using presigned POST policies, SAS tokens, or Pre-Authenticated Requests. Background workers automatically refresh credentials during large batch uploads before expiry. - **Server-mediated storage (Local Filesystem, PostgreSQL):** The administrator client streams binary payloads directly through the Livepatch Server API (`PUT /v1/admin/patches/file/{filename}`) authenticated by the administrator's session token. ```{note} -Admin-tool-facilitated patch upload is not yet supported for IBM Cloud Object Storage and OCI Object Storage. +Admin-tool-facilitated patch upload is not yet supported for IBM Cloud Object Storage. ``` For details on configuring cloud permissions so your server can generate upload credentials, see the [Patch storage reference](/server/reference/patch-storage/index.md). diff --git a/docs/server/reference/patch-storage/index.md b/docs/server/reference/patch-storage/index.md index f1a3772..4eade96 100644 --- a/docs/server/reference/patch-storage/index.md +++ b/docs/server/reference/patch-storage/index.md @@ -43,9 +43,9 @@ Livepatch Server supports native, modern authentication mechanisms for each clou When administrators use `livepatch-admin patch upload` to distribute patches to an on-premises server across an air gap, the server authorizes uploads depending on the storage driver: -- **Cloud object storage (S3, GCS, Azure, Swift):** The Livepatch Server acts as a credential issuer, generating temporary, scoped, upload-only credentials or presigned URLs. The `livepatch-admin` CLI uploads binary archives directly to cloud storage, bypassing the Livepatch Server API for high-bandwidth file transfers. +- **Cloud object storage (S3, GCS, Azure, OCI, Swift):** The Livepatch Server acts as a credential issuer, generating temporary, scoped, upload-only credentials or presigned URLs. The `livepatch-admin` CLI uploads binary archives directly to cloud storage, bypassing the Livepatch Server API for high-bandwidth file transfers. - **Server-mediated storage (Local Filesystem, PostgreSQL):** The CLI streams files directly to the Livepatch Server API endpoint (`PUT /v1/admin/patches/file/{filename}`) authenticated by the administrator's login token. -- **IBM COS and OCI Object Storage:** Admin-tool-facilitated patch upload is not supported for these backends just yet. +- **IBM COS:** Admin-tool-facilitated patch upload is not supported for this backend just yet. - **Upload credential lifetime:** For supported cloud backends, the duration of temporary upload credentials is configurable via `patch-storage.upload-credential-ttl` (defaults to 15 minutes). Note that Google Cloud STS (GCS) issues tokens with a cloud-enforced fixed duration of ~1 hour. See the [platform configuration reference](/server/reference/platform/configuration.md) for all available parameters. diff --git a/docs/server/reference/patch-storage/use-azure-for-patch-storage.md b/docs/server/reference/patch-storage/use-azure-for-patch-storage.md index ee578db..707ffbe 100644 --- a/docs/server/reference/patch-storage/use-azure-for-patch-storage.md +++ b/docs/server/reference/patch-storage/use-azure-for-patch-storage.md @@ -45,7 +45,7 @@ For synchronising and serving patches, the identity must have blob read, write, ### Temporary upload credentials for the patch uploader -When an administrator runs `livepatch-admin patch upload`, the Livepatch Server generates container-level Shared Access Signature (SAS) tokens scoped to the `livepatch-` object prefix within the container, granting write and create capabilities for patch uploads: +When an administrator runs `livepatch-admin patch upload`, the Livepatch Server generates container-level Shared Access Signature (SAS) tokens granting write and create capabilities throughout the container: - **When using Account Key or Connection String:** Livepatch signs the SAS token directly using the storage account Shared Key. - **When using Microsoft Entra ID (Service Principal or Managed Identity):** Livepatch requests a User Delegation Key from Microsoft Entra ID to sign a User Delegation SAS. To enable this, assign: diff --git a/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md b/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md index 619db3d..e720814 100644 --- a/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md +++ b/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md @@ -32,7 +32,7 @@ Legacy S3-compatible HMAC credentials (access key and secret key pairs) are unsu ## Required IAM access policies and trusted profiles -Configure IBM Cloud IAM roles for regular patch operations and offline patch uploads: +Configure IBM Cloud IAM roles for regular patch operations: ### Standard server operations diff --git a/docs/server/reference/patch-storage/use-oracle-for-patch-storage.md b/docs/server/reference/patch-storage/use-oracle-for-patch-storage.md index be7eb6b..e47f391 100644 --- a/docs/server/reference/patch-storage/use-oracle-for-patch-storage.md +++ b/docs/server/reference/patch-storage/use-oracle-for-patch-storage.md @@ -28,17 +28,23 @@ Livepatch supports two authentication methods for OCI Object Storage: ## Required OCI IAM policies -Configure OCI IAM policies for your instance dynamic group (when using instance principals) or user group (when using a config file): +Configure OCI IAM policies for your instance dynamic group (when using instance principals) or user group (when using a config file). Two policies are required: ### Standard server operations For synchronising patches and delivering them to clients, the identity requires object read, write, and delete permissions. Add a policy statement such as: ```text -allow dynamic-group to manage objects in compartment where target.bucket.name = '' +allow dynamic-group to manage objects in compartment where target.bucket.name = '' ``` -```{note} -Admin-tool-facilitated patch upload (`livepatch-admin patch upload`) is not supported for OCI Object Storage just yet. +### Temporary upload credentials for the patch uploader + +When an administrator runs `livepatch-admin patch upload`, the Livepatch Server creates Pre-Authenticated Requests (PAR) with `AnyObjectWrite` permissions scoped to the `livepatch-` prefix. To permit PAR creation and subsequent uploads, add a policy statement such as: + +```text +allow dynamic-group to manage buckets in compartment where all {target.bucket.name = '', request.permission = 'PAR_MANAGE'} ``` +Upload credential lifetimes are bounded by `patch-storage.upload-credential-ttl` (defaults to 15 minutes). + diff --git a/docs/server/reference/platform/configuration.md b/docs/server/reference/platform/configuration.md index 2c0e007..a42f37b 100644 --- a/docs/server/reference/platform/configuration.md +++ b/docs/server/reference/platform/configuration.md @@ -187,7 +187,7 @@ The following values configure how the server manages patch storage. See the [pa | `patch-storage.oracle-config-file` | Path to an OCI config file (optional; defaults to instance principal authentication). | `string` | | `patch-storage.oracle-profile` | Profile to use within `patch-storage.oracle-config-file` (optional). | `string` | | `patch-storage.swift-temp-url-key` | OpenStack Swift account or container TempURL key, used to sign scoped, time-limited upload credentials for `livepatch-admin patch upload`. Because Swift never returns a previously set key, it must be provisioned out-of-band and configured here with the identical secret key (optional). | `string` | -| `patch-storage.upload-credential-ttl` | Duration that temporary, upload-only credentials issued by the server remain valid for cloud storage backends (`s3`, `gcs`, `azure`, `swift`) during `livepatch-admin patch upload` (optional; defaults to `15m`). Has no effect for `filesystem` and `postgres`, which route uploads through the authenticated server API. Admin-tool-facilitated patch upload is not yet supported for `ibm` and `oracle`. Note that GCS issues bearer tokens with a cloud-enforced fixed duration of ~1 hour regardless of this setting. | `string` | +| `patch-storage.upload-credential-ttl` | Duration that temporary, upload-only credentials issued by the server remain valid for cloud storage backends (`s3`, `gcs`, `azure`, `oracle`, `swift`) during `livepatch-admin patch upload` (optional; defaults to `15m`). Has no effect for `filesystem` and `postgres`, which route uploads through the authenticated server API. Admin-tool-facilitated patch upload is not yet supported for `ibm`. Note that GCS issues bearer tokens with a cloud-enforced fixed duration of ~1 hour regardless of this setting. | `string` | ### Patch cache From 3dc459840e8a6d26ab2720197842927475b04328 Mon Sep 17 00:00:00 2001 From: Kunal Mohan Date: Sat, 17 Oct 2026 02:56:56 +0530 Subject: [PATCH 10/11] address review comments --- .../patch-management/distribute-patches-offline.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/server/how-to-guides/patch-management/distribute-patches-offline.md b/docs/server/how-to-guides/patch-management/distribute-patches-offline.md index 23e5cfa..dad8ff6 100644 --- a/docs/server/how-to-guides/patch-management/distribute-patches-offline.md +++ b/docs/server/how-to-guides/patch-management/distribute-patches-offline.md @@ -142,7 +142,7 @@ This deletes the contents of `$SNAP_COMMON/patches/`, including the downloaded p `livepatch-admin patch upload` works across the following storage backends: -- **Cloud object storage (AWS S3, Google Cloud Storage, Azure Blob Storage, Oracle Cloud Infrastructure, OpenStack Swift):** The Livepatch Server issues temporary, scoped upload credentials to the administrator client. The client transfers binary payloads directly to cloud object storage using presigned POST policies, SAS tokens, or Pre-Authenticated Requests. Background workers automatically refresh credentials during large batch uploads before expiry. +- **Cloud object storage (AWS S3, Google Cloud Storage, Azure Blob Storage, Oracle Cloud Infrastructure, OpenStack Swift):** The Livepatch Server issues temporary, scoped upload credentials to the administrator client. The client transfers binary payloads directly to cloud object storage using presigned POST policies, SAS tokens, Swift TempURLs or Pre-Authenticated Requests. Background workers automatically refresh credentials during large batch uploads before expiry. - **Server-mediated storage (Local Filesystem, PostgreSQL):** The administrator client streams binary payloads directly through the Livepatch Server API (`PUT /v1/admin/patches/file/{filename}`) authenticated by the administrator's session token. ```{note} From efafb3c1ad21e3242a803e17616f759ee435a2ff Mon Sep 17 00:00:00 2001 From: kunalmohan-work Date: Mon, 19 Oct 2026 13:52:29 +0530 Subject: [PATCH 11/11] Revise patch storage and Livepatch Server documentation Updated permissions and authentication instructions for patch storage and Livepatch Server. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: kunalmohan-work --- .../use-oracle-for-patch-storage.md | 24 ++++++++++++++----- .../server/tutorial/livepatch-and-microk8s.md | 2 +- 2 files changed, 19 insertions(+), 7 deletions(-) diff --git a/docs/server/reference/patch-storage/use-oracle-for-patch-storage.md b/docs/server/reference/patch-storage/use-oracle-for-patch-storage.md index e47f391..f1326c7 100644 --- a/docs/server/reference/patch-storage/use-oracle-for-patch-storage.md +++ b/docs/server/reference/patch-storage/use-oracle-for-patch-storage.md @@ -32,19 +32,31 @@ Configure OCI IAM policies for your instance dynamic group (when using instance ### Standard server operations -For synchronising patches and delivering them to clients, the identity requires object read, write, and delete permissions. Add a policy statement such as: +For synchronising patches and delivering them to clients, the identity requires object read, write, and delete permissions. For instance principal authentication, add: -```text +~~~text allow dynamic-group to manage objects in compartment where target.bucket.name = '' -``` +~~~ + +For config-file authentication, grant the same permissions to the group containing the configured user instead: + +~~~text +allow group to manage objects in compartment where target.bucket.name = '' +~~~ ### Temporary upload credentials for the patch uploader -When an administrator runs `livepatch-admin patch upload`, the Livepatch Server creates Pre-Authenticated Requests (PAR) with `AnyObjectWrite` permissions scoped to the `livepatch-` prefix. To permit PAR creation and subsequent uploads, add a policy statement such as: +When an administrator runs `livepatch-admin patch upload`, the Livepatch Server creates Pre-Authenticated Requests (PAR) with `AnyObjectWrite` permissions scoped to the `livepatch-` prefix. To permit PAR creation and subsequent uploads, add the following policy for instance principal authentication: -```text +~~~text allow dynamic-group to manage buckets in compartment where all {target.bucket.name = '', request.permission = 'PAR_MANAGE'} -``` +~~~ + +For config-file authentication, use the corresponding user-group policy instead: + +~~~text +allow group to manage buckets in compartment where all {target.bucket.name = '', request.permission = 'PAR_MANAGE'} +~~~ Upload credential lifetimes are bounded by `patch-storage.upload-credential-ttl` (defaults to 15 minutes). diff --git a/docs/server/tutorial/livepatch-and-microk8s.md b/docs/server/tutorial/livepatch-and-microk8s.md index b966ae8..1fffb14 100644 --- a/docs/server/tutorial/livepatch-and-microk8s.md +++ b/docs/server/tutorial/livepatch-and-microk8s.md @@ -243,7 +243,7 @@ sudo snap install canonical-livepatch-server-admin sudo snap alias canonical-livepatch-server-admin.livepatch-admin livepatch-admin ``` -Export the Livepatch Server URL and log in: +Log in with the admin tool, supplying the Livepatch Server URL with `--url`: ```bash sudo livepatch-admin --url http://livepatch.test.com login -a username:password