Understanding PerfectScale Operator CRD — SaaS

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

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:

Mode	Description
auto	The operator automatically upgrades the agent to the latest stable version published by PerfectScale.
webapp	The version is controlled from the PerfectScale web app. The operator waits for approval before upgrading.
manual	You set a specific version in the version field. The operator will not upgrade the agent until you update that value.

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

Example:

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.

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:

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