CFS Global Options

The Configuration Framework Service (CFS) provides a global service options endpoint for modifying the base configuration of the service itself.

View the options with the following command:

cray cfs options list --format json

Example output:

{
  "additionalInventoryUrl": "",
  "batchSize": 25,
  "batchWindow": 60,
  "batcherCheckInterval": 10,
  "batcherDisable": false,
  "batcherMaxBackoff": 3600,
  "batcherPendingTimeout": 300,
  "defaultAnsibleConfig": "cfs-default-ansible-cfg",
  "defaultBatcherRetryPolicy": 3,
  "defaultPlaybook": "site.yml",
  "hardwareSyncInterval": 10,
  "loggingLevel": "INFO",
  "sessionTTL": "7d"
}

In the CFS API specification, these options are defined in the V2Options schema.

The values for all CFS global options can be modified with the cray cfs options update command.

The following are the CFS global options, their names in CFS, and their default values.

Option CFS name Default Type Units/format
Additional inventory URL additionalInventoryUrl "" string Git clone URL
Batch size batchSize 25 integer Components
Batch window batchWindow 60 integer seconds
Batcher check interval batcherCheckInterval 10 integer seconds
Batcher disable batcherDisable false boolean -
Batcher maximum backoff batcherMaxBackoff 3600 integer seconds
Batcher pending timeout batcherPendingTimeout 300 integer seconds
Default Ansible configuration defaultAnsibleConfig "cfs-default-ansible-cfg" string ConfigMap name in services namespace
Default batcher retry policy defaultBatcherRetryPolicy 3 integer Component configuration attempts
Default playbook defaultPlaybook "site.yml" string Name of Ansible playbook
Hardware synchronization interval hardwareSyncInterval 10 integer seconds
Logging level loggingLevel "INFO" string Python logging level
Session Time-To-Live (TTL) sessionTTL "7d" string Length of time or empty string

Additional inventory URL

A Git clone URL to supply additional inventory content to all CFS sessions.

  • Name: additionalInventoryUrl
  • Default: "" (empty string)

See Manage Multiple Inventories in a Single Location for more information.

Batch size

This option determines the maximum number of components that will be included in each session created by CFS Batcher.

  • Name: batchSize
  • Default: 25 components per session

WARNING: Increasing this value will result in fewer batcher-created sessions, but will also require more resources for Ansible Execution Environment (AEE) containers to do the configuration.

See Configuration Management with the CFS Batcher for more information.

Batch window

This option sets the number of seconds that CFS batcher will wait before scheduling a CFS session when the number of components needing configuration has not reached the batch size limit.

  • Name: batchWindow
  • Default: 60 seconds

The batch window time-boxes the creation of sessions so no component needs to wait for the queue to fill.

WARNING: Lower values will cause CFS batcher to be more responsive to creating sessions, but values too low may result in degraded performance of both the CFS APIs as well as the overall system.

See Configuration Management with the CFS Batcher for more information.

Batcher check interval

This option sets how often CFS batcher checks for components waiting to be configured.

  • Name: batcherCheckInterval
  • Default: 10 seconds

This value must be lower than the batch window.

It is not recommended to increase this value during maintenance periods, in order to avoid CFS sessions being scheduled. In that situation, use the batcher disable option.

WARNING: Lower values will cause CFS Batcher to be more responsive to creating sessions, but values too low may result in degraded performance of the CFS APIs on larger systems.

See Configuration Management with the CFS Batcher for more information.

Batcher disable

This option specifies whether the CFS batcher service is enabled or disabled.

  • Name: batcherDisable
  • Default: false

If set to true, CFS batcher will still monitor existing sessions, but will not create new sessions or monitor the desired state of components. When doing maintenance, disabling batcher is preferred over setting a high batcher check interval. This is because the CFS batcher does not check the CFS options while it waits for the check interval to elapse, meaning that after the maintenance is complete, reducing the check interval may take some time in order to take effect, and the only alternative to force it to happen sooner is to restart the batcher service. Alternatively, even while batcher is disabled, it still monitors the CFS options, and will resume its activities when it sees that the disable flag is set to false.

See Configuration Management with the CFS Batcher for more information.

Batcher maximum backoff

This option specifies the maximum number of seconds that the CFS batcher’s back-off will reach.

  • Name: batcherMaxBackoff
  • Default: 3600 seconds

When all sessions are failing, CFS batcher will reduce the frequency with which sessions are created. This back-off time will continue to increase up to this cap, and will reset to 0 when a new session is successful.

See Configuration Management with the CFS Batcher for more information.

Batcher pending timeout

This option specifies the maximum number of seconds that CFS batcher will wait for a new session to enter a running state before deleting the session and trying again.

  • Name: batcherPendingTimeout
  • Default: 300 seconds

This retry helps manage rare communication errors that can cause sessions to be stuck in a pending state.

See Configuration Management with the CFS Batcher for more information.

Default Ansible configuration

The name of the Kubernetes ConfigMap in the services namespace that contains the Ansible configuration to use for CFS sessions when none is explicitly specified.

  • Name: defaultAnsibleConfig
  • Default: "cfs-default-ansible-cfg"

See Set the ansible.cfg for a Session for more information.

Default batcher retry policy

The default batcher retry policy is the maximum number of failed configuration attempts allowed per component before CFS batcher will stop attempting to configure the component.

  • Name: defaultBatcherRetryPolicy
  • Default: 3 attempts to configure a component

This value can be overridden on a per component basis.

For more information, see:

Default playbook

This value is used when no playbook is specified in a configuration layer.

  • Name: defaultPlaybook
  • Default: "site.yml"

For more information on configuration layers, see Configuration Layers.

Hardware synchronization interval

The number of seconds between checks to the Hardware State Manager (HSM) for new hardware additions to the system.

  • Name: hardwareSyncInterval
  • Default: 10 seconds

When new hardware is registered with HSM, CFS will add it as a component.

See Configuration Management of System Components for more information.

Logging level

Do not confuse this with the Ansible verbosity level. For details on how to change that, see Change the Ansible Verbosity Logs.

The logging level for all CFS services.

  • Name: loggingLevel
  • Default: "INFO"
  • Valid values: "DEBUG", "INFO", "WARNING", "ERROR"

This aids debugging by allowing the logging level to be changed dynamically at any time.

Session Time-To-Live (TTL)

The time-to-live for completed CFS sessions.

  • Name: "sessionTTL"
  • Default: "7d"

Running sessions will not be deleted. Specified in minutes (e.g. "45m"), hours (e.g. "9h"), days (e.g. "17d"), or weeks (e.g. "57w"). Set to an empty string to disable.

For more information, see Automatic Session Deletion with sessionTTL.