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 cluster access.

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:

• The onboarding secret is one-time use.

• The validator name, participant identifier, and party hint should be changed for each new validator.

• Secrets are referenced inside the Validator definition — keep names in sync.

• Some values (e.g., port, schema) are set directly in the spec, not as secret references.

Validator Operations

Migration

spec:
  migrationId: "2"
  migrationMigrating: false

To migrate:

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

Once migration is complete, set migrationMigrating back to false.

Recovery from Identity Dump

Create a Kubernetes secret:

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 with these additional fields:

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

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

Configuring the Validator

Environment Variable Overrides

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 spec.config.

On upgrade to v1.10, a script generates spec.config fields from older <app>.spec.envVars format. 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]"