Create and Sync Secrets

This guide walks through creating a secret, syncing it to a cluster, and consuming it from a workload.

Prerequisites

• A Kupe Cloud tenant with at least one running cluster.
• Tenant admin access in the console.

Step 1: Open the Secrets page

In the console, sign in as a tenant admin and click Secrets in the sidebar. This shows all secrets owned by your tenant across all clusters.

The table shows each secret’s name, the number of sync targets, and per-cluster sync status.

Step 2: Create the secret and add sync targets

1. Click Create Secret.
2. Enter a name for the secret (e.g., db-credentials). This becomes the Kubernetes Secret name in your cluster.
3. Add one or more key-value pairs:
   • Key: the data key (e.g., url, username, password)
   • Value: the sensitive value — entered as plain text, stored encrypted
4. In Sync Targets, add one or more target clusters.
5. For each target, select the namespace where the secret should be synced (for example backend, app, or default).
6. Click Create Secret.

The secret is stored in the platform vault, encrypted and isolated to your tenant, and Kupe starts syncing it to the selected targets immediately.

You can add multiple sync targets during creation if the same secret should be available in more than one cluster or namespace.

Step 3: Confirm sync status

After creation, the secret row shows each target and its sync status. A target moving to Synced means the Kubernetes Secret has been written into that cluster and namespace.

If you need to add more targets later, open the secret and edit Sync Targets from the management dialog.

Step 4: Verify the secret in your cluster

Once a sync target shows Synced status, the secret exists as a Kubernetes Secret in the selected cluster namespace.

Verify with kubectl:

kubectl get secret db-credentials -n backend

Expected output:

NAME              TYPE     DATA   AGE
db-credentials    Opaque   3      45s

Check the keys (values are base64-encoded):

kubectl get secret db-credentials -n backend -o jsonpath='{.data}' | jq

{
  "url": "cG9zdGdyZXM6Ly8uLi4=",
  "username": "YWNtZS1hcHA=",
  "password": "c3VwZXJzZWNyZXQ="
}

Step 5: Use the secret in a workload

Reference the secret in your deployment manifest. For example, inject as environment variables:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  namespace: backend
spec:
  template:
    spec:
      containers:
        - name: app
          image: my-app:latest
          env:
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef:
                  name: db-credentials
                  key: url
            - name: DB_USERNAME
              valueFrom:
                secretKeyRef:
                  name: db-credentials
                  key: username
            - name: DB_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: db-credentials
                  key: password

Or mount as files:

spec:
  template:
    spec:
      containers:
        - name: app
          volumeMounts:
            - name: creds
              mountPath: /etc/secrets
              readOnly: true
      volumes:
        - name: creds
          secret:
            secretName: db-credentials

Deploy via your normal GitOps workflow. The secret is already in the namespace — Argo CD does not need to manage it.

Updating a secret

1. In the console, click Edit on the secret row.
2. Modify key-value pairs — add, remove, or update values.
3. Click Save.

The updated values propagate to all synced clusters automatically. Workloads that mount the secret as a volume see the new values within a few minutes (Kubernetes kubelet sync interval). Workloads using environment variables require a pod restart.

Tip

To trigger a rolling restart after a secret update:

kubectl rollout restart deployment/my-app -n backend

Removing a sync target

Expand the secret row and click Remove on the sync target. The Kubernetes Secret is deleted from that cluster and namespace. Other sync targets are unaffected.

Deleting a secret

Click Delete on the secret row. This:

1. Removes the secret from the platform vault.
2. Does not automatically delete Kubernetes Secret objects that were already synced to clusters.
3. Cannot be undone — there is no soft-delete.

Caution

Deleting a secret removes the source of truth from the vault, but already-synced cluster secrets remain behind. Clean those up separately in each cluster if you want them removed.

Troubleshooting

Sync status shows “Pending”

The platform is waiting for the sync to complete. This usually resolves within 60 seconds. If it persists:

• Verify the target cluster is in Running state.
• Check that the target namespace exists in the cluster (the platform does not auto-create namespaces).

Sync status shows “Failed”

Expand the sync target to see the error message. Common causes:

• Namespace not found — create the namespace in your cluster first.
• Secret name conflict — a secret with the same name already exists in that namespace and was not created by the platform. Rename your secret or clean up the existing one.

Secret values are stale

After updating a secret, Kubernetes syncs volume-mounted secrets within ~60 seconds. Environment variables require a pod restart. Use kubectl rollout restart to pick up changes immediately.

Further reading

• Secrets — overview, isolation model, and sync architecture
• CLI Access — kubeconfig setup for kubectl verification