Skip to main content

Overview

This process is not for production. Use it only for testing or development.
This guide walks you through installing Arize AX on a single host (one VM) using k3s. You will install k3s and Helm, point Arize AX at an S3-compatible object store, then deploy Arize AX from the distribution. Throughout this section, distribution archive means the Arize AX release tarball you download with your JWT (Helm chart, arize.sh, examples, and offline HTML docs). Follow the sections in order: VM -> k3s/Helm -> object storage -> distribution -> install -> ingress -> validate.

Prerequisites

Before starting, have the following ready:
  • Arize AX distribution access — JWT token for downloading the distribution from Arize AI
  • Passwords and secrets — You will choose a Postgres password and encryption key, and collect S3-compatible object storage credentials (all secret-bearing values base64-encoded in values.yaml)
  • Organization name — Name of your organization or company (for values.yaml)
  • App URL — The URL you will use to reach the Arize AX UI (e.g. https://arize-app.yourdomain.com). This can be a hostname you map to a private IP (see Step 8) if the VM has no public address.
  • Network access to the VM — If the VM only has a private IP (for example 10.x.x.x, 172.16.x.x, or 192.168.x.x), your browser, SDKs, and any clients must run on a host that can reach that address (same VPC or subnet, site-to-site VPN, or client VPN into the cloud network). You do not need a public IP for this guide.

Step 1: Create the virtual machine

Create a single VM with these specifications:

Step 2: Install k3s

SSH into the machine, then run:
Verify: Run kubectl get nodes. You should see your node with status Ready and role control-plane, for example:

Step 3: Install Helm

Verify: Run helm version. You should see JSON output with BuildInfo for your Helm installation.

Step 4: Prepare object storage

Arize AX needs S3-compatible object storage for Gazette and ArizeDB data. For a single-host development install, use the same object storage endpoint your platform team supports for testing, or a short-lived S3-compatible endpoint dedicated to this install. Create or collect:
  • One bucket for Gazette data, for example gazette-bucket.
  • One bucket for ArizeDB data, for example adb-bucket.
  • An endpoint URL reachable from the k3s node.
  • An access key and secret key with read/write access to both buckets.
You will put these values in values.yaml in Step 6.

Step 5: Retrieve the Arize AX distribution

Create a release folder, download the distribution, and extract it. Replace <your JWT token> with your actual JWT.
Stay in the release directory you created (arize-release-$VERSION). After extraction, it should contain arize.sh, arize-operator-chart.tgz, docs/, and examples/.

Step 6: Create values.yaml

From the extracted release directory that contains arize.sh, create values.yaml by editing the placeholders below and pasting the result into your terminal. All values marked “(base64 encoded)” must be base64-encoded.
  • hubJwt: Your runtime registry JWT (base64)
  • postgresPassword: A password you choose (base64)
  • cephS3AccessKeyId: S3-compatible object storage access key ID (base64)
  • cephS3SecretAccessKey: S3-compatible object storage secret access key (base64)
  • cipherKey: An encryption key you generate (base64)
  • appBaseUrl: The URL where you will access the Arize AX UI

Step 7: Install Arize AX

From the same release directory, run:
This installs the Arize AX Helm chart and deploys Arize AX on the single host. When the script completes successfully, Arize AX is now up and running in your k3s cluster. You can run kubectl get pods -n arize to see all pods in a running state.

Step 8: Configure ingress

Ingress exposes the Arize AX UI over HTTPS. You can use any certificate; this step uses a self-signed certificate for a low-effort setup. You can choose any domain (e.g. arize-app.example.local) — no real DNS record is required because you will use /etc/hosts to point the hostname to your VM. Private IP only: If the VM has no public IP, use the VM’s private address in /etc/hosts on every client that should open the UI or send data (your laptop on VPN, a jump host, or a build agent in the same VPC). The certificate and ingress hostnames stay the same; only the IP you map must be reachable from that client.

8a. Generate a self-signed certificate

From the home directory, generate the cert. Replace <your domain> with the domain you want to use (e.g. example.local).

8b. Get base64 values for the ingress manifests

You will paste these values into the ingress YAML in the next step. Run:
Copy each command’s output and keep it handy.

8c. Create and apply the ingress manifests

Create an ingress directory and an ingress.yaml file. In the manifest below, replace:
  • <your domain> — The same domain you used in the certificate (e.g. example.local)
  • <your value for tls.crt> — The full output of base64 -w 0 tls.crt
  • <your value for tls.key> — The full output of base64 -w 0 tls.key
Then apply the file.

8d. Point the hostname to your VM and open the UI

On each machine where you want to use the Arize AX UI (your laptop or another host), add a line to /etc/hosts so arize-app.<your domain> resolves to the VM’s IP. This replaces a DNS record for testing.
  1. Edit hosts (e.g. sudo vi /etc/hosts or sudo nano /etc/hosts).
  2. Add a line: <VM IP address> arize-app.<your domain>
    Use the same domain as in the certificate and ingress.
Which IP to use
  • Public IP: If your cloud VM has a public address, use that IP in /etc/hosts from any client that can reach it (subject to your security group or firewall rules).
  • Private IP only: If the VM has only a private IP, use that private address. The client must be on a network that can route to it (for example same VPC, peered network, or connected VPN). If you reach the VM only via SSH through a bastion, you still need a path for HTTPS (port 443) from the browser/SDK machine to the Arize AX node—either run the browser on a host inside the VPC, use VPN, or forward ports with ssh -L and point localhost in /etc/hosts to match your tunnel setup.
Example:
Verify: In your browser, go to https://arize-app.<your domain>. You should see the Arize AX login page. Accept the self-signed certificate warning if prompted, then sign in with your initial admin credentials. You can now use Arize AX.

Step 9: Validate deployment

The distribution includes example scripts under examples/sdk. Use them to confirm the cluster can receive traces.
  • Certificate: The deployment uses a self-signed cert. Have the certificate (e.g. tls.crt) available on the machine where you run the script, or configure the script to skip TLS verification if it supports that.
  • Network: Run the script from a host that can reach the VM’s reachable address for HTTPS (public IP or private IP). If the VM uses only a private IP, run the SDK from a host on the same VPC/VPN or with routing to that host, and use the same hostname in /etc/hosts (or DNS) as in appBaseUrl.
From the extracted release directory, run the HTTP trace sample:
If the script runs without errors and traces appear in the Arize AX UI, the deployment is working correctly.