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