Classic Infrastructure Inventory YAML file format

About the Inventory File

An inventory file is the place where the deployment environment is defined. It is divided into different sections: hosts, groups, vars, and consts.

• The hosts section defines all hosts on which Nevis components are deployed.
• The groups section defines groups of hosts for deploying Nevis components. You can only group hosts that are already defined in the hosts section. Grouping hosts is not mandatory, but recommended. It is useful in cases where a Nevis component is simultaneously running on more than one host with the same configuration.
• The vars section contains variables which are defined for the whole inventory. Variables can also be defined at groups or hosts level.
• The consts section allows you to create constants that can be reused in multiple variables.

The hosts section is mandatory, whereas groups, vars, consts are optional.

It is common practice to have more than one inventory file: namely one for each stage. As an example: one inventory file describing the hosts used in your test stage and the second inventory file describing the hosts used in your production stage.

File Format

The inventory file uses YAML syntax. To get familiar with the YAML syntax, use one of the many online tutorials. In YAML, indentation is a crucial part of the syntax and is done with spaces. If tab stops are used, this leads to syntax errors in YAML. The integrated editor converts a tab stop automatically into two spaces, but be careful when copy-pasting from external editors. The syntax is automatically validated while you are editing the inventory file. The green traffic light in the top right corner switches to red to indicate syntax violation. Hovering over the traffic light reveals details about the syntax violation.

The inventory file starts with the mandatory preamble which defines the schemaVersion. This ensures that future format changes can be handled. Optionally, you can define a color for the inventory. This helps to distinguish between inventories at a glance, for example you can assign different colors for different stages.

The available values for color are:

• red,
• yellow,
• green,
• purple,
• brown, and
• blue.

The main part of the inventory file consists of the three lists: hosts, groups and vars. While it is mandatory to define hosts, groups and vars are optional.

Example

schemaVersion: 1
color: Blue
hosts:
  <items>
groups:
  <items>
vars:
  <items>

Hosts

In this section the hosts available for deployment are defined. Each host is usually referenced by its DNS name. Alternatively, you can define an abstract name or use its IP address as identifier.

Each host can have variables that are used by the Nevis components running on this particular host. They are defined right below the host identifier as a list. For hosts there are the following four predefined variables:

• __connection_host: If you use the abstract name as identifier of a host, you have to define the DNS name or IP address in this variable. If this variable is not set, the host name itself will be used.
• __connection_port: With this variable you define an alternative port to use for deployment. If this variable is not set, the port 22 (default for SSH) will be used.
• __connection_user: This variable defines an alternative user name to use for deployment. If this variable is not set, the user name nevis will be used.
• __connection_password: This variable defines the user's password to use for deployment. If this variable is not set, the tenant's SSH key will be used to authenticate.

hosts:
- nevis-host1.muvonda.ch

- nevis-host2.muvonda.ch

- nevis-host3.muvonda.ch:
    vars:
      __connection_port: 5222
      __connection_user: root
- proxy-prod:
    vars:
      __connection_host: nevis-host4.muvonda.ch
      __connection_port: 5222
      __connection_user: techuser
      __connection_password: dhei8Pha7ZeemoSho
- idm-prod:
    vars:
      __connection_host: nevis-host5.muvonda.ch

Groups

In this section the previously defined hosts can be organized into one or more groups. Groups allow you to organize your inventory logically. As an example, you can structure the hosts in groups according to their functions within the Nevis Security Suite. Another approach is to group them according to their physical location, e.g., if your infrastructure is geographically separated into different data centers. A combination of both approaches is also possible. Variables can also be defined at group level.

groups:
- proxy:
  members:
    - nevis-host3.muvonda.ch
    - proxy-prod
  vars:
    public_DNS: www.muvonda.ch
- auth:
  members:
    - nevis-host1.muvonda.ch
    - nevis-host2.muvonda.ch
- idm:
  members:
    - nevis-host2.muvonda.ch
    - idm-prod
  vars:
    database_primary: db-host1
    database_secondary: db-host2
- line_active:
  members:
    - proxy-prod
    - nevis-host1.muvonda.ch
    - idm-prod
- line_standby:
  members:
    - nevis-host3.muvonda.ch
    - nevis-host2.muvonda.ch

Vars (Variables)

In this section variables are defined that are valid on the entire inventory. This means that they are defined for every host in the hosts section. It is common practice to define variables at this level. In case some hosts or groups need different values for the same variable, they can be configured at the corresponding host or group level.

The names of the variables are defined in the project. In the inventory the values are assigned to these variables. Keep in mind that variables defined on host level override variables defined on group level, which themselves override variables defined on inventory level. Try to keep the confusion at a minimum by defining the variables at the appropriate level, rather than using precedence.

Variables do not only support simple key/value pairs, but also more complicated structures, such as lists, dictionaries and even nested structures.

For testing purposes only, you can enable the automatic key management with the following predefined variable:

• __nevisadmin_pki_automatic_enabled: This variable defines if the automatic key management is used " for more details.

vars:
  __nevisadmin_pki_automatic_enabled: true
  proxy_bind_address: https://www.muvonda.ch/
  proxy_alias:
    - https://www.nevis.ch/
    - https://www.nevis-security.ch/
    - https://www.nevis-security.de/
  session:
    ttl_max_sec: 43200
    inactive_interval_sec: 1800

Disable Patterns

If you want some patterns to not be included during the deployment, you can disable them in the inventory. For example, this allows you to apply a pattern in one stage while skipping it in another. The following predefined variables can be defined in the variables of Hosts, Groups or Vars (Variables):

• __disabled_patterns: With this variable you define the list of patterns that you want to have disabled during the deployment. There are two ways to define a pattern: by its name or by referencing its ID. It is possible to combine both options on the same list.
• __disabled_pattern_types: If you want to disable all the patterns of a certain type, you can define it on this variable. All the patterns belonging to the types defined on this list will be disabled during the deployment. Pattern types are defined by their class name.

vars:
  __disabled_patterns:
    - "Test Auth"
    - "pattern://d3f51b1fcbd3eaf433588645"
  __disabled_pattern_types:
    - "ch.nevis.admin.v4.plugin.nevisauth.patterns2.LdapLogin"