Configuring Arsenal¶

arsenal.conf¶

Arsenal reads configuration variables from a single file, canonically called arsenal.conf. The location and name of this configuration file can be changed as long as the --config-file argument to arsenal-director is set accordingly.

Oslo/Config¶

Arsenal uses the oslo.config module to parse and load configuration. See oslo.config‘s documentation for detailed information on the supported syntax.

Basic Syntax¶

That said, the basic syntax of the configuration file is fairly straight-forward.

Sections¶

Arsenal’s configuration file is separated into sections. Each section begins with a bracket enclosed string. For example:

[director]

Begins the “director” configuration section. Each line following the section directive will populate that section’s configuration options, until another section directive is parsed, or the end of the file is reached.

Options¶

Each option has this basic format:

<option_name>=<value>

Where <option_name> is the option’s name, and <value> is the value to assign to the option.

A Short Example¶

The following:

[director]
dry_run=True

Would set the dry_run option to the boolean value ‘True’, which belongs to the [director] section.

arsenal.conf Sections¶

There are several sections which comprise arsenal.conf. You may not need to include every available section, nor set every option. Please read through the following section descriptions to get a sense for what functionality is made available through arsenal.conf.

[director] Section¶

The [director] section contains options which affect how arsenal-director gathers information using Scouts.

Note

See scheduler.py for all [director] configuration options.

Important Section Options¶

scout - Configures which Scout will be loaded by arsenal-director to gather data from services. The Scout also currently handles issuing directives to endpoints. The format is:
```
<scout_module_name>.<ScoutClassName>
```
For example, setting the scout option to:
```
devstack_scout.DevstackScout
```
Would cause arsenal-director to use the DevStack Scout, which is a Scout provided by Arsenal that is designed to work with DevStack.

dry_run - A boolean option. Setting this option to True will cause arsenal-director to run in dry run mode. Which means no directives generated by the configured Strategy will be issued.

Tip

dry_run is a great option to use while testing Arsenal without worrying about affecting outside services beyond requesting information.

directive_spacing - An integer option. Represents time in seconds. Determines how long the Director will wait between issuing new directives returned by the configured Strategy.
log_statistics - A boolean option. If True, Arsenal will log detailed statistics about nodes at the INFO level every time Arsenal issues directives. Statistics include: number of provisioned nodes, number of available nodes, number of cached nodes, a breakdown of which images have been cached and at what frequency. Also logs information broken up by flavor of node. If False, no statistics will be logged. Defaults to True.

Cache Node Directive Rate Limiting¶

The next two options are related to limiting how many Cache Node directives Arsenal will issue within a given period of time. They are tightly coupled and should be set together.

cache_directive_rate_limit - An integer option limiting how many cache directives Arsenal will issue within a period of time delimited by cache_directive_limiting_period. Defaults to 0, which indicates no rate limiting of cache directives will occur.
cache_directive_limiting_period - An integer option denoting the period of time, in seconds, to limit Arsenal issuing cache directives to the limit set by cache_directive_rate_limit. Once this period of time passes, Arsenal will again issue cache directives (if the configured Strategy is returning cache directives) until the rate limit is reached, or until the current time period again passes.

Eject Node Directive Rate Limiting¶

The next two options are related to limiting how many Eject Node directives Arsenal will issue within a given period of time. They are tightly coupled and should be set together.

Tip

These two options operate identically as the cache directive rate limiting options presented above. Except they apply to ejection directives.

eject_directive_rate_limit - An integer option limiting how many eject directives Arsenal will issue within a period of time delimited by eject_directive_limiting_period. Defaults to 0, which indicates no rate limiting of eject directives will occur.
eject_directive_limiting_period - An integer option denoting the period of time, in seconds, to limit Arsenal issuing eject directives to the limit set by eject_directive_rate_limit. Once this period of time passes, Arsenal will again issue eject directives (if the configured Strategy is returning eject directives) until the rate limit is reached, or until the current time period again passes.

[strategy] Section¶

This section provides configuration options relevant to all Strategy objects.

module_class¶

