Yaml

kind: yaml

sourceconditiontarget

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

NameTypeDescriptionRequired
filestring

“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
filesarray

“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
keystring

“key” defines the yaml keypath.

	compatible:
		* source
		* condition
		* target

	remark:
		* key is a simpler version of yamlpath accepts keys.

	example:
		* key: $.name
		* key: $.agent.name
		* key: $.agents[0].name
		* key: $.agents[*].name
		* key: $.'agents.name'

	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
keyonlyboolean

“keyonly” allows to only check if a key exist and do not return an error otherwise

	compatible:
		* condition

	default:
		false
valuestring

“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.

Top