dockerapi 0.6.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 90acd383975c4846ca2d6bfb91aa15d9898ce0101557ca50481f20729871ef73
-  data.tar.gz: 03d01594692f5c2093bf3e91b4f67635d2bd8e1bf0360217747ea4aa8d2c6840
+  metadata.gz: aeb3c1971c26c62d0737576e5ec79f2abcf536b1148be5272be8f501dfcae852
+  data.tar.gz: 1392073ca52d6fecfc12e642368713c2fa44a9ebbcd7629de5fb54faf9ac7209
 SHA512:
-  metadata.gz: 56a36a3c8b73fc0a8ae02cc68bd93b6b858be21d8c9c6d033b5f1d34d581f646dbb9e77df2e0a9d216c2a835eec3bd8e1abb62ade82aa6ec818ef081b5181d5d
-  data.tar.gz: 101c74b35333664dc5573d5443f2c7d75d5c8de9a43a2f70a7a54e5bb5673091eebe31dfc9ed5845c1052f47907dc6d7873f3bbe84a5015e10f5411458993cb9
+  metadata.gz: 3b03b8e5ce6d95f19c8dd6d357277a102fcc170b35ac989cd080db27c66efcad63125aaedab1c971a8ed435bed7c7447979d332a1b7f43686a2217907bf21fe8
+  data.tar.gz: 62cd2888ad859834cf949a6189f6e863e1b2f23ce9849fce4a39a1248cfa74efeaff5e0e6220a165d6b7980445a7773dc4bc3f8d4a678fc364a06b205fc07630

data/CHANGELOG.md

@@ -1,16 +1,70 @@
+# 0.10.0
+
+Add `Docker::API::Service` methods:
+* create
+* update
+* list
+* details
+* logs
+* delete
+
+# 0.9.0
+
+Significant change: `#inspect` is now deprecated and replaced by `#details` in the following classes:
+* `Docker::API::Container`
+* `Docker::API::Image`
+* `Docker::API::Network`
+* `Docker::API::Volume`
+* `Docker::API::Exec`
+* `Docker::API::Swarm`
+* `Docker::API::Node`
+
+The method will be removed in the refactoring phase.
+
+# 0.8.1
+
+Restore the default `#inspect` output for `Docker::API` classes. 
+
+Most of the overriding methods take an argument, therefore calling using the expect arguments will return a `Docker::API::Response` object, while calling without arguments will return `Kernel#inspect`. To avoid this confusing schema, next release will rename `#inspect` within `Docker::API` to something else.
+
+# 0.8.0
+
+Add `Docker::API::Swarm` methods:
+* init
+* update
+* ~~inspect~~ details
+* unlock_key
+* unlock
+* join
+* leave
+
+Add `Docker::API::Node` methods:
+* list
+* ~~inspect~~ details
+* update
+* delete
+
+Query parameters and request body json can now skip the validation step with `:skip_validation => true` option.
+
+# 0.7.0
+
+Significant changes: `Docker::API::Connection` is now a regular class intead of a Singleton, allowing multiple connections to be stablished within the same program (replacing the connect_to implementation). To leverage this feature, API-related classes must be initialized and may or may not receive a `Docker::API::Connection` as parameter, or it'll connect to `/var/run/docker.sock` by default. For this reason, class methods were replaced with instance methods. Documentation will reflect this changes of implementation.
+
+Bug fix: Image push returns a 20X status even when the push is unsucessful. To prevent false positives, it now requires the authentication parameters to be provided, generating a 403 status for invalid credentials or an error if they are absent.
+
 # 0.6.0
 
 Add connection parameters specifications with connect_to in Docker::API::Connection.
 
-Add Docker::API::Exec methods:
+Add `Docker::API::Exec` methods:
 * create
 * start
 * resize
-* inspect
+* ~~inspect~~ details
 
 # 0.5.0
 
-Add Docker::API::System methods:
+Add `Docker::API::System` methods:
 * auth
 * ping
 * info
@@ -18,7 +72,7 @@ Add Docker::API::System methods:
 * events
 * df
 
-Add new response class Docker::API::Response with the following methods:
+Add new response class `Docker::API::Response` with the following methods:
 * json
 * path
 * success?
