nutkins 0.10.3 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: de316082b0b28edd1ebc742d5ec401abe2a66dbd
-  data.tar.gz: 7f9bed97a340303f36f36f15cce9b148dccfd1b7
+  metadata.gz: 52cf42f9bda34623d363c0949b12a37820f19ee6
+  data.tar.gz: 81197095413f31fac40a8e43b9e04dff878d824b
 SHA512:
-  metadata.gz: e99e6ebd941cbbf63c5a18afee83969a3be2c808b51e50847a09921482c7772be8d031f3da79e498d83bfa24258cc4b23500a67062946537e768a0057377e6e1
-  data.tar.gz: 9027b483aea433b86ddb909d03872e7697575b52c4386a80b62ea0b8a9968fd3970f7d3e1c91081bd3897258e9a9df4b7b04369fb40f979d3c8d9c3a01e240b2
+  metadata.gz: b76082e30b1f978daed27171a39039017754c894f34795f40b15b2d1602bb6676247b42318abda039c4b473868307402264158381e0c38daf23089ed882c4c3d
+  data.tar.gz: 3958e780eb1148ba2a9e879848bcfca8f87f99c783a2d05495f4d5272df82bdd7fb366576e2eb65422a18da2eaaf9e0b09e820a0309a3a4b7a9932b279814305

data/lib/nutkins/version.rb

@@ -1,3 +1,3 @@
 module Nutkins
-  VERSION = "0.10.3"
+  VERSION = "0.11.0"
 end

data/lib/nutkins.rb

@@ -30,6 +30,7 @@ module Nutkins
       @img_configs = {}
       # when an image is built true is stored against it's name to avoid building it again
       @built = {}
+      @etcd_running = false
       @project_root = project_dir || Dir.pwd
       cfg_path = File.join(@project_root, CONFIG_FILE_NAME)
       if File.exists? cfg_path
@@ -153,6 +154,8 @@ module Nutkins
     def run path, reuse: false, shell: false
       cfg = get_image_config path
       tag = cfg['tag']
+
+      start_etcd_container if cfg['etcd']
       create_args = []
       if shell
         raise '--shell and --reuse arguments are incompatible' if reuse
@@ -237,11 +240,14 @@ module Nutkins
       puts "TODO: exec #{path}: #{cmd.join ' '}"
     end
 
-    # TODO: move this stuff into another file
     def start_etcd_container
+      return if @etcd_running
+      # TODO: move this stuff into another file
       name = get_etcd_container_name
       return unless name
 
+      # TODO: update existing etcd server rather than creating new container...
+      #       this will let confd instances respond to updates
       existing = Docker.container_id_for_name name
       if existing
         Docker.run 'stop', name
@@ -298,6 +304,7 @@ module Nutkins
             puts res
           end
         end
+        @etcd_running = true
       else
         puts 'failed to start etcd container'
       end
@@ -319,10 +326,7 @@ module Nutkins
     end
 
   private
-    def get_etcd_container_name
-      repository = @config.repository
-      repository && "nutkins-etcd-#{repository}"
-    end
+    def get_etcd_container_name; "nutkins-etcd"; end
 
     # path should be "." or a single element path referencing the project root
     def get_image_config path

data/readme.md

