Product Template Reference
This document defines the separate pieces of a product template. For the purpose of explanation we use the PCF example tile, a functional tile provided by the Ops Manager engineering team that deploys the NGINX web server.
The product template, a
.yml file in the tile’s
metadata subdirectory, includes or points to the following:
- 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: <%= version.inspect %> minimum_version_for_upgrade: "1.7.0" metadata_version: "1.11" label: 'Ops Manager: Example Product' description: An example product to demonstrate Ops Manager product-author features rank: 1 service_broker: false # Default value stemcell_criteria: os: ubuntu-trusty version: <%= stemcell_version.inspect %> enable_patch_security_updates: true releases: - name: example-release file: <%= release_file_name.inspect %> version: <%= release_file_name.match(/^example-release-(.*)\.tgz$/).inspect %> variables: - name: credhub-password type: password post_deploy_errands: - name: example-errand pre_delete_errands: - name: example-errand
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: 220.127.116.11 minimum_version_for_upgrade: 18.104.22.168
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)i, you must set this value to an integer less than 100. Pivotal recommends that you set it to 1. Ops Manager sorts tiles alphabetically if all tiles have the same rank. This is a known weak point.
Boolean. Optional, default
true for on-demand service brokers. Setting
true does the following:
- Enables the service network selector property type
- Requires the operator to select a service network during tile configuration.
Tile authors can reference the selected service network with
(( $self.service_network )).
- Includes 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 )).
Hash. Required. For a list of stemcells, including OS and version, see the BOSH hub. 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 does not receive security patches through automatic stemcell updates.
stemcell_criteria os: ubuntu-trusty version: <%= stemcell_version.inspect %> 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. For more information, see Understanding Floating Stemcells.
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 run after a deploy succeeds.
run_post_deploy_errand_default: property to
off to set the default for the errand’s run rule selector in Ops Manager.
See Lifecycle Errands. If this property is not supplied, the selector defaults to
Array of Hashes. Optional. A list of errands that run before a deployment is deleted.
run_pre_delete_errand_default: property to
off to set the default for the errand’s run rule selector in Ops Manager.
See Lifecycle Errands. If this property is not supplied, the selector defaults to
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: | ## I am markdown, hear me _roar_. ![Alt text](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 field. 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 will not be editable 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'
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_selector type: selector configurable: true default: Pizza freeze_on_deploy: true 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 )) - name: provides_section manifest: | as: 'pizza_link_web_server_job' - name: consumes_section manifest: | from: 'pizza_link_web_server_job' property_blueprints: - name: pepperoni type: boolean configurable: true freeze_on_deploy: true - name: pineapple type: boolean configurable: true default: true - name: other_toppings type: string configurable: true optional: true constraints: - must_match_regex: '\A[^!@#$%^&*()]*\z' error_message: 'This name cannot contain special characters.' - name: filet_mignon_option select_value: Filet Mignon named_manifests: - name: my_snippet manifest: | rarity: (( .properties.example_selector.filet_mignon_option.rarity_dropdown.value )) review: (( .properties.example_selector.filet_mignon_option.review.value )) secret_sauce: (( .properties.example_selector.filet_mignon_option.secret_sauce.value )) - name: provides_section manifest: | as: 'filet_mignon_link_web_server_job' - name: consumes_section manifest: | from: 'filet_mignon_link_web_server_job' 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 unless
configurable is set to
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 list of options. The user chooses zero or more, viewed as HTML checkboxes.
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:
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.
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 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 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
job_type. This is because
vm_credentials are generated automatically,
and you can find them in the release manifest.
Note: Starting in PCF v2.1, Ops Manager ignores
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: '22.214.171.124-126.96.36.199,188.8.131.52-184.108.40.206' - 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: '220.127.116.11,example.com,foo.bar.example.com' - name: example_network_address type: network_address configurable: true default: '18.104.22.168' - 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 )) 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).
You can give users control of balancing jobs across availability zones (AZs) by setting
To limit a job to a single AZ, set this to
WARNING: If you change the
single_az_only setting, your VMs may switch AZs. This change can cause an orphaned disk.
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
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
For example, your product uses Amazon Relational Database Service (RDS) instead of MySQL, which is the default system database for Elastic Runtime.
property reference to
property value to
magic value to change the instance counts of all MySQL jobs to
Text snippet, prefaced by pipe symbol:
Ops Manager generates a BOSH manifest that defines properties for each job that the manifest deploys.
Some of these properties are not set until the user clicks Apply Changes, because the user configures them in the tile or because Ops Manager has to generate them.
To include these properties in a manifest snippet, use “double-parens” syntax, which consists of a variable name surrounded by two sets of parentheses:
manifest: | pizza_toppings: pepperoni: (( .properties.example_selector.pizza_option.pepperoni.value ))
When Ops Manager parses a product template and BOSH parses a manifest, they both fill in 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 Ops Manager. To include these BOSH deploy-time properties in a manifest snippet, use “triple-parens” notation:
manifest: | credhub: concatenated_password: prefix-((( credhub-password )))-suffix password: ((( credhub-password )))
Ops Manager strips 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.
Specify a property for collection within the
named_manifest section of the metadata.
See the Simple vs. Complex Inputs section for more information about collections.
The following example uses a named manifest called
for_routing that belongs to the
- name: certificate_collection type: collection configurable: true property_blueprints: - name: some_cert_name type: string - name: some_cert type: rsa_cert_credentials named_manifests: - name: for_routing manifest: | name: (( current_record.some_cert_name.value )) private_key: (( current_record.some_cert.private_key_pem )) public_key: (( current_record.some_cert.public_key_pem )) certificate: (( current_record.some_cert.cert_pem ))
current_record property within a collection record to refer to other properties in the same record.
For example, the properties in the
for_routing named manifest refer to the values for
certificate within this record only.
current_record property is reserved. You cannot create a new property named
After defining a named manifest, you can reference it using a manifest snippet in the following format:
routing_certificates: (( .properties.certificate_collection.parsed_manifest(for_routing) ))
Ops Manager renders the following manifest from this example:
routing_certificates: - name: foo_cert private_key: PRIVATE-KEY public_key: PUBLIC-KEY certificate: CERTIFICATE - name: bar_cert private_key: PRIVATE-KEY public_key: PUBLIC-KEY certificate: CERTIFICATE
Selector snippets are evaluated twice. As you saw in the
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.
The following double-parens accessors retrieve your job properties:
(( name ))
(( ram ))
(( ephemeral_disk ))
(( persistent_disk ))
(( instances ))
(( availability_zone ))(deprecated)
(( bosh_job_partition_stats ))(deprecated)
(( first_network_deprecated ))(deprecated)
(( subnet_cidrs ))
Note: As of PCF v2.1, IP accessors are no longer supported.
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.
- $ops_manager.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