Permalink
Browse files

Update man pages and add AUTHORS file

  • Loading branch information...
techhat committed Oct 12, 2012
1 parent d827bea commit 15048ce7a936013e90dc8b803a2b053e84ac8b79
Showing with 201 additions and 34 deletions.
  1. +42 −0 AUTHORS
  2. +2 −2 doc/conf.py
  3. +38 −21 doc/man/salt-cloud.1
  4. +118 −10 doc/man/salt-cloud.7
  5. +1 −1 saltcloud/version.py
View
42 AUTHORS
@@ -0,0 +1,42 @@
+=============
+Salt Authors
+=============
+
+Whos Who in Salt
+============================
+
+The Man With the Plan
+----------------------------
+
+Thomas S Hatch is the main developer of Salt. He is the founder, owner,
+maintainer and lead of the Salt project, as well as author of the majority
+of the Salt code and documentation.
+
+Documentation System
+----------------------------
+
+The documentation system was put together by Seth House, much of the
+documentation is being maintained by Joseph Hall
+
+Developers
+----------------------------
+
+Dan Garthwaite <dan@garthwaite.org>
+deutsche
+Joseph Hall <joseph@saltstack.com>
+lexual
+Marat Shakirov
+Matt Black
+Peter Baumgartner
+Robert Fielding
+Seth House
+Thomas S Hatch <thatch@saltstack.com>
+
+
+Growing Community
+--------------------------------
+
+To view all contributors please check ohloh, this file can sometimes be out
+of date:
+
+https://www.ohloh.net/p/salt-cloud/contributors
View
@@ -92,7 +92,7 @@ def __getattr__(self, name):
# General information about the project.
project = u'salt-cloud'
-copyright = u'2012, Thomas S Hatch'
+copyright = u'2012, SaltStack, Inc.'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
@@ -265,7 +265,7 @@ def __getattr__(self, name):
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
authors = [
- 'Thomas S. Hatch <thatch45@gmail.com> and many others, please see the Authors file',
+ 'Thomas S. Hatch <thatch@saltstack.com> and many others, please see the Authors file',
]
man_pages = [
View
@@ -1,4 +1,4 @@
-.TH "SALT-CLOUD" "1" "September 25, 2012" "0.8.0" "salt-cloud"
+.TH "SALT-CLOUD" "1" "October 12, 2012" "0.8.1" "salt-cloud"
.SH NAME
salt-cloud \- Salt Cloud Command
.
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
-.\" Man page generated from reStructeredText.
+.\" Man page generated from reStructuredText.
.
.sp
Copy a file to a set of systems
@@ -56,47 +56,57 @@ Print a usage message briefly summarizing these command\-line options.
.INDENT 0.0
.TP
.B \-p PROFILE, \-\-profile=PROFILE
-Select a single profile to build the named cloud vms from. The profile
+Select a single profile to build the named cloud VMs from. The profile
must be defined in the specified profiles file.
.UNINDENT
.INDENT 0.0
.TP
.B \-m MAP, \-\-map=MAP
-Specify a map file to use. This option will ensure that all of the mapped
-vms are created. If the named vm already exists then it will be skipped.
+Specify a map file to use. If used without any other options, this option
+will ensure that all of the mapped VMs are created. If the named VM
+already exists then it will be skipped.
.UNINDENT
.INDENT 0.0
.TP
.B \-H, \-\-hard
When specifying a map file, the default behavior is to ensure that all of
-the vms specified in the map file are created. If the \-\-hard option is
-set, then any vms that exist on configured cloud providers that are
+the VMs specified in the map file are created. If the \-\-hard option is
+set, then any VMs that exist on configured cloud providers that are
not specified in the map file will be destroyed. Be advised that this can
be a destructive operation and should be used with care.
.UNINDENT
.INDENT 0.0
.TP
.B \-d, \-\-destroy
-Pass in the name(s) of vms to destroy, salt\-cloud will search the
+Pass in the name(s) of VMs to destroy, salt\-cloud will search the
configured cloud providers for the specified names and destroy the
-vms. Be advised that this is a destructive operation and should be used
-with care.
+VMs. Be advised that this is a destructive operation and should be used
+with care. Can be used in conjunction with the \-m option to specify a map
+of VMs to be deleted.
.UNINDENT
.INDENT 0.0
.TP
.B \-P, \-\-parallel
Normally when building many cloud VMs they are executed serially. The \-P
option will run each cloud vm build in a separate process allowing for
-large groups of vms to be build at once.
+large groups of VMs to be build at once.
.sp
Be advised that some cloud provider\(aqs systems don\(aqt seem to be well suited
-for this influx of vm creation. When creating large groups of vms watch the
+for this influx of vm creation. When creating large groups of VMs watch the
cloud provider carefully.
.UNINDENT
.INDENT 0.0
.TP
.B \-Q, \-\-query
-Execute a query and print out the information about all cloud vms.
+Execute a query and print out information about all cloud VMs. Can be used
+in conjunction with \-m to display only information about the specified map.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-F, \-\-full\-query
+Execute a query and print out all available information about all cloud VMs.
+Can be used in conjunction with \-m to display only information about the
+specified map.
.UNINDENT
.INDENT 0.0
.TP
@@ -160,31 +170,38 @@ Disable all colored output.
.UNINDENT
.SH EXAMPLES
.sp
-To create 4 vms named web1, web2, db1 and db2 from specified profiles:
+To create 4 VMs named web1, web2, db1 and db2 from specified profiles:
.sp
# salt\-cloud \-p fedora_rackspace web1 web2 db1 db2
.sp
-To read in a map file and create all vms specified therein:
+To read in a map file and create all VMs specified therein:
.sp
# salt\-cloud \-m /path/to/cloud.map
.sp
-To read in a map file and create all vms specified therein in parallel:
+To read in a map file and create all VMs specified therein in parallel:
.sp
# salt\-cloud \-m /path/to/cloud.map \-P
.sp
-To delete any vms not specified in the maf file:
+To delete any VMs specified in the map file:
+.sp
+# salt\-cloud \-m /path/to/cloud.map \-d
+.sp
+To delete any VMs NOT specified in the map file:
+.sp
+# salt\-cloud \-m /path/to/cloud.map \-H
+.sp
+To display the status of all VMs specified in the map file:
.sp
-# salt\-cloud \-m /path/to/cloud.map \-H \-P
+# salt\-cloud \-m /path/to/cloud.map \-Q
.SH SEE ALSO
.sp
\fIsalt\-cloud(7)\fP
\fIsalt(7)\fP
\fIsalt\-master(1)\fP
\fIsalt\-minion(1)\fP
.SH AUTHOR
-Thomas S. Hatch <thatch45@gmail.com> and many others, please see the Authors file
+Thomas S. Hatch <thatch@saltstack.com> and many others, please see the Authors file
.SH COPYRIGHT
-2012, Thomas S Hatch
+2012, SaltStack, Inc.
.\" Generated by docutils manpage writer.
-.\"
.
View
@@ -1,4 +1,4 @@
-.TH "SALT-CLOUD" "7" "September 25, 2012" "0.8.0" "salt-cloud"
+.TH "SALT-CLOUD" "7" "October 12, 2012" "0.8.1" "salt-cloud"
.SH NAME
salt-cloud \- Salt Cloud Documentation
.
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
-.\" Man page generated from reStructeredText.
+.\" Man page generated from reStructuredText.
.
.SH VM PROFILES
.sp
@@ -130,9 +130,6 @@ fedora_small:
\- web1
\- web2
\- web3
- \- web3
- \- web4
- \- web5
fedora_high:
\- redis1
\- redis2
@@ -141,8 +138,6 @@ cent_high:
\- riak1
\- riak2
\- riak3
- \- riak4
- \- riak5
.ft P
.fi
.sp
@@ -193,6 +188,34 @@ fedora_small:
omelet: with peppers
.ft P
.fi
+.sp
+A map file may also be used with the various query options:
+.sp
+.nf
+.ft C
+$ salt\-cloud \-m /path/to/mapfile \-Q
+{\(aqaws\(aq: {\(aqweb1\(aq: {\(aqid\(aq: \(aqi\-e6aqfegb\(aq,
+ \(aqimage\(aq: None,
+ \(aqprivate_ips\(aq: [],
+ \(aqpublic_ips\(aq: [],
+ \(aqsize\(aq: None,
+ \(aqstate\(aq: 0}},
+ \(aqweb2\(aq: {\(aqAbsent\(aq}}
+.ft P
+.fi
+.sp
+...or with the delete option:
+.sp
+.nf
+.ft C
+$ salt\-cloud \-m /path/to/mapfile \-d
+The following virtual machines are set to be destroyed:
+ web1
+ web2
+
+Proceed? [N/y]
+.ft P
+.fi
.SH WRITING CLOUD PROVIDER MODULES
.sp
Salt cloud runs on a module system similar to the main Salt project. The
@@ -717,6 +740,92 @@ Ubuntu packages automatically start the service upon installation, and needed
to be handled differently in the deploy script. Configuration is now laid down
before the package is installed, so that the minion can make its initial start
happen with the correct configuration.
+.SS Salt Cloud 0.8.1 Release Notes
+.sp
+In a somewhat quicker timeline than usual, Salt Cloud 0.8.1 has been released!
+While many of the updates in this release focus on stability, users of map
+files and AWS also have some new features to look forward to.
+.SS Documentation
+.sp
+The documentation for Salt Cloud can be found on Read the Docs:
+\fI\%http://salt-cloud.readthedocs.org\fP
+.SS Download
+.sp
+Salt Cloud can be downloaded and install via pypi or github:
+.sp
+\fI\%http://pypi.python.org/packages/source/s/salt-cloud/salt-cloud-0.8.1.tar.gz\fP
+.sp
+\fI\%https://github.com/downloads/saltstack/salt-cloud/salt-cloud-0.8.1.tar.gz\fP
+.sp
+Some packages have been made available for salt\-cloud and more on on their
+way. Packages for Arch, and FreeBSD are being made available thanks to the
+work of Christer Edwards, and packages for RHEL and Fedora are being created
+by Clint Savage. Package availability will be announced on the salt mailing list.
+.SS Full Query Option
+.sp
+The \-Q or \-\-query option only displays a small amount of information about
+each virtual machine. This is to keep command\-line reports small and
+manageable. Now the \-F or \-\-full\-query option can be used to display all
+of the information about a VM that salt\-cloud knows about. The amount of
+information returned varies between providers, depending on the kinds of
+functionality available through them.
+.SS Increased Map Functionality
+.sp
+Previously, map files were only used for creating VMs. Now they can also be
+used to query and delete VMs. The \-Q, \-F and \-d options can all be used in
+conjunction with \-m, to display map\-specific data. If a VM that is specified
+in the map does not exist, it will still show up under \-Q and \-F as "Absent".
+If a VM specified in the map does not exist when a \-d is specified, it will
+of course be ignored.
+.SS Multiple Security Groups in AWS
+.sp
+AWS allows for multiple security groups to be applied to any given VM, but
+until this release, Salt Cloud only supported managing one. This update allows
+a list of security groups to be specified. In the main configuration file, an
+example of multiple security groups would look like:
+.sp
+.nf
+.ft C
+AWS.securitygroup:
+ \- default
+ \- extra
+.ft P
+.fi
+.sp
+In a profile, an example would be:
+.sp
+.nf
+.ft C
+micro_amazon:
+ provider: aws
+ image: ami\-e565ba8c
+ size: Micro Instance
+ os: RHEL6
+ securitygroup:
+ \- default
+ \- extra
+.ft P
+.fi
+.SS Bug Fixes
+.sp
+A number of bugs have been fixed in this release. Most of these were internal
+fixes related to authentication and deployment across various providers. Bug
+fixes in this release include:
+.sp
+Ubuntu users may notice that deploying an instance has become significantly
+noisier. A change was made to make Ubuntu display information returned as
+packages are installed, which is more aligned with how yum\-based machines
+already behaved. This also forced these VMs to deploy salt in a much more
+reliable manner.
+.sp
+Requirements listed in requirements.txt are also pulled into setup.py, to make
+it easy to use the easy_install tool.
+.sp
+Most cloud providers default to root as the initial user, but AWS typically
+providers a different user (ec2\-user, ubuntu, bitnami, etc). Deployment on
+such images must be handled using sudo. Previously, sudo was used to issue
+all deployment commands, but this failed on images where sudo was not installed
+by default (such as FreeBSD). Now sudo will only be used with non\-root logins.
.SH SALT CLOUD 0.6.0 RELEASE NOTES
.sp
The new Salt project, Salt Cloud, is introduced with version 0.6.0. Salt Cloud
@@ -983,9 +1092,8 @@ Proceed? [N/y]
.ft P
.fi
.SH AUTHOR
-Thomas S. Hatch <thatch45@gmail.com> and many others, please see the Authors file
+Thomas S. Hatch <thatch@saltstack.com> and many others, please see the Authors file
.SH COPYRIGHT
-2012, Thomas S Hatch
+2012, SaltStack, Inc.
.\" Generated by docutils manpage writer.
-.\"
.
View
@@ -1,2 +1,2 @@
-__version_info__ = (0, 8, 0)
+__version_info__ = (0, 8, 1)
__version__ = '.'.join(map(str, __version_info__))

0 comments on commit 15048ce

Please sign in to comment.