docker-rainbow 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 57676b6de93c1ed4dc502c7a83656ecb8eb4082d
+  data.tar.gz: 0d4a027e6676fb07393ba60d895287f2c9d4146d
+SHA512:
+  metadata.gz: acc9adc6da0606edd8145ff414b05ec0373bc39801078e62da03091e77c5e810d7e1c6c7e5f8c51bdf4dc7e8a5aeecc987e1217b12690c8c70d5da394b1eeacd
+  data.tar.gz: dfdc49afe47b3c96ceac9bfdaab223a968ffef7d9a351950bd3653dfc7ea568f7cbd914dd1b6d40ecc59c5c04f98af9d2ca2aa3aeb9b19b3099a3f649c33e8cc

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.2.2
+before_install: gem install bundler -v 1.10.6

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in docker-rainbow.gemspec
+gemspec

data/README.md

@@ -0,0 +1,156 @@
+# Docker::Rainbow
+
+This gem implements a scheme for choosing terse but meaningful names of Docker
+containers. The names that it chooses convey information about when and how
+containers were deployed, and how they relate to one another, without resorting
+to unreadable random gobbledegook for names.
+
+(If you want random gobbledegook, you should refer to containers by their IDs,
+which are globally unique. Names are there to make the operator's life easier
+by giving her a way to refer to containers when she types docker CLI commands.)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'docker-rainbow'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install docker-rainbow
+
+## Usage
+
+There is no command-line interface to the rainbow. Its API is minimal and
+hopefully self-documenting.
+
+```ruby
+require 'docker/rainbow'
+
+rainbow = Docker::Rainbow.new()
+
+# The color will be one of "blue," "green," "purple," etc. We try to find a
+# color that isn't in use, but wrap around when necessary.
+puts "Launching containers for the #{rainbow.color} epoch"
+
+# This will return an Array like so:
+#  ['blue_cassandra_1', 'blue_cassandra_2', 'blue_cassandra_3']
+names = rainbow.name_containers('spotify/cassandra:latest', count:3)
+
+
+names.each do |name|
+  system("docker run -n #{name} spotify/cassandra:latest")
+end
+```
+
+### Reusing names
+
+By default, the rainbow raises an exception if it tries to choose any name
+that is already in use by any container, running _or_ exited. Because rainbow's
+palette has just six colors, this will typically happen after just a few
+deploys.
+
+In most cases, by the time we wrap back around to a previous color, the original
+containers will have exited long ago; it's unlikely that you will have six
+"vintages" of a given service running at the same time. For this reason the
+rainbow will automatically remove exited containers with conflicting names,
+unless you specify `gc:false` when you build your rainbow.
+
+```ruby
+  rainbow.name_containers('spotify/cassandra:latest', gc:false)
+```
+
+However: if any container with a conflicting name is *still running*, this
+counts as a conflict and the rainbow will raise an exception because in all
+likelihood, something is seriously wrong with the containers deployed to this
+box. (How often would you have six different revisions of software running
+on one box at once time?)
+
+If you will handle naming conflicts yourself, you can ask the rainbow to ignore
+them and/or opt out of the built-in garbage collection.
+
+```ruby
+  rainbow.name_containers('spotify/cassandra:latest', reuse:true, gc:false)
+```
+
+### Accounting for entrypoints
+
+For images that expose an `ENTRYPOINT` rather than a `CMD`, you might end up
+with several long-lived containers launched from the same base image but with
+conceptually different purposes. You can tell the rainbow the name of the
+command you will be passing to `docker run` in order to choose unambiguous
+names.
+
+Note that you don't need to use the verbatim command; you could use a nickname
+for the "role" of the container.
+
+```ruby
+  rainbow.name_containers('docker/swarm', cmd: 'manager')
+    # => ["blue_swarm_manager"]
+
+  rainbow.name_containers('docker/swarm', cmd: 'node', count:2)
+    # => ["blue_swarm_node_1", "blue_swarm_node_2"]
+```
+
+We **strongly encourage** you to use a terse, meaningful description of the
+cmd instead of passing the entire command word-for-word into the rainbow. You
+might find it super interesting that you invoked busybox as `/bin/sh -c ls foo`,
+but the people who look at `docker ps` output probably don't care to see a
+container named `busybox_bin-sh-c-ls-foo`!
+
+To encourage you to choose terse names, Rainbow will extract the _first_
+alphanumeric word from the cmd and use it alone as a suffix for your container
+named. If this is an issue, refer to "Customizing Container Names", below.
+
+### Multi-tenancy
+
+You might be deploying containers to a cluster that is in use by other tenants;
+in this case, you want to choose a unique prefix to indicate which tenant owns
+which container. Rainbow borrows from the nomenclature used by `docker-compose`
+and supports an optional *project name* for all of your containers.
+
+```ruby
+  rainbow = Docker::Rainbow.new(project: 'development')
+
+  rainbow.name_containers('foo') # => ["development_blue_foo]
+```
+
+## Customizing Container Names
+
+If you absolutely insist on having more colors, you can pass a custom
+palette.
+
+```ruby
+  Docker::Rainbow.new(palette: ['mauve', 'pink', 'chartreuse', ...])
+```
+
+You can also subclass Rainbow and override its private methods if you want
+to be more opinionated about naming choices.
+
+```ruby
+  class PedanticRainbow < Docker::Rainbow
+    # Our full command is relevant to the container's personality; include
+    # every word, not just the first word! Also use periods to separate
+    # command words, not hyphens.
+    private def cmd_suffix(cmd)
+      cmd.split(/[^A-Za-z0-9]+/).join('.')
+    end
+  end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/docker-rainbow. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](contributor-covenant.org) code of conduct.
+

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "docker/rainbow"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/docker-rainbow.gemspec

@@ -0,0 +1,24 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'docker/rainbow/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "docker-rainbow"
+  spec.version       = Docker::Rainbow::VERSION
+  spec.authors       = ["Tony Spataro"]
+  spec.email         = ["tony@rightscale.com"]
+
+  spec.summary       = %q{An Ops-friendly container naming scheme for Docker.}
+  spec.description   = %q{Chooses terse, meaningful, unique names for containers based on base image, existing containers, and other factors.}
+  spec.homepage      = "https://github.com/xeger/docker-rainbow"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec"
+end

data/lib/docker/rainbow/version.rb

@@ -0,0 +1,5 @@
+module Docker
+  class Rainbow
+    VERSION = "0.1.0"
+  end
+end

data/lib/docker/rainbow.rb

@@ -0,0 +1,147 @@
+require 'set'
+
+require 'docker/rainbow/version'
+
+module Docker
+  class Rainbow
+    class Conflict < StandardError
+      attr_reader :names
+
+      def initialize(problem)
+        if problem.is_a?(String)
+          @names = []
+          super(problem)
+        elsif problem.respond_to?(:each) && problem.respond_to?(:join)
+          @names = problem
+          super("Names in use: #{problem.join(', ')}")
+        else
+          super("Unknown error: #{problem.inspect}")
+        end
+      end
+    end
+
+    # All the colors of the Docker rainbow, in alphabetical order. You can
+    # override these if you need more deployment epochs, but remember: the
+    # goal is meaningful container names, not names that record the history
+    # of the world. (That's what `docker logs` is for...)
+    PALETTE = ['blue', 'green', 'orange', 'red', 'yellow', 'violet'].freeze
+
+    # Execute a shell command and return its output. If the command fails,
+    # raise RuntimeError with details of the command that failed.
+    # TODO use a pretty gem to do this, and/or a Ruby docker CLI wrapper
+    #
+    # @param [String] cmd
+    # @return [Array] of output lines
+    def self.shell(cmd)
+      output = `#{cmd}`
+      raise RuntimeError, "Command failed: #{cmd}" unless $?.success?
+      output.split("\n")
+    end
+
+    # @param [String] project a prefix that comes before the colors, default
+    #   is none
+    # @param [Array] colors a list of colors to choose from, default is the
+    #   classic six colors of the rainbow, in alphabetical order.
+    def initialize(project:nil, palette:PALETTE)
+      @project = project
+      @palette = palette
+      @color   = choose_color
+    end
+
+    # Choose names for one or more containers that will be launched from a
+    # given image. Optionally specify a command, a number of containers, and
+    # what to do about dead or running containers with overlapping names.
+    #
+    # By default, the rainbow will automatically run `docker rm` for any exited
+    # container whose name is about to be reused; you can specify `gc:false`
+    # to cause it to raise instead.
+    #
+    # The rainbow will _not_ rm containers that are running
+    #
+    # @param [String] image a Docker image label i.e. a `repository:tag` pair
+    # @param [Integer] count number of containers to name
+    # @param [Boolean] gc if true rm dead containers with conflicting names
+    # @param [Boolean] reuse if true, ignore conflicts with running containers
+    def name_containers(image, cmd:nil, count:1, gc:true, reuse:false)
+      prefix = "#{@color}_#{base_name(image)}"
+      prefix = "#{prefix}_#{cmd_suffix(cmd)}" if cmd
+
+      result = []
+      if count == 1
+        result << prefix
+      else
+        (1..count).each do |i|
+          result << "#{prefix}_#{i}"
+        end
+      end
+
+      remove_dead(result) if gc
+
+      unless reuse
+        in_use = find_in_use(result)
+        raise Conflict.new(in_use) if in_use.any?
+      end
+
+      result
+    end
+
+    # Find a color that is not being used by any running container in our
+    # project. If all colors are in use, return the first color in the palette.
+    private def choose_color
+      all = self.class.shell("docker ps --format={{.Names}}").compact
+
+      if @project
+        prefix = "#{project}_"
+        all.reject! { |n| !n.start_with?(prefix) }
+        all = all.map { |cn| cn[prefix.length..-1] }
+      end
+
+      # Find colors that are in use
+      in_use = Set.new(all.map { |cn| cn.split('_')[0] }) & @palette
+
+      # Find a color that isn't in use; default to the first color if
+      # everything is already used
+      @palette.detect { |c| !in_use.include?(c) } || @palette.first
+    end
+
+    # Given an image tag, derive a meaningful but terse "base name" for
+    # containers that will be launched from that image.
+    private def base_name(image)
+      # Remove registry namespace (anything before the final slash)
+      # as well as tag.
+      if image.include?("/")
+        base = image.split('/').last.split(':').first
+      else
+        base = image.split(':').first
+      end
+
+      # Strip noise-word suffixes from image name
+      base.sub!(/_service$/, '')
+
+      base
+    end
+
+    # Transform a cmd into a valid container name fragment. Split cmd into
+    # words and return ONLY the first word.
+    # This assumes that the first word of the command is sufficient to
+    # uniquely identify the container's role, and that any remaining words are
+    # noise.
+    private def cmd_suffix(cmd)
+      words = cmd.split(/[^A-Za-z0-9]+/)
+      words.first
+    end
+
+    def remove_dead(containers)
+      words = ['docker', 'ps', '--filter=status=exited', '--format={{.ID}}']
+      containers.each { |cn| words << "--filter=name=#{cn}" }
+      output = self.class.shell(words.join(' '))
+      output.each { |dead| shell("docker rm #{dead}") }
+    end
+
+    def find_in_use(containers)
+      words = ['docker', 'ps', '--format={{.Names}}']
+      containers.each { |cn| words << "--filter=name=#{cn}" }
+      self.class.shell(words.join(' '))
+    end
+  end
+end

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: docker-rainbow
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tony Spataro
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-11-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Chooses terse, meaningful, unique names for containers based on base
+  image, existing containers, and other factors.
+email:
+- tony@rightscale.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- docker-rainbow.gemspec
+- lib/docker/rainbow.rb
+- lib/docker/rainbow/version.rb
+homepage: https://github.com/xeger/docker-rainbow
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: An Ops-friendly container naming scheme for Docker.
+test_files: []