Upgrade F5 Insight¶

Overview
Concepts
Use the web console
Use the REST API
Troubleshooting
Reference: files and locations
Reference: useful commands

Overview ¶

F5 Insight supports two upgrade paths for moving an appliance to a newer product version:

Type	Description	Method	Rollback behavior
Full upgrade	Updates the platform, host packages, K3s runtime, container images, Linkerd, and Helm release to a new product build.	Platform-manager runs `upgrade.sh` phases and uses Helm for the application release.	Automatic rollback is attempted for non-OS failures. Restore from a pre-upgrade backup to recover from full-upgrade rollback needs.
Patch	Updates selected service images without changing the full platform.	Platform-manager updates selected Kubernetes deployments with image changes.	Previous images are captured and can be restored automatically (on failure) or manually.

You perform upgrades using a bundle you upload to the appliance:

Method	Description
Bundle upload	A `.tar.gz` bundle uploaded to the appliance. The bundle is stored on the VM filesystem under `/opt/f5insight/system/bundle`.

Current version

You can read the current product version from the installed appliance state. The primary source of truth is:

/opt/f5insight/.version

The upgrade API exposes this version through:

GET /api/system/upgrade/current

Concepts ¶

Upgrade types ¶

Full upgrades and patches are both represented as upgrade bundles but are handled differently.

Attribute	Full upgrade	Patch
Manifest kind	`full_upgrade`	`patch`
Expected content	Platform packages, application images, Helm chart, optional OS package ISO, optional K3s package, Linkerd content	Application images for selected services
Kubernetes update method	`helm upgrade`	Image update for selected deployments
Backup requirement	Required by default unless explicitly skipped	Required by default unless explicitly skipped
Manual rollback API	Not supported - restore from backup instead	Supported for the latest successful patch within 72 hours
Cancel API	Supported for running jobs	Supported for pending or running patch jobs

Patch bundle manifest example

version: "1.2.1-3"
kind: "patch"
minimum_supported_version: "1.2.0"
services:
  - frontend

Full upgrade bundle manifest example

version: "1.2.0-211"
kind: "full_upgrade"
image_tag: "1.2.0-211"
minimum_supported_version: "1.1.0"

platform:
  k3s_version: "v1.34.3+k3s1"

application:
  helm_charts:
    - f5insights

Automatic kind detection

If kind isn’t specified in the manifest, F5 Insight detects the type from the manifest structure:

Manifest contains	Detected kind
`platform` or `application`	`full_upgrade`
`services`	`patch`
Neither	Rejected unless the top-level directory clearly identifies the type

Catalog ¶

The catalog API returns available upgrades from locally uploaded bundles:

GET /api/system/upgrade/catalog?mode=offline

The response returns only the latest available patch and the latest available full upgrade from local bundle storage. It doesn’t return every bundle present on disk.

Catalog entries are sourced from bundles stored in:

/opt/f5insight/system/bundle

Bundle upload and retention ¶

Upload bundles using the following endpoint:

POST /api/system/upgrade/upload

Upload behavior

Attribute	Details
File type	Must be a `.tar.gz` bundle
Size limit	Maximum 8 GB
Version rule	Uploaded bundle version must be greater than the current installed version
Kind retention	One uploaded patch and one uploaded full upgrade can coexist
Replacement	A new patch replaces the existing uploaded patch only; a new full upgrade replaces the existing uploaded full upgrade only
Sidecars	System-manager writes `.sha256` and `.metadata.json` sidecar files
Storage	Bundle and sidecars are stored on the VM filesystem, not in the database

Note

Patch uploads don’t replace full-upgrade uploads, and full-upgrade uploads don’t replace patch uploads.
If an uploaded bundle is deleted or replaced, pending scheduled upgrades for that bundle version are cancelled.

Version compatibility ¶

Version compatibility is enforced before the upgrade is applied. The current version must be lower than the target version. Same-version and downgrade attempts are blocked.

The bundle manifest must include:

minimum_supported_version: "<version>"

