1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
|
Usage
=====
R10k provides fairly fine grained controls over your environments to fit your
needs. If you want to do a full update of all of your environments and modules
and don't need it to be done in real time, you can trigger a full update and let
it run in the background. If you are actively developing code and need to run
very fast updates of one specific environment, you can do a targeted update of
that code as well.
All commands that deal with deploying environments are grouped under the `r10k
deploy` subcommand.
Command line invocation
-----------------------
### Deploying environments
Recursively update all environments:
r10k deploy environment --modules
The simplest way to use r10k is by simply updating all environments and modules
and takes the brute force approach of "update everything, ever." When this
command is run r10k will update all sources, create new environments and delete
old environments, and recursively update all environment modules specified in
environment Puppetfiles, yamldirs, etc. While this is the simplest method for
running r10k, it is also the slowest by a very large degree because it does the
maximum possible work. This should not be something you run interactively, or
use on a regular basis.
- - -
Update environments while avoiding unnecessary recursion:
r10k deploy environment
This will update existing environments and recursively create new environments.
Note that when an environment is deployed for the first time, it will
automatically update all modules as well. For subsequent updates only the
environment itself will be updated.
- - -
Update a single environment:
r10k deploy environment my_working_environment
When you're actively developing on a given environment, this is the best way to
deploy your changes. Note that when an environment is deployed for the first
time, it will automatically update all modules as well. For subsequent updates
only the environment itself will be updated.
- - -
Update a single environment and force an update of modules:
r10k deploy environment my_working_environment --modules
This will update the given environment and update all contained modules. This is
useful if you want to make sure that a given environment is fully up to date.
- - -
There is also a middle ground between updating all modules and updating no modules.
It is often desirable to update the environment and then update only those modules
whose definitions have changed in the Puppetfile, or whose content _could_ have
changed since the last deployment (eg, Forge modules with their version set to
`:latest` or Git modules who point to a `branch` ref).
This can be achieved by assuming content is unchanged locally on disk. This is the
opposite of what one would assume during a module development cycle, when a user
might be making local edits to test code changes. However, in production, access
to puppet code is usually locked down, and updates are deployed through automated
invocations of R10K.
In these cases, deploys where most modules are unchanged and reference exact
versions (ie, not `:latest` or a branch as mentioned above), this invocation
may shorten deployment times dozens of seconds if not minutes depending on how
many modules meet the above criteria (approximately 1 minute for every 400 modules).
To take advantage of this, set as many modules as possible in the Puppetfile to
explicit, static version. These are released Forge versions, or Git modules using
the `:tag`, or `:commit` keys. Git `:ref`s containing only the full 40 character
commit SHA will also be treated as static versions. Then invoke a deploy with:
There may be issues with deployments apparently successful after an initial errored
deployment. If this is happening, try running without the `--incremental` flag
to run a full deployment.
r10k deploy environment production --modules --incremental
- - -
Update a single environment and specify a default branch override:
r10k deploy environment my_working_environment --modules --default-branch-override default_branch_override
This will update the given environment and update all contained modules, overriding
the :default_branch entry in the Puppetfile of each module. If the specified override branch is not
found, it will fall back to the normal default branch and attempt to use that. This is used primarily to allow
automated r10k solutions using the control_branch pattern with a temporary branch deployment to
ensure the deployment is pushed to the correct module repository branch. Note that the :default_branch and its
override are only ever used if the specific desired ref cannot be located.
### Deploying modules
Update a single module across all environments:
r10k deploy module apache
This is useful for when you're working on a module specified in a Puppetfile
and want to update it across all environments. See
[Puppetfile documentation](doc/puppetfile.mkd) for details on how this affects
Forge vs. Git/SVN modules.
- - -
Update multiple modules across all environments:
r10k deploy module apache jenkins java
- - -
Update one or more modules in a single environment:
r10k deploy module -e production apache jenkins java
### Viewing environments
Display all environments being managed by r10k:
r10k deploy display
Display all environments being managed by r10k, and modules specified in the
Puppetfile:
r10k deploy display -p
Display all environments being managed by r10k, and modules specified in the
Puppetfile along with their expected and actual versions:
r10k deploy display -p --detail
Display an explicit list of environments being managed by r10k and modules
specified in the Puppetfile along with their expected and actual versions:
r10k deploy display -p --detail production vmwr webrefactor
User accounts
-------------
When running commands to deploy code on a master, r10k needs to have write
access to your Puppet environment path and should create files that are
readable by the user account running the master. If you're using Puppet
Enterprise this account is `pe-puppet`, and if you're using Puppet open source
this account is `puppet`.
This can be done in a few ways. First off, you can run r10k as the puppet user
itself. You can also create a new user that has write access to the Puppet
environment path, has the same GID as the puppet user, and has a umask of 0027.
You can also run r10k as root, which is the simplest solution but does require
access control to the root user.
|
