An article by Dominique, our head of technology.

The object ID and singleton types

Ressources

Cdist is located on github.com/ungleich/cdist.

A small overview of cdist you can find is here. For deeper insights also visit our lastest blog article cdist types and parameters.

You can find the man pages about singleton types on github github.com/ungleich/singelton and github.com/ungleich/singelton/one-instance-only or on your cloned cdist git repository.

Overview

There are two kinds of cdist types: Singleton and not singleton (normal) types.
In this post we will explore both of them and explain why they exist.

Normal type

When we talk about a normal type, it refers to something looking like this:

__TYPE OBJECT_ID [--parameter value …]

Important: We have an OBJECT_ID here. Since it is possible to use the same type more than just once per machine, cdist have to make sure that the correct type is running against the specified host. The combination of __TYPE and OBJECT_ID has to be unique in the whole manifest which defines the state of a machine.
An example is the __file type, which is able to manage files (creating, modifying and deleting). For example it is possible to __file more than once per host, so the object id is needed to distinguish them.

The object id is also important for the require statement. The require="" statement is usable if we need a specific type to run before another type. For example, when you want to have a specific directory with a specific file, the file requires the directory to not fail. The code in a type would resemble the following:

__directory /tmp/folder

require="__directory/tmp/folder" __file /tmp/folder/file

Here we see the require statement needs the object id of the directory type. Otherwise cdist wouldn't know which __directory the __file type requires.

Singleton type

A singleton type is used for types which should only run once per host. For example you create a type which is responsible for distributing ssh-keys. It doesn't make sense for this type to run multiple times per host per run of cdist.
A singleton type does not require a object id, it is easy to identify since only one type should exist.
For defining a singleton type you simply create an empty file called singleton in the type directory

touch PATH/TO/TYPE/singleton

Conclusion

If you create a type which has a generic usage and should be able to run more than just once over a host, you create a normal type.
And if you create a type which should only be used for once (e.g. installing a service etc.) you create a singleton type.

More information

Hope this short post helped your understanding of cdist types. 
If you have any trouble or need more information, visit our github page or write us an email!