CFEngine Sketch Core Concepts

To make full use of the resources in the CFEngine Design Center you will need to understand some of the basics about CFEngine Sketches. What are they? What assumptions were made about how they would be used? And, what are some of the basic features that make a CFengine Sketch useful?

The following sections outline some of these basic Sketch concepts which are essential to understand before you start using and customizing CFEngine Sketches.

How is a Sketch Distributed in a CFEngine Installation?

While you can run cf-sketch from any machine in a CFEngine installation, most users run cf-sketch from a CFEngine Policy Hub.

If you set up your API's config.json configuration to install under your masterfiles directory (see Introduction to Design Center API) then any sketches you install will automatically be distributed to all of your CFEngine clients. If you put the runfile location under masterfiles then it will be distributed as well.

For example, if you need to manage cron across all of your CFEngine-managed machines, run the cf-sketch tool on the Policy Hub (with the directory assumptions above), install and activate this cron sketch, and the policies associated with this sketch will be distributed to every machine in a CFEngine installation.

You can also run cf-sketch from a CFEngine client if you need to selectively deploy a recipe to a single machine. This approach is useful if you are testing a Sketch and need to test a Sketch's policy on a single machine before deploying it to an entire CFEngine installation. In a production environment, a CFEngine administrator will often set aside a few machines as Sketch testing machines, installing Sketches locally and testing before deploying to the entire network. The config.json API configuration needs to point to a subdirectory of your inputs directory, then.

Where are Sketches Executed?

Installing and distributing a sketch through your policy hub does not mean that it will necessarily be executed on all your machines. For each sketch, you can determine under which conditions it will be activated. The activated condition is expressed as a CFEngine class expression, and thus can be arbitrarily complex and involve any conditions available to CFEngine.

For example, if you want the [System::tzconfig] sketch to be executed only on Linux machines, you could set its activated parameter to linux, which is a hard class that is automatically set on Linux systems. But the conditions could be arbitrarily complex. If you have a sketch that you only want to execute on your web servers (assuming those have a class webserver defined) on Mondays, you could set activated to webserver.Mon.

With cf-sketch, this activated class is automatically in the cf_sketch_testing run environment. If you use the Design Center API (see Introduction to Design Center API) you can create multiple run environments and apply different activated classes to every activation.

Where are Sketches Installed? Where does cf-sketch find Sketches?

Sketches are installed by the Design Center API according to the config.json configuration.

See Introduction to Design Center API for details on this configuration.

config.json also tells the API where to look for sketches. You simply give the correct recognized_sources value for your environment. For instance, it could be https://github.com/cfengine/design-center/tree/master/sketches/cfsketches.json if you wanted to use the Design Center GitHub repository, located at https://github.com/cfengine/design-center. Or it could be the local location of your Design Center checkout. Remember that every web request can fail, so you probably want your permanent recognized_sources to point to a local directory.

While the goal of the CFEngine Design Center is to provide a set of reliable, widely shared recipes for common infrastructure, we realize that custom requirements are an unavoidable reality. Many users will want to customize Sketches and provide new Sketches that meet the unique requirements of their CFEngine installation.

To add new Sketches or to override existing Sketches, just add your own repository to the recognized_sources list. It needs the same cfsketches.json file format as the main Design Center repository. See Writing DC Sketches for information on writing your own Design Center sketches.

The Lifecycle of a Sketch

When discussing the state of a Sketch, it is important to understand the lifecycle of a Sketch as it relates to a particular CFEngine installation. If you are installing, configuring, and depoying Sketches the following diagram of the lifecycle of a Sketch illustrates the four states a Sketch can be in:

A Sketch can be in one of the following states:

• Uninstalled: The Sketch has not been downloaded to the system.
• Installed: The Sketch has been installed on the system, but no parameters have been specified. Many Sketches require configuration parameters to be set before they can be used.
• Configured: One or more "configuration parameter sets" have been created, each one containing all the necessary parameters for the Sketch to function. Note that configuration parameter sets can be shared between sketches.
• Activated: One or more configuration instances have been activated by specifying a CFEngine class expression that controls where they will be executed. Once a Sketch has been activated, CFEngine clients will begin enforcing the policies contained in a Sketch.

Integrating Sketches into Existing Policies

To integrate sketches into the execution flow of your existing CFEngine policies, you need to generate a runfile using the Design Center API. The runfile sets all the appropriate parameters for active sketches, and calls the appropriate bundles. The runfile can be standalone or not. See Introduction to Design Center API for information about configuring the runfile through config.json.