@@ -27,9 +81,9 @@ Error classes output better error messages.
 
 # 0.4.0
 
-Add Docker::API::Network methods:
+Add `Docker::API::Network` methods:
 * list
-* inspect
+* ~~inspect~~ details
 * create
 * remove
 * prune
@@ -38,9 +92,9 @@ Add Docker::API::Network methods:
 
 # 0.3.0
 
-Add Docker::API::Volume methods:
+Add `Docker::API::Volume` methods:
 * list
-* inspect
+* ~~inspect~~ details
 * create
 * remove
 * prune
@@ -48,8 +102,8 @@ Add Docker::API::Volume methods:
 
 # 0.2.0
 
-Add Docker::API::Image methods:
-* inspect
+Add `Docker::API::Image` methods:
+* ~~inspect~~ details
 * history
 * list
 * search
@@ -64,13 +118,13 @@ Add Docker::API::Image methods:
 * build
 * delete_cache
 
-Add Docker::API::System.auth (untested) for basic authentication
+Add `Docker::API::System.auth` (untested) for basic authentication
 
 # 0.1.0
 
-Add Docker::API::Container methods:
+Add `Docker::API::Container` methods:
 * list
-* inspect
+* ~~inspect~~ details
 * top
 * changes
 * start

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    dockerapi (0.6.0)
+    dockerapi (0.10.0)
       excon (~> 0.74.0)
 
 GEM

data/README.md

@@ -23,68 +23,71 @@ Or install it yourself as:
 ### Images
 
 ```ruby
+# Connect to local image endpoints
+image = Docker::API::Image.new
+
 # Pull from a public repository
-Docker::API::Image.create( fromImage: "nginx:latest" )
+image.create( fromImage: "nginx:latest" )
 
 # Pull from a private repository
-Docker::API::Image.create( {fromImage: "private/repo:tag"}, {username: "janedoe", password: "password"} )
+image.create( {fromImage: "private/repo:tag"}, {username: "janedoe", password: "password"} )
 
 # Create image from local tar file
-Docker::API::Image.create( fromSrc: "/path/to/file.tar", repo: "repo:tag" )
+image.create( fromSrc: "/path/to/file.tar", repo: "repo:tag" )
 
 # Create image from remote tar file
-Docker::API::Image.create( fromSrc: "https://url.to/file.tar", repo: "repo:tag" )
+image.create( fromSrc: "https://url.to/file.tar", repo: "repo:tag" )
 
 # List images
-Docker::API::Image.list
+image.list
 
 # Inspect image
-Docker::API::Image.inspect("image")
+image.details("image")
 
 # History
-Docker::API::Image.history("image")
+image.history("image")
 
 # Search image
-Docker::API::Image.search(term: "busybox", limit: 2)
-Docker::API::Image.search(term: "busybox", filters: {"is-automated": {"true": true}})
-Docker::API::Image.search(term: "busybox", filters: {"is-official": {"true": true}})
+image.search(term: "busybox", limit: 2)
+image.search(term: "busybox", filters: {"is-automated": {"true": true}})
+image.search(term: "busybox", filters: {"is-official": {"true": true}})
 
 # Tag image
-Docker::API::Image.tag("current:tag", repo: "new:tag") # or
-Docker::API::Image.tag("current:tag", repo: "new", tag: "tag")
+image.tag("current:tag", repo: "new:tag") # or
+image.tag("current:tag", repo: "new", tag: "tag")
 
 # Push image
-Docker::API::Image.push("repo:tag") # to dockerhub
-Docker::API::Image.push("localhost:5000/repo:tag") # to local registry
-Docker::API::Image.push("private/repo", {tag: "tag"}, {username: "janedoe", password: "password"} # to private repository
+image.push("repo:tag") # to dockerhub
+image.push("localhost:5000/repo:tag") # to local registry
+image.push("private/repo", {tag: "tag"}, {username: "janedoe", password: "password"} # to private repository
 
 # Remove image
-Docker::API::Image.remove("image")
-Docker::API::Image.remove("image", force: true)
+image.remove("image")
+image.remove("image", force: true)
 
 # Remove unsued images (prune)
-Docker::API::Image.prune(filters: {dangling: {"false": true}})
+image.prune(filters: {dangling: {"false": true}})
 
 # Create image from a container (commit)
-Docker::API::Image.commit(container: container, repo: "my/image", tag: "latest", comment: "Comment from commit", author: "dockerapi", pause: false )
+image.commit(container: container, repo: "my/image", tag: "latest", comment: "Comment from commit", author: "dockerapi", pause: false )
 
 # Build image from a local tar file
-Docker::API::Image.build("/path/to/file.tar")
+image.build("/path/to/file.tar")
 
 # Build image from a remote tar file
-Docker::API::Image.build(nil, remote: "https://url.to/file.tar")
+image.build(nil, remote: "https://url.to/file.tar")
 
 # Build image from a remote Dockerfile
-Docker::API::Image.build(nil, remote: "https://url.to/Dockerfile")
+image.build(nil, remote: "https://url.to/Dockerfile")
 
 # Delete builder cache
-Docker::API::Image.delete_cache
+image.delete_cache
 
 # Export repo
-Docker::API::Image.export("repo:tag", "~/exported_image.tar")
+image.export("repo:tag", "~/exported_image.tar")
 
 # Import repo
-Docker::API::Image.import("/path/to/file.tar")
+image.import("/path/to/file.tar")
 ```
 
 ### Containers 
