dockerapi 0.5.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: f647538a729eaa623b009a4e97713761bc80579073ebfb8b9ab7bfa26b6b6d98
4
- data.tar.gz: ce3b40c357d635a47ab8c921b59254ef734c2ec1173da60e58ba1b6f7d325ecf
3
+ metadata.gz: 2fa69dcb4c7b79c558bc6749b51def3a8a056e39259ad8163c84fec253193c67
4
+ data.tar.gz: '0998c5433ddcd3c4bbcc43ea6c21d61220527f7864c524e83bf0b3aedec501fd'
5
5
  SHA512:
6
- metadata.gz: f845ea3e89761d9ab726f098d4ef4ca1586c92320616359b182d6f9dc24e7769b53c88a6d17d8257514303226b16fd08a841ced1645be68c19b4d4b31a8a9b4f
7
- data.tar.gz: 409819921a1135b593377d8c561d0d5f81013f519e98a547976b1563b4038bff91f5948a5cd00b9f7513026821811b9baa476306915b7b644768232238daf0f4
6
+ metadata.gz: cafcf788d269546dd338daf50247df1ee1cf6af16372b50a2a6404b2323e0f8d6f78384789c245d122855d325e355dd9f822e4c61e5df4fb5bb9c7af79e11cac
7
+ data.tar.gz: b63d32250bfa09e067b56b19a2737ffc35e130511cd17dd31ffbb71db494406ff2b9e85e6e7226161e126b4d423a6fd570c3da6695dcb0d18407ce1c9a706190
@@ -1,6 +1,60 @@
1
+ # 0.9.0
2
+
3
+ Significant change: `#inspect` is now deprecated and replaced by `#details` in the following classes:
4
+ * `Docker::API::Container`
5
+ * `Docker::API::Image`
6
+ * `Docker::API::Network`
7
+ * `Docker::API::Volume`
8
+ * `Docker::API::Exec`
9
+ * `Docker::API::Swarm`
10
+ * `Docker::API::Node`
11
+
12
+ The method will be removed in the refactoring phase.
13
+
14
+ # 0.8.1
15
+
16
+ Restore the default `#inspect` output for `Docker::API` classes.
17
+
18
+ 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.
19
+
20
+ # 0.8.0
21
+
22
+ Add `Docker::API::Swarm` methods:
23
+ * init
24
+ * update
25
+ * ~~inspect~~ details
26
+ * unlock_key
27
+ * unlock
28
+ * join
29
+ * leave
30
+
31
+ Add `Docker::API::Node` methods:
32
+ * list
33
+ * ~~inspect~~ details
34
+ * update
35
+ * delete
36
+
37
+ Query parameters and request body json can now skip the validation step with `:skip_validation => true` option.
38
+
39
+ # 0.7.0
40
+
41
+ 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.
42
+
43
+ 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.
44
+
45
+ # 0.6.0
46
+
47
+ Add connection parameters specifications with connect_to in Docker::API::Connection.
48
+
49
+ Add `Docker::API::Exec` methods:
50
+ * create
51
+ * start
52
+ * resize
53
+ * ~~inspect~~ details
54
+
1
55
  # 0.5.0
2
56
 
3
- Add Docker::API::System methods:
57
+ Add `Docker::API::System` methods:
4
58
  * auth
5
59
  * ping
6
60
  * info
@@ -8,7 +62,7 @@ Add Docker::API::System methods:
8
62
  * events
9
63
  * df
10
64
 
11
- Add new response class Docker::API::Response with the following methods:
65
+ Add new response class `Docker::API::Response` with the following methods:
12
66
  * json
13
67
  * path
14
68
  * success?
@@ -17,9 +71,9 @@ Error classes output better error messages.
17
71
 
18
72
  # 0.4.0
19
73
 
20
- Add Docker::API::Network methods:
74
+ Add `Docker::API::Network` methods:
21
75
  * list
22
- * inspect
76
+ * ~~inspect~~ details
23
77
  * create
24
78
  * remove
25
79
  * prune
@@ -28,9 +82,9 @@ Add Docker::API::Network methods:
28
82
 
29
83
  # 0.3.0
30
84
 
31
- Add Docker::API::Volume methods:
85
+ Add `Docker::API::Volume` methods:
32
86
  * list
33
- * inspect
87
+ * ~~inspect~~ details
34
88
  * create
35
89
  * remove
36
90
  * prune
@@ -38,8 +92,8 @@ Add Docker::API::Volume methods:
38
92
 
39
93
  # 0.2.0
40
94
 
