Class: Tainers::Specification::Bare

Inherits:
Object
  • Object
show all
Defined in:
lib/tainers/specification.rb

Overview

An object representing a container configuration (a “specification”), with methods for checking and/or ensuring existence (by name).

While this can be used directly, it is not intended for direct instantiation, instead designed to be used via Tainers::specify, which provides name determination logic for organizing containers by their configuration.

Instance Method Summary collapse

Constructor Details

#initialize(args = {}) ⇒ Bare

Creates a new container specification that uses the same parameters supported by the Docker::Container::create singleton method. These parameters align with that of the docker daemon remote API.

Note that it requires a container name, and an Image. Without an Image, there’s nothing to build. The name is essential to the purpose of the entire Tainers project.

Raises:

  • (ArgumentError) 


20
21
22
23
24
25
26
27
 
# File 'lib/tainers/specification.rb', line 20

def initialize args={}
  raise ArgumentError, 'A name is required' unless valid_name? args['name']

  raise ArgumentError, 'An Image is required' unless valid_image? args['Image']

  # Maketh a copyeth of iteth
  @args = {}.merge(args)
end

Instance Method Details

#create ⇒ Object

Creates the container named by this specification, if it does not already exist.

Returns true (self, actually) if the invocation resulted in the creation of a new container; false otherwise.

A false condition could result from:

  • The container already existing

  • The container being simultaneously created by another actor, with your invocation losing the race.

A failure to create due to operational or semantic issues should result in an exception. Therefore, any non-exceptional case should mean that a container of the expected name exists, though in the false result case there is no firm guarantee that the existing container has the requested configuration e.



60
61
62
63
64
 
# File 'lib/tainers/specification.rb', line 60

def create
  return false if exists?
  return self if Tainers::API.create(@args)
  false
end

#ensure ⇒ Object

Ensures that the container named by this specification exists, creating the container if necessary.

Note that this only ensures that a container with the proper name exists; it does not ensure that the existing container has a matching configuration.

Returns true if the container reliably exists (it has been shown to exist, or was successfully created, or failed to create due to a name conflict). All other cases should result in exceptions.



38
39
40
41
42
 
# File 'lib/tainers/specification.rb', line 38

def ensure
  return self if exists?
  return self if Tainers::API.create_or_conflict(@args)
  return nil
end

#exists? ⇒ Boolean

True if the container of the appropriate name already exists. False if not.

Returns:

  • (Boolean) 


79
80
81
 
# File 'lib/tainers/specification.rb', line 79

def exists?
  ! Tainers::API.get_by_name(name).nil?
end

#image ⇒ Object

The image of the container described by this specification. Note that this is a string (a tag or image ID) and not a more complex object.



74
75
76
 
# File 'lib/tainers/specification.rb', line 74

def image
  @args['Image']
end

#name ⇒ Object

The name of the container described by this specification.



67
68
69
 
# File 'lib/tainers/specification.rb', line 67

def name
  @args['name']
end