Secrets

Use a Kubernetes Secret to store passwords, API tokens, and other sensitive settings for applications in your namespace. An application can read them as environment variables or files. A registry Secret lets Kubernetes download private container images.

Before you create a secret

• Make sure kubectl works with your namespace kubeconfig.
• Choose how the application will use the Secret: as environment variables, files, or credentials for downloading a private container image.

For kubeconfig setup, read Kubernetes overview.

Create a secret

Create an Opaque Secret, the general-purpose type for application settings and credentials. Replace the example token and profile with your own values:

kubectl --kubeconfig ./kubeconfig-team-ml.yaml create secret generic app-config \
  --from-literal=API_TOKEN=replace-with-token \
  --from-literal=MODEL_PROFILE=production

Use kubectl get secret to confirm that Kubernetes created the Secret:

kubectl --kubeconfig ./kubeconfig-team-ml.yaml get secret app-config

The command output shows the Secret name, type, and key count. It does not show Secret values.

Use a secret as environment variables

Add these snippets to spec.template.spec in your Deployment manifest. Keep the existing image and other container settings, and replace app with your container's name.

This snippet reads one key from the Secret and gives it to the container as an environment variable:

containers:
  - name: app
    env:
      - name: API_TOKEN
        valueFrom:
          secretKeyRef:
            name: app-config
            key: API_TOKEN

To turn every key in the Secret into an environment variable, use:

containers:
  - name: app
    envFrom:
      - secretRef:
          name: app-config

Mount a secret as files

If your application reads credentials from files, add this snippet to the same pod template:

containers:
  - name: app
    volumeMounts:
      - name: app-config
        mountPath: /etc/config
        readOnly: true
volumes:
  - name: app-config
    secret:
      secretName: app-config

Each Secret key becomes a file under the mount path. In this example, the container can read /etc/config/API_TOKEN.

Use a private image registry

Create a Docker registry Secret so Kubernetes can log in to your private registry and download images. Replace the example server, username, password, and email with your registry details:

kubectl --kubeconfig ./kubeconfig-team-ml.yaml create secret docker-registry app-registry \
  --docker-server=registry.example.com \
  --docker-username=replace-with-username \
  --docker-password=replace-with-password \
  --docker-email=dev@example.com

Add the registry Secret to the pod template. In this example, replace the container image with an image from your registry:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: private-image-demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: private-image-demo
  template:
    metadata:
      labels:
        app: private-image-demo
        remotegpu.ai/runtime-sku: cpu-shared-8g
    spec:
      imagePullSecrets:
        - name: app-registry
      containers:
        - name: app
          image: registry.example.com/team/app:1.0.0

Supported Secret types and limits

Create and use Secrets within the application's namespace. These limits apply:

Area	Supported value
Access path	kubectl
Namespace quota	Up to 128 Secrets per namespace
Secret types	Standard Kubernetes Secret types except kubernetes.io/service-account-token
Reserved names	Secret names and generateName prefixes must not start with rgpu- or remotegpu-
Finalizers	Customer-created Secrets must not set metadata.finalizers

RemoteGPU provides HTTPS for apps.remotegpu.ai hostnames. Creating your own TLS Secret does not replace that certificate. See Ingresses for the supported HTTPS settings.

Troubleshooting

Symptom	What to check
Secret creation is rejected	Check the Secret name, type, finalizers, and namespace Secret quota.
Pod cannot read an environment variable	Check the Secret name and key in secretKeyRef. If you updated the Secret, restart the pod to load the new environment variables.
Secret volume is empty or missing a file	Confirm the workload references the correct secretName and Secret key.
Private image pull fails	Check the registry server, username, password, image name, and imagePullSecrets reference.
Another user in the namespace can read the Secret	Use a separate namespace for applications whose Secrets must have different access permissions.

For detailed Kubernetes events, use kubectl describe pod on the affected pod.

Read next

• Read Deployments to run workloads that reference Secrets.
• Read Kubernetes overview to set up access to your namespace.