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.erb 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
  • Jobs

Top Level Properties

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$/)[1].inspect %>

  variables:
    - name: credhub-password
      type: password

  post_deploy_errands:
    - name: example-errand

  pre_delete_errands:
    - name: example-errand

name

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.

product_version

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.

minimum_version_for_upgrade

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:  1.7.0.0
  minimum_version_for_upgrade:  1.6.0.0

metadata_version

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.

label

String. Optional. The label that appears in the product tile when it displays in the Ops Manager Dashboard.

description

String. Optional. A description of the product. This is not currently used but may be displayed in a future version of Ops Manager.

rank

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.

stemcell_criteria

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.

releases

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).

post_deploy_errands

Array of Hashes. 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 Ops Manager. See Lifecycle Errands. If this property is not supplied, the selector defaults to On.

pre_delete_errands

Array of Hashes. 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 Ops Manager. See Lifecycle Errands. If this property is not supplied, the selector defaults to On.

Form Properties

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'

name

String. Required. The internal name of the form.

label

String. Required. The label of the form as it appears as a link on the left hand side of each form.

description

String. Optional. The description of the form. Appears at the top of the form as a header.

markdown

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.

property_inputs

Array of Hashes. Required. References to properties defined in the property_blueprints section of the product template.

placeholder

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.

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

Simple vs. Complex Inputs (Selectors and Collections)

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:

Selector

Collections appear as follows:

Collection

Property Blueprints

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'

configurable

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.

must_match_regex

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 error_message. Multiple must_match_regex constraints for a single property blueprint are evaluated in the order listed.

Configurable Properties

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.

string

A string.

integer

An integer.

boolean

A boolean. Viewed as a checkbox.

dropdown_select

A list of options. The user chooses one viewed as an HTML select box.

domain

A second, third, fourth, etc level domain.

wildcard_domain

A domain with a wildcard in front of it. Example: *.domain.com

text

A string. Appears as an HTML textarea.

ldap_url

A url prefaced by ldap://.

email

An email address.

ip_ranges

A range of IP addresses, with dashes and commas allowed. Example: 1.1.1.1-1.1.1.4,2.2.2.1-2.2.2.4

port

An integer representing a network port.

network_address

A single IP address or domain. Example: 1.1.1.1

network_address_list

A list of IP addresses or domains. Example: 1.1.1.1,example.com,2.2.2.2

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.

rsa_cert_credentials

An RSA certificate.

rsa_pkey_credentials

An RSA private key.

salted_credentials

Username and password created using a non-reversible hash algorithm.

simple_credentials

Username and password.

secret

A random string or password.

uuid

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.

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 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.

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: foo@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: '1.1.1.1-1.1.1.4,2.2.2.1-2.2.2.4'
    - 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: '1.1.1.1,example.com,foo.bar.example.com'
    - name: example_network_address
      type: network_address
      configurable: true
      default: '1.1.1.1'
    - 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 ))

name

String. Required. The name of the job as it will be created in the Ops Manager generated BOSH manifest.

resource_label

String. Required. The label of the job as it will appear in the resources page of the tile.

templates

Array of Hashes. Required. Each element has the following fields:

name

The name of the job template to use. Required.

release

The name of the release the template is from. Required.

consumes

A YAML string defining BOSH links this job consumes. Optional.

provides

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.

release

String. Required. The name of the BOSH release contained in your product archive (.pivotal file).

static_ip

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.

dynamic_ip

Boolean. Required. Set the opposite of static_ip. This will eventually be eliminated as a property as it is obviously redundant and unnecessary.

single_az_only

Boolean. Required. You can give users control of balancing jobs across availability zones (AZs) by setting single_az_only to false. To limit a job to a single AZ, set this to true.

max_in_flight

Integer. Required. A BOSH setting that controls the number of instances of this job that BOSH will deploy in parallel.

resource_definition

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:

  • ram
  • ephemeral_disk
  • persistent_disk
  • cpu

Note: If you set the default property for persistent_disk to 0, users cannot edit this value and the Resource Config page in Ops Mananger displays None under the persistent disk field.

instance_definition

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 .properties.system.database and property value to magic value to change the instance counts of all MySQL jobs to 0.

manifest

Text snippet, prefaced by pipe symbol: |. Optional. 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.

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: (( name ))
  • ips: (( ips ))
  • ram: (( ram ))
  • ephemeral_disk: (( ephemeral_disk ))
  • persistent_disk: (( persistent_disk ))
  • ips_by_availability_zone: (( ips_by_availability_zone )) (deprecated)
  • instances: (( instances ))
  • availability_zone: (( availability_zone )) (deprecated)
  • bosh_job_partition_stats: (( bosh_job_partition_stats )) (deprecated)
  • first_ip: (( first_ip )) (deprecated)
  • first_network_deprecated: (( first_network_deprecated )) (deprecated)
  • subnet_cidrs: (( subnet_cidrs ))

The following is a list of all typed values with the accessor “value”:

  • collection
  • ldap_url
  • domain
  • wildcard_domain
  • ip_ranges
  • ip_address
  • email
  • port
  • integer
  • string
  • boolean
  • text
  • smtp_authentication
  • network_address
  • network_address_list
  • string_list
  • ca_certificate
  • multi_select_options
  • dropdown_select
  • vm_type_dropdown
  • disk_type_dropdown
  • uuid
  • service_network_az_multi_select
  • service_network_az_single_select
  • secret

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
  • $opsmanager.trusted_certificates
  • $opsmanager.http_proxy
  • $opsmanager.https_proxy
  • $opsmanager.no_proxy
  • $director.deployment_ip
  • $director.hostname
  • $director.username
  • $director.password
  • $director.ntp_servers
  • $director.ca_public_key
  • $self.uaa_client_name
  • $self.uaa_client_secret
  • $self.service_network
  • $self.stemcell_version
  • .PRODUCT-NAME.properties
  • .PRODUCT-NAME.deployment_name
Create a pull request or raise an issue on the source for this page in GitHub