Merge branch 'master' into HEAD
[puppet_apt.git] / UPGRADING.md
1 # Introduction
2
3 This aims to document the replacement of the shared apt module by the [puppetlabs](https://github.com/puppetlabs/puppetlabs-apt) one.
4
5 I've tried to look at all the classes supported by our shared module.
6
7 ## Some thoughts on moving to the puppetlabs module
8
9 Whereas the shared module tried to be a coherent mass of code doing all the apt-related things we needed to do, the puppetlabs module takes a more modular approach. This means some of the features we had are not present and will never be added, since "they are not part of the main apt core functionalities"...
10
11 This means we'll have to start using multiple modules as "plugins" to the main puppetlabs apt module.
12
13 # Minor deprecations & warnings
14
15 ## lsb
16 One has to make sure `lsb-release` package is installed. Our shared apt module used to have a dependency on our `lsb` module that did that, but we deprecated that module.
17
18 ## `apt_updated` deprecation
19 The puppetlabs module uses the `apt_update` exec, whereas the shared module uses `apt_updated`. If you where calling this exec in other modules, you'll need to update this for the new exec name.
20
21 ## stdlib
22
23 Make sure your version of stdlib is recent. Mine wasn't and the apt module was failing on the pin functions because the `length` function was missing.
24
25 ## Partial management of the config files by default
26 By default, the puppetlabs apt module only partially manages the apt configuration and will not purge configuration added by hand. This differs from the shared module behavior, where those modifications would get overwritten by our templates.
27
28 To keep the old behavior, pass:
29
30     class { 'apt':
31       purge => {
32         sources.list   => true,
33         sources.list.d => true,
34         preferences    => true,
35         preferences.d  => true,
36       },
37     }
38
39 ## apt sources
40
41 By default, the puppetlabs module won't create any sources. To replicate the shared module template, use this:
42
43     apt::source {
44       $::lsbdistcodename:
45         location => 'http://deb.debian.org/debian',
46         repos    => 'main contrib non-free';
47
48       "${::lsbdistcodename}-security":
49         location => 'http://security.debian.org/debian-security',
50         repos    => 'main contrib non-free',
51         release  => "${::lsbdistcodename}/updates";
52
53       'testing':
54         location => 'http://deb.debian.org/debian',
55         repos    => 'main contrib non-free',
56         release  => "testing";
57     }
58     apt::pin {
59       "${::lsbdistcodename}":
60         priority => 990;
61       'testing':
62         priority => 2;
63     }
64
65
66 Sadly I can't find a way to iter the next codename from the facts :(. You can either use testing instead of "the next release" or specify it manually.
67
68 ## backports
69
70 The module provides a class specifically for deploying the backports repository and pin.
71
72     class { 'apt::backports':
73       pin      => 200,
74       location => 'http://deb.debian.org/debian',
75     }
76
77 # Classes comparison
78
79 ## apticron
80
81 Apticron is not supported by the puppetlabs module either, but [this slightly out of date](https://github.com/dhoppe/puppet-apticron) module from the Forge (the most popular one), although it doesn't state support for Debian 9 and could profit from a little love.
82
83 ## dist_upgrade
84
85 The behavior of the three `dist_upgrade` classes (`apt::cron::dist_upgrade`, `apt::dist_upgrade` and `apt::dist_upgrade::initiator`) are not supported by the puppetlabs module.
86
87 Maybe consider moving to a workflow using `unattended-upgrades`?
88
89 ## dselect
90
91 `dselect` is not supported and nothing seems to do what the shared module feature did.
92
93 ## apt-listchanges
94
95 I ported and upgraded our modules `apt::listchanges` code to a
96 [separate module](https://gitlab.com/baldurmen/puppet-apt_listchanges).
97
98 It basically does the same thing, but in a more modern style. Check the
99 parameters list as types are now defined.
100
101 ## proxy
102
103 Here is how you would configure an apt proxy:
104
105     class { 'apt':
106       proxy => {
107         host  => 'hostname',
108         port  => '8080',
109         https => true,
110        ensure => file,
111       },
112     }
113
114 ## reboot required
115
116 The puppetlabs notice will not manage `reboot-required` like the shared one did, but it creates a fact named `apt_reboot_required` that could be used by some external monitoring system.
117
118 Since it only looks at `/var/run/reboot-required`, it might be a better idea to use something like a combination of the `needrestart` package and an external monitoring system.
119
120 The [needrestart](https://github.com/hetznerZA/hetzner-needrestart) module seems to work well.
121
122 ## unattended-upgrades
123
124 The puppetlabs modules does not support `unattended-upgrades` natively anymore [it used to](https://tickets.puppetlabs.com/browse/MODULES-4943).
125
126 The recommended way to setup this feature is to use the compatible [voxpopuli/unattended-upgrades](https://github.com/voxpupuli/puppet-unattended_upgrades) module.
127
128 The default configuration is quite sane, but you might want to set up automatic upgrades for the stable release too (and not just stable security):
129
130     class { 'unattended_upgrades':
131       origins   => [ 'origin=Debian,archive=stable',
132                      'origin=Debian,archive=stable,label=Debian-Security' ]
133     }
134
135 # Defines comparison
136
137 ## apt confs
138
139 You can using the `apt::conf` define:
140
141     class { 'apt::conf':
142       'whatever_config':
143         ensure        => present,
144         content       => 'foo bar the config you want to see',
145         priority      => '20',
146         notify_update => true,
147     }
148
149 The content part can get quite long, so I would recommend using [heredocs](https://puppet.com/docs/puppet/4.8/lang_data_string.html#heredocs).
150
151 ## preferences_snippet
152
153 The way to pin a package is now [much more fleshed out](https://github.com/puppetlabs/puppetlabs-apt#defined-type-aptpin) and looks like:
154
155     apt::pin { 'certbot':
156       codename => 'buster',
157       packages => [ 'python3-certbot', 'python3-certbot-apache' ],
158     }
159
160 Be aware, as by default if you don't specify a list of packages, this define pins all packages.
161
162 ## apt_packages (preseed)
163
164 As far as I can see, there is nothing in the puppetlabs module that lets you preseed packages.
165
166 ## GPG key management
167
168 The shared module simply used to push a `.gpg` file to `/etc/apt/trusted.gpg.d` to manage GPG keys.
169
170 The puppetlabs module is a bit more sophisticated and lets you either import a key from a source (path, ftp, https, etc.) or fetches keys from a keyserver. 
171
172     apt::key { 'my_local_key':
173       id      => '13C904F0CE085E7C36307985DECF849AA6357FB7',
174       source  => "puppet://files/gpg/13C904F0CE085E7C36307985DECF849AA6357FB7.gpg",
175     }
176
177     apt::key { 'puppetlabs':
178       id      => '6F6B15509CF8E59E6E469F327F438280EF8D349F',
179       server  => 'pgp.mit.edu',
180       options => 'http-proxy="http://proxyuser:proxypass@example.org:3128"',
181     }
182
183 The heavy lifting is done by [these](https://github.com/puppetlabs/puppetlabs-apt/blob/dc3ead0ed5f4d735869565660c982983d379a519/lib/puppet/type/apt_key.rb) [two](https://github.com/puppetlabs/puppetlabs-apt/blob/dc3ead0ed5f4d735869565660c982983d379a519/lib/puppet/provider/apt_key/apt_key.rb) Ruby files.
184
185 ## upgrade_package
186
187 This can be done by using `apt::pin` and specifying a version:
188
189     apt::pin { 'perl':
190       packages => 'perl',
191       version  => '5.26.1-4',
192     }
193
194 ## dpkg_statoverride
195
196 Is there a reason you are using this instead of using `file`?
197
198 ## Facts
199
200 There are a bunch of new and [interesting facts](https://github.com/puppetlabs/puppetlabs-apt#facts).
201
202 # Contributing to the puppetlabs module
203
204 [Submitting a patch seems to be feasible](https://docs.puppet.com/forge/contributing.html), but is also a lot more work than just creating a pull request.
205
206 # Hiera
207
208 Here's some sane Hiera config I'm using. You'll need to specify a `create_ressources` statement somewhere since `apt::pin` is a define:
209
210 ```
211 $aptpins = hiera('apt::pin', {})                                                                                                                            
212 create_resources(apt::pin, $aptpins)
213 ```
214
215 ```
216 classes:
217   - apt
218   - needrestart
219   - unattended_upgrades
220
221 apt::purge:
222   'sources.list': true
223   'sources.list.d': true
224   'preferences': true
225   'preferences.d': true
226
227 apt::sources:
228   "%{facts.lsbdistcodename}":
229     comment: 'Stable'
230     location: 'http://deb.debian.org/debian/'
231     repos: 'main contrib non-free'
232   "%{facts.lsbdistcodename}-security":
233     comment: 'Stable security'
234     location: 'http://security.debian.org/debian-security'
235     repos: 'main contrib non-free'
236     release: "%{facts.lsbdistcodename}/updates"
237   "%{facts.lsbdistcodename}-backports":
238     comment: 'Backports'
239     location: 'http://deb.debian.org/debian/'
240     repos: 'main contrib non-free'
241     release: "%{facts.lsbdistcodename}-backports"
242   'testing':
243     comment: 'Testing'
244     location: 'http://deb.debian.org/debian/'
245     repos: 'main contrib non-free'
246     release: 'testing'
247     
248 apt::pin:
249   "%{facts.lsbdistcodename}":
250     priority: 990
251   "%{facts.lsbdistcodename}-backports":
252     priority: 200
253   'testing':
254     priority: 2
255
256 needrestart::action: automatic
257
258 unattended_upgrades::origins:
259   - origin=Debian,archive=stable
260   - origin=Debian,archive=stable,label=Debian-Security
261 ```