Agent Helm Chart

The escale-agent Helm chart installs the EcoScale agent components on a Kubernetes cluster. The agent handles workload discovery, metrics forwarding, recommendation generation, and optionally resource application.

Prerequisites

• Helm 3.x installed and access to the target cluster namespace.
• metrics-server installed (required for recommendation telemetry collection).
• For mode=apply, webhook TLS must be provisioned by cert-manager or an equivalent certificate mechanism before enabling write mode.
• If using cert-manager, install it separately and provide an existing Issuer or ClusterIssuer referenced by the chart.

Installation

Sign up or sign in to EcoScale, then go to Settings -> Clusters and select Add cluster. Enter a cluster name and EcoScale will show the install command.

helm upgrade --install escale-agent-crds oci://r.ecoscale.dev/ai/escale-agent-crds \
  --version 0.3.0 \
  --namespace escale-system --create-namespace

helm upgrade --install escale-agent oci://r.ecoscale.dev/ai/escale-agent \
  --version 0.3.0 \
  --namespace escale-system --create-namespace \
  --set mode=readonly \
  --set cluster.name={name} \
  --set oidc.clientId=$CLIENT_ID \
  --set oidc.clientSecret=$CLIENT_SECRET

Replace {name} with the cluster name configured in EcoScale. Use the $CLIENT_ID and $CLIENT_SECRET values shown in the EcoScale cluster setup instructions.

Install or upgrade escale-agent-crds before escale-agent so CRDs can be upgraded independently. HPA-related CRDs are disabled by default; set hpa=true on the escale-agent-crds command to install them.

After the chart is installed, return to Settings -> Clusters and confirm that the cluster becomes visible. Once connected, EcoScale can begin organizing namespaces, discovering workloads, and surfacing recommendations when metrics are available.

Installation Modes

The chart supports two operating modes: readonly and apply. Start with readonly unless your team is ready for EcoScale-driven apply workflows.

Mode	Use it when	Additional behavior
readonly	You want cluster visibility, workload discovery, metrics, recommendations, and review workflows.	The chart still creates operational permissions for EcoScale CRs, leases, events, configmaps, and related agent coordination, but it does not add target workload patch/update permissions.
apply	You want EcoScale to apply approved recommendations or support resource automation that patches target workloads.	Adds permissions to patch and update supported target workloads and create pod evictions.

To install with apply-capable permissions, use mode=apply:

helm upgrade --install escale-agent oci://r.ecoscale.dev/ai/escale-agent \
  --version 0.3.0 \
  --namespace escale-system --create-namespace \
  --set mode=apply \
  --set cluster.name={name} \
  --set oidc.clientId=$CLIENT_ID \
  --set oidc.clientSecret=$CLIENT_SECRET \
  --set certManager.enabled=true \
  --set certManager.issuer.name=ecoscale-webhook-ca \
  --set certManager.issuer.kind=ClusterIssuer

For mode=apply, cert-manager must inject the webhook certificate into the MutatingWebhookConfiguration before workloads can be patched safely. If you use a different certificate automation system, it must provide the equivalent certificate lifecycle and CA-bundle wiring for workload-manager-webhook-cert.

Review apply mode with your platform and security teams before enabling it. mode=apply is required before EcoScale can patch target workloads, but it should be introduced only after your organization is ready to use apply or automation workflows.

RBAC Setup

By default, the chart creates a ServiceAccount, ClusterRole, and ClusterRoleBinding for the agent:

rbac:
  create: true

serviceAccount:
  create: true
  automount: true

The base RBAC grants read access for cluster discovery, workload inventory, metrics collection, and recommendation workflows. It also grants operational permissions the agent needs for EcoScale CRs, configmaps, leases, events, and setup tasks.

When mode=apply is enabled, the chart adds workload mutation permissions for supported Kubernetes workloads and pod evictions. These permissions allow EcoScale apply and automation workflows to update target resources.

Custom Workload CRDs

The agent discovers workloads through WorkloadScalerRule CRs. By default, the chart creates a rule covering standard Kubernetes workload kinds.

For custom workload CRDs, prefer workloadRule.customWorkloads. It keeps RBAC, discovery, and pod matching close together, which is easier to review than spreading the same custom kind across several values.

workloadRule:
  customWorkloads:
    - group: argoproj.io
      version: v1alpha1
      kind: Rollout
      podNamePattern: "^%s-[a-z0-9]+-[a-z0-9]+$"

The chart uses this entry to add the custom kind to the default WorkloadScalerRule, generate read RBAC for the custom resource, and pass podNamePattern through to the selector. podNamePattern is used by EcoScale metrics queries to match pods owned by that custom workload. The value must contain %s, which is replaced with the workload name.

If the generated resource name is not correct for your CRD, specify resources explicitly:

workloadRule:
  customWorkloads:
    - group: argoproj.io
      version: v1alpha1
      kind: Rollout
      podNamePattern: "^%s-[a-z0-9]+-[a-z0-9]+$"
      resources: ["rollouts", "rollouts/scale"]

extraResourceSelectors and rbac.extraRules remain available as lower-level escape hatches when you need to manage discovery and permissions manually:

workloadRule:
  extraResourceSelectors:
    - apiVersion: argoproj.io/v1alpha1
      kind: Rollout

rbac:
  extraRules:
    - apiGroups: ["argoproj.io"]
      resources: ["rollouts"]
      verbs: ["get", "list", "watch"]

Use the manual path when your organization already manages RBAC separately or when a custom resource needs unusual permissions. Otherwise, customWorkloads is the safer default because it reduces duplicated configuration.

If you want the agent to apply recommendations to custom workload kinds, add the relevant patch verbs and switch to mode=apply. Keep additional rules narrow and review them with the same process used for other cluster-wide agents. For the full selector and defaulting behavior, see WorkloadScalerRule CRD.

OIDC Configuration

During cluster setup, EcoScale issues an OIDC client ID and client secret. The agent uses these credentials to authenticate to the platform, establishing the cluster identity.

Value	Purpose
oidc.clientId	OIDC client ID issued by EcoScale.
oidc.clientSecret	OIDC client secret for the client.

The client secret is mounted as a file at /etc/escale-agent/secret/oidc-client-secret inside the agent pod. For dev and testing, pass the secret inline:

helm upgrade --install escale-agent oci://r.ecoscale.dev/ai/escale-agent \
  --version 0.3.0 \
  --namespace escale-system --create-namespace \
  --set mode=readonly \
  --set cluster.name={name} \
  --set oidc.clientId=$CLIENT_ID \
  --set oidc.clientSecret=$CLIENT_SECRET \
  --set mountSecret=true

For production, use externalSecrets to mount a pre-created Kubernetes Secret from your organization’s secret management tooling (Vault, Sealed Secrets, external-secrets operator, SOPS, etc.):

values.yaml

mountSecret: false
externalSecrets:
  - secretName: "escale-agent-oidc"
    mountPath: "/etc/escale-agent/secret"

Pre-create the Secret in the target namespace with the key oidc-client-secret before installing or upgrading:

kubectl create secret generic escale-agent-oidc \
  --namespace escale-system \
  --from-literal=oidc-client-secret='your-secret-value'

Then install without passing the secret inline:

helm upgrade --install escale-agent oci://r.ecoscale.dev/ai/escale-agent \
  --version 0.3.0 \
  --namespace escale-system --create-namespace \
  --set mode=readonly \
  --set cluster.name={name} \
  --set oidc.clientId=$CLIENT_ID \
  -f values.yaml

Avoid passing oidc.clientSecret directly through shell history or --set in production environments.