-`apt` provides a number of common resources and options that are shared by the various defined types in this module, so you MUST always include this class in your manifests.
-
-The parameters for `apt` are not required in general and are predominantly for development environment use-cases.
-
- class { 'apt':
- always_apt_update => false,
- disable_keys => undef,
- proxy_host => false,
- proxy_port => '8080',
- purge_sources_list => false,
- purge_sources_list_d => false,
- purge_preferences_d => false,
- update_timeout => undef
- }
-
-Puppet will manage your system's `sources.list` file and `sources.list.d` directory but will do its best to respect existing content.
-
-If you declare your apt class with `purge_sources_list` and `purge_sources_list_d` set to 'true', Puppet will unapologetically purge any existing content it finds that wasn't declared with Puppet.
-
-### apt::builddep
-
-Installs the build depends of a specified package.
-
- apt::builddep { 'glusterfs-server': }
-
-### apt::force
-
-Forces a package to be installed from a specific release. This class is particularly useful when using repositories, like Debian, that are unstable in Ubuntu.
-
- apt::force { 'glusterfs-server':
- release => 'unstable',
- version => '3.0.3',
- require => Apt::Source['debian_unstable'],
- }
-
-### apt_key
-
-A native Puppet type and provider for managing GPG keys for APT is provided by
-this module.
-
- apt_key { 'puppetlabs':
- ensure => 'present',
- id => '4BD6EC30',
- }
-
-You can additionally set the following attributes:
-
- * `source`: HTTP, HTTPS or FTP location of a GPG key or path to a file on the
- target host;
- * `content`: Instead of pointing to a file, pass the key in as a string;
- * `server`: The GPG key server to use. It defaults to *keyserver.ubuntu.com*;
- * `keyserver_options`: Additional options to pass to `--keyserver`.
-
-Because it is a native type it can be used in and queried for with MCollective.
-
-### apt::key
-
-Adds a key to the list of keys used by APT to authenticate packages. This type
-uses the aforementioned `apt_key` native type. As such it no longer requires
-the wget command that the old implementation depended on.
-
- apt::key { 'puppetlabs':
- key => '4BD6EC30',
- key_server => 'pgp.mit.edu',
- }
-
- apt::key { 'jenkins':
- key => 'D50582E6',
- key_source => 'http://pkg.jenkins-ci.org/debian/jenkins-ci.org.key',
- }
-
-### apt::pin
-
-Adds an apt pin for a certain release.
-
- apt::pin { 'karmic': priority => 700 }
- apt::pin { 'karmic-updates': priority => 700 }
- apt::pin { 'karmic-security': priority => 700 }
-
-Note you can also specifying more complex pins using distribution properties.
-
- apt::pin { 'stable':
- priority => -10,
- originator => 'Debian',
- release_version => '3.0',
- component => 'main',
- label => 'Debian'
- }
-
-If you wish to pin a number of packages you may specify the packages as a space
-delimited string using the `packages` attribute or pass in an array of package
-names.
-
-### apt::hold
-
-When you wish to hold a package in Puppet is should be done by passing in
-'held' as the ensure attribute to the package resource. However, a lot of
-public modules do not take this into account and generally do not work well
-with an ensure of 'held'.
-
-There is an additional issue that when Puppet is told to hold a package, it
-will hold it at the current version installed, there is no way to tell it in
-one go to install a specific version and then hold that version without using
-an exec resource that wraps `dpkg --set-selections` or `apt-mark`.
-
-At first glance this could also be solved by just passing the version required
-to the ensure attribute but that only means that Puppet will install that
-version once it processes that package. It does not inform apt that we want
-this package to be held. In other words; if another package somehow wants to
-upgrade this one (because of a version requirement in a dependency), apt
-should not allow it.
-
-In order to solve this you can use apt::hold. It's implemented by creating
-a preferences file with a priority of 1001, meaning that under normal
-circumstances this preference will always win. Because the priority is > 1000
-apt will interpret this as 'this should be the version installed and I am
-allowed to downgrade the current package if needed'.
-
-With this you can now set a package's ensure attribute to 'latest' but still
-get the version specified by apt::hold. You can do it like this:
-
- apt::hold { 'vim':
- version => '2:7.3.547-7',
- }
-
-Since you might just want to hold Vim at version 7.3 and not care about the
-rest you can also pass in a version with a glob:
-
- apt::hold { 'vim':
- version => '2:7.3.*',
- }
-
-### apt::ppa
-
-Adds a ppa repository using `add-apt-repository`.
-
- apt::ppa { 'ppa:drizzle-developers/ppa': }
-
-### apt::release
-
-Sets the default apt release. This class is particularly useful when using repositories, like Debian, that are unstable in Ubuntu.
-
- class { 'apt::release':
- release_id => 'precise',
- }
+```puppet
+apt::pin { 'stable':
+ priority => -10,
+ originator => 'Debian',
+ release_version => '3.0',
+ component => 'main',
+ label => 'Debian'
+}
+```
+
+To pin multiple packages, pass them to the `packages` parameter as an array or a space-delimited string.
+
+<a id="add-a-personal-package-archive-repository"></a>
+### Add a Personal Package Archive (PPA) repository
+
+```puppet
+apt::ppa { 'ppa:drizzle-developers/ppa': }
+```
+
+### Add an Apt source to `/etc/apt/sources.list.d/`
+
+```puppet
+apt::source { 'debian_unstable':
+ comment => 'This is the iWeb Debian unstable mirror',
+ location => 'http://debian.mirror.iweb.ca/debian/',
+ release => 'unstable',
+ repos => 'main contrib non-free',
+ pin => '-10',
+ key => {
+ 'id' => 'A1BD8E9D78F7FE5C3E65D8AF8B48AD6246925553',
+ 'server' => 'subkeys.pgp.net',
+ },
+ include => {
+ 'src' => true,
+ 'deb' => true,
+ },
+}
+```
+
+To use the Puppet Apt repository as a source:
+
+```puppet
+apt::source { 'puppetlabs':
+ location => 'http://apt.puppetlabs.com',
+ repos => 'main',
+ key => {
+ 'id' => '6F6B15509CF8E59E6E469F327F438280EF8D349F',
+ 'server' => 'pgp.mit.edu',
+ },
+}
+```
+
+<a id="configure-apt-from-hiera"></a>
+### Configure Apt from Hiera
+
+Instead of specifying your sources directly as resources, you can instead just include the `apt` class, which will pick up the values automatically from hiera.
+
+```yaml
+apt::sources:
+ 'debian_unstable':
+ comment: 'This is the iWeb Debian unstable mirror'
+ location: 'http://debian.mirror.iweb.ca/debian/'
+ release: 'unstable'
+ repos: 'main contrib non-free'
+ pin: '-10'
+ key:
+ id: 'A1BD8E9D78F7FE5C3E65D8AF8B48AD6246925553'
+ server: 'subkeys.pgp.net'
+ include:
+ src: true
+ deb: true