Compatibility examples

Current version	Target version	Minimum supported	Result
`1.2.0-105`	`1.2.1-3`	`1.2.0`	Allowed
`1.1.0-58`	`1.2.1-3`	`1.2.0`	Blocked - current version below minimum
`1.2.1-3`	`1.2.1-3`	`1.2.0`	Blocked - same version
`1.2.1-3`	`1.2.0-106`	`1.1.0`	Blocked - downgrade not supported

Compatibility is checked against the minimum_supported_version field in the bundle manifest. The legacy fields minimum_version and min_version are no longer part of the current contract.

Pre-upgrade backup ¶

Backups are required by default for both manual and scheduled upgrades unless the caller explicitly selects skip backup.

When backup is not skipped, the request must include:

Parameter	Description
`backup_passphrase`	Passphrase used to encrypt the pre-upgrade backup
`backup_type`	Backup scope (for example, `full` or `config`)
`storage_target`	Local appliance storage or a configured network storage target

Note

For scheduled upgrades, the passphrase is stored securely and retrieved only when the schedule runs. It is cleaned up after the schedule is triggered, cancelled, replaced, or fails.
On DR standby nodes, system-manager forces backup skip because the standby is a read-only replica.

Preflight checks ¶

Preflight validation runs before the upgrade job is accepted and again inside the platform script before phases execute.

System-manager preflight checks

Check	Blocking	Description
`no_active_job`	Yes	Blocks when an upgrade is already running
`disk_space`	Yes	Requires free disk to be at least the bundle size plus a 20 percent buffer
`pod_health`	Bypassable	Checks that active pods are ready; completed pods are ignored
`dr_pair`	Yes	Enforces DR role and upgrade order
`version_compatibility`	Yes	Enforces that the target version is greater than the current version and meets the minimum supported version

Disk space calculation

Required free bytes = bundle size + (bundle size / 5)

That is a 20 percent buffer. For example:

Bundle size: 10 GB
Required:    12 GB

Free disk is checked at the following paths (in order):

s.bundleDir - when configured
/opt/f5insight/system - when available as the system directory
/opt/f5insight - as the final fallback

The platform script also performs its own host-level preflight checks after extracting the bundle, including K3s availability, Kubernetes API access, namespace presence, version compatibility, and disk/image checks.

High availability and disaster recovery ¶

System-manager detects the upgrade role based on the appliance’s DR configuration:

Role	Description
`standalone`	No DR configuration detected
`primary`	DR is configured and local PostgreSQL is writable
`standby`	DR is configured and local PostgreSQL is in recovery/read-only mode
`unknown`	DR configuration exists but the role can’t be determined

DR upgrade behavior

Role	Behavior
Standalone	Normal backup and scheduling policy
Standby	Backup is skipped, schedules are disabled, manual apply is allowed
Primary	Preflight requires the standby to already be on the target version

Important

The required DR upgrade order is:

Upgrade the standby node manually.
Confirm the standby is running the target version.
Upgrade the primary node.

During a full upgrade on standby, the script keeps write-oriented services scaled down. It also disables write-oriented hooks so the standby remains safe while PostgreSQL is read-only.

Lite mode compatibility ¶

The following upgrade APIs are compatible with Lite mode:

Catalog, current version, preflight, apply, job, rollback, upload, status, active-job, and history endpoints.
Upgrade schedule APIs are not available in Lite mode. Scheduled upgrades are treated as Full mode functionality unless product requirements change.

Rollback and recovery ¶

Patch rollback and full-upgrade rollback behave differently.

Patch rollback

Scenario	Behavior
Patch succeeds	Previous images are retained as a rollback snapshot
Latest successful patch is within 72 hours	Manual rollback is available
Patch fails after deployment starts	Automatic rollback is triggered
Patch is cancelled before deployment starts	Job is marked failed/clean
Patch is cancelled after deployment starts	Platform cancel is requested and automatic rollback is triggered

Full upgrade rollback

