Upgrading NAuth

NAuth is below 1.0.0, so breaking changes increase the minor version. This guide records migration steps for breaking releases.

Upgrade paths

For an upgrade that crosses multiple breaking releases, apply every matching section in ascending target-version order. The sections below are listed newest first for discoverability. Each section states whether an intermediate NAuth version is required; historical instructions may be silent, and that silence does not guarantee a direct upgrade path.

v0.7.x → v0.8.0

When jetStreamEnabled is omitted, an Account with no positive or unlimited memory or disk storage allowance will now have JetStream disabled. This includes Accounts that set stream or consumer limits but rely on the previous implicit unlimited memory and disk storage defaults. Explicit jetStreamEnabled: true still defaults omitted quotas to unlimited, as described in ADR-7.

Before upgrading, identify Accounts that currently rely on the implicit unlimited storage defaults to enable JetStream. Set jetStreamEnabled: true to retain unlimited quota behavior, or specify explicit storage limits in jetStreamLimits:

spec:
  jetStreamEnabled: true

Apply the Account changes while still running v0.7.x and let them reconcile before upgrading. Accounts with positive or unlimited memory or disk storage limits remain enabled when jetStreamEnabled is omitted. Accounts that intentionally keep JetStream disabled need no change.

jetStreamEnabled is already part of the v0.7.x Account API, so no CRD update or intermediate NAuth release is required for this migration.

v0.6.x → v0.7.0

The implicit NATS configuration path using NATS_URL and label-based Secret lookup was removed. Move the URL into NatsCluster.spec.url (or spec.urlFrom) and reference the existing credential Secrets through spec.operatorSigningKeySecretRef and spec.systemAccountUserCredsSecretRef.

For a single-cluster deployment, set the operator’s NATS_CLUSTER_REF to <namespace>/<name>. For Account-specific clusters, set spec.natsClusterRef on each Account. When an operator-level reference should be a default that Accounts can override, set NATS_CLUSTER_REF_OPTIONAL=true.

The Getting Started guide shows a complete NatsCluster and both reference patterns. The published v0.7.0 migration instructions do not state whether an intermediate NAuth version is required.

v0.4.x → v0.5.0

NAuth no longer populates User.status.claims.accountName; the field is deprecated. If a client needs the Account name associated with a User, read User.spec.accountName. No CRD data migration is required, and the field remains in the API for compatibility.

The published v0.5.0 migration instructions do not state whether an intermediate NAuth version is required.

v0.1.x → v0.2.0

Before upgrading to v0.2.0:

1. Add the nauth.io/secret-type label to the operator signing-key Secret and system-account credentials Secret. NAuth finds these Secrets by label in this release. Keep the secret data under the default key.

   metadata:
     labels:
       nauth.io/secret-type: operator-sign

   metadata:
     labels:
       nauth.io/secret-type: system-account-user-creds

   NAuth-managed Account and User Secrets are labeled during reconciliation; they do not need a manual label migration.

2. For CRDs managed by the nauth Helm release, add Helm ownership metadata to the existing accounts.nauth.io and users.nauth.io CRDs before upgrading. Use the actual Helm release name and namespace:

   metadata:
     annotations:
       meta.helm.sh/release-name: REPLACE_WITH_HELM_RELEASE_NAME
       meta.helm.sh/release-namespace: REPLACE_WITH_HELM_RELEASE_NAMESPACE
     labels:
       app.kubernetes.io/managed-by: Helm

The published v0.2.0 migration instructions do not state whether an intermediate NAuth version is required.