rhpds/sandbox-cli:cluster-details

---

context: main

Skill: cluster-details

Name: Sandbox Cluster Details Description: Get detailed configuration and status of a specific OCP shared cluster registered with the RHDP Sandbox API.

---

Purpose

Display the full configuration, annotations, health status, token rotation state, and quota settings for a specific cluster. This is useful for debugging cluster issues, verifying onboard configuration, or checking token rotation health.

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

If the user hasn't specified a cluster name, list all clusters to help them choose:

sandbox-cli cluster list

Ask the user which cluster they want details for.

Step 5: Get Cluster Details

sandbox-cli cluster get <CLUSTER_NAME>

Expected output:

{
  "annotations": {
    "cloud": "cnv-dedicated-shared",
    "lab": "lb1401-sec-genai-guardrails-service",
    "purpose": "dev"
  },
  "api_url": "https://api.cluster-ld7tc.dynamic.redhatworkshops.io:6443",
  "created_at": "2026-04-02T05:24:02.783263Z",
  "created_by": "ritesh",
  "data": {
    "connection_last_success_at": "2026-04-02T05:25:14.123456Z",
    "connection_status_at": "2026-04-02T05:25:14.123456Z",
    "deployer_admin_sa_token_updated_at": "2026-04-02T05:25:14.123456Z"
  },
  "deployer_admin_sa_token_refresh_interval": "24h",
  "deployer_admin_sa_token_target_var": "cluster_admin_agnosticd_sa_token",
  "deployer_admin_sa_token_ttl": "48h",
  "ingress_domain": "apps.cluster-ld7tc.dynamic.redhatworkshops.io",
  "name": "cluster-ld7tc",
  "quota_required": false,
  "skip_quota": true,
  "valid": true
}

Step 6: Summarize for the User

Present the key information in a readable format:

| Field | Value | |-------|-------| | Name | cluster name | | Valid | yes/no | | API URL | the API endpoint | | Ingress Domain | the wildcard domain for routes | | Created By | who onboarded it | | Created At | when it was onboarded | | Annotations | cloud, purpose, lab labels | | Skip Quota | whether quota enforcement is skipped | | Token TTL | deployer admin SA token lifetime | | Token Refresh | how often the token is refreshed | | Last Connection | last successful health check | | Token Last Updated | last token rotation timestamp |

Also flag any potential issues:

• If valid is false, the cluster is unreachable
• If data.connection_last_success_at is 0001-01-01T00:00:00Z, the sandbox API hasn't connected yet
• If data.deployer_admin_sa_token_updated_at is 0001-01-01T00:00:00Z, token rotation hasn't completed

Key Fields

| Field | Description | |-------|-------------| | annotations | Labels used for placement matching (cloud, purpose, lab) | | api_url | OCP API server endpoint | | ingress_domain | Wildcard domain for routes (e.g., apps.cluster-xxxxx...) | | valid | true if the cluster is reachable and healthy | | created_by | User who onboarded the cluster | | skip_quota | Whether ResourceQuota enforcement is skipped | | deployer_admin_sa_token_ttl | How long the admin SA token is valid | | deployer_admin_sa_token_refresh_interval | How often the token is refreshed | | deployer_admin_sa_token_target_var | Variable name used to pass the token to deployers | | data.connection_last_success_at | Last successful API health check | | data.deployer_admin_sa_token_updated_at | Last time the deployer token was rotated |

Important Notes

• The full output includes the cluster's service account token -- this is sensitive and should not be shared.
• If data.connection_last_success_at shows 0001-01-01T00:00:00Z, the sandbox API hasn't successfully connected yet. This is normal immediately after onboarding -- wait a few minutes for the first health check cycle.
• If valid is false, the cluster is unreachable. Common causes: cluster decommissioned, network/firewall issues, or API certificate expired.
• To test if a cluster matches specific workload selectors, use sandbox-cli placement dry-run --selector 'key=value'.