dockerapi 0.5.0 → 0.9.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHANGELOG.md +65 -11
- data/Gemfile.lock +1 -1
- data/README.md +186 -86
- data/bin/setup +17 -3
- data/lib/docker/api/base.rb +12 -10
- data/lib/docker/api/connection.rb +4 -10
- data/lib/docker/api/container.rb +64 -53
- data/lib/docker/api/exec.rb +46 -0
- data/lib/docker/api/image.rb +51 -43
- data/lib/docker/api/network.rb +29 -18
- data/lib/docker/api/node.rb +38 -0
- data/lib/docker/api/swarm.rb +51 -0
- data/lib/docker/api/system.rb +14 -13
- data/lib/docker/api/version.rb +1 -1
- data/lib/docker/api/volume.rb +26 -14
- data/lib/dockerapi.rb +3 -0
- metadata +5 -2
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 2fa69dcb4c7b79c558bc6749b51def3a8a056e39259ad8163c84fec253193c67
|
4
|
+
data.tar.gz: '0998c5433ddcd3c4bbcc43ea6c21d61220527f7864c524e83bf0b3aedec501fd'
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: cafcf788d269546dd338daf50247df1ee1cf6af16372b50a2a6404b2323e0f8d6f78384789c245d122855d325e355dd9f822e4c61e5df4fb5bb9c7af79e11cac
|
7
|
+
data.tar.gz: b63d32250bfa09e067b56b19a2737ffc35e130511cd17dd31ffbb71db494406ff2b9e85e6e7226161e126b4d423a6fd570c3da6695dcb0d18407ce1c9a706190
|
data/CHANGELOG.md
CHANGED
@@ -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
|
data/Gemfile.lock
CHANGED
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
|
-
|
30
|
+
image.create( fromImage: "nginx:latest" )
|
28
31
|
|
29
32
|
# Pull from a private repository
|
30
|
-
|
33
|
+
image.create( {fromImage: "private/repo:tag"}, {username: "janedoe", password: "password"} )
|
31
34
|
|
32
35
|
# Create image from local tar file
|
33
|
-
|
36
|
+
image.create( fromSrc: "/path/to/file.tar", repo: "repo:tag" )
|
34
37
|
|
35
38
|
# Create image from remote tar file
|
36
|
-
|
39
|
+
image.create( fromSrc: "https://url.to/file.tar", repo: "repo:tag" )
|
37
40
|
|
38
41
|
# List images
|
39
|
-
|
40
|
-
Docker::API::Image.list( all:true )
|
42
|
+
image.list
|
41
43
|
|
42
44
|
# Inspect image
|
43
|
-
|
45
|
+
image.details("image")
|
44
46
|
|
45
47
|
# History
|
46
|
-
|
48
|
+
image.history("image")
|
47
49
|
|
48
50
|
# Search image
|
49
|
-
|
50
|
-
|
51
|
-
|
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
|
-
|
55
|
-
|
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
|
-
|
59
|
-
|
60
|
-
|
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
|
63
|
-
|
64
|
-
|
64
|
+
# Remove image
|
65
|
+
image.remove("image")
|
66
|
+
image.remove("image", force: true)
|
65
67
|
|
66
68
|
# Remove unsued images (prune)
|
67
|
-
|
69
|
+
image.prune(filters: {dangling: {"false": true}})
|
68
70
|
|
69
71
|
# Create image from a container (commit)
|
70
|
-
|
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
|
-
|
75
|
+
image.build("/path/to/file.tar")
|
74
76
|
|
75
77
|
# Build image from a remote tar file
|
76
|
-
|
78
|
+
image.build(nil, remote: "https://url.to/file.tar")
|
77
79
|
|
78
80
|
# Build image from a remote Dockerfile
|
79
|
-
|
81
|
+
image.build(nil, remote: "https://url.to/Dockerfile")
|
80
82
|
|
81
83
|
# Delete builder cache
|
82
|
-
|
84
|
+
image.delete_cache
|
83
85
|
|
84
86
|
# Export repo
|
85
|
-
|
87
|
+
image.export("repo:tag", "~/exported_image.tar")
|
86
88
|
|
87
89
|
# Import repo
|
88
|
-
|
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
|
-
|
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
|
-
|
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
|
-
|
113
|
+
container.restart("nginx")
|
109
114
|
|
110
115
|
# Pause/unpause container
|
111
|
-
|
112
|
-
|
116
|
+
container.pause("nginx")
|
117
|
+
container.unpause("nginx")
|
113
118
|
|
114
119
|
# List containers
|
115
|
-
|
120
|
+
container.list
|
116
121
|
|
117
122
|
# List containers (including stopped ones)
|
118
|
-
|
123
|
+
container.list(all: true)
|
119
124
|
|
120
125
|
# Inspect container
|
121
|
-
|
126
|
+
container.details("nginx")
|
122
127
|
|
123
128
|
# View container's processes
|
124
|
-
|
129
|
+
container.top("nginx")
|
125
130
|
|
126
|
-
#
|
127
|
-
|
131
|
+
# Using json output
|
132
|
+
container.top("nginx").json
|
128
133
|
|
129
134
|
# View filesystem changes
|
130
|
-
|
135
|
+
container.changes("nginx")
|
131
136
|
|
132
137
|
# View filesystem logs
|
133
|
-
|
134
|
-
|
138
|
+
container.logs("nginx", stdout: true)
|
139
|
+
container.logs("nginx", stdout: true, follow: true)
|
135
140
|
|
136
141
|
# View filesystem stats
|
137
|
-
|
142
|
+
container.stats("nginx", stream: true)
|
138
143
|
|
139
144
|
# Export container
|
140
|
-
|
145
|
+
container.export("nginx", "~/exported_container")
|
141
146
|
|
142
147
|
# Get files from container
|
143
|
-
|
148
|
+
container.archive("nginx", "~/html.tar", path: "/usr/share/nginx/html/")
|
144
149
|
|
145
150
|
# Stop container
|
146
|
-
|
151
|
+
container.stop("nginx")
|
147
152
|
|
148
153
|
# Remove container
|
149
|
-
|
154
|
+
container.remove("nginx")
|
150
155
|
|
151
156
|
# Remove stopped containers (prune)
|
152
|
-
|
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
|
-
|
167
|
+
volume.create( Name:"my-volume" )
|
160
168
|
|
161
169
|
# List volumes
|
162
|
-
|
170
|
+
volume.list
|
163
171
|
|
164
172
|
# Inspect volume
|
165
|
-
|
173
|
+
volume.details("my-volume")
|
166
174
|
|
167
175
|
# Remove volume
|
168
|
-
|
176
|
+
volume.remove("my-volume")
|
169
177
|
|
170
178
|
# Remove unused volumes (prune)
|
171
|
-
|
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
|
-
|
189
|
+
network.list
|
179
190
|
|
180
191
|
# Inspect network
|
181
|
-
|
192
|
+
network.details("bridge")
|
182
193
|
|
183
194
|
# Create network
|
184
|
-
|
195
|
+
network.create( Name:"my-network" )
|
185
196
|
|
186
197
|
# Remove network
|
187
|
-
|
198
|
+
network.remove("my-network")
|
188
199
|
|
189
200
|
# Remove unused network (prune)
|
190
|
-
|
201
|
+
network.prune
|
191
202
|
|
192
203
|
# Connect container to a network
|
193
|
-
|
204
|
+
network.connect( "my-network", Container: "my-container" )
|
194
205
|
|
195
206
|
# Disconnect container to a network
|
196
|
-
|
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
|
-
|
217
|
+
sys.ping
|
204
218
|
|
205
219
|
# Docker components versions
|
206
|
-
|
220
|
+
sys.version
|
207
221
|
|
208
222
|
# System info
|
209
|
-
|
223
|
+
sys.info
|
210
224
|
|
211
225
|
# System events (stream)
|
212
|
-
|
226
|
+
sys.events(until: Time.now.to_i)
|
213
227
|
|
214
228
|
# Data usage information
|
215
|
-
|
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
|
-
|
|
274
|
-
|
|
275
|
-
| Volume | Ok | Ok |
|
276
|
-
| Network | Ok | Ok |
|
277
|
-
| System | Ok | Ok |
|
278
|
-
| Exec |
|
279
|
-
| Swarm |
|
280
|
-
| Node |
|
281
|
-
| Service |
|
282
|
-
| Task |
|
283
|
-
| Secret |
|
284
|
-
|
285
|
-
|
286
|
-
|
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
|
|