Muehlenhoff has uploaded a new change for review. (
https://gerrit.wikimedia.org/r/372829 )
Change subject: Update docs
......................................................................
Update docs
Change-Id: Iea127a2b6a63fa86b63ca47efe3e4dc23124cde6
---
M docs/readme.txt
1 file changed, 40 insertions(+), 109 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/operations/debs/debdeploy
refs/changes/29/372829/1
diff --git a/docs/readme.txt b/docs/readme.txt
index 7f4e121..f98eef4 100644
--- a/docs/readme.txt
+++ b/docs/readme.txt
@@ -3,29 +3,29 @@
-------
debdeploy allows the deployment of software updates in Debian (or Debian-based)
-environments on a large scale. It is based on salt; updates are
-initiated via the debdeploy tool running on the salt master. Servers
-can be grouped into arbitrary sets of servers/services based on Salt grains.
+environments on a large scale. It is based on Cumin; updates are
+initiated via the debdeploy tool running on the Cumin master. Servers
+can be grouped into arbitrary sets of servers/services based on the
+Cumin syntax.
Basic setup
-----------
-Install debdeploy-master on the salt master. Install debdeploy-minion
-on all salt minions. The necessary dependencies will be pulled in.
+Install debdeploy-server on the Cumin master. Install debdeploy-client
+on all clients to be managed. The necessary dependencies will be pulled in.
The Debian packaging installs a basic configuration in
-/etc/debdeploy.conf:
+/etc/debdeploy.conf on the Cumin master:
- You might need to customise the list of supported distros (this also
allows Debian derivatives like Ubuntu, but they must be Debian/apt
based).
- Each update file can be used on various server groups. The server
- groups are defined via Salt grains (one or several). You need to
- configure a name for each group of grains.
+ groups are defined via the Cumin host syntax.
-
-
+- [libraries] maintains a preconfigured list of library base names,
+ which are suggested by generate-debdeploy-spec, see below.
Defining an update
------------------
@@ -35,23 +35,30 @@
These update specs are only specified once and can then be applied to
the various server groups.
+generate-debdeploy-spec guides you through the creation of an update
+spec.
+
Here's an example for such an update definition:
----------------
-source: elinks
-comment: CVE-2015-0123
-update_type: tool
+source: openssl
+comment:
+update_type: library
fixes:
- jessie: 0.12~pre6-10
- trusty: 0.12~pre5-8ubuntu2
- precise:0.12~pre5-3ubuntu1
+ stretch: 1.0
+ jessie: 1.1
+ trusty: 1.2
+libraries:
+ - libssl
+ - libcrypto
----------------
debdeploy operates on Debian source packages. The reason is
that you may have different binary packages installed across your
-fleet. Some systems may e.g. only have php5-common installed, while
+fleet. Some systems may e.g. only have php5-cli installed, while
others may use several further PHP packages. debdeploy determines the
-installed binary packages per source package and updates them.
+installed binary packages per source package and updates every
+installed binary package.
The "comment" is mostly for informational purposes, it can e.g. denote
CVE IDs for security vulnerabilities.
@@ -72,48 +79,30 @@
system reboot(s) can be managed subsequently.
library -> After a library is updated, programs may need to be
restarted to fully effect the change. In addition
- to librarries, some applications may also fall under this
rule,
+ to libraries, some applications may also fall under this
rule,
e.g. when updating QEMU, you might need to restart
virtual machines. After installing the update, the
service restarts can be managed centrally.
-These are planned, but not yet implemented:
-daemon-cluster -> Clustered daemons, when updating, the invididual
- hosts are taken out of the cluster, updated and
- finally readded
-reboot-cluster -> Clustered systems, which are taken out of the
- cluster, updated, rebooted and finally re-added
-
-The "fixes" option describes the fixed package per source package. If
+The "fixes" option describes the fixed package version per distro release. If
a fix doesn't apply to a distribution, it can be left blank.
+
+"libraries" specifies a list of library base names, which are used to
+determine necessary process restarts after a library upgrade. If
+preconfigured in /etc/debdeploy.conf, the library base names are
+proposed when generating an update spec.
Deploying an update
-------------------
First you need to create an update spec as outlined above. Now you
-can deploy the update with the deploy command:
+can deploy the update with the "deploy" command. "testsystem" here
+refers to a host alias definition in Cumin.
debdeploy deploy -u elinks.yaml -s testsystem
-The update will run asynchronously via Salt. You can validate the
-status of the deployment via the status-deploy command, e.g.:
-
-debdeploy status-deploy -u elinks.yaml -s testsystem
-
-It will print out a summary like this:
-
- puppet-jmm-salt-client01.puppet.eqiad.wmflabs:
- Updated packages:
- elinks-data: 0.12~pre6-5 -> 0.12~pre6-10
- elinks: 0.12~pre6-5+b2 -> 0.12~pre6-10
- Deployment summary:
- Number of hosts in this deployment run: 1
- No packages were added
- No packages were removed
- Updated packages:
- elinks: 0.12~pre6-5+b2 -> 0.12~pre6-10 on 1 hosts
- elinks-data: 0.12~pre6-5 -> 0.12~pre6-10 on 1 hosts
+The update will run via Cumin.
If anything is awry, you can revert an update using the rollback
command, e.g.
@@ -122,22 +111,11 @@
Note that in some cases the version to be rolled back might no longer
be available via apt. In most cases it will still be available in the
-local apt cache of the system. The status of a rollback can be queried
-using the rollback-status command, e.g.
-
-debdeploy status-rollback -u elinks.yaml -s testsystem
-
-If you have an updatespec which applies to more than one group of
-servers (which will usually be the case for generic systems libs
-etc), you can check which server groups haven't had the update
-applied:
-
-debdeploy list-server-groups -u dpkg.yaml
-
-
+local apt cache of the system.
Restart detection / handling
+----------------------------
If you update a tool like, say, Emacs nothing needs to be done in
addition to deploying the update. However, if you're updating a
@@ -151,33 +129,11 @@
runtimes, if you are e.g. using daemons written in Java or Python,
these processes need to be restarted as well.
-When deploying an update for such a "library", debdeploy includes
-automatic restart detection. The deploy run returns a list of
-processes which need to be restarted. This may look like this:
+When deploying an update for such a "library", debdeploy provides
+restart detection using the "query_restart" command. It returns a
+list of processes which need to be restarted. This may look like this:
-----------------------------------------------------------
-$ debdeploy status-deploy -u python.yaml -s testsystem
-
-(..)
-
-Deployment summary:
-Number of hosts in this deployment run: 3
-No packages were added
-No packages were removed
-Updated packages:
-libpython2.7-minimal: 2.7.9-2 -> 2.7.10-3 on 1 hosts
-libpython2.7-stdlib: 2.7.9-2 -> 2.7.10-3 on 1 hosts
-libpython2.7: 2.7.9-2 -> 2.7.10-3 on 1 hosts
-python2.7-minimal: 2.7.9-2 -> 2.7.10-3 on 1 hosts
-python2.7: 2.7.9-2 -> 2.7.10-3 on 1 hosts
-
-Restarts needed:
-/usr/bin/diamond on 1 hosts
-
-Error summary:
-No errors found
-----------------------------------------------------------
Restarts are intentionally not made automatically for a number of
@@ -192,31 +148,6 @@
detectable. E.g. if someone has simply started something in a screen
session.
-
-debdeploy simplifies mass-restarts of services using the "restart"
-command. It also operates on groups of servers using the same set
-of grains. Since there are multiple ways to restart a service in an
-Ubuntu/Debian environment (sysv init scripts, upstart jobs, systemd
-unit files) and the method can vary across supported releases (e.g.
-on wheezy a service may use /etc/init.d/foo and on jessie
-/lib/systemd/unit/foo.service), only the name of the process binary
-is passed. debdeploy automatically detects the service to restart.
-If a service fails to restart, an error is flagged.
-
-Here's an example:
-
------------------
-debdeploy restart -s testsystem -p /usr/sbin/ntpd -p /usr/sbin/lldpd
-Restarting services. Use --verbose to also display non-failing restarts.
-puppet-jmm-salt-client01.puppet.eqiad.wmflabs:
- /usr/sbin/lldpd sucessfully restarted
- /usr/sbin/ntpd sucessfully restarted
- Restart summary:
-
-/usr/sbin/lldpd successfully restarted on 1 out of 1 hosts.
-/usr/sbin/ntpd successfully restarted on 1 out of 1 hosts.
------------------
-
Dealing with legacy binary packages
-----------------------------------
--
To view, visit https://gerrit.wikimedia.org/r/372829
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: Iea127a2b6a63fa86b63ca47efe3e4dc23124cde6
Gerrit-PatchSet: 1
Gerrit-Project: operations/debs/debdeploy
Gerrit-Branch: master
Gerrit-Owner: Muehlenhoff <[email protected]>
_______________________________________________
MediaWiki-commits mailing list
[email protected]
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