@@ -0,0 +1,169 @@
+# Nutkins
+
+[![build status](https://circleci.com/gh/ohjames/nutkins.png)](https://circleci.com/gh/ohjames/nutkins)
+
+nutkins provides a way to build and test clusters based on one or more containers.
+ * A easier and more flexible way to build docker images than `Dockerfile`.
+   * Can run multiple commands to build a layer with comments for each.
+   * No need for `.dockerignore`.
+   * Caches each command in a layer and rebuilds from cache in a fraction of a second.
+ * Test services that use multiple containers without having to use VMs.
+ * Support for etcd/environment variables and confd.
+  * nutkins can manage a local etcd server and its data to test confd configurations.
+  * nutkins can manage a confd configuration using a sensible convention-over-configuration approach.
+ * Manages secrets encrypted with gpg.
+
+nutkins works great with:
+ * [etcd](https://github.com/coreos/etcd) - a distributed key-value data store.
+ * [confd](https://github.com/kelseyhightower/confd) - a system for building configuration files from data stored using `etcd` (and other data stores).
+ * [smell-baron](https://github.com/ohjames/smell-baron) - an init system for docker containers
+
+## installation
+
+```bash
+gem install nutkins
+```
+
+## configuring nutkins
+
+### The project root
+
+In the project root there should be a `nutkins.yaml` which may contain global configuration:
+
+```yaml
+version: 0.0.1
+repository: myorg
+```
+
+With this configuration each built image will be tagged `myorg/${image_name}:0.0.1` where `0.0.1` may also be overridden per image.
+
+For projects that consist of a single `nutkin.yaml` in the project root then `nutkins.yaml` may be omitted and these fields should be present in the `nutkin.yaml`.
+
+### Images
+
+Each subdirectory in the project root that contains a file `nutkin.yaml` is used to build a docker image. The following project contains an image in a subdirectory `base` that extends the `ubuntu:16.04` container hosted on docker hub:
+
+```yaml
+base: ubuntu:16.04
+
+build:
+  resources:
+    -
+      source: https://github.com/ohjames/smell-baron/releases/download/v0.3.1/smell-baron
+      dest: bin/smell-baron
+      mode: 0755
+    -
+      source: https://github.com/kelseyhightower/confd/releases/download/v0.12.0-alpha3/confd-0.12.0-alpha3-linux-amd64
+      dest: bin/confd
+      mode: 0755
+    -
+      source: https://github.com/coreos/etcd/releases/download/v3.0.6/etcd-v3.0.6-linux-amd64.tar.gz
+      extract: "*/etcdctl"
+      dest: bin/etcdctl
+      mode: 0755
+  commands:
+    - run:
+      - apt-get update
+      - apt-get install -y vim zsh less nano rsync git net-tools
+      - groupadd -g 5496 sslcerts
+    - add: bin/* /bin/
+    - entrypoint: ["/bin/smell-baron"]
+```
+
+The `resources` section downloads files to local directories so that they can be used in the image. In the case of `confd` it also extracts a file from a `tar.gz` compressed archive.
+
+The `commands` section is like a `Dockerfile` and is used to build a container. In this case it runs multiple commands, add some files to the image and sets an `entrypoint`. This image would be tagged `myorg/base:0.0.1`. The image name comes from the subdirectory but can be overriden along with the `version`:
+
+```yaml
+base: ubuntu:16.04
+image: base_image
+version: 0.0.2
+build:
+  # ... as before
+```
+
+To build this image:
+```bash
+nutkins build base
+```
+
+This will output various information as it builds the image. If the same command is run again it will reuse data from the cache, exiting in less than a second:
+
+```bash
+% nutkins build base
+cached: apt-get update && apt-get install -y vim zsh less nano rsync git net-tools && groupadd -g 5496 sslcerts
+cached: #(nop) add bin/confd:33472f6b8f9522ec7bdb01a8feeb03fb bin/etcdctl:8edfaac7c726e8231c6e0e8f75ffb678 bin/smell-baron:909345dcbc4a029d42f39278486a32b9 /bin/
+cached: #(nop) entrypoint ["/bin/smell-baron"]
+unchanged image: myorg/base:0.0.1
+```
+
+To run a container from this image (this first rebuilds the image):
+```bash
+nutkins run base
+```
+
+To run a container from this image and open an interactive shell (this only works if the `entrypoint` is [smell-baron](https://github.com/ohjames/smell-baron)):
+```bash
+nutkins run -s base
+```
+
+### Image project dependencies
+
+When a `nutkin.yaml` file refers to a `base` image that exists in the current project then `nutkins` ensures the base image is up to date before any images are built that use or extend it.
+
+### Sharing local data with images
+
+When using `nutkins` to test images it can be useful to share data in the host system with the running containers:
+
+```yaml
+base: base
+
+build:
+  commands:
+    # ... build commands go here
+create:
+  volumes:
+    - ssl -> /etc/ssl
+    - ejabberd-etc -> /tmp/ejabberd-etc
+    - ejabberd-var -> /var/lib/ejabberd
+```
+
+If `nutkins.yaml` is in the directory `subdir` the volume `ssl` will be searched for first in `subdir/volumes/ssl` and then `volumes/ssl`.
+
+### Sharing ports with the host operating system
+
+```yaml
+create:
+  ports:
+    - 5222
+    - 5269
+```
+
+### Testing images configured with etcd
+
+The following `nutkin.yaml` shows how to manage a local `etcd` cluster:
+
+```yaml
+base: base
+
+build:
+  commands:
+    # ... as before
+create:
+  # ... as before
+etcd:
+  data:
+    ejabberd/node_name: ejabberd@myhost
+    ejabberd/hostname: myhost.net
+    ejabberd/muc_host: c.@HOST@
+```
+
+When running a container that has etcd data `nutkins` will first start up a helper container running `etcd` and use it to serve the etcd data from every `nutkin.yaml` in the project. To access this `etcd` data from within the container:
+
+```bash
+etcd2_host=$(ip route | grep '^default' | cut -d' ' -f3)
+# use confd to build the configuration files from the data stored in etcd
+confd -onetime -backend etcd -node http://$etcd_host:2379
+```
+
+The same command will work within a CoreOS cluster or any other etcd backed cluster.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: nutkins
 version: !ruby/object:Gem::Version
-  version: 0.10.3
+  version: 0.11.0
 platform: ruby
 authors:
 - James Pike
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-08-27 00:00:00.000000000 Z
+date: 2016-08-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -78,7 +78,6 @@ files:
 - ".rspec"
 - ".travis.yml"
 - Gemfile
-- README.md
 - Rakefile
 - bin/console
 - bin/nutkins
@@ -91,6 +90,7 @@ files:
 - lib/nutkins/download.rb
 - lib/nutkins/version.rb
 - nutkins.gemspec
+- readme.md
 homepage: http://github.com/ohjames/nutkins
 licenses: []
 metadata:

data/README.md

@@ -1,7 +0,0 @@
-# Nutkins
-
-[![build status](https://circleci.com/gh/ohjames/nutkins.png)](https://circleci.com/gh/ohjames/nutkins)
-
-Nutkins is a tool to help build and test multiple docker containers configured via etcd and confd. You can:
- * Describe test volumes and etcd variables using yaml.
- * Easily rebuild and test containers with a few simple commands.