Environment Variables Reference

Overview

AosCloud microservices are configured through environment variables that control secrets management, database connections, messaging, and inter-service communication. In AWS deployments, these variables are injected via the Helm chart rather than being read directly from .env files — the .env files in the source repository define the development-mode defaults and variable names, while the Helm values.yaml maps them to AWS Secrets Manager paths at deployment time.

This page documents every environment variable used by each microservice, its purpose, valid format, and injection source. It does not include actual secret values — only parameter names and format specifications.

Prerequisites

Before reading this page, review:

• Kubernetes Deployment Architecture — for pod-to-service mapping and IRSA context
• Helm Values Reference — for how values.yaml controls variable injection

Injection Architecture

All AosCloud services use a common secrets resolution pattern:

1. SecretManagerType determines which backend retrieves secrets at runtime
2. VaultAddr* variables specify the secret path prefix where configuration and credentials are stored
3. At startup, each service reads its configuration from the path pointed to by these variables

Injection Sources

Source	Description	Example
Helm values (env block)	Set directly in values.yaml per-service env array	SecretManagerType, VaultAddrCfg, PROJECT_VERSION
AWS Secrets Manager	Retrieved at runtime by the application using the VaultAddr* path	Database passwords, TLS certificates, API keys
Kubernetes Secret (envFromSecret)	Injected from a K8s Secret created by the RabbitMQ operator or Helm	RMQ_HOSTNAME, RMQ_USERNAME, RMQ_PASSWORD
Static configuration	Hardcoded in Helm templates or derived from global values	WS_EXTERNAL_HOSTNAME, WS_EXTERNAL_PORT

AWS Secret Path Naming Convention

In AWS deployments, secret paths follow the pattern ${AWS_BASE_NAME}-<suffix>:

Path Suffix	Content	Used By
appcfg	Application configuration (endpoints, feature flags)	API, Auth, WebSocket API, Message Handler, Unit Message Handler
appsec	Application secrets (API keys, tokens)	API, Auth, WebSocket API, Message Handler, Unit Message Handler
dbcfg	Database configuration (hostnames, ports)	API, Auth, Message Handler, Unit Message Handler, Data Migration
dbsec	Database secrets (credentials)	API, Auth, Message Handler, Unit Message Handler, Data Migration
data-services	Data services configuration	Alert Handler, Unit Monitoring
mhcfg	Message handler configuration	Message Handler, Unit Message Handler, Service Discovery
mhsec	Message handler secrets	Message Handler, Unit Message Handler, Service Discovery
sdcfg	Service discovery configuration	Service Discovery
sdsec	Service discovery secrets	Service Discovery
taskcfg	Task/queue management configuration	Queue Management
tasksec	Task/queue management secrets	Queue Management
ingress	Ingress/TLS certificates and keys	Istio gateway secrets job
landing	Landing page configuration	Landing Backend
base	Base infrastructure secrets (PostgreSQL admin, InfluxDB)	PostgreSQL init, InfluxDB

Environment Variables by Microservice

API Service

The API service provides the main REST interface for AosCloud operations.

Variable	Purpose	Format	Default	Injection Source
SecretManagerType	Secrets backend selector	AWSSecretManager or HashiCorp	AWSSecretManager	Helm env block
VaultAddrCfg	Path to application configuration secrets	${AWS_BASE_NAME}-appcfg	—	Helm env block
VaultAddrSec	Path to application credential secrets	${AWS_BASE_NAME}-appsec	—	Helm env block
VaultAddrDbCfg	Path to database configuration	${AWS_BASE_NAME}-dbcfg	—	Helm env block
VaultAddrDbSec	Path to database credentials	${AWS_BASE_NAME}-dbsec	—	Helm env block
PROJECT_VERSION	Deployed application version string	Semantic version	Current release	Helm env block
DEVELOPMENT_MODE	Enables development-only features	True / False	Not set in production	Dev .env only

Service account: ${AWS_BASE_NAME}-app

Auth Service

The Auth service handles authentication, authorization, and user management.

