Quick Start

Introducing a very basic updatecli workflow.

Updatecli is a command-line tool used to update your file. You specify in manifest how you expect your files to be updated and then you run updatecli to enforce the result.

For this quickstart we are going to need three components:

  1. Updatecli binary installed.

  2. The data file to update is provided in this guide.

  3. The updatecli manifest is also provided in this guide.

Installation

Updatecli is a standalone binary available on GitHub with packages for Windows, Linux, and OSX.

If you don’t have it yet locally, please make sure you downloaded the latest updatecli as explained on Installation →

Scenario

Let’s see what a simple updatecli pipeline can look like.

Data file

Firstly, we need a sample data file that we want to update (if needed). It could be your puppet hieradata file, your helm value file, or whatever data file you need. For us, it’s a YAML file defining the "latest" Jenkins Docker image tag running in our infrastructure.

# data.yaml
container:
  image: jenkinsci/jenkins
  tag: 2.275

Updatecli Pipeline

Updatecli needs at least one manifest to know what update pipeline to apply.

In our manifest, we introduce the most three important concepts of an updatecli manifest.

  1. A Source definition describes where a piece of information is coming from. In the current example, we are looking for the latest Jenkins weekly version.

  2. A Target definition describes what we want to update based on a source output. In our example, we want to update the key "container.tag" in the file "data.yaml" to the version retrieved from the source so the latest Jenkins weekly version.

  3. A Condition definition defined conditions required to update the target. In our example, we want to test that the docker image "jenkinsci/jenkins:<latest Jenkins weekly version>" exists on DockerHub.


Updatecli Pipeline

# manifest.yaml
title: QuickStart example
# Defines how to get "source" information such as Jenkins version
sources:
  jenkinsVersion:
    name: Get the latest Jenkins weekly version
    kind: jenkins
    spec:
      release: weekly
# Defines "conditions" required to update targets 
conditions:
  dockerimage:
    name: Is Jenkins weekly tag published on DockerHub
    kind: dockerImage
    spec:
      image: jenkins/jenkins

# Defines "targets" which need to be updated if different than "source" information.
targets:
  dataFile:
    name: Bump Jenkins Docker Image Tag 
    kind: yaml
    spec:
      key: container.tag
      file: data.yaml

Source, Condition, Target will behave differently based on the plugin used which is defined by the key "kind".

Updatecli Execution

Now that we have a data file and an updatecli manifest, describing how to update our file, let’s see how to use updatecli.

So for doing so, please execute the following command:

  1. To see what would change: updatecli diff --config manifest.yaml

  2. To apply the change: updatecli apply --config manifest.yaml

  3. To see that nothing needs to be changed anymore: updatecli apply --config manifest.yaml

Video

INFO: You can improve this video by contributing to updatecli/demo-terminal

Conclusion

Through this example, we saw how updatecli works with a very simple pipeline. They are many improvements possible for this pipeline, such as automatically publishing updated files to a git repository, using the GitHub pull-request workflow, transforming the source value, not retrieving the latest version, etc.

The real power of updatecli is to combine different plugins to easily implement a customized update pipeline.

Go Further

Core

Understand how the different core concepts work. Core →

Plugins

Understand how to combine the different plugins. Plugins →

Continously Update Everything

Learn how to continuously run updatecli to apply updates. CI →

Contributing

Find out how to contribute to Updatecli. Contributing →

Help

Get some help. Help →

Top