Validator CRD User Guide

Catalyst uses the operator pattern with Custom Resource Definitions. The same operations available in the Catalyst GUI can also be performed directly on Kubernetes with access to the cluster.

Creating a Validator

Full creation example (Kubernetes YAML)

apiVersion: v1
kind: Secret
metadata:
  namespace: canton-dev
  name: database-validator-dev-foo
data:
  user: "YWRtaW4="
  password: "YWRtaW4="
---
apiVersion: v1
kind: Secret
metadata:
  namespace: canton-dev
  name: cn-app-validator-dev-foo-onboarding-validator
data:
  secret: "<onboarding-secret-base64>"
---
apiVersion: v1
kind: Secret
metadata:
  namespace: canton-dev
  name: cn-app-validator-dev-foo-cns-ui-auth
data:
  url: "<keycloak-url-base64>"
  clientId: "<cns-client-id-base64>"
---
apiVersion: v1
kind: Secret
metadata:
  namespace: canton-dev
  name: cn-app-validator-dev-foo-wallet-ui-auth
data:
  url: "<keycloak-url-base64>"
  clientId: "<wallet-client-id-base64>"
  username: "<wallet-username-base64>"
---
apiVersion: v1
kind: Secret
metadata:
  namespace: canton-dev
  name: cn-app-validator-dev-foo-ledger-api-auth
data:
  client-id: "<client-id-base64>"
  client-secret: "<client-secret-base64>"
  ledger-api-user: "<ledger-api-user-base64>"
  url: "<token-url-base64>"
---
apiVersion: catalyst.manager.canton/v1
kind: Validator
metadata:
  name: validator-dev-foo
  namespace: canton-dev
spec:
  config:
    scanAddress: "https://scan.sv-1.dev.global.canton.network.sync.global"
    svSponsorAddress: "https://sv.sv-1.dev.global.canton.network.sync.global"
    defaultJvmOptions: "-Xms1152M -Xmx1152M -Dscala.concurrent.context.minThreads=4"
    partyHint: ieu-foo-001
    failOnAppVersionMismatch: true
    database:
      port: 5432
      pwdField: password
      schema: validator
      secretName: database-validator-dev-foo
      userField: user
    participant:
      nodeIdentifier: IEUDevFoo001
  customAuth: true
  imageRepo: ghcr.io/digital-asset/decentralized-canton-sync/docker
  imageTag: 0.4.16
  migrationId: "0"
  migrationMigrating: false
  onboardingSecretName: cn-app-validator-dev-foo-onboarding-validator
  storageSize: 20Gi

Key notes when creating a validator:

• The onboarding secret is one-time use.

• The validator name, participant identifier, and party hint should be changed when deploying a new validator.

• Secrets (names and fields) are referenced inside the Validator definition itself — keep them in-sync.

• Some data is provided as part of the reference itself (e.g., port, schema), not as a secret field.

Validator Operations

Migration

The following fields are used in migration:

spec:
  migrationId: "2"
  migrationMigrating: false

To migrate, set the values as follows:

spec:
  migrationId: "new mig id"
  migrationMigrating: true

Once the migration is complete, set migrationMigrating back to false.

Recovery from Identity Dump

To recover Canton Coin balances using an Identities Backup, create a Kubernetes secret in the following format:

apiVersion: v1
data:
  content: <Identity Backup>
kind: Secret
metadata:
  labels:
    validator: <validator crd name>
  name: id-backup-secret-example
  namespace: namespace-of-val
type: Opaque

Then create a validator (removing the old one if on the same cluster) with the following fields added to spec:

spec:
  config:
    partyHint: "oldParty"
    participant:
      nodeIdentifier: "validator-foooooooo"
    identitiesImport:
      newParticipantIdentifier: "validator-foooooooo"
      secretName: "secret-with-identity-dump-party"
    isMigrateValidatorParty: true

The participant should have the same node identifier as the newParticipantIdentifier field, which must differ from the previous validator.

Configuring the Validator

Environment Variable Overrides

To add extra environment variables:

spec:
  config:
    validatorOverrides:
      - name: OVERRIDE_EXAMPLE
        value: "5432"
    participantOverrides: []
    walletOverrides:
      - name: OVERRIDE_WITH_SECRET
        valueFrom:
          secretKeyRef:
            key: password
            name: secret
    cnsOverrides: []

These overrides will override any variables generated by the spec.config. In older versions, environment variables were defined directly in application.spec.envVars, applicationWallet.spec.envVars, etc. On upgrade to v1.10, a script generates the spec.config fields from these. The <app>.spec.envVars format will be removed in a future release.

Resource Customization

spec:
  application:
    spec:
      resources:
        cpuLimit: "4"
        cpuRequested: "2"
        memoryLimit: 8Gi
        memoryRequested: 4Gi
        replicas: 1
  applicationCantonNameServer:
    spec:
      resources:
        cpuLimit: "2"
        cpuRequested: "0.5"
        memoryLimit: 2Gi
        memoryRequested: 512Mi
        replicas: 1
  applicationWallet:
    spec:
      resources:
        cpuLimit: "2"
        cpuRequested: "0.5"
        memoryLimit: 2Gi
        memoryRequested: 512Mi
        replicas: 1
  participant:
    spec:
      resources:
        cpuLimit: "4"
        cpuRequested: "2"
        memoryLimit: 8Gi
        memoryRequested: 4Gi
        replicas: 1
  storageSize: 50Gi

Other Configuration Examples

Enable top-up

spec:
  config:
    topUp:
      enabled: true
      minInterval: 2m
      targetThroughput: 80000

Enable scheduled pruning

spec:
  config:
    scheduledPrune:
      retention: "2m"
      cron: "* * * * *"
      maxDuration: "30d"

Provide additional config

spec:
  config:
    additionalConfigOther: |
      canton.validator-apps.validator_backend.participant-bootstrapping-dump {
        type = file
        file = /participant-bootstrapping-dump/content
        new-participant-identifier = "validator-fooooooo"
      }

Set contact point

spec:
  config:
    contactPoint: "[e-mail]"

---

KMS

KMS is set at creation via spec.enableKms plus fields on the participant spec. It cannot be toggled on or off after creation.

AWS / GCP

AWS

spec:
  enableKms: true
  participant:
    spec:
      serviceAccount: catbm-aws-kms
      kmsValue: '{ type = "aws", region = "eu-west-1", audit-logging = true }'

GCP

Azure

spec:
  enableKms: true
  participant:
    spec:
      overrideImage: <azure-kms-driver participant image, matching the splice image>
      resources:
        imagePullSecret: azure-kms-registry-credentials
      kmsValue: '{ type = driver, name = "azure-kms", config { vault-url = "...", credential { type = environment } } }'
      kmsAzureVaultSecretName: azure-kms-credentials

The secret named by kmsAzureVaultSecretName must contain: tenant-id, client-id, client-secret.

API-to-CRD field mapping

The REST API nests these under clusterParticipantConfig:

API field	CRD path
enableKms	spec.enableKms
kmsValue	spec.participant.spec.kmsValue
kmsServiceAccount	spec.participant.spec.serviceAccount
kmsAzureVaultSecretName	spec.participant.spec.kmsAzureVaultSecretName
overrideImage	spec.participant.spec.overrideImage
participant.resources.imagePullSecret	spec.participant.spec.resources.imagePullSecret

---