Improve system documentation
[cacert-infradocs.git] / docs / systems / puppet.rst
1 .. index::
2 single: Systems; Puppet
3
4 ======
5 Puppet
6 ======
7
8 Purpose
9 =======
10
11 This system acts as `Puppet`_ master for infrastructure systems.
12
13 .. _Puppet: https://docs.puppet.com/puppet/
14
15 Application Links
16 -----------------
17
18 This system has no publicly visible URLs.
19
20
21 Administration
22 ==============
23
24 System Administration
25 ---------------------
26
27 * Primary: :ref:`people_jandd`
28 * Secondary: None
29
30 .. todo:: find an additional admin
31
32 Application Administration
33 --------------------------
34
35 +---------------+---------------------+
36 | Application | Administrator(s) |
37 +===============+=====================+
38 | Puppet server | :ref:`people_jandd` |
39 +---------------+---------------------+
40 | PuppetDB | :ref:`people_jandd` |
41 +---------------+---------------------+
42
43 Contact
44 -------
45
46 * puppet-admin@cacert.org
47
48 Additional People
49 -----------------
50
51 * None
52
53 Basics
54 ======
55
56 Physical Location
57 -----------------
58
59 This system is located in an :term:`LXC` container on physical machine
60 :doc:`infra02`.
61
62 Logical Location
63 ----------------
64
65 :IP Internet: None
66 :IP Intranet: None
67 :IP Internal: :ip:v4:`10.0.0.200`
68 :IPv6: :ip:v6:`2001:7b8:616:162:2::200`
69 :MAC address: :mac:`00:ff:f9:32:9d:2a` (eth0)
70
71 .. seealso::
72
73 See :doc:`../network`
74
75 .. index::
76 single: Monitoring; Puppet
77
78 Monitoring
79 ----------
80
81 :internal checks: :monitor:`puppet.infra.cacert.org`
82
83 DNS
84 ---
85
86 .. index::
87 single: DNS records; Puppet
88
89 .. todo:: setup DNS records (in infra.cacert.org zone)
90
91 .. seealso::
92
93 See :wiki:`SystemAdministration/Procedures/DNSChanges`
94
95 Operating System
96 ----------------
97
98 .. index::
99 single: Debian GNU/Linux; Stretch
100 single: Debian GNU/Linux; 9.4
101
102 * Debian GNU/Linux 9.4
103
104 Applicable Documentation
105 ------------------------
106
107 This is it :-)
108
109 Services
110 ========
111
112 Listening services
113 ------------------
114
115 +----------+-----------+-----------+------------------------------------------+
116 | Port | Service | Origin | Purpose |
117 +==========+===========+===========+==========================================+
118 | 22/tcp | ssh | ANY | admin console access |
119 +----------+-----------+-----------+------------------------------------------+
120 | 25/tcp | smtp | local | mail delivery to local MTA |
121 +----------+-----------+-----------+------------------------------------------+
122 | 5432/tcp | pgsql | local | PostgreSQL database for PuppetDB |
123 +----------+-----------+-----------+------------------------------------------+
124 | 8000/tcp | git-hook | internal | HTTP endpoint for git-pull-hook |
125 +----------+-----------+-----------+------------------------------------------+
126 | 8140/tcp | puppet | internal | Puppet master |
127 +----------+-----------+-----------+------------------------------------------+
128 | 8080/tcp | puppetdb | local | HTTP endpoint for local PuppetDB queries |
129 +----------+-----------+-----------+------------------------------------------+
130 | 8081/tcp | puppetdb | internal | HTTPS endpoint for PuppetDB |
131 +----------+-----------+-----------+------------------------------------------+
132
133 Running services
134 ----------------
135
136 .. index::
137 single: cron
138 single: exim
139 single: git-pull-hook
140 single: openssh
141 single: postgresql
142 single: puppet agent
143 single: puppet server
144 single: puppetdb
145 single: rsyslog
146
147 +--------------------+--------------------+----------------------------------------+
148 | Service | Usage | Start mechanism |
149 +====================+====================+========================================+
150 | cron | job scheduler | init script :file:`/etc/init.d/cron` |
151 +--------------------+--------------------+----------------------------------------+
152 | Exim | SMTP server for | init script |
153 | | local mail | :file:`/etc/init.d/exim4` |
154 | | submission | |
155 +--------------------+--------------------+----------------------------------------+
156 | git-pull-hook | Custom Python3 | init script |
157 | | hook to pull git | :file:`/etc/init.d/git-pull-hook` |
158 | | changes from the | |
159 | | cacert-puppet | |
160 | | repository | |
161 +--------------------+--------------------+----------------------------------------+
162 | openssh server | ssh daemon for | init script :file:`/etc/init.d/ssh` |
163 | | remote | |
164 | | administration | |
165 +--------------------+--------------------+----------------------------------------+
166 | PostgreSQL | PostgreSQL | init script |
167 | | database server | :file:`/etc/init.d/postgresql` |
168 | | for PuppetDB | |
169 +--------------------+--------------------+----------------------------------------+
170 | Puppet server | Puppet master for | init script |
171 | | infrastructure | :file:`/etc/init.d/puppetserver` |
172 | | systems | |
173 +--------------------+--------------------+----------------------------------------+
174 | Puppet agent | local Puppet agent | init script |
175 | | | :file:`/etc/init.d/puppet` |
176 +--------------------+--------------------+----------------------------------------+
177 | PuppetDB | PuppetDB for | init script |
178 | | querying Puppet | :file:`/etc/init.d/puppetdb` |
179 | | facts and nodes | |
180 | | and resources | |
181 +--------------------+--------------------+----------------------------------------+
182 | rsyslog | syslog daemon | init script |
183 | | | :file:`/etc/init.d/syslog` |
184 +--------------------+--------------------+----------------------------------------+
185
186 Databases
187 ---------
188
189 +-------------+----------+-------------------+
190 | RDBMS | Name | Used for |
191 +=============+==========+===================+
192 | PostgreSQL | puppetdb | PuppetDB database |
193 +-------------+----------+-------------------+
194
195 Connected Systems
196 -----------------
197
198 * :doc:`bugs`
199 * :doc:`emailout`
200 * :doc:`ircserver`
201 * :doc:`issue`
202 * :doc:`jenkins`
203 * :doc:`monitor`
204 * :doc:`motion`
205 * :doc:`proxyin`
206 * :doc:`proxyout`
207 * :doc:`svn`
208 * :doc:`translations`
209 * :doc:`web`
210 * :doc:`webstatic`
211 * :doc:`git` for triggering the git-pull-hook on newly pushed commits to the
212 cacert-puppet repository
213
214 Outbound network connections
215 ----------------------------
216
217 * :doc:`infra02` as resolving nameserver
218 * :doc:`emailout` as SMTP relay
219 * :doc:`git` to fetch new commits from the cacert-puppet repository
220 * :doc:`proxyout` as HTTP proxy for APT
221 * forgeapi.puppet.com for Puppet forge access
222 * rubygems.org for Puppet specific Ruby gems
223
224 Security
225 ========
226
227 .. sshkeys::
228 :RSA: SHA256:PPEZkD7ezGStENYmE9/RftHqJyy6cC9IN6zw63OvJTM MD5:54:57:b0:09:46:ba:56:95:5e:e3:35:df:28:27:ed:c5
229 :ECDSA: SHA256:3U1CVC9YAKmF9W5SDLibwP1A9MVSb5ltVN7nYNOE15o MD5:29:06:f1:71:8d:65:3e:39:7c:49:69:16:8d:99:97:15
230 :ED25519: SHA256:AkqMLLEtMbAEuxniRRDgd7TItD+pb9hsbpn5Ab81+IM MD5:53:dc:e7:4d:25:89:a8:d5:5a:24:0b:06:3f:41:cd:4d
231
232 Non-distribution packages and modifications
233 -------------------------------------------
234
235 The Puppet server, Puppet agent and PuppetDB packages and a few dependencies
236 are installed from the official Puppet APT repository because the versions
237 in Debian are too old to use modern Puppet features.
238
239 Some rubygems are installed via the puppet specific ruby gem binary to support
240 advanced Puppet functionality like hiera-eyaml.
241
242 All puppet related code is installed in the Puppet specific /opt/puppetlabs
243 tree.
244
245 Risk assessments on critical packages
246 -------------------------------------
247
248 The system uses third party packages with a good security track record and
249 regular updates. The attack surface is small due to the tightly restricted
250 access to the system.
251
252 Critical Configuration items
253 ============================
254
255 Keys and X.509 certificates
256 ---------------------------
257
258 Puppet comes with its own inbuilt special purpose CA that is used to sign the
259 Puppet server and Puppet DB certificates as well as the certificates of all
260 trusted Puppet agents.
261
262 The CA data is stored in :file:`/etc/puppetlabs/puppet/ssl` and managed by
263 puppet itself.
264
265 Eyaml private key
266 -----------------
267
268 All sensitive data like passwords in Hiera data is encrypted using the public
269 key in :file:`keys/public_key.pkcs7.pem` in the `CAcert puppet Git repository
270 <ssh://git.cacert.org/var/cache/git/cacert-puppet.git>`_. The corresponding
271 private key is stored in
272 :file:`/etc/puppetlabs/code/environments/production/keys/private_key.pkcs7.pem`.
273
274 hiera configuration
275 -------------------
276
277 Puppet uses Hiera for hierarchical information retrieval. The global hiera
278 configuration is stored in :file:`/etc/puppetlabs/puppet/hiera.yaml` and
279 defines the hierarchy lookup as well as the eyaml key locations.
280
281 puppet configuration
282 --------------------
283
284 All puppet configuration is stored in :file:`/etc/puppetlabs/`. The CAcert
285 specific puppet code is taken from the `CAcert puppet Git repository
286 <ssh://git.cacert.org/var/cache/git/cacert-puppet.git>`_ and cloned to
287 :file:`/etc/puppetlabs/code/environments/production/` directory. Required
288 Puppet modules are installed by :program:`/opt/puppetlabs/puppet/bin/r10k`.
289
290 The puppet code should follow best practices like the Roles and profiles
291 pattern (see references below) and code/data separation via Hiera.
292
293 Updates to the cacert-puppet repository trigger a web hook listening on tcp
294 port 8000 that automatically updates the production environment directory.
295
296 Tasks
297 =====
298
299 .. todo:: add a section to describe how to add a system for puppet management
300
301 Changes
302 =======
303
304 Planned
305 -------
306
307 * migrate as many systems as possible to use Puppet for a more
308 reproducible/auditable system setup
309
310 System Future
311 -------------
312
313 * Improve setup, use more widely
314
315 Additional documentation
316 ========================
317
318 .. seealso::
319
320 * :wiki:`Exim4Configuration`
321
322 References
323 ----------
324
325 * https://docs.puppet.com/puppet/
326 * https://puppet.com/blog/encrypt-your-data-using-hiera-eyaml
327 * https://docs.puppet.com/pe/2016.5/r_n_p_full_example.html