nugrant 2.1.2 → 2.1.4
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 +5 -5
- data/.gitignore +23 -23
- data/.travis.yml +15 -10
- data/CHANGELOG.md +347 -338
- data/CONTRIBUTORS.md +7 -5
- data/Gemfile +13 -13
- data/README.md +601 -601
- data/lib/nugrant/bag.rb +264 -264
- data/lib/nugrant/config.rb +201 -201
- data/lib/nugrant/helper/bag.rb +38 -38
- data/lib/nugrant/helper/env/exporter.rb +195 -195
- data/lib/nugrant/helper/env/namer.rb +47 -47
- data/lib/nugrant/helper/parameters.rb +12 -12
- data/lib/nugrant/helper/stack.rb +86 -86
- data/lib/nugrant/mixin/parameters.rb +178 -178
- data/lib/nugrant/parameters.rb +29 -29
- data/lib/nugrant/vagrant/errors.rb +35 -35
- data/lib/nugrant/vagrant/v2/action/auto_export.rb +45 -45
- data/lib/nugrant/vagrant/v2/action.rb +17 -17
- data/lib/nugrant/vagrant/v2/command/env.rb +118 -118
- data/lib/nugrant/vagrant/v2/command/parameters.rb +153 -153
- data/lib/nugrant/vagrant/v2/command/restricted_keys.rb +64 -64
- data/lib/nugrant/vagrant/v2/command/root.rb +95 -95
- data/lib/nugrant/vagrant/v2/config/user.rb +29 -29
- data/lib/nugrant/vagrant/v2/helper.rb +96 -96
- data/lib/nugrant/vagrant/v2/plugin.rb +34 -34
- data/lib/nugrant/version.rb +3 -3
- data/lib/nugrant.rb +31 -31
- data/locales/en.yml +24 -24
- data/locales/fr.yml +24 -24
- data/nugrant.gemspec +32 -32
- data/test/lib/nugrant/helper/env/test_exporter.rb +238 -238
- data/test/lib/nugrant/helper/test_bag.rb +16 -16
- data/test/lib/nugrant/helper/test_parameters.rb +17 -17
- data/test/lib/nugrant/helper/test_stack.rb +152 -152
- data/test/lib/nugrant/test_bag.rb +450 -450
- data/test/lib/nugrant/test_config.rb +201 -201
- data/test/lib/nugrant/test_parameters.rb +438 -438
- data/test/lib/test_helper.rb +3 -3
- data/test/resources/README.md +52 -52
- data/test/resources/json/params_current_1.json +6 -6
- data/test/resources/json/params_current_2.json +29 -29
- data/test/resources/json/params_user_nil_values.json +9 -9
- data/test/resources/vagrantfiles/v2.auto_export +13 -13
- data/test/resources/vagrantfiles/v2.bag_inside_array +15 -15
- data/test/resources/vagrantfiles/v2.defaults_mixed_string_symbols +18 -18
- data/test/resources/vagrantfiles/v2.defaults_null_values_in_vagrantuser +23 -23
- data/test/resources/vagrantfiles/v2.defaults_using_string +18 -18
- data/test/resources/vagrantfiles/v2.defaults_using_symbol +18 -18
- data/test/resources/vagrantfiles/v2.empty +2 -2
- data/test/resources/vagrantfiles/v2.fake +29 -29
- data/test/resources/vagrantfiles/v2.missing_parameter +3 -3
- data/test/resources/vagrantfiles/v2.real +22 -22
- data/test/resources/yaml/params_array.yml +5 -5
- data/test/resources/yaml/params_boolean.yml +1 -1
- data/test/resources/yaml/params_combinations.yml +72 -72
- data/test/resources/yaml/params_current_1.yml +4 -4
- data/test/resources/yaml/params_current_2.yml +23 -23
- data/test/resources/yaml/params_defaults_at_root.yml +1 -1
- data/test/resources/yaml/params_defaults_not_at_root.yml +2 -2
- data/test/resources/yaml/params_list.yml +2 -2
- data/test/resources/yaml/params_numeric_key.yml +3 -3
- data/test/resources/yaml/params_simple.yml +1 -1
- data/test/resources/yaml/params_system_1.yml +4 -4
- data/test/resources/yaml/params_system_2.yml +25 -25
- data/test/resources/yaml/params_unix_eol.yml +3 -3
- data/test/resources/yaml/params_user_1.yml +4 -4
- data/test/resources/yaml/params_user_2.yml +23 -23
- data/test/resources/yaml/params_user_nil_values.yml +5 -5
- data/test/resources/yaml/params_windows_eol.yml +3 -3
- metadata +12 -13
data/README.md
CHANGED
@@ -1,601 +1,601 @@
|
|
1
|
-
# Nugrant
|
2
|
-
|
3
|
-
[][gem]
|
4
|
-
[][travis]
|
5
|
-
[][gemnasium]
|
6
|
-
[][codeclimate]
|
7
|
-
|
8
|
-
[gem]: https://rubygems.org/gems/nugrant
|
9
|
-
[travis]: http://travis-ci.org/maoueh/nugrant
|
10
|
-
[gemnasium]: https://gemnasium.com/maoueh/nugrant
|
11
|
-
[codeclimate]: https://codeclimate.com/github/maoueh/nugrant
|
12
|
-
|
13
|
-
Nugrant is a library to easily handle parameters that need to be
|
14
|
-
injected into an application via different sources (system, user,
|
15
|
-
current, defaults). But foremost, a Vagrant plug-in that will enhance
|
16
|
-
Vagrantfile to allow user specific configuration values.
|
17
|
-
|
18
|
-
Supported platforms:
|
19
|
-
|
20
|
-
* Vagrant 1.x
|
21
|
-
* Ruby 1.9.3+
|
22
|
-
|
23
|
-
## Quick Start
|
24
|
-
|
25
|
-
Using Nugrant as a plug-in provides an easy and hierarchical system to manage
|
26
|
-
machine and user specific parameters.
|
27
|
-
|
28
|
-
Let's start with an example. You need to distribute among your enterprise a
|
29
|
-
`Vagrantfile` to start and provision an AWS EC2 instance (or for an open-source project).
|
30
|
-
The `aws_access_key` and `aws_secret_key` should be configurable depending on the user
|
31
|
-
running `vagrant up`.
|
32
|
-
|
33
|
-
To achieve this, simply create a file named `.vagrantuser` that resides in the directory
|
34
|
-
as your `Vagrantfile`:
|
35
|
-
|
36
|
-
aws:
|
37
|
-
access_key: "123456"
|
38
|
-
secret_key: "abcdef"
|
39
|
-
|
40
|
-
In your `Vagrantfile`, `Nugrant` will let you access the parameters via the
|
41
|
-
`config.user` object:
|
42
|
-
|
43
|
-
Vagrant.configure("2") do |config|
|
44
|
-
...
|
45
|
-
|
46
|
-
config.vm.provider :aws do |aws, override|
|
47
|
-
aws.access_key_id = config.user.aws.access_key
|
48
|
-
aws.secret_access_key = config.user.aws.secret_key
|
49
|
-
|
50
|
-
...
|
51
|
-
end
|
52
|
-
end
|
53
|
-
|
54
|
-
You then ignore the `.vagrantuser` file in your revision control, so each developer
|
55
|
-
as a specific one with their own values. People often commit a `.vagrantuser.example`
|
56
|
-
file in project's repository as an easy startup for the various parameters that
|
57
|
-
must be filled in, something like:
|
58
|
-
|
59
|
-
aws:
|
60
|
-
access_key: "<ACCESS_KEY_HERE>"
|
61
|
-
secret_key: "<SECRET_KEY_HERE>"
|
62
|
-
|
63
|
-
To find where your project `.vagrantuser` is located, Nugrant uses the directory
|
64
|
-
where the `Vagrantfile` is located. It achieves this using the same set of
|
65
|
-
rules as Vagrant meaning you can be in a nested directory and parameters
|
66
|
-
will still be fetched correctly.
|
67
|
-
|
68
|
-
Moreover, like other similar system, there is a hierarchy of `.vagrantuser` files
|
69
|
-
that you can leverage:
|
70
|
-
|
71
|
-
| Name | Location | Priority | Overrides |
|
72
|
-
| ---------|-----------------------------------------|:---------:|--------------------------|
|
73
|
-
| Defaults | [config.user.defaults](#default-values) | 4 | - |
|
74
|
-
| System | $SYSTEM/.vagrantuser | 3 | Defaults |
|
75
|
-
| User | ~/.vagrantuser | 2 | Defaults & System |
|
76
|
-
| Project | .vagrantuser | 1 | Defaults & System & User |
|
77
|
-
|
78
|
-
The project level directory is always the same as the directory where your
|
79
|
-
`Vagrantfile` resides and same rules as Vagrant are used to find it.
|
80
|
-
The `~` is the user's home directory and `$SYSTEM` is the platform dependent
|
81
|
-
folder where system global can be put. Check [Hierarchy](#hierarchy) section
|
82
|
-
for where `$SYSTEM` maps exactly.
|
83
|
-
|
84
|
-
You can use the command `vagrant user parameters` to see the final merged
|
85
|
-
hierarchy seen by Nugrant. This command also prints [restricted keys](#restricted-keys)
|
86
|
-
defined in your hierarchy.
|
87
|
-
|
88
|
-
Accessing parameters in your `Vagrantfile` can be done either by method access
|
89
|
-
(i.e. `config.user.<key>`) or by array access (i.e. `config.user[<key>]`).
|
90
|
-
This support is working for any deepness, only `config.user` is different
|
91
|
-
because provided directly by `Vagrant` and not by this plugin.
|
92
|
-
|
93
|
-
However, a drawback with method access, not present with array access, is its
|
94
|
-
set of [restricted keys](#restricted-keys) for which usage is prohibited. These
|
95
|
-
are in facts calls to method defined by the [Bag](lib/nugrant/bag.rb) class
|
96
|
-
([Bag](lib/nugrant/bag.rb) extends [Hash](http://ruby-doc.org/core-2.0/Hash.html)).
|
97
|
-
It's plain Ruby, use it at your advantage like iterating through a collection
|
98
|
-
using the `.each` method.
|
99
|
-
|
100
|
-
This is where the quick start end. Continue to section [Installation](#installation)
|
101
|
-
if you need so help on how to install Nugrant. Or jump to [Usage](#usage) section
|
102
|
-
which describe in greater details all necessary information needed to deeply
|
103
|
-
understand Nugrant and use it at its full potential.
|
104
|
-
|
105
|
-
## Installation
|
106
|
-
|
107
|
-
### Vagrant
|
108
|
-
|
109
|
-
Vagrant's plug-in system is very well done and Nugrant supports
|
110
|
-
the following plug-in API versions:
|
111
|
-
|
112
|
-
* V2 => Vagrant 1.x
|
113
|
-
|
114
|
-
To install the Nugrant as a Vagrant plug-in, simply type the following
|
115
|
-
command in a terminal:
|
116
|
-
|
117
|
-
vagrant plugin install nugrant
|
118
|
-
|
119
|
-
#### Vagrant 0.x
|
120
|
-
|
121
|
-
Vagrant 0.x is not supported anymore. If you still need support for
|
122
|
-
Vagrant 0.x, please use release line `1.x` (branch [1.x](https://github.com/maoueh/nugrant/tree/1.x)).
|
123
|
-
|
124
|
-
### Library
|
125
|
-
|
126
|
-
If you would like to use Nugrant as a library, simply reference
|
127
|
-
it as a dependency of your application. Probably by adding it to
|
128
|
-
your `Gemfile` or your `.gemspec` file.
|
129
|
-
|
130
|
-
"nugrant", "~> 2.0"
|
131
|
-
|
132
|
-
## Usage
|
133
|
-
|
134
|
-
Whether used as a library or a Vagrant plug-in, Nugrant has some
|
135
|
-
common concepts that apply to both usages. The most important
|
136
|
-
one is the parameters hierarchy.
|
137
|
-
|
138
|
-
### Common
|
139
|
-
|
140
|
-
Nugrant can read parameters from various locations and will merge
|
141
|
-
them all together in a single set. Merging is done in a fairly
|
142
|
-
standard fashion.
|
143
|
-
|
144
|
-
Here the precedence rules that apply when merging parameters
|
145
|
-
from various location. List index indicate the priority of the
|
146
|
-
entry. Entry with lower number has lower priority (values at this
|
147
|
-
priority will be overridden by values defined on higher priorities).
|
148
|
-
|
149
|
-
1. Defaults
|
150
|
-
2. System
|
151
|
-
3. User
|
152
|
-
4. Current
|
153
|
-
|
154
|
-
In text, this means that current parameters overrides user
|
155
|
-
parameters, user parameters overrides system parameters and
|
156
|
-
finally system parameters overrides defaults parameters.
|
157
|
-
|
158
|
-
When two keys that are merged together points to Array values,
|
159
|
-
the default operation is to replace current Array by
|
160
|
-
overriding one. The default merge strategy can be customized.
|
161
|
-
|
162
|
-
### Vagrant
|
163
|
-
|
164
|
-
All examples shown here are for Vagrant 1.1+. They have
|
165
|
-
been tested with Vagrant 1.4.0. Keep this in mind when
|
166
|
-
copying examples.
|
167
|
-
|
168
|
-
Let start with a small use case. Say the git repository you want
|
169
|
-
to share with your guest VM is not located under the root folder of
|
170
|
-
your `Vagrantfile`. That means you will need to specify
|
171
|
-
an absolute host path to share the folder on the guest VM.
|
172
|
-
|
173
|
-
Your `Vagrantfile` would look like this:
|
174
|
-
|
175
|
-
Vagrant.configure("2") do |config|
|
176
|
-
config.vm.box = "base"
|
177
|
-
config.vm.synced_folder "/home/user/work/git", "/git"
|
178
|
-
end
|
179
|
-
|
180
|
-
However, what happens when multiple developers
|
181
|
-
need to share the same `Vagrantfile`? This is the main
|
182
|
-
use case this plug-in try to address.
|
183
|
-
|
184
|
-
When Vagrant starts, it loads all vagrant plug-ins it knows
|
185
|
-
about. If you installed the plug-in with one of the two
|
186
|
-
methods we listed above, Vagrant will know about Nugrant
|
187
|
-
and will load it correctly.
|
188
|
-
|
189
|
-
To use the plug-in, first create a YAML file named
|
190
|
-
`.vagrantuser` in the same folder where your `Vagrantfile` is
|
191
|
-
located. The file must be a valid YAML file:
|
192
|
-
|
193
|
-
repository:
|
194
|
-
project: "/home/user/work/git"
|
195
|
-
|
196
|
-
The configuration hierarchy you define in the `.vagrantuser` file
|
197
|
-
is imported into the `config` object of the `Vagrantfile`
|
198
|
-
under the key `user`. So, with the `.vagrantuser` file above, you
|
199
|
-
could have this `Vagrantfile` that abstract absolute paths.
|
200
|
-
|
201
|
-
Vagrant.configure("2") do |config|
|
202
|
-
config.vm.box = "base"
|
203
|
-
config.vm.synced_folder config.user.repository.project, "/git"
|
204
|
-
end
|
205
|
-
|
206
|
-
This way, paths can be customized by every developer. They just
|
207
|
-
have to add a `.vagrantuser` file where user specific configuration
|
208
|
-
values can be specified. The `.vagrantuser` should be ignored by you
|
209
|
-
version control system so it is to committed with the project.
|
210
|
-
|
211
|
-
Additionally, you can also have a `.vagrantuser` under your user home
|
212
|
-
directory. This way, you can set parameters that will be
|
213
|
-
available to all your `Vagrantfile
|
214
|
-
within the same folder as the `Vagrantfile` file will overrides
|
215
|
-
parameters defined in the `.vagrantuser` file defined in the user
|
216
|
-
home directory.
|
217
|
-
|
218
|
-
For example, you have `.vagrantuser` file located at `~/.vagrantuser`
|
219
|
-
that has the following content:
|
220
|
-
|
221
|
-
ssh_port: 2223
|
222
|
-
repository:
|
223
|
-
project: "/home/user/work/git"
|
224
|
-
|
225
|
-
And another `.vagrantuser` within the same folder as your `Vagrantfile`:
|
226
|
-
|
227
|
-
ssh_port: 3332
|
228
|
-
repository:
|
229
|
-
personal: "/home/user/personal/git"
|
230
|
-
|
231
|
-
Then, the `Vagrantfile` could be defined like this:
|
232
|
-
|
233
|
-
Vagrant.configure("2") do |config|
|
234
|
-
config.ssh.port config.user.ssh_port
|
235
|
-
|
236
|
-
config.vm.synced_folder config.user.repository.project, "/git"
|
237
|
-
config.vm.synced_folder config.user.repository.personal, "/personal"
|
238
|
-
end
|
239
|
-
|
240
|
-
That would be equivalent to:
|
241
|
-
|
242
|
-
Vagrant.configure("2") do |config|
|
243
|
-
config.ssh.port 3332
|
244
|
-
|
245
|
-
config.vm.synced_folder "/home/user/work/git", "/git"
|
246
|
-
config.vm.synced_folder "/home/user/personal/git", "/personal"
|
247
|
-
end
|
248
|
-
|
249
|
-
#### Hierarchy
|
250
|
-
|
251
|
-
As you can see, the parameters defined in the second `.vagrantuser` file
|
252
|
-
(the current one) overrides settings defined in the `.vagrantuser` found
|
253
|
-
in the home directory (the user one).
|
254
|
-
|
255
|
-
Here the list of locations where Nugrant looks for parameters:
|
256
|
-
|
257
|
-
1. Defaults (via `config.user.defaults` in `Vagrantfile`)
|
258
|
-
2. System (`/etc/.vagrantuser` on Unix, `%PROGRAMDATA%/.vagrantuser` or `%ALLUSERSPROFILE%/.vagrantuser` on Windows)
|
259
|
-
3. Home (`~/.vagrantuser`)
|
260
|
-
4. Project (`.vagrantuser` within the same folder as the `Vagrantfile`)
|
261
|
-
|
262
|
-
#### Paths
|
263
|
-
|
264
|
-
When you want to specify paths on, specially on Windows, it's probably
|
265
|
-
better to only use forward slash (`/`). The main reason for this is because
|
266
|
-
Ruby, which will be used at the end by Vagrant is able to deal with forward
|
267
|
-
slash even on Windows. This is great because with this, you can avoid
|
268
|
-
values escaping in YAML file. If you need to use backward slash (`\`), don't
|
269
|
-
forget to properly escape it!
|
270
|
-
|
271
|
-
value: "C:/Users/user/work/git"
|
272
|
-
value: "C:\\Users\\user\\work\\git"
|
273
|
-
|
274
|
-
Moreover, it is preferable that paths are specified in full
|
275
|
-
(i.e. no `~` for HOME directory for example). Normally, they
|
276
|
-
should be handled by `Vagrant` but it may happen that it's not
|
277
|
-
the case. If your have an error with a specific parameter,
|
278
|
-
either expand it in your config:
|
279
|
-
|
280
|
-
project: "/home/joe/work/ruby/git"
|
281
|
-
|
282
|
-
Of expand it in the `Vagrantfile`:
|
283
|
-
|
284
|
-
config.vm.synced_folder File.expand_path(config.user.repository.project), "/git"
|
285
|
-
|
286
|
-
#### Parameters access
|
287
|
-
|
288
|
-
Parameters in the `Vagrantfile` can be retrieved via method call
|
289
|
-
of array access.
|
290
|
-
|
291
|
-
config.user['repository']['project'] # Array access
|
292
|
-
config.user.repository.project # Method access
|
293
|
-
|
294
|
-
You can even mix the two if you want, but we do not recommend
|
295
|
-
it since its always better to be consistent:
|
296
|
-
|
297
|
-
config.user['repository'].project # Mixed access
|
298
|
-
config.user.repository['project'] # Mixed access
|
299
|
-
|
300
|
-
Only the root key, i.e. `config.user`, cannot be access with
|
301
|
-
both syntax, only the method syntax can be used since this
|
302
|
-
is not provided by this plug-in but by Vagrant itself.
|
303
|
-
|
304
|
-
##### Tips
|
305
|
-
|
306
|
-
Each non-final parameter (i.e a parameter that contains other parameters and
|
307
|
-
not a scalar value) is in fact a [Bag](/lib/nugrant/bag.rb)
|
308
|
-
object. You can call any defined methods on it. This object extends
|
309
|
-
[Hash](http://ruby-doc.org/core-2.0/Hash.html) (itself including
|
310
|
-
module [Enumerable](http://ruby-doc.org/core-2.0/Enumerable.html)). Hence,
|
311
|
-
you can do neat things like iterating over your values or filtering them:
|
312
|
-
|
313
|
-
config.user.application.users.each do |key, data|
|
314
|
-
puts "Key #{key}: #{data}"
|
315
|
-
end
|
316
|
-
|
317
|
-
##### Restricted keys
|
318
|
-
|
319
|
-
Method access has the neat advantage of being beautiful to the
|
320
|
-
eye. However, the drawback of using this retrieval syntax is
|
321
|
-
that not all keys are permitted. As explained in the [Tips](#tips)
|
322
|
-
section, the object you are calling when using method access
|
323
|
-
is in fact of type [Bag](/lib/nugrant/bag.rb). Hence, if you
|
324
|
-
are using a key which collapse with ones of Bag's keys, it will
|
325
|
-
call the method instead of given you the value of you parameter.
|
326
|
-
At best, you will get a weird behavior and at worst a stack
|
327
|
-
trace when trying to access the parameter.
|
328
|
-
|
329
|
-
If you really want to use one of the restricted keys, simply
|
330
|
-
ensure to always use array access method.
|
331
|
-
|
332
|
-
The list of restricted keys can be accessed using command
|
333
|
-
`vagrant user restricted-keys`.
|
334
|
-
|
335
|
-
#### Default values
|
336
|
-
|
337
|
-
When using parameters, it is often needed so set default values
|
338
|
-
for certain parameters so if the user does not define one, the
|
339
|
-
default value will be picked up.
|
340
|
-
|
341
|
-
For example, say you want a parameter that will hold the ssh
|
342
|
-
port of the vm. This parameter will be accessible via the
|
343
|
-
parameter `config.user.vm.ssh_port`.
|
344
|
-
|
345
|
-
You can use the following snippet directly within your Vagrantfile
|
346
|
-
to set a default value for this parameter:
|
347
|
-
|
348
|
-
Vagrant.configure("2") do |config|
|
349
|
-
config.user.defaults = {
|
350
|
-
"vm" => {
|
351
|
-
"ssh_port" => "3335"
|
352
|
-
}
|
353
|
-
}
|
354
|
-
|
355
|
-
config.ssh.port config.user.vm.ssh_port
|
356
|
-
end
|
357
|
-
|
358
|
-
With this Vagrantfile, the parameter `config.user.vm.ssh_port`
|
359
|
-
will default to `3335` in cases where it is not defined by the
|
360
|
-
user.
|
361
|
-
|
362
|
-
If the user decides to change it, he just has to set it in his
|
363
|
-
own `.vagrantuser` and it will override the default value defined
|
364
|
-
in the Vagrantfile.
|
365
|
-
|
366
|
-
#### Array merge strategies
|
367
|
-
|
368
|
-
As stated previously, when two arrays are merged together,
|
369
|
-
the default strategy is to replace current array with new one.
|
370
|
-
|
371
|
-
However, in some certain circumstances, you may need another
|
372
|
-
behavior. Here the list of strategies that can be used.
|
373
|
-
|
374
|
-
* `:replace` (*default*)
|
375
|
-
With this strategy, the new array completely replace the
|
376
|
-
current one.
|
377
|
-
|
378
|
-
* `:concat`
|
379
|
-
With this strategy, new array is appended to the end
|
380
|
-
of current array when merged. The `Array` `+` operator
|
381
|
-
is used to concatenante the two arrays.
|
382
|
-
|
383
|
-
* `:extend`
|
384
|
-
With this strategy, current array is extended with values
|
385
|
-
from new one. The `Array` `|` (union) operator
|
386
|
-
is used to extend the array.
|
387
|
-
|
388
|
-
You can use the following snippet directly within your Vagrantfile
|
389
|
-
to change the array merge strategy:
|
390
|
-
|
391
|
-
Vagrant.configure("2") do |config|
|
392
|
-
config.user.array_merge_strategy = :extend
|
393
|
-
|
394
|
-
config.ssh.port config.user.vm.ssh_port
|
395
|
-
end
|
396
|
-
|
397
|
-
Note that you should change the array merge strategy before
|
398
|
-
you access any keys because it's just once set that values
|
399
|
-
are computed using the new strategy.
|
400
|
-
|
401
|
-
If you specify an unsupported strategy, nothing will happen.
|
402
|
-
|
403
|
-
#### Commands
|
404
|
-
|
405
|
-
In this section, we describe the various vagrant commands defined
|
406
|
-
by this plug-in that can be used to interact with it.
|
407
|
-
|
408
|
-
##### Parameters
|
409
|
-
|
410
|
-
This command will print the currently defined parameters at the
|
411
|
-
given location. All rules are respected when using this command.
|
412
|
-
It is usefull to see what parameters are available and what are
|
413
|
-
the current values of those parameters.
|
414
|
-
|
415
|
-
Usage:
|
416
|
-
|
417
|
-
> vagrant user parameters
|
418
|
-
---
|
419
|
-
config:
|
420
|
-
user:
|
421
|
-
chef:
|
422
|
-
cookbooks_path: /Users/Chef/kitchen/cookbooks
|
423
|
-
nodes_path: /Users/Chef/kitchen/nodes
|
424
|
-
roles_path: /Users/Chef/kitchen/roles
|
425
|
-
|
426
|
-
Add flag `-h` (or `--help`) for description of the command and a
|
427
|
-
list of available options.
|
428
|
-
|
429
|
-
##### Restricted Keys
|
430
|
-
|
431
|
-
This command will print the keys that cannot be accessed using
|
432
|
-
the method access syntax.
|
433
|
-
|
434
|
-
Usage:
|
435
|
-
|
436
|
-
> vagrant user restricted-keys
|
437
|
-
|
438
|
-
##### Env
|
439
|
-
|
440
|
-
Sometimes, you would like to have acces to the different values
|
441
|
-
stored in your `.vagrantuser` from environment variables: this is
|
442
|
-
exactly what this section is meant to show you.
|
443
|
-
|
444
|
-
By using one of the three methods below, you will be able to export
|
445
|
-
(but also unset) environment variables from your current
|
446
|
-
parameters as seen by Nugrant.
|
447
|
-
|
448
|
-
You can see the commands that will be executed by simply
|
449
|
-
calling the method:
|
450
|
-
|
451
|
-
vagrant user env
|
452
|
-
|
453
|
-
The name of the environment will be upper cased and full path of
|
454
|
-
the key, without the `config.user` prefix, separated
|
455
|
-
with `_`. For example, the key accessible using
|
456
|
-
`config.user.db.user` and with value `root` would generate the
|
457
|
-
export command:
|
458
|
-
|
459
|
-
export DB_USER=root
|
460
|
-
|
461
|
-
The value are escaped so it is possible to define value containing
|
462
|
-
spaces for example.
|
463
|
-
|
464
|
-
A last note about generate commands is that pre-existing environment
|
465
|
-
variable are not taking in consideration by this command. So if
|
466
|
-
an environment variable with name `DB_USER` already exist, it
|
467
|
-
would be overwritten by an export command.
|
468
|
-
|
469
|
-
Add flag `-h` (or `--help`) for description of the command and a
|
470
|
-
list of available options.
|
471
|
-
|
472
|
-
It's possible to export variables automatically on when Vagrant
|
473
|
-
provision your VM. Refer to [Automatic Exporting section](#automatic-exporting)
|
474
|
-
for more information.
|
475
|
-
|
476
|
-
###### Method #1
|
477
|
-
|
478
|
-
If you plan to frequently use this feature, our best suggestion
|
479
|
-
is to create a little bash script that will simply delegates
|
480
|
-
to the real command. By having a bash script that calls the
|
481
|
-
command, you will be able to easily export environment variables
|
482
|
-
by sourcing the script.
|
483
|
-
|
484
|
-
Create a file named `nugrant2env` somewhere accessible from
|
485
|
-
the `$PATH` variable with the following content:
|
486
|
-
|
487
|
-
#!/bin/env sh
|
488
|
-
|
489
|
-
$(vagrant user env "$@")
|
490
|
-
|
491
|
-
This script will simply delegates to the `vagrant user env`
|
492
|
-
command and pass all arguments it receives to it. The
|
493
|
-
magic happens because the command `vagrant user env` outputs
|
494
|
-
the various export commands to the standard output.
|
495
|
-
|
496
|
-
By sourcing the simple delegating bash script, the parameters
|
497
|
-
seen by Nugrant will be available in your environment:
|
498
|
-
|
499
|
-
. nugrant2env
|
500
|
-
|
501
|
-
By default, export commands are generated. But you can pass
|
502
|
-
some options to the `nugrant2env` script, For example, to
|
503
|
-
generate the unset ones, add `--unset` (or simply `-u`).
|
504
|
-
|
505
|
-
. nugrant2env --unset
|
506
|
-
|
507
|
-
For a list of options, see the help of the command delegated
|
508
|
-
to:
|
509
|
-
|
510
|
-
vagrant user env -h
|
511
|
-
|
512
|
-
###### Method #2
|
513
|
-
|
514
|
-
Use the command to generate a base script in the current
|
515
|
-
directory that you will then source:
|
516
|
-
|
517
|
-
vagrant user env --format script
|
518
|
-
|
519
|
-
This will generate a script called `nugrant2env.sh` into the
|
520
|
-
current directory. You then simply source this script:
|
521
|
-
|
522
|
-
. nugrant2env.sh
|
523
|
-
|
524
|
-
Using `vagrant user env -u --format script` will instead generate the bash
|
525
|
-
script that will unset the environment variables. Don't forget
|
526
|
-
to source it to unset variables.
|
527
|
-
|
528
|
-
###### Method #3
|
529
|
-
|
530
|
-
Use the command to generate an [autoenv](https://github.com/kennethreitz/autoenv)
|
531
|
-
file in the current directory. By using the [autoenv] project, anytime you
|
532
|
-
will enter the project directory via the `cd` command, variables
|
533
|
-
exported found in the `.env` file generated will be exported to
|
534
|
-
your environment.
|
535
|
-
|
536
|
-
vagrant user env --format autoenv
|
537
|
-
|
538
|
-
This will generate a file called `.env` in the
|
539
|
-
current directory. You then simply change to the directory
|
540
|
-
where the `.env` file was generated to made exported variables
|
541
|
-
available in your environment.
|
542
|
-
|
543
|
-
cd ..
|
544
|
-
cd <project_dir>
|
545
|
-
|
546
|
-
Using `vagrant user env -u --format autoenv` will instead generate
|
547
|
-
the autoenv file that will unset the environment variables.
|
548
|
-
|
549
|
-
#### Automatic Exporting
|
550
|
-
|
551
|
-
Running the right command each time variables change can be repetive
|
552
|
-
for nothing. Why not let the computer do the hard work for us, they
|
553
|
-
have been created for this after all.
|
554
|
-
|
555
|
-
You can achieve this using the `config.user.auto_export` parameter.
|
556
|
-
Defaulting to `false`, you can use it to export the variables
|
557
|
-
to your desired format. When set to a valid value, each time
|
558
|
-
vagrant will provision your VM, Nugrant will automatically
|
559
|
-
export variables for your.
|
560
|
-
|
561
|
-
Use the following configuration to export to [autoenv](https://github.com/kennethreitz/autoenv)
|
562
|
-
script format.
|
563
|
-
|
564
|
-
config.user.auto_export = :autoenv
|
565
|
-
|
566
|
-
Use the following configuration to export to bash script.
|
567
|
-
|
568
|
-
config.user.auto_export = :script
|
569
|
-
|
570
|
-
You can also pass an array of formats if you would like to export to
|
571
|
-
multiple formats at the same time.
|
572
|
-
|
573
|
-
config.user.auto_export = [:autoenv, :script]
|
574
|
-
|
575
|
-
|
576
|
-
The default filename for bash script (i.e. when using `:script` value) is
|
577
|
-
`./nugrant2env.sh`. You can control this by using parameter
|
578
|
-
`config.user.auto_export_script_path`:
|
579
|
-
|
580
|
-
config.user.auto_export_script_path = "./script/env.sh"
|
581
|
-
|
582
|
-
### Library
|
583
|
-
|
584
|
-
Using Nugrant as a library to handle parameters from various
|
585
|
-
location is really easy. Two main classes need to be handled.
|
586
|
-
|
587
|
-
First, you need to create a `Nugrant::Config` object. This
|
588
|
-
configuration holds the values that needs to be customized
|
589
|
-
by your own application. This includes the different parameters paths
|
590
|
-
and the format of the parameters file.
|
591
|
-
|
592
|
-
## Contributing
|
593
|
-
|
594
|
-
You can contribute by filling issues when something goes
|
595
|
-
wrong or was not what you expected. I will do my best
|
596
|
-
to fix the issue either in the code or in the documentation,
|
597
|
-
where applicable.
|
598
|
-
|
599
|
-
You can also send pull requests for any feature or improvement
|
600
|
-
you think should be included in this plug-in. I will evaluate
|
601
|
-
each of them and merge them as fast as possible.
|
1
|
+
# Nugrant
|
2
|
+
|
3
|
+
[][gem]
|
4
|
+
[][travis]
|
5
|
+
[][gemnasium]
|
6
|
+
[][codeclimate]
|
7
|
+
|
8
|
+
[gem]: https://rubygems.org/gems/nugrant
|
9
|
+
[travis]: http://travis-ci.org/maoueh/nugrant
|
10
|
+
[gemnasium]: https://gemnasium.com/maoueh/nugrant
|
11
|
+
[codeclimate]: https://codeclimate.com/github/maoueh/nugrant
|
12
|
+
|
13
|
+
Nugrant is a library to easily handle parameters that need to be
|
14
|
+
injected into an application via different sources (system, user,
|
15
|
+
current, defaults). But foremost, a Vagrant plug-in that will enhance
|
16
|
+
Vagrantfile to allow user specific configuration values.
|
17
|
+
|
18
|
+
Supported platforms:
|
19
|
+
|
20
|
+
* Vagrant 1.x
|
21
|
+
* Ruby 1.9.3+
|
22
|
+
|
23
|
+
## Quick Start
|
24
|
+
|
25
|
+
Using Nugrant as a plug-in provides an easy and hierarchical system to manage
|
26
|
+
machine and user specific parameters.
|
27
|
+
|
28
|
+
Let's start with an example. You need to distribute among your enterprise a
|
29
|
+
`Vagrantfile` to start and provision an AWS EC2 instance (or for an open-source project).
|
30
|
+
The `aws_access_key` and `aws_secret_key` should be configurable depending on the user
|
31
|
+
running `vagrant up`.
|
32
|
+
|
33
|
+
To achieve this, simply create a file named `.vagrantuser` that resides in the directory
|
34
|
+
as your `Vagrantfile`:
|
35
|
+
|
36
|
+
aws:
|
37
|
+
access_key: "123456"
|
38
|
+
secret_key: "abcdef"
|
39
|
+
|
40
|
+
In your `Vagrantfile`, `Nugrant` will let you access the parameters via the
|
41
|
+
`config.user` object:
|
42
|
+
|
43
|
+
Vagrant.configure("2") do |config|
|
44
|
+
...
|
45
|
+
|
46
|
+
config.vm.provider :aws do |aws, override|
|
47
|
+
aws.access_key_id = config.user.aws.access_key
|
48
|
+
aws.secret_access_key = config.user.aws.secret_key
|
49
|
+
|
50
|
+
...
|
51
|
+
end
|
52
|
+
end
|
53
|
+
|
54
|
+
You then ignore the `.vagrantuser` file in your revision control, so each developer
|
55
|
+
as a specific one with their own values. People often commit a `.vagrantuser.example`
|
56
|
+
file in project's repository as an easy startup for the various parameters that
|
57
|
+
must be filled in, something like:
|
58
|
+
|
59
|
+
aws:
|
60
|
+
access_key: "<ACCESS_KEY_HERE>"
|
61
|
+
secret_key: "<SECRET_KEY_HERE>"
|
62
|
+
|
63
|
+
To find where your project `.vagrantuser` is located, Nugrant uses the directory
|
64
|
+
where the `Vagrantfile` is located. It achieves this using the same set of
|
65
|
+
rules as Vagrant meaning you can be in a nested directory and parameters
|
66
|
+
will still be fetched correctly.
|
67
|
+
|
68
|
+
Moreover, like other similar system, there is a hierarchy of `.vagrantuser` files
|
69
|
+
that you can leverage:
|
70
|
+
|
71
|
+
| Name | Location | Priority | Overrides |
|
72
|
+
| ---------|-----------------------------------------|:---------:|--------------------------|
|
73
|
+
| Defaults | [config.user.defaults](#default-values) | 4 | - |
|
74
|
+
| System | $SYSTEM/.vagrantuser | 3 | Defaults |
|
75
|
+
| User | ~/.vagrantuser | 2 | Defaults & System |
|
76
|
+
| Project | .vagrantuser | 1 | Defaults & System & User |
|
77
|
+
|
78
|
+
The project level directory is always the same as the directory where your
|
79
|
+
`Vagrantfile` resides and same rules as Vagrant are used to find it.
|
80
|
+
The `~` is the user's home directory and `$SYSTEM` is the platform dependent
|
81
|
+
folder where system global can be put. Check [Hierarchy](#hierarchy) section
|
82
|
+
for where `$SYSTEM` maps exactly.
|
83
|
+
|
84
|
+
You can use the command `vagrant user parameters` to see the final merged
|
85
|
+
hierarchy seen by Nugrant. This command also prints [restricted keys](#restricted-keys)
|
86
|
+
defined in your hierarchy.
|
87
|
+
|
88
|
+
Accessing parameters in your `Vagrantfile` can be done either by method access
|
89
|
+
(i.e. `config.user.<key>`) or by array access (i.e. `config.user[<key>]`).
|
90
|
+
This support is working for any deepness, only `config.user` is different
|
91
|
+
because provided directly by `Vagrant` and not by this plugin.
|
92
|
+
|
93
|
+
However, a drawback with method access, not present with array access, is its
|
94
|
+
set of [restricted keys](#restricted-keys) for which usage is prohibited. These
|
95
|
+
are in facts calls to method defined by the [Bag](lib/nugrant/bag.rb) class
|
96
|
+
([Bag](lib/nugrant/bag.rb) extends [Hash](http://ruby-doc.org/core-2.0/Hash.html)).
|
97
|
+
It's plain Ruby, use it at your advantage like iterating through a collection
|
98
|
+
using the `.each` method.
|
99
|
+
|
100
|
+
This is where the quick start end. Continue to section [Installation](#installation)
|
101
|
+
if you need so help on how to install Nugrant. Or jump to [Usage](#usage) section
|
102
|
+
which describe in greater details all necessary information needed to deeply
|
103
|
+
understand Nugrant and use it at its full potential.
|
104
|
+
|
105
|
+
## Installation
|
106
|
+
|
107
|
+
### Vagrant
|
108
|
+
|
109
|
+
Vagrant's plug-in system is very well done and Nugrant supports
|
110
|
+
the following plug-in API versions:
|
111
|
+
|
112
|
+
* V2 => Vagrant 1.x
|
113
|
+
|
114
|
+
To install the Nugrant as a Vagrant plug-in, simply type the following
|
115
|
+
command in a terminal:
|
116
|
+
|
117
|
+
vagrant plugin install nugrant
|
118
|
+
|
119
|
+
#### Vagrant 0.x
|
120
|
+
|
121
|
+
Vagrant 0.x is not supported anymore. If you still need support for
|
122
|
+
Vagrant 0.x, please use release line `1.x` (branch [1.x](https://github.com/maoueh/nugrant/tree/1.x)).
|
123
|
+
|
124
|
+
### Library
|
125
|
+
|
126
|
+
If you would like to use Nugrant as a library, simply reference
|
127
|
+
it as a dependency of your application. Probably by adding it to
|
128
|
+
your `Gemfile` or your `.gemspec` file.
|
129
|
+
|
130
|
+
"nugrant", "~> 2.0"
|
131
|
+
|
132
|
+
## Usage
|
133
|
+
|
134
|
+
Whether used as a library or a Vagrant plug-in, Nugrant has some
|
135
|
+
common concepts that apply to both usages. The most important
|
136
|
+
one is the parameters hierarchy.
|
137
|
+
|
138
|
+
### Common
|
139
|
+
|
140
|
+
Nugrant can read parameters from various locations and will merge
|
141
|
+
them all together in a single set. Merging is done in a fairly
|
142
|
+
standard fashion.
|
143
|
+
|
144
|
+
Here the precedence rules that apply when merging parameters
|
145
|
+
from various location. List index indicate the priority of the
|
146
|
+
entry. Entry with lower number has lower priority (values at this
|
147
|
+
priority will be overridden by values defined on higher priorities).
|
148
|
+
|
149
|
+
1. Defaults
|
150
|
+
2. System
|
151
|
+
3. User
|
152
|
+
4. Current
|
153
|
+
|
154
|
+
In text, this means that current parameters overrides user
|
155
|
+
parameters, user parameters overrides system parameters and
|
156
|
+
finally system parameters overrides defaults parameters.
|
157
|
+
|
158
|
+
When two keys that are merged together points to Array values,
|
159
|
+
the default operation is to replace current Array by
|
160
|
+
overriding one. The default merge strategy can be customized.
|
161
|
+
|
162
|
+
### Vagrant
|
163
|
+
|
164
|
+
All examples shown here are for Vagrant 1.1+. They have
|
165
|
+
been tested with Vagrant 1.4.0. Keep this in mind when
|
166
|
+
copying examples.
|
167
|
+
|
168
|
+
Let start with a small use case. Say the git repository you want
|
169
|
+
to share with your guest VM is not located under the root folder of
|
170
|
+
your `Vagrantfile`. That means you will need to specify
|
171
|
+
an absolute host path to share the folder on the guest VM.
|
172
|
+
|
173
|
+
Your `Vagrantfile` would look like this:
|
174
|
+
|
175
|
+
Vagrant.configure("2") do |config|
|
176
|
+
config.vm.box = "base"
|
177
|
+
config.vm.synced_folder "/home/user/work/git", "/git"
|
178
|
+
end
|
179
|
+
|
180
|
+
However, what happens when multiple developers
|
181
|
+
need to share the same `Vagrantfile`? This is the main
|
182
|
+
use case this plug-in try to address.
|
183
|
+
|
184
|
+
When Vagrant starts, it loads all vagrant plug-ins it knows
|
185
|
+
about. If you installed the plug-in with one of the two
|
186
|
+
methods we listed above, Vagrant will know about Nugrant
|
187
|
+
and will load it correctly.
|
188
|
+
|
189
|
+
To use the plug-in, first create a YAML file named
|
190
|
+
`.vagrantuser` in the same folder where your `Vagrantfile` is
|
191
|
+
located. The file must be a valid YAML file:
|
192
|
+
|
193
|
+
repository:
|
194
|
+
project: "/home/user/work/git"
|
195
|
+
|
196
|
+
The configuration hierarchy you define in the `.vagrantuser` file
|
197
|
+
is imported into the `config` object of the `Vagrantfile`
|
198
|
+
under the key `user`. So, with the `.vagrantuser` file above, you
|
199
|
+
could have this `Vagrantfile` that abstract absolute paths.
|
200
|
+
|
201
|
+
Vagrant.configure("2") do |config|
|
202
|
+
config.vm.box = "base"
|
203
|
+
config.vm.synced_folder config.user.repository.project, "/git"
|
204
|
+
end
|
205
|
+
|
206
|
+
This way, paths can be customized by every developer. They just
|
207
|
+
have to add a `.vagrantuser` file where user specific configuration
|
208
|
+
values can be specified. The `.vagrantuser` should be ignored by you
|
209
|
+
version control system so it is to committed with the project.
|
210
|
+
|
211
|
+
Additionally, you can also have a `.vagrantuser` under your user home
|
212
|
+
directory. This way, you can set parameters that will be
|
213
|
+
available to all your `Vagrantfile` files. The `.vagrantuser` located
|
214
|
+
within the same folder as the `Vagrantfile` file will overrides
|
215
|
+
parameters defined in the `.vagrantuser` file defined in the user
|
216
|
+
home directory.
|
217
|
+
|
218
|
+
For example, you have `.vagrantuser` file located at `~/.vagrantuser`
|
219
|
+
that has the following content:
|
220
|
+
|
221
|
+
ssh_port: 2223
|
222
|
+
repository:
|
223
|
+
project: "/home/user/work/git"
|
224
|
+
|
225
|
+
And another `.vagrantuser` within the same folder as your `Vagrantfile`:
|
226
|
+
|
227
|
+
ssh_port: 3332
|
228
|
+
repository:
|
229
|
+
personal: "/home/user/personal/git"
|
230
|
+
|
231
|
+
Then, the `Vagrantfile` could be defined like this:
|
232
|
+
|
233
|
+
Vagrant.configure("2") do |config|
|
234
|
+
config.ssh.port config.user.ssh_port
|
235
|
+
|
236
|
+
config.vm.synced_folder config.user.repository.project, "/git"
|
237
|
+
config.vm.synced_folder config.user.repository.personal, "/personal"
|
238
|
+
end
|
239
|
+
|
240
|
+
That would be equivalent to:
|
241
|
+
|
242
|
+
Vagrant.configure("2") do |config|
|
243
|
+
config.ssh.port 3332
|
244
|
+
|
245
|
+
config.vm.synced_folder "/home/user/work/git", "/git"
|
246
|
+
config.vm.synced_folder "/home/user/personal/git", "/personal"
|
247
|
+
end
|
248
|
+
|
249
|
+
#### Hierarchy
|
250
|
+
|
251
|
+
As you can see, the parameters defined in the second `.vagrantuser` file
|
252
|
+
(the current one) overrides settings defined in the `.vagrantuser` found
|
253
|
+
in the home directory (the user one).
|
254
|
+
|
255
|
+
Here the list of locations where Nugrant looks for parameters:
|
256
|
+
|
257
|
+
1. Defaults (via `config.user.defaults` in `Vagrantfile`)
|
258
|
+
2. System (`/etc/.vagrantuser` on Unix, `%PROGRAMDATA%/.vagrantuser` or `%ALLUSERSPROFILE%/.vagrantuser` on Windows)
|
259
|
+
3. Home (`~/.vagrantuser`)
|
260
|
+
4. Project (`.vagrantuser` within the same folder as the `Vagrantfile`)
|
261
|
+
|
262
|
+
#### Paths
|
263
|
+
|
264
|
+
When you want to specify paths on, specially on Windows, it's probably
|
265
|
+
better to only use forward slash (`/`). The main reason for this is because
|
266
|
+
Ruby, which will be used at the end by Vagrant is able to deal with forward
|
267
|
+
slash even on Windows. This is great because with this, you can avoid
|
268
|
+
values escaping in YAML file. If you need to use backward slash (`\`), don't
|
269
|
+
forget to properly escape it!
|
270
|
+
|
271
|
+
value: "C:/Users/user/work/git"
|
272
|
+
value: "C:\\Users\\user\\work\\git"
|
273
|
+
|
274
|
+
Moreover, it is preferable that paths are specified in full
|
275
|
+
(i.e. no `~` for HOME directory for example). Normally, they
|
276
|
+
should be handled by `Vagrant` but it may happen that it's not
|
277
|
+
the case. If your have an error with a specific parameter,
|
278
|
+
either expand it in your config:
|
279
|
+
|
280
|
+
project: "/home/joe/work/ruby/git"
|
281
|
+
|
282
|
+
Of expand it in the `Vagrantfile`:
|
283
|
+
|
284
|
+
config.vm.synced_folder File.expand_path(config.user.repository.project), "/git"
|
285
|
+
|
286
|
+
#### Parameters access
|
287
|
+
|
288
|
+
Parameters in the `Vagrantfile` can be retrieved via method call
|
289
|
+
of array access.
|
290
|
+
|
291
|
+
config.user['repository']['project'] # Array access
|
292
|
+
config.user.repository.project # Method access
|
293
|
+
|
294
|
+
You can even mix the two if you want, but we do not recommend
|
295
|
+
it since its always better to be consistent:
|
296
|
+
|
297
|
+
config.user['repository'].project # Mixed access
|
298
|
+
config.user.repository['project'] # Mixed access
|
299
|
+
|
300
|
+
Only the root key, i.e. `config.user`, cannot be access with
|
301
|
+
both syntax, only the method syntax can be used since this
|
302
|
+
is not provided by this plug-in but by Vagrant itself.
|
303
|
+
|
304
|
+
##### Tips
|
305
|
+
|
306
|
+
Each non-final parameter (i.e a parameter that contains other parameters and
|
307
|
+
not a scalar value) is in fact a [Bag](/lib/nugrant/bag.rb)
|
308
|
+
object. You can call any defined methods on it. This object extends
|
309
|
+
[Hash](http://ruby-doc.org/core-2.0/Hash.html) (itself including
|
310
|
+
module [Enumerable](http://ruby-doc.org/core-2.0/Enumerable.html)). Hence,
|
311
|
+
you can do neat things like iterating over your values or filtering them:
|
312
|
+
|
313
|
+
config.user.application.users.each do |key, data|
|
314
|
+
puts "Key #{key}: #{data}"
|
315
|
+
end
|
316
|
+
|
317
|
+
##### Restricted keys
|
318
|
+
|
319
|
+
Method access has the neat advantage of being beautiful to the
|
320
|
+
eye. However, the drawback of using this retrieval syntax is
|
321
|
+
that not all keys are permitted. As explained in the [Tips](#tips)
|
322
|
+
section, the object you are calling when using method access
|
323
|
+
is in fact of type [Bag](/lib/nugrant/bag.rb). Hence, if you
|
324
|
+
are using a key which collapse with ones of Bag's keys, it will
|
325
|
+
call the method instead of given you the value of you parameter.
|
326
|
+
At best, you will get a weird behavior and at worst a stack
|
327
|
+
trace when trying to access the parameter.
|
328
|
+
|
329
|
+
If you really want to use one of the restricted keys, simply
|
330
|
+
ensure to always use array access method.
|
331
|
+
|
332
|
+
The list of restricted keys can be accessed using command
|
333
|
+
`vagrant user restricted-keys`.
|
334
|
+
|
335
|
+
#### Default values
|
336
|
+
|
337
|
+
When using parameters, it is often needed so set default values
|
338
|
+
for certain parameters so if the user does not define one, the
|
339
|
+
default value will be picked up.
|
340
|
+
|
341
|
+
For example, say you want a parameter that will hold the ssh
|
342
|
+
port of the vm. This parameter will be accessible via the
|
343
|
+
parameter `config.user.vm.ssh_port`.
|
344
|
+
|
345
|
+
You can use the following snippet directly within your Vagrantfile
|
346
|
+
to set a default value for this parameter:
|
347
|
+
|
348
|
+
Vagrant.configure("2") do |config|
|
349
|
+
config.user.defaults = {
|
350
|
+
"vm" => {
|
351
|
+
"ssh_port" => "3335"
|
352
|
+
}
|
353
|
+
}
|
354
|
+
|
355
|
+
config.ssh.port config.user.vm.ssh_port
|
356
|
+
end
|
357
|
+
|
358
|
+
With this Vagrantfile, the parameter `config.user.vm.ssh_port`
|
359
|
+
will default to `3335` in cases where it is not defined by the
|
360
|
+
user.
|
361
|
+
|
362
|
+
If the user decides to change it, he just has to set it in his
|
363
|
+
own `.vagrantuser` and it will override the default value defined
|
364
|
+
in the Vagrantfile.
|
365
|
+
|
366
|
+
#### Array merge strategies
|
367
|
+
|
368
|
+
As stated previously, when two arrays are merged together,
|
369
|
+
the default strategy is to replace current array with new one.
|
370
|
+
|
371
|
+
However, in some certain circumstances, you may need another
|
372
|
+
behavior. Here the list of strategies that can be used.
|
373
|
+
|
374
|
+
* `:replace` (*default*)
|
375
|
+
With this strategy, the new array completely replace the
|
376
|
+
current one.
|
377
|
+
|
378
|
+
* `:concat`
|
379
|
+
With this strategy, new array is appended to the end
|
380
|
+
of current array when merged. The `Array` `+` operator
|
381
|
+
is used to concatenante the two arrays.
|
382
|
+
|
383
|
+
* `:extend`
|
384
|
+
With this strategy, current array is extended with values
|
385
|
+
from new one. The `Array` `|` (union) operator
|
386
|
+
is used to extend the array.
|
387
|
+
|
388
|
+
You can use the following snippet directly within your Vagrantfile
|
389
|
+
to change the array merge strategy:
|
390
|
+
|
391
|
+
Vagrant.configure("2") do |config|
|
392
|
+
config.user.array_merge_strategy = :extend
|
393
|
+
|
394
|
+
config.ssh.port config.user.vm.ssh_port
|
395
|
+
end
|
396
|
+
|
397
|
+
Note that you should change the array merge strategy before
|
398
|
+
you access any keys because it's just once set that values
|
399
|
+
are computed using the new strategy.
|
400
|
+
|
401
|
+
If you specify an unsupported strategy, nothing will happen.
|
402
|
+
|
403
|
+
#### Commands
|
404
|
+
|
405
|
+
In this section, we describe the various vagrant commands defined
|
406
|
+
by this plug-in that can be used to interact with it.
|
407
|
+
|
408
|
+
##### Parameters
|
409
|
+
|
410
|
+
This command will print the currently defined parameters at the
|
411
|
+
given location. All rules are respected when using this command.
|
412
|
+
It is usefull to see what parameters are available and what are
|
413
|
+
the current values of those parameters.
|
414
|
+
|
415
|
+
Usage:
|
416
|
+
|
417
|
+
> vagrant user parameters
|
418
|
+
---
|
419
|
+
config:
|
420
|
+
user:
|
421
|
+
chef:
|
422
|
+
cookbooks_path: /Users/Chef/kitchen/cookbooks
|
423
|
+
nodes_path: /Users/Chef/kitchen/nodes
|
424
|
+
roles_path: /Users/Chef/kitchen/roles
|
425
|
+
|
426
|
+
Add flag `-h` (or `--help`) for description of the command and a
|
427
|
+
list of available options.
|
428
|
+
|
429
|
+
##### Restricted Keys
|
430
|
+
|
431
|
+
This command will print the keys that cannot be accessed using
|
432
|
+
the method access syntax.
|
433
|
+
|
434
|
+
Usage:
|
435
|
+
|
436
|
+
> vagrant user restricted-keys
|
437
|
+
|
438
|
+
##### Env
|
439
|
+
|
440
|
+
Sometimes, you would like to have acces to the different values
|
441
|
+
stored in your `.vagrantuser` from environment variables: this is
|
442
|
+
exactly what this section is meant to show you.
|
443
|
+
|
444
|
+
By using one of the three methods below, you will be able to export
|
445
|
+
(but also unset) environment variables from your current
|
446
|
+
parameters as seen by Nugrant.
|
447
|
+
|
448
|
+
You can see the commands that will be executed by simply
|
449
|
+
calling the method:
|
450
|
+
|
451
|
+
vagrant user env
|
452
|
+
|
453
|
+
The name of the environment will be upper cased and full path of
|
454
|
+
the key, without the `config.user` prefix, separated
|
455
|
+
with `_`. For example, the key accessible using
|
456
|
+
`config.user.db.user` and with value `root` would generate the
|
457
|
+
export command:
|
458
|
+
|
459
|
+
export DB_USER=root
|
460
|
+
|
461
|
+
The value are escaped so it is possible to define value containing
|
462
|
+
spaces for example.
|
463
|
+
|
464
|
+
A last note about generate commands is that pre-existing environment
|
465
|
+
variable are not taking in consideration by this command. So if
|
466
|
+
an environment variable with name `DB_USER` already exist, it
|
467
|
+
would be overwritten by an export command.
|
468
|
+
|
469
|
+
Add flag `-h` (or `--help`) for description of the command and a
|
470
|
+
list of available options.
|
471
|
+
|
472
|
+
It's possible to export variables automatically on when Vagrant
|
473
|
+
provision your VM. Refer to [Automatic Exporting section](#automatic-exporting)
|
474
|
+
for more information.
|
475
|
+
|
476
|
+
###### Method #1
|
477
|
+
|
478
|
+
If you plan to frequently use this feature, our best suggestion
|
479
|
+
is to create a little bash script that will simply delegates
|
480
|
+
to the real command. By having a bash script that calls the
|
481
|
+
command, you will be able to easily export environment variables
|
482
|
+
by sourcing the script.
|
483
|
+
|
484
|
+
Create a file named `nugrant2env` somewhere accessible from
|
485
|
+
the `$PATH` variable with the following content:
|
486
|
+
|
487
|
+
#!/bin/env sh
|
488
|
+
|
489
|
+
$(vagrant user env "$@")
|
490
|
+
|
491
|
+
This script will simply delegates to the `vagrant user env`
|
492
|
+
command and pass all arguments it receives to it. The
|
493
|
+
magic happens because the command `vagrant user env` outputs
|
494
|
+
the various export commands to the standard output.
|
495
|
+
|
496
|
+
By sourcing the simple delegating bash script, the parameters
|
497
|
+
seen by Nugrant will be available in your environment:
|
498
|
+
|
499
|
+
. nugrant2env
|
500
|
+
|
501
|
+
By default, export commands are generated. But you can pass
|
502
|
+
some options to the `nugrant2env` script, For example, to
|
503
|
+
generate the unset ones, add `--unset` (or simply `-u`).
|
504
|
+
|
505
|
+
. nugrant2env --unset
|
506
|
+
|
507
|
+
For a list of options, see the help of the command delegated
|
508
|
+
to:
|
509
|
+
|
510
|
+
vagrant user env -h
|
511
|
+
|
512
|
+
###### Method #2
|
513
|
+
|
514
|
+
Use the command to generate a base script in the current
|
515
|
+
directory that you will then source:
|
516
|
+
|
517
|
+
vagrant user env --format script
|
518
|
+
|
519
|
+
This will generate a script called `nugrant2env.sh` into the
|
520
|
+
current directory. You then simply source this script:
|
521
|
+
|
522
|
+
. nugrant2env.sh
|
523
|
+
|
524
|
+
Using `vagrant user env -u --format script` will instead generate the bash
|
525
|
+
script that will unset the environment variables. Don't forget
|
526
|
+
to source it to unset variables.
|
527
|
+
|
528
|
+
###### Method #3
|
529
|
+
|
530
|
+
Use the command to generate an [autoenv](https://github.com/kennethreitz/autoenv)
|
531
|
+
file in the current directory. By using the [autoenv] project, anytime you
|
532
|
+
will enter the project directory via the `cd` command, variables
|
533
|
+
exported found in the `.env` file generated will be exported to
|
534
|
+
your environment.
|
535
|
+
|
536
|
+
vagrant user env --format autoenv
|
537
|
+
|
538
|
+
This will generate a file called `.env` in the
|
539
|
+
current directory. You then simply change to the directory
|
540
|
+
where the `.env` file was generated to made exported variables
|
541
|
+
available in your environment.
|
542
|
+
|
543
|
+
cd ..
|
544
|
+
cd <project_dir>
|
545
|
+
|
546
|
+
Using `vagrant user env -u --format autoenv` will instead generate
|
547
|
+
the autoenv file that will unset the environment variables.
|
548
|
+
|
549
|
+
#### Automatic Exporting
|
550
|
+
|
551
|
+
Running the right command each time variables change can be repetive
|
552
|
+
for nothing. Why not let the computer do the hard work for us, they
|
553
|
+
have been created for this after all.
|
554
|
+
|
555
|
+
You can achieve this using the `config.user.auto_export` parameter.
|
556
|
+
Defaulting to `false`, you can use it to export the variables
|
557
|
+
to your desired format. When set to a valid value, each time
|
558
|
+
vagrant will provision your VM, Nugrant will automatically
|
559
|
+
export variables for your.
|
560
|
+
|
561
|
+
Use the following configuration to export to [autoenv](https://github.com/kennethreitz/autoenv)
|
562
|
+
script format.
|
563
|
+
|
564
|
+
config.user.auto_export = :autoenv
|
565
|
+
|
566
|
+
Use the following configuration to export to bash script.
|
567
|
+
|
568
|
+
config.user.auto_export = :script
|
569
|
+
|
570
|
+
You can also pass an array of formats if you would like to export to
|
571
|
+
multiple formats at the same time.
|
572
|
+
|
573
|
+
config.user.auto_export = [:autoenv, :script]
|
574
|
+
|
575
|
+
|
576
|
+
The default filename for bash script (i.e. when using `:script` value) is
|
577
|
+
`./nugrant2env.sh`. You can control this by using parameter
|
578
|
+
`config.user.auto_export_script_path`:
|
579
|
+
|
580
|
+
config.user.auto_export_script_path = "./script/env.sh"
|
581
|
+
|
582
|
+
### Library
|
583
|
+
|
584
|
+
Using Nugrant as a library to handle parameters from various
|
585
|
+
location is really easy. Two main classes need to be handled.
|
586
|
+
|
587
|
+
First, you need to create a `Nugrant::Config` object. This
|
588
|
+
configuration holds the values that needs to be customized
|
589
|
+
by your own application. This includes the different parameters paths
|
590
|
+
and the format of the parameters file.
|
591
|
+
|
592
|
+
## Contributing
|
593
|
+
|
594
|
+
You can contribute by filling issues when something goes
|
595
|
+
wrong or was not what you expected. I will do my best
|
596
|
+
to fix the issue either in the code or in the documentation,
|
597
|
+
where applicable.
|
598
|
+
|
599
|
+
You can also send pull requests for any feature or improvement
|
600
|
+
you think should be included in this plug-in. I will evaluate
|
601
|
+
each of them and merge them as fast as possible.
|