Glossary

Farmer (grlx-farmer)

The farmer is your management server running the grlx-farmer binary. The binary can run as a systemd service or be hosted in a container. This has analogs in other similar configuration platforms. In SaltStack, this is your Salt Master, or in Chef, your Chef Server. grlx utilizes the farmer for things like authentication, job processing, and ingredients.

Sprout (grlx-sprout)

The sprout is a managed node running the grlx-sprout binary. Sprouts receive commands from the farmer over the NATS message bus. These can be immediate shell commands, or actions that are performed by Ingredients defined in a recipe (e.g. ensure that a file exists). Sprouts are similar to a Salt Minion in SaltStack or a Chef Client in Chef.

CLI (grlx CLI)

The CLI is a tool used to interact with the farmer and manage sprouts. The CLI is used to accept keys from sprouts and cook (run) recipes that are hosted on the farmer. The CLI also contains tools to tail the traffic over the NAT bus, test sprout connections, and run arbitrary commands on sprouts.

Authentication

All communication is encrypted using self-signed TLS certificates and NATS.io NKey encryption. Certificates are pinned to the clients on first connection as an extra security precaution. Furthermore, every CLI must accept a working certificate for any interactions with the farmer. NKeys provides a NATS native method for handling asymmetric encryption of messages between all parts of the system.

Command Execution

The CLI has the ability to dispatch arbitrary shell commands to sprouts using grlx cmd run. Jobs are evaluated and dispatched to sprouts and their outputs are aggregated to the output of the CLI. Furthermore, this can be used inside of recipes for more structured deployments.

Farmer Hooks (hooks)

Hooks provide a way to fire off webhooks when recipe deployment (cook) starts, fails or finishes. Additionally, you can configure a hook to fire when a new sprout is added to the farm, or when a sprout’s status has changed. A “hook” ingredient is also provided (not shown) that can be fired from the sprout during steps of a recipe.

Ingredients

Ingredients are how we build configurations with grlx. They can be thought of as the building blocks for completing various file, service, or management operations. Ingredients use a provider interface to allow for simple extensibility via the Go plugin system.

Template Engine

Templating is achieved with Go’s builtin templating engine. This provides a Jinja-like templating system that hooks into the Farmer and Sprout properties to customize recipes to meet the dynamic needs of your needs.

Job Enqueuing and Processing

You initiate jobs from the CLI by cooking recipes. Processing is continued on the farmer, and sprouts stream results to the CLI in real-time over the message bus.

Properties (Farmer, Sprout and Fetched Sprout Props)

Both farmers and sprouts have properties for use in recipes. These properties are used in recipe templates to specify conditional execution of parts of the recipe. One example of this might be the specific OS or architecture of a sprout to ensure that the correct package gets installed on the correct machine.

API

Each farmer has a REST API used for querying information about jobs or other information the farmer has access to. API tokens can be generated by the grlx auth token.

Local API

The Local API is hosted on the grlx CLI to run a web frontend application for grlx. The local API provides a simple yet extensible interface for interacting with the CLI without the need for a terminal.

Message Bus

An embedded NATS.io server is built into the farmer to handle connection between the sprouts, farmer, and the CLI. The bus uses NKeys to handle secure message passing between sprouts, the farmer, and CLIs. The message bus is responsible for handling communication between the CLI and the farmer as well as ensuring that jobs get dispatched to sprouts.

Managed Node

The managed node is where the grlx-sprout daemon runs. It is the physical device where a sprout will deploy files, manage services, or run commands.