1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
|
Introduction
============
Concepts and terminology
------------------------
Host
~~~~
A machine, container, chroot, or similar. Has a plist of static informational
*host attributes*, usually including at least a hostname, and a property
application specification defining the properties it has.
Property
~~~~~~~~
Some configuration which a host can have or lack, and which can be added to
a host by running some code, possibly just by applying a series of other
properties.
For example: the presence of some lines in a config file; a package being
installed or absent; the availability of a website.
Connection
~~~~~~~~~~
A means by which properties can be applied to hosts, and multihop connections
to other hosts can be established. There are two types of connections: those
which interact with the remote host by means of a POSIX shell, and those which
apply properties by executing them in a Lisp image running on the host.
POSIX connections can pass input to and return output from processes, but
cannot start asynchronous processes for interaction with your Lisp functions.
This is so that POSIX connections can be defined to control hosts for which
any kind of shell multiplexing is hard or impossible, such as with serial
connections providing only a single interactive POSIX sh. For asynchronous
interaction, use a Lisp connection.
Deployment
~~~~~~~~~~
The combination of a connection and a host. Executing a connection deploys
all of a host's usual properties to that host by means of the given
connection. To deploy just a few particular properties, you can use
``DEPLOY-THESE``.
A deployment is itself a property. This is one way in which connections can
be nested: one remote host can be used to deploy others, as a controller.
Root Lisp
~~~~~~~~~
The Lisp image you control directly when you execute deployments. Typically
running on your development laptop/workstation (and not as the ``root`` user).
Property application specification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
An ordered list specifying the properties that a host has and/or lacks. For
example,::
'((apt:installed postfix)
(etc-default:set "locale" "LANG" "en_GB.UTF-8")
(unapply (com.example.consfig.services:mail-satellite)))
Property application specifications are always applied in order, so properties
later in the list implicitly depend on properties earlier in the list.
Unevaluated property application specification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A property application specification, except in atomic property applications
of the form ``(PROPERTY . ARGS)``, ``ARGS`` are expressions to be evaluated to
produce the arguments to pass to ``PROPERTY``, rather than those arguments
themselves. An unevaluated property application specification can be
converted into a property application specification by evaluating each of
``ARGS``.
The main place you will find an unevaluated property application specification
is in a call to ``DEFHOST``. That macro converts an unevaluated property
application specification into code which will produce the corresponding
property application specification.
Prerequisite data
~~~~~~~~~~~~~~~~~
File contents required to apply a property which should be generated or
extracted, by the root Lisp, at the time of deployment: a tarball containing
the latest version of the web service to be deployed; a secret extracted from
an encrypted store; a git bundle from localhost which the target host cannot
just ``git clone`` to itself.
Prerequisite data is versioned. To replace a secret key, for example, you
change the data and bump the version. If there is no version bump,
Consfigurator will assume connections can re-use old copies of prerequisite
data; this avoids uploading the same data over and over again.
In addition to secrets management, prerequisite data is Consfigurator's
mechanism for the common need to upload files to controlled hosts. The same
mechanism is used internally to upload the Lisp code needed to start up remote
Lisp images for ``:lisp`` connections.
Consfig
~~~~~~~
An ASDF system in which you define your hosts and initialise sources of
prerequisite data. This system might also define some site-specific
properties, default deployments, and helper functions. Typically the system
is named ``COM.EXAMPLE.CONSFIG`` where ``example.com`` is your primary domain
name.
The system can contain multiple packages, perhaps to divide up your
definitions of hosts and default deployments from your site-specific
properties (e.g. you might have a package called
``COM.EXAMPLE.CONSFIG.SITES``).
You can have multiple independent Consfigs loaded into the root Lisp at once,
but if you do, then you should avoid using the ``*CONSFIG*`` global variable.
Documentation conventions
-------------------------
All unqualified names of Lisp symbols refer to those exported from the
``CONSFIGURATOR`` package, because it is assumed that this package is imported
unqualified into both user consfigs and Lisp packages providing properties,
connection types and sources of prerequisite data.
``FOO.BAR:BAZ`` means a symbol ``BAZ`` defined in
``CONSFIGURATOR.PROPERTY.FOO.BAR``, except that ``DATA.FOO:BAR`` means a
symbol ``BAR`` defined in ``CONSFIGURATOR.PROPERTY.DATA.FOO``. These are the
recommended package nicknaming schemes for use in consfigs, e.g.::
(defpackage :com.example.consfig
(:use #:cl #:consfigurator)
(:local-nicknames (#:file #:consfigurator.property.file
#:data.pgp #:consfigurator.data.pgp)))
|