41
- Add Docker::API::Image methods:
42
- * inspect
95
+ Add `Docker::API::Image` methods:
96
+ * ~~inspect~~ details
43
97
  * history
44
98
  * list
45
99
  * search
@@ -54,13 +108,13 @@ Add Docker::API::Image methods:
54
108
  * build
55
109
  * delete_cache
56
110
 
57
- Add Docker::API::System.auth (untested) for basic authentication
111
+ Add `Docker::API::System.auth` (untested) for basic authentication
58
112
 
59
113
  # 0.1.0
60
114
 
61
- Add Docker::API::Container methods:
115
+ Add `Docker::API::Container` methods:
62
116
  * list
63
- * inspect
117
+ * ~~inspect~~ details
64
118
  * top
65
119
  * changes
66
120
  * start
@@ -1,7 +1,7 @@
1
1
  PATH
2
2
  remote: .
3
3
  specs:
4
- dockerapi (0.5.0)
4
+ dockerapi (0.9.0)
5
5
  excon (~> 0.74.0)
6
6
 
7
7
  GEM
data/README.md CHANGED
@@ -23,69 +23,71 @@ Or install it yourself as:
23
23
  ### Images
24
24
 
25
25
  ```ruby
26
+ # Connect to local image endpoints
27
+ image = Docker::API::Image.new
28
+
26
29
  # Pull from a public repository
27
- Docker::API::Image.create( fromImage: "nginx:latest" )
30
+ image.create( fromImage: "nginx:latest" )
28
31
 
29
32
  # Pull from a private repository
30
- Docker::API::Image.create( {fromImage: "private/repo:tag"}, {username: "janedoe", password: "password"} )
33
+ image.create( {fromImage: "private/repo:tag"}, {username: "janedoe", password: "password"} )
31
34
 
32
35
  # Create image from local tar file
33
- Docker::API::Image.create( fromSrc: "/path/to/file.tar", repo: "repo:tag" )
36
+ image.create( fromSrc: "/path/to/file.tar", repo: "repo:tag" )
34
37
 
35
38
  # Create image from remote tar file
36
- Docker::API::Image.create( fromSrc: "https://url.to/file.tar", repo: "repo:tag" )
39
+ image.create( fromSrc: "https://url.to/file.tar", repo: "repo:tag" )
37
40
 
38
41
  # List images
39
- Docker::API::Image.list
40
- Docker::API::Image.list( all:true )
42
+ image.list
41
43
 
42
44
  # Inspect image
43
- Docker::API::Image.inspect("image")
45
+ image.details("image")
44
46
 
45
47
  # History
46
- Docker::API::Image.history("image")
48
+ image.history("image")
47
49
 
48
50
  # Search image
49
- Docker::API::Image.search(term: "busybox", limit: 2)
50
- Docker::API::Image.search(term: "busybox", filters: {"is-automated": {"true": true}})
51
- Docker::API::Image.search(term: "busybox", filters: {"is-official": {"true": true}})
51
+ image.search(term: "busybox", limit: 2)
52
+ image.search(term: "busybox", filters: {"is-automated": {"true": true}})
53
+ image.search(term: "busybox", filters: {"is-official": {"true": true}})
52
54
 
53
55
  # Tag image
54
- Docker::API::Image.tag("current:tag", repo: "new:tag") # or
55
- Docker::API::Image.tag("current:tag", repo: "new", tag: "tag")
56
+ image.tag("current:tag", repo: "new:tag") # or
57
+ image.tag("current:tag", repo: "new", tag: "tag")
56
58
 
57
59
  # Push image
58
- Docker::API::Image.push("repo:tag") # to dockerhub
59
- Docker::API::Image.push("localhost:5000/repo:tag") # to local registry
60
- Docker::API::Image.push("private/repo", {tag: "tag"}, {username: "janedoe", password: "password"} # to private repository
60
+ image.push("repo:tag") # to dockerhub
61
+ image.push("localhost:5000/repo:tag") # to local registry
62
+ image.push("private/repo", {tag: "tag"}, {username: "janedoe", password: "password"} # to private repository
61
63
 
62
- # Remove container
63
- Docker::API::Image.remove("image")
64
- Docker::API::Image.remove("image", force: true)
64
+ # Remove image
65
+ image.remove("image")
66
+ image.remove("image", force: true)
65
67
 
66
68
  # Remove unsued images (prune)
67
- Docker::API::Image.prune(filters: {dangling: {"false": true}})
69
+ image.prune(filters: {dangling: {"false": true}})
68
70
 
69
71
  # Create image from a container (commit)
70
- Docker::API::Image.commit(container: container, repo: "my/image", tag: "latest", comment: "Comment from commit", author: "dockerapi", pause: false )
72
+ image.commit(container: container, repo: "my/image", tag: "latest", comment: "Comment from commit", author: "dockerapi", pause: false )
71
73
 
72
74
  # Build image from a local tar file
73
- Docker::API::Image.build("/path/to/file.tar")
75
+ image.build("/path/to/file.tar")
74
76
 
75
77
  # Build image from a remote tar file
76
- Docker::API::Image.build(nil, remote: "https://url.to/file.tar")
78
+ image.build(nil, remote: "https://url.to/file.tar")
77
79
 
78
80
  # Build image from a remote Dockerfile
79
- Docker::API::Image.build(nil, remote: "https://url.to/Dockerfile")
81
+ image.build(nil, remote: "https://url.to/Dockerfile")
80
82
 
81
83
  # Delete builder cache
82
- Docker::API::Image.delete_cache
84
+ image.delete_cache
83
85
 
84
86
  # Export repo
85
- Docker::API::Image.export("repo:tag", "~/exported_image.tar")
87
+ image.export("repo:tag", "~/exported_image.tar")
86
88
 
87
89
  # Import repo
88
- Docker::API::Image.import("/path/to/file.tar")
90
+ image.import("/path/to/file.tar")
89
91
  ```
