> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shiftlabs.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets

> Manage Kubernetes Secrets for storing sensitive data like passwords, tokens, and certificates

Secrets store sensitive data such as passwords, OAuth tokens, SSH keys, and TLS certificates. Unlike ConfigMaps, Secrets are designed for confidential information and can be encrypted at rest.

## Key Concepts

<CardGroup cols={2}>
  <Card title="Secret" icon="key-round">
    A Kubernetes resource that stores sensitive data as base64-encoded key-value pairs.
  </Card>

  <Card title="Type" icon="shield-check">
    Secret type indicates the intended use (Opaque, TLS, Docker, etc.) and may enforce required keys.
  </Card>

  <Card title="Data" icon="lock">
    Base64-encoded key-value pairs containing the actual secret values.
  </Card>

  <Card title="stringData" icon="file-text">
    Plain text values that are automatically base64-encoded when the Secret is created.
  </Card>
</CardGroup>

## Required Permissions

| Action        | Permission                                     |
| ------------- | ---------------------------------------------- |
| View secrets  | `iam:project:infrastructure:kubernetes:read`   |
| Create secret | `iam:project:infrastructure:kubernetes:write`  |
| Edit secret   | `iam:project:infrastructure:kubernetes:write`  |
| Delete secret | `iam:project:infrastructure:kubernetes:delete` |

<Info>
  Secret data is masked in the list view for security. Click on a Secret to view the actual (base64-encoded) values in the detail view.
</Info>

## Secret Types

| Type                                    | Label      | Description                                 |
| --------------------------------------- | ---------- | ------------------------------------------- |
| **Opaque**                              | Opaque     | Generic secret for arbitrary data (default) |
| **kubernetes.io/tls**                   | TLS        | TLS certificate and private key             |
| **kubernetes.io/dockerconfigjson**      | Docker     | Docker registry credentials                 |
| **kubernetes.io/dockercfg**             | Docker     | Legacy Docker registry credentials          |
| **kubernetes.io/service-account-token** | SA Token   | ServiceAccount token (auto-generated)       |
| **kubernetes.io/basic-auth**            | Basic Auth | Username and password                       |
| **kubernetes.io/ssh-auth**              | SSH        | SSH private key                             |
| **bootstrap.kubernetes.io/token**       | Bootstrap  | Bootstrap token for node joining            |
| **helm.sh/release.v1**                  | Helm       | Helm release metadata                       |

## How to View Secrets

<Steps>
  <Step title="Select Cluster">
    Choose a cluster from the cluster dropdown.
  </Step>

  <Step title="Select Namespace">
    Choose a namespace or select "all" to view Secrets across all namespaces.
  </Step>

  <Step title="Search">
    Use the search box to find Secrets by name, namespace, or type.
  </Step>
</Steps>

## How to View Secret Details

<Steps>
  <Step title="Find the Secret">
    Locate the Secret in the list.
  </Step>

  <Step title="Click Secret Name">
    Click on the Secret name to open the detail drawer.
  </Step>

  <Step title="Review Details">
    View Secret information including:

    * **Overview**: Name, namespace, type, key count, size, age
    * **Data**: Base64-encoded values (can be decoded)
    * **Labels & Annotations**: Metadata attached to the Secret
    * **Events**: Recent Kubernetes events
  </Step>
</Steps>

<Warning>
  Secret values in the detail view are base64-encoded. Decode them with `echo "<value>" | base64 -d` to see the actual content.
</Warning>

## How to Create a Secret

<Steps>
  <Step title="Click Create Secret">
    Click the **Create Secret** button in the page header.
  </Step>

  <Step title="Write YAML">
    Enter the Secret manifest in YAML format. Key fields:

    * `type` - Secret type (defaults to Opaque)
    * `data` - Base64-encoded key-value pairs
    * `stringData` - Plain text values (auto-encoded)
  </Step>

  <Step title="Select Namespace">
    Choose the target namespace for the Secret.
  </Step>

  <Step title="Create">
    Click **Create** to apply the manifest.
  </Step>
</Steps>

<Tip>
  Use `stringData` instead of `data` when creating Secrets manually - Kubernetes automatically base64-encodes the values.
</Tip>

## How to Edit a Secret

<Steps>
  <Step title="Open Actions Menu">
    Click the actions menu (three dots) on the Secret row.
  </Step>

  <Step title="Click Edit Secret">
    Select **Edit Secret** to open the YAML editor.
  </Step>

  <Step title="Modify Data">
    Edit the Secret content. You can:

    * Update existing values
    * Add new keys
    * Change the type (with caution)
  </Step>

  <Step title="Save">
    Click **Update** to apply changes.
  </Step>
</Steps>

<Warning>
  Like ConfigMaps, updating a Secret does not automatically restart pods. Pods must be restarted to pick up new Secret values.
</Warning>

## How to Delete a Secret

<Steps>
  <Step title="Open Actions Menu">
    Click the actions menu on the Secret row.
  </Step>

  <Step title="Click Delete">
    Select **Delete** from the menu.
  </Step>

  <Step title="Confirm">
    Confirm the deletion. Pods referencing this Secret may fail.
  </Step>
</Steps>

<Warning>
  Deleting a Secret that is mounted by running pods or used for image pull credentials will cause those pods to fail. Ensure no pods depend on the Secret before deletion.