@@ -93,140 +96,258 @@ Let's test a Nginx container
 
 ```ruby
 # Pull nginx image
-Docker::API::Image.create( fromImage: "nginx:latest" )
+Docker::API::Image.new.create( fromImage: "nginx:latest" )
+
+# Connect to local container endpoints
+container = Docker::API::Container.new
 
 # Create container
-Docker::API::Container.create( {name: "nginx"}, {Image: "nginx:latest", HostConfig: {PortBindings: {"80/tcp": [ {HostIp: "0.0.0.0", HostPort: "80"} ]}}})
+container.create( {name: "nginx"}, {Image: "nginx:latest", HostConfig: {PortBindings: {"80/tcp": [ {HostIp: "0.0.0.0", HostPort: "80"} ]}}})
 
 # Start container
-Docker::API::Container.start("nginx")
+container.start("nginx")
 
 # Open localhost or machine IP to check the container running
 
 # Restart container
-Docker::API::Container.restart("nginx")
+container.restart("nginx")
 
 # Pause/unpause container
-Docker::API::Container.pause("nginx")
-Docker::API::Container.unpause("nginx")
+container.pause("nginx")
+container.unpause("nginx")
 
 # List containers
-Docker::API::Container::list
+container.list
 
 # List containers (including stopped ones)
-Docker::API::Container::list(all: true)
+container.list(all: true)
 
 # Inspect container
-Docker::API::Container.inspect("nginx")
+container.details("nginx")
 
 # View container's processes
-Docker::API::Container.top("nginx")
+container.top("nginx")
 
-# Let's enhance the output
-JSON.parse(Docker::API::Container.top("nginx").body)
+# Using json output
+container.top("nginx").json
 
 # View filesystem changes
-Docker::API::Container.changes("nginx")
+container.changes("nginx")
 
-# View filesystem logs
-Docker::API::Container.logs("nginx", stdout: true)
-Docker::API::Container.logs("nginx", stdout: true, follow: true)
+# View container logs
+container.logs("nginx", stdout: true)
+container.logs("nginx", stdout: true, follow: true)
 
 # View filesystem stats
-Docker::API::Container.stats("nginx", stream: true)
+container.stats("nginx", stream: true)
 
 # Export container
-Docker::API::Container.export("nginx", "~/exported_container")
+container.export("nginx", "~/exported_container")
 
 # Get files from container
-Docker::API::Container.archive("nginx", "~/html.tar", path: "/usr/share/nginx/html/")
+container.archive("nginx", "~/html.tar", path: "/usr/share/nginx/html/")
 
 # Stop container
-Docker::API::Container.stop("nginx")
+container.stop("nginx")
 
 # Remove container
-Docker::API::Container.remove("nginx")
+container.remove("nginx")
 
 # Remove stopped containers (prune)
-Docker::API::Container.prune
+container.prune
 ```
 
 ### Volumes
 
 ```ruby
+# Connect to local volume endpoints
+volume = Docker::API::Volume.new
+
 # Create volume
-Docker::API::Volume.create( Name:"my-volume" )
+volume.create( Name:"my-volume" )
 
 # List volumes
-Docker::API::Volume.list
+volume.list
 
 # Inspect volume
-Docker::API::Volume.inspect("my-volume")
+volume.details("my-volume")
 
 # Remove volume
-Docker::API::Volume.remove("my-volume")
+volume.remove("my-volume")
 
 # Remove unused volumes (prune)
-Docker::API::Volume.prune
+volume.prune
 ```
 
 ### Network
 
 ```ruby
+# Connect to local network endpoints
+network = Docker::API::Network.new
+
 # List networks
-Docker::API::Network.list
+network.list
 
 # Inspect network
-Docker::API::Network.inspect("bridge")
+network.details("bridge")
 
 # Create network
-Docker::API::Network.create( Name:"my-network" )
+network.create( Name:"my-network" )
 
 # Remove network
-Docker::API::Network.remove("my-network")
+network.remove("my-network")
 
 # Remove unused network (prune)
-Docker::API::Network.prune
+network.prune
 
 # Connect container to a network
-Docker::API::Network.connect( "my-network", Container: "my-container" )
+network.connect( "my-network", Container: "my-container" )
 
 # Disconnect container to a network
-Docker::API::Network.disconnect( "my-network", Container: "my-container" )
+network.disconnect( "my-network", Container: "my-container" )
 ```
 
 ### System
 
 ```ruby
+# Connect to local system endpoints
+sys = Docker::API::System.new
+
 # Ping docker api
-Docker::API::System.ping
+sys.ping
 
 # Docker components versions
-Docker::API::System.version
+sys.version
 
 # System info
-Docker::API::System.info
+sys.info
 
 # System events (stream)
-Docker::API::System.events(until: Time.now.to_i)
+sys.events(until: Time.now.to_i)
 
 # Data usage information
-Docker::API::System.df
+sys.df
 ```
 
 ### Exec
 
 ```ruby
+# Connect to local exec endpoints
+exe = Docker::API::Exec.new
+
 # Create exec instance, get generated exec ID
-response = Docker::API::Exec.create(container, AttachStdout:true, Cmd: ["ls", "-l"])
+response = exe.create(container, AttachStdout:true, Cmd: ["ls", "-l"])
 id = response.json["Id"]
 
 # Execute the command, stream from Stdout is stored in response data
-response = Docker::API::Exec.start(id)
+response = exe.start(id)
 print response.data[:stream]
 
 # Inspect exec instance
-Docker::API::Exec.inspect(id)
+exe.details(id)
+```
+
+### Swarm
+```ruby
+# Connect to local swarm endpoints
+swarm = Docker::API::Swarm.new
+
+# Init swarm
+swarm.init({AdvertiseAddr: "local-ip-address:2377", ListenAddr: "0.0.0.0:4567"})
+
+# Inspect swarm
+swarm.details
+
+# Update swarm
+swarm.update(version, {rotateWorkerToken: true})
+swarm.update(version, {rotateManagerToken: true})
+swarm.update(version, {rotateManagerUnlockKey: true})
+swarm.update(version, {EncryptionConfig: { AutoLockManagers: true }})
+
+# Get unlock key
+swarm.unlock_key
+
+# Unlock swarm
+swarm.unlock(UnlockKey: "key-value")
+
+# Join an existing swarm
+swarm.join(RemoteAddrs: ["remote-manager-address:2377"], JoinToken: "Join-Token-Here")
+
+# Leave a swarm
+swarm.leave(force: true)
+```
+
+### Node
+```ruby
+# Connect to local node endpoints
+node = Docker::API::Node.new
+
+# List nodes
+node.list
+
+# Inspect node
+node.details("node-id")
+
+# Update node (version, Role and Availability must be present)
+node.update("node-id", {version: "version"}, {Role: "worker", Availability: "pause" })
+node.update("node-id", {version: "version"}, {Role: "worker", Availability: "active" })
+node.update("node-id", {version: "version"}, {Role: "manager", Availability: "active" })
+
+# Delete node
+node.delete("node-id")
+```
+
+### Service
+```ruby
+# Connect to local service endpoints
+service = Docker::API::Service.new
+
+# List services
+service.list
+
+# Create a service
+service.create({Name: "nginx-service", 
+    TaskTemplate: {ContainerSpec: { Image: "nginx:alpine" }},
+    Mode: { Replicated: { Replicas: 2 } },
+    EndpointSpec: { Ports: [ {Protocol: "tcp", PublishedPort: 80, TargetPort: 80} ] }
+})
+
+# Update a service (needs version and current Spec)
+version = service.details( service ).json["Version"]["Index"]
+spec = service.details(service).json["Spec"]
+service.update("nginx-service", {version: version}, spec.merge!({ Mode: { Replicated: { Replicas: 1 } } }))
+
+# View service logs
+service.logs("nginx-service", stdout: true)
+
+# Inspect service 
+service.details("nginx-service")
+
+# Delete service 
+service.delete("nginx-service")
+
+```
+
+### Connection
+
+By default Docker::API::Connection will connect to local Docker socket at `/var/run/docker.sock`. See examples below to use a different path or connect to a remote address.
+
+```ruby
+# Setting different connections
+local = Docker::API::Connection.new('unix:///', socket: "/path/to/docker.sock")
+remote = Docker::API::Connection.new("http://127.0.0.1:2375") # change the IP address accordingly
+
+# Using default /var/run/docker.sock
+image_default = Docker::API::Image.new
+image_default.list
+
+# Using custom socket path
+image_custom = Docker::API::Image.new(local)
+image_custom.list
+
+# Using remote address
+image_remote = Docker::API::Image.new(remote)
+image_remote.list
 ```
 
 ### Requests
