Inventory File¶

VOR Stream deployments rely on an Ansible inventory file for site-specific customizations via host variables. This allows for customization of deployment locations, ports, users, etc. The default inventory file resides in the root-level directory and is named hosts.ini.

Defining Target Hosts¶

Single Machine Deployment¶

The first line under each host group in the hosts.ini file specifies a deployment target definition that identifies the machine on which VOR Stream is being deployed.
Save and close the hosts.ini file.

To assign a machine to a target host, specify a single hostname under all and it will cascade to the remaining hosts. An example is shown below.

Example

[all]
hostname1

[compute]

[django]

[caddy]

[postgres]

[rabbitmq]

[super]

[web]

[sdk]

[vault]

[consul]

[consul_ui]

Save and close the hosts.ini file after editing.

Multi Machine Deployment¶

The first line under each host group in the hosts.ini file specifies a deployment target for each target machine.

To assign machines to target hosts, specify a hostname under each host group. Some services, e.g., Consul, support a clustered deployment where multiple hostnames can be specified. An example is shown below.

Example

[all]

[compute]
hostname1

[django]
hostname2

[caddy]
hostname3

[postgres]
hostname4

[rabbitmq]
hostname5

[super]
hostname6

[web]
hostname7

[sdk]
hostname8

[vault]
hostname9

[consul]
hostname10
hostname11
hostname12

[consul_ui]
hostname13

Save and close the hosts.ini file after editing.

Variable Customizations¶

The sections below describe the inventory file variable customizations that are available to

Foundational¶

General¶

use_become - True/False to use privilege escalation (defaults to True). If running with use_become=False, tasks that require elevated privileges must have been executed prior to running the playbook.
environment_name - the name of the environment, e.g., dev, test, prod. Currently, this is only used if Sentry integration with Django/Super is enabled.
vor_root - the root directory for the installation.
vor_user - the user to perform the installation. Created if it does not exist (requires root).
vor_group - the primary group for vor_user. Created if it does not exist (requires root).
create_system_profile_script - True/False to create the system profile script (defaults to True). If True, the Ansible deployment will attempt to create the system profile script under /etc/profile.d. The script will always exist at {{ vor_root }}/etc/profile.d as well. If running with use_become=False, the script can be manually copied from {{ vor_root }}/etc/profile.d to /etc/profile.d for automatic sourcing of all users on the system.
supervisord_root_deployment - True/False to allow for running services as root, e.g., to run a service on a privileged port. Requires root if True.
vor_stream_profile_script_name - name of the script, e.g., vor-stream to create under /etc/profile.d to set important environment variables for the installation. Requires root.
vor_log_directory - directory to store log files
Python_version - the version of Python to install (do not modify). Python is compiled and installed on all hosts.
vault_addr - the address of the Vault server that the deployment should use. This defaults to hostname of the first Vault host in the inventory file.
vault_skip_verify - skip verifying the TLS certificate of the Vault server (defaults to False). This is useful for performing deployments where the Vault server's certificates are: self-signed, signed by an internal CA, or signed by a CA that is not trusted by the deployment machine. This can also be set when replacing expired Vault certificates.
oidc_providers_file - the path to the OIDC providers file. This file is used to configure the OIDC providers in VOR. This defaults to {{ inventory_dir }}/oidc_providers.yaml'.
vor_token_ttl - the TTL for the VOR token in seconds (defaults to 43200). Increase this value if you have jobs that are expected to run longer than 12 hours.
default_sql_version - System-wide setting for the default SQL syntax version to use. This can be overridden at the process and node level. Acceptable values are 1 and 2.
database_conn_path - System-wide setting for the Vault path (relative to kv/data/node) where database connection information is stored. When set, all database nodes will use this path to retrieve their connection details by default. For example, if the full Vault path is kv/data/node/vor/mssql, set this variable to vor/mssql. This setting can be overridden at the playpen or node level for more granular control.

