Environment variables

Environment variables

Artemis accepts several environment variables that control its behavior after starting.

Warning:

All variables starting with ARTEMIS_HOOK_ prefix are required and must be set properly.

Artemis core

  • ARTEMIS_BROKER_HEARTBEAT_TIMEOUT (int): An interval, in seconds, after which a broker client should ping the server over the established connection to keep both parties aware the connection should be kept alive. Default: 60.
  • ARTEMIS_BROKER_HOST (string): Host of the broker. This variable is available only when deploying using container, and is used if ARTEMIS_BROKER_URL is not set. Default: unset.
  • ARTEMIS_BROKER_PASSWORD (string): Password for connecting to the broker. This variable is available only when deploying using container, and is used if ARTEMIS_BROKER_URL is not set. Default: unset.
  • ARTEMIS_BROKER_PROTOCOL (string): Schema for connecting to the broker. This variable is available only when deploying using container, and is used if ARTEMIS_BROKER_URL is not set. Default: unset.
  • ARTEMIS_BROKER_URL (string): Broker URL. Default: amqp://guest:guest@127.0.0.1:5672.
  • ARTEMIS_BROKER_USERNAME (string): Username for connecting to the broker. This variable is available only when deploying using container, and is used if ARTEMIS_BROKER_URL is not set. Default: unset.
  • ARTEMIS_CACHE_URL (string): Cache URL. Default: redis://127.0.0.1:6379.
  • ARTEMIS_CLOSE_AFTER_DISPATCH (boolean): When enabled, broker connection will be forcefully closed after every message dispatch. Default: no.
  • ARTEMIS_CONFIG_DIR (string): Path to a directory with configuration. Default: current working directory.
  • ARTEMIS_CONTAINER_LOG_METHOD (string): Sets logging mode for Artemis components running in containers: file for logging into a file under /logs directory, stdout for the very basic stream of logs streamed through container’s own stdout/stderr, promtail-pipe for piping the stdout/stderr into promtail process. Default: file.
  • ARTEMIS_CONTAINER_LOG_PROMTAIL_CONFIG_FILEPATH (string): path to a Promtail configuration file. Default: /promtail-config/promtail.yaml.
  • ARTEMIS_CONTAINER_LOG_PROMTAIL_OPTIONS (string): additional Promtail options. Default: unset.
  • ARTEMIS_DB_DATABASE (string): Database name. This variable is available only when deploying using container, and is used if ARTEMIS_DB_URL is not set. Default: unset.
  • ARTEMIS_DB_HOST (string): Host of the database. This variable is available only when deploying using container, and is used if ARTEMIS_DB_URL is not set. Default: unset.
  • ARTEMIS_DB_PASSWORD (string): Password for connecting to the database. This variable is available only when deploying using container, and is used if ARTEMIS_DB_URL is not set. Default: unset.
  • ARTEMIS_DB_POOL_SIZE (int): Size of the DB connection pool. Default: 20.
  • ARTEMIS_DB_POOL_MAX_OVERFLOW (int): Maximum size of connection pool overflow. Default: 10.
  • ARTEMIS_DB_PROTOCOL (string): Schema for connecting to the database. This variable is available only when deploying using container, and is used if ARTEMIS_DB_URL is not set. Default: unset.
  • ARTEMIS_DB_SCHEMA_REVISION (string): Target database schema revision to upgrade/downgrade to. This variable is available only when deploying using container. Default: head
  • ARTEMIS_DB_USERNAME (string): Username for connecting to the database. This variable is available only when deploying using container, and is used if ARTEMIS_DB_URL is not set. Default: unset.
  • ARTEMIS_DB_URL (string): Database URL. Default: sqlite:///test.db.
  • ARTEMIS_LOG_DB_POOL (boolean|string): When enabled, Artemis would log events related to database connection pool. Accepts also debug for more details. Default: no.
  • ARTEMIS_LOG_DB_QUERIES (boolean): When enabled, Artemis would log SQL queries. Default: no.
  • ARTEMIS_LOG_DB_SLOW_QUERIES (boolean): When enabled, Artemis would log "slow" queries - queries whose execution took longer than ARTEMIS_LOG_DB_SLOW_QUERY_THRESHOLD seconds. Default: no.
  • ARTEMIS_LOG_DB_SLOW_QUERY_THRESHOLD (float): Minimal time, in seconds, spent executing a query for it to be reported as "slow". Default: 10.
  • ARTEMIS_LOG_JSON (boolean): When enabled, Artemis would emit log messages as JSON mappings. Default: yes.
  • ARTEMIS_LOG_LEVEL (choice): Level of logging. Accepted values are Python logging levels as defined by Python’s logging subsystem, case-insensitive. Default: info.
  • ARTEMIS_LOG_SLOW_CLI_COMMANDS (boolean): When enabled, Artemis would log "slow" CLI commands - commands whose execution took longer than ARTEMIS_LOG_SLOW_CLI_COMMAND_THRESHOLD seconds. Default: no.
  • ARTEMIS_LOG_SLOW_CLI_COMMAND_PATTERN (string): Log only slow commands matching the pattern. Default: .*.
  • ARTEMIS_LOG_SLOW_CLI_COMMAND_THRESHOLD (float): Minimal time, in seconds, spent executing a CLI command for it to be reported as "slow". Default: 10.
  • ARTEMIS_VAULT_PASSWORD (string): A password for decrypting files protected by Ansible Vault. Takes precedence over ARTEMIS_VAULT_PASSWORD_FILE.
  • ARTEMIS_VAULT_PASSWORD_FILE (string): Path to a file with a password for decrypting files protected by Ansible Vault. Default: $HOME/.vault_password.

