README.md in knife-topo-0.0.5 vs README.md in knife-topo-0.0.6
- old
+ new
@@ -1,50 +1,67 @@
knife topo
==========
-This Chef Knife plugin allows you to create and update topologies
-consisting of multiple nodes. You may find it useful if you are
+The knife-topo plugin allows you to create and update topologies
+consisting of multiple nodes using single knife commands, based on
+a JSON definition of the topology. The plugin:
+* creates a data bag for the topology
+* generates attribute file(s) in a topology-specific cookbook
+* sets and updates the run list, chef environment and properties of nodes
+* uploads the topology-specific cookbook and bootstraps nodes
+
+You may find this plugin useful if you are
regularly updating a system consisting of multiple nodes, and would
-like to manage its dynamic configuration (like software versions)
+like to manage its dynamic configuration (e.g. changing software versions)
through a single (json) configuration file. It may also be useful
if you are regularly bringing up multi-node systems with similar
topologies but differences in their configuration details.
+
# Installation #
-Copy the contents of lib/chef/knife into your plugin directory, e.g.:
+[Download the latest knife-topo release](http://github.com/christinedraper/knife-topo/releases/latest),
+unzip and copy `lib/chef/knife` into your plugin directory, e.g.:
- $ mkdir -p ~/.chef/knife/plugins
- $ cp lib/chef/knife/* ~/.chef/knife/plugins
+ $ unzip knife-topo-0.0.6.zip -d ~
+ $ cd ~/knife-topo-0.0.6
+ $ mkdir -p ~/.chef/plugins/knife
+ $ cp lib/chef/knife/* ~/.chef/plugins/knife
or install knife-topo as a gem
- $ sudo gem install knife-topo
+ $ gem install knife-topo
-This plugin has been tested with Chef Version 11.12 on Ubuntu 14.04 LTS.
+You may need to use `sudo gem install knife-topo`, depending on your setup.
+This plugin has been tested with Chef Version 11.12 on Ubuntu 14.04 LTS.
+
+Note: I've encountered a case (on a Mac) where knife was not configured to use
+ gems on the gem path. If the gem install succeeds but `knife topo`
+ is not a recognized knife command, try the first approach (copy
+the ruby plugin scripts into ~/.chef/plugins/knife).
+
# Usage #
-Define one or more topologies in a [topology file](#topology-file).
+Define one or more topologies in a [topology file](#topology-file). Import
+that file into your Chef workspace using [knife topo import](#import),
+then create and bootstrap the nodes using a single command [knife topo create](#create).
+Update the topology file as the configuration changes (e.g., when you
+need to update software versions), import those changes and run one command
+[knife topo update](#update) to update all of the nodes.
-Import the topology file into your local chef repo using
-[knife topo import](#import). Create and optionally
-bootstrap a topology on the Chef server using
-[knife topo create](#create), and update it
-using [knife topo update](#update).
# Getting Started #
-Try out this plugin using a [test repo](test-repo)
-which you can download from Github or is included in the installed gem. See the
-[Instructions](Instructions.md) for a
+Try out this plugin using a [test-repo](test-repo) provided in the knife-topo github repository.
+[Download the latest knife-topo release](http://github.com/christinedraper/knife-topo/releases/latest)
+and unzip it, then follow the [Instructions](test-repo/Instructions.md) for a
demo script, explanation, and troubleshooting.
-The instructions assume you have
- [chefDK](http://www.getchef.com/downloads/chef-dk/)
+The instructions assume you have [chefDK](http://www.getchef.com/downloads/chef-dk/)
or equivalent installed and working with Vagrant and VirtualBox, but
- none of these are requirements for this plugin.
+ none of these are requirements to use the knife-topo plugin.
# Topology File <a name="topology-file"></a>#
See the [example topology file](test-repo/topology.json)
@@ -84,12 +101,12 @@
```
{
"name": "test1",
...
- "nodes": {
- "buildserver": {
+ "nodes": [
+ {
"name": "buildserver01",
"ssh_host": "192.168.1.201",
"ssh_port": "2224",
"chef_environment": "dev",
"run_list": ["role[base-ubuntu]", "ypo::db", "recipe[ypo::appserver]"],
@@ -99,15 +116,12 @@
}
},
"tags": ["build"]
},
...
- }
- }
- },
- ...
- ]}
+ ]
+ }
```
Within `nodes`, the `name` field is the node name that will be used in Chef.
The fields `chef_environment`, `run_list`, `tags` and the attributes
within `normal` will also be applied to the node in Chef. All of these
fields are optional.
@@ -275,35 +289,35 @@
## knife topo create <a name="create"></a>
knife topo create TOPOLOGY
Creates the specified topology in the chef server as an item in the
-system environment data bag. Creates the chef environment associated
-with the system environment, if it does not already exist. Uploads any
-topology cookbooks. Creates or
-updates nodes identified in the topology, using information
-specified in the system environment and for the specific node.
+topology data bag. Creates the chef environment associated
+with the topology, if it does not already exist. Uploads any
+topology cookbooks. Updates existing nodes based on the topology
+information. New nodes will be created if the bootstrap option is
+specified.
### Options:
The knife topo create subcommand supports the following additional options.
Option | Description
------------ | -----------
--bootstrap | Bootstrap the topology (see [topo bootstrap](#bootstrap))
See [knife bootstrap](http://docs.opscode.com/knife_bootstrap.html) | Options supported by `knife bootstrap` are passed through to the bootstrap command
---no-upload | Do not upload topology cookbooks
+--disable-upload | Do not upload topology cookbooks
### Examples:
The following will create the 'test1' topology, and bootstrap it.
$ knife topo create test1 --bootstrap
The following will create the 'test1' topology but will not bootstrap it
or upload topology cookbooks.
-$ knife topo create test1 --no-upload
+$ knife topo create test1 --disable-upload
## knife topo export <a name="export"></a>
knife topo export [ TOPOLOGY [ NODE ... ]
@@ -328,12 +342,12 @@
## knife topo import <a name="import"></a>
knife topo import [ TOPOLOGY_FILE [ TOPOLOGY ... ]]
-Imports the system environment and topologies from a
-[topology file](#Topology File) into the local repo. If no topology
+Imports the topologies from a
+[topology file](#topology-file) into the local repo. If no topology
file is specified, attempts to read from a file called 'topology.json'
in the current directory. Generates the topology cookbook attribute
files and attributes described in the 'cookbook_attributes' property.
### Examples:
@@ -352,11 +366,17 @@
Updates the specified topology. Creates or updates nodes
identified in the topology, using information specified in the
topology for the specific node.
-If no topology is specified, all existing topologies in that environment
+If no topology is specified, all existing topologies
will be updated.
+
+Option | Description
+------------ | -----------
+--bootstrap | Bootstrap the topology (see [topo bootstrap](#bootstrap))
+See [knife bootstrap](http://docs.opscode.com/knife_bootstrap.html) | Options supported by `knife bootstrap` are passed through to the bootstrap command
+--disable-upload | Do not upload topology cookbooks
### Examples:
The following will update the 'test1' topology.
$ knife topo update test1