Scenario	Behavior
Failure before OS package phase finishes	No general automatic restore is guaranteed
Failure after non-OS phase starts	Full rollback is attempted
Helm failure	Helm rollback is attempted, then runtime Kubernetes state is restored
Full upgrade rollback request through API	Not supported - restore from the pre-upgrade backup instead

The full-upgrade script snapshots the following version files before phases run:

/opt/f5insight/.version
/opt/f5insight/.release
/etc/product_version

If packaging or platform packages overwrite version files during a failed upgrade, rollback restores the pre-upgrade version files from this snapshot.

Dirty state

A dirty state indicates the system might have changed after a failed patch and requires rollback or administrator review. Administrators can clear an unresolved dirty state only after verifying the system is clean:

POST /api/system/upgrade/jobs/{job_id}/confirm-clean

Use the web console ¶

Check the current version ¶

Navigate to: Info ‣ About

The page displays:

Field	Description
Current version	Version currently installed on the appliance
Latest available	Latest patch or full upgrade returned by the catalog (visible only after a bundle has been uploaded)
Update status	Whether an upgrade is available

Note

If the current version displays as v... or the page doesn’t load, check appliance health first. A failed or unhealthy core service can prevent the UI from displaying version details.

Download the upgrade package ¶

Before uploading a bundle, download the latest patch or full upgrade package from the MyF5 downloads portal.

Note

F5 Insight does not currently support an online method for fetching the latest upgrade. You must download the package manually from MyF5 and then upload it to the appliance.

Upload a bundle ¶

Navigate to Info ‣ About.
Select the Upload button.
Select the bundle file (.tar.gz) from your local system.
Wait for the upload to complete.

After a successful upload, the available upgrade appears in the Available Upgrades section below the upload control.

Warning

If the uploaded version is the same as or lower than the current installed version, the upload is rejected.

View available upgrades ¶

After uploading a bundle, the Available Upgrades section on the Info ‣ About page lists the latest available patch and full upgrade from the uploaded bundles.

Note

If no bundle has been uploaded, only the Upload button is displayed. Available upgrades appear only after a successful bundle upload.

Apply an upgrade (full upgrade or patch)¶

The upgrade workflow is the same for both full upgrades and patches. Follow these steps to apply an upgrade:

Select the upgrade ¶

Navigate to Info ‣ About.
In the Available Upgrades section, locate the full upgrade or patch you want to apply.
Select Apply on the upgrade you want to install.

Review preflight checks ¶

After you select Apply, F5 Insight automatically runs preflight checks. The results are displayed before you can proceed.

Check	Resolution if failed
No active job	Wait for the current job to finish or resolve a stale state
Disk space	Free disk space or remove old bundles/backups
DR pair	Upgrade the standby first or fix peer reachability
Version compatibility	Use a compatible newer bundle

If all preflight checks pass, select Continue to proceed to the backup step.

Note

If any blocking preflight check fails, resolve the issue before continuing. You cannot proceed with the upgrade until all blocking checks pass.

Configure pre-upgrade backup ¶

After preflight checks pass, the backup configuration screen appears. You can either take a backup or skip it.

Important

It is recommended to take a backup before applying an upgrade, even though you can skip it.

Option	Description
Skip backup	Select Skip Backup to proceed without a backup. Not recommended for production environments.
Config backup	Takes a configuration-only backup. Can be stored on local appliance storage.
Full backup	Takes a full backup including data and configuration. Requires an external (network) storage target to be configured.

If you choose to take a backup, fill in the required backup details (passphrase, backup type, and storage target) and select Continue.

Note

A full backup requires an external storage location (NFS or SMB) to be configured. If no external storage is available, use a config backup instead. For more information on configuring storage locations, see Back up and restore F5 Insight.

Apply or schedule the upgrade ¶

After the backup step, you can choose to apply the upgrade immediately or schedule it for a later time.