</Warning>

## Using Secrets in Pods

### As Environment Variables

```yaml theme={null}
spec:
  containers:
    - name: app
      envFrom:
        - secretRef:
            name: app-secrets
      # Or individual keys:
      env:
        - name: DATABASE_PASSWORD
          valueFrom:
            secretKeyRef:
              name: app-secrets
              key: db-password
```

### As Volume Mounts

```yaml theme={null}
spec:
  containers:
    - name: app
      volumeMounts:
        - name: secret-volume
          mountPath: /etc/secrets
          readOnly: true
  volumes:
    - name: secret-volume
      secret:
        secretName: app-secrets
```

### For Image Pull

```yaml theme={null}
spec:
  imagePullSecrets:
    - name: docker-registry-secret
```

## Creating Common Secret Types

### TLS Secret

```yaml theme={null}
apiVersion: v1
kind: Secret
metadata:
  name: tls-secret
type: kubernetes.io/tls
data:
  tls.crt: <base64-encoded-cert>
  tls.key: <base64-encoded-key>
```

Or use kubectl:

```bash theme={null}
kubectl create secret tls tls-secret --cert=cert.pem --key=key.pem
```

### Docker Registry Secret

```yaml theme={null}
apiVersion: v1
kind: Secret
metadata:
  name: docker-secret
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: <base64-encoded-docker-config>
```

Or use kubectl:

```bash theme={null}
kubectl create secret docker-registry docker-secret \
  --docker-server=registry.example.com \
  --docker-username=user \
  --docker-password=pass
```

### Basic Auth Secret

```yaml theme={null}
apiVersion: v1
kind: Secret
metadata:
  name: basic-auth
type: kubernetes.io/basic-auth
stringData:
  username: admin
  password: secretpassword
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Pod fails to start with Secret error">
    * Verify the Secret exists in the same namespace as the pod
    * Check Secret name spelling in pod spec
    * Ensure referenced keys exist in the Secret
    * Use `optional: true` if Secret might not exist
  </Accordion>

  <Accordion title="Image pull fails with authentication error">
    * Verify imagePullSecrets is configured on the pod or ServiceAccount
    * Check the Docker Secret contains valid credentials
    * Ensure the Secret type is `kubernetes.io/dockerconfigjson`
    * Verify the registry URL in the Secret matches the image registry
  </Accordion>

  <Accordion title="TLS Secret not working">
    * Ensure type is `kubernetes.io/tls`
    * Verify keys are exactly `tls.crt` and `tls.key`
    * Check certificate and key are valid and match
    * Ensure values are base64-encoded
  </Accordion>

  <Accordion title="Secret data appears corrupted">
    * Values must be base64-encoded in `data` field
    * Use `stringData` for plain text (auto-encoded)
    * Don't double-encode values
    * Verify encoding with `echo "<value>" | base64 -d`
  </Accordion>

  <Accordion title="Secret changes not reflected in pod">
    * Pods don't automatically reload Secrets
    * Restart the deployment/pod to pick up changes
    * Volume-mounted Secrets eventually update (kubelet sync)
    * Environment variables from Secrets never auto-update
  </Accordion>

  <Accordion title="Cannot see Secret data">
    * List view masks data for security (shows \*\*\*)
    * Click the Secret name to view actual values in detail view
    * YAML view shows base64-encoded data
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Are Secrets actually secure?">
    By default, Secrets are only base64-encoded, not encrypted. For true security, enable encryption at rest in your cluster and use RBAC to restrict access. Consider external secret managers (Vault, AWS Secrets Manager) for highly sensitive data.
  </Accordion>

  <Accordion title="What's the difference between data and stringData?">
    **data** expects base64-encoded values. **stringData** accepts plain text and automatically encodes it. Use `stringData` when creating Secrets manually for convenience.
  </Accordion>

  <Accordion title="Can I use Secrets across namespaces?">
    No. Secrets are namespace-scoped. A pod can only reference Secrets in its own namespace. For shared secrets, create copies in each namespace or use external secret management.
  </Accordion>

  <Accordion title="Why is my Secret type important?">
    Secret types help Kubernetes validate required keys and enable specific functionality. For example, `kubernetes.io/tls` requires `tls.crt` and `tls.key`, and `kubernetes.io/dockerconfigjson` is recognized by kubelet for image pulls.
  </Accordion>

  <Accordion title="How do I rotate Secrets?">
    Update the Secret with new values, then restart pods that use it. For zero-downtime rotation, consider using external secret managers with automatic rotation support.
  </Accordion>

  <Accordion title="What's the size limit for Secrets?">
    Secrets are limited to 1 MiB, same as ConfigMaps. For larger data, consider external storage or splitting into multiple Secrets.
  </Accordion>

  <Accordion title="Should I commit Secrets to version control?">
    Never commit plain Secrets to version control. Use sealed-secrets, SOPS, or external secret managers to safely store encrypted secret references in Git.
  </Accordion>

  <Accordion title="How do ServiceAccount tokens work?">
    Kubernetes automatically creates `kubernetes.io/service-account-token` Secrets for ServiceAccounts. These contain tokens for authenticating to the API server.
  </Accordion>
</AccordionGroup>