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

## 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:**

* 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.
  {% endhint %}

## Validator Operations

### Migration

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

To migrate:

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

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

### Recovery from Identity Dump

Create a Kubernetes secret:

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

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

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

## Configuring the Validator

### Environment Variable Overrides

```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 `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.
{% 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.10/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.