- Application Interface
freckles automatically applies pre-configured tasks according to a profile,
frecklecute is more flexible. It takes a
yaml-formatted text file (let’s call those ‘frecklecutables’) as input, and executes the list of tasks contained in them.
If you’ve ever used Ansible then you know about their so-called ‘playbooks’. If not, Ansible playbooks are basically list of instructions to get a (physical or virtual) machine from one state to another. Usually, from a useless state to a useful one. Your definition of ‘usefulness’ of course is what’s important here.
Ansible is very powerful, and mainly designed to manage infrastructure, not single machines. Although, of course, Ansible can do that too. The issue is that – for single machines – setting up Ansible and a playbook, and the environment and configuration that playbook needs, is often more effort than just doing whatever needs doing manually. Esp. if those are things that don’t need to be done very often, relatively.
So, If you find yourself in a situation where you’d like to have some ‘managed state change’, but can’t really be bothered (or afford) to setup Ansible and write a playbook, maybe frecklecute is for you. It is (deliberately) not as powerful as a full-blown Ansible playbook, but it can be used to execute Ansible roles, which means you can, if need be, get all of Ansible’s power by just writing a ‘normal’ Asible role, but the ease of execution that frecklecute provides.
(Autogenerated) cli help
A frecklecutable is a (yaml) text file that does not contain a ‘.’ (dot) in its file name, and is found in any of the ‘trusted_repo’ folders configured in
$HOME/.freckles/config.yml (if not shipped with freckles, or located in
Those are the top-level
yaml keys a valid frecklecutable can contain:
- the list of tasks the frecklecutable executes if called
- contains help text to display in the command line (if called with the
- configuration for command-line arguments for a frecklecutable
- variables to be forwarded to the Ansible tasks and roles that get executed by the frecklecutable
By default, frecklecute comes with a (small) set of ‘officially supported’ adapters which are always available (see below). Those are mostly for freckles housekeeping tasks (like updating the freckles package itself, or adding new trusted repos, etc.) or generic enough to be of common interest.
In addition, by default frecklecute checks one other folder for more available adapters:
$HOME/.freckles/frecklecutables. Additional locations can be specified by adding either git repository urls or local paths to the
trusted-repos config option of the freckles config file (
$HOME/.freckles/config.yml). To easily add and retrieve an existing git repo that contains frecklecutables, you can use the
enable-repo frecklecutable, e.g.:
frecklecute enable-repo gh:makkus/my-frecklecutables
This will add the git repo url to the
trusted-repos key in
$HOME/.freckles/config.yml, and check out the repository into a location using a unique path (
$HOME/.local/share/freckles/repos/https/github/com/makkus/my/frecklecutables/git in this case) where freckles will find it in subsequent runs.
frecklecute will look at all files in the roots of the configured folders and check if it can find any (usable – which means their content is yaml and contains a
tasks key) files. Also, those files are not allowed to have a ‘.’ (dot) in their name. In addition, frecklecute will look for any child-folders of all of the configured folders, and look into the roots of all of those child-folders that are named (exactly)
frecklecutables. It’ll also check the roots of those for useable text files that don’t contain a ‘.’ in their name.
Those are the frecklecutables that ship with the freckles python package.
freckles.io frecklecutables repository¶
There is a repository of community created and maintained freckle adapters, which can easily enabled using the
frecklecutable enable-repo freckles-io
This will check out the freckles adapters git repo (into:
~/.local/share/freckles/repos/freckles_io), and mark it as trusted in the
~/.freckles/config.yml config file.
Locally available frecklecutables¶
Which frecklecutables are available to you locally depends on which additional repositories you specify as ‘trusted’ in the freckles config, and whether you have any custom frecklecutables in
~/.freckles/frecklecutables. To quickly list all available frecklecutables, execute
frecklecute with the
$ frecklecute --help Usage: frecklecute [OPTIONS] FRECKLECUTABLE [ARGS]... Executes a list of tasks specified in a (yaml-formated) text file (called ... ... * more output * ... ... Commands: ansible-task executes an ansible task or role create-adapter create a freckle adapter stub from a template disable-repo ensures the specified repositories are not used by default, no previously enabled repos will be deleted enable-repo ensures the specified repositories are present locally, and used by default update updates freckles itself update-repos updates the trusted repos configured in ~/.freckles/config.yml
frecklecutables in your $PATH¶
As a frecklecutable is really just a text file with a list of tasks, it can also be used as a ‘proper’ exectuable script. In order to use a frecklecutable like that, it needs to have a shebang like such:
#! /usr/bin/env frecklecute doc: help: updates the trusted repos configured in ~/.freckles/config.yml tasks: - makkus.freckles-config: freckles_config_update_repos: true
And, of course, it needs to be executable:
chmod +x <frecklecutable>
After this, you can either add the folder where the frecklecutable lives to your $PATH, or you copy it into a folder that already is included in it. Now you can use your frecklecutable like any other commandline script :-)