sandbox-cli-cluster-offboard

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:

1. Disables scheduling on the cluster
2. Cleans up all active placements (namespaces, service accounts, quotas, etc.)
3. Removes the cluster configuration from the sandbox API
4. 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.