-
Notifications
You must be signed in to change notification settings - Fork 68
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.
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.
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.
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.
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.
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
.
A public repository for customizable CFEngine design patterns and code.