Hypershield reference🔗

Hypershield 10.0.0🔗

The two loopback interfaces per switch are used for management (controller source) and HA heartbeat.

config add dpu🔗

Add a DPU configuration entry from a JSON file. This appends to the existing DPU set; it does not replace it.

Usage:

agwctl config add dpu [flags]

Flags:

config add ha🔗

Add the HA configuration to the AGW from a JSON file. Replaces any existing HA configuration.

Usage:

agwctl config add ha [flags]

Flags:

config load_dpu_config🔗

Replace the AGW’s DPU configuration with the contents of a JSON file. The file must be a single JSON object with the following fields:

• service_ip: string

• service_mac: string

• port_low: int

• port_high: int

Usage:

agwctl config load_dpu_config --file <file> [flags]

Flags:

config remove dpu🔗

Remove every DPU configuration entry currently held by the AGW.

Usage:

agwctl config remove dpu

config remove ha🔗

Remove the HA configuration currently held by the AGW.

Usage:

agwctl config remove ha

config show🔗

Show every AGW configuration object currently active, including DPU, HA, and syslog export configuration.

Usage:

agwctl config show

device show🔗

Show the full contents of the AGW device gNMI data store.

Usage:

agwctl device show

dpu debug🔗

Show repair state for every DPU peer, including:

• Repair-requested flag and last repair reason

• Reconnect count and last ack timestamp

• Per-policy repair fences currently blocking sync

Use --dpu to restrict output to a single DPU number.

Usage:

agwctl dpu debug [flags]

Flags:

dpu show🔗

Show the contents of the DPU gNMI data store. Use --filter to narrow the output to DPU names matching a regular expression.

Usage:

agwctl dpu show [flags]

Flags:

dpu status🔗

Show an aggregate summary of DPU fleet status. Reports counts only, without per-DPU details.

Usage:

agwctl dpu status

dpu sync🔗

Show SyncPolicy convergence state for every DPU peer, including:

• Desired, installed, and pending rule counts

• Last ack timestamp and in-sync-since timestamp

• Reconnect count

Use --dpu to restrict output to a single DPU, and --policy to include a per-policy drift breakdown for DPUs that have not yet converged.

Usage:

agwctl dpu sync [flags]

Flags:

ha compatibility🔗

Show a side-by-side comparison of HA membership and adjacency compatibility fields between the local switch and each HA peer. Use --peer to restrict the comparison to a single peer.

Usage:

agwctl ha compatibility [flags]

Flags:

ha debug fail🔗

Set the debug_override HA criterion to false on the local node, forcing it into ha-switchover state. Run agwctl ha debug ok to restore normal operation.

Usage:

agwctl ha debug fail

ha debug ok🔗

Set the debug_override HA criterion to true on the local node, allowing normal HA criteria evaluation to resume. Clears a failure previously injected by agwctl ha debug fail.

Usage:

agwctl ha debug ok

ha debug peer-fail🔗

Inject a debug failure for a specific HA peer’s membership or adjacency criterion. Exactly one of --membership or --adjacency must be set, along with --peer. Run agwctl ha debug peer-ok to clear the injected failure.

Usage:

agwctl ha debug peer-fail [flags]

Flags:

ha debug peer-ok🔗

Clear a debug failure previously injected via agwctl ha debug peer-fail for a peer’s membership or adjacency HA criterion. Exactly one of the --membership or --adjacency flags must be set, along with --peer.

Usage:

agwctl ha debug peer-ok [flags]

Flags:

ha debug reset🔗

Clear every local and peer-directed HA debug criterion in a single call and (optionally) block until the pair is stable. This replaces the ad-hoc sequence of calls that HA integration tests otherwise issue back-to-back:

• agwctl ha debug ok

• agwctl ha debug peer-ok --membership

• agwctl ha debug peer-ok --adjacency

Usage:

agwctl ha debug reset [flags]

Flags:

ha debug timers reset🔗

Restore production HA loop timer defaults

Usage:

agwctl ha debug timers reset

ha debug timers set🔗

Override any subset of the HA loop timers. Unset flags leave the current value unchanged. At least one flag is required.

Usage:

agwctl ha debug timers set [flags]

Flags:

ha debug timers show🔗

Show the currently-active HA loop timers

Usage:

agwctl ha debug timers show

ha gids🔗

Show VRFs with GID or preset allocations on the local switch and every HA peer. Use this to verify GID reconciliation across the HA cluster.

Usage:

agwctl ha gids

ha info🔗

Show the static HA configuration, including HA IP and port, admin and operational state, leader status, and policy settings.

Usage:

agwctl ha info

ha peers🔗

Show detailed HA state for every peer. Use --filter to narrow the output to peer IPs matching a regular expression.

Usage:

agwctl ha peers [flags]

Flags:

ha show🔗

Show the HA cluster state, the local node state, and a per-peer summary with [OK]/[FAIL] indicators for membership, adjacency, and service.

Usage:

agwctl ha show

ha vlans🔗

