Upgrade SigNoz to v0.150.0 with Alert Rules v2alpha1 Schema

SigNoz v0.150.0 moves alert rules to a single schema, v2alpha1. Your existing rules are converted to the new schema automatically when the server starts, so no action is needed if you only manage alerts in the UI.

The v1 rules endpoints (/api/v1/rules, /api/v1/testRule) and the GET /api/v2/rules list are removed. See Endpoints.
Rule create, replace, and test requests must send "schemaVersion": "v2alpha1". See What a v1 payload gets back after the upgrade.
Terraform configurations on the signoz_alert resource have to move to signoz_rule. See Who needs to act.
The SigNoz Operator must be v0.0.5 or newer. See Upgrade the SigNoz Operator.

Key changes:

Schema: one rule schema, v2alpha1, which groups thresholds, evaluation, and notification behavior into three required objects: condition.thresholds, evaluation, and notificationSettings
APIs: the rules API lives on /api/v2/rules, with a paginated summary list at GET /api/v3/rules; the v1 rules endpoints are removed
Migration: stored v1 rules are rewritten to v2alpha1 when the server starts

For the full release scope, see the v0.150.0 release notes. For the scope of the alert rules change, see signoz#13524. For the schema and API details, see Migrate Alert Rules from the v1 Schema to v2alpha1.

Who needs to act

If you	Then
Use alerts only through the UI	Nothing: rules are migrated automatically
Have scripts calling `/api/v1/rules`, `/api/v1/testRule`, or `GET /api/v2/rules`	Migrate them to the v2 rules APIs before upgrading: these endpoints are removed
Have scripts already on `/api/v2/rules` that send v1-shaped bodies	Add `schemaVersion` and the new objects before upgrading: create, replace, and test bodies without `schemaVersion` are rejected with `400`
Have scripts or integrations that read rules and expect the v1 fields back	Update them to the new shape: after the upgrade, a rule fetched by id comes back in the `v2alpha1` shape, and the list returns a summary of each rule
Manage alerts with the Terraform `signoz_alert` resource	Move to `signoz_rule`
Manage SigNoz resources with the SigNoz Operator	Upgrade the operator to v0.0.5 or newer

Upgrade Self-Hosted SigNoz

Step 1: Back up your data

Alert rules live in the SigNoz Metastore (SQLite or Postgres) and are rewritten to the new schema when the server starts.
Back up the Metastore before upgrading.
If you are more than one release behind, check the Upgrade Path Tool for required stops before you move to v0.150.0.
The required stop before v0.150.0 is v0.143.0, which also needs a collector upgrade.

Step 2: Upgrade SigNoz

Upgrade foundryctl, then re-apply your existing casting.yaml.

cast applies the regenerated files but does not pull images. If your casting uses floating tags such as latest, refresh signoz/signoz on the host first so the restarted container runs v0.150.0. Otherwise SigNoz stays on the old image.

curl -fsSL https://signoz.io/foundry.sh | bash
foundryctl cast -f casting.yaml

If your casting.yaml pins image versions, bump SigNoz to v0.150.0 yourself.

Foundry does not download binaries. Replace the SigNoz binary at the path your casting states, then cast:

ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
 
# default; your casting may set foundry.signoz.io/signoz-binary-path
# extract the full SigNoz tarball: bin/, web/, templates/ and conf/ have to stay together
curl -fsSL "https://github.com/SigNoz/signoz/releases/download/v0.150.0/signoz_linux_${ARCH}.tar.gz" \
  | sudo tar -xz --strip-components=1 -C /opt/signoz
 
sudo foundryctl cast -f casting.yaml

cast runs the migrations and reloads the units, but does not restart running services. Restart SigNoz so it picks up the new binary:

sudo systemctl restart <name>-signoz.service

<name> is metadata.name in your casting.yaml, which is signoz in the shipped example.

Update the chart and upgrade. Replace <namespace> and <release-name> with your own values, and <your-values.yaml> with your values file:

helm repo update
helm -n <namespace> upgrade <release-name> signoz/signoz -f <your-values.yaml>

helm upgrade takes the newest chart. To pin a chart version, add --version <chart-version>.

Step 3: Verify the upgrade

Pods and containers are healthy (kubectl get pods -n <namespace>, docker compose ps, or systemctl status 'signoz-*').
SigNoz reports v0.150.0 under Settings.
Open Alerts and confirm your existing rules are listed.

What changes after migration

Automatic conversion. Existing v1 rules are rewritten to v2alpha1 when SigNoz starts after the upgrade.
Re-notification is stored on each rule. In v1, every rule re-notified every 4 hours while firing. Migrated rules come back with notificationSettings filled in from their v1 values, so they keep re-notifying every 4 hours while firing, and on no data when alertOnAbsent was set.
Channels are listed on each rule. In v1, an empty channel list meant every channel in the organization. A migrated rule that had no channels comes back with an empty channels list: add channels to it, or set it to use routing policies.
API reads return the new shape. A rule fetched by id comes back in v2alpha1, including rules created under v1, and the list returns a summary of each rule. To find where each v1 field moved, see the field mapping.

Migrate API scripts to the v2 rules APIs

The v1 rules endpoints and the GET /api/v2/rules list are removed in v0.150.0. Move your scripts to the replacements before you upgrade:

Removed	Replacement
`GET /api/v1/rules`	`GET /api/v3/rules`
`GET /api/v2/rules`	`GET /api/v3/rules`
`GET /api/v1/rules/{id}`	`GET /api/v2/rules/{id}`
`POST /api/v1/rules`	`POST /api/v2/rules`
`PUT /api/v1/rules/{id}`	`PUT /api/v2/rules/{id}`
`PATCH /api/v1/rules/{id}`	`PATCH /api/v2/rules/{id}`
`DELETE /api/v1/rules/{id}`	`DELETE /api/v2/rules/{id}`
`POST /api/v1/testRule`	`POST /api/v2/rules/test`

After the upgrade:

Calls to /api/v1/rules and /api/v1/testRule return 404.
GET /api/v2/rules returns 405.
A create, replace, or test body sent to the v2 endpoints without "schemaVersion": "v2alpha1" returns 400. The message is alert rule is not valid, and the reason is schemaVersion: unsupported value ""; must be "v2alpha1".

GET /api/v3/rules returns a paginated summary of each rule. Fetch the full definition from GET /api/v2/rules/{id}.

For the field mapping, the behaviors to carry over, a before-and-after example, and a checklist for each script, see Migrate Alert Rules from the v1 Schema to v2alpha1.

Upgrade the SigNoz Operator

SigNoz v0.150.0 needs SigNoz Operator v0.0.5 or newer, because older operator versions look up alert rules through the removed rules list. For how the operator is installed, see the SigNoz Operator docs.

Migrate Terraform-managed alerts

Users on the signoz_rule resource, Terraform provider v0.1.0 and later, need no changes. It already uses the v2 endpoints and the v2alpha1 schema.

Configurations still on the older signoz_alert resource have to move to signoz_rule. Follow the provider's migrate signoz_alert to signoz_rule guide.

For general usage, see the Terraform provider guide.