The module_class option controls which Strategy object is loaded and subsequently used to provide Arsenal’s cache decisions. The format of the module_class option is as follows:

<strategy_module_name>.<StrategyClassName>

For example, the default value for module_class is:

simple_proportional_strategy.SimpleProportionalStrategy

This causes the the class SimpleProportionalStrategy, which can be found in the simple_proportional_strategy module, to be instantiated and used by arsenal-director to provide cache decisions at run-time. The simple_proportional_strategy module is included as part of Arsenal.

Astute readers will notice the the syntax of this option matches that of scout from the [director] section.

image_weights_filename¶

image_weights_filename is a string option specifying the location of a text file containing a single JSON object where the object’s keys are names of images as strings, and the values are the associated weights as non-negative integers. This JSON object is loaded as a Python dictionary and then referred to by Arsenal whenever a built-in image selection function, such as arsenal.strategy.choose_weighted_images_force_distribution, has to make a decision on which image(s) to choose to cache to available nodes.

Important

The keys of the JSON object in the file named by image_weights_filename must exactly match the names of images as reported by the configured Scout object. This typically means image names reported by Glance. Otherwise the configured weights will not be properly applied.

Images with higher weights will tend to be picked more frequently, and similarly those with lower weights will tend to be picked less frequently.

Note

If image_weights_filename is not defined, then every image will receive the weight specified by the default_image_weight option. Meaning every image will have an equal chance of being cached.

Example JSON object containing image weights:

{
    'Ubuntu': 10,
    'CoreOS': 5,
    'Windows': 2,
    'SteamOS': 1
}

In the above example the Ubuntu image will be picked twice as often as the CoreOS image, and ten times as often as the SteamOS image. If you had 18 nodes to cache, then you can reasonably expect 10 nodes to have the Ubuntu image cached, 5 nodes to have the CoreOS image cached, and so on.

An example image weight json file is available in Arsenal’s source tree.

default_image_weight¶

default_image_weight is an integer value which is used to weight an image with no corresponding entry in the JSON object loaded by the image_weights_filename option. Defaults to 1.

[simple_proportional_strategy] Section¶

Currently, the SimpleProportionalStrategy class is the only concrete implementation of strategy.Strategy provided by Arsenal.

See the SimpleProportionalStrategy section for more information on this Strategy.

Important Section Options¶

percentage_to_cache - A floating point number. Valid values range from 0 to 1 inclusive. 0 corresponds to 0%, and 1 corresponds to 100%. Controls the percentage of unprovisioned/available nodes of a particular flavor to be cached at a particular time.

[client_wrapper] Section¶

The [client_wrapper] section contains options relevant to the Openstack client wrapper provided by Arsenal. Arsenal provides service-specific client wrappers for Ironic, Nova, and Glance.

The client wrappers provided by Arsenal all provide client caching and call-retry behavior. This section provides options to configure part of that behavior as well as provide credentials to all wrappers.

Note

Please see client_wrapper.py for all [client_wrapper] configuration options.

Important

Credential options defined in the client_wrapper section will be used by default by every derived instance of client wrapper unless the credential is overridden in the derived client wrapper’s section. For instance, if os_username is defined in the [client_wrapper] section, then the Nova client wrapper will use the client_wrapper.os_username value unless nova.admin_username is defined.

Important Section Options¶

call_max_retries - An integer value which determines how many times an individual client will be retried, until it is successful.
call_retry_interval - An integer value which Determines how long the client wrapper will wait before trying a call again.

[nova] Section¶

This section provides options mainly relating to credentials and the endpoint to use to communicate with Nova.

Note

Please see nova_client_wrapper.py for all [nova] configuration options.

[ironic] Section¶

This section provides options mainly relating to credentials and the endpoint to use to communicate with Ironic.

Note

Please see ironic_client_wrapper.py for all [ironic] configuration options.

[glance] Section¶

This section provides options mainly relating to credentials and the endpoint to use to communicate with Glance.

Note

Please see glance_client_wrapper.py for all [glance] configuration options.

A full example arsenal.conf file¶

See the example Arsenal configuration in the Arsenal source tree to see a full example configuration to use with arsenal-director.