Show VLANs with ID allocations on the local switch and every HA peer. Use this to verify VLAN reconciliation across the HA cluster.

Usage:

agwctl ha vlans

health🔗

Report the AGW agent’s health as observed by the local IPC health probe.

Usage:

agwctl health

load_syslog_cfg🔗

Load the syslog export configuration from a JSON file and push it to all DPU agents, replacing any existing configuration. The file must contain a JSON object keyed by export ID, where each entry has:

• id, name, description, type: string

• config: host, port, mode (string) and tls (bool)

• secrets: token, ca, cert, key, keyPassword (string)

Usage:

agwctl load_syslog_cfg <file>

logging🔗

Set the AGW process log level. Supported values for --level:

• debug

• info (default)

• warn

• error

Usage:

agwctl logging [flags]

Flags:

metrics show🔗

Show a snapshot of current AGW runtime metrics, including memory usage, CPU usage, policy counts, and DPU insert/update/delete error counters.

Usage:

agwctl metrics show

policies add🔗

Add a policy to the AGW from a YAML file.

WARNING: Adding policies locally bypasses the on-prem controller and may leave the AGW OUT OF SYNC with it.

Usage:

agwctl policies add [flags]

Flags:

policies clear🔗

Remove every policy currently loaded in the AGW.

WARNING: Clearing policies locally bypasses the on-prem controller and may leave the AGW OUT OF SYNC with it. To re-sync after clearing, restart HypershieldAgent from the NX-OS CLI (no in-service then in-service).

Usage:

agwctl policies clear

policies info🔗

Display a summary of loaded policies including:

• Rule limits (global and per-policy; 0 = unlimited)

• Total number of policies and rules

• Number of allow vs deny rules

• Policies and rules per namespace

• VRFs and VLANs in use

• Protocol distribution

Flags:

• --persisted: Summarize the on-disk checkpoint via AGW’s already-open DB.

• --diff: Report only ResourceIDs whose expanded rule count differs between the live handler and the persisted set. Identical entries collapse into a single count.

Usage:

agwctl policies info [flags]

Flags:

policies limit🔗

Get or set the rule limits the AGW enforces on incoming policies. When either limit is exceeded, the incoming policy upsert is rejected with a rate-limit error. Set a limit to 0 to disable that specific check.

Running with no flags prints the current limits.

Defaults:

• --set: 1000000 (global, across all policies)

• --set-per-policy: 75000 (single policy)

Usage:

agwctl policies limit [flags]

Flags:

policies remove🔗

Remove a policy from the AGW, identified either by its ResourceID passed as a positional argument or by a YAML file supplied via --file.

WARNING: Removing policies locally bypasses the on-prem controller and may leave the AGW OUT OF SYNC with it. To re-sync after removal, restart HypershieldAgent from the NX-OS CLI (no in-service then in-service).

Usage:

agwctl policies remove [resourceId] [flags]

Flags:

policies show🔗

Show the policies currently loaded in the AGW. Each policy’s ResourceID is kind/namespace/name as it appears in Kubernetes. Use --filter with a regular expression to narrow the list.

Pass --persisted to stream the on-disk checkpoint (bbolt) instead of the live handler. AGW walks its already-open DB in-process, so this is safe to run while AGW is up. Rule counts reflect the post-expansion form so the output matches the live view.

Usage:

agwctl policies show [flags]

Flags:

policies status🔗

Stream one frame per policy with desired and installed rule counts, matching RuleNames, and active SyncPolicy conditions per DPU.

Use --policy to restrict output to a single Kubernetes policy, and use --unhealthy-only to emit only policies with active SyncPolicy conditions.

Usage:

agwctl policies status [flags]

Flags:

policies translate🔗

Translate policies into the JSON rule format consumed by the DPU dataplane.

By default the current AGW policy set is translated using the AGW’s active VRFs. Use --file to translate policies from a YAML file instead, or --no-vrfs to translate every policy while ignoring active VRFs.

Usage:

agwctl policies translate [flags]

Flags:

policies validate🔗

Walk the on-disk policy checkpoint database and report any entries that RestorePolicyCheckpoint would skip at startup — malformed payload, unsupported schemaVersion, or missing kind/namespace/name. On success, also prints an info-style summary of the accepted entries.

Runs entirely on this host — no AGW round-trip. AGW holds an exclusive lock on the checkpoint file while running, so this command only succeeds when the agent is stopped (or against a copy of the file inspected via --dir).

Usage:

agwctl policies validate [flags]

Flags:

policies wait🔗

Block until all policies report no active SyncPolicy conditions across all DPUs, or until the timeout elapses.

Use --timeout to cap the wait duration. Exits non-zero on timeout and exits 130 on SIGINT.

Usage:

agwctl policies wait [flags]

Flags:

show_dpu🔗

Show DPU peer status in the legacy table format. Prefer agwctl dpu show for the current, richer output.

Usage:

agwctl show_dpu

show_log🔗

Show a head and tail excerpt of the AGW process log buffer maintained by the agent on disk.

Usage:

agwctl show_log

show_status🔗