Variable	Purpose	Format	Default	Injection Source
SecretManagerType	Secrets backend selector	AWSSecretManager or HashiCorp	AWSSecretManager	Helm env block
VaultAddrCfg	Path to application configuration secrets	${AWS_BASE_NAME}-appcfg	—	Helm env block
VaultAddrSec	Path to application credential secrets	${AWS_BASE_NAME}-appsec	—	Helm env block
VaultAddrDbCfg	Path to database configuration	${AWS_BASE_NAME}-dbcfg	—	Helm env block
VaultAddrDbSec	Path to database credentials	${AWS_BASE_NAME}-dbsec	—	Helm env block
PROJECT_VERSION	Deployed application version string	Semantic version	Current release	Helm env block
POSTGRES_HOST	PostgreSQL hostname (dev override)	Hostname string	—	Dev .env only

Service account: ${AWS_BASE_NAME}-app

Backend (App) Service

The Backend service handles core business logic, Django-based management, and background task processing.

Variable	Purpose	Format	Default	Injection Source
SecretManagerType	Secrets backend selector	AWSSecretManager or HashiCorp	AWSSecretManager	Helm env block
VaultAddrCfg	Path to application configuration secrets	${AWS_BASE_NAME}-appcfg	—	Helm env block
VaultAddrSec	Path to application credential secrets	${AWS_BASE_NAME}-appsec	—	Helm env block
VaultAddrDbCfg	Path to database configuration	${AWS_BASE_NAME}-dbcfg	—	Helm env block
VaultAddrDbSec	Path to database credentials	${AWS_BASE_NAME}-dbsec	—	Helm env block
PROJECT_VERSION	Deployed application version string	Semantic version	Current release	Helm env block

The Backend also has a task runner variant (bg-tasks) and scheduler variant (bg-scheduler) that share the same environment variables but run different commands.

Service account: ${AWS_BASE_NAME}-app

Alert Handler

The Alert Handler processes alert events and stores them in DocumentDB (MongoDB-compatible).

Variable	Purpose	Format	Default	Injection Source
SecretManagerType	Secrets backend selector	AWSSecretManager or HashiCorp	AWSSecretManager	Helm env block
VaultAddrCfg	Path to data services configuration	${AWS_BASE_NAME}-data-services	—	Helm env block
SomeSaName	Service account name reference	String	Service account name	Helm env block
PROJECT_VERSION	Deployed application version string	Semantic version	Current release	Helm env block

Service account: ${AWS_BASE_NAME}-data-services

Message Handler

The Message Handler processes messages between the cloud platform and Units, managing software update distribution and status tracking.

Variable	Purpose	Format	Default	Injection Source
SecretManagerType	Secrets backend selector	AWSSecretManager or HashiCorp	AWSSecretManager	Helm env block
VaultAddrMHCfg	Path to message handler configuration	${AWS_BASE_NAME}-mhcfg	—	Helm env block
VaultAddrMHSec	Path to message handler secrets	${AWS_BASE_NAME}-mhsec	—	Helm env block
VaultAddrCfg	Path to application configuration	${AWS_BASE_NAME}-appcfg	—	Helm env block
VaultAddrSec	Path to application secrets	${AWS_BASE_NAME}-appsec	—	Helm env block
VaultAddrDbCfg	Path to database configuration	${AWS_BASE_NAME}-dbcfg	—	Helm env block
VaultAddrDbSec	Path to database credentials	${AWS_BASE_NAME}-dbsec	—	Helm env block

Service account: ${AWS_BASE_NAME}-task

Unit Message Handler

The Unit Message Handler processes messages directly from connected Units via RabbitMQ, handling Unit-initiated communications.

