Product Template Reference
This document defines the separate pieces of a product template. For the purpose of explanation we will use the v1.7 example product tile, a functional tile provided by the Ops Manager engineering team that deploys the NGINX web server.
The product template includes the following sections:
- Metadata: high level information about your tile
- Dependencies: how to specify product dependencies
- Property Blueprints: the building blocks of representing values
- Form Types: exposing property blueprints into generated forms
The following is an example of the properties that appear at the top of a product template. Following this example are definitions of each property.
--- name: example-product product_version: "22.214.171.124-alpha" metadata_version: "1.7" label: 'Ops Manager: Example Product' description: An example product to demonstrate Ops Manager product-author features rank: 1 stemcell_criteria: os: ubuntu-trusty version: "3191" # BOSH stemcell should match Ops Manager with same version releases: - name: example-release file: example-release-11.tgz version: "11" post_deploy_errands: - name: example-errand pre_delete_errands: - name: example-errand icon_image: iVBORw0KGgoAAAANSUhEUgAAAUIAAADcCAYAAAAFtqgbAAAAAXNSR0IArs4c6QAAAAlwSFl...
String. Required. The internal name of the product. You must keep the name of your product consistent for migrations to function properly. Changing the name indicates the installation of a completely different product.
String. Required. The version of the product. At present you can only import this version into Ops Manager once. If you intend to import the same product / version, you must delete the existing one from the /metadata folder and delete the installation files from Ops Manager’s disk. The version number is important for migrations.
String. Optional. Pivotal recommends that you set a minimum version for upgrading to your current product version. This example shows a current product version of v1.7 that only upgrades from a v1.6.x version of the same product:
- product_version: 126.96.36.199 minimum_version_for_upgrade: 188.8.131.52
String. Required. The versioned structure of the product template (the file you are editing). Changing the version number can unlock new properties, and also break properties that changed from previous versions. The metadata version does not always correlate to Ops Manager version number and depends on what, or if, new metadata properties were introduced.
String. Optional. The label that appears in the product tile when it displays in the Ops Manager Dashboard.
String. Optional. A description of the product. This is not currently used but may be displayed in a future version of Ops Manager.
Integer. Required. The order in which a product tile appears on the dashboard. The Ops Manager Director always appears at rank 100. For your product to appear to the right of Ops Manager Director (preferable) you must set this value to an integer less than 100. It is recommended that you set it to 1. Ops Manager will sort tiles alphabetically if all tiles have the same rank. This is a known weak point and will be improved in a future version of Ops Manager.
Hash. Required. Refer to the BOSH hub for a list of stemcells, including os and version. Notice that 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. At the time of this writing, none of the BOSH stemcells require a Cloud Provider Interface (CPI). This is expected to change in a future release of BOSH.
enable_patch_security_updates allows you to automatically use the latest patched version of a stemcell. This is by default set to
true. For products using static compilations, you can disable this feature. If you set the property to
false, your product will not receive security patches through automatic stemcell updates.
stemcell_criteria enable_patch_security_updates: true
This feature increases security by automatically using the latest patched version of a stemcell. However, operators may experience longer than expected upgrade times. Review the Understanding Floating Stemcells topic for more information.
Array of Hashes. Required. The list of releases contained in your product’s releases directory. The version of the release must be exactly the same as the version contained in the release (BOSH releases are versioned and signed by BOSH).
Array of Hashes. Optional. A list of errands that will run after a deploy succeeds. See Lifecycle Errands.
Array of Hashes. Optional. A list of errands that will run before a deployment is deleted. See Lifecycle Errands.
The following is an example of the properties that appear in the form_types section of a product template. These forms appear on the left hand side, as links, after a user clicks on the tile itself.
As shown in a later section, form properties reference property_blueprints for the definition of the type of data (url, IP address, list, etc.) being saved. Form properties are themselves referenced in the manifest section of the job_types section, which will also be explained later in this document. The eventual purpose of these properties is to hydrate a BOSH manifest, which Ops Manager generates on the user’s behalf.
Following this example are definitions of each property.
form_types: - name: example-form label: Configurable Properties description: All the properties that you can configure! markdown: | ## This is markdown. ![Alt text](http://placekitten.com/g/400/200) Things to do: 1. Learn [markdown](https://daringfireball.net/projects/markdown/). 1. ... 1. Describe your tile. 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 field. Configuration not necessary' placeholder: 'Ghost text. Spooky!' - name: example_collections_form label: 'Collection example' description: 'A collection example form' property_inputs: - reference: .properties.example_collection label: 'Albums collection' description: 'The albums' property_inputs: - reference: album label: 'Name of the Album' description: 'ex Graceland' - reference: artist label: 'Name of the Artist' description: 'ex Paul Simon' - reference: explicit label: 'Explicit?' description: '$#!%&' - name: example_selector_form label: 'Selector Example' description: 'A selector example form' property_inputs: - reference: .properties.example_selector label: 'Food Choices' selector_property_inputs: - reference: .properties.example_selector.pizza_option label: 'Pizza' property_inputs: - reference: .properties.example_selector.pizza_option.pepperoni label: 'Add Pepperoni' - reference: .properties.example_selector.pizza_option.pineapple label: 'Add Pineapple' - reference: .properties.example_selector.pizza_option.other_toppings label: 'Other toppings' - reference: .properties.example_selector.filet_mignon_option label: 'Filet Mignon' property_inputs: - reference: .properties.example_selector.filet_mignon_option.rarity_dropdown label: 'How rare?'
String. Required. The internal name of the form.
String. Required. The label of the form as it appears as a link on the left hand side of each form.
String. Optional. The description of the form. Appears at the top of the form as a header.
Markdown. Optional. Provide a block of markdown to display at the top of the form. Includes image support. You can use this property to document the tile and provide explanations or references.
Array of Hashes. Required. References to properties defined in the property_blueprints section of the product template.
String. Optional. Specify placeholder text for a field. The text appears in light gray to show an example value for the user. The text disappears when the user types in the field, and reappears if the user leaves the field empty.
placeholder attribute displays for the following form types:
Most properties are simple values such as strings, integers, url addresses, or IP addresses. Others are complex, such as selectors or collections.
Selectors are a means of giving the user a choice of a set of inputs. Collections are a means of giving the user the ability to enter an array of values to create a hash.
Selectors appear as follows:
Collections appear as follows:
The following is an example of the property_blueprints that appear in a product template. These blueprints define anything that will eventually end up in the BOSH manifest generated by Ops Manager.
Note that one of these blueprints references a migrated value, which came from the Example Product v1.6 using migrations.
property_blueprints: - name: example_string type: string configurable: true default: 'Hello world' constraints: - must_match_regex: '^[^!@#$%^&*()]*$' error_message: 'This name cannot contain capital digits.' - must_match_regex: '^[^0-9]*$' error_message: 'This name cannot contain digits.' - name: example_migrated_integer type: integer configurable: true default: 1 - name: example_collection type: collection configurable: true property_blueprints: - name: album type: string - name: artist type: string - name: explicit type: boolean default: - album: Christmas Carols artist: Ops Manatee explicit: true - name: example_selector type: selector configurable: true default: Pizza option_templates: - name: pizza_option select_value: Pizza named_manifests: - name: my_snippet manifest: | pizza_toppings: pepperoni: (( .properties.example_selector.pizza_option.pepperoni.value )) pineapple: (( .properties.example_selector.pizza_option.pineapple.value )) other: (( .properties.example_selector.pizza_option.other_toppings.value )) property_blueprints: - name: pepperoni type: boolean configurable: true - name: pineapple type: boolean configurable: true - name: other_toppings type: string configurable: true optional: true - name: filet_mignon_option select_value: Filet Mignon named_manifests: - name: my_snippet manifest: | rarity: (( .properties.example_selector.filet_mignon_option.rarity_dropdown.value )) property_blueprints: - name: rarity_dropdown type: dropdown_select configurable: true default: rare options: - name: rare label: 'Rare' - name: medium label: 'Medium' - name: well-done label: 'Well done'
No property will be viewable in a form if unless
configurable is set to
true. Rather than giving the user the ability to enter a value, the value is generated by Ops Manager.
Regular Expression. Optional. Create a validator that runs on the form save event. If the user input does not match the
must_match_regex constraint, the form displays the specified
must_match_regex constraints for a single property blueprint are evaluated in the order listed.
Many of these properties are strings, but can be used with validators in order to check that the user typed in the correct format for a url, IP, address, domain, etc.
A boolean. Viewed as a checkbox.
A list of options. The user chooses one viewed as an HTML select box.
A second, third, fourth, etc level domain.
A domain with a wildcard in front of it. Example:
A string. Appears as an HTML textarea.
A url prefaced by
An email address.
A range of IP addresses, with dashes and commas allowed. Example:
An integer representing a network port.
A single IP address or domain. Example:
A list of IP addresses or domains. Example:
Generated Properties (can also be configurable)
The following properties are configurable, but can also be generated by Ops manager if configurable is false, or the configurable key is omitted. The exceptions are the uuid and salted credentials properties, which are never configurable.
An RSA certificate.
An RSA private key.
Username and password created using a non-reversible hash algorithm.
Username and password.
A random string or password.
A universal unique identifier.
Complex Properties (Selectors and Collections)
The selector and collections inputs are referenced by their selector and collection property blueprints. These are more complicated than simple properties in that they contain manifest snippets, which are further referenced in other manifest snippets. We will learn about manifest snippets in the next section.
The following is an example of the job_types section that appear 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 in order to function properly, and that is the crux of what Ops Manager does for you: it asks a user for values to those settings, and generates a manifest based on what was entered.
Ops Manager does not require product authors to provide
vm_credentials in the
property_blueprints for each
vm_credentials are generated automatically, and you can find them in the release manifest.
job_types: - name: web_server resource_label: Web Server templates: - name: web_server release: example-release - name: time_logger release: example-release release: example-release static_ip: 1 dynamic_ip: 0 max_in_flight: 1 single_az_only: true instance_definition: name: instances type: integer configurable: true default: 1 constraints: max: 1 zero_if: property_reference: '.web_server.example_text' property_value: 'magic value' resource_definitions: - name: ram type: integer configurable: true default: 1024 - name: ephemeral_disk type: integer configurable: true default: 2048 - name: persistent_disk type: integer configurable: true default: 1024 constraints: min: 1024 - name: cpu type: integer configurable: true default: 1 property_blueprints: - name: static_ips type: ip_ranges configurable: true optional: true - name: generated_rsa_cert_credentials type: rsa_cert_credentials - name: generated_rsa_pkey_credentials type: rsa_pkey_credentials - name: generated_salted_credentials type: salted_credentials - name: generated_simple_credentials type: simple_credentials - name: generated_secret type: secret - name: generated_uuid type: uuid - name: example_string_with_placeholder type: string configurable: true optional: true placeholder: 'Configure me!' - name: example_string type: string configurable: true default: 'Hello world' constraints: - must_match_regex: '^[^!@#$%^&*()]*$' error_message: 'This name cannot contain capital digits.' - must_match_regex: '^[^0-9]*$' error_message: 'This name cannot contain digits.' - name: example_migrated_integer type: integer configurable: true default: 1 - name: example_boolean type: boolean configurable: true default: true - name: example_dropdown type: dropdown_select configurable: true default: kiwi options: - name: kiwi label: 'label for kiwi' - name: lime label: 'label for lime' - name: avocado label: 'label for avocado' - name: example_domain type: domain configurable: true default: www.example.com - name: example_wildcard_domain type: wildcard_domain configurable: true default: 'example.com' - name: example_string_list type: string_list configurable: true default: 'a,list,of,strings' - name: example_text type: text configurable: true default: 'some_text' - name: example_ldap_url type: ldap_url configurable: true default: 'ldap://example.com' - name: example_email type: email configurable: true default: email@example.com - name: example_http_url type: http_url configurable: true default: 'http://www.example.com' - name: example_ip_address type: ip_address configurable: true default: '192.168.0.1' - name: example_ip_ranges type: ip_ranges configurable: true default: '184.108.40.206-220.127.116.11,18.104.22.168-22.214.171.124' - name: example_multi_select_options type: multi_select_options configurable: true default: ['earth', 'jupiter'] options: - name: mercury label: 'label for mercury' - name: venus label: 'label for venus' - name: earth label: 'label for earth' - name: mars label: 'label for mars' - name: jupiter label: 'label for jupiter' - name: saturn label: 'label for saturn' - name: uranus label: 'label for uranus' - name: neptune label: 'label for neptune' - name: example_network_address_list type: network_address_list configurable: true default: '126.96.36.199,example.com,foo.bar.example.com' - name: example_network_address type: network_address configurable: true default: '188.8.131.52' - name: example_port type: port configurable: true default: 1111 - name: example_smtp_authentication type: smtp_authentication configurable: true default: plain - name: client_certificate type: ca_certificate configurable: true optional: true manifest: | generated: root_rsa_certificate: (( $ops_manager.ca_certificate )) rsa_cert_credentials: public_key_pem: (( generated_rsa_cert_credentials.public_key_pem )) cert_and_private_key_pems: (( generated_rsa_cert_credentials.cert_and_private_key_pems )) rsa_pkey_credentials: public_key_pem: (( generated_rsa_pkey_credentials.public_key_pem )) private_key_pem: (( generated_rsa_pkey_credentials.private_key_pem )) public_key_openssh: (( generated_rsa_pkey_credentials.public_key_openssh )) public_key_fingerprint: (( generated_rsa_pkey_credentials.public_key_fingerprint )) salted_credentials: sha512_hashed_password: (( generated_salted_credentials.sha512_hashed_password )) identity: (( generated_salted_credentials.identity )) salt: (( generated_salted_credentials.salt )) password: (( generated_salted_credentials.password )) simple_credentials: identity: (( generated_simple_credentials.identity )) password: (( generated_simple_credentials.password )) secret: (( generated_secret.value )) uuid: (( generated_uuid.value )) configured: string: (( example_string.value )) integer: (( example_migrated_integer.value )) ... record_collection: (( .properties.example_collection.value ||  )) selector: (( .properties.example_selector.selected_option.parsed_manifest(my_snippet) )) ops_manager_provided_accessors: name: (( name )) ram: (( ram )) ephemeral_disk: (( ephemeral_disk )) persistent_disk: (( persistent_disk )) instances: (( instances )) availability_zone: (( availability_zone )) first_ip: (( first_ip )) ips: (( ips )) ips_by_availability_zone: (( ips_by_availability_zone )) bosh_job_partition_stats: (( bosh_job_partition_stats ))
String. Required. The name of the job as it will be created in the Ops Manager generated BOSH manifest.
String. Required. The label of the job as it will appear in the resources page of the tile.
Array of Hashes. Required. Each element has the following fields:
The name of the job template to use. Required.
The name of the release the template is from. Required.
A YAML string defining BOSH links this job consumes. Optional.
A YAML string defining BOSH links this job provides. Optional.
This is a BOSH feature (creating jobs from different releases). See the BOSH documentation for more information.
String. Required. The name of the BOSH release contained in your product archive (.pivotal file).
Boolean. Required. Sets whether the BOSH job should have a static or dynamic IP. Static IPs are set by the user, and reserved, while Dynamic IPs are set by BOSH. Both are, in effect, static, in that they should not change between deployments.
Boolean. Required. Set the opposite of static_ip. This will eventually be eliminated as a property as it is obviously redundant and unnecessary.
Boolean. Required. You can give users control of balancing jobs across availability zones (AZs) by setting
false. To limit a job to a single AZ, set this to
Integer. Required. A BOSH setting that controls the number of instances of this job that BOSH will deploy in parallel.
Array of Hashes. Required. A set of resource settings for the job along with max and min constraints, defaults, and whether or not the user can configure (change) the setting. The resources that can be set are:
Note: If you set the
default property for
0, users cannot edit this value and the Resource Config page in Ops Mananger displays None under the persistent disk field.
Hash. Required. The number of default instances for a job along with max, min, odd, and the ability to decrease sizing after deploy constraints.
If your product uses an external service that performs the same job as a service in Elastic Runtime, you can reduce resource usage by setting the instance count of a job to
0 with the
zero_if property. For example, your product uses Amazon Relational Database Service (RDS) instead of MySQL, which is the default system database for Elastic Runtime. Set
property reference to
property value to
magic value to change the instance counts of all MySQL jobs to
Text Snippet, prefaced by pipe symbol: |. Optional. A BOSH manifest will be created by Ops Manager. The sections of that manifest will include each job, and the properties for that job. These properties come directly from the manifest snippet here, and use a syntax known as “double-parens” which consists of a variable name surrounded by two sets of parentheses.
The double-parens syntax will be evaluated when a user clicks the Apply Changes button in Ops Manager. A manifest is created and the double-parens variables are evaluated. The values, either entered by a user, or generated by Ops Manager, are dynamically inserted in place of the double-parens references.
Selector Manifest Snippets
Selector snippets are evaluated twice. As you saw in the property_blueprint, the selector has a manifest snippet for both sets of inputs that the user might choose. Only one of these sets is evaluated and inserted into the job’s manifest.
Ops Manager Provided Snippets
The following double-parens accessors retrieve your job properties:
(( name ))
(( ips ))
(( ram ))
(( ephemeral_disk ))
(( persistent_disk ))
(( ips_by_availability_zone ))(deprecated)
(( instances ))
(( availability_zone ))(deprecated)
(( bosh_job_partition_stats ))(deprecated)
(( first_ip ))(deprecated)
(( first_network_deprecated ))(deprecated)
(( subnet_cidrs ))
The following is a list of all typed values with the accessor “value”:
The following list shows typed values with multiple accessors:
- simple_credentials: identity, password
- rsa_cert_credentials: private_key_pem, cert_pem, public_key_pem, cert_and_private_key_pems
- rsa_pkey_credentials: private_key_pem, public_key_pem, public_key_openssh, public_key_fingerprint
- salted_credentials: salt, identity, password
- selector: value, selected_option, nested context
In addition, Ops Manager supports accessors that are global to the entire installation rather than job specific.
- $opsmanager.ca_certificate: The internal SSL CA certificate used to sign all SSL certificates generated by this Ops Manager instance, such as when the user clicks a Generate Self-Signed RSA Certificate link