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

# Secrets

> Define and manage sensitive values — credentials, API keys, tokens — used to configure app components and actions.

Secrets allow you to configure components with sensitive values and keys.

Secret metadata (not the secret) are defined with a `secrets.toml` and incorporated in the CloudFormation stack deployed
by the customer. This allows the customer to enter values when clicking on the stack link provided by the vendor, during
the initial step of an install where the runner is created as a VM. Secrets are then stored in the user's AWS Secrets
Manager.

<Note>
  Because the customer creates the CloudFormation stack from that Nuon-generated CloudFormation template using their
  cloud credentials, the customer (not the vendor) can enter the secret values at that time. Nuon nor the vendor will
  never see the secret values, as they are not stored in the Nuon data plane.
</Note>

Secret can be used to configure components and actions using [variables](/guides/using-variables).

## How do you configure a secret?

Within your app directory, create a file named `secrets.toml`. This file will contain the configuration for your
secrets. Alternatively, you can create a directory named `secrets` and place individual Secret files inside it, such as
`github_app_key.toml`, `vendor_license_key`.

```toml secrets.toml theme={null}
# secrets

[[secret]]
name         = "github_app_key"
display_name = "GitHub App Key"
description  = "Base64 encoded Github App Key"
required     = true
format       = "base64"

[[kubernetes_sync_targets]]
namespaces = ["control-plane"]
name       = "github"
key        = "app-key"

[[secret]]
name = "vendor_license_key"
display_name = "Vendor license key"
description = "Vendor license key"
required = true

[[kubernetes_sync_targets]]
namespaces = ["app"]
name       = "vendor-license"
key        = "key"

[[secret]]
name          = "rds_secret"
display_name  = "database password"
description   = "database password"
required      = true
auto_generate = true

[[kubernetes_sync_targets]]
namespaces = ["workers", "control-plane"]
name       = "storage"
key        = "db-password"
```

Use the key-value pair `kubernetes_sync = true` to indicate that the secret should be synced to Kubernetes as a Secret
object. The `kubernetes_secret_namespace` and `kubernetes_secret_name` fields specify where the secret will be created
in Kubernetes.

This workflow step is run after the provisioning of a Kubernetes sandbox and uses the key of `value` when creating the
Kubernetes secret.

## Configuring components with secrets

Reference the secrets from AWS Secrets Manager as outputs from the CloudFormation stack, and then use them in your
component config.

### Terraform components with secrets

```toml components/open_webui.toml theme={null}
# terraform
name              = "open_webui"
type              = "terraform_module"
terraform_version = "1.13.5"

...

[vars]
...
openai_secret_arn = "{{ .nuon.install_stack.outputs.openai_api_key_arn }}"

```

### Helm components with secrets

```toml components/my-component theme={null}
# helm
name = "helm"
type = "helm_chart"
chart_name = "chart-name"

[connected_repo]
directory = "helm"
repo = "org/repo"
branch = "main"

[[values_file]]
contents = "./values/values.yaml"
```

```yaml values.yaml theme={null}
service:
  port: 80
  targetPort: 3000

secrets:
  botTokenSecret: bot-user-oauth-token
```

Then reference the secret with the `value` key in the Helm chart template.

```yaml deployment.tpl theme={null}
apiVersion: apps/v1
kind: Deployment
---
containers:
  - name: slack-app
    image: '{{ .Values.image.repository }}:{{ .Values.image.tag }}'
    ports:
      - containerPort: { { .Values.deployment.containerPort } }
    env:
      - name: SLACK_BOT_TOKEN
        valueFrom:
          secretKeyRef:
            name: { { .Values.secrets.botTokenSecret } }
            key: value
```

## Configuring actions with secrets

Reference the secrets from AWS Secrets Manager as outputs from the CloudFormation stack, and then use them in your
actions config. In this example, the secret is assigned to an action environment variable and then referenced in a
script. Note the script is stored in the `src` directory of the app.

```toml actions/rds_secrets.toml theme={null}

[[triggers]]
type           = "post-deploy-component"
component_name = "rds_cluster"

[[steps]]
name    = "Copy RDS Secret for deployment"
command = "./rds_secrets/import.sh"

[steps.env_vars]
SECRET_ARN       = "{{ .nuon.install_stack.outputs.rds_secret_arn }}"

```

```sh src/rds_secrets/import.sh theme={null}

#!/usr/bin/env bash
secret_arn="$SECRET_ARN"

echo "[rds-secrets import] reading db access secrets from AWS"
secret=`aws --region $region secretsmanager get-secret-value --secret-id=$secret_arn`

```

## Changing Secrets Outside of the App

If you need to change a secret value outside of the app, e.g., in AWS Secrets Manager or update the CloudFormation
stack, understand that Nuon will not detect the change.

In order for Nuon to be aware of the change, you will have to either reprovision the install or review the dependency
graph in the dashboard and manually redeploy the components or actions that depend on the secret.

If your secrets are configured to sync with Kubernetes, go to the install dashboard and manually select sync secrets in
the Manage drop-down.

<Note>
  If you have a use case for working with secret values not covered here, Please [contact
  us](https://nuon.co/contact-us).
</Note>