Show the AGW agent’s operational status, including uptime, IPC state, and DPU connectivity.

Usage:

agwctl show_status

show_syslog_cfg🔗

Show the syslog export configuration the AGW has currently pushed to DPU agents.

Usage:

agwctl show_syslog_cfg

show_tech🔗

Show a full AGW tech-support snapshot, aggregating status, metrics, policies, configuration, VRF/VLAN/DPU/HA state, and syslog output for support diagnostics.

This is a compatibility alias for agwctl tech-support show. Prefer the subcommand form in new scripts.

Usage:

agwctl show_tech

show_timescape_cfg🔗

Show the Timescape client configuration used by the AGW, including:

• Client status (enabled or disabled)

• Server information: endpoint URL and username (passwords are redacted)

• gRPC configuration: enabled status and port

Usage:

agwctl show_timescape_cfg

show_tokens🔗

Show metadata for the AGW’s cached access and refresh tokens. The token value itself is only printed when JSON output is requested via --json.

Usage:

agwctl show_tokens

tac_pac🔗

Collect a Cisco TAC support bundle on the local switch.

This is a compatibility alias for agwctl tech-support bundle that writes the bundle to the historical path /iox_data/agw_logs.tgz. The bundle contains AGW logs and configuration, the on-disk policy checkpoint, system state, and — when the AGW agent is reachable over IPC — its show_tech output plus a DPU log archive.

Core dumps are excluded (they can be multi-GB per file). Collect them separately with agwctl tech-support cores or via the NX-OS show cores command.

Prefer agwctl tech-support bundle for new integrations; it writes a timestamped file under /data/volatile and accepts flags for finer control.

Usage:

agwctl tac_pac

tech-support bundle🔗

Collect a compressed tech-support bundle on the local switch.

The bundle always includes local artifacts (AGW logs and config, on-disk policy checkpoint, and system state such as dmesg / ps / df). It also attempts to contact the running AGW agent over its IPC socket to include show_tech output and a DPU log archive.

Core dumps are NOT included by default — cores may be multi-GB per file and are handled by agwctl tech-support cores on their own. Pass --include-cores to fold them into this bundle anyway.

If AGW is not running (crashed, restarting, or not deployed) the local artifacts are still collected — the IPC-derived sections are simply marked skip in the bundle’s MANIFEST.txt. This is the intended behaviour: a tech-support bundle is most valuable exactly when the agent is unhealthy.

Bundle path defaults to /data/volatile/agw_tech_support_<UTC-timestamp>.tar.gz.

Usage:

agwctl tech-support bundle [flags]

Flags:

tech-support cores🔗

Collect a tarball containing only core dumps found on the local switch.

Cores are copied newest-first with a per-bundle budget (see MANIFEST.txt for details); anything past the budget is recorded in core_dumps/_SKIPPED.txt so support can request it out-of-band. No IPC calls are made — this command works whether or not AGW is running.

Output defaults to /data/volatile/agw_cores_<UTC-timestamp>.tar.gz.

Usage:

agwctl tech-support cores [flags]

Flags:

tech-support dpu🔗

Collect a tech-support archive from every DPU peer. This subcommand requires the AGW agent to be running — it uses the agent’s SSH credentials to reach each DPU.

If AGW is not running, use agwctl tech-support bundle instead: that collects local artifacts even when the agent has crashed.

Usage:

agwctl tech-support dpu

tech-support show🔗

Print a full AGW tech-support snapshot to stdout, aggregating status, metrics, policies, configuration, VRF/VLAN/DPU/HA state, and syslog output. Requires the AGW agent to be running — this command talks to the agent’s IPC socket.

Use agwctl tech-support bundle when AGW is crashed: it collects local artifacts and marks the IPC-derived sections as skipped in the bundle’s MANIFEST.txt.

Usage:

agwctl tech-support show

vlan info🔗

Show aggregate VLAN statistics, including total count, active count, ID assignment, and pinning distribution.

Usage:

agwctl vlan info

vlan list🔗

Print a compact table of active VLANs, followed by a count summary.

Usage:

agwctl vlan list

vlan show🔗

Show the contents of the VLAN gNMI data store. Use --filter to narrow the output to VLAN names matching a regular expression.

Usage:

agwctl vlan show [flags]

Flags:

vrf gids🔗

Show the GID allocation table for every VRF currently holding a GID on the local switch.

Usage:

agwctl vrf gids

vrf info🔗

Show aggregate VRF statistics, including total count, active count, GID usage, and pinning distribution.

Usage:

agwctl vrf info

vrf list🔗

Print a compact table of active VRFs, followed by a count summary.

Usage:

agwctl vrf list

vrf show🔗

Show the contents of the VRF gNMI data store. Use --filter to narrow the output to VRF names matching a regular expression.

Usage:

agwctl vrf show [flags]

Flags:

clear collector-session statistics🔗

clear collector session statistics

Usage:

dpctl clear collector-session statistics [flags]

Flags:

clear flow🔗

clear flow object information

Usage:

dpctl clear flow

