> For the complete documentation index, see [llms.txt](https://docs.perfectscale.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.perfectscale.io/administration/perfectscale-operator/understanding-perfectscale-operator-crd.md).

# Understanding PerfectScale Operator CRD

The Agents CR is the main resource used to install and manage PerfectScale components. Each component uses the same structure:

* `exporter`
* `autoscaler`
* `promexporter`

### Full annotated example

```yaml
apiVersion: perfectscale.io/v1alpha1
kind: Agents
metadata:
  name: agents
  namespace: perfectscale
spec:
  exporter:
    # Controls whether the operator installs and manages this agent.
    # "on"  - install the agent and keep it in sync
    # "off" - do not install the agent. If the agent is already installed, it will be removed.
    installationMode: "on"

    upgrade:
      # Controls how the operator chooses which version to run.
      # auto: The operator automatically upgrades to the latest stable version after it is published by PerfectScale.
      # webapp: The version is controlled from the PerfectScale webapp. The operator waits for approval before upgrading.
      # manual: You pin a specific version using the version field. The operator will not upgrade the agent until you update that value.
      mode: auto

      # Required only when mode is set to manual. Forbiden when mode is auto or webapp.
      # The version must use the vX.Y.Z format, for example: "v1.1.8".
      # To upgrade, set a newer version and apply the manifest.
      # To roll back, set an older version and apply the manifest.
      # version: "v1.1.8"

    # Optional. Use valuesOverride to override values supported by the exporter Helm chart.
    # The operator manages credentials and cluster name automatically. You only need valuesOverride for registry overrides, resource tuning, or other advanced chart settings.
    # Supported exporter values: https://perfectscale-io.github.io/charts/exporter
    valuesOverride:
      image:
        repository: your-registry.example.com/perfectscale-io/psc-exporter

      initContainer:
        image:
          repository: your-registry.example.com/perfectscale-io/alpine

      coroot:
        image:
          repository: your-registry.example.com/perfectscale-io/coroot-node-agent

      # kube-state-metrics uses separate registry and repository fields.
      kube-state-metrics:
        image:
          registry: your-registry.example.com
          repository: perfectscale-io/kube-state-metrics

      crdUpgradeHook:
        image:
          repository: your-registry.example.com/perfectscale-io/kubectl

  autoscaler:
    installationMode: "on"
    upgrade:
      mode: auto
    # Supported autoscaler values: https://perfectscale-io.github.io/charts/psc-autoscaler
    # valuesOverride: {}

  promexporter:
    # Disabled by default. Set installationMode to "on" to enable Prometheus metrics export.
    installationMode: "off"
    upgrade:
      mode: auto
    # Supported promexporter values: https://perfectscale-io.github.io/charts/psc-prom-exporter
    # valuesOverride: {}
```

### Upgrade modes

Each agent supports the following upgrade modes:

<table><thead><tr><th width="115.4580078125">Mode</th><th>Description</th></tr></thead><tbody><tr><td><code>auto</code></td><td>The operator automatically upgrades the agent to the latest stable version published by PerfectScale.</td></tr><tr><td><code>webapp</code></td><td>The version is controlled from the PerfectScale web app. The operator waits for approval before upgrading.</td></tr><tr><td><code>manual</code></td><td>You set a specific version in the <code>version</code> field. The operator will not upgrade the agent until you update that value.</td></tr></tbody></table>

When using `manual` mode, the `version` field is required and must use the `vX.Y.Z` format.

Example:

```yaml
upgrade:
  mode: manual
  version: "v1.1.8"
```

### valuesOverride

Use `valuesOverride` to override values supported by the underlying Helm chart.

The operator automatically manages credentials and cluster name, so you usually do not need to set those values manually.

Common use cases for `valuesOverride` include:

* Using a private image registry
* Overriding image repositories
* Adjusting resource requests or limits
* Configuring advanced Helm chart settings

### Status fields

The operator continuously updates `.status` to show the current state of each agent.

The status fields are read-only.

```yaml
status:
  exporter:
    currentVersion: "v1.1.8" # The version currently running in the cluster.
    expectedVersion: "v1.1.8" # The version the operator is trying to apply.
    errorMessage: "" # Shows the latest install or upgrade error, if one occurred.
  autoscaler:
    currentVersion: "v1.0.47"
    expectedVersion: "v1.0.47"
  promexporter:
    currentVersion: "v0.2.4"
    expectedVersion: "v0.2.4"
```

Check the current status at any time by running:

```bash
kubectl get agents agents -n perfectscale -o jsonpath='{.status}' | jq .
```


---

# 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.perfectscale.io/administration/perfectscale-operator/understanding-perfectscale-operator-crd.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.