API server

  • ARTEMIS_API_ENABLE_PROFILING (bool): If enabled, API server will profile handling of each request, emitting a summary into log. Default: no.
  • ARTEMIS_API_ENGINE_DEBUG (bool): Run engine with a debugging enabled. Default: no.
  • ARTEMIS_API_ENGINE_RELOAD_ON_CHANGE (bool): Reload API server when its code changes. Default: no.
  • ARTEMIS_API_PROFILING_LIMIT (int): How many functions should be included in the summary. Default: 20.
  • ARTEMIS_API_PROCESSES (int): Number of processes to spawn for servicing API requests. Default: 1.
  • ARTEMIS_API_THREADS (int): Number of threads to spawn in each process for servicing API requests. Default: 1.
  • ARTEMIS_ENABLE_AUTHENTICATION (bool): If enabled, API requests must pass authentication by providing proper username and token. Default: no.
  • ARTEMIS_ENABLE_AUTHORIZATION (bool): If enabled, API requests must pass authorization by providing username with privileges high enough for the requested action. Default: no.

Worker

  • ARTEMIS_WORKER_PROCESSES (int): Number of worker processes to spawn. Default: number of CPU cores.
  • ARTEMIS_WORKER_THREADS (int): Number of worker threads to spawn per process. Default: 4.
  • ARTEMIS_WORKER_PREFETCH (int): Number of messages to prefetch from regular queues. Default: 2 for each worker thread.
  • ARTEMIS_WORKER_PREFETCH_DELAYED (int): Number of messages to prefetch from delay queues. Default: 1000 for each worker thread.
  • ARTEMIS_WORKER_QUEUES (space-separated list): If specified, worker will listen to only the given queues. Default: unset.

AWS driver

  • ARTEMIS_HOOK_AWS_ENVIRONMENT_TO_IMAGE (string): Script to map environment to an AWS image.

Azure driver

  • ARTEMIS_HOOK_AZURE_ENVIRONMENT_TO_IMAGE (string): Script to map environment to an Azure image.
  • ARTEMIS_AZURE_UPDATE_TICK (int): A delay, in seconds, between two calls of update-guest-request checking provisioning progress. Default: 30.

Beaker driver

  • ARTEMIS_BEAKER_RESERVATION_DURATION (int): A time, in seconds, for which the guest would be initially reserved. Default: 86400.
  • ARTEMIS_BEAKER_UPDATE_TICK (int): A delay, in seconds, between two calls of update-guest-request checking provisioning progress. Default: 300.

OpenStack driver

  • ARTEMIS_HOOK_OPENSTACK_ENVIRONMENT_TO_IMAGE (string): Script to map environment to an OpenStack image.
  • ARTEMIS_OPENSTACK_BUILD_TIMEOUT (int): How long, in seconds, is an instance allowed to stay in BUILD state until cancelled and reprovisioned. Default: 600.
  • ARTEMIS_OPENSTACK_UPDATE_TICK (int): A delay, in seconds, between two calls of update-guest-request checking provisioning progress. Default: 30.
  • ARTEMIS_OPENSTACK_CONSOLE_URL_EXPIRES (int): How long, in seconds, it takes for a console url to be qualified as expired. Default: 600.