clear pipeline statistics🔗

clear pipeline statistics

Usage:

dpctl clear pipeline statistics [command]

clear pipeline statistics datapath-assist🔗

clear pipeline datapath assist statistics

Usage:

dpctl clear pipeline statistics datapath-assist

clear pipeline statistics drop🔗

clear pipeline statistics

Usage:

dpctl clear pipeline statistics drop

clear session🔗

clear a specific session by ID and its associated flows

Usage:

dpctl clear session [flags]

Flags:

debug create collector-session🔗

create collector session

Usage:

dpctl debug create collector-session [flags]

Flags:

debug create telemetry-policy🔗

create telemetry policy

Usage:

dpctl debug create telemetry-policy [flags]

Flags:

debug datapath-assist🔗

datapath assist debug command

Usage:

dpctl debug datapath-assist [flags]

Flags:

debug delete collector-session🔗

delete collector session

Usage:

dpctl debug delete collector-session [flags]

Flags:

debug delete telemetry-policy🔗

delete telemetry policy

Usage:

dpctl debug delete telemetry-policy [flags]

Flags:

debug pipeline internal packet-trace-rule create🔗

add packet trace rule

Usage:

dpctl debug pipeline internal packet-trace-rule create [flags]

Flags:

debug pipeline internal packet-trace-rule delete🔗

delete packet trace rule

Usage:

dpctl debug pipeline internal packet-trace-rule delete [flags]

Flags:

debug port-counters clear🔗

Reset all port operation counters to zero

Usage:

dpctl debug port-counters clear

debug port-counters show🔗

Display statistics about port operations in the policy engine

Usage:

dpctl debug port-counters show

debug update🔗

debug update commands

Usage:

dpctl debug update

hs fwa_message🔗

fwa_message

Usage:

dpctl hs fwa_message [flags]

Flags:

hs ha disable🔗

disable

Usage:

dpctl hs ha disable

hs ha enable🔗

enable

Usage:

dpctl hs ha enable

hs ha peers add🔗

add

Usage:

dpctl hs ha peers add [flags]

Flags:

hs ha peers clear🔗

Clear HA flow sync statistics shown by hs ha peers show

Usage:

dpctl hs ha peers clear

hs ha peers show🔗

Show HA peer status including local/peer IPs, ports, state (UP/DOWN/UNKNOWN), and keepalive sequence numbers

Usage:

dpctl hs ha peers show

hs ha steering show🔗

Show HA flow sync steering table entries programmed for P4 qid steering

Usage:

dpctl hs ha steering show

hs ha timer🔗

timer commands

Usage:

dpctl hs ha timer [command]

hs ha timer delete_query🔗

Set HA delete query timeout in milliseconds

Usage:

dpctl hs ha timer delete_query <ms>

hs ha timer delete_query_idle🔗

Set HA delete query idle timer in milliseconds

Usage:

dpctl hs ha timer delete_query_idle <ms>

hs ha timer interval🔗

Set HA keepalive interval in milliseconds

Usage:

dpctl hs ha timer interval <ms>

hs ha timer keepalive🔗

Set HA max missed keepalive threshold

Usage:

dpctl hs ha timer keepalive <count>

hs ha timer keepalive_up_update🔗

Set periodic HA status replay interval in seconds. A value of 0 disables periodic replay.

Usage:

dpctl hs ha timer keepalive_up_update <sec>

hs ha timer show🔗

Show HA timer settings

Usage:

dpctl hs ha timer show

hs ha timer timeout🔗

Set HA keepalive timeout in milliseconds

Usage:

dpctl hs ha timer timeout <ms>

hs log_export show🔗

Show log export status including configuration and collectors

Usage:

dpctl hs log_export show

hs logging🔗

logging {error | info | verbose | debug | drops | timestamp {enable | disable}} If the level is omitted, the current log level will be printed. Use ‘timestamp enable’ or ‘timestamp disable’ to control timestamps. Use ‘drops’ to log only dropped packets with details.

Usage:

dpctl hs logging [command]

hs logging categorize🔗

Enable or disable categorized logging. When enabled, logs are routed to separate files based on category (HA, Policy, Main).

Usage:

dpctl hs logging categorize [flags]

Flags:

hs logging category🔗

Set log level for a specific category. When a category’s log level is set independently, logs for that category are automatically routed to a separate file.

Categories: main - General/main logs (dp-app.log) ha - HA-related logs (dp-app-ha.log) policy - Policy-related logs (dp-app-policy.log)

Log levels: error, info, debug, verbose, drop

Examples: dpctl hs logging category --name ha --level debug # Set HA logs to debug, route to dp-app-ha.log dpctl hs logging category --name policy --level info # Set Policy logs to info, route to dp-app-policy.log dpctl hs logging category --name ha --reset # Reset HA to global level, stop separate file dpctl hs logging category --name ha # Show current HA log level

Usage:

dpctl hs logging category [flags]

Flags:

hs logging drop clear🔗

Clear all captured packets from the buffer

Usage:

dpctl hs logging drop clear

