| name | sandbox-cli:cluster-offboard |
| description | This skill should be used when the user asks to "offboard a cluster", "remove a cluster from sandbox", "decommission a cluster", "sandbox offboard", "take a cluster offline", or "remove a shared cluster". |
context: main
Skill: cluster-offboard
Name: Sandbox Cluster Offboard
Description: Offboard an existing OCP shared cluster from the RHDP Sandbox API.
Purpose
Walk the user through safely offboarding an OCP shared cluster from the Sandbox API. This includes verifying VPN connectivity, identifying the cluster, checking active placements, running the offboard, and verifying cleanup.
Workflow
Step 1: Verify Prerequisites
Check that sandbox-cli is installed:
which sandbox-cli
If sandbox-cli is not installed, tell the user to run /sandbox-cli:sandbox-setup first and stop.
Step 2: Verify Red Hat VPN Connection
CRITICAL: Always verify VPN connectivity before any sandbox-cli operation.
host squid.redhat.com
If the DNS resolves (returns an IP address like 10.x.x.x), the user is on VPN. Proceed.
If it fails with NXDOMAIN, not found, or connection timed out, STOP and tell the user:
You are NOT connected to the Red Hat VPN. The sandbox API is IP-restricted and all commands will fail with EOF errors. Please connect to the Red Hat VPN before proceeding.
Do NOT proceed until VPN is confirmed.
Step 3: Check Authentication
sandbox-cli status
If not authenticated or token expired, tell the user to re-login:
sandbox-cli login --server <SERVER_URL> --token <TOKEN>
Step 4: Identify the Cluster to Offboard
List all clusters to help the user identify which one to offboard:
sandbox-cli cluster list
Output columns:
- NAME - Cluster identifier
- VALID - Whether the cluster is reachable (
yes / NO)
- CREATED_BY - Who onboarded it
- PLACEMENTS - Current active placements (e.g.,
3 / 10)
Ask the user which cluster to offboard. Note the cluster name and current placement count.
IMPORTANT: If the cluster has active placements, warn the user that offboarding will clean them up. The user should confirm they want to proceed.
Step 5: Get Cluster Details (Optional)
For additional context before offboarding:
sandbox-cli cluster get <CLUSTER_NAME>
This shows full configuration, annotations, and connection status.
Step 6: Login to the Cluster (if reachable)
If the cluster is still reachable (VALID = yes), login to it so the offboard can clean up resources:
oc login --token=<ADMIN_TOKEN> --server=<CLUSTER_API_URL>
If the cluster is unreachable (VALID = NO), the --force flag will be needed in Step 7.
Step 7: Run the Offboard
sandbox-cli cluster offboard <CLUSTER_NAME>
If the cluster is unreachable, use force mode:
sandbox-cli cluster offboard <CLUSTER_NAME> --force
What this does:
- Disables scheduling on the cluster
- Cleans up all active placements (namespaces, service accounts, quotas, etc.)
- Removes the cluster configuration from the sandbox API
- Polls for completion (up to 6 minutes, checking every 3 seconds)
Expected output:
==> Offboarding cluster '<CLUSTER_NAME>'...
Offboard started for cluster <CLUSTER_NAME>. N placement(s) to process.
Poll GET /api/v1/ocp-shared-cluster-configurations/<CLUSTER_NAME>/offboard for status.
==> Waiting for offboard to complete...
Offboard completed successfully.
If the offboard is taking long, check status manually:
sandbox-cli cluster offboard-status <CLUSTER_NAME>
Step 8: Verify Offboard
Confirm the cluster is no longer listed:
sandbox-cli cluster list
The offboarded cluster should no longer appear in the list.
Important Notes
- Force offboard (
--force) should only be used when the target cluster is permanently unreachable or decommissioned. It leaves orphaned resources (namespaces, service accounts, Ceph resources, Keycloak users) on the cluster.
- Only
admin and shared-cluster-manager (for own clusters) can offboard.
- Offboarding is asynchronous -- it may return HTTP 202 and poll for completion.
- If offboard fails partway through, some placements may require manual cleanup. The output will list these.
- Always verify with
sandbox-cli cluster list after offboarding.
