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. For example: one inventory file describes the hosts used in your test stage and a second inventory file describes 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, that leads to syntax errors.

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, blue

The main part of the inventory file consists of the following sections: hosts, groups, vars, and consts.

schemaVersion: 1

color: Blue

hosts:
  <items>
groups:
  <items>
vars:
  <items>
consts:
  <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.siven.ch

- nevis-host2.siven.ch

- nevis-host3.siven.ch:
    vars:
      __connection_port: 5222
      __connection_user: root
- proxy-prod:
    vars:
      __connection_host: nevis-host4.siven.ch
      __connection_port: 5222
      __connection_user: techuser
      __connection_password: dt/6lBRCeivAENo6GZY=
- idm-prod:
    vars:
      __connection_host: nevis-host5.siven.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.siven.ch
    - proxy-prod
  vars:
    public_dns: www.siven.ch
- auth:
  members:
    - nevis-host1.siven.ch
    - nevis-host2.siven.ch
- idm:
  members:
    - nevis-host2.siven.ch
    - idm-prod
  vars:
    database_primary: db-host1
    database_secondary: db-host2
- line_active:
  members:
    - proxy-prod
    - nevis-host1.siven.ch
    - idm-prod
- line_standby:
  members:
    - nevis-host3.siven.ch
    - nevis-host2.siven.ch

Vars (Variables)

The vars section defines variables that are valid for 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.

The names of the variables are defined in the project. In the inventory the values are assigned to these variables.

In case some hosts or groups need different values for the same variable, they can be configured at the corresponding host or group level. 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.

Variable names consist only of letters, numbers, underscores and dashes.

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

info

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

• __nevisadmin_pki_automatic_enabled: This variable defines whether the automatic key management is used for deployment (true) or not (false). If this variable is not set, it will be considered as disabled. See Configuring Key Material and Certificates for more details.

vars:
  __nevisadmin_pki_automatic_enabled: true

  proxy_bind_address: https://www.siven.ch/

  proxy_alias:
    - https://www.nevis.ch/
    - https://www.nevis-security.ch/
    - https://www.nevis-security.de/

  # property with multiple value
  session:
    ttl_max_sec: 43200
    inactive_interval_sec: 1800

  # variable example for key-value property
  log-level:
    - EsAuthStart: INFO
    - org.apache.catalina.startup.HostConfig: Error

Consts (Constants)

Constants allows you to create one constant and use it in multiple variables. What you only need to do is to link your constant to variables by inserting a reference in the following formats:

• For local constants: ${const://constantVariableName}
• For global constants: ${g-const://constantVariableName}

This will also give you a possibility to manage your variables efficiently. If you need to update the value of your variable later on, you will no longer need to update it in multiple places where it is used, but simply you update the constant and this will apply to all variables which are referencing to the given constant.

Constants cannot be referenced in another constants.

Local constants

Local constants can be created and used only in the given inventory. To create and use local constants, define consts section in the inventory file and list the constants in that section. To use a constant in your variable, insert its reference as a variable value.

consts:
  c1: nevis.net
  c2: nevis
  c3: 8080
  c4: true
  c5: secret://cd445cb0e611e26f8f6480c2

vars:
  var1: {{'${const://c1}'}}                         # resolved: nevis.net
  var2: {{'http://${const://c1}:${const://c3}'}}    # resolved: http://nevis.net:8080
  var3: {{'https://${const://notfound}'}}           # resolved: {{'https://${const://notfound}'}}
  var4: {{'${const://c3}'}}                         # resolved: 8080 (note: 8080 as a number, not as a string)
  var5: {{'${const://c4}'}}                         # resolved: true (note: true as a boolean, not as a string)
  var6:
    varKey: {{'${const://c2}'}}                     # resolved: nevis
  var7:
    - {{'${const://c1}'}}                           # resolved: [ nevis.net, portal.nevis.com ]
    - portal.nevis.com
  var8: {{'${const://c5}'}}                         # resolved: secret://cd445cb0e611e26f8f6480c2

Global constants

Unlike local constants, the global constants can be created in Global Constants screen and used in multiple inventories. To use a global constant in your variable, insert its reference as a variable value. You can insert the reference in three ways:

• By using Insert global constant button
• By copy-pasting it (copy it from Global Constants screen)
• By manually typing it in the format of ${g-const://constantVariableName}

Disable Patterns

If you want to exclude some patterns from the deployment, you can disable them. For example, this allows you to apply a pattern in one stage while skipping it in another. The following predefined variables can be used:

• __disabled_patterns: There are two ways to disable a pattern: by its name or by referencing its ID. It is possible to combine both options on the same list. Pattern name supports wildcard character asterisk * which matches zero or any number of characters. It can be used multiple times in pattern name.
• __disabled_pattern_types: Disables all the patterns of a certain type. Pattern types are defined by their fully-qualified class name.

vars:
  __disabled_patterns:
    - "Test Auth"
    - "*Proxy*"
    - "PEM*"
    - "*Instance"
    - "Generic*Settings"
    - "pattern://d3f51b1fcbd3eaf433588645"
    
  __disabled_pattern_types:
    - "ch.nevis.admin.v4.plugin.nevisauth.patterns2.LdapLogin"