Create a Validator

A validator is declared as a single Validator custom resource. You apply it, and the operator provisions everything else to create the validator.

Validators are created, changed, and deleted through custom resources — not through the UI. This keeps validator configuration reviewable and GitOps-friendly. The UI is where you operate a validator once it exists.

What the operator does

1

Provisions authentication

When spec.auth.managedKeycloak is true, the operator creates the OIDC clients, client scopes, protocol mappers, and wallet user for this validator, then writes the generated backend client secret to a Kubernetes Secret and records the result in status.managedAuth.

2

Provisions databases

The participant and validator-app databases and schemas are created, plus the PQS and Wallet Gateway databases when those components are enabled.

3

Creates the component applications

One child Application resource per component: participant, validator, wallet-ui, cns-ui, and optionally pqs and wallet-gateway.

4

Creates the workloads

Each Application becomes a Deployment, a Service, and — for externally reachable components — a Traefik IngressRoute.

The validator reports Ready once every component it owns is ready.

---

Prepare the secrets

Two secrets are needed in the validator's namespace before you apply.

# Database credentials — must be able to CREATE DATABASE
kubectl create secret generic my-validator-db-credentials \
  --from-literal=username=<db-user> \
  --from-literal=password=<db-password> \
  -n <namespace>

# One-time onboarding secret from the sponsoring Super Validator
kubectl create secret generic my-validator-onboarding \
  --from-literal=secret=<onboarding-secret> \
  -n <namespace>

The onboarding secret's key must be secret. The operator reads that exact key name.

If you are using an external identity provider rather than managed authentication, you also need a secret holding the backend OIDC client secret — see External Identity Provider.

---

A minimal Validator

This example relies on managed authentication and on operator defaults for every component. It is the shortest useful Validator.

my-validator.yaml

apiVersion: catalyx.manager.canton/v1alpha1
kind: Validator
metadata:
  name: my-validator
  namespace: <namespace>
spec:
  auth:
    managedKeycloak: true
    targetAudience: https://canton.network.global
    ledgerApiUserManagementScope: daml_ledger_api

  network:
    spliceVersion: "0.6.4"
    partyHint: catalyx-devnet-001
    onboardingSecretName: my-validator-onboarding
    sponsorSvUrl: https://sv.sv-1.dev.global.canton.network.sync.global
    scan:
      address: https://scan.sv-1.dev.global.canton.network.sync.global
      type: bft
      seedUrls:
        - https://scan.sv-1.dev.global.canton.network.sync.global
    synchronizer:
      connectionType: bft
      url: https://sequencer.sv-1.dev.global.canton.network.sync.global

  database:
    host: postgres.default.svc.cluster.local
    participantDb: participant_my_validator
    validatorDb: validator_my_validator
    credentialsSecretRef:
      name: my-validator-db-credentials

kubectl apply -f my-validator.yaml

spec.network.partyHint is pattern-validated. It must match ^[a-zA-Z0-9]+-[a-zA-Z0-9]+-[0-9]+$ — that is, two alphanumeric segments and a numeric segment, separated by hyphens. catalyx-devnet-001 is valid; myvalidator and my_validator_1 are rejected at apply time.

spec.network.spliceVersion sets one version for the participant, validator app, and both UIs. You can still pin any component individually with its own version field. Either the component version or spliceVersion must be set, or the validator is rejected.

Required fields

Only three top-level blocks are mandatory, and the API server rejects the resource at apply time if any is missing:

Block	Mandatory fields inside
spec.auth	None individually, but the block itself is required.
spec.network	partyHint
spec.database	host, participantDb, validatorDb, credentialsSecretRef.name

spec.network.scan and spec.network.synchronizer are not marked mandatory in the schema, but the validator cannot reconcile without them. Always supply both.

For the complete field list, see the Validator CRD Reference.

---

Watch it come up

kubectl -n <namespace> get validators
kubectl -n <namespace> get validators my-validator -o wide

The Validator resource prints a READY column, and -o wide adds the REASON for a validator that is not ready.

# Per-component detail
kubectl -n <namespace> get validators my-validator -o jsonpath='{.status.applications}' | jq

# The child applications and their workloads
kubectl -n <namespace> get applications
kubectl -n <namespace> get pods -l app.kubernetes.io/instance=my-validator

Or open the UI and watch the validator's Summary and Status tabs, which refresh automatically.

If it does not become ready

The Ready condition carries a reason that tells you which kind of problem you have:

Reason	Meaning
InvalidSpec	A configuration problem the operator detected. The condition message names the exact field. Fix the Validator and re-apply.
ReconcileError	Something went wrong that is not a configuration error — for example the database or identity provider was unreachable. Check the operator logs.
ApplicationNotReady	The configuration is accepted but a component has not come up. Look at status.applications to see which one, then at that component's pods.

kubectl -n <namespace> logs deploy/catalyx-canton-operator

Unknown fields are silently pruned by the Kubernetes API server. A misspelled field name is dropped without an error, and the setting simply has no effect. If a value seems to be ignored, check the spelling against the CRD reference and confirm it survived with kubectl get validator <name> -o yaml.

---

Deleting a validator

kubectl -n <namespace> delete validator my-validator

Kubernetes garbage-collects the child Application resources and their workloads.

Deleting a Validator does not remove:

• the databases — participant, validator, PQS, and Wallet Gateway data all remain;

• the identity provider objects created by managed authentication — clients, scopes, and users stay in the realm;

• the managed authentication secret <validator-name>-managed-ledger-api-auth.

Clean these up yourself if you are decommissioning a validator permanently. Retaining them is what makes it possible to recreate a validator against its existing state.