LDAP¶

If you choose to use LDAP for authentication, the following variables are required for Vault to configure the LDAP authentication method:

ldap_base_dn
ldap_bind_dn
ldap_bind_password
ldap_group_search
ldap_group_attr
ldap_host - the hostname of the LDAP server.
ldap_protocol - the protocol to use for the LDAP server. Acceptable values are ldap and ldaps.
ldap_group_subtree
ldap_user_attr

Database¶

database_type - the type of database to use for the Django backend. Acceptable values are postgres and mssql (defaults to postgres).
database_user - the user to authenticate as when connecting to the database.
database_password - the password for the user.
database_schema - the schema to use for the database (defaults to django).
database_host - The hostname of the database server (defaults to the first host in the "postgres" Ansible group if using PostgreSQL and localhost if using MSSQL).
database_port - The port of the database server (defaults to 1433 for MSSQL and 5432 for PostgreSQL).
database_name - the name of the database to use (defaults to vor).
database_sslmode - disable/require (defaults to require). Only applicable to PostgreSQL.
database_vault_path - path to the Vault service that should be used to retrieve the database credentials. To use dynamic secrets, use database/creds/vor-django-role for PostgreSQL (dynamic credentials with Microsoft SQL Server are not supported at this time). If the dynamic secrets engine is used, the database_user and database_password parameters should also be set to create the dynamic roles.
mssql_driver - the driver to use for the MSSQL database (defaults to ODBC Driver 18 for SQL Server).
mssql_extra_params - extra parameters to pass to the MSSQL database (defaults to 'Encrypt=no;LongAsMax=yes'). See Supported DSN/Connection String Keywords and Connection Attributes for a list of supported keywords.

RabbitMQ¶

rabbitmq_host - the hostname of the RabbitMQ server. In a production environment, this should be a load balancer or other proxy that can route messages to the RabbitMQ cluster, as this value is used by Vault for RabbitMQ secret creation and by Consul for health checks. If using a managed service RabbitMQ, e.g., Amazon MQ for RabbitMQ, this should be the address to that managed instance. If RabbitMQ is installed by Ansible and this value is not provided, it will default to the inventory hostname of the first RabbitMQ node in the cluster. If RabbitMQ is not installed, it's mandatory to set this variable.
rabbitmq_user - the user to authenticate as when connecting to the RabbitMQ server. If RabbitMQ is installed by Ansible, the user will be created if it does not exist. If RabbitMQ is not installed, it's mandatory to set this value.
rabbitmq_password - the password for the user.
rabbitmq_amqp_port - the port of the RabbitMQ server (defaults to 5672).
rabbitmq_management_port - the port of the RabbitMQ management interface (defaults to 15672).
rabbitmq_vhost - the virtual host to use (defaults to /).
rabbitmq_node_name - the name of the node to use (defaults to rabbit).
rabbitmq_vault_path - Vault path to retrieve RabbitMQ credentials from. To use the Vault key-value secrets engine (static credentials), specify the path in the form of kv/data/<name>, e.g., kv/data/rabbitmq. To use the dynamic secrets engine, specify the path in form of rabbitmq/creds/<credential-name> e.g., rabbitmq/creds/vor-midtier-role. If using the dynamic secrets engine, the values provided for rabbitmq_user and rabbitmq_password are used by Vault to communicate with RabbitMQ to generate credentials.

Email Server¶

email_port - port that the email server should listen on. (defaults to 587)
email_host - hostname that the email server should listen on. (e.g. if using Amazon SES, the domain name will look like email-smtp.us-east-1.amazonaws.com)
email_sender - email address that the email server should use as the sender address.
email_user - user that the email server should authenticate as.
email_password - password that the email server should use to authenticate.
email_vault_path - path to the Vault service that should be used to retrieve the email server credentials.

TLS¶

To copy certificate from the local machine to the server, use the following variables:

local_tls_ca_cert_file_path - path to the local TLS CA certificate file.
local_tls_cert_file_path - path to the local TLS certificate file.
local_tls_key_file_path - path to the local TLS key file.

Set the following variables to the paths to the files on the server to indicate the server should be configured to use TLS:

tls_directory - path to the directory where the TLS files should be stored.
tls_ca_cert_file_path - path to the TLS CA certificate file.
tls_cert_file_path - path to the TLS certificate file.
tls_key_file_path - path to the TLS key file.

Vault¶

vault_storage_path - path to store the Vault tokens and keys (defaults to <vor_root>/vault/data)
vault_listener_address - used to set Vault's api_addr property. This defaults to the server's hostname and port 8200. This can be customized to a more generic address, e.g., 0.0.0.0:8200, to allow Vault to listen on all interfaces or using a go-sockaddr template, e.g., {% raw %}{{ GetInterfaceIP "eth0" }}:8200{% endraw %}. If this address is not an explicit IP address or hostname, the service_address variable must be set.
vault_cluster_address - used to set Vault's cluster_addr property and generally does not require modification.
vault_enable_audit - True/False to enable detailed logging of all requests and response to Vault (defaults to False).
service_address - the address to register with Consul for the Vault service. This defaults to the value of vault_listener_address if it is an explicit IP address or hostname. Set this to the address only without the port. This can also be used to set the address to a load balancer in front of a Vault cluster if it is desired to send all traffic through the load balancer.
vault_issuer - used for verifying JWTs issued by Vault. This should be set to an externally accessible address for Vault, e.g., https://vault.example.com:8200. In a clustered deployment, this would typically be a load balancer in front of the cluster. If not specified, this defaults to the listener address of the first node in the vault Ansible group.

Consul¶

consul_bind_addr - the address to bind for internal cluster communications (defaults to 0.0.0.0). If multiple private IPs are available, the address can be dynamically defined using a go-sockaddr template, e.g., {% raw %}{{ GetInterfaceIP "eth0" }}{% endraw %} (see Consul documentation for more information).
consul_client_addr - the address to which Consul will bind client interfaces, including the HTTP and DNS servers (defaults to 127.0.0.1). Note that this value is not applicable to the Consul UI instance, which is always bound to 0.0.0.0.
consul_http_api_port - the port of the Consul HTTP API (defaults to 8501).
consul_http_max_conns_per_client - the maximum number of connections per client (defaults to the minimum of 10000 or the maximum number of file descriptors for the vor_user user minus 20). See Consul documentation for more information.
consul_storage_path - path to store the Consul tokens and state.
consul_server_rejoin_max_age - the maximum allowable downtime for a server before attempting to rejoin a cluster (defaults to 168h). See Consul documentation for more information.

Cloudwatch¶

collection_interval - the interval in seconds to collect all metrics (defaults to 60).
cpu_collection_interval - the interval in seconds to collect CPU metrics (defaults to 60).
disk_collection_interval - the interval in seconds to collect Disk metrics (defaults to 60).
memory_collection_interval - the interval in seconds to collect Memory metrics (defaults to 60).
ignored_mounts - comma-separated list of mount points to ignore when collecting disk metrics (defaults to ["/boot", "/boot/efi"]).

Service group level configuration¶

Caddy¶

caddy_version - the version of Caddy to install (do not modify).

Django¶

