forked from mboldt/docs-tiledev
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathproperty-template-references.html.md.erb
1660 lines (1247 loc) · 62.5 KB
/
property-template-references.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
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
---
title: Property and template references
owner: Ops Manager
---
Use these instructions to describe your product template for your tile and learn how to edit it to include different properties.
The `metadata` subdirectory of a tile contains a product template file in `.yml` file format. The product template file specifies how the tile interface collects configurable properties from the user,
and how Tanzu Operations Manager incorporates these properties into the deployment manifest.
## <a id="product-template"></a> Product template contents
The product template, a `.yml` file in the tile's `metadata` subdirectory, includes or points to:
* **Metadata:** High-level information about your tile.
* **Dependencies:** Specifies tile dependencies.
* **Property blueprints:** Templates to represent values.
* **Form types:** Exposes property blueprints to generated forms.
* **Job types:** Configuration properties for jobs defined in the BOSH release.
* **Runtime configs:** Specifies the manifest for any number of global deployment configurations.
Use the product template use the
[<%= vars.platform_name %> example tile](https://github.com/pivotal-cf-experimental/ops-manager-example),
a functional tile that is provided by the Tanzu Operations Manager engineering team that deploys the NGINX web server.
For more information about product template configuration, see [Top-Level Properties](#top-level).
To learn how to configure your tile's forms, see [Form properties](#form-properties).
## <a id='property-values'></a> Editing the product template
You can edit the product template to designate property values.
Within the product template, there are two sections with `manifest` snippets:
* `form_types`: Defines the tile interface, or how users of your tile view and interact with different tile features.
* `job_types`: Defines the jobs that the manifest deploys, or what the tile does in response to user input, developer input, or at set intervals.
You can use special expressions in these snippets to include property values that the tile might
otherwise not use, for example, user-provided configurable properties or dynamically generated
system properties.
These special expressions take the following forms:
* Double parentheses expressions
* Triple parentheses expressions
### <a id="double-parens"></a> Double parentheses expressions
Double parentheses expressions, such as `(( PROPERTY-VALUE ))`, designate property values that Tanzu Operations Manager uses when it generates the deployment manifest. This occurs after you click **Apply Changes**.
These values include configurable properties and properties supplied by Tanzu Operations Manager.
To include these properties in a manifest snippet, use "double-parens" syntax, which consists of a variable name surrounded by two sets of parentheses, as shown in the following example:
```console
manifest: |
pizza_toppings:
peppers: (( .properties.example_selector.pizza_option.peppers.value ))
```
### <a id="triple-parens"></a> Triple parentheses expressions
Triple-parentheses expressions, such as `((( PROPERTY-VALUE )))`, designate property values that BOSH supplies when it deploys instances of the tile service. For example, CredHub credentials that are designated in triple parentheses.
To include these BOSH deploy-time properties in a manifest snippet, use "triple-parens" notation, as shown in the following example:
```console
manifest: |
credhub:
concatenated_password: prefix-((( credhub-password )))-suffix
password: ((( credhub-password )))
```
When Tanzu Operations Manager parses a product template and BOSH parses a manifest, they both use properties designated by double-parens syntax.
Some property values in a product template, such as CredHub credentials, must be filled in by BOSH on the BOSH Director VM, rather than by Tanzu Operations Manager.
Tanzu Operations Manager gets rid of the outer parentheses from these expressions and includes the resulting double-parens expressions in the manifest it generates, for BOSH to evaluate at deploy time.
For more information about tile properties, see [Referencing properties](#property-refs).
### <a id='property-refs'></a> Referencing properties
Each property is represented by two segments:
* The location of the property.
* The information from the property you want to access, commonly known as accessors.
When you use these two segments, you can write an expression as:
```
(( PROPERTY-LOCATION.ACCESSOR ))
```
Where:
* `PROPERTY-LOCATION` is the location of the property.
* `ACCESSOR` is the accessor.
#### <a id="property-location"></a> Referencing a location
The method of referencing the location of the property varies.
The following table describes the different methods of referencing a property:
| Method Name | Description |
| ----------- | ----------- |
| .properties.top_level_property | The property blueprint called "top_level_property" found in the global list of properties of the same tile. |
| .job_one.job_level_property | The property blueprint called "job_level_property" found in the list of properties of the job "job_one" of the same tile. |
| job_level_property | The property blueprint called "top_level_property" found in the same tile and job whose manifest is being evaluated. |
| ..other_product.properties.top_level_property | The property blueprint called "top_level_property" found in the global list of properties of the tile "other_product". |
| ..other_product.job_two.job_level_property | The property blueprint called "job_level_property" found in the list of properties of the job "job_one" of the tile "other_product". |
#### <a id="accessor-location"></a> Referencing an accessor
Accessors vary between property blueprint types.
The following example uses the property blueprint type `string` with its one accessor, `value`:
```console
(( .properties.example-string.value ))
```
Tanzu Operations Manager allows empty arrays in double-parentheses expressions.
For example:
```console
(( .properties.example-string.value || [] ))
```
For more information about the available properties and their accessors, see [Property Blueprint reference](#property-blueprints).
### <a id='product'></a> Product context
Product context is useful for accessing information about a tile. It can be used in a manifest using this syntax:
```console
(( ..TILE-NAME.accessor ))
```
Where `TILE-NAME` is the name of the tile.
These are the allowed accessors:
| Accessor | Description |
| -------- | ----------- |
| deployment_name | Provides the deployment name passed to BOSH for the tile |
| network_name | Provides the name of the network assigned for the tile |
| present? | Returns `true` when the tile is staged or deployed |
### <a id='dollar'></a> Dollar contexts
Outside of properties, you can also retrieve information about various configuration details of your tile and Tanzu Operations Manager.
* **$ops_manager:** Any tile uses this to obtain information about specific Tanzu Operations Manager deployments.
* **$director:** Any tile uses this to obtain information about the BOSH Director.
* **$runtime:** Any tile uses this to obtain information about the <%= vars.app_runtime_full %> tile.
* **$self:** Your own tile uses this to obtain information about its configuration.
#### <a id='ops-manager'></a> $ops_manager
The following table describes the accessors you can use to retrieve information about an Tanzu Operations Manager deployment:
| Accessor | Description |
| -------- | ----------- |
| `ca_certificate` | Provides the root CA certificate that signs the Director VM |
| `trusted_certificates` | Provides a list of certificates that the Director applies to all VMs. |
| `http_proxy` | Provides the comma-separated values (CSV) that are entered when Tanzu Operations Manager traffic is directed to an HTTP Proxy. |
| `https_proxy` | Provides the CSVs that are entered when Tanzu Operations Manager traffic is directed to an HTTPS Proxy. |
| `no_proxy` | Provides the CSVs that should not go through a proxy. |
| `instance_types_catalog` | Provides a list of all available VM types. Includes custom VM types. |
| `restricted_view_api_access_credentials` | Provides a payload for a UAA client to make read-only non-credential requests against Tanzu Operations Manager. The payload includes `uaa_client_name`, `uaa_client_secret`, `hostname`, and `port`. |
| `iaas_type` | Provides the type of the infrastructure: `google`, `aws`, `azure`, `vsphere`, or `openstack`. |
#### <a id='director'></a> $director
The following table describes the accessors you can use to retrieve information about your BOSH Director:
| Accessor | Description |
| -------- | ----------- |
| `guid` | Unique identifier for the BOSH Director |
| `deployment_ip` | Provides the IP address where the BOSH Director is deployed |
| `username` | Provides the user name for the BOSH Director VM |
| `password` | Provides the password for the BOSH Director VM |
| `ntp_servers` | Provides a list of Network Time Protocol (NTP) servers that the BOSH Director deploys |
| `ca_public_key` | Provides the public key that is used to sign the BOSH Director VM |
| `hostname` | Provides the host name for the BOSH Director VM |
| `tld` | Returns the string `bosh` as the top-level domain (TLD) of the BOSH Director |
| `metrics_server_enabled` | Returns `true` if the `system-metrics-server` job is included in the manifest.<br>For information about the job, see <a href="https://bosh.io/jobs/system-metrics-server?source=github.com/cloudfoundry/bosh-system-metrics-server-release">system-metrics-server job</a> in the BOSH documentation. |
| `bosh_metrics_forwarder_client_name` | Provides the BOSH Metrics Forwarder client name |
| `bosh_metrics_forwarder_client_secret` | Provides the BOSH Metrics Forwarder client secret |
| `metrics_server_enabled` | Exposes whether the `system-metrics-server` job of the `bosh-system-metrics-server` release is included in the BOSH Director. |
| `system_metrics_runtime_enabled` | Exposes whether the `ops_manager_system_metrics_runtime` is added to the BOSH Director. |
| `dns_release_present` | Exposes the BOSH Director configuration for `disable_dns_release` |
| `metrics_server_enabled` | Exposes the BOSH Director configuration for `metrics_server_enabled` |
#### <a id='runtime'></a> $runtime
The following table describes the accessors you can use to retrieve information about your <%= vars.app_runtime_abbr %> tile:
| Accessor | Description |
| -------- | ----------- |
| `system_domain` | Provides domain for system-level <%= vars.app_runtime_abbr %> components, such as the API, UAA, or Apps Manager. |
| `apps_domain` | Provides the default domain used by apps. |
| `system_api_url` | Provides the URL to the <%= vars.app_runtime_abbr %> API component |
| `login_url` | Provides the URL to authenticate with the <%= vars.app_runtime_abbr %> components |
| `uaa_url` | Provides the URL to the <%= vars.app_runtime_abbr %> UAA component |
| `console_url` | Provides the URL to the <%= vars.app_runtime_abbr %> Apps Manager component |
| `default_reply_to` | Provides the default reply-to email address for the system domain |
| `default_from` | Provides the default from email address of the system domain |
#### <a id='self'></a> $self
The following table describes the accessors you can use to retrieve information about your own tile:
| Accessor | Description |
| -------- | ----------- |
| `uaa_client_name` | Provides the UAA client name created for your tile to communicate with the BOSH Director. |
| `uaa_client_secret` | Provides the UAA client secret created for your tile to communicate with the BOSH Director. |
| `service_network` | Provides the name of the service network assigned to your tile. |
| `stemcell_version` | Provides the version of the stemcell your tile uses. |
### <a id='complex'></a> Complex properties: selectors and collections
Most properties are simple values, for example, strings, integers, URL addresses, or IP addresses. Others are complex, like selectors or collections.
* **Selectors**: Give you a choice of a set of inputs.
* **Collections**: Give you the ability to enter an array of values to create a hash.
![Selector showing pizza toppings.](img/selector.png)
![Collection showing record collection.](img/collection.png)
The selector and collections inputs are referenced by their selector and collection property blueprints.
Most properties are simple values, for example, strings, integers, URL addresses, or IP addresses. Selectors and collections are more complicated than simple properties because they contain manifest snippets, which are further referenced in other manifest snippets. Selectors and collections can exist alone, or nest within each other or within different parts of the manifest.
## <a id='top-level'></a> Top-level properties
The following example shows the properties that appear at the top of a product template. The definitions of each property follow this example:
```console
---
name: example-tile
product_version: "1.0-build.0"
minimum_version_for_upgrade: "1.7.0"
pivnet_filename_regex: "tile-*.pivotal"
metadata_version: "1.11"
opsmanager_syslog: true
label: 'Ops Manager: Example Tile'
description: An example tile to demonstrate Ops Manager tile author features
rank: 1
service_broker: false # Default value
stemcell_criteria:
os: ubuntu-xenial
version: "97.0"
enable_patch_security_updates: true
requires_product_versions:
- name: p-mysql
version: '~> 2.4'
releases:
- name: example-release
file: "example-release.tgz"
version: "15"
variables:
- name: credhub-password
type: password
post_deploy_errands:
- name: example-errand
pre_delete_errands:
- name: example-errand
runtime_configs:
- name: example-runtime-config
runtime_config: |
releases:
- name: os-conf
version: 15
addons:
- name: login
jobs:
- name: login-banner
release: os-conf
properties:
login_banner:
text: |
(( .properties.example_string.value )).
```
### <a id='top-name'></a> Name
* **Format:** String
* **Type:** Required
The internal name of the tile. You must keep the name of your tile consistent for migrations to function properly. Changing the name indicates the installation of a finished different tile.
### <a id='top-version'></a> product_version
* **Format:** String
* **Type:** Required
The version of the tile.
You can only import this version into Tanzu Operations Manager once. If you want to import the same tile or version, you must delete the existing one from the `/metadata` folder and delete the installation files from Tanzu Operations Manager's disk.
The version number is important for migrations.
For more information, see [Upgrading Tiles](./tile-upgrades.html).
### <a id='top-min-version'></a> minimum\_version\_for\_upgrade
* **Format:** String
* **Type:** Required
You must set a minimum version for upgrading to your current tile version. The following example shows a current tile version of v1.7 that only upgrades from a v1.6.x version of the same tile:
```
- product_version: 1.7.0.0
minimum_version_for_upgrade: 1.6.0.0
```
### <a id='top-metadata'></a> metadata_version
* **Format:** String
* **Type:** Required
The version of the schema of the product template, the file that this documentation describes.
If you bump the version number, it activates new properties that are not present in an older `metadata_version`. It can also require you to restructure the product template to conform to the new `metadata_version`.
The `metadata_version` corresponds to a major or minor release of Tanzu Operations Manager. Tanzu Operations Manager can accept a tile with a `metadata_version` that is older than the Tanzu Operations Manager version, but Tanzu Operations Manager cannot accept a
tile with a `metadata_version` that is newer than the Tanzu Operations Manager version. A best practice is to set the `metadata_version` to be the same as the oldest version of
Tanzu Operations Manager that the tile version supports.
### <a id='top-label'></a> Label
* **Format:** String
* **Type:** Optional
The label that is used in the tile when it appears in the Tanzu Operations Manager Dashboard.
### <a id='top-description'></a> Description
* **Format:** String
* **Type:** Optional
A description of the tile.
### <a id='top-rank'></a> Rank
* **Format:** Integer
* **Type:** Optional
The order in which a tile appears on the dashboard. The BOSH Director always appears at rank 100.
For your tile to appear to the right of BOSH Director, you must set this value to an integer less than 100. Set it to 1.
If all tiles have the same rank, Tanzu Operations Manager sorts them alphabetically.
### <a id='top-pivnet_filename_regex'></a> pivnet_filename_regex
* **Format:** String
* **Type:** Optional
This regular expression allows the Tanzu Operations Manager VMware Tanzu Network integration to pull a specific tile file. You must do this when there are multiple tiles with the same product slug.
### <a id='top-service-broker'></a> service_broker
* **Format:** Boolean
* **Type:** Optional, default `false`
Set `service_broker` to `true` for on-demand service brokers. When you set `service_broker` to `true` it:
* Activates the service network selector property type.
* Requires you to select a service network during tile configuration. You can reference the selected service network with `(( $self.service_network ))`.
* Include a UAA client for the service to use. Tile authors can reference the UAA client credentials with `(( $self.uaa_client_name ))` and `(( $self.uaa_client_secret ))`.
### <a id='top-stemcell-criteria'></a> stemcell_criteria
* **Format:** Hash
* **Type:** Required
With the `enable_patch_security_updates` property, you can automatically use the latest patched version of a stemcell. This key is set to `true` by default. For tiles using static compilations, you can deactivate this feature. This feature increases security by automatically using the latest patched version of a stemcell. However, you might experience longer than expected upgrade times.
For example:
```
stemcell_criteria
os: ubuntu-xenial
version: "97.0"
enable_patch_security_updates: false
```
You must set the `enable_patch_security_updates` property to `true`. If you set the property to `false`, your tile does not receive security patches through automatic stemcell updates.
You do not specify which IaaS the stemcell targets. This keeps your product template IaaS agnostic so that one product template can be deployed on any IaaS.
For a list of stemcells, including OS and version, see the [BOSH](https://bosh.io/) website.
For more information, see [Floating Stemcells](https://docs.vmware.com/en/VMware-Tanzu-Operations-Manager/3.0/vmware-tanzu-ops-manager/install-understanding-stemcells.html).
### <a id='top-additional-stemcells-criteria'></a> additional_stemcells_criteria
* **Format:** Array of hashes
* **Type:** Optional
Stemcell criteria can be selected using the `stemcell_selector` property type. These stemcells are listed, in addition to the configured stemcell, with `stemcell_criteria`. After you select a stemcell, it becomes required.
For more information about the `stemcell_selector` property type, see [stemcell_selector](#stemcell-selector).
For example:
```
additional_stemcells_criteria:
- os: ubuntu-xenial
version: 97.0
enable_patch_security_updates: false
- os: windows2016
version: 1709.1
```
### <a id='top-requires'></a> requires_product_versions
* **Format:** Array of hashes
* **Type:** Optional
A list of tile dependencies. If the required tile is not present in the <%= vars.platform_name %> installation, Tanzu Operations Manager lists the needed dependencies and does not install your tile until the dependencies are satisfied.
Supported restriction operators are `=`, `!=`, `>`, `<`, `>=`, `<=`, and `~>`.
The following keys are supported:
- `name`: The name of the tile required by your tile. This is a required key.
- `version`: The version range required by your tile. This is a required key.
- `optional`: This is an optional key that defaults to false.
<p class="note caution">
<span class="note__title">Caution</span>
Declared dependencies are required in Tanzu Operations Manager v2.7 and earlier.
</p>
For example:
```
requires_product_versions:
- name: tile-one
version: '> 1.2'
- name: tile-two
version: '~> 2.3.4'
optional: true
```
For more information about required and optional dependencies, see [Dependencies](tile-structure.html#dependencies) in _How Tiles Work_.
### <a id='top-release'></a> releases
* **Format:** Array of hashes
* **Type:** Required
The list of releases contained in your tile's releases directory.
The version of the release must be exactly the same as the version contained in the release.
Each release requires the following keys:
* `name`
* `file`
* `version`
### <a id='top-variables'></a> Variables
* **Format:** Array of hashes
* **Type:** Optional
A list of variables, that are generated after a deploy succeeds.
You can reference variables in a manifest snippet using triple-parentheses expressions.
Each release requires the following keys:
* `name`
* `type`
### <a id='top-post-deploy'></a> post_deploy_errands
* **Format:** Array of hashes
* **Type:** Optional
A list of errands that run after a deploy succeeds.
Set the `run_post_deploy_errand_default:` property to `on` or `off` to set the default for the errand's run rule selector in Tanzu Operations Manager.
For more information, see [Errands](./tile-errands.html). If this property is not supplied, the selector defaults to `On`.
### <a id='top-pre-delete'></a> pre_delete_errands
* **Format:** Array of hashes
* **Type:** Optional
A list of errands that run before a deployment is deleted.
Set the `run_pre_delete_errand_default:` property to `on` or `off` to set the default for the errand's run rule selector in Tanzu Operations Manager. If you do not specify this property, the selector defaults to `On`.
For more information, see [Errands](./tile-errands.html).
### <a id='top-runtime-configs'></a> runtime_configs
* **Format:** Array of hashes
* **Type:** Optional
These are keys that define global deployment configurations. For more information, see [Managing Runtime Configs](./runtime-config.html).
### <a id='top-verifier'></a> install_time_verifiers
* **Format:** Array of hashes
* **Type:** Optional
Install-time verifiers confirm that properties for external services are set correctly.
Install-time verifiers run in Tanzu Operations Manager before the changes are applied.
You can correct invalid properties before you deploy.
For example, `Verifiers::MysqlDatabaseVerifier` checks that MySQL database properties are valid by
using the properties to connect to the MySQL database. If the properties are invalid,
the install-time verifier informs you.
Each install-time verifier supports the following keys:
* `name`: The type of verifier. The value must be one of the verifiers listed in the following table.
* `properties`: A mapping of verifier inputs to either property references or static values.
The required properties for each verifier are listed in the table that follows.
* `ignorable`: If this key is set to `false`, you cannot click **Apply Changes** until the verification errors are resolved.
If this key is set to `true`, you can ignore the warning message and click **Apply Changes**.
This key is set to `false` by default.
* `run_on`: Determines when to run the verifier. Valid values include `'always'` and `'major_or_minor_upgrades'`.
Defaults to `'always'`.
For information about how you can manage and view verifiers,
see [Managing Tanzu Operations Manager Verifiers](https://docs.vmware.com/en/VMware-Tanzu-Operations-Manager/3.0/vmware-tanzu-ops-manager/install-granular-verifier-control.html).
The following table lists the available install-time verifiers:
<table class="table">
<thead>
<tr>
<th width="250">
Verifier Type
</th>
<th>
Verifies that...
</th>
<th width="210px">
Properties
</th>
</tr>
</thead>
<tr>
<td>
<code>Verifiers::BlobstoreVerifier</code>
</td>
<td>
the specified AWS s3 bucket exists and is accessible.
<td>
<ul>
<li><code>access_key_id</code></li>
<li><code>bucket_name</code></li>
<li><code>secret_access_key</code></li>
<li>(Optional) <code>signature_version</code></li>
<li>(Optional) <code>region</code></li>
<li>(Optional) <code>use_path_style</code></li>
<li>(Optional) <code>endpoint</code></li>
<li>(Optional) <code>use_path_style</code></li>
<li>(Optional, only available after Metadata version 2.10.1, shipped in Tanzu Operations Manager v2.10.21) <code>ca_cert</code></li>
</ul>
</td>
</tr>
<tr>
<td>
<code>Verifiers::LDAPBindVerifier</code>
</td>
<td>
the specified LDAP server exists and that the provided credentials are valid.
Multiple LDAP servers can be verified if the <code>url</code> property is a space-separated list of server URLs.
<td>
<ul>
<li><code>url</code></li>
<li><code>credentials</code></li>
</ul>
</td>
</tr>
<tr>
<td>
<code>Verifiers::MysqlDatabaseVerifier</code>
</td>
<td>
the specified MySQL server exists and that the provided credentials and database are valid.
</td>
<td>
<ul>
<li><code>database</code></li>
<li><code>host</code></li>
<li><code>password</code></li>
<li><code>port</code></li>
<li><code>username</code></li>
<li>(Optional) <code>tls_enabled</code></li>
<li>(Optional) <code>tls_ca</code></li>
<li>(Optional) <code>tls_certificate</code></li>
<li>(Optional) <code>tls_private_key</code></li>
</ul>
</td>
</tr>
<tr>
<td>
<code>Verifiers::SmtpAuthenticationVerifier</code>
</td>
<td>
the specified SMTP server exists and that the provided credentials are valid.
</td>
<td>
<ul>
<li><code>credentials</code></li>
<li><code>address</code></li>
<li><code>port</code></li>
<li><code>helo_domain</code></li>
<li><code>authentication</code></li>
<li><code>enable_starttls_auto</code></li>
</ul>
</td>
</tr>
<tr>
<td>
<code>Verifiers::SsoUrlVerifier</code>
</td>
<td>
the specified SSO server exists.
</td>
<td>
<ul>
<li><code>url</code></li>
</ul>
</td>
</tr>
<tr>
<td>
<code>Verifiers::StaticIpsVerifier</code>
</td>
<td>
all requested static IPs fall within the subnet assigned to the job. For more information, see <code>static_ips</code> in <a href="#job-types">Job Types</a>.
</td>
<td>
<em>(none)</em>
</td>
</tr>
<tr>
<td>
<code>Verifiers::WildcardDomainVerifier</code>
</td>
<td>
the specified domain resolves using DNS.
</td>
<td>
<ul>
<li><code>domain</code></li>
</ul>
</td>
</tr>
<tr>
<td>
<code>Verifiers::VsphereConfigurationVerifier</code>
</td>
<td>
the vSphere configuration is valid.
</td>
<td>
<ul>
<li><code>vcenter_hosturl</code></li>
<li><code>vcenter_credentials</code></li>
<li><code>datacenter</code></li>
<li><code>datastore_pattern</code></li>
</ul>
</td>
</tr>
<tr>
<td>
<code>Verifiers::HttpSuccessVerifier</code>
</td>
<td>
the specified endpoint returns successfully. If <code>must_match_regex</code> expression is provided, it must be wrapped in forward slashes. For example, <code>/.*/</code>. The verifier ensures that the response body matches the regular expression.
</td>
<td>
<ul>
<li><code>host</code></li>
<li><code>port</code></li>
<li><code>path</code></li>
<li><code>scheme</code></li>
<li>(Optional) <code>must_match_regex</code></li>
<li>(Optional) <code>skip_ssl_verification</code></li>
</ul>
</td>
</tr>
</table>
The following is an example of a `install_time_verifiers` section:
```
install_time_verifiers:
- ignorable: true
name: Verifiers::WildcardDomainVerifier
properties:
domain: .cloud_controller.system_domain
- name: Verifiers::SsoUrlVerifier
properties:
url: .properties.uaa.saml.sso_url
- ignorable: true
name: Verifiers::BlobstoreVerifier
properties:
access_key_id: .properties.system_blobstore.external.access_key
bucket_name: .properties.system_blobstore.external.buildpacks_bucket
endpoint: .properties.system_blobstore.external.endpoint # Optional. Defaults to AWS
region: .properties.system_blobstore.external.region # Optional. Defaults to default IaaS setting
secret_access_key: .properties.system_blobstore.external.secret_key
signature_version: .properties.system_blobstore.external.signature_version
use_path_style: .properties.system_blobstore.external.use_path_style # Optional. Defaults to false
- ignorable: true
name: Verifiers::MysqlDatabaseVerifier
properties:
database: "static-database-name"
host: .properties.system_database.external.host
password: .properties.system_database.external.account_password
port: 1234
user name: example-dbuser
- ignorable: true
name: Verifiers::HttpSuccessVerifier
run_on: major_or_minor_upgrades
properties:
host: .properties.external_host
scheme: https
port: 443
path: /verify
```
### <a id='top-icon-image'></a> icon_image
* **Format:** Base64 Image
* **Type:** Required
This is the icon that appears on the tile in the Tanzu Operations Manager Installation Dashboard.
### <a id="top-bas-url"></a> base_releases_url
* **Format:** String
* **Type:** Optional
A publicly available URL that is passed to BOSH to download your releases during installation. If you use this text box, BOSH Director must have internet connectivity. This allows you to package your tile without releases, decreasing the tile size.
### <a id="syslog-flag"></a> opsmanager_syslog
* **Format:** Boolean
* **Type:** Optional, default `false`
Set `opsmanager_syslog` to `true` to opt in to the Tanzu Operations Manager provided syslog form. If you opt in, you do not need provide the Syslog BOSH release for your tile.
For more information about the Syslog BOSH release, see the [Syslog BOSH Release](https://github.com/cloudfoundry/syslog-release) repository on GitHub.
For more information about migrating an existing form to the Tanzu Operations Manager provided syslog form, see [Migrating existing Syslog configuration to Tanzu Operations Manager](./migrating-syslog-configuration.html).
## <a id='form-properties'></a> Form properties
Each form type you write is composed of form properties. Form properties dictate the structure of the form fields that appear in the Tanzu Operations Manager UI. The `name` of each form appears on the left-hand side as navigational tabs.
Form properties reference `property_blueprints`. Property blueprints define each text box's data type.
For a corresponding example to the `form_types` example that follows, see [property_blueprints](#property-blueprints).
The following is an example of the properties that appear in the `form_types` section of a product template:
```
form_types:
- name: example-form
label: Configurable Properties
description: All the properties that you can configure!
markdown: |
## I am markdown, hear me _roar_.
![](http://placekitten.com/g/400/200)
Things to do:
1. Learn [markdown](https://daringfireball.net/projects/markdown/).
1. ...
1. Profit!
property_inputs:
- reference: .web_server.example_string
label: Example string
description: 'Configure a property of type string'
- reference: .web_server.example_string_with_placeholder
label: Example string containing Placeholder text
description: 'Optional text box. Configuration not necessary'
placeholder: 'Ghost text. Spooky!'
- reference: .web_server.example_migrated_integer
label: Example integer
description: 'Configure a property of type integer'
- reference: .web_server.example_boolean
label: Example boolean
description: 'Configure a property of type boolean'
- reference: .web_server.example_dropdown
label: Example dropdown
description: 'Configure a property of type dropdown'
- reference: .web_server.example_domain
label: Example domain
description: 'Configure a property of type domain'
- reference: .web_server.example_wildcard_domain
label: Example wildcard_domain
description: 'Configure a property of type wildcard_domain'
- reference: .web_server.example_string_list
label: Example string_list
description: 'Configure a property of type string_list'
- reference: .web_server.example_text
label: Example text
description: 'Configure a property of type text (setting to "magic value" causes the web server job instance count to go to 0)'
- reference: .web_server.example_ldap_url
label: Example ldap_url
description: 'Configure a property of type ldap_url'
- reference: .web_server.example_email
label: Example email
description: 'Configure a property of type email'
- reference: .web_server.example_http_url
label: Example http_url
description: 'Configure a property of type http_url'
- reference: .web_server.example_ip_address
label: Example ip_address
description: 'Configure a property of type ip_address'
- reference: .web_server.example_ip_ranges
label: Example ip_ranges
description: 'Configure a property of type ip_ranges'
- reference: .web_server.example_multi_select_options
label: Example multi_select_options
description: 'Configure a property of type multi_select_options'
- reference: .web_server.example_network_address_list
label: Example network_address_list
description: 'Configure a property of type network_address_list (this property was marked with freeze_on_deploy, and so cannot be edited after changes are first applied)'
- reference: .web_server.example_network_address
label: Example network_address
description: 'Configure a property of type network_address'
- reference: .web_server.example_port
label: Example port
description: 'Configure a property of type port'
- reference: .web_server.example_smtp_authentication
label: Example smtp_authentication
description: 'Configure a property of type smtp_authentication'
- reference: .web_server.client_certificate
label: Example certificate
description: 'Configure a certificate'
verifiers:
- name: Verifiers::WildcardDomainVerifier
properties:
domain: .web_server.example_wildcard_domain
- name: Verifiers::StaticIpsVerifier
properties:
domain: .web_server.example_ip_address
```
### <a id='form-name'></a> Name
* **Format:** String
* **Type:** Required
The internal name of the form.
### <a id='form-label'></a> Label
* **Format:** String
* **Type:** Required
The label of the form as it appears as a link on the left hand side of each form.
### <a id='form-description'></a> Description
* **Format:** String
* **Type:** Optional
The description of the form. Appears at the top of the form as a header.
### <a id='form-markdown'></a> Markdown
* **Format:** Markdown
* **Type:** Optional
Provide a block of markdown to display at the top of the form, including image support. Use this property to document the tile and provide explanations or references.
### <a id='form-property-inputs'></a> property_inputs
* **Format:** Array of hashes
* **Type:** Required
References to properties defined in the `property_blueprints` section of the product template.
### <a id='verifiers'></a> Verifiers
Verifiers confirm that properties are set correctly in forms.
If a verifier displays a warning, the form can still be saved and the warning ignored.
Verifiers are similar to install-time verifiers
except that they run after a form is saved and not before you click **Apply Changes**.
Verifiers do not block deployments and only inform you that the properties you set are invalid.
To have a verifier run when a form is saved and before you click **Apply Changes**,
add the verifier to both the `verifiers` and `install_time_verifiers` sections.
For information about how you can manage and view verifiers,
see [Managing Tanzu Operations Manager Verifiers](https://docs.vmware.com/en/VMware-Tanzu-Operations-Manager/3.0/vmware-tanzu-ops-manager/install-granular-verifier-control.html).
For information about how verifiers are configured, see [install\_time\_verifiers](#top-verifier).
The following is an example of a `verifiers` section:
```
form_types:
- name: example-form
label: Configurable Properties
description: All the properties that you can configure!
property_inputs:
- reference: .web_server.example_wildcard_domain
label: Example wildcard_domain
description: 'Configure a property of type wildcard_domain'
- reference: .web_server.static_ips
label: Example ip_address
description: 'Configure a property of type ip_address'
verifiers:
- name: Verifiers::WildcardDomainVerifier
properties:
domain: .web_server.example_wildcard_domain
- name: Verifiers::StaticIpsVerifier
- name: Verifiers::MysqlDatabaseVerifier
properties:
database: "static-database-name"
host: .properties.example-database-host
port: 1234
user name: example-dbuser
```
You can specify either a tile property reference or a static value for a form verifier. In the preceding example, `Verifiers::MysqlDatabaseVerifier` uses a tile property reference for the database host and static values for the database name, port number, and user name.
### <a id='form-placeholder'></a> Placeholder
* **Format:** String
* **Type:** Optional
Specify placeholder text for a text box. The text appears in light gray to show an example value for the user. The text disappears when you type in the text box and reappears if you leave the text box empty.
The `placeholder` attribute displays for the following form types:
* `string`
* `integer`
* `domain`
* `wildcard_domain`
* `string_list`
* `text`
* `ldap_url`
* `email`
* `http_url`
* `ip_address`
* `ip_ranges`
* `network_address_list`
* `network_address`
* `port`
## <a id='job-types'></a> Job types
The following is an example of the `job_types` section that appears in a product template.
This section defines the jobs that end up in a BOSH manifest. Those jobs are defined in your BOSH release.
Jobs require many different settings to function properly. That is the core of what Tanzu Operations Manager does for you: Tanzu Operations Manager asks you to designate values for those settings and generates a manifest based on what you specify.
Tanzu Operations Manager does not require tile authors to provide `vm_credentials` in the `property_blueprints` for each `job_type`. This is because `vm_credentials` are generated automatically. You can find them in the release manifest.
Tanzu Operations Manager ignores <code>static_ip</code> and <code>dynamic_ip</code> keys. To configure the static IPs of a <code>job_type</code>, create a property blueprint with <code>name: static_ips</code> and <code>type: ip_ranges</code>.<br><code>static_ips</code> is a special keyword that Tanzu Operations Manager uses to find static IPs and pass them to the BOSH manifest. For more information about <code>ip_ranges</code>, see <a href="#ip-ranges">ip_ranges</a>.