Store¶

Deptool stores cluster configuration in a Git repository called the store. It stores all config trees that were ever deployed to the cluster. The store exists as a bare Git repository on the operator machine, by default in .deptool. It also exists as a bare repository on every target host in /var/lib/deptool/store.

Data model¶

A config tree defines the desired state for the entire cluster, as outlined in the directory layout chapter. Upon deploy, Deptool records the config tree in the store as one Git tree per host directory.

Every deployment is a commit that points to the subdirectory of the config tree we deployed or attempted to deploy. Commits contain metadata about who created it and when, and this enables Deptool to not just track what is currently deployed, but everything that was ever deployed to the cluster.

Every host has its own independent history. To correlate deploys between hosts, commits have a Deploy-Run trailer that is the same for commits that were created as part of the same Deptool invocation.

Operator-side refs¶

For every target host in the cluster, Deptool keeps a remote-tracking ref refs/remotes/<host> which points to the commit that is deployed at that host. This enables Deptool to determine which hosts are affected by a change, completely offline. For a cluster managed by a single person from a single store, these refs are always up to date because nothing else mutates the cluster. In a collaborative setting they may be outdated, just like your Git remote tracking refs may be outdated when you did not pull for a while. A deptool deploy will discover staleness and update the refs, but if you already know your local store has outdated refs, you can also run deptool sync to pull the latest state explicitly.

Target-side refs¶

• refs/heads/current points to the last successfully deployed commit.
• refs/heads/target points to the target of the last deploy.

On the target machine, Deptool keeps refs to record what is currently deployed there, and their reflog provides a log of every (attempted) deploy. When the host is in a clean state, current and target point to the same commit. At the start of a deploy, target advances to the commit that we attempt to deploy, while current only advances after the deploy is complete. When the two refs disagree, either a deploy is in progress, or a deploy failed and the target state is only partially applied.

Store format version¶

On the target host, the Git config at /var/lib/deptool/store/config contains a key storeVersion in the deptool section that records the version of the store format used. As of Deptool 1.3, the format is at version 2.

Transport¶

Deptool keeps the Git repositories synchronized between the operator machine and target hosts by sending packfiles over the existing SSH agent session. This skips the additional SSH handshake that would be needed for an out-of-band git push, and it ensures that Deptool works even when Git is not installed on the target host. (Deptool embeds libgit2 in its static binary.)

Security considerations¶

The store holds the full history of a host’s configuration. Although you should never store secrets in your configuration, this still presents some information disclosure risk. To mitigate this somewhat, the store on managed hosts is accessible only to the root user.

Historical versions¶

Store format version 1, used up to Deptool 1.2, recorded the entire cluster configuration on every host. This ostensibly had the advantage that the entire cluster state can be described by a single commit, but due to host limits and rollbacks, that view was misleading. It also presented an information disclosure risk, and complicated host renames.

Store format version 2 stores only the target host’s own directory from the config tree, and has a linear history per host. Hosts converted from store format version 1 have a single continuous history with a switchover commit.