Prerequisites for the upgrade modes

Learn about prerequisites for the upgrade modes.

Before enabling auto or webapp upgrade mode, ensure your cluster nodes can pull the required agent images. Choose the option that matches your network setup.

Public ECR (no setup required)

All PerfectScale agent images are published to public ECR. If your cluster nodes have outbound internet access to public.ecr.aws, no extra configuration is needed.

Operator image

public.ecr.aws/perfectscale-io/psc-agent-operator

Agent images (tags change with each release)

public.ecr.aws/perfectscale-io/psc-exporter
public.ecr.aws/perfectscale-io/psc-autoscaler
public.ecr.aws/perfectscale-io/psc-prom-exporter

Sub-agents and init images used by the Helm charts

Image	Purpose
public.ecr.aws/perfectscale-io/alpine	Init container
public.ecr.aws/perfectscale-io/coroot-node-agent	Node-level metrics
public.ecr.aws/perfectscale-io/kubectl	In-cluster operations
ghcr.io/prometheus-community/windows-exporter	Windows nodes only
public.ecr.aws/perfectscale-io/kube-state-metrics	Kube-state-metrics

---

Private Registry (air-gapped or restricted clusters)

If your nodes cannot pull from public.ecr.aws, mirror the images to your own registry. Because image tags change with every release, you have two mirroring strategies:

1. Pull-Through Cache (recommended for auto and webapp mode)

Configure your registry (ECR, Harbor, Nexus, etc.) as a pull-through cache for public.ecr.aws. New image tags are fetched automatically whenever the operator upgrades agents, without manual intervention required between releases.

2. Manual Mirror (suitable for manual and webapp mode)

Pull and push each image for the specific version you intend to run. You must repeat this process for every upgrade.

Use the following Helm install command:

  helm upgrade --install psc-agents-operator perfectscale/psc-agent-operator \
  -n perfectscale --create-namespace \
  --set secret.create=true \
  --set secret.clientId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  --set secret.clientSecret=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  --set settings.clusterName={your-cluster-name} \
  --set controllerManager.manager.image.repository=your-registry.example.com/perfectscale-io/psc-agent-operator

Overriding the image registry in the AgentManager CR

Use valuesOverride per agent to point each component to your private registry.

apiVersion: perfectscale.io/v1alpha1
kind: Agents
metadata:
  labels:
    app.kubernetes.io/name: psc-agent-operator
  name: agents
  namespace: perfectscale
spec:
  exporter:
    installationMode: "on"
    upgrade:
      mode: auto
    valuesOverride:
      image:
        repository: your-registry.example.com/perfectscale-io/psc-exporter
      corootNodeAgent:
        image:
          repository: your-registry.example.com/perfectscale-io/coroot-node-agent
      kube-state-metrics:
        image:
          registry: your-registry.example.com
          repository: perfectscale-io/kube-state-metrics
  autoscaler:
    installationMode: "on"
    upgrade:
      mode: auto
    valuesOverride:
      image:
        repository: your-registry.example.com/perfectscale-io/psc-autoscaler
  promexporter:
    installationMode: "on"
    upgrade:
      mode: auto
    valuesOverride:
      image:
        repository: your-registry.example.com/perfectscale-io/psc-prom-exporter

The operator merges valuesOverride on top of its own defaults before every Helm install or upgrade. Your custom registry is preserved even when the operator auto-upgrades to a new version.