Variable	Purpose	Format	Default	Injection Source
SecretManagerType	Secrets backend selector	AWSSecretManager or HashiCorp	AWSSecretManager	Helm env block
WS_EXTERNAL_HOSTNAME	External WebSocket endpoint hostname	ws.<domain>	ws.{{ .Values.global.domainName }}	Helm env block (static)
WS_EXTERNAL_PORT	External WebSocket endpoint port	Port number string	443	Helm env block (static)
VaultAddrCfg	Path to application configuration	${AWS_BASE_NAME}-appcfg	—	Helm env block
VaultAddrSec	Path to application secrets	${AWS_BASE_NAME}-appsec	—	Helm env block
VaultAddrMHCfg	Path to message handler configuration	${AWS_BASE_NAME}-mhcfg	—	Helm env block
VaultAddrMHSec	Path to message handler secrets	${AWS_BASE_NAME}-mhsec	—	Helm env block
VaultAddrDbCfg	Path to database configuration	${AWS_BASE_NAME}-dbcfg	—	Helm env block
VaultAddrDbSec	Path to database credentials	${AWS_BASE_NAME}-dbsec	—	Helm env block
PROJECT_VERSION	Deployed application version string	Semantic version	Current release	Helm env block
RMQ_HOSTNAME	RabbitMQ server hostname	Hostname string	—	Kubernetes Secret (envFromSecret)
RMQ_PORT	RabbitMQ server port	Port number string	—	Kubernetes Secret (envFromSecret)
RMQ_USERNAME	RabbitMQ authentication username	String	—	Kubernetes Secret (envFromSecret)
RMQ_PASSWORD	RabbitMQ authentication password	String	—	Kubernetes Secret (envFromSecret)

Service account: ${AWS_BASE_NAME}-task

Unit Monitoring

The Unit Monitoring service collects and stores telemetry data from connected Units, writing to InfluxDB.

Variable	Purpose	Format	Default	Injection Source
SecretManagerType	Secrets backend selector	AWSSecretManager or HashiCorp	AWSSecretManager	Helm env block
VaultAddrCfg	Path to data services configuration	${AWS_BASE_NAME}-data-services	—	Helm env block
PROJECT_VERSION	Deployed application version string	Semantic version	Current release	Helm env block

Service account: ${AWS_BASE_NAME}-data-services

WebSocket API

The WebSocket API manages persistent WebSocket connections from Units, providing real-time bidirectional communication.

Variable	Purpose	Format	Default	Injection Source
SecretManagerType	Secrets backend selector	AWSSecretManager or HashiCorp	AWSSecretManager	Helm env block
WS_EXTERNAL_HOSTNAME	External WebSocket endpoint hostname	ws.<domain>	ws.{{ .Values.global.domainName }}	Helm env block (static)
WS_EXTERNAL_PORT	External WebSocket endpoint port	Port number string	443	Helm env block (static)
VaultAddrCfg	Path to application configuration	${AWS_BASE_NAME}-appcfg	—	Helm env block
VaultAddrSec	Path to application secrets	${AWS_BASE_NAME}-appsec	—	Helm env block
PROJECT_VERSION	Deployed application version string	Semantic version	Current release	Helm env block
RMQ_HOSTNAME	RabbitMQ server hostname	Hostname string	—	Kubernetes Secret (envFromSecret)
RMQ_PORT	RabbitMQ server port	Port number string	—	Kubernetes Secret (envFromSecret)
RMQ_USERNAME	RabbitMQ authentication username	String	—	Kubernetes Secret (envFromSecret)
RMQ_PASSWORD	RabbitMQ authentication password	String	—	Kubernetes Secret (envFromSecret)

Service account: ${AWS_BASE_NAME}-app

Service Discovery

The Service Discovery service handles Unit registration and connection assignment within the AosCloud platform.

Variable	Purpose	Format	Default	Injection Source
SecretManagerType	Secrets backend selector	AWSSecretManager or HashiCorp	AWSSecretManager	Helm env block
WS_EXTERNAL_HOSTNAME	External WebSocket endpoint hostname	ws.<domain>	ws.{{ .Values.global.domainName }}	Helm env block (static)
WS_EXTERNAL_PORT	External WebSocket endpoint port	Port number string	443	Helm env block (static)
VaultAddrCfg	Path to service discovery configuration	${AWS_BASE_NAME}-sdcfg	—	Helm env block
VaultAddrSec	Path to service discovery secrets	${AWS_BASE_NAME}-sdsec	—	Helm env block
VaultAddrNosqlCfg	Path to NoSQL (DocumentDB) configuration	${AWS_BASE_NAME}-mhcfg	—	Helm env block
VaultAddrNosqlSec	Path to NoSQL (DocumentDB) secrets	${AWS_BASE_NAME}-mhsec	—	Helm env block
PROJECT_VERSION	Deployed application version string	Semantic version	Current release	Helm env block

Service account: ${AWS_BASE_NAME}-sd

Queue Management (Units Queues Management)

