forked from mboldt/docs-tiledev
-
Notifications
You must be signed in to change notification settings - Fork 0
/
tile-errands.html.md.erb
193 lines (155 loc) · 8.63 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
---
title: Using BOSH errands with your tile
owner: Services
---
Life cycle 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.
In Tanzu Operations Manager v2.0 and later, you can select [co-locate errands](#colocated) on existing VMs.
When errands are not co-located, BOSH deploys a new VM for each errand defined in the tile metadata.
Co-located errands can run alongside other jobs or errands on existing VMs in an operator's deployment.
For more information about BOSH errands, see [BOSH documentation](https://bosh.io/docs/errands),
and for more information about errands in <%= vars.platform_name %>,
see [Managing errands in Tanzu Operations Manager](https://docs.vmware.com/en/VMware-Tanzu-Operations-Manager/3.0/vmware-tanzu-ops-manager/install-managing_errands.html).
Products can have two kinds of errands.
[Post-deploy errands](#post-deploy) run after a product
installs but before Tanzu Operations Manager makes it available for use.
[Pre-delete errands](#pre-delete) run after you delete a product, but before
Tanzu Operations Manager finishes removing it from use.
To save deployment time, you can set [errand run rules](#run-rules) that dictate if errands run.
Tile authors can [set defaults](./property-template-references.html#top-level) for these run rules.
## <a id="colocated"></a>Define a co-located errand
System tests might incur costs from using third-party services, IaaS resources, and others.
Instead of deploying a new VM for each errand, co-located errands run on an existing VM.
Errands can run alongside other jobs on a VM, and multiple errands are be co-located on the same VM.
Colocated errands run faster than traditional errands and use less resources, including disk and IP space.
To configure a co-located errand, define the following properties in the `pre_delete_errands` and
`post_deploy_errands` sections of the tile metadata:
<table class=“table”>
<thead>
<tr>
<th>Property</th>
<th>Description</th>
</tr>
</thead>
<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,
Tanzu Operations 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> or <code>off</code>.
See <a href="#run-rules">Errand Run Rules</a> for more information.<br><br>
If you do not define this property, Tanzu Operations Manager sets the run default to <code>on</code>.
The operator can override this setting using the Tanzu Operations 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> tab and
following <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> tab.</td>
</tr><tr>
<td width="30%"><code>impact_warning: TEXT</code></td>
<td>(Optional) Provide an impact warning that appears in the
<b>Review Pending Changes</b> tab before running the errand.</td>
</tr>
</table>
After you define the errand in the sections previous, 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 co-located `post_deploy_errands` and `pre_delete_errands` sections
in the tile metadata:
```yaml
post_deploy_errands:
- name: example-errand
colocated: false
impact_warning: "This is an impact warning for your post-deploy errand."
- 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 to prove co-located errands work.
pre_delete_errands:
- name: example-errand
impact_warning: "This is an impact warning for your pre-delete errand."
```
The following example shows the co-located 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='post-deploy'></a>Post-deploy errands
Post-deploy errands run after a product is installed, but before Tanzu Operations Manager makes it
available for use.
Typical post-installation errands include smoke or acceptance tests, database initialization or database
migration, and service broker registration.
Post-deploy errands run by default. You can prevent a post-deploy errand from running by
setting the [run rule](#run-rules) to **Off** under **Pending Changes** in the Tanzu Operations Manager Installation
Dashboard or on the service's **Settings** tab **Errands** pane, before you install the product.
For example, Redis has a **Broker Registrar** post-deploy errand that
the <%= vars.app_runtime_full %> tile uses
to register its service broker with the Cloud Controller and publish the service plans.
If you select **Off** from the drop-down menu for Redis's **Broker Registrar** errand
before installation, the Redis service broker is not registered with the Cloud Controller and the
service plans are not made public.
##<a id='pre-delete'></a>Pre-delete errands
Pre-delete errands run after you choose to delete a product, but before Tanzu Operations Manager actually
finishes deleting it.
Typical pre-delete errands include cleanup of application artifacts and service
broker de-registration.
For example, VMware Tanzu SQL [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 you choose to delete the VMware Tanzu SQL [MySQL] product, Tanzu Operations Manager first
runs the **Broker Deregistrar** pre-delete errand, and then deletes the product.
Pre-delete errands run by default. You can prevent a pre-delete errand from running by setting
the [run rule](#run-rules) to **Off** under **Pending Changes** in the Tanzu Operations 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
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. Tanzu Operations Manager lets you save installation time by
turning errands off or on.
Errand run rules are set in two places:
* **One-Time Rules** under **Pending Changes** in the Tanzu Operations 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 Tanzu Operations Manager](https://docs.vmware.com/en/VMware-Tanzu-Operations-Manager/3.0/vmware-tanzu-ops-manager/install-managing_errands.html).