Software installation jobs

Overview

Software installation jobs run the actual software installation on target instances. Installation jobs use images that have already been distributed to the instances (see Software distribution jobs). The installation job type determines how the upgrade is orchestrated across your fleet — see Installation job types below.

Benefits and key features

  • Orchestrated upgrades — Install distributed images across the fleet with per-instance progress and status.
  • Job type to match your environment — Choose HA pair or Standalone (Serial or Parallel execution) for the right balance of availability and speed.
  • Uses pre-distributed images — Installs from images already staged on instances, shortening the end-to-end upgrade time.

Installation job types

F5 Insight supports multiple installation job types to match different operational requirements. This release includes HA pair and Standalone installation types; Standalone installations use a Serial (Rolling Execution) or Parallel (Batch Execution) execution pattern. The type you choose determines how the upgrade is orchestrated across your instances, balancing speed against availability. For a side-by-side comparison, see Choose the right job type below.

Important

In F5 Insight version 1.2, a Standalone installation job type requires that all BIG-IPs selected are neither ‘Active’ nor ‘Standby.’ The name refers to how F5 Insight performs the upgrade — each selected instance is installed independently, with no automated HA failover — therefore, the instances must not be in an HA pair. In a future release, Standalone installation jobs will support upgrading HA pairs without failover, so that the administrator can control traffic and failover on their own schedule.

High availability pairs

High availability (HA) pair installation jobs upgrade two instances that are configured as an HA pair. F5 Insight orchestrates the upgrade to maintain traffic availability throughout the process.

How it works:

  1. At the beginning of the installation/upgrade job, F5 Insight identifies the Active and Standby instances in the HA pair.
  2. The Standby instance is upgraded first.
  3. After the Standby upgrade completes and the instance is verified healthy, a failover occurs.
  4. The formerly Active instance (now Standby) is upgraded.
  5. Final health checks confirm both instances are healthy and running the desired software version.

Considerations:

  • The HA pair installation job can be configured with several human-in-the-loop (HITL) pauses at key points, giving you control during the upgrade.
  • Traffic continues to flow throughout the upgrade process via the Active instance.
  • A failover event occurs mid-process.
  • If the Standby upgrade fails, or the administrator deems that the new software is causing an adverse effect, the job can be paused or aborted before upgrading the Active instance.

Important

Parallel HA pair installations: To upgrade multiple HA pairs in parallel, create a separate installation job for each pair and run them simultaneously. To upgrade multiple HA pairs serially (one pair at a time), include them in a single job. In a future release, F5 Insight will support parallel HA-pair upgrades within a single job.

Standalone installations

Standalone installations upgrade each selected instance independently.

Two execution patterns are available, set with the Execution Type field: Serial (Rolling Execution) and Parallel (Batch Execution). The Standalone installation job can be configured with human-in-the-loop (HITL) pauses between instances (Serial execution) or between batches (Parallel execution).

Serial (Rolling Execution)

Serial (Rolling Execution) installations upgrade instances one at a time, sequentially.

How it works:

  1. F5 Insight starts with the first instance as defined in the job.
  2. The instance is upgraded and verified healthy.
  3. The next instance is then upgraded.
  4. This continues until all instances in the job are upgraded.

When to use:

  • When you need to minimize risk by upgrading one instance at a time.
  • When you want to monitor each upgrade before proceeding to the next.
  • When instances serve independent traffic and sequential upgrades are acceptable.

Parallel (Batch Execution)

Parallel (Batch Execution) installations upgrade multiple instances simultaneously.

How it works:

  1. Batch size is configured in the software installation job parameters. For example, an installation job might define 12 total instances with a batch size of 4, so only 4 are run in parallel.
  2. F5 Insight selects the first batch of instances in the order defined in the job.
  3. These instances are upgraded in parallel.
  4. Once the first batch completes, F5 Insight begins the next batch of instances.
  5. The job completes when all instances report success or failure.

When to use:

  • When you need to upgrade many instances quickly.
  • When instances are behind a load balancer or are otherwise redundant.
  • During scheduled maintenance windows where speed is prioritized.

Choose the right job type

Use this comparison to pick the job type that best fits your availability and speed requirements:

