Teleport Kubernetes Access

Access Kubernetes clusters, pods, and databases through Teleport's secure proxy.

Reference: Quick Start with Teleport Wiki

Contents

• •Quick Start
• •RBAC & Safety Rules
• •Cluster Login
• •kubectl Operations
• •Debug Pod (Kafka/Postgres) → See debug-pod.md
• •AI Agent Workflow → See ai-agent-tmux.md
• •Troubleshooting → See troubleshooting.md

Quick Start

# 1. Login to Teleport (if expired)
tsh login --proxy=extreme-cloud.teleport.sh

# 2. Login to cluster
tkl va-rdc        # or: tsh kube login va-rdc

# 3. Run kubectl commands (read-only)
kubectl get pods -n nvo
kubectl logs -f deployment/nvo-network -n nvo

# 4. Access debug pod for Kafka/Postgres
tkl debug

When to Use

• •Accessing Kubernetes clusters managed by Teleport
• •Running kubectl commands against RDC/GDC clusters
• •Debugging with the middleware-access-util pod (Kafka, Postgres tools)
• •Connecting to databases through Teleport proxy
• •Checking pod health across multiple clusters
• •AI Agent database queries via tmux → See ai-agent-tmux.md

⚠️ CRITICAL: Dos and Don'ts

Role-Based Access Control

Scrum teams access production through read-only privileges only.

✅ Permitted Actions

🚫 Forbidden Actions

⚠️ Important Warnings

1. •All activities are monitored and recorded
2. •Debug pod auto-terminates in 2 hours
3. •Database queries MUST use WHERE conditions

Prerequisites

# Verify tsh is installed
which tsh  # /usr/local/bin/tsh

# Check login status
tsh status

# Login if expired
tsh login --proxy=extreme-cloud.teleport.sh

AI Agent Usage

When running kubectl commands programmatically, set KUBECONFIG explicitly:

# Recommended: Inline KUBECONFIG export
export KUBECONFIG=~/.kube/config && tsh kube login <cluster-name>
kubectl get pods -n nvo

# Alternative: Use tkl via interactive zsh
zsh -ic 'tkl <cluster-name> && kubectl get pods -n nvo'

For full AI agent workflow with database access via tmux: See ai-agent-tmux.md

Cluster Login Workflow

Using tkl (Recommended)

tkl va-rdc        # Virginia RDC
tkl eu0-gdc       # EU0 GDC
tkl stage-rdc     # Staging RDC
tkl k3s           # Switch to local k3s

What tkl does:

1. •Sets KUBECONFIG to ~/.kube/config
2. •Clears existing Teleport session
3. •Sources cluster-specific aliases
4. •Runs tsh kube login <cluster>

Manual tsh Commands

# List available clusters
tsh kube ls
tsh kube ls --format=json | jq -r '.[].kube_cluster_name'

# Login to specific cluster
tsh kube login va-rdc

# Check current context
tsh status
kubectl config current-context

Common Cluster Types

⚠️ Cluster Name Resolution (IMPORTANT for AI Agents)

Cluster names ALWAYS include the suffix (-rdc, -gdc). When a user provides a partial name, you MUST append the appropriate suffix:

Resolution Rules:

1. •If name already ends with -rdc, -gdc, or -uz → use as-is
2. •If name matches known GDC pattern → append -gdc:
   • •eu0, eu1, us0, us1 (global data centers)
   • •cal (California GDC)
   • •Any of the above with -staging suffix (e.g., eu0-staging → eu0-staging-gdc)
3. •Otherwise → append -rdc (default to Regional Data Center)

Known GDC clusters: cal-gdc, eu0-gdc, eu0-staging-gdc, eu1-gdc, eu1-staging-gdc, us0-gdc, us0-staging-gdc, us1-gdc, us1-staging-gdc

When in doubt, run tsh kube ls | grep -i <partial-name> to find the exact cluster name.

kubectl via Teleport

After tsh kube login, kubectl works for read-only operations:

# View operations
kubectl get pods -n nvo
kubectl logs -f deployment/nvo-network -n nvo
kubectl describe pod <pod-name> -n nvo
kubectl get events -n nvo

# With cluster aliases (loaded by tkl)
kn get pods           # kubectl -n nvo get pods
kc get pods           # kubectl -n common get pods
km get pods           # kubectl -n monitoring get pods

Common Alias Mappings

Middleware Debug Pod

Access Kafka, Postgres, and other middleware from inside the cluster.

# Login to cluster first
tkl va-rdc

# Launch debug pod
tkl debug

For complete Kafka/Postgres operations: See debug-pod.md

Database Access via Teleport

# List available databases
tsh db ls

# Connect interactively
tsh db connect <db-name> --db-user=postgres --db-name=nvo_db

# Get connection info
tsh db config <db-name>

Multi-Cluster Health Checks

# Check all prod clusters
check_nvo_pods_rdc prod

# Check specific clusters
check_nvo_pods_rdc fra-rdc jp-rdc va-rdc

Quick Reference

Common Mistakes

For full troubleshooting guide: See troubleshooting.md

Architecture

User Machine                    Teleport Proxy                   K8s Cluster
     |                               |                               |
     |-- tsh kube login cluster ---->|                               |
     |<-- kubeconfig updated --------|                               |
     |                               |                               |
     |-- kubectl get pods ---------->|-- proxy to K8s API ---------->|
     |<-- pod list ------------------|<-- response ------------------|

Debugging Workflow

1. •Login to cluster: tkl <cluster-name>
2. •Check pod status: kn get pods
3. •View logs: kn logs -f <pod-name>
4. •For middleware issues: tkl debug → See debug-pod.md
5. •For database issues: tsh db connect for direct access