90
92
 
91
93
  ### Containers
@@ -94,125 +96,227 @@ Let's test a Nginx container
94
96
 
95
97
  ```ruby
96
98
  # Pull nginx image
97
- Docker::API::Image.create( fromImage: "nginx:latest" )
99
+ Docker::API::Image.new.create( fromImage: "nginx:latest" )
100
+
101
+ # Connect to local container endpoints
102
+ container = Docker::API::Container.new
98
103
 
99
104
  # Create container
100
- Docker::API::Container.create( {name: "nginx"}, {Image: "nginx:latest", HostConfig: {PortBindings: {"80/tcp": [ {HostIp: "0.0.0.0", HostPort: "80"} ]}}})
105
+ container.create( {name: "nginx"}, {Image: "nginx:latest", HostConfig: {PortBindings: {"80/tcp": [ {HostIp: "0.0.0.0", HostPort: "80"} ]}}})
101
106
 
102
107
  # Start container
103
- Docker::API::Container.start("nginx")
108
+ container.start("nginx")
104
109
 
105
110
  # Open localhost or machine IP to check the container running
106
111
 
107
112
  # Restart container
108
- Docker::API::Container.restart("nginx")
113
+ container.restart("nginx")
109
114
 
110
115
  # Pause/unpause container
111
- Docker::API::Container.pause("nginx")
112
- Docker::API::Container.unpause("nginx")
116
+ container.pause("nginx")
117
+ container.unpause("nginx")
113
118
 
114
119
  # List containers
115
- Docker::API::Container::list
120
+ container.list
116
121
 
117
122
  # List containers (including stopped ones)
118
- Docker::API::Container::list(all: true)
123
+ container.list(all: true)
119
124
 
120
125
  # Inspect container
121
- Docker::API::Container.inspect("nginx")
126
+ container.details("nginx")
122
127
 
123
128
  # View container's processes
124
- Docker::API::Container.top("nginx")
129
+ container.top("nginx")
125
130
 
126
- # Let's enhance the output
127
- JSON.parse(Docker::API::Container.top("nginx").body)
131
+ # Using json output
132
+ container.top("nginx").json
128
133
 
129
134
  # View filesystem changes
130
- Docker::API::Container.changes("nginx")
135
+ container.changes("nginx")
131
136
 
132
137
  # View filesystem logs
133
- Docker::API::Container.logs("nginx", stdout: true)
134
- Docker::API::Container.logs("nginx", stdout: true, follow: true)
138
+ container.logs("nginx", stdout: true)
139
+ container.logs("nginx", stdout: true, follow: true)
135
140
 
136
141
  # View filesystem stats
137
- Docker::API::Container.stats("nginx", stream: true)
142
+ container.stats("nginx", stream: true)
138
143
 
139
144
  # Export container
140
- Docker::API::Container.export("nginx", "~/exported_container")
145
+ container.export("nginx", "~/exported_container")
141
146
 
142
147
  # Get files from container
143
- Docker::API::Container.archive("nginx", "~/html.tar", path: "/usr/share/nginx/html/")
148
+ container.archive("nginx", "~/html.tar", path: "/usr/share/nginx/html/")
144
149
 
145
150
  # Stop container
146
- Docker::API::Container.stop("nginx")
151
+ container.stop("nginx")
147
152
 
148
153
  # Remove container
149
- Docker::API::Container.remove("nginx")
154
+ container.remove("nginx")
150
155
 
151
156
  # Remove stopped containers (prune)
152
- Docker::API::Container.prune
157
+ container.prune
153
158
  ```
