hyperkit 1.0.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.
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA1:
3
+ metadata.gz: 4c987dcdd24e8fd164c8c1aa0ba7d6424413afbf
4
+ data.tar.gz: f1cb3dccfbe526352a95b237e3f02e09371df577
5
+ SHA512:
6
+ metadata.gz: 21984f55160a78b75d64971d67ea3ff45d8d5017ff3f34c7b985a265c34961844f0717680fa0c7e3061a67328cbb3c68bc65219c15e2f73687b0328c0e38acd0
7
+ data.tar.gz: 37e780a30ca13a612637de881d91d8ea86ca83c8fb9e1f89faff770313458bbfee028c9c382dd6036241e7ea524ebec8641baa565f5380a347ed1b4bc1e59f70
@@ -0,0 +1,13 @@
1
+ /.bundle/
2
+ /.yardoc
3
+ /Gemfile.lock
4
+ /_yardoc/
5
+ /coverage/
6
+ /doc/
7
+ /pkg/
8
+ /spec/reports/
9
+ /tmp/
10
+ /.ruby-gemset
11
+ /.ruby-version
12
+ /.vagrant
13
+ .*.swp
data/.rspec ADDED
@@ -0,0 +1,2 @@
1
+ --format documentation
2
+ --color
@@ -0,0 +1,4 @@
1
+ language: ruby
2
+ rvm:
3
+ - 1.9.3
4
+ before_install: gem install bundler -v 1.11.2
@@ -0,0 +1 @@
1
+ --type-tag async:"Asynchronous"
@@ -0,0 +1,49 @@
1
+ # Contributor Code of Conduct
2
+
3
+ As contributors and maintainers of this project, and in the interest of
4
+ fostering an open and welcoming community, we pledge to respect all people who
5
+ contribute through reporting issues, posting feature requests, updating
6
+ documentation, submitting pull requests or patches, and other activities.
7
+
8
+ We are committed to making participation in this project a harassment-free
9
+ experience for everyone, regardless of level of experience, gender, gender
10
+ identity and expression, sexual orientation, disability, personal appearance,
11
+ body size, race, ethnicity, age, religion, or nationality.
12
+
13
+ Examples of unacceptable behavior by participants include:
14
+
15
+ * The use of sexualized language or imagery
16
+ * Personal attacks
17
+ * Trolling or insulting/derogatory comments
18
+ * Public or private harassment
19
+ * Publishing other's private information, such as physical or electronic
20
+ addresses, without explicit permission
21
+ * Other unethical or unprofessional conduct
22
+
23
+ Project maintainers have the right and responsibility to remove, edit, or
24
+ reject comments, commits, code, wiki edits, issues, and other contributions
25
+ that are not aligned to this Code of Conduct, or to ban temporarily or
26
+ permanently any contributor for other behaviors that they deem inappropriate,
27
+ threatening, offensive, or harmful.
28
+
29
+ By adopting this Code of Conduct, project maintainers commit themselves to
30
+ fairly and consistently applying these principles to every aspect of managing
31
+ this project. Project maintainers who do not follow or enforce the Code of
32
+ Conduct may be permanently removed from the project team.
33
+
34
+ This code of conduct applies both within project spaces and in public spaces
35
+ when an individual is representing the project or its community.
36
+
37
+ Instances of abusive, harassing, or otherwise unacceptable behavior may be
38
+ reported by contacting a project maintainer at TODO: Write your email address. All
39
+ complaints will be reviewed and investigated and will result in a response that
40
+ is deemed necessary and appropriate to the circumstances. Maintainers are
41
+ obligated to maintain confidentiality with regard to the reporter of an
42
+ incident.
43
+
44
+ This Code of Conduct is adapted from the [Contributor Covenant][homepage],
45
+ version 1.3.0, available at
46
+ [http://contributor-covenant.org/version/1/3/0/][version]
47
+
48
+ [homepage]: http://contributor-covenant.org
49
+ [version]: http://contributor-covenant.org/version/1/3/0/
data/Gemfile ADDED
@@ -0,0 +1,23 @@
1
+ source 'https://rubygems.org'
2
+
3
+ group :development do
4
+ gem 'awesome_print', :require => 'ap'
5
+ gem 'guard-rspec', '~> 4.6'
6
+ gem 'hirb-unicode'
7
+ gem 'pry'
8
+ gem 'yard'
9
+ gem 'rake'
10
+ end
11
+
12
+ group :test do
13
+ gem 'coveralls', :require => false
14
+ gem 'multi_json', '~> 1.11.0'
15
+ gem 'rb-fsevent', '~> 0.9'
16
+ gem 'rspec', '~> 3.0.0'
17
+ gem 'simplecov', :require => false
18
+ gem 'vcr', '~> 3.0'
19
+ gem 'webmock', '~> 1.24.2'
20
+ end
21
+
22
+ # Specify your gem's dependencies in hyperkit.gemspec
23
+ gemspec
@@ -0,0 +1,43 @@
1
+ # A sample Guardfile
2
+ # More info at https://github.com/guard/guard#readme
3
+
4
+ ## Uncomment and set this to only include directories you want to watch
5
+ # directories %w(app lib config test spec features) \
6
+ # .select{|d| Dir.exists?(d) ? d : UI.warning("Directory #{d} does not exist")}
7
+
8
+ ## Note: if you are using the `directories` clause above and you are not
9
+ ## watching the project directory ('.'), then you will want to move
10
+ ## the Guardfile to a watched dir and symlink it back, e.g.
11
+ #
12
+ # $ mkdir config
13
+ # $ mv Guardfile config/
14
+ # $ ln -s config/Guardfile .
15
+ #
16
+ # and, you'll have to watch "config/Guardfile" instead of "Guardfile"
17
+
18
+ # Note: The cmd option is now required due to the increasing number of ways
19
+ # rspec may be run, below are examples of the most common uses.
20
+ # * bundler: 'bundle exec rspec'
21
+ # * bundler binstubs: 'bin/rspec'
22
+ # * spring: 'bin/rspec' (This will use spring if running and you have
23
+ # installed the spring binstubs per the docs)
24
+ # * zeus: 'zeus rspec' (requires the server to be started separately)
25
+ # * 'just' rspec: 'rspec'
26
+
27
+ guard :rspec, cmd: "bundle exec rspec" do
28
+ require "guard/rspec/dsl"
29
+ dsl = Guard::RSpec::Dsl.new(self)
30
+
31
+ # Feel free to open issues for suggestions and improvements
32
+
33
+ # RSpec files
34
+ rspec = dsl.rspec
35
+ watch(rspec.spec_helper) { rspec.spec_dir }
36
+ watch(rspec.spec_support) { rspec.spec_dir }
37
+ watch(rspec.spec_files)
38
+
39
+ # Ruby files
40
+ ruby = dsl.ruby
41
+ dsl.watch_spec_files_for(ruby.lib_files)
42
+
43
+ end
@@ -0,0 +1,47 @@
1
+ ================================================================================
2
+ The MIT License (MIT)
3
+
4
+ Copyright (c) 2016, Western University
5
+
6
+ Permission is hereby granted, free of charge, to any person obtaining a copy
7
+ of this software and associated documentation files (the "Software"), to deal
8
+ in the Software without restriction, including without limitation the rights
9
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10
+ copies of the Software, and to permit persons to whom the Software is
11
+ furnished to do so, subject to the following conditions:
12
+
13
+ The above copyright notice and this permission notice shall be included in
14
+ all copies or substantial portions of the Software.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
22
+ THE SOFTWARE.
23
+
24
+ --------------------------------------------------------------------------
25
+ Portions of this software adapted or taken from Octokit.
26
+ The original license text is below:
27
+ --------------------------------------------------------------------------
28
+
29
+ Copyright (c) 2009-2016 Wynn Netherland, Adam Stacoviak, Erik Michaels-Ober
30
+
31
+ Permission is hereby granted, free of charge, to any person obtaining a
32
+ copy of this software and associated documentation files (the "Software"),
33
+ to deal in the Software without restriction, including without limitation
34
+ the rights to use, copy, modify, merge, publish, distribute, sublicense,
35
+ and/or sell copies of the Software, and to permit persons to whom the
36
+ Software is furnished to do so, subject to the following conditions:
37
+
38
+ The above copyright notice and this permission notice shall be included
39
+ in all copies or substantial portions of the Software.
40
+
41
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
42
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
43
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
44
+ THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
45
+ OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
46
+ ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
47
+ OTHER DEALINGS IN THE SOFTWARE.
@@ -0,0 +1,341 @@
1
+ # Hyperkit
2
+
3
+ Hyperkit is a flat API wrapper for LXD, the next-generation hypervisor. It is
4
+ shamelessly based on the design of Octokit, the popular wrapper for the GitHub
5
+ API.
6
+
7
+ ## Installation
8
+
9
+ Add this line to your application's Gemfile:
10
+
11
+ ```ruby
12
+ gem 'hyperkit'
13
+ ```
14
+
15
+ And then execute:
16
+
17
+ ```
18
+ $ bundle
19
+ ```
20
+
21
+ Or install it yourself as:
22
+
23
+ ```
24
+ $ gem install hyperkit
25
+ ```
26
+
27
+ ## Usage examples
28
+
29
+ ```ruby
30
+ require 'hyperkit'
31
+
32
+ lxd = Hyperkit::Client.new(api_endpoint: "https://lxd.example.com", verify_ssl: false)
33
+
34
+ # Create a new container and start it
35
+ lxd.create_container("test-container", alias: "ubuntu/trusty/amd64")
36
+ lxd.start_container("test-container")
37
+
38
+ # Execute a command in a container
39
+ lxd.execute_command("test-container", "bash -c 'echo hello > /tmp/test.txt'")
40
+
41
+ # Create an image from a container and assign an alias to it
42
+ response = lxd.create_image_from_container("test-container")
43
+ lxd.create_image_alias(response.metadata.fingerprint, "ubuntu/custom")
44
+
45
+ # Take a snapshot of a container (note that CRIU must be installed to snapshot
46
+ # a running container)
47
+ lxd.create_snapshot("test-container", "test-snapshot")
48
+
49
+ # Migrate a container (or a snapshot) from one server to another
50
+ # Note that CRIU must be installed on both LXD servers to migrate a running
51
+ # container.
52
+ lxd2 = Hyperkit::Client.new(api_endpoint: "https://lxd2.example.com")
53
+ source = lxd2.init_migration("remote-container")
54
+ lxd.migrate_container(source, "migrated-container")
55
+ ```
56
+
57
+ Each method in the API documentation has at least one example of its usage. Please see the documentation for the following modules:
58
+
59
+ * [Certificates]()
60
+ * [Containers]()
61
+ * [Images]()
62
+ * [Networks]()
63
+ * [Operations]()
64
+ * [Profiles]()
65
+
66
+ ## Requirements
67
+
68
+ Hyperkit supports **LXD 2.0.0 and above**, and **Ruby 2.0 and above**.
69
+
70
+ To get started, you'll need to first enable the HTTPS API on your LXD server:
71
+
72
+ ```
73
+ $ lxc config set core.https_address 127.0.0.1
74
+ ```
75
+
76
+ To listen on all interfaces, replace `127.0.0.1` with `0.0.0.0`.
77
+
78
+ ### Making requests
79
+
80
+ Being based on Octokit, [API methods][] are available as module methods
81
+ (consuming module-level configuration) or as client instance methods.
82
+
83
+ ```ruby
84
+ Hyperkit.configure do |c|
85
+ c.api_endpoint = 'https://lxd.example.com:8443'
86
+ c.verify_ssl = false
87
+ end
88
+
89
+ # Create an Ubuntu 14.04 container
90
+ Hyperkit.create_container("test-container", alias: "ubuntu/trusty/amd64")
91
+ ```
92
+ or
93
+
94
+ ```ruby
95
+ client = Octokit::Client.new(api_endpoint: 'https://lxd.example.com:8443', verify_ssl: false)
96
+
97
+ # Create an Ubuntu 14.04 container
98
+ client.create_container("test-container", alias: "ubuntu/trusty/amd64")
99
+ ```
100
+
101
+ [API methods]: http://TODO
102
+
103
+ ## Authentication
104
+
105
+ The LXD API uses client-side certificates to authenticate clients. By
106
+ default, Hyperkit uses the following files:
107
+
108
+ * Certificate: `ENV['HOME']/.config/lxc/client.crt`
109
+ * Private key: `ENV['HOME']/.config/lxc/client.key`
110
+
111
+ To specify alternate files:
112
+
113
+ ```
114
+ client = Hyperkit::Client.new(client_cert: '/path/to/crt/file', client_key: '/path/to/key/file')
115
+ ```
116
+
117
+ or, to configure all new instances of Hyperkit:
118
+
119
+ ```
120
+ Hyperkit.configure do |c|
121
+ c.client_cert = '/path/to/crt/file'
122
+ c.client_key = '/path/to/key/file'
123
+ end
124
+ ```
125
+
126
+ If you're running Hyperkit on your LXD host, the `lxc` tool should have
127
+ already generated your certificate and private key for you, and placed them in
128
+ `~/.config/lxc`.
129
+
130
+ If you are running Hyperkit on a different host, you'll need to generate a
131
+ certificate and private key. To do this, install OpenSSL and issue the
132
+ following commands:
133
+
134
+ ```
135
+ mkdir -p ~/.config/lxc
136
+ openssl req -x509 -newkey rsa:2048 -keyout ~/.config/lxc/client.key.secure -out ~/.config/lxc/client.crt -days 3650
137
+ openssl rsa -in ~/.config/lxc/client.key.secure -out ~/.config/lxc/client.key
138
+ ```
139
+
140
+ You will then need to tell LXD to trust your certificate. You can do this in
141
+ two ways:
142
+
143
+ ### Option 1: Trusting your certificate using a trust password
144
+
145
+ If you have configured your LXD server with a trust password, you can use
146
+ Hyperkit to get your certificate trusted:
147
+
148
+ ```ruby
149
+ require 'hyperkit'
150
+
151
+ Hyperkit.api_endpoint = 'https://lxd.example.com:8443'
152
+ Hyperkit.verify_ssl = false # Needed if you're using a self-signed certificate on the server
153
+
154
+ Hyperkit.create_certificate(File.read("/path/to/your/client.crt"), password: "server-trust-password")
155
+ ```
156
+
157
+ ### Option 2: Trusting your certificate using the `lxc` tool
158
+
159
+ Alternatively, you can simply copy your certificate file to the LXD server and
160
+ use the `lxc` tool to trust it:
161
+
162
+ ```
163
+ lxd-server$ lxc config trust add my-new-cert.crt
164
+ ```
165
+
166
+ ## API coverage
167
+
168
+ Hyperkit supports the entirety of [version 1.0 of the LXD
169
+ API](https://github.com/lxc/lxd/blob/master/specs/rest-api.md), but does not
170
+ support any of the Websocket API calls (e.g. `/1.0/events`).
171
+
172
+ ## Asynchronous Operations
173
+
174
+ A good deal of the LXD API calls are asynchronous: you issue the call, and you
175
+ receive an operation ID. You must then wait on the operation to complete.
176
+ Each asynchronous method is marked as such in the Hyperkit documentation.
177
+
178
+ **By default, Hyperkit provides auto-synchronization**. When you initiate an
179
+ asynchronous operation, Hyperkit will automatically wait for the operation to
180
+ complete before returning.
181
+
182
+ For example,
183
+
184
+ ```ruby
185
+ # By default, this will block until the container is created
186
+ Hyperkit.create_container("test-container", alias: "ubuntu/trusty/amd64")
187
+ ```
188
+
189
+ If you wish to override this functionality, there are two ways to do this.
190
+ First, you can pass `sync: false` to any of the asynchronous methods:
191
+
192
+ ```ruby
193
+ # Initiates the operation and immediately returns an operation ID
194
+ op = Hyperkit.create_container("test-container", alias: "ubuntu/trusty/amd64", sync: false)
195
+
196
+ # Blocks until the operation is complete
197
+ Hyperkit.wait_for_operation(op.id)
198
+ ```
199
+
200
+ Alternatively, you can disable auto-synchronization at the module or class
201
+ level:
202
+
203
+ ```ruby
204
+ Hyperkit.auto_sync = false
205
+
206
+ # or
207
+
208
+ client = Hyperkit::Client.new(auto_sync: false)
209
+ ```
210
+
211
+ Any asynchronous calls you issue after setting `auto_sync` to `false` will
212
+ immediately return an operation ID instead of blocking. To ensure that an
213
+ operation is complete, you will need to call `wait_for_operation`:
214
+
215
+ ```ruby
216
+ Hyperkit.auto_sync = false
217
+
218
+ op = Hyperkit.create_container("test-container", alias: "ubuntu/trusty/amd64")
219
+ Hyperkit.wait_for_operation(op.id)
220
+ ```
221
+
222
+ Note that, after an operation completes, LXD keeps it around for only 5
223
+ seconds, so if you wait too long to call `wait_for_operation`, you'll get an
224
+ exception when you eventually do call it.
225
+
226
+ Most users will likely want to keep `auto_sync` enabled for convenience.
227
+
228
+
229
+ ## Configuration and defaults
230
+
231
+ Hyperkit allows you to configure a new `Hyperkit::Client` instance by passing
232
+ options to its constructor.
233
+
234
+ As in Octokit, you also have the option of setting configuration at the module
235
+ level. If you need to create a number of client instances which will share
236
+ certain options, this ability will be useful.
237
+
238
+ When you change options at the module level, only new `Hyperkit::Client`
239
+ instances will be affected -- any existing instances that you have created
240
+ will retain their existing configuration.
241
+
242
+ ### Configuring module defaults
243
+
244
+ Every writable attribute in {Hyperkit::Configurable} can be set one at a time:
245
+
246
+ ```ruby
247
+ Hyperkit.api_endpoint = 'https://lxd.example.com:8443'
248
+ Hyperkit.verify_ssl = false
249
+ Hyperkit.client_cert = '/home/user/client.crt'
250
+ Hyperkit.client_key = '/home/user/client.key'
251
+ ```
252
+
253
+ or in batch:
254
+
255
+ ```ruby
256
+ Hyperkit.configure do |c|
257
+ c.api_endpoint = 'https://lxd.example.com:8443'
258
+ c.verify_ssl = false
259
+ c.client_cert = '/home/user/client.crt'
260
+ c.client_key = '/home/user/client.key'
261
+ end
262
+ ```
263
+
264
+ ### Using ENV variables
265
+
266
+ Default configuration values are specified in {Hyperkit::Default}. Many
267
+ attributes will look for a default value from the `ENV` before returning
268
+ Hyperkit's default.
269
+
270
+ ```ruby
271
+ # Given $HYPERKIT_API_ENDPOINT is "https://lxd.example.com:8443"
272
+ Hyperkit.api_endpoint
273
+
274
+ # => "https://lxd.example.com:8443"
275
+ ```
276
+
277
+
278
+ ## Supported Ruby Versions
279
+
280
+ This library aims to support and is [tested against][travis] the following
281
+ Ruby implementations:
282
+
283
+ * Ruby 2.0
284
+ * Ruby 2.1
285
+ * Ruby 2.2
286
+
287
+ If something doesn't work on one of these interpreters, it's a bug. This
288
+ library may inadvertently work (or seem to work) on other Ruby
289
+ implementations, however support will only be provided for the versions listed
290
+ above.
291
+
292
+ If you would like this library to support another Ruby version, you may
293
+ volunteer to be a maintainer. Being a maintainer entails making sure all tests
294
+ run and pass on that implementation. When something breaks on your
295
+ implementation, you will be responsible for providing patches in a timely
296
+ fashion. If critical issues for a particular implementation exist at the time
297
+ of a major release, support for that Ruby version may be dropped.
298
+
299
+ ## Versioning
300
+
301
+ This library aims to adhere to [Semantic Versioning 2.0.0][semver]. Violations
302
+ of this scheme should be reported as bugs. Specifically, if a minor or patch
303
+ version is released that breaks backward compatibility, that version should be
304
+ immediately yanked and/or a new version should be immediately released that
305
+ restores compatibility. Breaking changes to the public API will only be
306
+ introduced with new major versions. As a result of this policy, you can (and
307
+ should) specify a dependency on this gem using the [Pessimistic Version
308
+ Constraint][pvc] with two digits of precision. For example:
309
+
310
+ ```ruby
311
+ spec.add_dependency 'hyperkit', '~> 1.0'
312
+ ```
313
+ [semver]: http://semver.org/
314
+ [pvc]: http://docs.rubygems.org/read/chapter/16#page74
315
+
316
+ ## Development
317
+
318
+ After checking out the repo, run `bin/setup` to install dependencies. Then,
319
+ run `rake spec` to run the tests. You can also run `bin/console` for an
320
+ interactive prompt that will allow you to experiment.
321
+
322
+ To install this gem onto your local machine, run `bundle exec rake install`.
323
+ To release a new version, update the version number in `version.rb`, and then
324
+ run `bundle exec rake release`, which will create a git tag for the version,
325
+ push git commits and tags, and push the `.gem` file to
326
+ [rubygems.org](https://rubygems.org).
327
+
328
+ ## Contributing
329
+
330
+ Bug reports and pull requests are welcome on GitHub at
331
+ https://github.com/jeffshantz/hyperkit. This project is intended to be a safe,
332
+ welcoming space for collaboration, and contributors are expected to adhere to
333
+ the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
334
+
335
+ ## License
336
+
337
+ The gem is available as open source under the terms of the [MIT
338
+ License](http://opensource.org/licenses/MIT). Its design is based on Octokit,
339
+ also licensed under the MIT license. See the file `LICENSE.txt` for more
340
+ information.
341
+