Apt Operations¶
Manage apt packages and repositories.
Facts used in these operations: apt.AptKeys, apt.AptSources, server.Date, deb.DebPackage, deb.DebPackages, files.File, gpg.GpgKey, apt.SimulateOperationWillChange.
apt.deb¶
Add/remove .deb file packages.
apt.deb(src: str, present=True, force=False, **kwargs)
- src: filename or URL of the - .debfile
- present: whether or not the package should exist on the system 
- force: whether to force the package install by passing –force-yes to apt 
- Note:
- When installing, - apt-get install -fwill be run to install any unmet dependencies.
- URL sources with present=False:
- If the - .debfile isn’t downloaded, pyinfra can’t remove any existing package as the file won’t exist until mid-deploy.
Example:
# Note: Assumes wget is installed.
apt.deb(
    name="Install Chrome via deb",
    src="https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb",
)
- Note:
- This operation also inherits all global arguments. 
apt.dist_upgrade¶
Updates all apt packages, employing dist-upgrade.
apt.dist_upgrade(auto_remove: bool=False, **kwargs)
- auto_remove: removes transitive dependencies that are no longer needed. 
Example:
apt.dist_upgrade(
    name="Upgrade apt packages using dist-upgrade",
)
- Note:
- This operation also inherits all global arguments. 
apt.key¶
Add apt gpg keys with apt-key.
apt.key(
    src: str | None=None, keyserver: str | None=None, keyid: str | list[str] | None=None,
    **kwargs,
)
- src: filename or URL 
- keyserver: URL of keyserver to fetch key from 
- keyid: key ID or list of key IDs when using keyserver 
- keyserver/id:
- These must be provided together. 
Warning
apt-key is deprecated in Debian, it is recommended NOT to use this
operation and instead follow the instructions here:
Examples:
# Note: If using URL, wget is assumed to be installed.
apt.key(
    name="Add the Docker apt gpg key",
    src="https://download.docker.com/linux/ubuntu/gpg",
)
apt.key(
    name="Install VirtualBox key",
    src="https://www.virtualbox.org/download/oracle_vbox_2016.asc",
)
- Note:
- This operation also inherits all global arguments. 
apt.packages¶
Install/remove/update packages & update apt.
apt.packages(
    packages: str | list[str] | None=None, present=True, latest=False, update=False,
    cache_time: int | None=None, upgrade=False, force=False, no_recommends=False,
    allow_downgrades=False, extra_install_args: str | None=None,
    extra_uninstall_args: str | None=None, **kwargs,
)
- packages: list of packages to ensure 
- present: whether the packages should be installed 
- latest: whether to upgrade packages without a specified version 
- update: run - apt updatebefore installing packages
- cache_time: when used with - update, cache for this many seconds
- upgrade: run - apt upgradebefore installing packages
- force: whether to force package installs by passing –force-yes to apt 
- no_recommends: don’t install recommended packages 
- allow_downgrades: allow downgrading packages with version (–allow-downgrades) 
- extra_install_args: additional arguments to the apt install command 
- extra_uninstall_args: additional arguments to the apt uninstall command 
- Versions:
- Package versions can be pinned like apt: - <pkg>=<version>
- Cache time:
- When - cache_timeis set the- /var/lib/apt/periodic/update-success-stampfile is touched upon successful update. Some distros already do this (Ubuntu), but others simply leave the periodic directory empty (Debian).
Examples:
# Update package list and install packages
apt.packages(
    name="Install Asterisk and Vim",
    packages=["asterisk", "vim"],
    update=True,
)
# Install the latest versions of packages (always check)
apt.packages(
    name="Install latest Vim",
    packages=["vim"],
    latest=True,
)
# Note: host.get_fact(OsVersion) is the same as `uname -r` (ex: '4.15.0-72-generic')
apt.packages(
    name="Install kernel headers",
    packages=[f"linux-headers-{host.get_fact(OsVersion)}"],
    update=True,
)
- Note:
- This operation also inherits all global arguments. 
apt.ppa¶
Stateless operation
This operation will always execute commands and is not idempotent.
Add/remove Ubuntu ppa repositories.
apt.ppa(src: str, present=True, **kwargs)
- src: the PPA name (full ppa:user/repo format) 
- present: whether it should exist 
- Note:
- requires - apt-add-repositoryon the remote host
Example:
# Note: Assumes software-properties-common is installed.
apt.ppa(
    name="Add the Bitcoin ppa",
    src="ppa:bitcoin/bitcoin",
)
- Note:
- This operation also inherits all global arguments. 
apt.repo¶
Add/remove apt repositories.
apt.repo(src: str, present=True, filename: str | None=None, **kwargs)
- src: apt source string eg - deb http://X hardy main
- present: whether the repo should exist on the system 
- filename: optional filename to use - /etc/apt/sources.list.d/<filename>.list. By default uses- /etc/apt/sources.list.
Example:
apt.repo(
    name="Install VirtualBox repo",
    src="deb https://download.virtualbox.org/virtualbox/debian bionic contrib",
)
- Note:
- This operation also inherits all global arguments. 
apt.update¶
Stateless operation
This operation will always execute commands unless the cache_time argument is provided.
Updates apt repositories.
apt.update(cache_time: int | None=None, **kwargs)
- cache_time: cache updates for this many seconds 
Example:
apt.update(
    name="Update apt repositories",
    cache_time=3600,
)
- Note:
- This operation also inherits all global arguments. 
apt.upgrade¶
Upgrades all apt packages.
apt.upgrade(auto_remove: bool=False, **kwargs)
- auto_remove: removes transitive dependencies that are no longer needed. 
Example:
# Upgrade all packages
apt.upgrade(
    name="Upgrade apt packages",
)
# Upgrade all packages and remove unneeded transitive dependencies
apt.upgrade(
    name="Upgrade apt packages and remove unneeded dependencies",
    auto_remove=True
)
- Note:
- This operation also inherits all global arguments. 
 pyinfra 3.x
            pyinfra 3.x