> For the complete documentation index, see [llms.txt](https://docs.catalyx.solutions/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.catalyx.solutions/catalyx-blockchain-manager/canton-network/version-1.11/validator-management/validator-crd-user-guide.md).

# 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

<details>

<summary>Full creation example (Kubernetes YAML)</summary>

```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
```

</details>

{% hint style="info" %}
**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.
  {% endhint %}

### Validator Operations

#### Migration

The following fields are used in migration:

```yaml
spec:
  migrationId: "2"
  migrationMigrating: false
```

To migrate, set the values as follows:

```yaml
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:

```yaml
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`:

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

{% hint style="warning" %}
The participant should have the same node identifier as the `newParticipantIdentifier` field, which must differ from the previous validator.
{% endhint %}

### Configuring the Validator

#### Environment Variable Overrides

To add extra environment variables:

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

{% hint style="info" %}
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.
{% endhint %}

#### Resource Customization

```yaml
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

<details>

<summary>Enable top-up</summary>

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

</details>

<details>

<summary>Enable scheduled pruning</summary>

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

</details>

<details>

<summary>Provide additional config</summary>

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

</details>

<details>

<summary>Set contact point</summary>

```yaml
spec:
  config:
    contactPoint: "mycompany@mail.com"
```

</details>

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.catalyx.solutions/catalyx-blockchain-manager/canton-network/version-1.11/validator-management/validator-crd-user-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.