hs logging drop show🔗

Display all captured packets in the buffer

Usage:

dpctl hs logging drop show

hs logging drop start🔗

Start capturing dropped packets with optional category filter.

Categories: all - Capture all drops (default) policy - Policy-related drops (explicit deny, default deny, no match) parse - Packet parsing/header drops (invalid header, unsupported ethertype) flow - Flow/session programming drops ha - HA-related drops (control messages, errors)

Usage:

dpctl hs logging drop start [flags]

Flags:

hs logging drop status🔗

Show packet drop logging status and statistics

Usage:

dpctl hs logging drop status

hs logging drop stop🔗

Stop capturing dropped packets

Usage:

dpctl hs logging drop stop

hs logging drop summary🔗

Show number of packets dropped per policy

Usage:

dpctl hs logging drop summary

hs logging drop write🔗

Export captured packets from buffer to file

Usage:

dpctl hs logging drop write [flags]

Flags:

hs pol disable🔗

disable

Usage:

dpctl hs pol disable

hs pol enable🔗

enable

Usage:

dpctl hs pol enable

hs policies clear🔗

clear

Usage:

dpctl hs policies clear

hs policies limit🔗

Set the hypershield policy limit

Usage:

dpctl hs policies limit <count>

hs policies show🔗

show

Usage:

dpctl hs policies show [flags]

Flags:

hs policies update🔗

update

Usage:

dpctl hs policies update [flags]

Flags:

hs policy-update-timer🔗

policy update timer (500ms to 600000ms)

Usage:

dpctl hs policy-update-timer

hs vrf add🔗

Add VRF information

Usage:

dpctl hs vrf add

hs vrf del🔗

Delete VRF information

Usage:

dpctl hs vrf del

hs vrf disable🔗

disable

Usage:

dpctl hs vrf disable

hs vrf enable🔗

enable

Usage:

dpctl hs vrf enable

hs vrf show🔗

show

Usage:

dpctl hs vrf show

hs vrf show-map🔗

Display VRF Map table information

Usage:

dpctl hs vrf show-map

show collector-session🔗

show collector session

Usage:

dpctl show collector-session [flags] [command]

Flags:

show collector-session statistics🔗

show collector session statistics

Usage:

dpctl show collector-session statistics [flags]

Flags:

show dpu-capacity🔗

show DPU table capacity and resource usage in hardware

Usage:

dpctl show dpu-capacity [command]

show dpu-capacity summary🔗

show DPU capacity summary with table and worker thread usage

Usage:

dpctl show dpu-capacity summary

show flow🔗

show flow object information

Usage:

dpctl show flow [flags]

Flags:

show flow-analysis🔗

show detailed flow/session/policy analysis for a specific flow filtered by 5-tuple (supports both IPv4 and IPv6)

Usage:

dpctl show flow-analysis [flags]

Flags:

show npu_address🔗

npu_address

Usage:

dpctl show npu_address

show pipeline internal table constant🔗

show P4 pipeline table constant

Usage:

dpctl show pipeline internal table constant

show pipeline internal table info🔗

show P4 pipeline table information

Usage:

dpctl show pipeline internal table info

show pipeline internal table nacl🔗

show nacl information

Usage:

dpctl show pipeline internal table nacl

show pipeline internal table nexthop🔗

show nexthop table entry information

Usage:

dpctl show pipeline internal table nexthop [flags]

Flags:

show pipeline internal table rewrite🔗

show rewrite table entry information

Usage:

dpctl show pipeline internal table rewrite [flags]

Flags:

show pipeline statistics🔗

show pipeline statistics

Usage:

dpctl show pipeline statistics [command]

show pipeline statistics datapath-assist🔗

Show pipeline datapath assist statistics

Usage:

dpctl show pipeline statistics datapath-assist [flags]

Flags:

show pipeline statistics drop🔗

show pipeline drop statistics

Usage:

dpctl show pipeline statistics drop

show session🔗

show session object information

Usage:

dpctl show session [flags]

Flags:

show telemetry-policy🔗

show telemetry policy

Usage:

dpctl show telemetry-policy [flags]

Flags:

show uplink-pinning🔗

show uplink pinning

Usage:

dpctl show uplink-pinning

show version🔗

show version information

Usage:

dpctl show version

tcp-state-check disable🔗

Disable TCP state machine compliance checking. When disabled, packets that violate the TCP state machine will not be dropped.

Usage:

dpctl tcp-state-check disable

tcp-state-check enable🔗

Enable TCP state machine compliance checking. When enabled, packets that violate the TCP state machine will be dropped.

Usage:

dpctl tcp-state-check enable

tcp-state-check show🔗

Show whether TCP state machine compliance checking is enabled in the P4 datapath.

Usage:

dpctl tcp-state-check show

bootstrap capi🔗

Install and initialize CAPI (with no infra providers) on the cluster.

Usage:

isoctl bootstrap capi

bootstrap install🔗

Bootstrap and install a new management cluster.

Usage:

isoctl bootstrap install [flags]

Flags:

Examples:

