> ## Documentation Index
> Fetch the complete documentation index at: https://metoro.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrading from 11.x

> Upgrade Metoro on-premises 11.x hubs and exporters to 12.x

12.x upgrades in place from 11.x. Upgrade straight to the hub chart **12.0.2** (see the note below on 12.0.0); the exporter chart is `12.0.0`. Both releases run on the same new-generation telemetry tables, so no ClickHouse reset, data migration, or datastore maintenance step is required. New PostgreSQL tables (the webhook secret store, CRD sync state, Guardian GitHub drafts) are created automatically when the new Apiserver starts.

> [!NOTE]
>
> Hub commands assume the Helm release is named `metoro` and runs in the `metoro-hub` namespace. Monitored-cluster exporter commands assume the Helm release is named `metoro-exporter` and runs in the `metoro` namespace. Adjust release names and namespaces if your installation uses different values.

## Values Changes

12.0.0 removes the 11.x telemetry-table switches, because the hub now always writes and reads only the new-generation tables. Delete these keys from your hub values file if they are present:

* `newTelemetryTablesAcknowledged`
* `ingester.tablesV3`
* `ingester.tablesV3Only`
* `ingester.attributesJsonTables`

The chart ignores them if they are left in place, so forgetting one does not break the upgrade.

New optional values, all off by default:

| Value | Purpose |
| - | - |
| `apiserver.secretStore.encryptionSecret.name` / `.key` | Turns on the encrypted secret store that backs `MetoroWebhook` `secretKeyRef`s. See [Webhook Secret Store](https://metoro.io/docs/on-premises/12.x/operations/apiserver.md#webhook-secret-store). |
| `agentSandbox.appArmorProfile` | Runs Guardian sandbox pods under a named AppArmor profile, needed on Ubuntu 24.04+ nodes. See [Guardian sandbox security profile](https://metoro.io/docs/on-premises/12.x/installation/metoro-ai.md#guardian-sandbox-security-profile). |
| `exporter.secretRefs.*` (exporter chart) | Lets the exporter read the Kubernetes Secrets that `MetoroWebhook` resources reference. |

> [!WARNING]
>
> Do not upgrade to hub chart 12.0.0 or 12.0.1. 12.0.0 left the bundled PostgreSQL at its default `max_connections` of 100, which is too low for Temporal's connection pools, so some Temporal pods crashloop with `no usable database connection found`. 12.0.1 raised `max_connections` to 400 (new value `postgres.bundled.cluster.parameters`) and sizes the Temporal pools to fit. If you use external PostgreSQL, make sure it allows at least 400 connections for Metoro. Separately, Guardian chat fails on 12.0.0 and 12.0.1 hubs served over plain HTTP; 12.0.2 fixes that. See [Upgrade 12.0.0 or 12.0.1 to 12.0.2](https://metoro.io/docs/on-premises/12.x/upgrades/12-0-0-to-12-0-1.md).

> [!WARNING]
>
> When `ai.enabled=true`, the Guardian sandbox pods now run with an `Unconfined` seccomp profile (and an `Unconfined` AppArmor profile unless `agentSandbox.appArmorProfile` is set), so the Guardian runner can create the user namespaces it uses for its own isolation. The pods still run as non-root with all capabilities dropped. If your cluster enforces Pod Security Admission `restricted` or a policy engine rule on the Agent Sandbox namespace, allow these profiles for the Guardian sandbox pods before upgrading.

## Upgrade The Hub

Start from the values file used for the existing hub release. If you do not have it locally, export the user-supplied Helm values:

```bash theme={null}
helm -n metoro-hub get values metoro > metoro-hub-values.yaml
```

Remove the keys listed in [Values Changes](#values-changes), then upgrade the hub chart to `12.0.2`:

```bash theme={null}
helm upgrade --install metoro oci://quay.io/metoro/charts/metoro-onprem \
  --namespace metoro-hub \
  --version 12.0.2 \
  --values metoro-hub-values.yaml
```

## Check The Hub Rollout

```bash theme={null}
helm -n metoro-hub status metoro
kubectl -n metoro-hub rollout status deployment/apiserver
kubectl -n metoro-hub rollout status deployment/ingester
```

If hub self-monitoring is enabled, check the bundled exporter rollout too:

```bash theme={null}
kubectl -n metoro-hub rollout status deployment/metoro-exporter
```

If Metoro AI is enabled, check the Agent Sandbox components:

```bash theme={null}
kubectl -n metoro-hub rollout status deployment/sandbox-router-deployment
kubectl -n agent-sandbox-system rollout status deployment/agent-sandbox-controller
```

## Upgrade Monitored-Cluster Exporters

Upgrading the hub repins future onboarding commands, but it does not upgrade exporter releases already installed on monitored clusters. The 12.0.0 exporter chart installs the new `MetoroClusterIngestionRule` CRD, adds `spec.tags` to the `MetoroAlert` and `MetoroDashboard` CRDs and the Secret reference fields to `MetoroWebhook`, so upgrade every monitored cluster before using those features there.

Upgrade the hub first, then repeat this section for every monitored cluster that has `metoro-exporter-onprem` installed. Start from the values file used for the existing exporter release. If you do not have it locally, export the user-supplied Helm values:

```bash theme={null}
helm -n metoro get values metoro-exporter > metoro-exporter-values.yaml
```

Upgrade the exporter chart to `12.0.0`:

```bash theme={null}
helm upgrade --install metoro-exporter oci://quay.io/metoro/charts/metoro-exporter-onprem \
  --namespace metoro \
  --version 12.0.0 \
  --values metoro-exporter-values.yaml
```

## Check Monitored-Cluster Rollouts

```bash theme={null}
helm -n metoro status metoro-exporter
kubectl -n metoro rollout status deployment/metoro-exporter
kubectl -n metoro rollout status daemonset/metoro-node-agent
kubectl get crd metoroclusteringestionrules.observability.metoro.io
```

If ServiceMonitor scraping is enabled, check the collector and target allocator rollouts too:

```bash theme={null}
kubectl -n metoro rollout status statefulset/metoro-exporter-sm-scraper
kubectl -n metoro rollout status deployment/metoro-exporter-sm-scraper-targetallocator
```

Expected outcome:

* Apiserver, Ingester, and (when enabled) the Guardian runner roll to the `onprem-12.0.2` images, and the bundled PostgreSQL restarts once (rolling, with a switchover) to apply `max_connections`.
* Hub self-monitoring rolls to the 12.0.0 exporter chart and images when enabled.
* Existing monitored-cluster exporter releases roll to the 12.0.0 exporter chart and images after their Helm upgrades, and the `MetoroClusterIngestionRule` CRD exists on each cluster.
* Existing PostgreSQL, ClickHouse, Temporal, and telemetry data remain in place.
* Future monitored-cluster onboarding commands reference `metoro-exporter-onprem` 12.0.0.

## Rolling Back

11.0.0 and 12.0.0 use the same telemetry tables, but 12.0.0 also updates ClickHouse view definitions and PostgreSQL schema on startup. Contact Metoro support before rolling a hub back to 11.0.0.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.