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

# Secrets

> Secret Manager containers, payloads, and Kubernetes sync.

The GCP deployment separates **secret container creation** from **secret payload population**. Terraform creates the Secret Manager containers; you populate the payloads unless a stack explicitly creates a secret version.

## Required secrets

| Secret Manager secret       | Created by                                                              | Synced into Kubernetes by                                                             | Required keys / payload                                                                                                                  | Used by                                            |
| --------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `tfc-agent-config`          | `envs/aperium-apps-prod/tf`                                             | `charts/terraform-agent-resources` via `terraform-operator`                           | `team_token`                                                                                                                             | HCP Terraform agent pool                           |
| `phoenix-auth`              | External prerequisite or manual creation                                | `envs/aperium-apps-prod/values/external-secrets.yaml`                                 | `PHOENIX_SECRET`, `PHOENIX_ADMIN_SECRET`, `PHOENIX_POSTGRES_PASSWORD`, `PHOENIX_SMTP_PASSWORD`, `PHOENIX_DEFAULT_ADMIN_INITIAL_PASSWORD` | Phoenix                                            |
| `prefect-admin-credentials` | External prerequisite or manual creation                                | `charts/prefect-resources` via `envs/aperium-apps-prod/values/prefect-resources.yaml` | Extracted object containing at least `auth-string`                                                                                       | Prefect server and Prefect worker basic auth       |
| `aperium-backend-yml`       | `apps/aperium/envs/prod/tf`                                             | `charts/aperium` and MCP values via `external-secrets`                                | `env` payload containing the backend env file contents                                                                                   | Aperium backend, workers, migrations, MCP services |
| `aperium-mcp-auth-token`    | `apps/aperium/envs/prod/tf`                                             | `charts/aperium-mcp-common`                                                           | `mcp_auth_token`                                                                                                                         | All in-cluster MCP services                        |
| `qdrant-api-keys`           | `apps/aperium/envs/prod/tf`                                             | `charts/qdrant-resources` and `charts/aperium`                                        | `apiKey`, `readOnlyApiKey`                                                                                                               | Qdrant and Aperium                                 |
| `aperium-keda-db-url`       | `apps/aperium/envs/prod/tf` when Cloud SQL + Secret Manager are enabled | `charts/aperium`                                                                      | `DATABASE_URL` payload                                                                                                                   | KEDA document worker scaler                        |

## Notes by secret

### `tfc-agent-config`

* The shared env Terraform creates the secret container only.
* You load the `team_token` payload yourself.
* The Terraform operator stack materializes it as a Kubernetes secret for the agent pool.

### `phoenix-auth`

* The ExternalSecret mapping is defined in `envs/aperium-apps-prod/values/external-secrets.yaml`.
* The Secret Manager secret must already exist with the expected properties before Phoenix is validated.

### `prefect-admin-credentials`

* The local `charts/prefect-resources` chart creates an `ExternalSecret` named `prefect-admin-credentials`.
* The backing secret-store entry must extract into a Kubernetes secret containing at least the key `auth-string`.
* The minimal Prefect deployment assumes this secret exists before Prefect server and worker become healthy.

### `aperium-backend-yml`

* This is the most important application secret.
* It is treated as an env-file payload, not as many separate key/value secrets.
* At minimum, it needs the database and application settings required by the backend and the in-cluster MCP services. The full list of variables lives on the [Environment variables](/deployment/configuration) page.
* It is also the expected home for runtime [feature flags](/deployment/configuration#feature-flags) and service-routing settings that are not modeled directly as Helm chart defaults.

  Current production-style examples include runtime flags such as:

  * `GALLERY_ENABLED`
  * `TOOL_LOADING_CAPABILITY_ROUTING_ENABLED`
  * `TOOL_LOADING_CAPABILITY_ROUTING_SHADOW_MODE`
  * `ENABLE_PARALLEL_TOOL_EXECUTION`
  * `ENABLE_FORK_MODEL`
  * `DASHBOARD_V2_ENABLED`

  Production-style examples also rely on env-file-provided application settings used alongside the Git-managed overlay, including MCP and retrieval settings for services such as `aperium-mcp-slack-workspace`, `aperium-mcp-atlassian`, `aperium-mcp-gcs-datalake`, and `aperium-retrieval`.

  Treat these as runtime env-file settings that accompany the deployment shape, not as a claim that the Helm chart alone expresses every runtime flag used in production.

### `aperium-mcp-auth-token`

* A single token is reused across all in-cluster MCP services.
* Each MCP deployment maps it into a namespaced Kubernetes secret.

### `qdrant-api-keys`

* The remote secret uses camelCase properties:
  * `apiKey`
  * `readOnlyApiKey`
* The Kubernetes secrets rendered by External Secrets use kebab-case keys:
  * `api-key`
  * `read-only-api-key`

### `aperium-keda-db-url`

* This is the one secret where Terraform can also create the secret *version* automatically.
* It is only written when Cloud SQL and Secret Manager support are enabled in the app stack.

## Operational checklist

Before expecting workloads to become healthy, verify:

* Each required Secret Manager secret exists.
* Each required property exists inside the secret payload.
* `ClusterSecretStore` points at the correct GCP project.
* ExternalSecret resources are Healthy.
* The generated Kubernetes secrets exist in the expected namespaces (`aperium`, `prefect`, `qdrant`, `phoenix`, and `tfc-operator-system` as applicable).