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.
Schema default
Applied by the Kubernetes API server when you omit the field. It is written into the stored resource, so kubectl get -o yaml shows it.
Operator default
Applied by the operator at reconcile time. The field stays absent from the stored resource — the value appears only in the resulting workload.
Similarly, two kinds of "required":
Schema required
The API server rejects the resource at kubectl apply. Fast, obvious failure.
Reconcile required
Accepted at apply, then fails during reconciliation. Surfaces as the Ready condition with reason InvalidSpec and a message naming the field.
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:
kubectl -n <namespace> get validator my-validator -o yamlTop level
Three blocks are schema-required: auth, database, and network.
spec.auth
Schema
Authentication for every component.
spec.database
Schema
PostgreSQL connection and database names.
spec.network
Schema
Canton network connectivity.
spec.participant
No
Canton participant node configuration.
spec.validator
No
Validator app configuration.
spec.ui
No
Wallet UI and CNS UI configuration and branding.
spec.pqs
No
Participant Query Store.
spec.walletGateway
No
Wallet Gateway.
spec.kms
No
External key management.
spec.overrides
No
Extra environment variables per component.
spec.auth
enabled
boolean
true
Master authentication switch. false disables authentication on the participant.
managedKeycloak
boolean
false
true → the operator provisions the OIDC objects and reads configuration from status.managedAuth.
authUrl
string
—
OIDC issuer or token endpoint.
jwksUrl
string
—
JWKS endpoint for token verification.
targetAudience
string
—
Audience every token must carry.
ledgerApiUserManagementScope
string
—
OAuth scope granting Ledger API user management.
ledgerApiUser
string
—
Participant admin user name.
walletUserName
string
—
Wallet owner user name.
ledgerApiClientId
string
—
Confidential backend client ID.
walletUiClientId
string
—
Public client ID for the Wallet UI.
cnsUiClientId
string
—
Public client ID for the CNS UI.
walletGatewayClientId
string
—
Public client ID for the Wallet Gateway.
ledgerApiClientSecretRef.name
string
—
Secret holding the backend client secret.
ledgerApiClientSecretRef.key
string
client-secret
Key within that secret.
spec.database
Schema-required inside: host, participantDb, validatorDb, credentialsSecretRef.name.
host
string
—
PostgreSQL host. Schema required.
port
integer
5432
PostgreSQL port. Must be 1–65535.
participantDb
string
—
Participant database name. Schema required.
participantSchema
string
participant
Participant schema.
validatorDb
string
—
Validator app database name. Schema required.
validatorSchema
string
validator
Validator app schema.
pqsDatabase
string
—
PQS database name. Reconcile required when pqs.enabled.
pqsSchema
string
pqs
PQS schema.
walletGatewayStoreDatabase
string
—
Wallet Gateway store database. Reconcile required when walletGateway.enabled.
walletGatewaySigningDatabase
string
—
Wallet Gateway signing database. Reconcile required when walletGateway.enabled.
credentialsSecretRef.name
string
—
Secret with the database credentials. Schema required.
credentialsSecretRef.usernameKey
string
username
Key holding the username.
credentialsSecretRef.passwordKey
string
password
Key holding the password.
spec.network
Schema-required inside: partyHint.
partyHint
string
—
Party ID hint, and the wallet username under managed authentication. Schema required, and pattern-validated — see below.
spliceVersion
string
—
Single image tag for the participant, validator app, and both UIs, used when a component has no version of its own.
migrationId
string
"1"
Canton domain migration ID. A string, not an integer.
onboardingSecretName
string
—
Secret holding the Super Validator onboarding token, under the key secret.
sponsorSvUrl
string
—
Sponsoring Super Validator URL.
contactPoint
string
—
Operator contact point published to the network.
scan.address
string
—
Scan service address.
scan.type
string
—
Scan mode. Use bft with seedUrls, or trust-single with a single address.
scan.seedUrls
string[]
—
BFT scan seed URLs.
synchronizer.connectionType
string
—
Sequencer connection mode: bft or trust-single.
synchronizer.url
string
—
Sequencer URL. Used with trust-single.
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.
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.
spec.participant and spec.validator
Both blocks are optional and take operator defaults. spec.participant additionally has nodeIdentifier; spec.validator additionally has dumpPath.
version
spec.network.spliceVersion
Image tag. Reconcile required if spliceVersion is also unset.
participant.nodeIdentifier
spec.network.partyHint
Canton participant node identifier.
validator.dumpPath
—
Path to a domain migration dump.
resources.requests.cpu / .memory
2 / 3Gi
CPU and memory requests.
resources.limits.cpu / .memory
3 / 6Gi
CPU and memory limits.
jvm.minHeap / .maxHeap
2048m / 4096m
JVM heap bounds.
jvm.logbackConfigFile
/app/logback.xml
Logback configuration path.
participant.service.jsonApiPort
7575
JSON API port.
participant.service.ledgerApiPort
5001
Ledger API port.
participant.service.adminApiPort
5002
Admin API port.
validator.service.apiPort
5003
Validator app HTTP API port.
service.metricsPort
10013
Metrics port.
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.
If you supply a requests or limits block, both cpu and memory are required inside it. A partial block is rejected at apply time.
spec.ui
wallet and cns take the same fields.
wallet.enabled / cns.enabled
true (schema)
Whether the UI runs.
wallet.version / cns.version
spliceVersion (operator)
Image tag. Reconcile required if spliceVersion is also unset — even when the UI is disabled.
resources.requests.cpu / .memory
100m / 128Mi (operator)
Requests.
resources.limits.cpu / .memory
3 / 128Mi (operator)
Limits.
branding.networkName
Canton Network
Network display name.
branding.networkFaviconUrl
Canton Network favicon
Favicon URL.
branding.amuletName
Canton Coin
Coin display name.
branding.amuletNameAcronym
CC
Coin acronym.
branding.nameServiceName
Amulet Name Service
Name service display name.
branding.nameServiceNameAcronym
ANS
Name service acronym.
spec.pqs
enabled
false (schema)
Deploy the Participant Query Store.
version
—
Image tag. Required when enabled, and does not fall back to spliceVersion.
ledgerStart
Latest (schema)
Where the pipeline starts reading.
resources.requests.cpu / .memory
500m / 1Gi
Requests.
resources.limits.cpu / .memory
3 / 2Gi
Limits.
jvm.minHeap / .maxHeap
512m / 1536m
JVM heap bounds.
Also requires spec.database.pqsDatabase. See Participant Query Store.
spec.walletGateway
enabled
false (schema)
Deploy the Wallet Gateway.
version
—
Image tag. Required when enabled, enforced by the schema.
resources.requests.cpu / .memory
250m / 512Mi
Requests.
resources.limits.cpu / .memory
1 / 1Gi
Limits.
dfns.orgId
—
Provider organisation ID.
dfns.apiUrl
—
Provider API base URL.
dfns.credentialId
—
Provider credential ID.
dfns.credentialsSecretRef.name
—
Secret with the provider credentials. Schema required when the block is present.
dfns.credentialsSecretRef.privateKeyKey
private-key
Key holding the private key.
dfns.credentialsSecretRef.authTokenKey
auth-token
Key holding the auth token.
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.
spec.kms
enabled
false
Hold Canton keys in an external KMS.
provider
—
azure or aws. Case-sensitive, and required when enabled.
spec.kms.azure
Schema-required inside: vaultUrl, preBuiltImage.
vaultUrl
—
Key vault URL. Schema required.
preBuiltImage
—
KMS-enabled participant image. Schema required, and it replaces the normal participant image.
imagePullSecret
—
Pull secret for that image.
keyNamePrefix
—
Prefix for generated key names.
credentialType
—
default, environment, or managedIdentity. Omit for a service principal.
tenantId, clientId
—
Service principal identifiers.
clientSecretRef.name / .key
— / client-secret
Service principal secret. The key default is applied by the operator, not the schema.
hardwareBackedKeys
driver default
Create HSM-protected keys.
healthProbeKey
driver default
Key name used as a connectivity probe.
auditLogging, auditNodeId
driver default
KMS request auditing.
eagerCredentialCheck
driver default
Acquire a token at startup to fail fast.
aesKeySizeBits
driver default
128, 192, or 256.
kekRsaKeySizeBits
driver default
2048, 3072, or 4096.
requirePinnedKeyVersion, validateKeySpec, requireKeyOps, rejectExportableKeys, hardenGeneratedKeys, requireStrongKek
driver default
Strict-mode security checks.
cryptoClientCacheSize, cryptoClientCacheIdleMinutes, ioThreads, httpIdleTimeoutSeconds, httpMaxConnections, httpResponseTimeoutSeconds
driver default
Performance and connection tuning.
spec.kms.aws
Schema-required inside: region.
region
—
AWS region. Schema required.
serviceAccountName
—
Pre-created service account for IRSA. CAT-BM does not create it.
credentialsSecretRef.name
—
Static credentials secret. Schema required when the block is present.
credentialsSecretRef.accessKeyIdKey
access-key-id
Applied by the operator, not the schema.
credentialsSecretRef.secretAccessKeyKey
secret-access-key
Applied by the operator, not the schema.
credentialsSecretRef.sessionTokenKey
—
For temporary or assumed-role credentials.
multiRegionKey
—
Use a multi-region key.
auditLogging
—
Log KMS operations.
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.
Available for participant, validator, walletUi, and cnsUi.
Status
The status subresource is written by the operator. It is read-only.
status.observedGeneration
The resource generation the operator last reconciled. Compare against metadata.generation to see whether your change has been picked up.
status.conditions[]
A single Ready condition, with status, reason, message, and lastTransitionTime.
status.databaseProvisioned
Participant and validator databases created.
status.pqsDatabaseProvisioned
PQS database created. Present only when PQS is enabled.
status.walletGatewayDatabaseProvisioned
Wallet Gateway databases created. Present only when enabled.
status.applications.<component>
Per-component summary — name, ready, reason, message, lastTransitionTime. Components: participant, validatorBackend, walletUi, cnsUi, and pqs / walletGateway when enabled.
status.managedAuth
The result of managed authentication provisioning. See Managed Keycloak.
Ready condition reasons
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
The Application resource
The operator creates one Application per component, as a child of the Validator.
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.
Application resources are useful to read, though — they show exactly what the operator generated:
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 pages.
Schema stability
Last updated
Was this helpful?