Yaml

kind: yaml

source	condition	target
✔	✔	✔

source

condition

target

✔

Description

source

The Yaml "source" retrieve a key value from a yaml file.

condition

The Yaml "condition" test if an association of key/value match in the defined file.

target

The Yaml "target" test if an association of key/value match in the defined file and update it if necessary.

Parameters

Name	Type	Description
engine	string	“engine” defines the engine to use to manipulate the yaml file. `There is no one good Golang library to manipulate yaml files. And each one of them have has its pros and cons so we decided to allow this customization based on user's needs. remark: * Accepted value is one of "yamlpath", "go-yaml","default" or nothing * go-yaml, "default" and "" are equivalent`
file	string	“file” defines the yaml file path to interact with. `compatible: * source * condition * target remark: * "file" and "files" are mutually exclusive * scheme "https://", "http://", and "file://" are supported in path for source and condition`
files	array	“files” defines the list of yaml files path to interact with. `compatible: * condition * target remark: * file and files are mutually exclusive * protocols "https://", "http://", and "file://" are supported in file path for source and condition`
key	string	“key” defines the yaml keypath. `compatible: * source * condition * target remark: * key is a simpler version of yamlpath accepts keys. example using default engine: * key: $.name * key: $.agent.name * key: $.agents[0].name * key: $.agents[].name key: $.'agents.name' * key: $.repos[?(@.repository == 'website')].owner" (require engine set to yamlpath) remark: field path with key/value is not supported at the moment. some help would be useful on https://github.com/goccy/go-yaml/issues/290`
keyonly	boolean	“keyonly” allows to only check if a key exist and do not return an error otherwise `compatible: * condition default: false`
searchpattern	boolean	`searchpattern` defines if the MatchPattern should be applied on the file(s) path If set to true, it modifies the behavior of the `file` and `files` attributes to search for files matching the pattern instead of searching for files with the exact name. When looking for file path pattern, it requires pattern to match all of name, not just a substring. The pattern syntax is: ``` pattern: { term } term: '' matches any sequence of non-Separator characters '?' matches any single non-Separator character '[' [ '^' ] { character-range } ']' character class (must be non-empty) c matches character c (c != '', '?', '\\', '[') '\\' c matches character c character-range: c matches character c (c != '\\', '-', ']') '\\' c matches character c lo '-' hi matches character c for lo <= c <= hi ```
value	string	“value” is the value associated with a yaml key. `compatible: * source * condition * target default: When used from a condition or a target, the default value is set to linked source output.`

File

When used from a source or condition, file can accept different value If the value start with https:// or http:// then it will read the file from a http location If the value start with file:// then it means that we explicitly want to read a file Otherwise any other file name is accepted.

Key

Array

When we need to reference a specific position inside a YAML array, using the parameter key, we use the a custom syntax which is key[x] where the key represents a YAML key of type array and [x] represents the position inside that array starting from zero.

example_array.yaml

COUNTRY_CODE:
- BE
- FR
- LU

The key COUNTRY_CODE[1] equal FR

Note	Arrays can also be grouped with dots like `key.array[3].key`

Escaping

In yaml keys, the dots character can be escaped using "/" to identify a key containing dots, such as the following example.

image\.tag

image.tag: latest

image.tag

# Is different than
image:
    tag: latest

data.yaml

targets:
  helm-chart-label:
    name: bump chart dependencies
    kind: yaml
    disablesourceinput: true
    spec:
      file: "/tmp/gateway.yaml"
      key: 'spec\.values\.labels\.service\.istio\.io/canonical-revision'
      value: "test"

Please note that for the escaping to work in Updatecli, the YAML value must be single quote otherwise the escaping character is used to escape YAML special characters

Example

# updatecli.yaml
name: Example of YAML resources

scms:
  default:
    kind: github
    spec:
      user: "my git user"
      email: "my git email"
      owner: "olblak"
      repository: "chart"
      token: "{{ requiredEnv .github.token }}"
      username: "github username"
      branch: "main"

sources:
  lastRelease:
    kind: helmchart
    spec:
      url: https://charts.jenkins.io
      name: jenkins

conditions:
  chartVersion:
    name: "jenkinsci/jenkins Helm Chart used"
    kind: yaml
    scmid: default
    spec:
      file: "charts/jenkins/requirements.yaml"
      key: "dependencies[0].name"
      value: "jenkins"

targets:
  chartVersion:
    name: "jenkinsci/jenkins Helm Chart"
    kind: yaml
    scmid: default
    spec:
      file: "charts/jenkins/requirements.yaml"
      key: "dependencies[0].version"

What it says:

Source

Retrieve the version from the Jenkins helm chart repository located on "https://charts.jenkins.io" ⇒ 2.7.1

Conditions

Then there is a YAML condition: "Do we have a YAML file named "charts/jenkins/requirements.yaml" with the key dependencies that contains an array where the first element is set to "jenkins" ?" ⇒ Yes, proceed, No then abort

Targets

If conditions are all met, then updatecli will update (if needed) the first element of the key "dependencies" to "2.7.1" for the file "charts/jenkins/requirements.yaml" from the github repository olblak/chart then publish changes using a Github Pull Request targeting the master from a temporary branch.

Last modified on December 20, 2022

Edit this page on GitHub