154
159
 
155
160
  ### Volumes
156
161
 
157
162
  ```ruby
163
+ # Connect to local volume endpoints
164
+ volume = Docker::API::Volume.new
165
+
158
166
  # Create volume
159
- Docker::API::Volume.create( Name:"my-volume" )
167
+ volume.create( Name:"my-volume" )
160
168
 
161
169
  # List volumes
162
- Docker::API::Volume.list
170
+ volume.list
163
171
 
164
172
  # Inspect volume
165
- Docker::API::Volume.inspect("my-volume")
173
+ volume.details("my-volume")
166
174
 
167
175
  # Remove volume
168
- Docker::API::Volume.remove("my-volume")
176
+ volume.remove("my-volume")
169
177
 
170
178
  # Remove unused volumes (prune)
171
- Docker::API::Volume.prune
179
+ volume.prune
172
180
  ```
173
181
 
174
182
  ### Network
175
183
 
176
184
  ```ruby
185
+ # Connect to local network endpoints
186
+ network = Docker::API::Network.new
187
+
177
188
  # List networks
178
- Docker::API::Network.list
189
+ network.list
179
190
 
180
191
  # Inspect network
181
- Docker::API::Network.inspect("bridge")
192
+ network.details("bridge")
182
193
 
183
194
  # Create network
184
- Docker::API::Network.create( Name:"my-network" )
195
+ network.create( Name:"my-network" )
185
196
 
186
197
  # Remove network
187
- Docker::API::Network.remove("my-network")
198
+ network.remove("my-network")
188
199
 
189
200
  # Remove unused network (prune)
190
- Docker::API::Network.prune
201
+ network.prune
191
202
 
192
203
  # Connect container to a network
193
- Docker::API::Network.connect( "my-network", Container: "my-container" )
204
+ network.connect( "my-network", Container: "my-container" )
194
205
 
195
206
  # Disconnect container to a network
196
- Docker::API::Network.disconnect( "my-network", Container: "my-container" )
207
+ network.disconnect( "my-network", Container: "my-container" )
197
208
  ```
198
209
 
199
210
  ### System
200
211
 
201
212
  ```ruby
213
+ # Connect to local system endpoints
214
+ sys = Docker::API::System.new
215
+
202
216
  # Ping docker api
203
- Docker::API::System.ping
217
+ sys.ping
204
218
 
205
219
  # Docker components versions
206
- Docker::API::System.version
220
+ sys.version
207
221
 
208
222
  # System info
209
- Docker::API::System.info
223
+ sys.info
210
224
 
211
225
  # System events (stream)
212
- Docker::API::System.events(until: Time.now.to_i)
226
+ sys.events(until: Time.now.to_i)
213
227
 
214
228
  # Data usage information
215
- Docker::API::System.df
229
+ sys.df
230
+ ```
231
+
232
+ ### Exec
233
+
234
+ ```ruby
235
+ # Connect to local exec endpoints
236
+ exe = Docker::API::Exec.new
237
+
238
+ # Create exec instance, get generated exec ID
239
+ response = exe.create(container, AttachStdout:true, Cmd: ["ls", "-l"])
240
+ id = response.json["Id"]
241
+
242
+ # Execute the command, stream from Stdout is stored in response data
243
+ response = exe.start(id)
244
+ print response.data[:stream]
245
+
246
+ # Inspect exec instance
247
+ exe.details(id)
248
+ ```
249
+
250
+ ### Swarm
251
+ ```ruby
252
+ # Connect to local swarm endpoints
253
+ swarm = Docker::API::Swarm.new
254
+
255
+ # Init swarm
256
+ swarm.init({AdvertiseAddr: "local-ip-address:2377", ListenAddr: "0.0.0.0:4567"})
257
+
258
+ # Inspect swarm
259
+ swarm.details
260
+
261
+ # Update swarm
262
+ swarm.update(version, {rotateWorkerToken: true})
263
+ swarm.update(version, {rotateManagerToken: true})
264
+ swarm.update(version, {rotateManagerUnlockKey: true})
265
+ swarm.update(version, {EncryptionConfig: { AutoLockManagers: true }})
266
+
267
+ # Get unlock key
268
+ swarm.unlock_key
269
+
270
+ # Unlock swarm
271
+ swarm.unlock(UnlockKey: "key-value")
272
+
273
+ # Join an existing swarm
274
+ swarm.join(RemoteAddrs: ["remote-manager-address:2377"], JoinToken: "Join-Token-Here")
275
+
276
+ # Leave a swarm
277
+ swarm.leave(force: true)
278
+ ```
279
+
280
+ ### Node
281
+ ```ruby
282
+ # Connect to local node endpoints
283
+ node = Docker::API::Node.new
284
+
285
+ # List nodes
286
+ node.list
287
+
288
+ # Inspect node
289
+ node.details("node-id")
290
+
291
+ # Update node (version, Role and Availability must be present)
292
+ node.update("node-id", {version: "version"}, {Role: "worker", Availability: "pause" })
293
+ node.update("node-id", {version: "version"}, {Role: "worker", Availability: "active" })
294
+ node.update("node-id", {version: "version"}, {Role: "manager", Availability: "active" })
295
+
296
+ # Delete node
297
+ node.delete("node-id")
298
+ ```
299
+
300
+ ### Connection
301
+
302
+ 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.
303
+
304
+ ```ruby
305
+ # Setting different connections
306
+ local = Docker::API::Connection.new('unix:///', socket: "/path/to/docker.sock")
307
+ remote = Docker::API::Connection.new("http://127.0.0.1:2375") # change the IP address accordingly
308
+
309
+ # Using default /var/run/docker.sock
310
+ image_default = Docker::API::Image.new
311
+ image_default.list
312
+
313
+ # Using custom socket path
314
+ image_custom = Docker::API::Image.new(local)
315
+ image_custom.list
316
+
317
+ # Using remote address
318
+ image_remote = Docker::API::Image.new(remote)
319
+ image_remote.list
216
320
  ```
