Environment variables | NVIDIA AIStore

Introduction

Generally, AIStore (AIS) configuration comprises several sources:

cluster (a.k.a. global) and node (or, local) configurations, the latter further “splitting” into local config per se and local overrides of the inherited cluster config;
aisnode command line;
environment variables (this document);
finally, assorted low-level constants (also referred to as “hardcoded defaults”) that almost never have to change.

This enumeration does not include buckets (and their respective configurations). In AIS, buckets inherit a part of the cluster config that can be further changed on a per-bucket basis - either at creation time or at any later time, etc.

In effect, cluster configuration contains cluster-wide defaults for all AIS buckets, current and future.

For additional references, please see the last section in this document. The rest of it, though, describes only and exclusively environment variables - item 3 above.

Rules

First though, two common rules that, in fact, apply across the board:

in AIS, all environment settings are optional
if specified, environment variable will always override:
- the corresponding default constant (if exists), and/or
- persistent configuration (again, if the latter exists).

For example:

in AIS cluster, each node has an ID, which is persistent, replicated and unique; at node startup its ID can be overridden via AIS_DAEMON_ID environment (see below);
environment AIS_READ_HEADER_TIMEOUT, if specified, will be used instead of the apc.ReadHeaderTimeout constant in the code;
AIS_USE_HTTPS takes precedence over net.http.use_https value from the cluster configuration,

and so on.

The remainder of this text groups AIS environment variables by their respective usages, and is structured as follows:

separately, there’s authentication server config:

AuthN

and finally:

References

Build Tags

Different AIS builds may (or may not) require different environment vars. For complete list of supported build tags, please see conditional linkage. Here’s a very brief and non-exhaustive intro:

1 # 1) no build tags, no debug
2 MODE="" make node
3 
4 # 2) no build tags, debug
5 MODE="debug" make node
6 
7 # 3) cloud backends, no debug
8 AIS_BACKEND_PROVIDERS="aws azure gcp" MODE="" make node
9 
10 # 4) cloud backends, debug
11 AIS_BACKEND_PROVIDERS="aws azure gcp" MODE="debug" make node
12 
13 # 5) cloud backends, debug
14 TAGS="aws azure gcp debug" make node
15 
16 # 6) debug, nethttp (note that fasthttp is used by default)
17 TAGS="nethttp debug" make node

Primary

Background: in a running AIS cluster, at any point in time there’s a single primary gateway that may also be administratively selected, elected, reelected. Hence, two related variables:

name	comment
`AIS_PRIMARY_EP`	at startup, tells one of the starting-up proxies to assume the primary role iff `AIS_PRIMARY_EP` specifies one of the proxy’s listening endpoints; e.g. usage:

$ $ AIS_PRIMARY_EP=https://ais-proxy-0.svc.cluster.local:51082
$ # or (same):
$ $ AIS_PRIMARY_EP=ais-proxy-0.svc.cluster.local:51082

Network

name	comment
`AIS_ENDPOINT`	http or https address of an arbitrary AIS gateway (proxy) in a given cluster
`AIS_CLUSTER_CIDR`	ais cluster CIDR; often can be understood/approximated as the cluster’s subnet; when specified will be used to differentiate between clients within the same subnet vs outside
`AIS_READ_HEADER_TIMEOUT`	maximum time to receive request headers; e.g. usage: ‘export AIS_READ_HEADER_TIMEOUT=10s’, and note that ‘0s’ (zero) is also permitted

Node

name	comment
`AIS_DAEMON_ID`	ais node ID
`AIS_HOST_IP`	node’s public IPv4
`AIS_HOST_PORT`	node’s public TCP port (and note the corresponding local config: “host_net.port”)

See also:

three logical networks

HTTPS

At first it may sound slightly confusing, but HTTP-wise AIS is both a client and a server.

All nodes in a cluster talk to each other using HTTP (or HTTPS) - the fact that inevitably implies a certain client-side configuration (and configurability).

In particular, AIS server-side HTTPS environment includes:

name	comment
`AIS_USE_HTTPS`	tells AIS to run HTTPS transport (both public and intra-cluster networks)
`AIS_SERVER_CRT`	TLS certificate (pathname). Required when `AIS_USE_HTTPS` is `true`
`AIS_SERVER_KEY`	private key (pathname) for the certificate above.
`AIS_SKIP_VERIFY_CRT`	when true will skip X.509 cert verification (usually enabled to circumvent limitations of self-signed certs)

E.g., for local playground, typical usage starts from running export AIS_USE_HTTPS=true followed by one of the usual make deploy combinations.

In addition, all embedded (intra-cluster) clients in a cluster utilize the following environment:

name	comment
`AIS_CRT`	TLS certificate pathname (this and the rest variables in the table are ignored when AIS is AIS_USE_HTTPS==false
`AIS_CRT_KEY`	pathname that contains X.509 certificate private key
`AIS_CLIENT_CA`	certificate authority that authorized (signed) the certificate
`AIS_SKIP_VERIFY_CRT`	when true will skip X.509 cert verification (usually enabled to circumvent limitations of self-signed certs)

Further references

Local Playground

This group of environment variables is used exclusively by development scripts and integration tests.

name	comment
`NUM_TARGET`	number of targets in a test cluster
`NUM_PROXY`	number of proxies (gateways) in a test cluster
`NUM_CHUNKS`	when greater than zero, specifies the number of chunks each new PUT operation will produce
`SIGN_HMAC`	when “true”, enables HMAC signing and validation of all HTTP redirects
`RAND_NS`	when “true”, generate buckets with random namespaces, e.g.: `ais://#ns123/bucket1`, `s3://#ns456/bucket2`, etc.

See also:

Kubernetes

name	comment
`MY_POD` and `HOSTNAME`	Kubernetes POD name. `MY_POD` is used in production; `HOSTNAME`, on the other hand, is usually considered a Kubernetes default
`MY_NODE`	Kubernetes node name
`K8S_NS` and `POD_NAMESPACE`	Kubernetes namespace. `K8S_NS` is used in production, while `POD_NAMESPACE` - development

Kubernetes POD name is also reported via ais show cluster CLI - when it is a Kubernetes deployment, e.g.:

1 $ ais show cluster t[fXbarEnn]
2 TARGET         MEM USED(%)   MEM AVAIL     CAP USED(%)   CAP AVAIL     LOAD AVERAGE    REBALANCE   UPTIME        K8s POD         STATUS  VERSION        BUILD TIME
3 t[fXbarEnn]    3.08%         367.66GiB     51%           8.414TiB      [0.9 1.1 1.3]   -           1852h19m40s   ais-target-26   online  3.20.92bc0c1   2023-09-18T19:12:52+0000

See related:

AIS K8s Operator: environment variables

AWS S3

NOTE: for the most recent updates, please refer to the source.

name	comment
`S3_ENDPOINT`	global S3 endpoint to be used instead of `s3.amazonaws.com`
`AWS_REGION`	default bucket region; can be set to override the global default ‘us-east-1’ location
`AWS_PROFILE`	global AWS profile with alternative (as far as the [default]) credentials and/or AWS region
`AIS_S3_CONFIG_DIR`	directory containing any number of AWS `config` and `credentials` files to be loaded by the AIS S3 client

Package: backend

AIS natively supports 3 (three) Cloud storages.

The corresponding environment “belongs” to the internal backend package and includes:

name	comment
`S3_ENDPOINT`, `AWS_PROFILE`, `AWS_REGION`, `AIS_S3_CONFIG_DIR`	see previous section
`GOOGLE_CLOUD_PROJECT`, `GOOGLE_APPLICATION_CREDENTIALS`	GCP account with permissions to access Google Cloud Storage buckets
`AZURE_STORAGE_ACCOUNT`, `AZURE_STORAGE_KEY`	Azure account with permissions to access Blob Storage containers
`AIS_AZURE_URL`	Azure endpoint, e.g. `http://<account_name>.blob.core.windows.net`
`OCI_TENANCY_OCID`, `OCI_USER_OCID`, `OCI_REGION`, `OCI_FINGERPRINT`, `OCI_PRIVATE_KEY`, `OCI_COMPARTMENT_OCID`	OCI account with permissions to access Object Storage buckets and compartments

Notice in the table above that the variables S3_ENDPOINT and AWS_PROFILE are designated as global: cluster-wide.

The implication: it is possible to override one or both of them on a per-bucket basis:

configuring buckets with alternative S3 andpoint and/or credentials

AIS as S3 storage

Environment S3_ENDPOINT is important, and may also be a source of minor confusion. The reason: AIS itself provides S3 compatible interface.

For instance, on the client side you could say something like:

1 export S3_ENDPOINT=https://10.0.4.53:51080/s3

and then run existing S3 applications against an AIS cluster at 10.0.4.53 - with no changes (to the application).

Moreover, configure AIS to handle S3 requests at its ”/” root:

1 $ ais config cluster features S3-API-via-Root

and re-specify S3_ENDPOINT environment to make it looking slightly more conventional:

1 export S3_ENDPOINT=https://10.0.4.53:51080

To recap:

use S3_ENDPOINT to override the s3.amazonaws.com default;
specify AWS_PROFILE to use a non-default (named) AWS profile

and separately:

you could run existing S3 apps (with no changes) against AIS by using S3_ENDPOINT on the client side

See also:

Package: stats

AIStore is a fully compliant Prometheus exporter.

StatsD was deprecated in v3.28 (Spring 2025) and completely removed in v4.0 (September 2025).

Package: memsys

name	comment
`AIS_MINMEM_FREE`	for details, see Memory Manager, Slab Allocator (MMSA)
`AIS_MINMEM_PCT_TOTAL`	same as above and, specifically, the section “Minimum Available Memory”
`AIS_MINMEM_PCT_FREE`	(ditto)

Package: transport

name	comment
`AIS_STREAM_DRY_RUN`	read and immediately discard all read data (can be used to evaluate client-side throughput)

AuthN

AIStore Authentication Server (AuthN) provides secure access control to AIStore via JSON Web Tokens.

A single AuthN service can support multiple AIS clusters, with no fixed limit.

The following variables can be used to configure deployment scripts and validation of tokens in AIStore:

Variable	Default Value	Description
`AIS_AUTHN_ENABLED`	`false`	Enable AuthN server and token-based access in AIStore proxy (`true` to enable)
`AIS_AUTHN_DEPLOY`	`false`	Deploy AuthN alongside AIStore in deployment scripts (`false` to use existing service)
`AIS_AUTHN_SECRET_KEY`	`""`	HMAC secret key used to sign tokens
`AIS_AUTHN_PUBLIC_KEY`	`""`	RSA public key (PEM or base64 DER) for verifying tokens signed by AuthN
`AIS_AUTHN_ALLOWED_ISS`	`""`	Comma-separated list of allowed OIDC issuer URLs for token validation (deploy scripts)

For configuring the AuthN service and clients, see the AuthN Environment Variables.

When AuthN is disabled (i.e., not used), the respective ais config command will show something like:

1 $ ais config cluster auth
2 PROPERTY                         VALUE
3 auth.signature.key               **********
4 auth.signature.method            hmac
5 auth.required_claims.aud         []
6 auth.oidc.issuer_ca_bundle
7 auth.oidc.allowed_iss            []
8 auth.cluster_key.enabled         false
9 auth.cluster_key.ttl             0s
10 auth.cluster_key.nonce_window    1m
11 auth.cluster_key.rotation_grace  1m
12 auth.enabled                     false ## <<<< disabled

Notice: this command is executed on the AIStore cluster, not AuthN.

See also:

References

env package README
system filenames
cluster configuration
local playground: cluster and node configuration
ais config command
performance tunables
feature flags

Introduction

Rules

Table of Contents

Build Tags

Primary

Network

Node

HTTPS

Further references

Local Playground

Kubernetes

AWS S3

Package: backend

AIS as S3 storage

Package: stats

Package: memsys

Package: transport

AuthN

References