The Queue Management service manages RabbitMQ queues for Unit communication, handling queue lifecycle and monitoring.

Variable	Purpose	Format	Default	Injection Source
SecretManagerType	Secrets backend selector	AWSSecretManager or HashiCorp	AWSSecretManager	Helm env block
VaultAddrCfg	Path to queue management configuration	${AWS_BASE_NAME}-taskcfg	—	Helm env block
VaultAddrSec	Path to queue management secrets	${AWS_BASE_NAME}-tasksec	—	Helm env block
PROJECT_VERSION	Deployed application version string	Semantic version	Current release	Helm env block

Service account: Custom (${AWS_BASE_NAME}-qm role via IRSA annotation)

Landing Backend

The Landing service provides the public-facing marketing/signup pages and AWS SaaS Marketplace integration.

Variable	Purpose	Format	Default	Injection Source
SecretManagerType	Secrets backend selector	AWSSecretManager or HashiCorp	AWSSecretManager	Helm env block
VaultAddrLanding	Path to landing page configuration	${AWS_BASE_NAME}-landing	—	Helm env block
AWS_SAAS_ARN	IAM role ARN for SaaS operations	ARN string	—	Helm env block
AWS_SAAS_REGION	AWS region for SaaS integration	Region string (e.g., us-east-1)	—	Helm env block
AWS_SAAS_METERING_ARN	SQS ARN for metering events	ARN string	—	Helm env block
AWS_SAAS_ENTITLEMENT_ARN	SQS ARN for entitlement events	ARN string	—	Helm env block

Service account: ${AWS_BASE_NAME}-base

CMS (Content Management System)

The CMS manages landing page content via a Strapi-based headless CMS.

Variable	Purpose	Format	Default	Injection Source
SecretManagerType	Secrets backend selector	AWSSecretManager	AWSSecretManager	Helm env block
DATABASE_FILENAME	Path to SQLite database file	File path	/opt/app/database/cms.db	Helm env block
TMPDIR	Temporary directory path	File path	/tmp	Helm env block
ADMIN_JWT_SECRET	JWT secret for admin authentication	JWT token string	—	Helm env block
API_TOKEN_SALT	Salt for API token generation	Random string	—	Helm env block
JWT_SECRET	JWT secret for general authentication	JWT token string	—	Helm env block
NODE_ENV	Node.js environment mode	production / development	production	Helm env block
APP_KEYS	Application encryption keys	Comma-separated strings	—	Helm env block
SMTP_SERVER	SMTP server hostname (from secrets)	Secret path string	${AWS_BASE_NAME}-appcfg/SMTPMailServerHostname	AWS Secrets Manager
SMTP_PORT	SMTP server port (from secrets)	Secret path string	${AWS_BASE_NAME}-appcfg/SMTPMailServerPort	AWS Secrets Manager
SMTP_USER	SMTP login (from secrets)	Secret path string	${AWS_BASE_NAME}-appsec/SMTPMailServerLogin	AWS Secrets Manager
SMTP_PASS	SMTP password (from secrets)	Secret path string	${AWS_BASE_NAME}-appsec/SMTPMailServerPassword	AWS Secrets Manager

Service account: ${AWS_BASE_NAME}-base

Data Migration

The Data Migration job runs database schema migrations (Alembic) during upgrades.

Variable	Purpose	Format	Default	Injection Source
SecretManagerType	Secrets backend selector	AWSSecretManager or HashiCorp	AWSSecretManager	Helm env block
VaultAddrDbSec	Path to database credentials	${AWS_BASE_NAME}-dbsec	—	Helm env block
VaultAddrDbCfg	Path to database configuration	${AWS_BASE_NAME}-dbcfg	—	Helm env block
POSTGRES_HOST	PostgreSQL hostname (dev override)	Hostname string	—	Dev .env only
PYTHONPATH	Python module search path	Colon-separated paths	../cloud-common:../data-layer	Dev .env only

Service account: ${AWS_BASE_NAME}-app

Nginx (Frontend Proxy)

The Nginx service serves the frontend web application and proxies API requests.

Variable	Purpose	Format	Default	Injection Source
SecretManagerType	Secrets backend selector	AWSSecretManager	AWSSecretManager	Helm env block
PROJECT_VERSION	Deployed application version string	Semantic version	Current release	Helm env block