Apply now: Select Apply Now to start the upgrade immediately. The upgrade progress is displayed in the Active Job section.
Schedule upgrade: Select Schedule Upgrade to schedule the upgrade for a future date and time. The scheduled upgrade appears in the Schedule tab.

Note

To cancel a scheduled upgrade, navigate to the Schedule tab and cancel the pending schedule.
If you apply a manual upgrade for the same bundle version, any pending scheduled upgrade for that version is automatically cancelled.

Monitor upgrade progress ¶

After selecting Apply Now:

The upgrade progress is displayed in the Active Job section on the Info ‣ About page.
The active job shows the current status, progress, and any errors encountered during the upgrade.

Cancel an upgrade ¶

You can cancel a running upgrade (both full upgrade and patch) while it is in progress.

Navigate to Info ‣ About.
In the Active Job section, select Cancel on the running upgrade.

Note

If the upgrade has already progressed past certain phases, cancellation triggers an automatic rollback to restore the system to its previous state.

Roll back a patch ¶

Manual patch rollback is available for the latest successful patch within 72 hours of completion.

To roll back a patch:

Navigate to Info ‣ About.
Select the History tab.
Locate the most recent successful patch job.
Select the Rollback icon on that job entry.
Confirm the rollback when prompted.

The rollback progress is displayed in the Active Job section. After a successful rollback, the system returns to the previous version.

Note

The Rollback icon is visible only for the latest successful patch and only within 72 hours of the upgrade.
After 72 hours, the rollback option is no longer available.
Failed patch jobs use automatic rollback and do not require manual intervention.

Full upgrade rollback and recovery ¶

A full upgrade attempts automatic rollback for non-OS failures. Helm failures trigger a Helm rollback followed by a runtime Kubernetes state restore from a snapshot.

If rollback succeeds and workloads are healthy, the appliance returns to the previous running version.
If rollback completes but workloads are not healthy, the UI might display loading errors. Check the failed workload and recover it manually or restore from the pre-upgrade backup.

Important

The supported recovery path after a failed full upgrade is restoring from the pre-upgrade backup.

Use the REST API ¶

All upgrade tasks available in the web console are also available through the F5 Insight REST API, enabling automation and integration with existing tooling.

Authentication ¶

All upgrade endpoints are under /api/system/ and require authentication, authorization, activation/license checks, and audit logging.

Read endpoints are available to authenticated, activated users with the required feature authorization.
Mutating endpoints require the admin role.

Admin-only endpoints

POST   /api/system/upgrade/upload
DELETE /api/system/upgrade/upload
POST   /api/system/upgrade/apply
POST   /api/system/upgrade/jobs/{job_id}/cancel
POST   /api/system/upgrade/jobs/{job_id}/rollback
POST   /api/system/upgrade/jobs/{job_id}/confirm-clean
POST   /api/system/upgrade/schedule
DELETE /api/system/upgrade/scheduled/{sched_id}

Uploaded bundles ¶

Get current uploaded bundle info

GET /api/system/upgrade/upload

Upload a bundle

POST /api/system/upgrade/upload
Content-Type: multipart/form-data

bundle=<file>

Delete uploaded bundles

DELETE /api/system/upgrade/upload
DELETE /api/system/upgrade/upload?version=1.2.1-3
DELETE /api/system/upgrade/upload?kind=patch
DELETE /api/system/upgrade/upload?version=1.2.1-3&kind=patch

Catalog ¶

GET /api/system/upgrade/catalog?mode=offline

Response fields

Field	Description
`latest_patch`	Latest patch version from local bundle storage
`latest_full_upgrade`	Latest full-upgrade version from local bundle storage
`patches`	Latest patch entry, or empty
`full_upgrades`	Latest full-upgrade entry, or empty

Example catalog entry

{
  "version": "1.2.1-3",
  "kind": "patch",
  "minimum_supported_version": "1.2.0",
  "services": ["frontend"],
  "filename": "f5insight-1.2.1-3-bundle.tar.gz",
  "size_bytes": 123456789,
  "sha256": "<sha256>"
}

Current version ¶

