Validator Custom Resource Definition

This page provides an overview of the Validator Custom Resource Definition (CRD) used by Catalyst Blockchain Manager to deploy and manage Canton validators using Kubernetes. It describes the structure of the CRD and explains how each validator component is defined and configured.

A Custom Resource Definition (CRD) in Kubernetes is a way to extend the Kubernetes API by defining new, custom object types, allowing you to manage application-specific data.

Structure of the Specification

The CRD specification defines each validator component separately.

Component	CRD Location
Validator (core)	Top level of the specification
ANS/CNS UI	spec.applicationCantonNameServer.spec
Wallet UI	spec.walletUI.spec
Participant Node	spec.participant.spec

Provisioned Postgres Database

The PostgreSQL database provisioned for the validator is not explicitly represented in the CRD specification. To increase the database storage size (decreases are ignored), use:

spec.storageSize

Modifying Component Specifications

Environment Variables

For all components, environment variables are defined under spec.envVars. They follow the same structure and format used in Kubernetes Pods and Deployments.

Resources

Each component has a resource specification:

resources:
    cpuLimit: '2'
    cpuRequested: '1'
    imagePullSecret: intellecteu-gitlab-access
    memoryLimit: 2Gi
    memoryRequested: 1Gi
    replicas: 1

Field	Description
cpuLimit	Maximum CPU allocation
cpuRequested	Minimum CPU allocation
memoryLimit	Maximum memory allocation
memoryRequested	Minimum memory allocation
replicas	Number of instances (can be set to 0 or 1)

To scale down a validator, set the replicas field to 0 for all components.

Example CRD

Full example Validator CRD YAML

apiVersion: catalyst.manager.canton/v1
kind: Validator
metadata:
  name: validator1st
  namespace: canton-dev
spec:
  application:
    spec:
      domain: participant-validator1st
      resources:
        cpuLimit: '2'
        cpuRequested: '1'
        imagePullSecret: intellecteu-gitlab-access
        memoryLimit: 2Gi
        memoryRequested: 1Gi
        replicas: 1
      type: backend
      validatorParent: validator1st
  applicationCantonNameServer:
    spec:
      domain: cns-validator1st
      image: >-
        digitalasset-canton-network-docker.jfrog.io/digitalasset/ans-web-ui:0.3.15
      resources:
        cpuLimit: '1'
        cpuRequested: '0.1'
        imagePullSecret: intellecteu-gitlab-access
        memoryLimit: 1536Mi
        memoryRequested: 240Mi
        replicas: 1
      type: ui
  applicationWallet:
    spec:
      domain: wallet-validator1st
      image: >-
        digitalasset-canton-network-docker.jfrog.io/digitalasset/wallet-web-ui:0.3.15
      resources:
        cpuLimit: '1'
        cpuRequested: '0.1'
        imagePullSecret: intellecteu-gitlab-access
        memoryLimit: 1536Mi
        memoryRequested: 240Mi
        replicas: 1
      type: ui
  customAuth: false
  disabledWallet: false
  enableKms: false            # master flag for KMS; the KMS fields live under participant.spec
  image: digitalasset-canton-network-docker.jfrog.io/digitalasset/validator-app:0.3.15
  imageRepo: digitalasset-canton-network-docker.jfrog.io/digitalasset
  imageTag: 0.3.15
  migrationId: '0'
  migrationMigrating: false
  participant:
    spec:
      adminPort: '5002'
      auth: true
      authProvider: keycloak
      image: >-
        digitalasset-canton-network-docker.jfrog.io/digitalasset/canton-participant:0.3.15
      jsonapi: false
      ledgerPort: '5001'
      # --- KMS (only applied when spec.enableKms is true) ---
      serviceAccount: catbm-aws-kms          # AWS/GCP: K8s ServiceAccount (IRSA / workload identity)
      kmsValue: '{ type = "aws", region = "eu-west-1", audit-logging = true }'   # HOCON provider config
      kmsAzureVaultSecretName: ''            # Azure only: K8s Secret with tenant-id, client-id, client-secret
      overrideImage: ''                      # Azure only: Azure-KMS driver participant image (matches splice image)
      logLevel: INFO
      resources:
        cpuLimit: '2'
        cpuRequested: '1'
        imagePullSecret: intellecteu-gitlab-access   # Azure KMS: set to pull secret for the override (driver) image
        memoryLimit: 2Gi
        memoryRequested: 1Gi
        replicas: 1
      storageType: Shared Postgres
  resources:
    cpuLimit: '2'
    cpuRequested: '1'
    imagePullSecret: intellecteu-gitlab-access
    memoryLimit: 2Gi
    memoryRequested: 1Gi
    replicas: 1
  storageSize: 20Gi

KMS Fields

The following fields control KMS for a validator. enableKms is immutable after creation; all other KMS fields are also immutable except overrideImage, which remains editable.

Field	Location	Notes
enableKms	spec	Master flag; immutable after creation
participant.spec.kmsValue	spec.participant.spec	HOCON provider config (AWS / GCP / Azure)
participant.spec.serviceAccount	spec.participant.spec	AWS/GCP ServiceAccount; not used for Azure
participant.spec.kmsAzureVaultSecretName	spec.participant.spec	Azure only; Secret with tenant-id / client-id / client-secret
participant.spec.overrideImage	spec.participant.spec	Azure driver image; the only KMS-adjacent field editable post-creation
participant.spec.resources.imagePullSecret	spec.participant.spec.resources	Azure only; pull secret for the override (driver) image

When enableKms is true: kmsValue is required, plus either serviceAccount (AWS/GCP) or kmsAzureVaultSecretName (Azure).

---