-
Notifications
You must be signed in to change notification settings - Fork 23
/
tile-errands.html.md.erb
204 lines (156 loc) · 11.3 KB
/
tile-errands.html.md.erb
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
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
---
title: Errands
owner: Services
---
<strong><%= modified_date %></strong>
Lifecycle errands are BOSH errands (scripts) that run at the beginning and end of an installed product's availability time. Product teams create errands as part of a product package, and a product can only run errands it includes.
For more information about BOSH errands, see [BOSH documentation](https://bosh.io/docs/errands), and for more information about errands in Pivotal Cloud Foundry (PCF), see [Managing Errands in Ops Manager](http://docs.pivotal.io/pivotalcf/customizing/managing_errands.html).
In Ops Manager 2.0 and later, tile authors can choose to [colocate errands](#colocated) on existing VMs.
When errands are not colocated, BOSH deploys a new VM for each errand defined in the tile metadata.
Colocated errands can run alongside other jobs or errands on existing VMs in an operator's deployment.
Products can have two kinds of errands. [Post-deploy errands](#post-deploy) run after a product installs but before Ops Manager displays makes it available for use.
[Pre-delete errands](#pre-delete) run after an operator chooses to delete a product, but before Ops Manager finishes removing it from use.
To save deployment time, operators can set [errand run rules](#run-rules) that dictate whether or not errands run. Tile authors can [set defaults](./product-template-reference.html#top-level) for these run rules.
## <a id="colocated"></a>Define a Colocated Errand
<p class="note"><strong>Note</strong>: Ops Manager 2.0 and later supports colocated errands.</p>
Instead of deploying a new VM for each errand, colocated errands run on an existing VM.
Errands can run alongside other jobs on a VM, and multiple errands can be colocated on the same VM.
Colocated errands run faster than traditional errands and use fewer resources, including disk and IP space.
To configure a colocated errand, define the following properties in the `pre_delete_errands` and `post_deploy_errands` sections of the tile metadata:
<table>
<tr>
<th>Property</th>
<th>Description</th>
</tr><tr>
<td width="28%"><code>name: MY-ERRAND</code></td>
<td>Provide the name of the errand job. The example manifest in the following section uses <code>example_colocated_errand</code>.</td>
</tr><tr>
<td><code>colocated: true</code></td>
<td>Set this value to <code>true</code> to enable colocated errands. If you do not set this value, Ops Manager ignores all other errand attributes in this section.</td>
</tr><tr>
<td><code>run_default: on</code></td>
<td>(Optional) You can set the run rules to <code>on</code>, <code>off</code>, or <code>when-changed</code>. See <a href="#run-rules">Errand Run Rules</a> for more information.<br><br>
If you do not define this property, Ops Manager sets the run default to <code>on</code>.
The operator can override this setting using the Ops Manager API or the tile's <strong>Errand Config</strong> tab.</td>
</tr><tr>
<td><code>instances: []</code></td>
<td>(Optional) Provide an array that tells BOSH where to run the errand.
Use the name of an instance group, such as <code>web_server</code>, or a single instance, such as <code>web_server/first</code>.<br><br>
If you do not define this property or you provide an empty array, the errand runs on every instance of the job in the operator's deployment.</td>
</tr><tr>
<td><code>label: ERRAND-LABEL</code></td>
<td>Define the errand name to be shown in the tile's <strong>Errand Config</strong> page and above <strong>Apply Changes</strong>.
The example manifest in the following section uses <code>colocated errand on web_server</code>.</td>
</tr><tr>
<td><code>description: TEXT</code></td>
<td>(Optional) Provide a description for the errand that appears in the tile's <strong>Errand Config</strong> page.</td>
</tr>
</table>
After defining the errand in the sections above, add the errand to the job properties in the `job_types` section.
### <a id="colocated-example"></a>Colocated Errand Example Manifest
The following example shows colocated `post_deploy_errands` and `pre_delete_errands` sections in the tile metadata:
```yaml
post_deploy_errands:
- name: example-errand
colocated: false
- name: example_colocated_errand
colocated: true
run_default: on
instances:
- web_server/first
label: colocated errand on web_server
description: This errand does little more than print a message in order to prove colocated errands work.
pre_delete_errands:
- name: example-errand
```
The following example shows the colocated errands referenced within the `job_type`:
```yaml
job_types:
- name: web_server
resource_label: Web Server
templates:
- name: web_server
release: example-release
provides: |
web_server_info: (( .properties.example_selector.selected_option.parsed_manifest(provides_section) ))
consumes: |
web_server_info: (( .properties.example_selector.selected_option.parsed_manifest(consumes_section) ))
- name: time_logger
release: example-release
- name: example_colocated_errand
release: example-release
release: example-release
static_ip: 1
dynamic_ip: 0
max_in_flight: 1
```
### <a id='compatibility'></a>Backward Compatibility for Colocated Errands
Colocated errand support is available in Ops Manager 2.0 and later.
If your tile uses colocated errands, use the instructions in this section to ensure your tile is also compatible with Ops Manager 1.12 and earlier.
When your tile no longer requires Ops Manager 1.12 support, configure your errands as either colocated or non-colocated.
Future versions of Ops Manager will not support the workaround described in this section.
The following example manifest shows an `example_colocated_errand` configured as a colocated errand in Ops Manager 2.0 and as an instance group errand in Ops Manager 1.12:
```yaml
post_deploy_errands:
- name: example_colocated_errand
colocated: true
run_default: on
instances:
- web_server/first
label: colocated errand on web_server
description: This errand does little more than print a message in order to prove colocated errands work.
...
job_types:
- name: example_colocated_errand
description: The very best illustrative errand that prints all the properties, including secrets.
templates:
- name: dummy
release: dummy
errand: true
...
- name: web_server
resource_label: Web Server
templates:
- name: example_colocated_errand
release: example-release
```
To make your tile compatible with both colocated and non-colocated errands, perform the following steps:
1. Configure your colocated errand for Ops Manager 2.0, as shown in the [Colocated Errand Example Manifest](#colocated-example).
Ops Manager versions 1.12 and earlier ignore this property in the manifest.
1. In the `job_types` section, define the same errand in the `web_server` instance group, as shown in the example above.
Ops Manager 1.12 and earlier runs the errand on every VM in the `web_server` instance group.
If you want the errand to run only once, configure the errand to run on an instance group with only one instance.
1. Configure the instance group that corresponds to your errand:
* Set `instance_definition.configurable: false`
* Set `instance_definition.default: 0`
* Configure at least one non-errand job in the instance group. Ops Manager requires each instance group to contain at least one job.
<p class="note"><strong>Note</strong>: The example manifest above uses the <code>dummy</code> job from the <a href="https://github.com/pivotal-cf-experimental/dummy-boshrelease/tree/master/jobs">Dummy BOSH release</a>. You can use any no-op job.</p>
1. Ops Manager 1.12 and earlier displays the following warning, but runs the errand on the specified instance group:
<pre class="terminal">Warning: Ambiguous request: the requested errand name 'example\_colocated\_errand' matches both a job name and an errand instance group</pre>
##<a id='post-deploy'></a>Post-Deploy Errands
Post-deploy errands run after a product installs, but before Ops Manager makes it available for use.
Typical post-install errands include smoke or acceptance tests, database initialization or database migration, and service broker registration.
Post-deploy errands run by default. An operator can prevent a post-deploy errand from running by setting its [run rule](#run-rules) to **Off** under **Pending Changes** in the Ops Manager Installation Dashboard or on the product tile's **Settings** tab **Errands** pane, before installing the product.
For example, Redis has a **Broker Registrar** post-deploy errand that the Elastic Runtime tile uses to register its service broker with the Cloud Controller and publish its service plans.
If an operator chooses **Off** in the drop-down menu for Elastic Runtime's **Broker Registrar** errand before installation, Elastic Runtime's service broker is not registered with the Cloud Controller and its service plans are not made public.
##<a id='pre-delete'></a>Pre-Delete Errands
Pre-delete errands run after an operator chooses to delete a product, but before Ops Manager actually finishes deleting it.
Typical pre-delete errands include clean up of application artifacts and service
broker de-registration. For example, Pivotal MySQL has a **Broker Deregistrar** pre-delete errand that:
* Purges the service offering
* Purges all service instances
* Purges all application bindings
* Deletes the service broker from the Cloud Controller
When an operator chooses to delete the Pivotal MySQL product, Ops Manager first
runs the **Broker Deregistrar** pre-delete errand, then deletes the product.
Pre-delete errands run by default. An operator can prevent a pre-delete errand from running by setting its [run rule](#run-rules) to **Off** under **Pending Changes** in the Ops Manager Installation Dashboard or on the product tile's **Settings** tab **Errands** pane, before installing the product.
##<a id='run-rules'></a>Errand Run Rules
<p class="note warning"><strong>WARNING</strong>: In Ops Manager v1.10.0 and later, errands set to the <strong>When Changed</strong> rule do not always run when the tile has relevant changes.
Instead of using <strong>When Changed</strong>, Pivotal recommends that tile developers leave the default run rule for errands as <strong>On</strong>
and let operators use <a href="http://docs.pivotal.io/pivotalcf/customizing/managing_errands.html#changes-view">one-time rules</a> to turn errands off and save deploy time.</p>
Some errands do not always need to run. For example, installing a minor patch to a existing service might not require re-registering its broker. Ops Manager lets operators save installation time by turning errands off or on. They set these errand run rules in two places:
* **One-Time Rules** under **Pending Changes** in the Ops Manager Installation Dashboard. These rules only apply to the next time you run **Apply Changes** and do not persist after the next successful installation.
* **Persistent Rules** in the tile's **Errands** pane. These rules persist through subsequent installations, until changed in the **Errands** pane.
For more information, see [Configure Run Rules in Ops Manager](http://docs.pivotal.io/pivotalcf/customizing/managing_errands.html#modify).