# Install bootstrap cluster interactively
isoctl bootstrap install

# Install bootstrap cluster from config
isoctl bootstrap install -f bootstrap.yaml

bootstrap validate🔗

Validate a bootstrap config file with offline and/or online checks.

Offline checks:

• required bootstrap fields (vSphere settings, networks)

• proxy settings and noProxy value format

• network/IPAM values (names, ranges, prefix, nameservers, optional gateway)

• no overlap between networks[*].ipam.addresses and effective pod/service CIDRs (mgmtCluster.podCIDR/serviceCIDR or defaults)

• network IPAM address capacity per configured segment against required node replicas (controlPlaneReplicas + workerReplicas)

• management cluster API and SSH auth strategy settings

• mgmtCluster.vmProfile value (must be one of: standard, hypershield)

• mgmtCluster.vmSizing bounds (numCPUs: 4..256, memoryMiB: 8192..1048576 when set)

• warning when both vmProfile and vmSizing are set (vmSizing overrides vmProfile/defaults per field; unset fields keep profile/default values)

• when using nodeAuthorizedKeysFromAgent as the only auth option: SSH_AUTH_SOCK must be set and ssh-agent must have at least one loaded private key

• archive paths and runtime prerequisites

• preflight check: bootstrap kind cluster name is not already in use

Online checks:

• vSphere connectivity/authentication

• vSphere inventory lookups (datacenter, datastore, resource pool, networks)

• management requested-IP preflight for mgmtCluster.apiServer.address (fail if the address responds to ICMP or already listens on TCP/6443)

• proxy endpoint TCP reachability (host/IP + configured port)

• container registry reachability (docker.io/registry.k8s.io/quay.io/ghcr.io), warning-only for potential airgap installs

• warning-only IPAM collision scan against visible VM guest IPs

Skipped during online checks:

• vSphere folder existence

• VM template existence

Usage:

isoctl bootstrap validate [flags]

Flags:

Examples:

# Validate all checks (default)
isoctl bootstrap validate -f bootstrap.yaml

# Validate only local/offline checks
isoctl bootstrap validate -f bootstrap.yaml --validation-mode offline

# Validate only provider connectivity/resource checks
isoctl bootstrap validate -f bootstrap.yaml --validation-mode online

charts extract🔗

Extract a Helm chart from the cluster

Usage:

isoctl charts extract [CHART_NAME...] [flags]

Flags:

Examples:

# Extract a single chart
isoctl charts extract harbor-1.17.2 -o /tmp/

# Extract multiple charts
isoctl charts extract harbor-1.17.2 cilium-1.18.10 infra-0.1.1 -o /tmp/

# Extract all charts
isoctl charts extract --all -o /tmp/

# Extract from custom manifest
isoctl charts extract harbor-1.17.2 --manifest /path/to/install.yaml -o /tmp/

charts list🔗

List available Helm charts in the cluster

Usage:

isoctl charts list [flags]

Flags:

hypershield dev create🔗

Create a kind cluster wired for Hypershield and deploy Hypershield into it.

This mirrors a BYOVM install with no vSphere or Cluster API: it creates the kind cluster (default CNI and kube-proxy disabled) with the caller’s Docker registry credentials mounted so the kubelet can pull enterprise images, applies the operator bundle, installs the Gateway API CRDs and enterprise Cilium, then runs the operator in-cluster and creates a self-targeting Hypershield CR.

With --mode leader the Hypershield CR is deployed in Timescape Leader mode with the web UI, Public API, a bespoke in-cluster Dex OIDC provider, and a host-exposed gateway. The UI and authenticated Public API are both reachable from the host.

With --mode follower the cluster joins an existing leader. First register the follower on the leader UI and copy back the join credential, then pass it here with --credential along with --leader (the leader kind cluster name). The cluster ID is read from the credential, and the leader address, CA, and the follower’s k8s host are all auto-discovered. Multiple followers can join one leader; each is its own kind cluster. The follower name (--follower-name, or --name) must match the name registered on the leader.

Usage:

isoctl hypershield dev create [flags]

Flags:

Examples:

# Leader dev cluster (UI, Public API, Dex, and gateway are always on)
isoctl hypershield dev create --name hs-leader --mode leader

# Follower joined to the hs-leader cluster (credential copied from the leader UI)
isoctl hypershield dev create --name hs-follower-1 --mode follower \
  --leader hs-leader --credential "$CREDENTIAL"

hypershield dev delete🔗

Delete the kind cluster created by ‘isoctl hypershield dev create’ and remove its per-cluster state directory (the resolved registry credentials, kubeconfig, and any leader/follower credential material such as the join credential and the Dex/leader CAs).

This is idempotent: deleting a cluster that does not exist is not an error.

Usage:

isoctl hypershield dev delete [flags]

Flags:

Examples:

# Delete the default dev cluster
isoctl hypershield dev delete

# Delete a named cluster
isoctl hypershield dev delete --name hs-leader

hypershield install🔗

Create or update the Hypershield CR and wait for all components to be ready.

Deployment modes:

