Implement apt package pinning

Registered by Jesse Pretorius


Package pinning helps to provide a 'stable' environment, which is defined as an environment in which changes to the base infrastructure are as controlled as possible.

Note that this blueprint complements the concept of providing a 'frozen repository'. A 'frozen repository' aims to provide a repository which is updated in a controlled fashion. Providing a frozen repository will be handled in a separate blueprint.

Package pinning is a complementary control layer on top of a frozen repository which provides the capability to keep packages at the same level even when the repository has been updated. Package pinning provides the capability to do controlled updates of packages from a (frozen or not frozen) repository, enabling the deployment of updated selected packages from the repository as and when required to selected groups of servers.

Problem Description

In the past it has been discovered that unexpected updates to apt packages have resulted in a destabilised environment.

When a deployer has executed a playbook in order to change configuration or deploy a new host, the result has unexpectedly been that packages get updated. This introduces new problems in the environment that are unrelated to the intended change.

There is a need to allow specified key packages to be kept at a certain version and only updated when specifically intended. This need also includes ensuring that any new hosts added to the environment have the same versions of the same key packages as the rest of the environment.

Proposed Change

I propose that we make use of the debops.apt_preferences Ansible Galaxy role ( in order to handle the actual apt configuration to enable pinning. Documentation for the role is available here:

The advantages of making use of this role are:
1 - It's already written, so we'll be able to join a broader community of developers that share needs and development skills instead of building a role in isolation and carrying the development ourselves.
2 - The role is already in an Ansible Galaxy format.
3 - The role is tested by a test suite for every commit, and therefore is likely to be of high quality.
4 - The debops collection of roles may also be useful for other infrastructure services. It has, for instance, already been suggested as a solution for spec/improved-network-generation.

Playbooks need to be provided which do updates of packages on designated host groups. These updates should respect the package pinning rules.

Playbook Impact

Playbooks will need to be added which provide the capability to execute apt upgrades to packages which are already deployed on each host. It must be possible to deliberately execute these updates separately from any installation of configuration plays.


1 - Continue to do without pinning in any way. This would continue to cause frustrating delays in development as gate checks fail due to unrelated changes. It would also continue to cause frustration in production environments
2 - Only implement infrastructure to provide a 'frozen repository'. While this would have the effect of 'pinning' packages at a specific version, it would not provide the capability to
3 - Implement controlled image-based deployment for all containers, hosts, etc. This is something that would be great, but is a far more complex implementation.

Security Impact

If the package pinning list is not actively maintained by the deployers and the upgrade plays are not executed on a regular schedule then the deployed environment will have the risk of being compromised due to known security issues. This will need to be highlighted in documentation.

Performance Impact


End User Impact


Deployer Impact

There would need to be documentation produced which covers how to:
 - review and change the package pinning list
 - how to run the upgrade configuration plays independently from the install/configuration plays
 - how to upgrade from the method used in icehouse/juno to this new method

Gate checks would need to include:
 - running the upgrade playbooks
 - checking that the pinning preferences were respected
 - completing functional tests after the upgrade

Developer Impact

Developers would need to routinely update any pinning preferences set in the code repository to ensure that they stay current enough without impacting the development process.

Blueprint information

Jesse Pretorius
Needs approval
Jesse Pretorius
Series goal:
Milestone target:
Completed by
Jesse Pretorius


A key question that does need to be asked is whether this actually belongs in os-ansible-deployment? A precedent has been set in that we provide infrastructure for a frozen python repository, but then perhaps the question should be asked whether that belongs in os-ansible-deployment too. Should these perhaps be provided publically via other means and the deployer can decide whether they wish to make use of these facilities or not?

The packages to pin and the process for updating them needs to be decided.
 - Do we update the pinning list after every patch tag, after every minor release or after every major release?
 - Do we deal with branches differently to the tagged releases?
 - How do we handle security updates to pinned packages? Do we update the pinning preference as part of a patch update?

 - Do we include the upgrade plays inside the installation plays?
 - Do we include the upgrade plays inside the configuration plays?
 - Are playbooks currently designed to allow the separate execution of installation and configuration tasks? If not, should this be changed? I would think that this would provide a deployer with more control over what happens when. It also lays the foundation for implementing image-based deployment - images would only require installation/upgrade plays, not configuration plays. Perhaps the right approach here would be to have '-all' plays which include '-install', '-upgrade' and '-config' plays.

[jpretorius/odyssey4me 11 Mar 2015]
apt-pinning is easily enough implemented by a deployer should they wish to, but it's not seen as something that belongs in this repository at this stage


Work Items

This blueprint contains Public information 
Everyone can see this information.


No subscribers.