Service account: default

RMQ Metrics

The RMQ Metrics service exports RabbitMQ queue metrics to Prometheus.

Variable	Purpose	Format	Default	Injection Source
SecretManagerType	Secrets backend selector	AWSSecretManager	AWSSecretManager	Helm env block
REDIS_CONN	Redis connection string for metrics caching	Connection string	—	Kubernetes Secret (from ${AWS_BASE_NAME}-base/RmqMetricsRedisConnString)

Service account: ${AWS_BASE_NAME}-base

Infrastructure Services Configuration

These environment variables configure infrastructure-level services that are not AosCloud microservices but support the platform.

RabbitMQ (Units Queues)

Variable	Purpose	Format	Default
RABBITMQ_CARS_PORT	AMQPS connection port	Port number	5671
RABBITMQ_CARS_DEFAULT_VHOST	Default virtual host	Path string	/
RABBITMQ_CARS_CLOUD_EXCHANGE_NAME	Cloud-side exchange name	String	aos_cloud
RABBITMQ_CARS_UNITS_EXCHANGE_NAME	Units-side exchange name	String	aos_units
RABBITMQ_CARS_CLOUD_QUEUE_NAME	Cloud message queue name	String	cloud_queue
RABBITMQ_CARS_QUEUES_LIMIT	Maximum queue count	Integer	30000
RABBITMQ_CARS_QUEUES_CACHE	Queue cache size	Integer	100
RABBITMQ_INITIAL_SERVERS_AMOUNT	Initial RabbitMQ cluster nodes	Integer	1
RABBITMQ_CARS_ADDITIONAL_SERVER	Additional server flag	0 or 1	0
RABBITMQ_QUEUES_TTL_MULTIPLIER	TTL multiplier for queue expiry	Float	1.2

Note: In AWS deployments, RabbitMQ is deployed via the rabbitmq-cluster-operator Helm chart. Connection credentials are provided through a Kubernetes Secret generated by the operator, injected into services via envFromSecret.

PostgreSQL

Variable	Purpose	Format	Default
POSTGRES_DB_NAME	Application database name	String	—
POSTGRES_DB_SCHEMA	Application database schema	String	—
POSTGRES_CLI_SSL_CA	Path to CA certificate for SSL	File path	—
POSTGRES_CLI_SSL_CRT	Path to client certificate	File path	—
POSTGRES_CLI_SSL_KEY	Path to client key	File path	—
POSTGRES_CONFIG_MAX_CONNECTIONS	Maximum connections	Integer	300
POSTGRES_CONFIG_SHARED_BUFFERS	Shared buffer memory	Size string	128MB
POSTGRES_CONFIG_EFFECTIVE_CACHE_SIZE	Effective cache size	Size string	384MB
POSTGRES_CONFIG_WORK_MEM	Per-operation work memory	Size string	1310kB
POSTGRES_CONFIG_MAX_WAL_SIZE	Maximum WAL size	Size string	2GB

Note: In AWS deployments, PostgreSQL is provided by Aurora PostgreSQL. The connection parameters (host, port, credentials) are stored in AWS Secrets Manager at the ${AWS_BASE_NAME}-dbcfg and ${AWS_BASE_NAME}-dbsec paths. Performance tuning parameters are managed by the Aurora configuration rather than environment variables.

DocumentDB (MongoDB-Compatible)

Variable	Purpose	Format	Default
MONGO_INITDB_DATABASE	Initial database name	String	aos-alert

Note: In AWS deployments, DocumentDB connection details are stored in AWS Secrets Manager at the ${AWS_BASE_NAME}-mhcfg and ${AWS_BASE_NAME}-mhsec paths. DocumentDB endpoints are also injected through the Helm aws.docdb.endpoints array.

InfluxDB

Variable	Purpose	Format	Default
INFLUXDB_HOST	InfluxDB server hostname	Hostname	influxdb (K8s service)
INFLUXDB_PORT	InfluxDB HTTP port	Port number	8086
INFLUXDB_DB	Database name	String	influx
DOCKER_INFLUXDB_REPORTING_DISABLED	Disable usage reporting	true / false	true
DOCKER_INFLUXDB_DATA_QUERY_LOG_ENABLED	Enable query logging	true / false	false
DOCKER_INFLUXDB_HTTP_LOG_ENABLED	Enable HTTP access logging	true / false	false
DOCKER_INFLUXDB_INIT_ORG	Initial organization	String	cloud
DOCKER_INFLUXDB_INIT_RETENTION	Data retention period	Duration string	7d
DOCKER_INFLUXDB_INIT_BUCKET	Initial bucket name	String	unit-monitoring

