> For the complete documentation index, see [llms.txt](https://docs.catalyx.solutions/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.catalyx.solutions/catalyx-blockchain-manager/canton-network/version-2.0/validator-crd.md).

# Validator CRD Reference

Every field on the Validator custom resource, with types and defaults.

## How to read this reference

Two different kinds of default appear in the tables, and the distinction is load-bearing.

<table><thead><tr><th width="230">Kind</th><th>Behaviour</th></tr></thead><tbody><tr><td><strong>Schema default</strong></td><td>Applied by the Kubernetes API server when you omit the field. It is written into the stored resource, so <code>kubectl get -o yaml</code> shows it.</td></tr><tr><td><strong>Operator default</strong></td><td>Applied by the operator at reconcile time. The field stays absent from the stored resource — the value appears only in the resulting workload.</td></tr></tbody></table>

Similarly, two kinds of "required":

<table><thead><tr><th width="230">Kind</th><th>Behaviour</th></tr></thead><tbody><tr><td><strong>Schema required</strong></td><td>The API server rejects the resource at <code>kubectl apply</code>. Fast, obvious failure.</td></tr><tr><td><strong>Reconcile required</strong></td><td>Accepted at apply, then fails during reconciliation. Surfaces as the <code>Ready</code> condition with reason <code>InvalidSpec</code> and a message naming the field.</td></tr></tbody></table>

{% hint style="danger" %}
**Unknown fields are silently pruned.** The API server drops any field not in the schema, without an error. A misspelled field name has no effect and produces no warning. After applying, confirm your fields survived:

```bash
kubectl -n <namespace> get validator my-validator -o yaml
```

{% endhint %}

***

## Top level

Two blocks are schema-required: `auth` and `network`. `spec.database` is required unless the platform sets an operator-level database — see `spec.database` below.

<table><thead><tr><th width="230">Field</th><th width="130">Required</th><th>Purpose</th></tr></thead><tbody><tr><td><code>spec.auth</code></td><td><strong>Schema</strong></td><td>Authentication for every component.</td></tr><tr><td><code>spec.database</code></td><td>Conditional</td><td>PostgreSQL connection and database names. Required unless <code>operator.database.host</code> is set on the platform. The schema does not enforce this: a <code>Validator</code> without it is accepted, then reports <code>Ready</code> = <code>False</code> with reason <code>InvalidSpec</code>.</td></tr><tr><td><code>spec.network</code></td><td><strong>Schema</strong></td><td>Canton network connectivity.</td></tr><tr><td><code>spec.participant</code></td><td>No</td><td>Canton participant node configuration.</td></tr><tr><td><code>spec.validator</code></td><td>No</td><td>Validator app configuration.</td></tr><tr><td><code>spec.ui</code></td><td>No</td><td>Wallet UI and CNS UI configuration and branding.</td></tr><tr><td><code>spec.pqs</code></td><td>No</td><td>Participant Query Store.</td></tr><tr><td><code>spec.walletGateway</code></td><td>No</td><td>Wallet Gateway.</td></tr><tr><td><code>spec.kms</code></td><td>No</td><td>External key management.</td></tr><tr><td><code>spec.overrides</code></td><td>No</td><td>Extra environment variables per component.</td></tr></tbody></table>

***

## `spec.auth`

<table><thead><tr><th width="330">Field</th><th width="110">Type</th><th width="130">Default</th><th>Purpose</th></tr></thead><tbody><tr><td><code>enabled</code></td><td>boolean</td><td><code>true</code></td><td>Master authentication switch. <code>false</code> disables authentication on the participant.</td></tr><tr><td><code>managedKeycloak</code></td><td>boolean</td><td><code>false</code></td><td><code>true</code> → the operator provisions the OIDC objects and reads configuration from <code>status.managedAuth</code>.</td></tr><tr><td><code>authUrl</code></td><td>string</td><td>—</td><td>OIDC issuer or token endpoint.</td></tr><tr><td><code>jwksUrl</code></td><td>string</td><td>—</td><td>JWKS endpoint for token verification.</td></tr><tr><td><code>targetAudience</code></td><td>string</td><td>—</td><td>Audience every token must carry.</td></tr><tr><td><code>ledgerApiUserManagementScope</code></td><td>string</td><td>—</td><td>OAuth scope granting Ledger API user management.</td></tr><tr><td><code>ledgerApiUser</code></td><td>string</td><td>—</td><td>Participant admin user name.</td></tr><tr><td><code>walletUserName</code></td><td>string</td><td>—</td><td>Wallet owner user name.</td></tr><tr><td><code>ledgerApiClientId</code></td><td>string</td><td>—</td><td>Confidential backend client ID.</td></tr><tr><td><code>walletUiClientId</code></td><td>string</td><td>—</td><td>Public client ID for the Wallet UI.</td></tr><tr><td><code>cnsUiClientId</code></td><td>string</td><td>—</td><td>Public client ID for the CNS UI.</td></tr><tr><td><code>walletGatewayClientId</code></td><td>string</td><td>—</td><td>Public client ID for the Wallet Gateway.</td></tr><tr><td><code>ledgerApiClientSecretRef.name</code></td><td>string</td><td>—</td><td>Secret holding the backend client secret.</td></tr><tr><td><code>ledgerApiClientSecretRef.key</code></td><td>string</td><td><code>client-secret</code></td><td>Key within that secret.</td></tr></tbody></table>

{% hint style="info" %}
With `managedKeycloak: false`, the fields the components need are **reconcile-required**, not schema-required. A `Validator` missing them applies successfully and then reports `InvalidSpec`. See [External Identity Provider](https://docs.catalyx.solutions/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/identity-provider-configuration/external-identity-provider.md).
{% endhint %}

***

## `spec.database`

When the block is present, these are schema-required inside it: `host`, `participantDb`, `validatorDb`, `credentialsSecretRef.name`.

{% hint style="warning" %}
**Operator-level database (from 2.0.2).** When the platform sets `operator.database.host`, the operator generates the database names itself and **ignores each `Validator`'s own `spec.database`**, except `pqsDatabase`. Sandbox validators rely on this. Leave `operator.database.host` empty on clusters where validators bring their own `spec.database`. See [Platform Installation](https://docs.catalyx.solutions/catalyx-blockchain-manager/canton-network/version-2.0/installation-instructions-canton/platform-installation.md#operator-database).
{% endhint %}

<table><thead><tr><th width="330">Field</th><th width="110">Type</th><th width="130">Default</th><th>Purpose</th></tr></thead><tbody><tr><td><code>host</code></td><td>string</td><td>—</td><td>PostgreSQL host. <strong>Schema required.</strong></td></tr><tr><td><code>port</code></td><td>integer</td><td><code>5432</code></td><td>PostgreSQL port. Must be 1–65535.</td></tr><tr><td><code>participantDb</code></td><td>string</td><td>—</td><td>Participant database name. <strong>Schema required.</strong></td></tr><tr><td><code>participantSchema</code></td><td>string</td><td><code>participant</code></td><td>Participant schema.</td></tr><tr><td><code>validatorDb</code></td><td>string</td><td>—</td><td>Validator app database name. <strong>Schema required.</strong></td></tr><tr><td><code>validatorSchema</code></td><td>string</td><td><code>validator</code></td><td>Validator app schema.</td></tr><tr><td><code>pqsDatabase</code></td><td>string</td><td>—</td><td>PQS database name. <strong>Reconcile required when <code>pqs.enabled</code>.</strong></td></tr><tr><td><code>pqsSchema</code></td><td>string</td><td><code>pqs</code></td><td>PQS schema.</td></tr><tr><td><code>walletGatewayStoreDatabase</code></td><td>string</td><td>—</td><td>Wallet Gateway store database. <strong>Reconcile required when <code>walletGateway.enabled</code>.</strong></td></tr><tr><td><code>walletGatewaySigningDatabase</code></td><td>string</td><td>—</td><td>Wallet Gateway signing database. <strong>Reconcile required when <code>walletGateway.enabled</code>.</strong></td></tr><tr><td><code>credentialsSecretRef.name</code></td><td>string</td><td>—</td><td>Secret with the database credentials. <strong>Schema required.</strong></td></tr><tr><td><code>credentialsSecretRef.usernameKey</code></td><td>string</td><td><code>username</code></td><td>Key holding the username.</td></tr><tr><td><code>credentialsSecretRef.passwordKey</code></td><td>string</td><td><code>password</code></td><td>Key holding the password.</td></tr></tbody></table>

{% hint style="info" %}
The operator creates the databases and schemas for you, so these credentials need `CREATEDB` privileges and access to the `postgres` maintenance database.
{% endhint %}

***

## `spec.network`

Schema-required inside: `partyHint`.

<table><thead><tr><th width="330">Field</th><th width="130">Type</th><th width="110">Default</th><th>Purpose</th></tr></thead><tbody><tr><td><code>partyHint</code></td><td>string</td><td>—</td><td>Party ID hint, and the wallet username under managed authentication. <strong>Schema required</strong>, and pattern-validated — see below.</td></tr><tr><td><code>spliceVersion</code></td><td>string</td><td>—</td><td>Single image tag for the participant, validator app, and both UIs, used when a component has no <code>version</code> of its own.</td></tr><tr><td><code>migrationId</code></td><td>string</td><td><code>"1"</code></td><td>Canton domain migration ID. A string, not an integer.</td></tr><tr><td><code>onboardingSecretName</code></td><td>string</td><td>—</td><td>Secret holding the Super Validator onboarding token, under the key <code>secret</code>.</td></tr><tr><td><code>sponsorSvUrl</code></td><td>string</td><td>—</td><td>Sponsoring Super Validator URL.</td></tr><tr><td><code>contactPoint</code></td><td>string</td><td>—</td><td>Operator contact point published to the network.</td></tr><tr><td><code>scan.address</code></td><td>string</td><td>—</td><td>Scan service address.</td></tr><tr><td><code>scan.type</code></td><td>string</td><td>—</td><td>Scan mode. Use <code>bft</code> with <code>seedUrls</code>, or <code>trust-single</code> with a single <code>address</code>.</td></tr><tr><td><code>scan.seedUrls</code></td><td>string[]</td><td>—</td><td>BFT scan seed URLs.</td></tr><tr><td><code>synchronizer.connectionType</code></td><td>string</td><td>—</td><td>Sequencer connection mode: <code>bft</code> or <code>trust-single</code>.</td></tr><tr><td><code>synchronizer.url</code></td><td>string</td><td>—</td><td>Sequencer URL. Used with <code>trust-single</code>.</td></tr></tbody></table>

{% hint style="danger" %}
**`partyHint` is pattern-validated** as `^[a-zA-Z0-9]+-[a-zA-Z0-9]+-[0-9]+$` — two alphanumeric segments and a numeric segment, hyphen-separated. `catalyx-devnet-001` is valid; `myvalidator` and `my_validator_1` are rejected at apply time.
{% endhint %}

{% hint style="warning" %}
**`scan` and `synchronizer` are effectively required**, even though the schema does not mark them so. A validator without them fails to reconcile.

**`scan.type` and `synchronizer.connectionType` are not enum-validated.** Only `trust-single` is treated specially; every other value — including a typo — takes the BFT path. Check the spelling.
{% endhint %}

***

## `spec.participant` and `spec.validator`

Both blocks are optional and take operator defaults. `spec.participant` additionally has `nodeIdentifier`; `spec.validator` additionally has `dumpPath`.

<table><thead><tr><th width="330">Field</th><th width="180">Operator default</th><th>Purpose</th></tr></thead><tbody><tr><td><code>version</code></td><td><code>spec.network.spliceVersion</code></td><td>Image tag. <strong>Reconcile required</strong> if <code>spliceVersion</code> is also unset.</td></tr><tr><td><code>replicas</code></td><td><code>1</code> (schema)</td><td>Deployment replicas. <code>0</code> scales the component down without deleting it. Minimum <code>0</code>. Values above <code>1</code> are not supported for either component.</td></tr><tr><td><code>participant.nodeIdentifier</code></td><td><code>spec.network.partyHint</code></td><td>Canton participant node identifier.</td></tr><tr><td><code>validator.dumpPath</code></td><td>—</td><td>Path to a domain migration dump.</td></tr><tr><td><code>resources.requests.cpu</code> / <code>.memory</code></td><td>Participant: <code>2</code> / <code>14Gi</code><br>Validator app: <code>2</code> / <code>8Gi</code></td><td>CPU and memory requests.</td></tr><tr><td><code>resources.limits.cpu</code> / <code>.memory</code></td><td>Participant: <code>10</code> / <code>14Gi</code><br>Validator app: <code>10</code> / <code>8Gi</code></td><td>CPU and memory limits.</td></tr><tr><td><code>jvm.minHeap</code> / <code>.maxHeap</code></td><td>Participant: <code>10240m</code> / <code>10240m</code><br>Validator app: <code>6144m</code> / <code>6144m</code></td><td>JVM heap bounds.</td></tr><tr><td><code>jvm.logbackConfigFile</code></td><td><code>/app/logback.xml</code></td><td>Logback configuration path.</td></tr><tr><td><code>participant.service.jsonApiPort</code></td><td><code>7575</code></td><td>JSON API port.</td></tr><tr><td><code>participant.service.ledgerApiPort</code></td><td><code>5001</code></td><td>Ledger API port.</td></tr><tr><td><code>participant.service.adminApiPort</code></td><td><code>5002</code></td><td>Admin API port.</td></tr><tr><td><code>validator.service.apiPort</code></td><td><code>5003</code></td><td>Validator app HTTP API port.</td></tr><tr><td><code>service.metricsPort</code></td><td><code>10013</code></td><td>Metrics port.</td></tr></tbody></table>

{% hint style="danger" %}
**Heap and memory limit are validated together.** The operator rejects the validator if `jvm.maxHeap` would not fit inside `resources.limits.memory` — the container would otherwise be OOM-killed. The limit must also leave headroom for JVM non-heap memory.

Heap values use **JVM units** with an optional `k`, `m`, or `g` suffix — `2048m`, `2g`. Kubernetes-style units such as `Mi` and `Gi` are rejected.
{% endhint %}

{% hint style="info" %}
**Version note.** 2.0.2 raised these defaults. In 2.0.1 both components defaulted to requests `2` / `3Gi`, limits `3` / `6Gi`, and heap `2048m` / `4096m`. A `Validator` that sets its own `resources` or `jvm` keeps its values.
{% endhint %}

{% hint style="warning" %}
If you supply a `requests` or `limits` block, **both `cpu` and `memory` are required inside it**. A partial block is rejected at apply time.
{% endhint %}

{% hint style="info" %}
The validator app is always held back until the participant reports `Ready`. A participant that later becomes unready pauses reconciliation of the validator app, but never removes or scales it.
{% endhint %}

***

## `spec.ui`

`wallet` and `cns` take the same fields.

<table><thead><tr><th width="330">Field</th><th width="180">Default</th><th>Purpose</th></tr></thead><tbody><tr><td><code>wallet.enabled</code> / <code>cns.enabled</code></td><td><code>true</code> (schema)</td><td>Whether the UI runs.</td></tr><tr><td><code>wallet.version</code> / <code>cns.version</code></td><td><code>spliceVersion</code> (operator)</td><td>Image tag. <strong>Reconcile required</strong> if <code>spliceVersion</code> is also unset — <em>even when the UI is disabled.</em></td></tr><tr><td><code>wallet.replicas</code> / <code>cns.replicas</code></td><td><code>1</code> (schema)</td><td>Replicas while enabled. Ignored when <code>enabled: false</code>. Minimum <code>0</code>.</td></tr><tr><td><code>resources.requests.cpu</code> / <code>.memory</code></td><td><code>100m</code> / <code>128Mi</code> (operator)</td><td>Requests.</td></tr><tr><td><code>resources.limits.cpu</code> / <code>.memory</code></td><td><code>3</code> / <code>128Mi</code> (operator)</td><td>Limits.</td></tr><tr><td><code>branding.networkName</code></td><td><code>Canton Network</code></td><td>Network display name.</td></tr><tr><td><code>branding.networkFaviconUrl</code></td><td>Canton Network favicon</td><td>Favicon URL.</td></tr><tr><td><code>branding.amuletName</code></td><td><code>Canton Coin</code></td><td>Coin display name.</td></tr><tr><td><code>branding.amuletNameAcronym</code></td><td><code>CC</code></td><td>Coin acronym.</td></tr><tr><td><code>branding.nameServiceName</code></td><td><code>Amulet Name Service</code></td><td>Name service display name.</td></tr><tr><td><code>branding.nameServiceNameAcronym</code></td><td><code>ANS</code></td><td>Name service acronym.</td></tr></tbody></table>

{% hint style="info" %}
Setting `enabled: false` scales the UI to zero replicas rather than removing it. It still appears as a component in the UI and still requires a resolvable version.
{% endhint %}

***

## `spec.pqs`

<table><thead><tr><th width="330">Field</th><th width="180">Default</th><th>Purpose</th></tr></thead><tbody><tr><td><code>enabled</code></td><td><code>false</code> (schema)</td><td>Deploy the Participant Query Store.</td></tr><tr><td><code>version</code></td><td>—</td><td>Image tag. <strong>Required when enabled</strong>, and does <em>not</em> fall back to <code>spliceVersion</code>.</td></tr><tr><td><code>replicas</code></td><td><code>1</code> (schema)</td><td>Replicas while enabled. Ignored when <code>enabled: false</code>. Minimum <code>0</code>.</td></tr><tr><td><code>ledgerStart</code></td><td><code>Latest</code> (schema)</td><td>Where PQS starts when its datastore is empty: <code>Latest</code>, <code>Oldest</code>, <code>Genesis</code>, or a ledger offset. A non-empty datastore always resumes from its checkpoint.</td></tr><tr><td><code>resources.requests.cpu</code> / <code>.memory</code></td><td><code>500m</code> / <code>1Gi</code></td><td>Requests.</td></tr><tr><td><code>resources.limits.cpu</code> / <code>.memory</code></td><td><code>3</code> / <code>2Gi</code></td><td>Limits.</td></tr><tr><td><code>jvm.minHeap</code> / <code>.maxHeap</code></td><td><code>512m</code> / <code>1536m</code></td><td>JVM heap bounds.</td></tr><tr><td><code>ledgerStop</code></td><td>PQS default</td><td>Where PQS stops: <code>Never</code>, <code>Latest</code>, or a ledger offset. Any value other than <code>Never</code> makes PQS exit when it gets there, and the deployment restarts it.</td></tr><tr><td><code>datasource</code></td><td>PQS default</td><td><code>TransactionStream</code> (creates and archives) or <code>TransactionTreeStream</code> (also exercises, divulgences, and transient contracts, at the cost of more storage).</td></tr><tr><td><code>filter.parties</code>, <code>filter.contracts</code>, <code>filter.metadata</code></td><td>PQS default</td><td>What PQS captures. Expressions use wildcards (<code>*</code>) with boolean logic.</td></tr><tr><td><code>encoding.numericAsString</code>, <code>encoding.int64AsString</code>, <code>encoding.excludeNulls</code></td><td>PQS default</td><td>JSON payload encoding.</td></tr><tr><td><code>source.bufferSize</code>, <code>source.keepAlive.time</code> / <code>.timeout</code></td><td>PQS default</td><td>Ledger API stream tuning. Host, port, and auth are set by the operator.</td></tr><tr><td><code>postgres.maxConnections</code>, <code>.bufferSize</code>, <code>.keepAlive</code>, <code>.probeInterval</code>, <code>.appName</code></td><td>PQS default</td><td>Database connection tuning. Host, database, schema, and credentials come from <code>spec.database</code>.</td></tr><tr><td><code>postgres.tlsMode</code></td><td><code>Require</code> (operator)</td><td><code>Require</code> or <code>Disable</code>. Set <code>Disable</code> only for a Postgres without TLS.</td></tr><tr><td><code>schema.autoApply</code>, <code>schema.baseline</code></td><td>PQS default</td><td>Schema management on startup.</td></tr><tr><td><code>oauth.preemptExpiry</code></td><td>PQS default</td><td>Refresh the token this long before it expires. Used only when authentication is enabled.</td></tr><tr><td><code>retry.backoff.*</code>, <code>retry.counter.*</code></td><td>PQS default</td><td>Retry delays and limits.</td></tr><tr><td><code>logger.level</code>, <code>.format</code>, <code>.pattern</code>, <code>.mappings</code></td><td>PQS default</td><td>Logging.</td></tr><tr><td><code>extraArgs</code></td><td>—</td><td>Raw PQS arguments, appended after everything the operator renders. A flag set here and by a field above is passed twice.</td></tr><tr><td><code>extraEnv</code></td><td>—</td><td>Extra environment variables for the PQS container.</td></tr></tbody></table>

Also requires `spec.database.pqsDatabase`. Fields marked *PQS default* have no default in the CRD: when one is unset, the operator passes no flag and PQS's own default applies. Durations use ISO-8601, for example `PT30S`. The fields from `ledgerStop` down were added in 2.0.2. See [Participant Query Store](https://docs.catalyx.solutions/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/participant-query-store.md).

{% hint style="warning" %}
Changing `datasource`, a `filter.*` field, or an `encoding.*` field after PQS first starts **requires a re-seed of the PQS database**.
{% endhint %}

***

## `spec.walletGateway`

<table><thead><tr><th width="380">Field</th><th width="170">Default</th><th>Purpose</th></tr></thead><tbody><tr><td><code>enabled</code></td><td><code>false</code> (schema)</td><td>Deploy the Wallet Gateway.</td></tr><tr><td><code>version</code></td><td>—</td><td>Image tag. <strong>Required when enabled</strong>, enforced by the schema.</td></tr><tr><td><code>replicas</code></td><td><code>1</code> (schema)</td><td>Replicas while enabled <em>and</em> authentication is ready. Ignored otherwise. Minimum <code>0</code>.</td></tr><tr><td><code>resources.requests.cpu</code> / <code>.memory</code></td><td><code>250m</code> / <code>512Mi</code></td><td>Requests.</td></tr><tr><td><code>resources.limits.cpu</code> / <code>.memory</code></td><td><code>1</code> / <code>1Gi</code></td><td>Limits.</td></tr><tr><td><code>dfns.enabled</code></td><td><code>false</code></td><td>Enable DFNS as a signing provider. While no provider is enabled, no wallet can be created.</td></tr><tr><td><code>dfns.orgId</code></td><td>—</td><td>Provider organisation ID.</td></tr><tr><td><code>dfns.apiUrl</code></td><td>—</td><td>Provider API base URL.</td></tr><tr><td><code>dfns.credentialId</code></td><td>—</td><td>Provider credential ID.</td></tr><tr><td><code>dfns.credentialsSecretRef.name</code></td><td>—</td><td>Secret with the provider credentials. <strong>Schema required</strong> when the block is present.</td></tr><tr><td><code>dfns.credentialsSecretRef.privateKeyKey</code></td><td><code>private-key</code></td><td>Key holding the private key.</td></tr><tr><td><code>dfns.credentialsSecretRef.authTokenKey</code></td><td><code>auth-token</code></td><td>Key holding the auth token.</td></tr><tr><td><code>bitgo.enabled</code></td><td><code>false</code></td><td>Enable BitGo as a signing provider. DFNS and BitGo can be enabled together. Added in 2.0.2.</td></tr><tr><td><code>bitgo.apiUrl</code></td><td>—</td><td>Provider API base URL.</td></tr><tr><td><code>bitgo.enterpriseId</code></td><td>—</td><td>BitGo enterprise ID.</td></tr><tr><td><code>bitgo.coin</code></td><td>—</td><td>BitGo coin.</td></tr><tr><td><code>bitgo.credentialsSecretRef.name</code></td><td>—</td><td>Secret with the BitGo access token. <strong>Schema required</strong> when the block is present.</td></tr><tr><td><code>bitgo.credentialsSecretRef.accessTokenKey</code></td><td><code>access-token</code></td><td>Key holding the access token.</td></tr></tbody></table>

Also requires `spec.auth.enabled: true`, an auth URL, a backend client ID, a Wallet Gateway client ID, a target audience, a user-management scope, and both Wallet Gateway databases. See [Wallet Gateway](https://docs.catalyx.solutions/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/wallet-gateway.md).

***

## `spec.kms`

<table><thead><tr><th width="330">Field</th><th width="130">Default</th><th>Purpose</th></tr></thead><tbody><tr><td><code>enabled</code></td><td><code>false</code></td><td>Hold Canton keys in an external KMS.</td></tr><tr><td><code>provider</code></td><td>—</td><td><code>azure</code> or <code>aws</code>. <strong>Case-sensitive</strong>, and required when enabled.</td></tr></tbody></table>

### `spec.kms.azure`

Schema-required inside: `vaultUrl`, `preBuiltImage`.

<table><thead><tr><th width="330">Field</th><th width="150">Default</th><th>Purpose</th></tr></thead><tbody><tr><td><code>vaultUrl</code></td><td>—</td><td>Key vault URL. <strong>Schema required.</strong></td></tr><tr><td><code>preBuiltImage</code></td><td>—</td><td>KMS-enabled participant image. <strong>Schema required</strong>, and it <em>replaces</em> the normal participant image.</td></tr><tr><td><code>imagePullSecret</code></td><td>—</td><td>Pull secret for that image.</td></tr><tr><td><code>keyNamePrefix</code></td><td>—</td><td>Prefix for generated key names.</td></tr><tr><td><code>credentialType</code></td><td>—</td><td><code>default</code>, <code>environment</code>, or <code>managedIdentity</code>. Omit for a service principal.</td></tr><tr><td><code>tenantId</code>, <code>clientId</code></td><td>—</td><td>Service principal identifiers.</td></tr><tr><td><code>clientSecretRef.name</code> / <code>.key</code></td><td>— / <code>client-secret</code></td><td>Service principal secret. The key default is applied by the operator, not the schema.</td></tr><tr><td><code>hardwareBackedKeys</code></td><td>driver default</td><td>Create HSM-protected keys.</td></tr><tr><td><code>healthProbeKey</code></td><td>driver default</td><td>Key name used as a connectivity probe.</td></tr><tr><td><code>auditLogging</code>, <code>auditNodeId</code></td><td>driver default</td><td>KMS request auditing.</td></tr><tr><td><code>eagerCredentialCheck</code></td><td>driver default</td><td>Acquire a token at startup to fail fast.</td></tr><tr><td><code>aesKeySizeBits</code></td><td>driver default</td><td>128, 192, or 256.</td></tr><tr><td><code>kekRsaKeySizeBits</code></td><td>driver default</td><td>2048, 3072, or 4096.</td></tr><tr><td><code>requirePinnedKeyVersion</code>, <code>validateKeySpec</code>, <code>requireKeyOps</code>, <code>rejectExportableKeys</code>, <code>hardenGeneratedKeys</code>, <code>requireStrongKek</code></td><td>driver default</td><td>Strict-mode security checks.</td></tr><tr><td><code>cryptoClientCacheSize</code>, <code>cryptoClientCacheIdleMinutes</code>, <code>ioThreads</code>, <code>httpIdleTimeoutSeconds</code>, <code>httpMaxConnections</code>, <code>httpResponseTimeoutSeconds</code></td><td>driver default</td><td>Performance and connection tuning.</td></tr></tbody></table>

{% hint style="info" %}
Fields marked *driver default* have **no default in the CRD**. Omitting one emits no configuration at all, and the KMS driver's own default applies. Set a value explicitly if you need to depend on it.
{% endhint %}

### `spec.kms.aws`

Schema-required inside: `region`.

<table><thead><tr><th width="380">Field</th><th width="180">Default</th><th>Purpose</th></tr></thead><tbody><tr><td><code>region</code></td><td>—</td><td>AWS region. <strong>Schema required.</strong></td></tr><tr><td><code>serviceAccountName</code></td><td>—</td><td>Pre-created service account for IRSA. CAT-BM does not create it.</td></tr><tr><td><code>credentialsSecretRef.name</code></td><td>—</td><td>Static credentials secret. <strong>Schema required</strong> when the block is present.</td></tr><tr><td><code>credentialsSecretRef.accessKeyIdKey</code></td><td><code>access-key-id</code></td><td>Applied by the operator, not the schema.</td></tr><tr><td><code>credentialsSecretRef.secretAccessKeyKey</code></td><td><code>secret-access-key</code></td><td>Applied by the operator, not the schema.</td></tr><tr><td><code>credentialsSecretRef.sessionTokenKey</code></td><td>—</td><td>For temporary or assumed-role credentials.</td></tr><tr><td><code>multiRegionKey</code></td><td>—</td><td>Use a multi-region key.</td></tr><tr><td><code>auditLogging</code></td><td>—</td><td>Log KMS operations.</td></tr></tbody></table>

There is no `preBuiltImage` for AWS — the standard participant image is used.

***

## `spec.overrides`

Appends environment variables to a component's container. Each block takes an `extraEnv` array using the standard Kubernetes `EnvVar` schema, so `value`, `secretKeyRef`, `configMapKeyRef`, and the other reference forms are all available.

```yaml
spec:
  overrides:
    participant:
      extraEnv:
        - name: MY_SETTING
          value: "value"
```

Available for `participant`, `validator`, `walletUi`, and `cnsUi`. An entry with the same name as an operator-set variable overrides it.

{% hint style="warning" %}
**Version note.** The 2.0.1 operator ignored `spec.overrides` entries. From 2.0.2 they are applied, so entries that had no effect before take effect on upgrade.
{% endhint %}

{% hint style="info" %}
There is no `overrides` block for PQS or the Wallet Gateway. PQS takes extra environment variables through its own `spec.pqs.extraEnv` field. The Wallet Gateway is configured only through its own fields.
{% endhint %}

***

## Status

The status subresource is written by the operator. It is read-only.

<table><thead><tr><th width="380">Field</th><th>Meaning</th></tr></thead><tbody><tr><td><code>status.observedGeneration</code></td><td>The resource generation the operator last reconciled. Compare against <code>metadata.generation</code> to see whether your change has been picked up.</td></tr><tr><td><code>status.conditions[]</code></td><td>A single <code>Ready</code> condition, with <code>status</code>, <code>reason</code>, <code>message</code>, and <code>lastTransitionTime</code>.</td></tr><tr><td><code>status.databaseProvisioned</code></td><td>Participant and validator databases created.</td></tr><tr><td><code>status.pqsDatabaseProvisioned</code></td><td>PQS database created. Present only when PQS is enabled.</td></tr><tr><td><code>status.walletGatewayDatabaseProvisioned</code></td><td>Wallet Gateway databases created. Present only when enabled.</td></tr><tr><td><code>status.applications.&#x3C;component></code></td><td>Per-component summary — <code>name</code>, <code>ready</code>, <code>reason</code>, <code>message</code>, <code>lastTransitionTime</code>. Components: <code>participant</code>, <code>validatorBackend</code>, <code>walletUi</code>, <code>cnsUi</code>, and <code>pqs</code> / <code>walletGateway</code> when enabled.</td></tr><tr><td><code>status.managedAuth</code></td><td>The result of managed authentication provisioning. See <a href="https://docs.catalyx.solutions/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/identity-provider-configuration/managed-keycloak.md">Managed Keycloak</a>.</td></tr></tbody></table>

### `Ready` condition reasons

| Reason                 | Meaning                                                                                 |
| ---------------------- | --------------------------------------------------------------------------------------- |
| `AllApplicationsReady` | Healthy                                                                                 |
| `ApplicationNotReady`  | A component has not come up. Check `status.applications`                                |
| `InvalidSpec`          | Configuration error. The message names the field                                        |
| `ReconcileError`       | A non-configuration failure — often the database or identity provider being unreachable |

### Printer columns

```bash
kubectl -n <namespace> get validators        # NAME, READY, AGE
kubectl -n <namespace> get validators -o wide  # adds REASON
```

***

## The `Application` resource

The operator creates one `Application` per component, as a child of the `Validator`.

{% hint style="danger" %}
**Never create, edit, or delete `Application` resources.** They are an operator implementation detail. A hand-created one is unowned and unmanaged; an edited one is reverted on the next reconcile. All configuration flows through the `Validator`.
{% endhint %}

`Application` resources are useful to *read*, though — they show exactly what the operator generated:

```bash
kubectl -n <namespace> get applications
kubectl -n <namespace> get application my-validator-participant -o yaml
```

Their status carries the generated `deployment`, `service`, and `ingress` names, the internal and external `endpoints`, and a `Ready` condition whose reason is one of `DeploymentNotFound`, `DeploymentAvailable`, or `DeploymentUnavailable`. The UI surfaces all of it on the [Applications](https://docs.catalyx.solutions/catalyx-blockchain-manager/canton-network/version-2.0/user-guide-canton/applications.md) pages.

***

## Schema stability

{% hint style="info" %}
The served version is `catalyx.manager.canton/v1alpha1`. **Field-level changes may still occur in a future minor release.** Keep your `Validator` resources under version control, and read the [Release Notes](https://docs.catalyx.solutions/catalyx-blockchain-manager/canton-network/version-2.0/release-notes.md) before upgrading the platform.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.catalyx.solutions/catalyx-blockchain-manager/canton-network/version-2.0/validator-crd.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