GET /api/system/upgrade/current

Returns the current installed version. The host version file is the preferred source:

/opt/f5insight/.version

Preflight ¶

GET /api/system/upgrade/preflight?kind=patch&version=1.2.1-3
GET /api/system/upgrade/preflight?kind=full_upgrade&version=1.2.0-211

Example response

{
  "status": "200",
  "data": {
    "can_proceed": true,
    "checks": [
      {
        "name": "disk_space",
        "status": "pass",
        "message": "Need 12.0 GB, have 40.0 GB free",
        "bypass_allowed": false
      }
    ]
  }
}

Apply ¶

POST /api/system/upgrade/apply

Example: patch with backup skipped

{
  "version": "1.2.1-3",
  "kind": "patch",
  "skip_backup": true
}

Example: full upgrade with backup

{
  "version": "1.2.0-211",
  "kind": "full_upgrade",
  "skip_backup": false,
  "backup_passphrase": "<passphrase>",
  "backup_type": "full",
  "storage_target": "local"
}

Optional parameter

Parameter	Description
`bypass_preflight_checks`	Allows bypassable failed checks to be bypassed. Blocking checks can’t be bypassed.

Accepted response (202)

{
  "status": "202",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "pending"
  }
}

Jobs ¶

Get a job

GET /api/system/upgrade/jobs/{job_id}

Get active job

GET /api/system/upgrade/active-job

When no active job exists, data is null.

Cancel a patch job

POST /api/system/upgrade/jobs/{job_id}/cancel

Get postflight

GET /api/system/upgrade/jobs/{job_id}/postflight

Rollback ¶

Check rollback availability

GET /api/system/upgrade/jobs/{job_id}/rollback-state

Start manual patch rollback

POST /api/system/upgrade/jobs/{job_id}/rollback

Poll rollback status

GET /api/system/upgrade/rollback/{rollback_id}

Clear dirty state

POST /api/system/upgrade/jobs/{job_id}/confirm-clean

History and stats ¶

Get recent upgrade history

GET /api/system/upgrade/history

Get aggregate upgrade stats

GET /api/system/upgrade/history/stats

Scheduled upgrades ¶

Create a schedule

POST /api/system/upgrade/schedule

Example request

{
  "version": "1.2.1-3",
  "kind": "patch",
  "scheduled_at": "2026-07-10T18:30:00Z",
  "skip_backup": true
}

List pending schedules

GET /api/system/upgrade/scheduled

Cancel a pending schedule

DELETE /api/system/upgrade/scheduled/{sched_id}

List schedule history

GET /api/system/upgrade/scheduled/history

Get recommended scheduling window

GET /api/system/upgrade/schedule/recommendation

Legacy endpoints ¶

The legacy start endpoint is not supported from F5 Insight 1.2.0:

POST /api/system/upgrade/start

Use the following endpoint instead:

POST /api/system/upgrade/apply

The legacy status endpoint remains available:

GET /api/system/upgrade/status

Troubleshooting ¶

Uploaded bundle does not appear in catalog ¶

Verify the following:

The catalog request includes mode=offline.
The bundle exists under /opt/f5insight/system/bundle.
The bundle has .metadata.json and .sha256 sidecar files.
The uploaded version is greater than the current version.
The manifest has a valid kind or recognizable structure.
The catalog is expected to show only the latest patch and latest full upgrade.

sudo ls -lh /opt/f5insight/system/bundle

Same version still shows update available ¶

Check whether the catalog entry version exactly matches the current installed version:

cat /opt/f5insight/.version

Compare with:

GET /api/system/upgrade/current
GET /api/system/upgrade/catalog?mode=offline

Same-version upgrades should be blocked by upload validation and preflight compatibility checks.

Current version is wrong after rollback ¶

Check the following files:

cat /opt/f5insight/.version
cat /etc/product_version
sudo cat /opt/f5insight/system/upgrade-status.json | jq