Criteria HA pair Standalone — Serial (Rolling Execution) Standalone — Parallel (Batch Execution)
Traffic continuity Maintained via failover Per-instance downtime All instances down simultaneously
Upgrade speed Moderate (2 instances) Slow (sequential) Fast (parallel)
Best for Active/Standby pairs needing continuous traffic Risk-sensitive, closely monitored upgrades Fast bulk upgrades in a maintenance window

Prerequisites

  • Software image successfully distributed to the target instances.
  • Target instances in a healthy state and ready for installation.
  • Appropriate change management approvals in place.
  • Maintenance window scheduled (recommended).

Create an installation job

To create an installation job, go to the Manage section in the left toolbar, select Automation > Jobs, then select Add Job > Software Installation.

Create an HA pair installation job

  1. On the New: Software Installation Job form, confirm the Enabled toggle (top right) is on.

  2. Under General Settings, enter a Job Name (required) and an optional Description.

  3. Job Type is Manual (the only option in this release).

  4. Under Installation Type:

    • Set Installation Type to HA Pair.
    • The Execution Type is set to Serial (Rolling Execution), which is the only option for HA pair jobs.
    • Select the failover options as needed:
      • Automatic failback after both instances in the HA pair are upgraded — When enabled, F5 Insight reverts the Active instance to its original role after both instances are upgraded and verified healthy.
      • Pause before failback — When enabled, F5 Insight pauses the failback so you can verify the new Active instance is healthy before reverting to the original Active instance.
      • Disable Auto Config-Sync during the installation process — When enabled, F5 Insight disables automatic configuration synchronization during the installation, preventing configuration changes on the Active instance from syncing to the Standby instance during the upgrade. F5 Insight re-enables automatic configuration synchronization after the job completes if it was enabled beforehand. This setting applies to the entire job, so ensure all HA pairs in the job have the same auto config-sync setting.
    • Under Installation Pauses, select any of the human-in-the-loop (HITL) pauses:
      • After software installation on the Standby instance, before reboot — When enabled, prevents reboot of the Standby instance until you manually resume the job, so you can verify the Standby instance is healthy and ready to reboot.
      • After reboot of the Standby instance, before failover (Recommended) — When enabled, prevents failover until you manually resume the job, so you can verify the upgraded Standby instance is healthy before it takes over traffic.
      • After failover, before software installation on the new Standby instance — When enabled, prevents installation on the new Standby instance until you manually resume the job, so you can verify the new Active instance is healthy and serving traffic before proceeding.
      • After software installation on the new Standby instance, before reboot — When enabled, prevents reboot of the new Standby instance until you manually resume the job, so you can verify it is healthy and ready to take over as Active before rebooting.

  5. Under Software, select the Target Version.

  6. Under Instances:

    • Set the Set Target Volume option (for example, First Inactive (Numerically)). The available options are:
      • First Inactive (Numerically) — F5 Insight sets the target volume to the first inactive volume in numerical order.
      • Last Inactive (Numerically) — F5 Insight sets the target volume to the last inactive volume in numerical order.
      • Next Sequential (New) — F5 Insight sets the target volume to a new volume based on the existing volumes. For example, if the last install was on HD1.2, F5 Insight targets HD1.3 and creates that volume at execution.
    • Select Select Instances to open the Instance Selection drawer. Only instances compatible with the selected target version are shown. Use the columns (Hostname, MGMT IP, Platform, Version, HA Role, HA Peer, Service Check Date) and the Search box to find your targets, and select both members of each HA pair — the HA Role and HA Peer columns identify partners.
    • Select Back to Job Settings to return. Selected instances appear with their role, Active Volume, and Target Volume.

    Note

    Using First Inactive (Numerically) lets you re-run the job later with minimal rework — you only update the target version. For example, the initial run installs Hardened Release 1 to HD1.2 (HD1.1 is the Active volume); a couple of weeks later, a run to install HR 2 — still set to First Inactive (Numerically) — installs HR 2 to HD1.1 (HD1.2 is now Active). Administrators can re-run the installation job on a recurring basis with minimal rework.

  7. Under Readiness Checks, select Run Check to validate each instance before running the job. Each instance is marked Ready or Failed; a blocking failure disables Execute Job until you remove the instance or resolve the issue and re-run the check. Checks include:

    • Image Compatibility
    • HA Sync Status
    • Software Image Presence
    • Disk Space
    • Upgrade Path
    • License Compatibility
    • License Date

  8. Under Pre & Post Flight Snapshot, select View Options and choose the Core Checks to capture before and after the upgrade for comparison:

    • Trunk status
    • Interface status
    • Virtual server state
    • Pool health
    • Pool member health
    • tmsh show sys performance all-stats

  9. Select Save to save the job for later, or Execute Job to run it now.

  10. After you select Execute Job, F5 Insight shows a confirmation window. Optionally, enter a Change Request tracking # that will persist with the job execution details. You MUST enter “BEGIN INSTALLATION” in the confirmation field to run the install. Select Execute Job to start the installation.

  11. To Review the Job Execution status, either click on the Yes in the Executing column, or click on the digit in the Executions column for the Job you wish to view.

  12. See the Monitor job status section below for more details on monitoring the job execution.