Routing

  • ARTEMIS_CACHE_PATTERN_MAPS (bool): If enabled, pattern maps loaded by pools would be cached. Default: yes.
  • ARTEMIS_HOOK_ROUTE (string): Routing script, to be called by route-guest-request task.
  • ARTEMIS_ROUTE_REQUEST_MAX_TIME (int): A time, in seconds, after which a guest request is cancelled if provisioning haven’t succeeded. Default: 21600.
  • ARTEMIS_ROUTE_POOL_FORGIVING_TIME (int): A time, in seconds, after which a pool error during a guest provisioning is ignored and pool becomes eligible for said guest request again. Default: 600.
  • ARTEMIS_ROUTE_POOL_RESOURCE_THRESHOLD (int): A percentage part of pool resource that, when reached, marks pool as depleted and not eligible for provisioning. Default: 90.
  • ARTEMIS_ROUTE_POOL_ENABLED_* (bool): Per-pool variable enabling/disabling pools. The variable name is suffixed with capitalized pool name, for example pool named foo would use variable named ARTEMIS_ROUTE_POOL_ENABLED_FOO. Default: True

Provisioning workflow

Following variables control default values of task aspects, and apply where no specific setting exists.

  • ARTEMIS_ACTOR_DEFAULT_RETRIES (int): A number of time a failing task get retried. Serves as a default value for tasks without custom setting. Default: 5.
  • ARTEMIS_ACTOR_DEFAULT_MIN_BACKOFF (int): The lowest possible delay, in seconds, before the next attempt to run a failed task. Default: 15.
  • ARTEMIS_ACTOR_DEFAULT_MAX_BACKOFF (int): The biggest possible delay, in seconds, before the next attempt to run a failed task. Default: 60.
  • ARTEMIS_ACTOR_DELAY_UNIFORM_SPREAD (int): A range, in seconds, by which can a task delay be modified before use. For example, with ARTEMIS_ACTOR_DELAY_UNIFORM_SPREAD=7 every delay is changed by a random number from range <-7, +7> seconds. Default: 5.
  • ARTEMIS_ACTOR_DISPATCH_PREPARE_DELAY (int): A delay, in second, between successful acquire of a cloud instance and dispatching of post-acquire preparation tasks. Default: 60.

Besides the variables listed above, Artemis accepts variables affecting particular tasks - the name of these variables contains upper-cased task name, with underscores replacing dashes. For example, to influence task named foo-bar, Artemis would accept variables named ARTEMIS_ACTOR_FOO_BAR_…​.

Following variables override defaults specified by ARTEMIS_ACTOR_DEFAULT_* variables for a given task:

  • ARTEMIS_ACTOR_*_RETRIES
  • ARTEMIS_ACTOR_*_MIN_BACKOFF
  • ARTEMIS_ACTOR_*_MAX_BACKOFF

Periodically executed tasks accept following variable controlling the schedule:

  • ARTEMIS_ACTOR_*_SCHEDULE (str): A Cron-like schedule specification, e.g. */7 * * * *. The default value depends on the task.

Prepare stage SSH connection verification timeout is configurable using:

  • ARTEMIS_PREPARE_VERIFY_SSH_CONNECT_TIMEOUT (int): Global SSH connection timeout, in seconds. Default: 15.

Besides this variable, it is possible to override the timeout value per pool:

  • ARTEMIS_PREPARE_VERIFY_SSH_CONNECT_TIMEOUT_* (int): Pool-specific SSH connection timeout value, in seconds. The environmental variable is suffixed with pool name, with underscores replacing dashes. For example for pool named foo-bar the variable name would be ARTEMIS_PREPARE_VERIFY_SSH_CONNECT_TIMEOUT_foo_bar. If not defined, global value is used.

Pool resource cleanup

The process taking care of releasing allocated pool resources is triggered every time Artemis no longer needs to keep them around.

  • ARTEMIS_DISPATCH_RESOURCE_CLEANUP_DELAY (int): A delay, in seconds, to schedule pool resources release with. Instead of running as soon as possible, it would be delayed.

Task queues

Every dispatched task is assigned to one queue. By default, a single queue named default is used. To override this setting, following variable is accepted, specifying a queue name to use instead of default:

  • ARTEMIS_ACTOR_*_QUEUE

Task priorities

Every dispatched task is given a priority. By default, a priority named DEFAULT is used, with exception of tasks crucial for the well-being of the provisioning workflow. To override priority this setting, following variable is accepted, specifying a priority to instead of the one given by developers:

  • ARTEMIS_ACTOR_*_PRIORITY

Following values are accepted as priority specifications:

  • HIGH - equals 100.
  • DEFAULT - equals 200.
  • LOW - equals 300.
  • any integer value.

    Despite being called priority, the lower value, the sooner the task would be executed! Think of it as a ticket number: the lower number, the sooner you are served.