README.md in knife-topo-0.0.3 vs README.md in knife-topo-0.0.4
- old
+ new
@@ -1,11 +1,15 @@
knife topo
==========
-This Chef Knife plugin is provided by ThirdWave Insights LLC.
-It allows you to use knife to create and update topologies consisting of
-multiple nodes.
+This Chef Knife plugin allows you to create and update topologies
+consisting of multiple nodes. You may find it useful if you are
+regularly updating a system consisting of multiple nodes, and would
+like to manage its dynamic configuration (like 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.:
@@ -18,28 +22,29 @@
This plugin has been tested with Chef Version 11.12 on Ubuntu 14.04 LTS.
# Usage #
-Define one or more *topologies* in a [*topology file*](#markdown-header-topology-file).
+Define one or more topologies in a [topology file](#markdown-header-topology-file).
Import the topology file into your local chef repo using
[knife topo import](#markdown-header-knife-topo-import). Create and optionally
bootstrap a topology on the Chef server using
[knife topo create](#markdown-header-knife-topo-create), and update it
using [knife topo update](#markdown-header-knife-topo-update).
# Getting Started #
-Try out this plugin using a [test repo](knife-topo/src/master/test-repo) which you can
-download from Github or is included in the installed gem. See the
-[Instructions](knife-topo/src/master/test-repo/Instructions.txt) for how to use the test repo.
+Try out this plugin using a [test repo](knife-topo/src/master/test-repo)
+which you can download from Github or is included in the installed gem. See the
+[Instructions](knife-topo/src/master/test-repo/Instructions.md) for a
+demo script, explanation, and troubleshooting.
The instructions assume you have
[chefDK](http://www.getchef.com/downloads/chef-dk/)
or equivalent installed and working with Vagrant and VirtualBox, but
- chefDK is not a requirement for this plugin.
+ none of these are requirements for this plugin.
# Topology File #
See the [example topology file](knife-topo/src/master/test-repo/topology.json)
@@ -70,21 +75,11 @@
`knife topo` subcommands.
The `chef-environment` and `normal` attributes defined
here will be applied to all nodes in the topology, unless alternative
values are provided for a specific node. The `tags`
-will be added to each node. The normal attributes may either be
-specified using the dot notation, as shown above, or may be expanded as
-a JSON structure, i.e., the above is equivalent to:
-```json
- {
- "normal": {
- "topo": {
- "blueprint": "blah"
- }
- }
- }
+will be added to each node.
## Node List
Each topology contains a list of `nodes`.
```json
@@ -92,12 +87,12 @@
"name": "test1",
...,
"nodes": {
"buildserver": {
"name": "buildserver01",
- "ssh_host": "127.0.0.1",
- "ssh_port": "8241",
+ "ssh_host": "192.168.1.201",
+ "ssh_port": "2224",
"chef_environment": "dev",
"run_list": ["role[base-ubuntu]", "ypo::db", "recipe[ypo::appserver]"],
"normal": {
"topo.node_type": "buildserver",
"another": "Value 1"
@@ -119,13 +114,68 @@
The `ssh_host` and `ssh_port` are optional fields that are used to
bootstrap a node.
## Topology Cookbook Attributes
+Each topology may have attributes that are set via
+an attribute file in a topology-specific cookbook. Each
+attribute file is described in an entry in the 'cookbook_attributes'
+array.
+```json
+ "cookbook_attributes": [
+ {
+ "cookbook": "testsys_test1",
+ "filename": "softwareversion",
+ "normal":
+ {
+ "nodejs":
+ {
+ "version": "0.28"
+ },
+ "testapp":
+ {
+ "version": "0.0.3"
+ },
+ "mongodb":
+ {
+ "package_version": "2.6.1"
+ }
+ },
+ "conditional" : [
+ {
+ "qualifier": "node_type",
+ "value" : "buildserver",
+ "normal":
+ {
+ "mongodb":
+ {
+ "package_version": "2.5.1"
+ }
+ }
+ }
+ ]
+ }
+ ]
+```
+
+Attributes listed directly under an attribute priority (e.g. 'normal'
+in the above) will generate an entry in the attribute file such as:
+
+ normal['mongodb'][package_version] = "2.6.1"
+
+Attributes listed under the `conditional` property will generate an
+entry in the attribute file such as:
+
+```ruby
+ if (node['topo']['node_type'] == "buildserver")
+ normal['mongodb'][package_version] = "2.5.1"
+ end
+```
+
# Subcommands #
The main subcommands for `knife topo` are:
* `knife topo import` - Import one or more into your workspace/local repo
@@ -183,15 +233,45 @@
knife topo cookbook create TOPOLOGY
Generates the topology cookbook attribute files and attributes described in the
'cookbook_attributes' property.
+### Options:
+
+The knife topo cookbook create subcommand supports the following additional options.
+
+Option | Description
+------------ | -----------
+See [knife cookbook create](http://docs.opscode.com/chef/knife.html#cookbook) |
+
### Examples:
The following will generate the topology cookbook attribute files for
topology test1.
$ knife topo cookbook create test1
+
+## knife topo cookbook upload
+
+ knife topo cookbook upload TOPOLOGY
+
+Uploads the topology cookbook attribute files.
+
+### Options:
+
+The knife topo cookbook upload subcommand supports the following additional options.
+
+Option | Description
+------------ | -----------
+See [knife cookbook upload](http://docs.opscode.com/chef/knife.html#cookbook) |
+
+
+### Examples:
+The following will generate the topology cookbook attribute files for
+topology test1.
+
+ $ knife topo cookbook create test1
+
## knife topo create
knife topo create TOPOLOGY
Creates the specified topology in the chef server as an item in the