Skip to main content

Kubernetes kubeconfig

Use a namespace-scoped kubeconfig for day-to-day kubectl access. The console downloads a kubeconfig that refreshes short-lived credentials with your RemoteGPU API key.

Authentication model​

RemoteGPU Kubernetes access uses two different auth paths:

  • Console and namespace management APIs use your signed-in browser session
  • kubectl credential refresh uses a RemoteGPU API key

This means:

  • creating, renaming, or downloading a namespace kubeconfig happens while you are signed in to the console
  • running kubectl get pods later depends on REMOTEGPU_API_KEY

Before you start​

  • Create an API key in Settings / API Keys
  • Make sure the key allows Kubernetes exec access for the namespace you want
  • Export the key into your shell before running kubectl
export REMOTEGPU_API_KEY=rgpu_your_scoped_api_key
kubectl --kubeconfig ./kubeconfig-team-ml.yaml get pods

An API key can authorize Kubernetes exec access in any of these ways:

  • {"all": true}
  • {"kubernetes_exec": {"all_namespaces": true}}
  • {"kubernetes_exec": {"namespace_ids": ["..."]}}

Inference-only keys cannot refresh Kubernetes credentials.

Create or select a namespace​

From the console:

  1. Open Kubernetes
  2. Create a namespace or select an existing one
  3. Download the kubeconfig for that namespace

The namespace management APIs behind this flow use your signed-in session:

  • GET /v1/kubernetes/namespaces
  • POST /v1/kubernetes/namespaces
  • PATCH /v1/kubernetes/namespaces/{namespace_id}
  • DELETE /v1/kubernetes/namespaces/{namespace_id}

Namespace names:

  • must be lowercase DNS-style names
  • cannot use the reserved name all
  • are currently limited to 63 characters

Download kubeconfig​

From the console:

  1. Open Kubernetes
  2. Select the namespace
  3. Download the kubeconfig for that namespace

The API route behind this flow is GET /v1/kubernetes/namespaces/{namespace_id}/kubeconfig.

The response returns:

  • namespace
  • filename
  • kubeconfig

The kubeconfig is pre-wired to call the namespace-specific exec credential endpoint when kubectl needs a fresh token.

Exec credential refresh​

The kubeconfig uses:

  • POST /v1/kubernetes/namespaces/{namespace_id}/exec-credential

This endpoint expects x-api-key. It does not use your browser session.

Typical outcomes:

  • 401 Missing, invalid, revoked, or expired API key
  • 403 API key is valid but does not allow Kubernetes exec access for this namespace
  • 503 The backing Kubernetes token response did not include an expiration

Deploy workloads​

The simplest path is to create deployments from the console. For direct kubectl apply, RemoteGPU workloads are selected by SKU label.

RemoteGPU workloads are selected by SKU label. Add remotegpu.ai/sku-code to the pod template metadata and let admission fill in the exact scheduling details.

Minimal CPU example:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: demo-cpu
  namespace: YOUR_NAMESPACE
spec:
  replicas: 1
  selector:
    matchLabels:
      app: demo-cpu
  template:
    metadata:
      labels:
        app: demo-cpu
        remotegpu.ai/sku-code: cpu-shared-8g
    spec:
      containers:
        - name: app
          image: nginx:1.27-alpine

GPU example:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: demo-gpu-full
  namespace: YOUR_NAMESPACE
spec:
  replicas: 1
  selector:
    matchLabels:
      app: demo-gpu-full
  template:
    metadata:
      labels:
        app: demo-gpu-full
        remotegpu.ai/sku-code: gpu-h100-1x
    spec:
      containers:
        - name: app
          image: nginx:1.27-alpine

You can use namespace admission checks to validate a deployment plan before creating it:

  • POST /v1/kubernetes/namespaces/{namespace_id}/admission-check

Common outcomes​

  • If your browser session is missing, namespace APIs return 401 Missing access token
  • If your API key is missing, kubeconfig refresh fails with 401 Missing API key
  • If the key is scoped to the wrong namespace, exec credential issuance returns 403
  • If a namespace is empty, you can still create deployments in it
  • If you need a kubeconfig for automation, download it once and rotate the API key separately
  • GET /v1/kubernetes/namespaces
  • POST /v1/kubernetes/namespaces
  • PATCH /v1/kubernetes/namespaces/{namespace_id}
  • DELETE /v1/kubernetes/namespaces/{namespace_id}
  • GET /v1/kubernetes/namespaces/{namespace_id}/kubeconfig
  • POST /v1/kubernetes/namespaces/{namespace_id}/exec-credential
  • POST /v1/kubernetes/namespaces/{namespace_id}/admission-check