@@ -238,7 +359,7 @@ Requests should work as described in [Docker API documentation](https://docs.doc
 All requests return a response class that inherits from Excon::Response. Available attribute readers and methods include: `status`, `data`, `body`, `headers`, `json`, `path`, `success?`.
 
 ```ruby
-response = Docker::API::Image.create(fromImage: "busybox:latest")
+response = Docker::API::Image.new.create(fromImage: "busybox:latest")
 
 response
 => #<Docker::API::Response:0x000055bb390b35c0 ... >
@@ -269,6 +390,8 @@ response.success?
 
 `Docker::API::InvalidParameter` and `Docker::API::InvalidRequestBody` may be raised when an invalid option is passed as argument (ie: an option not described in Docker API documentation for request query parameters nor request body (json) parameters). Even if no errors were raised, consider validating the status code and/or message of the response to check if the Docker daemon has fulfilled the operation properly.
 
+To completely skip the validation process, add `:skip_validation => true` in the hash to be validated.
+
 ## 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.
@@ -277,28 +400,22 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ### Road to 1.0.0
 
-NS: Not Started
-
-WIP: Work In Progress
-
-
 | Class | Tests | Implementation | Refactoring |
 |---|---|---|---|
-| Container | Ok | Ok | NS |
-| Image | Ok | Ok | NS |
-| Volume | Ok | Ok | NS |
-| Network | Ok | Ok | NS |
-| System | Ok | Ok | NS |
-| Exec | Ok | Ok | NS |
-| Swarm | NS | NS | NS |
-| Node | NS | NS | NS |
-| Service | NS | NS | NS |
-| Task | NS | NS | NS |
-| Secret | NS | NS | NS |
-
-Misc: 
-* ~~Improve response object~~
-* ~~Improve error objects~~
+| Image | Ok | Ok | 8/7 |
+| Container | Ok | Ok | 8/14 |
+| Volume | Ok | Ok | 8/21 |
+| Network | Ok | Ok | 8/21 |
+| System | Ok | Ok | 8/21 |
+| Exec | Ok | Ok | 8/21 |
+| Swarm | Ok | Ok | 8/28 |
+| Node | Ok | Ok | 8/28 |
+| Service | 7/17 | 7/17 | 8/28 |
+| Task | 7/17 | 7/17 | 9/4 |
+| Secret | 7/17 | 7/17 | 9/4 |
+| Config | 7/17 | 7/17 | 9/4 |
+| Distribution | 7/17 | 7/17 | 9/4 |
+| Plugin | 7/24 | 7/24 | 9/4 |
 
 ## Contributing