diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index c758f7e..5c23d46 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -9,12 +9,14 @@ Autoscaling aws backend backends +backoff backport bcrypt blocklisted blocklisting boolean bugfixes +burstable Canonical('s)? Charmcraft charmstore @@ -28,6 +30,8 @@ Diátaxis docstrings? downloader Downloader +downscoped +downscoping dvipng enablement Enablement @@ -82,6 +86,7 @@ Multipass MyST npm Numpy +OAuth oem OCI Open Graph @@ -89,6 +94,7 @@ openapi otf patchstore PDF +permissionless plaintext plantuml PNG @@ -97,6 +103,8 @@ PPAs PR PRs preconfigured +presigned +Presigned proxying Pygments pymarkdown @@ -139,6 +147,7 @@ TOC toctree triages txt +uploader ulwazi unapplied uncomment(ing)? 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..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} - -livepatch-admin login -a [username:password] +sudo livepatch-admin --url http(s)://{haproxy url} login -a [username:password] ``` ### 5. Download patches @@ -139,7 +137,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..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 @@ -121,7 +117,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 +125,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: @@ -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/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 2fe8215..f4a7441 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 @@ -260,7 +260,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. @@ -272,7 +272,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 d946616..b3444f2 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 @@ -236,8 +236,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..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 @@ -13,15 +13,16 @@ 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. +* 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. * 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 +40,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 +48,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. @@ -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,11 @@ 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.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 \ @@ -172,6 +179,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 3af3f3b..4120425 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,118 @@ --- 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. -``` -juju refresh haproxy -``` +## 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 canonical-livepatch-server-k8s --channel= --revision= ``` + +If you manage supporting infrastructure services via Juju, upgrade them as required: + +```bash juju refresh postgresql +juju refresh haproxy +juju refresh ubuntu-advantage ``` -``` -juju refresh ubuntu-advantage +### Standalone snap deployments + +In snap deployments, refresh the server snap: + +```bash +sudo snap refresh canonical-livepatch-server ``` +## Step 2: Apply database schema upgrades + +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 + +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 canonical-livepatch-server-k8s/leader schema-upgrade --wait ``` -juju refresh livepatch + +```{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. ``` -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: +If needed, restart units after the schema upgrade completes: +```bash +juju run canonical-livepatch-server-k8s/ restart --wait ``` -juju run-action livepatch/leader schema-upgrade --wait + +### Snap deployments + +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 + +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**. + +### 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 +sudo 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 +sudo livepatch-admin job-status ``` -juju run-action livepatch/ restart --wait + +Or view recent sync reports: + +```bash +sudo 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 `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 new file mode 100644 index 0000000..dad8ff6 --- /dev/null +++ b/docs/server/how-to-guides/patch-management/distribute-patches-offline.md @@ -0,0 +1,152 @@ +--- +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 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`. + +- **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 +sudo 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: + +```bash +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: + +- `--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. +- `--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 +$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 +``` + +- **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 `$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, placing it in that system's `$SNAP_COMMON/patches/` directory. + +## Step 3: Upload patches to the on-premises server + +Log in to your on-premises Livepatch Server with administrator credentials: + +```bash + sudo livepatch-admin --url https://livepatch.internal.example.com login --auth : +``` + +### Run the upload command + +Upload the patches placed in `$SNAP_COMMON/patches/`: + +```bash +sudo livepatch-admin patch upload +``` + +### Command options and flags + +`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. +- `--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 `$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 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, 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} +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/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/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/how-to-guides/security/setup-administration-tool.md b/docs/server/how-to-guides/security/setup-administration-tool.md index 54cd83c..6be9044 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 @@ -55,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} - -livepatch-admin login --auth : +sudo livepatch-admin --url 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/index.md b/docs/server/reference/patch-storage/index.md index d0a7bbf..4eade96 100644 --- a/docs/server/reference/patch-storage/index.md +++ b/docs/server/reference/patch-storage/index.md @@ -9,22 +9,46 @@ 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**: 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 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, 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:** 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. ```{toctree} :titlesonly: @@ -37,5 +61,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..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 @@ -8,12 +8,62 @@ 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: + +```{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`. +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 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: + 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). + +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 | -`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..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 @@ -8,12 +8,99 @@ 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. 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 + +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 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. -`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..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 @@ -8,12 +8,40 @@ 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: + +### 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) + +```{note} +Admin-tool-facilitated patch upload (`livepatch-admin patch upload`) is not supported for IBM Cloud Object Storage just yet. +``` -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..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 @@ -8,12 +8,55 @@ 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). Two policies are required: + +### Standard server operations + +For synchronising patches and delivering them to clients, the identity requires object read, write, and delete permissions. For instance principal authentication, add: + +~~~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 the following policy for instance principal authentication: + +~~~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). -`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..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 @@ -4,25 +4,106 @@ 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), 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 + +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. + +### 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" + }] +} ``` -https://.amazonaws.com/{filaname} + +### 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: + +``` +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..abb10bd --- /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 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..a42f37b 100644 --- a/docs/server/reference/platform/configuration.md +++ b/docs/server/reference/platform/configuration.md @@ -161,12 +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, 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` | @@ -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). 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`, `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 @@ -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 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` | | `patch-sync.proxy.https` | HTTPS proxy URL. | `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..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 -livepatch-admin login -a admin:admin123 +sudo livepatch-admin --url http://$HAPROXY_ADDRESS login -a admin:admin123 ``` ## Sync patches @@ -227,7 +221,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..1fffb14 100644 --- a/docs/server/tutorial/livepatch-and-microk8s.md +++ b/docs/server/tutorial/livepatch-and-microk8s.md @@ -243,11 +243,10 @@ 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 -export LIVEPATCH_URL="http://livepatch.test.com" -livepatch-admin login -a username:password +sudo livepatch-admin --url http://livepatch.test.com login -a username:password ``` ## Sync patches @@ -255,19 +254,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).