README.md in dev-lxc-0.4.1 vs README.md in dev-lxc-0.5.0
- old
+ new
@@ -61,37 +61,55 @@
Run `gem update dev-lxc` inside the Vagrant VM platform to ensure you have the latest version.
## Usage
+### Display Help
+
+```
+dev-lxc help
+
+dev-lxc -h
+
+dev-lxc --help
+
+dev-lxc help <subcommand>
+```
+
### Shorter Commands are Faster (to type that is :)
The dev-lxc-platform's root user's `~/.bashrc` file has aliased `dl` to `dev-lxc` for ease of use but
for most instructions in this README I will use `dev-lxc` for clarity.
You only have to type enough of a `dev-lxc` subcommand to make it unique.
The following commands are equivalent:
```
-dev-lxc cluster init standalone > dev-lxc.yml
-dl cl i standalone > dev-lxc.yml
+dev-lxc init standalone > dev-lxc.yml
+dl i standalone > dev-lxc.yml
```
```
-dev-lxc cluster start
-dl cl start
+dev-lxc start
+dl start
+
+# if no subcommand is given then `start` will be called by default
+# and any arguments will be passed to the `start` subcommand
+# so both of the following commands will start all servers
+dev-lxc
+dl
```
```
-dev-lxc cluster status
-dl cl stat
+dev-lxc status
+dl stat
```
```
-dev-lxc cluster destroy
-dl cl d
+dev-lxc destroy
+dl d
```
### Create and Manage a Cluster
The following instructions will build a tier cluster with an Analytics server for
@@ -105,22 +123,22 @@
Be sure you configure the
[mounts and packages entries](https://github.com/jeremiahsnapp/dev-lxc#cluster-config-files)
appropriately.
- dev-lxc cluster init tier > dev-lxc.yml
+ dev-lxc init tier > dev-lxc.yml
Uncomment the Analytics server section in `dev-lxc.yml` if you want it to be built.
#### Start cluster
Starting the cluster the first time takes awhile since it has a lot to build.
The tool automatically creates snapshot clones at appropriate times so future
creation of the cluster's servers is very quick.
- dev-lxc cluster start
+ dev-lxc start
A test org, user, knife.rb and keys are automatically created in
the bootstrap backend server in `/root/chef-repo/.chef` for testing purposes.
The `knife-opc` plugin is installed in the embedded ruby environment of the
@@ -129,29 +147,29 @@
#### Cluster status
Run the following command to see the status of the cluster.
- dev-lxc cluster status
+ dev-lxc status
This is an example of the output.
```
Cluster is available at https://chef.lxc
Analytics is available at https://analytics.lxc
- be-tier.lxc running 10.0.3.203
- fe1-tier.lxc running 10.0.3.204
- analytics-tier.lxc running 10.0.3.206
+ tier-be.lxc running 10.0.3.203
+ tier-fe1.lxc running 10.0.3.204
+ tier-analytics.lxc running 10.0.3.206
```
[https://chef.lxc](https://chef.lxc) resolves to the frontend.
#### Create chef-repo
Create a local chef-repo with appropriate knife.rb and pem files.
- dev-lxc cluster chef-repo
+ dev-lxc chef-repo
Now you can easily use knife to access the cluster.
cd chef-repo
knife ssl fetch
@@ -161,82 +179,92 @@
Clones of the servers as they existed immediately after initial installation, configuration and
test org and user creation are available so you can destroy the cluster and "rebuild" it within
seconds effectively starting with a clean slate very easily.
- dev-lxc cluster destroy
- dev-lxc cluster start
+ dev-lxc destroy
+ dev-lxc start
#### Stop and start the cluster
- dev-lxc cluster stop
- dev-lxc cluster start
+ dev-lxc stop
+ dev-lxc start
#### Backdoor access to each server's filesystem
The abspath subcommand can be used to prepend each server's rootfs path to a particular file.
-When using `dev-lxc cluster abspath` only results for actual Chef Servers will be returned.
-If an Analytics server is described in `dev-lcx.yml` it will be ignored.
+For example, you can use the following command to edit the backend and frontend servers' chef-server.rb
+file without logging into the containers.
-For example, you can use the following command to edit each server's chef-server.rb file without
-logging into the containers.
+ emacs $(dev-lxc abspath 'be|fe' /etc/opscode/chef-server.rb)
- emacs $(dev-lxc cluster abspath /etc/opscode/chef-server.rb)
-
#### Run arbitrary commands in each server
-After modifying the chef-server.rb you could use the run_command subcommand to tell each server
-to run `chef-server-ctl reconfigure`.
+After modifying the chef-server.rb you could use the run_command subcommand to tell the backend and
+frontend servers to run `chef-server-ctl reconfigure`.
-When using `dev-lxc cluster run_command` the command will only be run in actual Chef Servers.
-If an Analytics server is described in `dev-lcx.yml` it will be ignored.
+ dev-lxc run_command 'be|fe' 'chef-server-ctl reconfigure'
- dev-lxc cluster run_command 'chef-server-ctl reconfigure'
-
#### Destroy cluster
Use the following command to destroy the cluster's servers and also destroy their unique and shared
base containers if you want to build them from scratch.
- dev-lxc cluster destroy -u -s
+ dev-lxc destroy -u -s
#### Use commands against a specific server
-You can also run most of these commands against individual servers by using the server subcommand.
+You can also run most of these commands against a set of servers by specifying a pattern that matches
+a set of server names.
- dev-lxc server ...
+ dev-lxc <subcommand> [pattern]
+For example, to only start the backend and frontend servers named `tier-be.lxc` and `tier-fe1.lxc`
+you can run the following command.
+
+ dev-lxc start 'be|fe'
+
### Using the dev-lxc library
-dev-lxc can also be used as a library.
+dev-lxc cli interface can be used as a library.
+ require 'dev-lxc/cli'
+
+ ARGV = [ 'start' ] # start all servers
+ DevLXC::CLI::DevLXC.start
+
+ ARGV = [ 'status' ] # show status of all servers
+ DevLXC::CLI::DevLXC.start
+
+ ARGV = [ 'run_command', 'uptime' ] # run `uptime` in all servers
+ DevLXC::CLI::DevLXC.start
+
+ ARGV = [ 'destroy' ] # destroy all servers
+ DevLXC::CLI::DevLXC.start
+
+dev-lxc itself can also be used as a library
+
require 'yaml'
require 'dev-lxc'
- config = YAML.load(IO.read('dev-lxc.yml'))
- cluster = DevLXC::ChefCluster.new(config)
- cluster.start
- cluster.status
- cluster.run_command("uptime")
- server = DevLXC::ChefServer.new("fe1-tier.lxc", config)
- server.stop
- server.status
- cluster.status
- server.start
- cluster.status
- server.run_command("chef-server-ctl reconfigure")
- cluster.destroy
- cluster.status
+ config = YAML.load(IO.read('dev-lxc.yml'))
+ server = DevLXC::ChefServer.new("tier-fe1.lxc", config)
+
+ server.start # start tier-fe1.lxc
+ server.status # show status of tier-fe1.lxc
+ server.run_command("chef-server-ctl reconfigure") # run command in tier-fe1.lxc
+ server.stop # stop tier-fe1.lxc
+
## Cluster Config Files
dev-lxc uses a YAML configuration file named `dev-lxc.yml` to define a cluster.
The following command generates sample config files for various cluster topologies.
- dev-lxc cluster init
+ dev-lxc init
-`dev-lxc cluster init tier > dev-lxc.yml` creates a `dev-lxc.yml` file with the following content:
+`dev-lxc init tier > dev-lxc.yml` creates a `dev-lxc.yml` file with the following content:
platform_container: p-ubuntu-1404
topology: tier
api_fqdn: chef.lxc
#analytics_fqdn: analytics.lxc
@@ -247,21 +275,21 @@
# manage: /dev-shared/chef-packages/manage/opscode-manage_1.11.2-1_amd64.deb
# reporting: /dev-shared/chef-packages/reporting/opscode-reporting_1.2.3-1_amd64.deb
# push-jobs-server: /dev-shared/chef-packages/push-jobs-server/opscode-push-jobs-server_1.1.6-1_amd64.deb
# analytics: /dev-shared/chef-packages/analytics/opscode-analytics_1.1.1-1_amd64.deb
servers:
- be-tier.lxc:
+ tier-be.lxc:
role: backend
ipaddress: 10.0.3.203
bootstrap: true
- fe1-tier.lxc:
+ tier-fe1.lxc:
role: frontend
ipaddress: 10.0.3.204
- # fe2-tier.lxc:
+ # tier-fe2.lxc:
# role: frontend
# ipaddress: 10.0.3.205
- # analytics-tier.lxc:
+ # tier-analytics.lxc:
# role: analytics
# ipaddress: 10.0.3.206
This config defines a tier cluster consisting of a single backend and a single frontend.
@@ -296,14 +324,14 @@
The following is an example of managing multiple clusters while still avoiding specifying
each cluster's config file.
mkdir -p ~/clusters/{clusterA,clusterB}
- dev-lxc cluster init tier > ~/clusters/clusterA/dev-lxc.yml
- dev-lxc cluster init standalone > ~/clusters/clusterB/dev-lxc.yml
- cd ~/clusters/clusterA && dev-lxc cluster start # starts clusterA
- cd ~/clusters/clusterB && dev-lxc cluster start # starts clusterB
+ dev-lxc init tier > ~/clusters/clusterA/dev-lxc.yml
+ dev-lxc init standalone > ~/clusters/clusterB/dev-lxc.yml
+ cd ~/clusters/clusterA && dev-lxc start # starts clusterA
+ cd ~/clusters/clusterB && dev-lxc start # starts clusterB
### Maintain Uniqueness Across Multiple Clusters
The default cluster configs are already designed to be unique from each other but as you build
more clusters you have to maintain uniqueness across the YAML config files for the following items.
@@ -318,14 +346,14 @@
`api_fqdn` uniqueness only matters when clusters with the same `api_fqdn` are running.
If cluster B is started with the same `api_fqdn` as an already running cluster A, then cluster B
will overwrite cluster A's DNS resolution of `api_fqdn`.
- It is easy to provide uniqueness. For example, you can use the following command to replace `-tier`
- with `-1234` in a tier cluster's config.
+ It is easy to provide uniqueness. For example, you can use the following command to replace `.lxc`
+ with `-1234.lxc` in a cluster's config.
- sed -i 's/-tier/-1234/' dev-lxc.yml
+ sed -i 's/\.lxc/-1234.lxc/' dev-lxc.yml
* IP Addresses
IP addresses uniqueness only matters when clusters with the same IP's are running.
@@ -371,11 +399,11 @@
The shared base container is the second to get created and is identified by the
"s-" prefix on the container name.
`DevLXC::ChefServer#create_base_server` controls the creation of a shared base container.
- Chef packages that are common to all servers in a Chef cluster, such as Chef server,
+ Chef packages that are common to all servers in a Chef cluster, such as chef-server-core,
opscode-reporting and opscode-push-jobs-server are installed using `dpkg` or `rpm`.
Note the manage package will not be installed at this point since it is not common to all
servers (i.e. it does not get installed on backend servers).
@@ -405,18 +433,15 @@
unique base container. These unique base containers make it very easy to quickly recreate
a Chef cluster from a clean starting point.
### Destroying Base Containers
-When using `dev-lxc cluster destroy` to destroy an entire Chef cluster or `dev-lxc server destroy [NAME]`
-to destroy a single Chef server you have the option to also destroy any or all of the three types
-of base containers associated with the cluster or server.
+When using `dev-lxc destroy` to destroy servers you have the option to also destroy any or all of
+the three types of base containers associated with the servers.
-Either of the following commands will list the options available.
+The following command will list the options available.
- dev-lxc cluster help destroy
-
- dev-lxc server help destroy
+ dev-lxc help destroy
Of course, you can also just use the standard LXC commands to destroy any container.
lxc-destroy -n [NAME]