Note: In AWS deployments, InfluxDB runs within EKS with persistence via EFS. Admin credentials are stored in AWS Secrets Manager at ${AWS_BASE_NAME}-base (keys: InfluxdbAdminPassword, InfluxdbAdminToken) and mounted via the CSI secrets driver.

Certificates and Keys

Variable	Purpose	Format
ROOT_CA	Root CA certificate filename	PEM filename
SECONDARY_CA_CERTIFICATE	Secondary CA certificate	PEM filename
OEM_CA_CERTIFICATE	OEM CA certificate	PEM filename
OEM_CA_KEY	OEM CA private key	PEM filename
VEHICLE_CA_CERTIFICATE	Vehicle CA certificate	PEM filename
VEHICLE_CA_KEY	Vehicle CA private key	PEM filename
SP_CA_CERTIFICATE	Service Provider CA certificate	PEM filename
SP_CA_KEY	Service Provider CA private key	PEM filename
INTERNAL_CA_CERT	Internal CA certificate	PEM filename
INTERNAL_CA_CERT_FULLCHAIN	Internal CA full chain	PEM filename
RABBIT_CARS_KEY	RabbitMQ client private key	PEM filename
RABBIT_CARS_CERTIFICATE	RabbitMQ client certificate	PEM filename
MESSAGE_HANDLER_KEY	Message handler TLS key	PEM filename
MESSAGE_HANDLER_CERTIFICATE	Message handler TLS certificate chain	PEM filename
CONTAINER_KEY	Container signing key	PEM filename
CONTAINER_CERTIFICATE	Container signing certificate	PEM filename

Note: In AWS deployments, certificates are stored in AWS Secrets Manager and mounted into pods via the CSI Secrets Store driver (secrets-store.csi.k8s.io). The ingress TLS certificates (for both the main domain and the WebSocket subdomain ws.<domain>) are stored at the ${AWS_BASE_NAME}-ingress secret path and injected by the Istio secrets job.

Inter-Service Dependencies

The following diagram shows how environment variables create dependencies between services:

Key Dependencies

Dependent Service	References	Through Variable	Purpose
Service Discovery	Message Handler secrets	VaultAddrNosqlCfg / VaultAddrNosqlSec	Access DocumentDB for Unit registration data
Unit Message Handler	Message Handler config	VaultAddrMHCfg / VaultAddrMHSec	Share messaging configuration with MH
WebSocket API, Unit Message Handler	RabbitMQ	RMQ_HOSTNAME, RMQ_PORT	Connect to RabbitMQ for Unit message routing
WebSocket API, Unit Message Handler, Service Discovery	External WebSocket endpoint	WS_EXTERNAL_HOSTNAME	Inform Units where to establish WebSocket connections
All services	AWS Secrets Manager	SecretManagerType=AWSSecretManager	Runtime secret resolution from AWS

Common Variable Patterns

SecretManagerType

Every AosCloud microservice includes this variable. It determines the secrets resolution backend:

• AWSSecretManager (production): Resolves VaultAddr* values as AWS Secrets Manager path names
• HashiCorp (development): Resolves VaultAddr* values as HashiCorp Vault URLs

VaultAddr* Variables

These are not Vault URLs in AWS deployments — the name is a historical artifact. In AWS mode, they specify the AWS Secrets Manager secret name prefix where configuration is stored. The application uses the AWS SDK to read secret values from these paths at startup.

PROJECT_VERSION

Injected from the Helm global value global.aos.projectVersion, which is set to ${AOS_CLOUD_VERSION} during deployment. Used for version reporting in health checks and metrics.

Related Documentation

• Helm Values Reference — complete Helm chart parameters that control variable injection
• Kubernetes Deployment Architecture — pod-to-service mapping and IRSA configuration
• IAM Roles and Policies — service account roles that enable Secrets Manager access