Deployment Modes

Local experimentation

Recommended backend:

in_memory for quick local request/validation testing.

Characteristics:

No persistence: data is lost on process restart.
Single-process state only.
Not suitable for horizontal scaling or replica failover.
Supports replay and watch in-process, limited by local memory retention.
For local JetStream testing, see Installation: Local JetStream.
For a quick end-to-end behavior check, see Getting Started: Run the Smoke Test.

Production-like / persistent mode

Recommended backend:

jetstream

Characteristics:

Durable message storage.
Retention and size limits.
Replica support (requires clustered NATS setup).
Supports replay and live streaming workflows.

For Kubernetes, use the Aviso Helm chart.

Selection guideline

Need persistence/replay/streaming robustness: use jetstream.
Need fastest setup for local functional checks only: use in_memory (node-local replay/watch).

The server provides the application and its configuration format. The chart defines Kubernetes resources and supplies default values. Keep your own deployment values separately; no additional configuration repository is required.

Prepare the chart

You need a Kubernetes cluster, kubectl, and Helm with OCI support. The chart and its dependencies, as well as the server image, must be accessible from your environment. The default image and one chart dependency are hosted at eccr.ecmwf.int; check registry access before installing. Helm registry authentication does not supply image-pull credentials to Kubernetes nodes.

To install from a chart checkout:

git clone https://github.com/ecmwf/aviso-chart.git
helm repo add nats https://nats-io.github.io/k8s/helm/charts/
helm dependency build ./aviso-chart

Select the chart revision you intend to deploy before building dependencies. helm dependency build uses the chart’s lockfile. Dependencies must be downloadable even when their components are disabled in your values.

Start with a development deployment

This example runs one Aviso replica and one NATS server with JetStream. Your cluster needs a default StorageClass that can provision a persistent volume. Create values-demo.yaml:

fullnameOverride: aviso
replicaCount: 1

nats:
  enabled: true
  config:
    jetstream:
      enabled: true
      fileStore:
        enabled: true
        pvc:
          enabled: true
          size: 10Gi

extraEnv:
  - name: AVISOSERVER_CONFIG_FILE
    value: /etc/aviso_server/config.yaml

config:
  notification_backend:
    kind: jetstream
    jetstream:
      nats_url: nats://aviso-nats:4222
      storage_type: file
      replicas: 1

The NATS URL assumes the Helm release name aviso, used in the commands below. Change the URL if you choose another release name.

NATS stores notifications on the persistent volume, so they can survive pod restarts while that volume is retained. This uses chart defaults for the remaining settings, with no authentication or ingress. It is a development setup, not a highly available production deployment.

Validate and inspect the rendered resources before installing:

helm lint ./aviso-chart -f values-demo.yaml
helm template aviso ./aviso-chart --namespace aviso -f values-demo.yaml

helm upgrade --install aviso ./aviso-chart \
  --namespace aviso \
  --create-namespace \
  -f values-demo.yaml \
  --wait --timeout 5m

The fullnameOverride setting names the Aviso Service and Deployment aviso. For a temporary local check, forward the Service port to your machine:

kubectl -n aviso port-forward service/aviso 8000:8000

Keep this command running while testing. It exposes Aviso on your machine’s loopback interface and stops forwarding when you press Ctrl+C. It does not provide a shared endpoint for other users.

In another terminal, check liveness and backend-connection readiness:

curl --fail http://127.0.0.1:8000/health
curl --fail http://127.0.0.1:8000/ready

Applications inside the cluster can use the Kubernetes Service directly. For access from outside the cluster, configure the chart’s ingress settings with your hostname and TLS configuration, or use your platform’s supported exposure method. An Ingress requires an ingress controller; creating the resource alone does not make the service reachable. Configure authentication before exposing Aviso, and ensure proxy buffering and timeouts support long-lived SSE connections.

Understand the configuration layers

Helm merges chart defaults with your -f files in command-line order. Later files take precedence. Maps merge, but lists such as extraEnv are replaced as a whole. You can use one values file or layer several; their names and organization are yours to choose.

Top-level chart values configure Kubernetes resources. The config: map contains server settings and becomes a ConfigMap mounted at /etc/aviso_server/config.yaml.

The server then applies its own configuration loading rules. Without an explicit file selector, configuration included in the image can be merged with the mounted file. Omitting a setting from an overlay does not remove it from an earlier source.

The AVISOSERVER_CONFIG_FILE setting in the example selects the mounted file as the only file source. Field-level AVISOSERVER_* environment variables still override its settings. This does not remove Helm’s chart defaults.

Use Helm values for settings that also affect rendered resources, such as the application port. Changing the server port only through an environment variable does not update the chart’s container ports or probes.

Supply credentials through Secrets

Do not put credentials in config:: it is stored in a ConfigMap, not a Secret. Provision Secrets separately and reference their keys through extraEnv. For example, a deployment using token-authenticated NATS could use this values fragment:

extraEnv:
  - name: AVISOSERVER_CONFIG_FILE
    value: /etc/aviso_server/config.yaml
  - name: AVISOSERVER_NOTIFICATION_BACKEND__JETSTREAM__TOKEN
    valueFrom:
      secretKeyRef:
        name: aviso-nats-credentials
        key: token

Create that Secret in the release namespace before installation. This fragment supplies credentials only; it does not select or deploy JetStream. Keep any other required extraEnv entries in the same list.

Prepare for production

The example configures both sides: nats.enabled deploys NATS, while config.notification_backend tells Aviso how to connect to it. Neither setting automatically configures the other. To use an existing NATS deployment, disable the dependency and supply its URL and credentials.

Choose retention and capacity limits for your notification schemas through storage_policy. Schema settings override backend defaults per field. The demo intentionally leaves retention unspecified rather than choosing one age limit for every stream. Other limits still apply, including keeping only the latest notification per subject by default. See the JetStream backend guide for storage policy details.

Aviso pod replicas and JetStream stream replicas are separate settings. A single NATS server with persistent storage is not a highly available cluster. Before exposing the service, also configure authentication and ingress/TLS for your environment.

Apply configuration changes

Use helm upgrade with your chosen values files. The chart includes a checksum of the rendered ConfigMap in the pod template, so configuration changes through Helm trigger a rollout. The server reads configuration at startup; this is not live reload.

Editing the ConfigMap directly does not update that checksum. The mounted file also uses subPath, so existing containers do not receive projected ConfigMap updates. Keep configuration changes in your Helm values.

Updating a referenced Secret’s contents does not automatically restart pods. After rotating credentials, restart the Deployment so its environment variables are loaded again:

kubectl -n aviso rollout restart deployment/aviso
kubectl -n aviso rollout status deployment/aviso

Aviso Server Documentation