default_require_comment - True/False to enable/disable comment prompts when saving objects in the UI (defaults to True). This setting can be modified at the playpen level by updating the require_comment field in the playpen configuration.
default_require_upload_approval - True/False to enable/disable the requirement for uploaded files to be approved by a manager (defaults to False). This setting can be modified at the playpen level by updating the require_upload_approval field in the playpen configuration. When set to True only approved uploads (ex/ Macro Economic Scenarios, Portfolio Data, Overlays) will be available for selection on the View Scenario, Build Study and Run Study screens.
default_disable_scenario_weighting - True/False to enable/disable scenario weight prompting when attaching them to studies.
default_require_methodology_selection - True/False setting to true will force users to select a methodology before saving a study.
default_require_scenario_selection - True/False setting to true will force users to select scenarios before saving a study.
default_hide_scenario_selection - True/False setting to true will hide the scenario tab from the build study screen.
default_disable_model_unit_test - True/False setting to true will hide the model run section from the model screen.
django_server_name - the server name to use for the Django server (defaults to the group hostname).
django_debug - True/False to enable/disable Django's DEBUG setting (defaults to False).
django_sentry_dsn - if using Sentry with Django, the Sentry DSN to use for error reporting (defaults to None). If this value is not set, the Sentry SDK will not be configured.
django_port - the port to use for the Django server (defaults to 8000).
django_ssl_port - the port to use for the Django TLS server (defaults to 8001).
superuser_username - the username to use for the superuser (defaults to vrisk).
superuser_email - the email address to use for the superuser (defaults to [email protected]).
django_vault_roleid_path - path to the approle id for authenticating to Vault.
django_vault_secretid_path - path to the secret id for the approle.
django_vault_token_path - path to the Vault token to retrieve credentials for the django service.
data_upload_max_memory_size - the maximum allowed size of a request body in bytes. This setting is disabled by default. See Django documentation for more information.
uwsgi_limit_as - the maximum amount of virtual memory (in bytes) that a uWSGI worker can use (defaults to 2048). See the uWSGI documentation for more details.
uwsgi_listen - the maximum number of pending connections for the uWSGI server (defaults to the kernel setting for the maximum listen backlog, which can be viewed by running the sysctl net.core.somaxconn command). See the uWSGI documentation for more details.
uwsgi_max_temp_file_size - This value is used to disable the download button on the waterways outputs modal for files larger than the max temp file size.
uwsgi_read_timeout - the maximum amount of time in seconds to wait for a request from uWSGI (defaults to 60).This sets the timeout value for uWSGI harakiri options.

Compute¶

compute_port - the port to use for the compute server SSHD service (defaults to 23234).
rabbitmq_tls_ca_cert_file_path - path to the RabbitMQ TLS CA certificate file. This is used to verify the server's certificate when connecting to the RabbitMQ server.
go_version - the version of Go to install (do not modify).
go_checksum - the checksum of the Go binary to download (do not modify).

RabbitMQ¶

consumer_timeout - delivery acknowledgement timeout in milliseconds (defaults to 1800000). See the RabbitMQ documentation for more information.
disk_free_limit_absolute - sets the disk_free_limit.absolute value in the RabbitMQ configuration. See the RabbitMQ documentation. Conflicts with disk_free_limit_relative. If this variable is not defined, the setting will not be specified in the configuration file.
disk_free_limit_relative - sets the disk_free_limit.relative value in the RabbitMQ configuration. See the RabbitMQ documentation. Conflicts with disk_free_limit_absolute. If this variable is not defined, the setting will not be specified in the configuration file.
vm_memory_high_watermark_absolute - sets the vm_memory_high_watermark_absolute.absolute value in the RabbitMQ configuration. See the Rabbit MQ documentation. Conflicts with vm_memory_high_watermark_relative. If this variable is not defined, the setting will not be specified in the configuration file.
vm_memory_high_watermark_relative - sets the vm_memory_high_watermark_absolute.relative value in the RabbitMQ configuration. See the Rabbit MQ documentation. Conflicts with vm_memory_high_watermark_absolute. If this variable is not defined, the setting will not be specified in the configuration file.

Super¶