Create a Standalone installation job

  1. On the New: Software Installation Job form, confirm the Enabled toggle (top right) is on.
  2. Under General Settings, enter a Job Name (required) and an optional Description.
  3. Job Type is Manual (the only option in this release).
  4. Under Installation Type:
    • Set Installation Type to Standalone.
    • Set Execution Type:
      • Serial (Rolling Execution) — upgrades instances one at a time. Under Installation Pauses, optionally select Pause between instances.
      • Parallel (Batch Execution) — upgrades instances in batches. Set the Batch Size (maximum 50). Under Installation Pauses, optionally select Pause between batches.
  5. Under Software, select the Target Version — the distributed image to install.
  6. Under Instances:
    • Set the Set Target Volume option (for example, First Inactive (Numerically)). The same Target Volume options are available as for HA pair jobs (see above).
    • Select Select Instances to open the Instance Selection drawer (only instances compatible with the selected target version are shown), select the instances to include, then select Back to Job Settings.
  7. Under Readiness Checks, select Run Check to validate each instance. The same checks run as for an HA pair job, except HA Sync Status is skipped for standalone instances.
    • Image Compatibility
    • Software Image Presence
    • Disk Space
    • Upgrade Path
    • License Compatibility
    • License Date
  8. Under Pre & Post Flight Snapshot, select View Options and choose the Core Checks to capture before and after the upgrade for comparison:
    • Trunk status
    • Interface status
    • Virtual server state
    • Pool health
    • Pool member health
    • tmsh show sys performance all-stats
  9. Select Save to save the job for later, or Execute Job to run it now.
  10. After you selecct Execute Job, F5 Insight shows a confirmation window. Optionally, enter a Change Request tracking # that will persist with the job execution details. You MUST enter “BEGIN INSTALLATION” in the confirmation field to run the install. Select Execute Job to start the installation.
  11. To Review the Job Execution status, either click on the Yes in the Executing column, or click on the digit in the Executions column for the Job you wish to view.
  12. See the Monitor job status section below for more details on monitoring the job execution.

Human-in-the-loop pauses, resuming and aborting jobs

Pauses

  • Based on the job’s configuration, F5 Insight may pause the installation execution at key points so you can verify that an instance is healthy and ready to proceed. When a job execution is paused, F5 Insight displays a banner indicating the job execution is paused and requires your attention.
  • Enabling pauses is not required for a job to execute; it is up to the administrator to decide which pauses are needed, based on the environment and risk tolerance.
  • An administrator can also pause a job execution from the F5 Insight interface. Pausing does not halt the step already in progress — it prevents the subsequent step (and all following) from starting.

A common Installation Pauses configuration is the following:

☐ After software installation on the Standby instance, before reboot
☑ After reboot of the Standby instance, before failover
☑ After failover, before software installation on the new Standby instance
☐ After software installation on the new Standby instance, before reboot

The reasoning behind this configuration is that the administrator wants to verify that:

  1. The first selected pause is to verify that the Standby instance has been upgraded successfully, is healthy, and ready to take over traffic before failover occurs.
  2. The second selected pause is to verify that the new Active instance (the one that was upgraded) is serving traffic correctly, before proceeding to upgrade the new Standby instance.

Resuming jobs

  • Resume a paused job execution from the F5 Insight interface.

Aborting jobs

  • An administrator can abort an executing job from the F5 Insight interface. Aborting the job halts some tasks but not all — for example, once a BIG-IP has begun rebooting, that step cannot be stopped, whereas aborting during a software distribution abandons the in-flight file copy to the BIG-IP(s).

Monitor job status

  • View job progress by select Yes in the Executing column or the digit in the Executions column for the Job you want to view status.
  • Each job displays its current status as well as a prior history. The Executions column shows the number of times the job has run.
  • For HA pair jobs, the detail view shows context on a pair basis, detailing the steps taken on the Standby instance first, and then, after failover, the new Standby (formerly Active).
  • Select a job for detailed logs, step-by-step progress, and any warnings or errors.

Refresh instance metadata

F5 Insight refreshes instance metadata hourly. If volumes or installed versions have changed, F5 Insight may display incorrect volume and version information for an instance. Refreshing the instance pulls live data from the BIG-IP — current version, boot volumes (HD1.x), license info, disk space, and HA state — so that F5 Insight reflects the current reality.

Note

In a future release, a Refresh Info button will be available in the Instances section of the installation job form (next to Set Target Volume). In the 1.2 release, use the API workaround below.

Refresh via API

The API endpoint to refresh a device’s metadata is:

POST /api/v1/fleet/upgrade/devices/{deviceId}/refresh

You need the device’s UUID (not its IP address). To find it, list the devices first, then call refresh with the UUID.

Step 1 — Get the device list to find the UUID:

curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://<INSIGHT_IP>/api/v1/fleet/upgrade/devices" \
  | python3 -c "import sys,json
for d in json.load(sys.stdin).get('devices',[]):
    print(f\"{d['id']}  {d.get('hostname','')}  {d.get('endpoint','')}\")"

Step 2 — Refresh the instance by UUID:

curl -sk -X POST \
  "https://<INSIGHT_IP>/api/v1/fleet/upgrade/devices/<DEVICE_UUID>/refresh" \
  -H "Authorization: Bearer $TOKEN"

The response confirms the refresh. F5 Insight then updates the instance’s metadata: current software version, boot volumes, license information, disk space, and HA state.

Troubleshooting

For more detailed software installation log messages, SSH to the F5 Insight host and check /opt/f5insight/logs/provisioning.log.

Issue Possible cause Resolution
Installation fails to start Image not distributed Verify the distribution job completed successfully.
Instance unreachable during install Network issue or instance reboot Check connectivity; the instance may be rebooting as part of the upgrade.

Rollback

If an upgrade causes issues, the primary rollback mechanism is to boot the BIG-IP back into the volume it was running before the upgrade started. Each BIG-IP maintains multiple boot volumes (for example, HD1.1 and HD1.2); the installation job installs the new software to an inactive volume, so the previous version remains intact on the original volume.

Important

In the 1.2 release, rollback must be performed outside of F5 Insight — directly on the BIG-IP (via the console, SSH, or the BIG-IP UI). A future release will add rollback support within F5 Insight.

To roll back:

  1. Identify the previous boot volume — the volume the BIG-IP was running before the upgrade (for example, HD1.1). This information is visible in the installation job’s instance table (Active Volume column) or on the BIG-IP itself via tmsh list sys software volume.

  2. On the BIG-IP, activate the previous volume:

    tmsh reboot volume HD#.#

  3. The BIG-IP reboots into the previous version. Verify it is healthy.

  4. If the BIG-IP is part of an HA pair, rollback should be performed with consideration of which instance is Active and which is Standby.

  5. (Optionally) After the rollback, refresh the instance metadata in F5 Insight (see Refresh instance metadata above) so the console reflects the current running version.

Note

Rolling back restores the previous software version but does not revert configuration changes made after the upgrade. If configuration changes were made post-upgrade, they may need to be reconciled manually.

Scale limits

  • Support for 100 instances in one software installation job.
  • Support for up to 50 instances in parallel (parallel batch size).
  • When using the HA pair installation type, up to 50 HA pairs are supported per job (executed in serial, one pair at a time).

Out of scope for the initial release

The following capabilities are not included in this release:

  • Major and minor version upgrades — The initial release is scoped to deliver installations within a major and minor software version. For example, the initial release does not support minor (17.1.3 to 17.5.1) or major (17.x to 21.x) version upgrades.
  • Hotfix installations — This release does not support hotfix installations. Hotfixes are planned for the next release.
  • Active/Active with Traffic Groups — High availability installation does not support Active/Active configurations with Traffic Groups.