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

# Secrets

Some applications require credentials you provide - API keys, database passwords, webhook tokens, and similar. During configuration, the setup interface tells you exactly what's needed and how to create each secret.

## The Key Principle

**Your secrets never leave your infrastructure.** You create them directly in your own cluster or cloud secret manager. The controller detects them automatically and shows their status in the setup interface. We never see or store your secret values.

## How It Works

<Steps>
  <Step title="Review">
    The setup interface lists every secret the application needs.
  </Step>

  <Step title="Identify">
    For each secret, it shows:

    * What the secret is for (e.g., "GitHub Personal Access Token for CI")
    * Whether it's required or optional
    * The exact command to create it
  </Step>

  <Step title="Create">
    You create the secret in your infrastructure.
  </Step>

  <Step title="Confirm">
    The controller detects it and the status updates to a green checkmark.
  </Step>

  <Step title="Skip (optional)">
    Optional secrets can be skipped.
  </Step>
</Steps>

## Secret Types

### Required Secrets

These must be created before the deployment can proceed. The setup interface won't advance until all required secrets are detected.

### Optional Secrets

These enable additional functionality but aren't required. You can skip them during setup and add them later if needed.

## What About Our Secrets?

Some secrets are provided by us (for example, internal service credentials that the application needs). These are handled automatically during deployment - you don't need to create or manage them.

## Creating Secrets

<Tabs>
  <Tab title="Kubernetes">
    The setup interface generates ready-to-run `kubectl` commands. For example:

    ```bash theme={null}
    kubectl create secret generic github-token \
      -n <namespace> \
      --from-literal=token=<your-token>
    ```

    Copy the command, replace the placeholder with your actual value, and run it. The secret goes directly into your cluster.
  </Tab>

  <Tab title="AWS">
    AWS deployments store secrets in either **AWS Secrets Manager** or **AWS Systems Manager Parameter Store**, depending on what the origin stack uses. The setup interface tells you which service applies to each secret.

    **AWS Secrets Manager:**

    ```bash theme={null}
    aws secretsmanager create-secret \
      --name <secret-name> \
      --secret-string <your-value> \
      --region <your-region>
    ```

    **AWS Systems Manager Parameter Store:**

    ```bash theme={null}
    aws ssm put-parameter \
      --name <parameter-name> \
      --value <your-value> \
      --type SecureString \
      --region <your-region>
    ```
  </Tab>
</Tabs>

## Verifying Secrets

<Tabs>
  <Tab title="Kubernetes">
    Confirm your secrets were created in the correct namespace:

    ```bash theme={null}
    kubectl get secrets -n <namespace>
    ```

    The setup interface also shows a green checkmark next to each detected secret.
  </Tab>

  <Tab title="AWS">
    **AWS Secrets Manager:**

    ```bash theme={null}
    aws secretsmanager list-secrets \
      --filters Key=name,Values=<expected-prefix> \
      --query "SecretList[].Name"
    ```

    **AWS Systems Manager Parameter Store:**

    ```bash theme={null}
    aws ssm describe-parameters \
      --parameter-filters "Key=Name,Option=BeginsWith,Values=<expected-prefix>" \
      --query "Parameters[].Name"
    ```

    The setup interface also shows a green checkmark next to each detected secret.
  </Tab>
</Tabs>

## Rotating Secrets

<Tabs>
  <Tab title="Kubernetes">
    ```bash theme={null}
    kubectl delete secret <secret-name> -n <namespace>
    kubectl create secret generic <secret-name> \
      -n <namespace> \
      --from-literal=key=<new-value>
    ```

    The controller detects the updated value automatically. No restart is needed in most cases.
  </Tab>

  <Tab title="AWS">
    **AWS Secrets Manager:**

    ```bash theme={null}
    aws secretsmanager update-secret \
      --secret-id <secret-name> \
      --secret-string <new-value>
    ```

    **AWS Systems Manager Parameter Store:**

    ```bash theme={null}
    aws ssm put-parameter \
      --name <parameter-name> \
      --value <new-value> \
      --type SecureString \
      --overwrite
    ```
  </Tab>
</Tabs>

## Adding Secrets Later

If you skipped optional secrets during setup, you can add them at any time using the same creation command shown above. The controller polls periodically and will detect the new secret within 30-60 seconds.

## Common Issues

<Tabs>
  <Tab title="Kubernetes">
    | Symptom             | Likely Cause    | Fix                                                                |
    | ------------------- | --------------- | ------------------------------------------------------------------ |
    | Secret not detected | Wrong namespace | Verify you used `-n <namespace>` matching the deployment namespace |
    | Secret not detected | Wrong name      | Copy the exact command from the setup interface to avoid typos     |
    | Secret not detected | Detection delay | Wait 30-60 seconds and refresh the setup interface                 |
  </Tab>

  <Tab title="AWS">
    | Symptom             | Likely Cause    | Fix                                                                                     |
    | ------------------- | --------------- | --------------------------------------------------------------------------------------- |
    | Secret not detected | Wrong region    | Verify the secret is in the same region as the deployment                               |
    | Secret not detected | Wrong name      | Copy the exact name from the setup interface to avoid typos                             |
    | Secret not detected | Wrong service   | Confirm whether the secret belongs in Secrets Manager or Parameter Store                |
    | Secret not detected | Detection delay | Wait 30-60 seconds and refresh the setup interface                                      |
    | Permission denied   | IAM issue       | Verify your IAM user has `secretsmanager:CreateSecret` or `ssm:PutParameter` permission |
  </Tab>
</Tabs>

## Security Guarantees

* Secret values are created in **your** infrastructure by **you**
* They are transmitted over **your** network
* We see only the **existence** of secrets (present or missing), never their **values**
* The setup interface shows status indicators, not secret contents