use-kube-dc-cli

Use Kube-DC CLI

The kube-dc CLI provides browser-based OAuth authentication and context management for Kube-DC clusters. It integrates as a kubectl exec credential plugin.

Installation

# Linux (amd64)
sudo curl -sL https://github.com/kube-dc/kube-dc-public/releases/latest/download/kube-dc_linux_amd64 -o /usr/local/bin/kube-dc && sudo chmod +x /usr/local/bin/kube-dc

# Linux (arm64)
sudo curl -sL https://github.com/kube-dc/kube-dc-public/releases/latest/download/kube-dc_linux_arm64 -o /usr/local/bin/kube-dc && sudo chmod +x /usr/local/bin/kube-dc

# macOS (Apple Silicon)
sudo curl -sL https://github.com/kube-dc/kube-dc-public/releases/latest/download/kube-dc_darwin_arm64 -o /usr/local/bin/kube-dc && sudo chmod +x /usr/local/bin/kube-dc

# macOS (Intel)
sudo curl -sL https://github.com/kube-dc/kube-dc-public/releases/latest/download/kube-dc_darwin_amd64 -o /usr/local/bin/kube-dc && sudo chmod +x /usr/local/bin/kube-dc

Commands

Login

kube-dc login --domain kube-dc.cloud --org {org-name}
kube-dc login --domain stage.kube-dc.com --org {org-name}
kube-dc login --domain internal.example.com --org {org-name} --ca-cert /path/to/ca.crt

Opens browser for Keycloak OAuth login. Tokens cached for ~30 days with auto-refresh.

Switch Context (org/project)

kube-dc use {org}/{project}    # Switch to specific project
kube-dc use                    # Interactive selection

Context names follow pattern: kube-dc/{domain}/{org}/{project}

List / Switch Namespace

kube-dc ns                     # List available namespaces (from JWT claims)
kube-dc ns {namespace}         # Switch to specific namespace

Show Configuration

kube-dc config show            # Current context, server, cached credentials
kube-dc config get-contexts    # List all kube-dc contexts

Logout

kube-dc logout                 # Remove credentials for current server
kube-dc logout --all           # Remove all cached credentials

Determine Current Context

Before creating resources, always check the current context:

# Quick check
kubectl config current-context

# Detailed info (server, namespace, token status)
kube-dc config show

# Available namespaces for current user
kube-dc ns

The namespace tells you the project: namespace {org}-{project} → org={org}, project={project}.

How kubectl Integration Works

After kube-dc login, the CLI configures kubectl with an exec credential plugin:

users:
- name: kube-dc@{org}
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1
      command: kube-dc
      args: ["credential", "--server", "https://kube-api.{domain}:6443"]

Every kubectl command automatically:

1. Returns cached token if valid
2. Refreshes token using refresh_token if expired
3. Prompts re-login only when refresh_token expires (~30 days)

kubectx / kubens Compatibility

kubectx                            # Lists all contexts including kube-dc ones
kubectx kube-dc/shalb/demo        # Switch to Kube-DC context

File Locations

Path	Purpose
~/.kube/config	Kubeconfig (Kube-DC entries merged, never overwrites others)
~/.kube-dc/config.yaml	CLI configuration
~/.kube-dc/credentials/	Cached OAuth tokens (0600 permissions)

Verification

After CLI operations:

After Login

# 1. Check credentials are cached
kube-dc config show
# Expected: shows server, user, org, valid access/refresh tokens

# 2. Verify kubectl works
kubectl get ns
# Expected: lists namespaces you have access to

After Context Switch

# 1. Verify active context
kubectl config current-context
# Expected: kube-dc/{domain}/{org}/{project}

# 2. Verify namespace
kubectl config view --minify -o jsonpath='{.contexts[0].context.namespace}'
# Expected: {org}-{project}

After Namespace Switch

# 1. Verify namespace changed
kube-dc ns
# Expected: asterisk (*) next to the active namespace

Success: Config shows valid tokens, kubectl commands return data. Failure:

• "not logged in": run kube-dc login --domain {domain} --org {org}
• "session expired": refresh token expired (~30 days), re-run login
• "Forbidden": user doesn't have access to the requested namespace/resource

Safety

• The CLI never stores passwords — only OAuth tokens with auto-refresh
• Tokens are cached with 0600 permissions (owner-read-only)
• Never log or display token contents in chat output
• If token is expired, suggest kube-dc login rather than trying to extract tokens manually