---
title: "Secrets"
url: "/reference/resources/secrets/"
kind: "reference"
summary: "Field reference for TLS certificate and validation-context secrets, data sources and SDS name references."
---

> Arion site index: [/llms.txt](/llms.txt)

# Secrets

Field reference for TLS certificate and validation-context secrets, data sources and SDS name references.

Secrets hold TLS material by name under `envoy_bootstrap.static_resources.secrets`, so listeners and clusters can reference certificates instead of inlining them; the same resources can also be delivered and rotated over xDS (SDS, see [xDS resource types](@/reference/xds/resource-types.md)).

## secret

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `name` | string | yes | — | Unique secret name, referenced from TLS contexts. |
| `tls_certificate` | object | one of | — | A certificate and private key (below). |
| `validation_context` | object | one of | — | A CA bundle for peer verification (below). |

`generic_secret` and `session_ticket_keys` are not supported.

### tls_certificate

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `certificate_chain` | data source | yes | — | PEM certificate chain, leaf first. |
| `private_key` | data source | yes | — | PEM private key for the leaf certificate. |

Not supported: `pkcs12`, `password`, `watched_directory`, `private_key_provider`, `ocsp_staple`.

### validation_context

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `trusted_ca` | data source | yes | — | PEM bundle of trusted CA certificates. |
| `trust_chain_verification` | enum | no | `VERIFY_TRUST_CHAIN` | `ACCEPT_UNTRUSTED` skips chain verification (for testing only). |

Other validation options (SAN matching, SPKI/hash pinning, CRLs, `allow_expired_certificate`, `max_verify_depth`, `system_root_certs`) are not supported.

```yaml,arion=fragment
static_resources:
  secrets:
    - name: example_com_cert
      tls_certificate:
        certificate_chain:
          filename: /etc/arion/certs/example.com.crt
        private_key:
          filename: /etc/arion/certs/example.com.key
    - name: client_ca
      validation_context:
        trusted_ca:
          filename: /etc/arion/certs/ca.crt
```

## Data sources

Every field marked "data source" accepts exactly one of:

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `filename` | string | one of | — | Read from a file at startup. The file is not watched for changes; rotate via SDS instead. |
| `inline_string` | string | one of | — | The value inline in the configuration. |
| `inline_bytes` | bytes | one of | — | Base64-encoded bytes inline in the configuration. |
| `environment_variable` | string | one of | — | Read from the named environment variable. |

`watched_directory` is not supported.

## Referencing secrets

TLS contexts reference secrets by name only — the reference carries a `name` and nothing else (a nested `sds_config` is rejected). Names resolve against the static `secrets` list, or against secrets streamed over the ADS connection when [dynamic resources](@/docs/operate/xds-control-planes.md) are configured.

| Where | Field | Refers to |
|---|---|---|
| Listener `DownstreamTlsContext` | `common_tls_context.tls_certificate_sds_secret_configs` (list of `- name:`) | `tls_certificate` secrets |
| Listener `DownstreamTlsContext` | `common_tls_context.validation_context_sds_secret_config` (`name:`) | a `validation_context` secret |
| Cluster `UpstreamTlsContext` | `common_tls_context.tls_certificate_sds_secret_configs` (at most one entry) | a `tls_certificate` secret |
| Cluster `UpstreamTlsContext` | `common_tls_context.validation_context_sds_secret_config` (`name:`) | a `validation_context` secret |

```yaml,arion=fragment
# inside a listener filter chain
transport_socket:
  name: envoy.transport_sockets.tls
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
    common_tls_context:
      tls_certificate_sds_secret_configs:
        - name: example_com_cert
      validation_context_sds_secret_config:
        name: client_ca
```

> [!NOTE]
> The admin [`/config_dump`](@/reference/observability/admin-api.md) endpoint redacts private keys before returning secrets.