CAPI (default):

• Resolves the MgmtCluster from the current kubeconfig context.

• Creates a cluster-scoped Hypershield CR using the MgmtCluster namespace as its management namespace.

• Uses the MgmtCluster’s admin kubeconfig to deploy components.

• Uses vsphere-csi as the Timescape PVC storage class.

BYOVM:

• Select this mode with --byovm for an existing cluster not provisioned through CAPI.

• Requires --admin-kubeconfig-secret to identify an admin kubeconfig Secret.

• Creates a cluster-scoped Hypershield CR using isovalent-operator-system as its management namespace.

• Uses longhorn as the Timescape PVC storage class.

Components installed:

• ClickHouse operator

• CloudNativePG operator

• Control plane (CRDs and SmartSwitch configuration)

• Hubble Timescape (configure UI and Public API exposure via -f or --timescape-* flags)

The complete configuration is validated before any cluster resources are changed.

Usage:

isoctl hypershield install [flags]

Flags:

Examples:

# Install on a CAPI-provisioned cluster
isoctl hypershield install

# Install on a pre-existing cluster (BYOVM / brownfield)
isoctl hypershield install --byovm --admin-kubeconfig-secret my-admin-kubeconfig

# Install with Timescape UI (operator manages TLS automatically)
isoctl hypershield install \
  --timescape-ui-enabled \
  --timescape-ip 10.0.0.100 \
  --timescape-ui-hostname timescape.example.com

# Install with Timescape UI using user-provided TLS certificates
isoctl hypershield install \
  --timescape-ui-enabled \
  --timescape-ip 10.0.0.100 \
  --timescape-ui-hostname timescape.example.com \
  --timescape-ui-tls-cert-file /path/to/tls.crt \
  --timescape-ui-tls-key-file /path/to/tls.key

# Install in the leader profile without initial identity bindings
isoctl hypershield install \
  --timescape-profile leader \
  --timescape-ip 10.0.0.200 \
  --timescape-sc-ip 10.0.0.201 \
  --timescape-server-hostname timescape-grpc.example.com \
  --timescape-public-api-enabled \
  --timescape-public-api-hostname api.example.com \
  --timescape-server-rbac-oidc-issuer-url https://my-account.okta.com/oauth2/default \
  --timescape-server-rbac-oidc-client-id 0oabc123def456 \
  --timescape-server-rbac-oidc-ca-file /path/to/oidc-ca.crt

# Install in the leader profile using a config file (see example.hypershield-install.yaml)
isoctl hypershield install -f hypershield-install.yaml

hypershield upgrade🔗

Validate and apply a supported Hypershield release artifact.

The install path may be an upgrade .tar.zst bundle or the expanded directory installed by an isovalent-upgrade-hypershield Debian/RPM package. Installing the package only stages files; it does not change the cluster.

One immutable release contains the complete infrastructure and application payload. It may change either or both. The command executes their ordered internal stages and records the release only after the complete target converges.

Phase 1 supports CAPI-managed Hypershield installations.

Usage:

isoctl hypershield upgrade [flags]

Flags:

hypershield validate🔗

Validate a Hypershield installation config without changing cluster resources.

Validation checks:

• unknown or obsolete configuration fields

• a required Timescape leader or follower profile

• required leader and follower settings

• Timescape UI and Public API exposure and OIDC consistency

• referenced credential, certificate, and client-secret files

• optional component requirements

Usage:

isoctl hypershield validate [flags]

Flags:

Examples:

# Validate a configuration file
isoctl hypershield validate -f hypershield-install.yaml

# Validate the equivalent CLI arguments before installing
isoctl hypershield validate \
  --timescape-profile leader \
  --timescape-ip 10.0.0.200 \
  --timescape-server-hostname timescape-grpc.example.com \
  --timescape-server-rbac-oidc-issuer-url https://idp.example.com \
  --timescape-server-rbac-oidc-client-id my-client-id

hypervisor-agnostic validate🔗

Validate a hypervisor-agnostic Hypershield cluster config with offline and/or online checks.

Offline checks:

• required fields (podCIDR, serviceCIDR, controlPlaneReplicas, workerReplicas, apiServer.address)

• network names, IPAM addresses, gateway, and nameservers

• no overlap between networks[*].ipam.addresses and pod/service CIDRs

• network IPAM address capacity against required node replicas

• proxy settings and noProxy value format

• nodeAuthorizedKeys format when provided

• controller and worker IP resolution from networks[0].ipam.addresses

Online checks:

• proxy endpoint TCP reachability (host/IP + configured port)

Usage:

isoctl hypervisor-agnostic validate [flags]

Flags:

Examples:

# Validate all checks (default)
isoctl hypervisor-agnostic validate -f cluster-config.yaml

# Validate only local/offline checks
isoctl hypervisor-agnostic validate -f cluster-config.yaml --validation-mode offline

# Validate only network reachability checks
isoctl hypervisor-agnostic validate -f cluster-config.yaml --validation-mode online

ilb accesslog🔗

Display load balancer T2 access log.