The host file /opt/f5insight/.version is the source of truth. Full-upgrade rollback snapshots version files before phases run and restores them when packaging rollback is needed.

Note

If a test bundle contains older platform packages, it can overwrite version files. Use a test bundle built from the same base build as the appliance when testing failure scenarios.

Helm upgrade failed ¶

Check logs

sudo tail -f /opt/f5insight/logs/upgrade.log

Check Helm status

sudo KUBECONFIG=/etc/rancher/k3s/k3s.yaml helm history f5-insight -n f5-insight
sudo KUBECONFIG=/etc/rancher/k3s/k3s.yaml helm status f5-insight -n f5-insight

Check pod status

sudo kubectl get pods -n f5-insight
sudo kubectl get events -n f5-insight --sort-by=.lastTimestamp | tail -80

Common causes

Error	Cause
`context deadline exceeded`	Helm waited for workloads until timeout
`ImagePullBackOff`	Missing image, incorrect image tag, or image import issue
`exists and can't be imported`	Helm ownership annotation issue
Workloads not ready after rollback	Helm rollback completed but one or more pods are unhealthy

Vault is down after a failed upgrade ¶

Check Vault pod status

sudo kubectl get pod f5-insight-vault-0 -n f5-insight

Vault is healthy when it displays:

f5-insight-vault-0   3/3   Running

Check Vault images

sudo kubectl get sts f5-insight-vault -n f5-insight \
  -o jsonpath='{range .spec.template.spec.initContainers[*]}{.name}{" => "}{.image}{"\n"}{end}{range .spec.template.spec.containers[*]}{.name}{" => "}{.image}{"\n"}{end}'

If a test bundle used an incorrect image tag, Vault might remain in ImagePullBackOff. Restore the expected image tag and restart the pod.

Patch rollback is not available ¶

Manual patch rollback is blocked when:

The job is not a patch.
The job failed (failed patches use automatic rollback).
The job is not the latest successful patch.
The job completed more than 72 hours ago.
A newer successful upgrade or rollback exists.
The previous image snapshot is missing.

Active job shows stale running state ¶

Check the platform status:

sudo cat /opt/f5insight/system/upgrade-status.json | jq
sudo ps -ef | egrep 'upgrade.sh|helm|kubectl rollout|apt|dpkg' | grep -v grep

If no platform process is running but the job still appears active, compare:

GET /api/system/upgrade/active-job
GET /api/system/upgrade/jobs/{job_id}
GET /api/system/upgrade/history

Note

Dirty failed jobs appear in history and might require rollback or administrator confirmation.

Scheduled upgrade did not run ¶

Verify the following:

The schedule was set to a future time.
The appliance is not a DR standby node.
The bundle still exists in the catalog.
Preflight passed at execution time.
The schedule was not more than 5 minutes late when picked up.
The backup passphrase reference was available (if backup was required).

Reference: files and locations ¶

Path	Description
`/opt/f5insight/.version`	Current installed product version
`/opt/f5insight/system/bundle`	Uploaded upgrade bundles
`/opt/f5insight/system/staging`	Extracted bundle staging area during apply
`/opt/f5insight/system/upgrade-status.json`	Platform-manager upgrade status
`/opt/f5insight/logs/upgrade.log`	Upgrade script log
`/opt/f5insight/system/.upgraded_components`	Components upgraded during the current or resumed full upgrade

Reference: useful commands ¶

Current version

cat /opt/f5insight/.version

Bundle storage

sudo ls -lh /opt/f5insight/system/bundle

Upgrade status

sudo cat /opt/f5insight/system/upgrade-status.json | jq

Upgrade logs

sudo tail -f /opt/f5insight/logs/upgrade.log

Pod status

sudo kubectl get pods -n f5-insight

Helm history

sudo KUBECONFIG=/etc/rancher/k3s/k3s.yaml helm history f5-insight -n f5-insight

Running upgrade processes

sudo ps -ef | egrep 'upgrade.sh|helm|kubectl rollout|apt|dpkg' | grep -v grep

Previous Next