217
321
 
218
322
  ### Requests
@@ -224,7 +328,7 @@ Requests should work as described in [Docker API documentation](https://docs.doc
224
328
  All requests return a response class that inherits from Excon::Response. Available attribute readers and methods include: `status`, `data`, `body`, `headers`, `json`, `path`, `success?`.
225
329
 
226
330
  ```ruby
227
- response = Docker::API::Image.create(fromImage: "busybox:latest")
331
+ response = Docker::API::Image.new.create(fromImage: "busybox:latest")
228
332
 
229
333
  response
230
334
  => #<Docker::API::Response:0x000055bb390b35c0 ... >
@@ -255,6 +359,8 @@ response.success?
255
359
 
256
360
  `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.
257
361
 
362
+ To completely skip the validation process, add `:skip_validation => true` in the hash to be validated.
363
+
258
364
  ## Development
259
365
 
260
366
  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.
@@ -263,28 +369,22 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
263
369
 
264
370
  ### Road to 1.0.0
265
371
 
266
- NS: Not Started
267
-
268
- WIP: Work In Progress
269
-
270
-
271
372
  | Class | Tests | Implementation | Refactoring |
272
373
  |---|---|---|---|
273
- | Container | Ok | Ok | NS |
274
- | Image | Ok | Ok | NS |
275
- | Volume | Ok | Ok | NS |
276
- | Network | Ok | Ok | NS |
277
- | System | Ok | Ok | NS |
278
- | Exec | NS | NS | NS |
279
- | Swarm | NS | NS | NS |
280
- | Node | NS | NS | NS |
281
- | Service | NS | NS | NS |
282
- | Task | NS | NS | NS |
283
- | Secret | NS | NS | NS |
284
-
285
- Misc:
286
- * ~~Improve response object~~
287
- * ~~Improve error objects~~
374
+ | Image | Ok | Ok | 8/7 |
375
+ | Container | Ok | Ok | 8/14 |
376
+ | Volume | Ok | Ok | 8/21 |
377
+ | Network | Ok | Ok | 8/21 |
378
+ | System | Ok | Ok | 8/21 |
379
+ | Exec | Ok | Ok | 8/21 |
380
+ | Swarm | Ok | Ok | 8/28 |
381
+ | Node | Ok | Ok | 8/28 |
382
+ | Service | 7/17 | 7/17 | 8/28 |
383
+ | Task | 7/17 | 7/17 | 9/4 |
384
+ | Secret | 7/17 | 7/17 | 9/4 |
385
+ | Config | 7/17 | 7/17 | 9/4 |
386
+ | Distribution | 7/17 | 7/17 | 9/4 |
387
+ | Plugin | 7/24 | 7/24 | 9/4 |
288
388
 
289
389
  ## Contributing
290
390