Usage:

isoctl ilb accesslog

ilb applicationlog🔗

Display load balancer T2 application log.

Usage:

isoctl ilb applicationlog

ilb delete🔗

Delete a load balancer by name.

Usage:

isoctl ilb delete NAME [flags]

Flags:

Examples:

  # Delete LB and wait for completion
  isoctl ilb delete my-loadbalancer --wait

# Delete LB cluster and don't wait
  isoctl ilb delete my-loadbalancer

ilb install🔗

Install a load balancer.

Usage:

isoctl ilb install [flags]

Flags:

Examples:

# Install a basic load balancer from args using SSH_AGENT for node auth
   isoctl ilb install --name lb --address 10.53.53.249 --t1 2 --t2 3 --node-authorized-keys-from-agent

   # Install a load balancer from a MgmtCluster manifest
   isoctl ilb install -m loadbalancer.yaml

   # Install a load balancer from a config file
   isoctl ilb install -f config.yaml

ilb kubeconfig🔗

Get the kubeconfig for a load balancer by name.

Usage:

isoctl ilb kubeconfig NAME [flags]

Flags:

Examples:

# Get the kubeconfig for a load balancer
isoctl ilb kubeconfig my-loadbalancer

ilb service🔗

Display load balancer service status.

Usage:

isoctl ilb service

ilb status🔗

Display load balancer status.

Usage:

isoctl ilb status

ilb switch🔗

Switch between cluster contexts.

Usage:

isoctl ilb switch [NAME] [flags]

Flags:

Examples:

# Switch between contexts interactively
isoctl switch

# Switch to context by cluster name
isoctl switch my-loadbalancer

# Swicth to management cluster context
isoctl switch --mgmt

ilb sysdump🔗

Collect information required to troubleshoot issues with Cilium and Hubble.

Usage:

isoctl ilb sysdump

ilb test🔗

Run load balancer tests.

Usage:

isoctl ilb test

ilb upgrade🔗

Upgrade the ILB cluster using the given install artifact tarball.

Usage:

isoctl ilb upgrade [flags]

Flags:

images load🔗

Load container images from the given local image archive to the management cluster’s registry, or to an explicitly provided registry.

Usage:

isoctl images load ARCHIVE [flags]

Flags:

Examples:

  # Load a local zst compressed image archive
isoctl images load my-images.tar.zst

# Load a local zst compressed image archive to an explicit registry
isoctl images load my-images.tar.zst --registry registry.example.com

# Load to an explicit registry with a self-signed certificate
isoctl images load my-images.tar.zst --registry registry.example.com --insecure-skip-tls-verify

# Load to an explicit registry with basic auth
isoctl images load my-images.tar.zst --registry registry.example.com --username myuser --password mypass

kubeconfig🔗

Get the kubeconfig for all clusters

Usage:

isoctl kubeconfig [flags]

Flags:

mgmtcluster delete🔗

Delete a management cluster.

The nuke strategy is intended for repeated CI/test environments where speed and full teardown are prioritized over graceful uninstall semantics.

Usage:

isoctl mgmtcluster delete [flags]

Flags:

operator install🔗

Install the Isovalent Operator into an existing Kubernetes cluster (BYOVM).

The command applies the embedded operator bundle (CRDs, RBAC, Deployment, and related resources from install.yaml), then waits until the controller-manager Deployment is available.

The operator Deployment’s manager container image comes from the embedded manifest (for example quay.io/isovalent-dev/isovalent-operator-ci:latest). Cluster nodes must be configured to pull from your registry when you are not using a public registry (registry mirrors, TLS trust, and credentials as required by your environment). You do not need to pass a registry host or Harbor project path in this command when node configuration already resolves the embedded image reference.

Use --operator-image only when you want to replace the manager container image with a different reference (for example <registry>/<project>/<image>:<tag>).

Flags:

• -k, --kubeconfig: Path to kubeconfig (default: standard kubeconfig path)

• --context: Kubeconfig context (default: mgmtcluster.isovalent.com)

• --timeout: Max wait for operator readiness (default: 10m)

• --operator-image: Override only the manager container image on the operator Deployment

Usage:

isoctl operator install [flags]

Flags:

Examples:

# Install using current kubeconfig defaults
isoctl operator install

# Install with explicit kubeconfig and context (typical BYOVM admin cluster)
isoctl operator install --kubeconfig ~/.kube/config --context admin

# Install with a longer readiness wait
isoctl operator install --timeout 15m

# Optionally replace the manager container image
isoctl operator install --operator-image isovalent-dev/isovalent-operator-ci:latest

switch🔗

Switch between cluster contexts.

Usage:

isoctl switch [NAME] [flags]

Flags:

Examples:

# Switch between contexts interactively
isoctl switch

# Switch to context by cluster name
isoctl switch my-loadbalancer

# Swicth to management cluster context
isoctl switch --mgmt

sysdump🔗

Collect a sysdump from the cluster containing logs and diagnostics information for troubleshooting

Usage:

isoctl sysdump [flags]

Flags: