invoke dist-upgrade instead of upgrade for apt upgrades

dist-upgrade is generally more correct here to get all packages upgraded.
We add the options to change these in system_info.  Also, document
the previous apt configuration change (apt_get_command).

ChangeLog

@@ -52,6 +52,8 @@
    (LP: #1023179)
  - use python-requests rather than urllib2.  By using recent versions of
    python-requests, we get https support (LP: #1067888).
+ - make apt-get invoke 'dist-upgrade' rather than 'upgrade' for
+   package_upgrade. (LP: #1164147)
 
 0.7.1:
  - sysvinit: fix missing dependency in cloud-init job for RHEL 5.6 

cloudinit/distros/debian.py

@@ -161,7 +161,12 @@ class Distro(distros.Distro):
         elif args and isinstance(args, list):
             cmd.extend(args)
 
-        cmd.append(command)
+        subcmd = command
+        if command == "upgrade":
+            subcmd = self.get_option("apt_get_upgrade_subcommand",
+                                     "dist-upgrade")
+
+        cmd.append(subcmd)
 
         pkglist = util.expand_package_list('%s=%s', pkgs)
         cmd.extend(pkglist)

doc/examples/cloud-config.txt

@@ -125,6 +125,24 @@ apt_sources:
       =Y2oI
       -----END PGP PUBLIC KEY BLOCK-----
 
+## apt config via system_info:
+# under the 'system_info', you can further customize cloud-init's interaction
+# with apt. 
+#   system_info:
+#    apt_get_command: [command, argument, argument]
+#    apt_get_upgrade_subcommand: dist-upgrade
+#
+# apt_get_command:
+#  To specify a different 'apt-get' command, set 'apt_get_command'.
+#  This must be a list, and the subcommand (update, upgrade) is appended to it.
+#  default is:
+#    ['apt-get', '--option=Dpkg::Options::=--force-confold',
+#     '--option=Dpkg::options::=--force-unsafe-io', '--assume-yes', '--quiet']
+#
+# apt_get_upgrade_subcommand:
+# Specify a different subcommand for 'upgrade. The default is 'dist-upgrade'.
+# This is the subcommand that is invoked if package_upgrade is set to true above.
+
 # Install additional packages on first boot
 #
 # Default: none