super_docs_dir - directory to store symlinks to playpen documentation (defaults to <vor_root>/docs/playpen).
super_queue_buffer - queue buffer length (defaults to 50).
super_queue_prefetch - queue prefetch count (defaults to 10).
super_queue_threads - number of threads to use for the queue (defaults to 0, which will use the number of CPUs available on the Super host).
super_queue_limit - Maximum number of observation waiting on a queue (defaults to 0, which implies no limit).
super_queue_poison_pill_multiplier - The number of poison pills sent when a queue is empty is; super-queue-prefetch x super-queue-threads x super-queue-poison-pill-multiplier (defaults to 10).
super_queue_limit_wait - The number of milliseconds between polling for current queue length (defaults to 10). Only relevent if there is a queue limit.
super_user_groups_cache_ttl - TTL for the django group cache(defaults to 60s).
super_django_request_timeout - timeout for django requests (defaults to 60s).
super_vault_roleid_path - the path to the approle id for authenticating to Vault.
super_vault_secretid_path - the path to the secret id for the approle.
super_vault_token_path - path to the Vault token to retrieve credentials for the super service.
umask - the umask to use for the super service (defaults to 002. This allows the playpen owner and group members to overwrite files created by the Super API).
envvars - comma-separated list of environment variables for the super service to run with, e.g., ENVVAR1=value-1,ENVVAR2=value-2,...,ENVVARN=value-n.
super_listen_addr - host and port to listen on (defaults to <super-hostname>:1962).
log_level - the log level to use for the super service. Available levels are trace, debug, info, warning, error, fatal and panic (defaults to trace).
super_sentry_dsn - if using Sentry with Super, the Sentry DSN to use for error reporting (defaults to None). If this value is not set, the Sentry SDK will not be configured.
super_sentry_traces_sample_rate - the sample rate to use for tracing with Super. This should be a value between 0 and 1. If this value is not set, tracing will not be enabled. See Set Up Tracing for more information.

Web¶

web_server_name - the hostname to use for the web server (defaults to the group hostname).
enable_reporting_db - true/false feature flag to enable the option to save results to the reporting database on the model tab (defaults to false).
django_endpoint - the endpoint to communicate with the Django server. The format is //<django-server-name>:<django-port>.
django_ssl_endpoint - the TLS endpoint to communicate with the Django server. The format is //<django-server-name>:<django-ssl-port>.
consul_endpoint - the endpoint to communicate with the Consul API. This should be an endpoint accessible from the UI, such as the Consul host or a load balancer or proxy pointing to a Consul host or cluster. The format is <scheme>//<hostname>:<port>, where <port> and scheme scheme are optional. If scheme is not provided it will default to the scheme of the web UI.
web_port - the port to use for the web server (defaults to 8080).
web_ssl_port - the port to use for the web TLS server (defaults to 8081).
local_logo_file_path - specify a path to a logo file on the Ansible controller to override the default logo for the web UI.
primary_color - override the website's primary color.
accent_color - override the website's accent color.

SDK¶

sdk_listen_addr - host and port to listen on (defaults to <sdk-hostname>:9000).
sdk_django_request_timeout - timeout for django requests (defaults to 60s).
sdk_vault_roleid_path - path to the approle id for authenticating to Vault.
sdk_vault_secretid_path - path to the secret id for the approle.
sdk_vault_token_path - path to the Vault token to retrieve credentials for the SDK service.
log_level - the log level to use for the SDK service. Available levels are trace, debug, info, warning, error, fatal and panic (defaults to debug). Use trace to enable gRPC payload logging.

Vault¶

vault_listener_address - address of the Vault server (defaults to hostname where the Vault server is running at port 8200).
vault_cluster_address - address (full URL) that is shown to other Vault servers for request forwarding (defaults to hostname where the Vault server is running at port 8201).

Consul¶

encryption_key - key to encrypt communication among Consul agents within a datacenter. (see Consul Gossip Encryption documentation for more information)
consul_ca_cert - Consul CA certificate file. (see Consul TLS documentation for more information on how to generate new CA)
consul_ca_key - Consul CA key.

Consul UI¶

consul_ui_http_api_port - the port of the Consul UI HTTP API (defaults to 8500).