YAML – Basics page

This section introduces the basic YAML syntax as it is used for Airlock Microgateway configuration. For more information about Microgateway configuration and the different sources of settings (e.g. DSL reference list and default deny rule groups), see Configuration.

• YAML is case-sensitive.
• YAML is indentation sensitive – this is a common source of errors.
• YAML does not allow the use of tabs but only whitespaces.

Key-value pairs are the basic building block of YAML. Each pair is written as key: value, where whitespace after the : is optional. The key is always a string, the value can be of any datatype.

# This is an example of simple key: value pairs.
name: webapp  
      hostname: webapp.virtinc.com  
      http_enabled: false  
      https_port: 8443 

A single key may have multiple values or objects. This can be done using lists/arrays, preferably written in a list-style as in our following example.

# This is an example of a simple list/array.
 redis_host:
 - 'redis-service1'
 - 'redis-service2'
 - 'redis-service3'    

Other styles i.e. native JSON style would work too but may tend to grow into long and confusing single-line expressions.

The | (pipe) symbol is used for line breaks in multi-line blocks. When using the | symbol, YAML interprets the following block exactly as is including all linebreaks.

# This is a simple multiline example.
 expert_settings:  
            security_gate: |  
              BackendSSLConnectTimeout "13"    
              BackendSSLServerCA /secret/tls/backend-server-validation-ca.crt  
              BackendSSLClientCert /secret/tls/backend-client.crt   
              BackendSSLClientCertKey /secret/tls/backend-client.key  
              BackendSSLVerifyHost "true"

YAML uses backslash, single and double quotes for escaping. For most scalars quotes are not required at all, but if you need to define data that contains characters that could be mistaken with YAML syntax you need to quote the piece of data for the YAML file to stay valid.

• To break it down to simple rules of thumb:
• If your data contains any of these characters :-{}[]!#|>&%@, use quotes for escaping.
• For strings that could be mistaken for a valid number (integer or float), use quotes for escaping.
• For values that consist only of boolean values e.g. true or false, do not use quotes so that these values can be interpreted as boolean.
• In YAML, \n is used to represent a new line, \t is used to represent a tab, and \\ is used to represent the slash. In addition, since whitespace is folded, YAML uses bash style "\ " to escape additional spaces that are part of the content and should not be folded. Lastly, the trailing \ is used as a continuation marker, allowing content to be broken into multiple lines without introducing unwanted whitespace.

As for backslashes and in combination with backslashes, the following rules apply:

Examples for different types of escape sequences:

# This is three rows escaping example.
backslash: P\@ssw\*rd
double_quotes: "String * w!th + characters? and linebreak\n”
single_quotes: ‘"String" with \n other characters’ 

Our example would be interpreted as follows:

# This is the interpretation of our three rows escaping example.
backslash: P@ssw*rd
double_quotes: String * w!th + characters? and linebreak
single_quotes: "String" with \n other characters

• To avoid syntax errors during editing, use the JSON Schema as described in chapter Automatic YAML validation during editing.
• YAML syntax could also be checked with online tools such as (yamlchecker.com) YAML online syntax checker.
• For a brief introduction including a general YAML syntax example, see: https://www.redhat.com/en/topics/automation/what-is-yaml