LATEST VERSION: 2.3 - RELEASE NOTES
PCF Tile Developer Guide v2.3

Property and Template References

Page last updated:

Overview

A tile’s metadata subdirectory contains a product template file in .yml format. The product template file specifies how the tile interface collects configurable properties from the user, and how Ops Manager incorporates these properties into its deployment manifest.

You can modify your tile’s product template in many different ways. Two important concepts to understand are what the product template contains and how to modify it to include different properties.

This topic explains these two concepts and gives examples of different configuration options for tiles.

Product Template Contents

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: Your opportunity to specify product dependencies
  • Property Blueprints: The templates to represent values
  • Form Types: The way to expose property blueprints to generated forms
  • Job Types: configuration properties for jobs defined in the BOSH release
  • Runtime Configs: specifes the manifest for any number of global deployment configurations

For the purpose of explanation, examples that refer to the product template use the PCF example tile, a functional tile provided by the Ops Manager engineering team that deploys the NGINX web server.

For more information about product template configuration, see Top Level Properties.

To learn how to configure your tile’s forms, see Form Properties.

Modifying the Product Template

You can modify the product template to designate property values.

Within the product template, there are two sections with manifest snippets. These sections are:

  • form_types: This defines the tile interface, or how users of your tile view and interact with different tile features.
  • job_types: This 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 would otherwise not know about, such as user provided configurable properties or dynamically generated system properties.

These special expressions take two forms:

Double Parentheses Expressions

Double-parentheses expressions, such as (( PROPERTY-VALUE )) designate property values that Ops Manager fills in when it generates the deployment manifest. This occurs after the user clicks Apply Changes.

These values include configurable properties and properties supplied by Ops 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:

    manifest: |
      pizza_toppings:
        peppers: (( .properties.example_selector.pizza_option.peppers.value ))

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

    manifest: |
      credhub:
        concatenated_password: prefix-((( credhub-password )))-suffix
        password: ((( credhub-password )))

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.

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.

For more information about product properties, continue reading Referencing Properties.

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.

Using these two segments, you can write an expression as:

(( LOCATION_OF_PROPERTY.ACCESSOR ))

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 Refers to the property blueprint called “top_level_property” and found in the global list of properties of the same product
.job_one.job_level_property Refers to the property blueprint called “job_level_property” and found in the list of properties of the job “job_one” of the same product
job_level_property Refers to the property blueprint called “top_level_property” and found in the same product and job whose manifest is currently being evaluated
..other_product.properties.top_level_property Refers to the property blueprint called “top_level_property” and found in the global list of properties of the product “other_product”
..other_product.job_two.job_level_property Refers to the property blueprint called “job_level_property” and found in the list of properties of the job “job_one” of the product “other_product”

Referencing an Accessor

Accessors vary between property blueprint types. The following example uses the property blueprint type string with its one accessor, value. A valid double-parentheses expression to access the value of this property (assuming it is top-level, and has the name example-string) would look like:

(( .properties.example-string.value ))

Ops Manager allows empty arrays in double-parentheses expressions. For example:

(( .properties.example-string.value || [] ))

For more information about the available properties and their accessors, see the Property Blueprint Reference.

Dollar Contexts

Outside of properties, you can also retrieve information about various configuration details of your product and Ops Manager.

  • $ops_manager: Any product can use this to obtain information about specific OpsManagers.
  • $director: Any product can use this to obtain information about the Director.
  • $runtime: Any product can use this to obtain information about the PAS tile.
  • $self: Your own product uses this to obtain information about its configuration.

$ops_manager

ca_certificate Provides the root CA cert that is used to sign 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 Ops Manager traffic is directed to an HTTP Proxy
https_proxy Provides the CSVs that are entered when Ops Manager traffic is directed to an HTTPS Proxy
no_proxy Provides the CSVs that should not go through a proxy

$director

deployment_ip Provides the IP address where the BOSH Director is deployed
username Provides the username for the Director VM
password Provides the password for the Director VM
ntp_servers Provides a list of Network Time Protocol (NTP) servers that the Director deploys
ca_public_key Provides the public key that is used to sign the Director VM
hostname Provides the hostname for the Director VM
tld Returns the string bosh as the top-level domain (TLD) of the BOSH Director
bosh_metrics_forwarder_client_name Provides the BOSH Metrics Forwarder client name
bosh_metrics_forwarder_client_secret Provides the BOSH Metrics Forwarder client secret
dns_release_present Exposes the Director configuration for disable_dns_release

$runtime

system_domain Provides domain for system-level PCF components, such as the API, UAA, or Apps Manager.
apps_domain Provides the default domain used by applications
system_api_url Provides the url to the PCF API component
login_url Provides the url to authenticate with the PCF components
uaa_url Provides the url to the PCF UAA component
console_url Provides the url to the PCF 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

$self

uaa_client_name Provides the UAA client name created for your product to communicate with the BOSH Director
uaa_client_secret Provides the UAA client secret created for your product to communicate with the BOSH Director
service_network Provides the name of the service network assigned to your product
stemcell_version Provides the version of the stemcell your product uses

Complex Properties: 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: Give the user a choice of a set of inputs.
  • Collections: Give the user the ability to enter an array of values to create a hash.

Selectors appear as follows:

Selector

Collections appear as follows:

Collection

The selector and collections inputs are referenced by their selector and collection property blueprints.

Most properties are simple values such as 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.

Top Level Properties

The following is an example of the properties that appear at the top of a product template. Definitions of each property follow this example.

  ---
  name: example-product
  product_version: <%= version.inspect %>
  minimum_version_for_upgrade: "1.7.0"
  pivnet_filename_regex: "product-*.pivotal"
  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-xenial
    version: <%= stemcell_version.inspect %>

    enable_patch_security_updates: true

  requires_product_versions:
    - name: p-mysql
      version: '~> 2.4'

  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

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

name

  • Format: String
  • Type: 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

  • Format: String
  • Type: Required

The version of the product.

You can only import this version into Ops Manager once. If you want to import the same product or 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

  • Format: String
  • Type: Required

You must 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

  • Format: String
  • Type: Required

The version of the schema of the product template, the file that this documentation describes.

Bumping the version number enables new properties that are not present in an older metadata_version but may also require restructuring of the product template to conform to the new metadata_version.

The metadata_version corresponds to a major and/or minor release of Ops Manager. Ops Manager can accept a product with a metadata_version that is older than the Ops Manager version, but Ops Manager cannot accept a product with a metadata_version that is newer than the Ops Manager version. It is therefore best practice to set the metadata_version to be the same as the oldest version of Ops Manager that the tile version supports.

label

  • Format: String
  • Type: Optional

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

description

  • Format: String
  • Type: Optional

A description of the product.

rank

  • Format: Integer
  • Type: Optional

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, you must set this value to an integer less than 100.

Pivotal recommends that you set it to 1.

If all tiles have the same rank, Ops Manager sorts them alphabetically.

pivnet_filename_regex

  • Format: String
  • Type: Optional

This regular expression allows Ops Manager’s Pivotal Network integration to pull a specific product file. You must do this when there are multiple products with the same product slug.

service_broker

  • Format: Boolean
  • Type: Optional, default false

Set service_broker to true for on-demand service brokers. Setting service_broker to 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 )).

stemcell_criteria

  • Format: Hash
  • Type: Required

enable_patch_security_updates allows you to automatically use the latest patched version of a stemcell. This is set to true by default. For products using static compilations, you can disable this feature. This feature increases security by automatically using the latest patched version of a stemcell. However, operators may experience longer than expected upgrade times.

Example:

 stemcell_criteria
  os: ubuntu-xenial
  version: <%= stemcell_version.inspect %>
  enable_patch_security_updates: true
 

Pivotal recommends setting this property to true. If you set the property to false, your product 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 hub.

For more information, see Understanding Floating Stemcells.

requires_product_versions

  • Format: Array of hashes
  • Type: Required

A list of product dependencies. If the required product is not present in the PCF installation, Ops Manager lists the needed dependencies and does not install your tile until the dependencies are satisfied.

releases

  • Format: Array of hashes
  • Type: 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).

Each release requires the following keys:

  • name
  • file
  • version

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

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

See Lifecycle Errands. If this property is not supplied, the selector defaults to On.

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 Ops Manager. If you do not specify this property, the selector defaults to On.

For more information, see Lifecycle Errands.

runtime_configs

  • Format: Array of hashes
  • Type: Optional

These are keys that define global deployment configurations. For more information, see Managing Runtime Configs.

install_time_verifiers

  • Format: Array of hashes
  • Type: Optional

Verifiers are configurable settings that contact things outside the tile. For example, given an IP, a verifier can ping the IP to see that it responds.

Verifiers are separate from validators, which check whether a string is formatted properly.

Each verifier requires the following keys:

  • name
  • properties
  • ignorable - set to false by default

Here is a list of verifiers you can use:

  • BlobstoreVerifier
  • LDAPBindVerifier
  • MysqlDatabaseVerifier
  • SmtpAuthenticationVerifier
  • SsoUrlVerifier
  • StaticIpsVerifier
  • WildcardDomainVerifier

icon_image

  • Format: Base64 Image
  • Type: Required

This is the icon that displays on the tile in the Ops Manager Installation Dashboard.

base_releases_url

  • Format: String.
  • Type: Optional

A publicly available URL that is passed to BOSH in order to download your releases during installation. If you use this field, BOSH Director must have internet connectivity. This allows you to package your tile without releases, decreasing the tile size.

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 Ops 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 field’s data type. For a corresponding example to the form_types example below, see 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_.

      ![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'
    verifiers:
      - name: Verifiers::WildcardDomainVerifier
        properties:
          domain: .web_server.example_wildcard_domain
      - name: Verifiers::StaticIpsVerifier
        properties:
          domain: .web_server.example_ip_address

name

  • Format: String
  • Type: Required

The internal name of the form.

label

  • Format: String
  • Type: Required

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

description

  • Format: String
  • Type: Optional

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

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.

property_inputs

  • Format: Array of hashes
  • Type: Required

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

verifiers

Verifiers are configurable settings that contact things outside the tile. For example, given an IP, a verifier can ping the IP to see that it responds.

Verifiers are separate from validators, which check whether a string is formatted properly. For an example of a validator, see must_match_regex.

Here is a list of verifiers you can use:

  • BlobstoreVerifier
  • LDAPBindVerifier
  • MysqlDatabaseVerifier
  • SmtpAuthenticationVerifier
  • SsoUrlVerifier
  • StaticIpsVerifier
  • WildcardDomainVerifier

placeholder

  • Format: String
  • Type: 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

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. That is the core of what Ops Manager does for you: Ops Manager asks a user to designate values for those settings and generates a manifest based on what the user specifies.

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. You can find them in the release manifest.

Note: Starting in PCF v2.1, Ops Manager ignores static_ip and dynamic_ip keys.


  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 ))
          bosh_job_partition_stats: (( bosh_job_partition_stats ))

name

  • Format: String
  • Type: Required

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

resource_label

  • Format: String
  • Type: Required

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

templates

  • Format: Array of hashes
  • Type: Required

Each element has the following fields:

name

  • Format: Name of the job template to use
  • Type: Required

release

  • Format: Name of the release the template is from
  • Type: Required

consumes

  • Format: YAML string defining BOSH links that this job consumes
  • Type: Optional

provides

  • Format: YAML string defining BOSH links that this job provides
  • Type: Optional

This is a BOSH feature (creating jobs from different releases). See the BOSH documentation for more information.

release

  • Format: String
  • Type: Required

The name of the BOSH release contained in your product archive, which is the .pivotal file.

single_az_only

  • Format: Boolean
  • Type: 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 single_az_only to true.

WARNING: If you change the single_az_only setting, your VMs may switch AZs. This change can cause an orphaned disk.

max_in_flight

  • Format: Integer
  • Type: Required

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

resource_definitions

  • Format: Array of hashes
  • Type: Required

A set of resource settings for the job along with maximum and minimum constraints, defaults, and enabled or disabled configurability.

The resources you can set are:

  • ram
  • ephemeral_disk
  • persistent_disk
  • cpu

For examples of supported constraint types, see integer below.

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

instance_definition

  • Format: Hash
  • Type: Required

The number of default instances for a job, including maximum, minimum, odd, and the ability to decrease sizing after deploy.

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. Remove all instance counts of MySQL by setting property reference to .properties.system.database and property value to magic value.

For examples of supported constraint types, see integer below.

Note: If you are using the zero_if property, you should not set the may_only_increase constraint to true.

manifest

  • Format: Text snippet, prefaced by pipe symbol: |
  • Type: Optional

Ops Manager generates a BOSH manifest that defines properties for each job 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.

For more information about these properties, see Designating Property Values.

Property Blueprint Reference

Common Property Blueprint Attributes

All property blueprints can have the following attributes:

name Required.
The name of the property. The name is used to reference a property in form_types and in (( )) accessors.
type Required.
The type of property. Must be one of the property types listed in this documentation.
optional Optional.
Default: False
When set to true, Ops Manager will not require this property to be set in order to deploy, nor will it validate that this field has a value when saving a form with this property.
optional cannot be set to true if a default value is set (see documentation below for which types support default).
optional cannot be set to true if the property also has configurable: false.
configurable Optional.
Default: false.
When set to true for property types which support operator configuration, the operator will be allowed to configure this value.
Do not set configurable: true for property types which do not support operator configuration.
When set to false, Ops Manager will not render this property in any form, even if it’s specified in a form_type, nor will it allow the property to be updated via the API.
For property types which support auto-generation of values, when configurable is false, Ops Manager will generate and save a value for this property when the product to which this property belongs is deployed for the first time.
freeze_on_deploy Optional.
Default: false.
When set to true, Ops Manager will not allow this property to be changed after the product this property belongs to is successfully deployed.

Configurable and Auto-Generated Properties

When a property has configurable: true and is added to a form_type, the operator can configure the value of that property.

Alternatively, a property with configurable: false will have a value auto-generated by Ops Manager. See below for which property types support each of these usages.

Properties with configurable set to false:

+ cannot be edited by the operator.
+ will not show up in forms, even if added under `form_types`.
+ will have auto-generated values filled in by OpsManager if that specific type of property supports auto-generation of values.

named_manifest for selector and collection type properties

Specify a property for collection within the named_manifest section of the metadata.

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

Use the 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 name, private_key, public_key, and certificate within this record only.

Note: The current_record property is reserved. You cannot create a new property named current_record.

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

For more information, see the sections on Selector and Collection types.

All Property Blueprint Types

Below is a reference to every property blueprint type.

boolean

This holds a single boolean value.

credential no
supports auto-generation no
supports operator configuration yes

Property Blueprint Attributes

default Optional. Specifies a default value. When provided, must be set to a value which is valid for this type. Cannot be used when the property also has optional: true.

Accessors

value Returns the boolean value of the property.
value_present? Returns true only if the value of the property is set.

Example

property_blueprints:
  - name: example_boolean
    type: boolean
    configurable: true
    default: false

form_types:
  - name: example_form
    label: 'Example form'
    description: 'An example form'
    property_inputs:
      - reference: .properties.example_boolean
        label: 'Example checkbox'
        description: 'This is an example checkbox'

job_types:
- name: example-job
  resource_label: An Example Job
  <<: *job_type_boilerplate
    templates:
      - name: user_add
        release: os-conf
        manifest: |
          persistent_homes: (( .properties.example_boolean.value ))

Example Product with Boolean Information

ca_certificate

This holds a string value

credential no
supports auto-generation no
supports operator configuration yes

Property Blueprint Attributes

default Optional. Specifies a default value. When provided, must be set to a value which is valid for this type. Cannot be used when the property also has optional: true.

Accessors

value Returns a string or null.
value_present? Returns true only if the value of the property is set.

Example

property_blueprints:
- name: ca_cert
  type: ca_certificate
  configurable: true

form_types:
- name: example_form
  label: 'Example form'
  description: 'An example form'
  property_inputs:
    - reference: .properties.ca_cert
      label: 'Trusted CA certs'
      description: 'These certificates will be trusted by the deployed VM'

job_types:
- name: example-job
  resource_label: An Example Job
  <<: *job_type_boilerplate
  templates:
    - name: ca_certs
      release: os-conf
      manifest: |
        certs: (( .properties.ca_cert.value ))

Example Product with CA Certificate

collection

This holds multiple records of a group of custom defined properties.

credential no
supports auto-generation no
supports operator configuration yes

Property Blueprint Attributes

default Optional. Specifies a default value. When provided, must be set to a value which is valid for this type. Cannot be used when the property also has optional: true.

If specified, the default value must be an array where each item of the array has the keys and values which are appropriate for the property blueprints provided. For the example below, a default value could be:
default:
  - name: sam
    public_key: ssh-rsa AAAAB3NzaC1yc2EAAAAD...
    sudo: true
property_blueprints A group of property blueprints that each record will have. Any type and combination of property types can be used except collections and selectors which cannot be nested inside of collections.
named_manifests An array of objects each containing a name and a manifest. The manifest specifies the YAML which can be used with parsed_manifest(name) where the manifest will be interpolated for each record in the collection. The manifest has a special property level, current_record, which has all the properties in a record of the collection. The provided example below shows have named_manifest, current_record, and parsed_manifest together to render a collection in a BOSH manifest.

Accessors

parsed_manifest(named) An array of interpolated YAML elements (often objects, but could be strings or numbers). Where each element of the array is an interpolation of the named_manifest for each record.
value An array of objects whose keys are the property names specified under property_blueprints, and whose values are the .value for each property. For example, if a collection “albums” had properties: title (string) and explicit (boolean), (( albums.value )) would render:
[
  {title: 'album-one', explicit: true},
  {title: 'album-two', explicit: false}
]

Example using .value accessor

property_blueprints:
  - name: users_to_add
    type: collection
    configurable: true
    property_blueprints:
      - name: name
        type: string
        configurable: true
      - name: public_key
        type: string
        configurable: true
      - name: sudo
        type: boolean
        configurable: true

form_types:
  - name: example_form
    label: 'Example form'
    description: 'An example form'
    property_inputs:
      - reference: .properties.users_to_add
        label: 'Users to add'
        description: 'will added to deployed VM'
        property_inputs:
          - reference: name
            label: Username
            description: username of the added user
          - reference: public_key
            label: Public key
            description: RSA public key used to SSH onto the VM
          - reference: sudo
            label: make sudoer
            description: if checked, user will be able to sudo

job_types:
  - name: example-job
    resource_label: An Example Job
    <<: *job_type_boilerplate
    templates:
      - name: user_add
        release: os-conf
        manifest: |
          users: ((.properties.users_to_add.value))

Example Product with a Collection

Resulting manifest snippet
...
instance_groups:
- name: example-job
  jobs:
  - name: user_add
    release: os-conf
    ...
    properties:
      users:
      - name: tom
        public_key: ssh-rsa MFwwDQYJKoZIhvcNAQEBBQ...
        sudo: false
      - name: sameer
        public_key: ssh-rsa MFwwDQYJKoZIhvcNAQEBBQ...
        sudo: true
...

Example with .parsed_manifest(name)

property_blueprints:
  - name: sysctls
    type: collection
    configurable: true
    property_blueprints:
      - name: setting_name
        type: string
        configurable: true
      - name: setting_value
        type: string
        configurable: true
    named_manifests:
      - name: name_value_format
        manifest: (( current_record.setting_name.value ))=(( current_record.setting_value.value ))

form_types:
  - name: example_form
    label: 'Example form'
    description: 'An example form'
    property_inputs:
      - reference: .properties.sysctls
        label: 'Custom sysctls'
        description: 'sysctl configuration settings to be placed in /etc/sysctl.d'
        property_inputs:
          - reference: setting_name
            label: Setting name
            description: the sysctl setting name, e.g. net.core.somaxconn
          - reference: setting_value
            label: Setting value
            description: value for this sysctl setting

job_types:
  - name: example-job
    resource_label: An Example Job
    <<: *job_type_boilerplate
    templates:
      - name: sysctl
        release: os-conf
        manifest: |
          sysctl: (( .properties.sysctls.parsed_manifest(name_value_format) ))

Example Product with a Collection

Resulting manifest snippet
...
instance_groups:
- name: example-job
  jobs:
  - name: sysctl
    release: os-conf
    ...
    properties:
      sysctl:
      - foo=bar
      - fooz=baz
...

disk_type_dropdown

This holds a single string value selected from allowed disk types.

credential no
supports auto-generation no
supports operator configuration yes

Property Blueprint Attributes

resource_definitions Optional. An array of objects with the same schema as resource_definitions for job_types. For disk_type_dropdown, resource_definitions should only have one element with name “persistent_disk”. This element can also specify a default which OpsManager uses as a minimum bound when it selects a default value. It can also specify constraints, which can be any set of constraints that can be specified for an integer property. For examples of supported constraint types, see integer below.

Accessors

value Returns a string containing the size of the selected disk in megabytes, e.g. “1024”. If nothing or “Automatic” was specified by the operator, then then this returns the smallest disk that is greater than the default value specified in resource_definitions. If no default was specified, then this returns the smallest disk in the catalog.
value_present? Returns true only if a disk type is selected. If the user has selected “Automatic”, value_present? will be false.

Example

property_blueprints:
  - name: example_disk_type_dropdown
    type: disk_type_dropdown
    configurable: true
    resource_definitions:
      - name: persistent_disk
        default: 4096
        constraints:
          min: 2048

form_types:
  - name: example_form
    label: 'Example form'
    description: 'An example form'
    property_inputs:
      - reference: .properties.example_disk_type_dropdown
        label: 'Example disk_type_dropdown'
        description: 'This is an example'

job_types:
- name: example-job
  resource_label: An Example Job
  <<: *job_type_boilerplate
  templates:
    - name: login_banner
      release: os-conf
      manifest: |
        login_banner:
          text: "Hello user, I see that your favorite disk size greater than 2 Gb is: (( .properties.example_disk_type_dropdown.value ))."

Example Product with Disk Types Dropdown

domain

This holds a string value that is a valid domain (e.g. example.com or x.example.com:80/a/b).

credential no
supports auto-generation no
supports operator configuration yes

Property Blueprint Attributes

default Optional. Specifies a default value. When provided, must be set to a value which is valid for this type. Cannot be used when the property also has optional: true.

Accessors

value Returns the domain as a string or null.
value_present? Returns true only if the value is a non-empty string.

Example

property_blueprints:
  - name: example_domain
    type: domain
    configurable: true

form_types:
  - name: example_form
    label: 'Example form'
    description: 'An example form'
    property_inputs:
      - reference: .properties.example_domain
        label: 'Example domain'
        description: 'This is an example'

job_types:
- name: example-job
  resource_label: An Example Job
  <<: *job_type_boilerplate
  templates:
    - name: login_banner
      release: os-conf
      manifest: |
        login_banner:
          text: Hello, user. I see your favorite domain is (( .properties.example_domain.value )).

Example Product with Domain

This holds an array of strings selected string values.

credential no
supports auto-generation no
supports operator configuration yes

Property Blueprint Attributes

default Optional. Specifies a default value. When provided, must be set to a value which is valid for this type. Cannot be used when the property also has optional: true.

The default value should be one of the options’ names. For example, in the example shown below, “tomato” could be used as the default.
options An array of hashes, each item specifying a: name, which becomes the value of the property if this option is selected, and label shows up as the text in the dropdown for this option.

Accessors

value Returns the name of the selected option.
value_present? Returns true if an option in selected, and that option’s name is a non-empty string.

Example

property_blueprints:
- name: example_dropdown_select
  type: dropdown_select
  default: kiwi
  configurable: true
  options:
  - name: kiwi
    label: 'Kiwi'
  - name: lime
    label: 'Lime'
  - name: tomato
    label: 'Tomato'

form_types:
- name: example_dropdown
  label: 'Example form'
  description: 'An example form'
  property_inputs:
  - reference: .properties.example_dropdown_select
    label: Favorite fruit
    description: 'What is your favorite fruit?'

job_types:
- name: example-job
  resource_label: An Example Job
  <<: *job_type_boilerplate
  templates:
  - name: login_banner
    release: os-conf
    manifest: |
      login_banner:
        text: Hello, user. I see your favorite fruit is (( .properties.example_dropdown_select.value )).

Example Product with Multi-Select Options

email

This ensures the string value is formatted as an email address.

credential no
supports auto-generation no
supports operator configuration yes

Property Blueprint Attributes

default Optional. Specifies a default value. When provided, must be set to a value which is valid for this type. Cannot be used when the property also has optional: true.

Accessors

value Returns a string or null.
value_present? Returns true if value is a non-empty string.

Example

property_blueprints:
- name: example_email
  type: email
  configurable: true

form_types:
- name: example_dropdown
  label: 'Example form'
  description: 'An example form'
  property_inputs:
  - reference: .properties.example_email
    label: User email
    description: 'What is your email?'

job_types:
- name: example-job
  resource_label: An Example Job
  <<: *job_type_boilerplate
  templates:
  - name: login_banner
    release: os-conf
    manifest: |
      login_banner:
        text: Hello, user. Your email is (( .properties.example_email.value )).

Example Product with Email

http_url

This holds an HTTP URL.

credential no
supports auto-generation no
supports operator configuration yes

Property Blueprint Attributes

default Optional. Specifies a default value. When provided, must be set to a value which is valid for this type. Cannot be used when the property also has optional: true.

Accessors

value Returns a string or null.
value_present? Returns true if value is a non-empty string.

Example

property_blueprints:
  - name: example_http_url
    type: http_url
    configurable: true
    default: 'http://example.com'

form_types:
  - name: example_form
    label: 'Example form'
    description: 'An example form'
    property_inputs:
      - reference: .properties.example_http_url
        label: Example http_url
        description: 'Configure a property of type http_url'

job_types:
- name: example-job
  resource_label: An Example Job
  <<: *job_type_boilerplate
  templates:
  - name: login_banner
    release: os-conf
    manifest: |
      login_banner:
        text: Hello, user. For fun, please visit (( .properties.example_http_url.value )).

Example Product with Http URL

integer

This holds a single integer value.

credential no
supports auto-generation no
supports operator configuration yes

Property Blueprint Attributes

default Optional. Specifies a default value. When provided, must be set to a value which is valid for this type. Cannot be used when the property also has optional: true.
constraints Constrains which integer values are considered valid. See the below table for all supported constraint types.

Supported Constraints

max Sets the maximum value of the integer.
may_only_be_odd_or_zero Sets the integer to only allow odd or zero values.
may_only_increase Sets the integer to only increase in value.
min Sets the minimum value of the integer.
modulo Sets the integer to only be divisable by the given value.
power_of_two Sets the integer to only be a power of two.
zero_or_min Sets the minimum value of the integer but allows zero.

Accessors

value Returns an integer or null.
value_present? Returns true if value is an integer.

Example

property_blueprints:
  - name: example_integer1
    type: integer
    configurable: true
    default: 9
    constraints: # the following constraints allow the values 9, 15, and 21
      min: 8
      max: 21
      may_only_increase: true
      may_only_be_odd_or_zero: true
      modulo: 3
  - name: example_integer2 # the following constraints allow the values 8 and 16
    type: integer
    configurable: true
    optional: true
    constraints:
      zero_or_min: 5
      max: 20
      power_of_two: true

form_types:
  - name: example_integer
    label: 'Example form'
    description: 'An example form'
    property_inputs:
      - reference: .properties.example_integer1
        label: Example Integer 1
        description: 'Configure a property of type integer'
      - reference: .properties.example_integer2
        label: Example Integer 2
        description: 'Configure another property of type integer'

job_types:
  - name: example-job
    resource_label: An Example Job
    <<: *job_type_boilerplate
    templates:
    - name: tcp_keepalive
      release: os-conf
      manifest: |
        tcp_keepalive:
          time: (( .properties.example_integer1.value ))
          interval: (( .properties.example_integer2.value ))

Example Product with Integer

ip_address

Ensures the string value is an IP address.

credential no
supports auto-generation no
supports operator configuration yes

Property Blueprint Attributes

default Optional. Specifies a default value. When provided, must be set to a value which is valid for this type. Cannot be used when the property also has optional: true.

Accessors

value Returns a string or null.
value_present? Returns true if value is a non-empty string.

Example

property_blueprints:
  - name: example_ip_address
    type: ip_address
    configurable: true
    default: 192.168.0.1

form_types:
  - name: example_form
    label: 'Example form'
    description: 'An example form'
    property_inputs:
      - reference: .properties.example_ip_address
        label: Example IP Address
        description: 'Configure a property of type ip_address'

job_types:
- name: example-job
  resource_label: An Example Job
  <<: *job_type_boilerplate
  templates:
    - name: login_banner
      release: os-conf
      manifest: |
        login_banner:
          text: Hello, user. I see your favorite IP Address is (( .properties.example_ip_address.value )).

Example Product with IP Address

ip_ranges

This holds a string that is a comma-separated list of IP addresses and IP address ranges.

credential no
supports auto-generation no
supports operator configuration yes

Property Blueprint Attributes

default Optional. Specifies a default value. When provided, must be set to a value which is valid for this type. Cannot be used when the property also has optional: true.

Accessors

parsed_ip_ranges Returns an array of strings containing each IP range
value Returns a string containing a comma-separated list of IP ranges and IP addresses, or null.
value_present? Returns true if value is a non-empty string.

Example

property_blueprints:
  - 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,3.3.3.3

form_types:
  - name: example_form
    label: 'Example form'
    description: 'An example form'
    property_inputs:
      - reference: .properties.example_ip_ranges
        label: Example IP Ranges
        description: 'Configure a property of type ip_ranges'

job_types:
- name: example-job
  resource_label: An Example Job
  <<: *job_type_boilerplate
  templates:
    - name: login_banner
      release: os-conf
      manifest: |
        login_banner:
          text: Hello, user. I see your favorite IP ranges are (( .properties.example_ip_ranges.value )).

Example Product with IP Ranges

ldap_url

Ensures the inputted string matches a URL of the LDAP protocol.

credential no
supports auto-generation no
supports operator configuration yes

Property Blueprint Attributes

default Optional. Specifies a default value. When provided, must be set to a value which is valid for this type. Cannot be used when the property also has optional: true.

Accessors

value Returns a string or null.
value_present? Returns true if value is a non-empty string.

Example

property_blueprints:
  - name: example_ldap_url
    type: ldap_url
    configurable: true
    default: 'ldap://example.com'

form_types:
  - name: example_form
    label: 'Example form'
    description: 'An example form'
    property_inputs:
      - reference: .properties.example_ldap_url
        label: Example ldap_url
        description: 'Configure a property of type ldap_url'

job_types:
- name: example-job
  resource_label: An Example Job
  <<: *job_type_boilerplate
  templates:
  - name: login_banner
    release: os-conf
    manifest: |
      login_banner:
        text: Hello, user. I see your favorite LDAP URL is (( .properties.example_ldap_url.value )).

Example Product with LDAP URL

multi_select_options

This holds an array of selected string values. Must be an array of non-blank strings.

credential no
supports auto-generation no
supports operator configuration yes

Property Blueprint Attributes

default Optional. Specifies a default value. When provided, must be set to a value which is valid for this type. Cannot be used when the property also has optional: true.

Accessors

value Returns an array of strings for the selected options or null.
value_present? Returns true if any of the checkboxes are checked.

Example

property_blueprints:
  - name: example_multi_select_options
    type: multi_select_options
    configurable: true
    default: ['earth', 'mercury']
    options:
    - name: mercury
      label: 'label for mercury'
    - name: venus
      label: 'label for venus'
    - name: earth
      label: 'label for earth'

form_types:
  - name: example_multi_select_options
    label: 'Example form'
    description: 'An example form'
    property_inputs:
      - reference: .properties.example_multi_select_options
        label: Example Multi-Select Options
        description: 'Configure a property of type multi_select_options'

job_types:
  - name: example-job
    resource_label: An Example Job
    <<: *job_type_boilerplate
    templates:
    - name: modprobe
      release: os-conf
      manifest: |
        # the value at the 'modules' key will render as an array of strings
        modules: (( .properties.example_multi_select_options.value ))

Example Product with Multi-Select Options

network_address

This holds a string which is a hostname, domain name, or IP addresses.

credential no
supports auto-generation no
supports operator configuration yes

Property Blueprint Attributes

default Optional. Specifies a default value. When provided, must be set to a value which is valid for this type. Cannot be used when the property also has optional: true.

Accessors

value Returns a string or null.
value_present? Returns true if value is a non-empty string.

Example

property_blueprints:
  - name: example_network_address
    type: network_address
    configurable: true
    default: 'localhost'

form_types:
  - name: example_network_address
    label: 'Example form'
    description: 'An example form'
    property_inputs:
      - reference: .properties.example_network_address
        label: Example Network Address
        description: 'Configure a property of type network_address'

job_types:
  - name: example-job
    resource_label: An Example Job
    <<: *job_type_boilerplate
    templates:
    - name: login_banner
      release: os-conf
      manifest: |
        login_banner:
          text: Hello, user. I see your favorite network address is (( .properties.example_network_address.value )).

Example Product with Network Address

network_address_list

This holds a string which is a comma-separated list of hostnames and IP addresses.

credential no
supports auto-generation no
supports operator configuration yes

Property Blueprint Attributes

default Optional. Specifies a default value. When provided, must be set to a value which is valid for this type. Cannot be used when the property also has optional: true.

Accessors

parsed_network_addresses Returns the list of hostnames and IP addresses as an array of strings
value Returns a string which is a comma-separated list of hostnames and IP addresses or null.
value_present? Returns true if value is a non-empty string.

Example

property_blueprints:
  - name: example_network_address_list
    type: network_address_list
    configurable: true
    default: 'localhost,8.8.8.8'

form_types:
  - name: example_network_address_list
    label: 'Example form'
    description: 'An example form'
    property_inputs:
      - reference: .properties.example_network_address_list
        label: Example Network Address List
        description: 'Configure a property of type network_address_list'

job_types:
  - name: example-job
    resource_label: An Example Job
    <<: *job_type_boilerplate
    templates:
    - name: login_banner
      release: os-conf
      manifest: |
        login_banner:
          text: Hello, user. I see your favorite network addresses are (( .properties.example_network_address_list.value )).
          an_ignored_array_of_network_addresses: (( .properties.example_network_address_list.parsed_network_addresses ))

Example Product with Network Address List

port

This holds a single integer value. Allowed values are 0 through 65535 and null.

credential no
supports auto-generation no
supports operator configuration yes

Property Blueprint Attributes

default Optional. Specifies a default value. When provided, must be set to a value which is valid for this type. Cannot be used when the property also has optional: true.

Accessors

value Returns an integer or null.
value_present? Returns true if value is not null.

Example

property_blueprints:
  - name: example_port
    type: port
    configurable: true
    default: 3000

form_types:
  - name: example_port
    label: 'Example form'
    description: 'An example form'
    property_inputs:
      - reference: .properties.example_port
        label: Example Port
        description: 'Configure a property of type port'

job_types:
  - name: example-job
    resource_label: An Example Job
    <<: *job_type_boilerplate
    templates:
    - name: login_banner
      release: os-conf
      manifest: |
        login_banner:
          text: Hello, user. I see your favorite network port is (( .properties.example_port.value )).

Example Product with Port

rsa_cert_credentials

This holds SSL certificate generated from root CA

credential yes
supports auto-generation yes
supports operator configuration yes

Property Blueprint Attributes

default For properties which use configurable: false, the default can specify a list of domain names to use when auto-generating the RSA certificate. The first domain listed will be the value of the Common Name field of the cert. The full list of domains will be the value of the Alternative Names field of the cert. See the example below.

Accessors

cert_pem Returns a string
private_key_pem Returns a string
cert_and_private_key_pems Returns a string
public_key_pem Returns a string
value_present? Returns true if value is an RSA certificate. Returns false if the value is null.

Example

property_blueprints:
  # This is configurable by the operator and appears in the form_types section
  - name: example_configurable_rsa_cert_credentials
    type: rsa_cert_credentials
    configurable: true
    optional: true
  # This is not configurable by the operator and is auto-generated
  - name: example_non_configurable_rsa_cert_credentials
    type: rsa_cert_credentials
    configurable: false
    default:
      domains:
        - 'cell.service.cf.internal'
        - '*cell.service.cf.internal'
form_types:
  - name: example_form
    label: 'Example form'
    description: 'An example form'
    property_inputs:
      - reference: .properties.example_configurable_rsa_cert_credentials
        label: Example configurable rsa_cert_credentials
        description: 'Configure a property of type rsa_cert_credentials'

job_types:
  - name: example-job
    resource_label: An Example Job
    <<: *job_type_boilerplate
    templates:
    - name: login_banner
      release: os-conf
      manifest: |
        login_banner:
          text: |
            Hello, user.
            Here is your public_key_pem
            (( .properties.example_non_configurable_rsa_cert_credentials.public_key_pem ))
            Here is your private_key_pem
            (( .properties.example_non_configurable_rsa_cert_credentials.private_key_pem ))
            Here is your cert_pem
            (( .properties.example_non_configurable_rsa_cert_credentials.cert_pem ))
            Here is your cert_and_private_key_pems
            (( .properties.example_non_configurable_rsa_cert_credentials.cert_and_private_key_pems ))

Example Product with RSA Cert Credentials

rsa_pkey_credentials

This holds RSA public and private keys. This is a non-configurable property.

credential yes
supports auto-generation yes
supports operator configuration no

Accessors

public_key_pem Returns a string
private_key_pem Returns a string
public_key_fingerprint Returns a string
public_key_openssh Returns a string
value_present? Returns true if value of the pkey already exists.

Example

property_blueprints:
  - name: example_rsa_pkey_credentials
    type: rsa_pkey_credentials
    configurable: false

job_types:
  - name: example-job
    resource_label: An Example Job
    <<: *job_type_boilerplate
    templates:
      - name: user_add
        release: os-conf
        manifest: |
          users:
            - name: nick
              public_key: ((.properties.example_rsa_pkey_credentials.public_key_pem))

salted_credentials

This holds credentials with salted and hashed passwords. This is a non-configurable property.

credential yes
supports auto-generation yes
supports operator configuration no

Property Blueprint Attributes

default Optional. Specifies a default value. When provided, must be set to a value which is valid for this type. Cannot be used when the property also has optional: true.

If specified, the default value must be an object which is allowed to have the key identity. For example, a default value could be:
default:
  - identity: ryan

Accessors

identity Returns a string
password Returns a string
salt Returns a string
sha512_hashed_password Returns a string
value_present? Returns true if value of the credential has been generated already

Example

property_blueprints:
  # Example without defaults
  - name: example_salted_credentials
    type: salted_credentials
  # Example with default identity
  - name: example_salted_credentials_with_default
    type: salted_credentials
    default:
      identity: vcap

job_types:
  - name: example-job
    resource_label: An Example Job
    <<: *job_type_boilerplate
    templates:
      - name: user_add
        release: os-conf
        manifest: |
          users:
            - name: vcap
              crypted_password: ((.properties.example_salted_credentials.sha512_hashed_password))

secret

This holds a single string value.

credential yes
supports auto-generation yes
supports operator configuration yes

Accessors

value Returns the secret as a string or null.
value_present? Returns true if value is a non-empty string.

Example

property_blueprints:
  - name: example_secret
    type: secret
    configurable: true

form_types:
  - name: example_secret
    label: 'Example form'
    description: 'An example form'
    property_inputs:
      - reference: .properties.example_secret
        label: Example Secret
        description: 'Configure a property of type secret'
        display_type: text_area

job_types:
- name: example-job
  resource_label: An Example Job
  <<: *job_type_boilerplate
  templates:
    - name: login_banner
      release: os-conf
      manifest: |
        login_banner:
          text: Shh, today's secret is (( .properties.example_secret.value )).

Example Product with Secret

Adding an additional key to the property input for a secret will allow you to use a multi-line credential.

form_types:
  - name: example_secret
    label: 'Example form'
    description: 'An example form'
    property_inputs:
      - reference: .properties.example_secret
        label: Example Secret
        description: 'Configure a property of type secret'
        display_type: text_area

Example Product with Secret

selector

Provides the ability to switch between groups of properties. Shows in the UI as a radio button group, potentially with additional options nested under each radio button.

Selectors are unique in the way that property information is accessed. Ops Manager provides accessors available at the top-level selector property, accessors for retrieving a specific property in an option group, and the ability to provide manifest snippets for a selector option group.

Each selector group may provide manifest snippets. This is because Ops Manager does not support conditionally adding manifest snippets. A manifest snippet should be present within all option groups, and can be used to create a simple kind of branching logic in manifest generation. Only one of these sets is evaluated and inserted into the job’s manifest.

credential no
supports auto-generation no
supports operator configuration yes

Property Blueprint Attributes

default Optional. Specifies a default value. When provided, must be set to a value which is valid for this type. Cannot be used when the property also has optional: true.

If specified, the default value should be one of the values of select_value.
option_templates An array of objects which defines the options available. See example below.

Accessors

value Returns the select_value string of the currently selected option group. For example, the selector shown in the example below might return “Filet Mignon” as its value.
selected_option.parsed_manifest(manifest_snippet_name) Returns a parsed named manifest snippet for the currently selected option.
Example: .properties.example_selector.selected_option.parsed_manifest(my_snippet)
SPECIFIC_SELECTOR_OPTION_GROUP.OPTION_GROUP_PROPERTY.value Scopes the accessor to a specific selector option group.
Does not return meaningful information alone. Must be followed with the name and accessor of a specific property in the option group.
Example: .properties.example_selector.filet_mignon_option.review.value
value Returns the select_value of the selected option.

Example

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 ))
                other: (( .properties.example_selector.pizza_option.other_toppings.value ))
        property_blueprints:
          - name: pepperoni
            type: boolean
            configurable: true
            freeze_on_deploy: 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 ))
              review: (( .properties.example_selector.filet_mignon_option.review.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'
          - name: review
            type: string
            configurable: true
            default: A+ power seller of mail order steak
            optional: false

form_types:
  - 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'
                description: 'Yum!'
              - 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?'
                description: 'Extinct.'
              - reference: .properties.example_selector.filet_mignon_option.review
                label: 'Write your review'
                description: '"E.g. Would not buy again"'

job_types:
- name: example-job
  resource_label: An Example Job
  <<: *job_type_boilerplate
  templates:
    - name: login_banner
      release: os-conf
      manifest: |
        login_banner:
          text: |
            Would you like some (( .properties.example_selector.value ))?
            I'm asking because you mentioned (( .properties.example_selector.pizza_option.other_toppings.value ))
          more_manifest_ignored_by_os_conf: (( .properties.example_selector.selected_option.parsed_manifest(my_snippet) ))

Example Product with a Selector

service_network_az_multi_select

This holds an arrays of string value selected from allowed availability zones (AZs).

credential no
supports auto-generation no
supports operator configuration yes

Accessors

value Returns an array of strings for the selected options.
value_present? Returns true if value is set.

Example

service_broker: true

property_blueprints:
  - name: service_instance_azs
    type: service_network_az_multi_select
    configurable: true
    optional: false

form_types:
  - name: example_service_network_az_multi_select
    label: 'Example form'
    description: 'An example form'
    property_inputs:
      - reference: .properties.service_instance_azs
        label: Example Service Network AZ Multi-Select
        description: 'Configure a property of type service_network_az_multi_select'

job_types:
- name: example-job
  resource_label: An Example Job
  <<: *job_type_boilerplate
  templates:
    - name: login_banner
      release: os-conf
      manifest: |
        login_banner:
          text: "Hello, user. Here is an array of AZ names: (( .properties.service_instance_azs.value ))"

Example Product with Service Network AZ Multi-Select

service_network_az_single_select

This holds a single string value selected from allowed azs. Appears as a radio button group in the UI.

credential no
supports auto-generation no
supports operator configuration yes

Accessors

value Returns a string or null.
value_present? Returns true if value is a non-empty string

Example

service_broker: true

property_blueprints:
  - name: example_service_network_az_single_select
    type: service_network_az_single_select
    configurable: true
    optional: false

form_types:
  - name: example_service_network_az_single_select
    label: 'Example form'
    description: 'An example form'
    property_inputs:
      - reference: .properties.example_service_network_az_single_select
        label: Example Service Network AZ Single-Select
        description: 'Configure a property of type service_network_az_single_select'

job_types:
- name: example-job
  resource_label: An Example Job
  <<: *job_type_boilerplate
  templates:
    - name: login_banner
      release: os-conf
      manifest: |
        login_banner:
          text: "Hello, user. Here is a single AZ name: (( .properties.example_service_network_az_single_select.value ))"

Example Product with Service Network AZ Single-Select

simple_credentials

This holds an identity and password.

credential yes
supports auto-generation yes
supports operator configuration yes

Property Blueprint Attributes

default Optional. Specifies a default value. When provided, must be set to a value which is valid for this type. Cannot be used when the property also has optional: true.

If specified, the default value must be an object which is allowed to have the key identity. For example, a default value could be:
default:
  - identity: ryan

Accessors

identity Returns a string
password Returns a string
value_present? Returns true if value is a non-empty string.

Example

property_blueprints:
  - name: example_configurable_simple_credentials
    type: simple_credentials
    configurable: true
  - name: example_non_configurable_simple_credentials
    type: simple_credentials
    configurable: false
    default:
      identity: vcap
form_types:
  - name: example_form
    label: 'Example form'
    description: 'An example form'
    property_inputs:
      - reference: .properties.example_configurable_simple_credentials
        label: Example configurable simple_credentials
        description: 'Configure a property of type simple_credentials'

job_types:
- name: example-job
  resource_label: An Example Job
  <<: *job_type_boilerplate
  templates:
    - name: login_banner
      release: os-conf
      manifest: |
        login_banner:
          text: |
            Shh, today's secret password is (( .properties.example_non_configurable_simple_credentials.password ))
            And the username is (( .properties.example_non_configurable_simple_credentials.identity ))

Example Product with Simple Credentials

smtp_authentication

This holds string with a possible value of plain, login, or cram_md5.

credential no
supports auto-generation no
supports operator configuration yes

Property Blueprint Attributes

default Optional. Specifies a default value. When provided, must be set to a value which is valid for this type. Cannot be used when the property also has optional: true.

Accessors

value Returns a string with possible value of plain, login, cram_md5.
value_present? Returns true if value is a non-empty string.

Example

property_blueprints:
  - name: example_smtp_authentication
    type: smtp_authentication
    configurable: true
    default: plain

form_types:
  - name: example_text
    label: 'Example form'
    description: 'An example form'
    property_inputs:
      - reference: .properties.example_smtp_authentication
        label: Example SMTP Authentication
        description: 'Configure a property of type smtp_authentication'

job_types:
- name: example-job
  resource_label: An Example Job
  <<: *job_type_boilerplate
  templates:
    - name: login_banner
      release: os-conf
      manifest: |
        login_banner:
          text: Hello. The SMTP auth type is (( .properties.example_smtp_authentication.value ))

Example Product with SMTP Authentication

string_list

This holds an array of strings.

credential no
supports auto-generation no
supports operator configuration yes

Property Blueprint Attributes

default Optional. Specifies a default value. When provided, must be set to a value which is valid for this type. Cannot be used when the property also has optional: true.

Accessors

parsed_strings Returns an array of strings for each string entry
parsed_regex Returns a string containing a regex of the format ^(string1|string2|string3)$ where the value of this property is string1,string2,string3
value Returns a string or null.
value_present? Returns true if value is a non-empty string.

Example

property_blueprints:
  - name: example_string_list
    type: string_list
    configurable: true
    default: foo,bar,baz

form_types:
  - name: example_string_list
    label: 'Example form'
    description: 'An example form'
    property_inputs:
      - reference: .properties.example_string_list
        label: Example String List
        description: 'Configure a property of type string_list'

job_types:
- name: example-job
  resource_label: An Example Job
  <<: *job_type_boilerplate
  templates:
    - name: login_banner
      release: os-conf
      manifest: |
        login_banner:
          text: Hello. Your array of strings is (( .properties.example_string_list.value ))

Example Product with String List

string

This holds a single string value.

credential no
supports auto-generation no
supports operator configuration yes

Property Blueprint Attributes

constraints.must_match_regex A regular expression that the user input must match. 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. See the example below for example on how to use.

Accessors

value Returns the string value or null.
value_present? Returns true only if the value is a non-empty string.

Example

property_blueprints:
  - name: example_string
    type: string
    configurable: true
    default: 'Karl'
    constraints:
    - must_match_regex: 'A[^!@#$%^&*()]*z'
      error_message: 'This name cannot contain special characters.'
    - must_match_regex: 'A[^0-9]*z'
      error_message: 'This name cannot contain digits.'

form_types:
  - name: example_form
    label: 'Example form'
    description: 'An example form'
    property_inputs:
      - reference: .properties.example_string
        label: 'Example string'
        description: 'This is an example'

job_types:
- name: example-job
  resource_label: An Example Job
  <<: *job_type_boilerplate
  templates:
    - name: login_banner
      release: os-conf
      manifest: |
        login_banner:
          text: Hello, (( .properties.example_string.value ))! Welcome.

Example Product with String Information

text

This holds a string value. For configurable properties of this type, the UI allows multi-line strings to be entered.

credential no
supports auto-generation no
supports operator configuration yes

Property Blueprint Attributes

default Optional. Specifies a default value. When provided, must be set to a value which is valid for this type. Cannot be used when the property also has optional: true.

Accessors

value Returns a string or null.
value_present? Returns true if value is a non-empty string.

Example

property_blueprints:
  - name: example_text
    type: text
    configurable: true
    default: |
      Example
      Text

form_types:
  - name: example_text
    label: 'Example form'
    description: 'An example form'
    property_inputs:
      - reference: .properties.example_text
        label: Example Text
        description: 'Configure a property of type text'

job_types:
- name: example-job
  resource_label: An Example Job
  <<: *job_type_boilerplate
  templates:
    - name: login_banner
      release: os-conf
      manifest: |
        login_banner:
          text: |
            Hello. Check out all this text!
            (( .properties.example_text.value ))

Example Product with Text

uuid

This holds a string uuid value.

credential no
supports auto-generation yes
supports operator configuration no

Accessors

value Returns a string or null.
value_present? Returns true if value is a non-empty string.

Example

property_blueprints:
  - name: example_uuid
    type: uuid
    configurable: false

job_types:
- name: example-job
  resource_label: An Example Job
  <<: *job_type_boilerplate
  templates:
    - name: login_banner
      release: os-conf
      manifest: |
        login_banner:
          text: Hello. Your UUID is (( .properties.example_uuid.value ))

vm_type_dropdown

This holds single string value selected from allowed vm_types.

credential no
supports auto-generation no
supports operator configuration yes

Property Blueprint Attributes

resource_definitions Optional. An array of objects with the same schema as resource_definitions for job_types. For vm_type_dropdown, resource_definitions can have elements with name “ram”, “cpu”, or “ephemeral_disk”. This element can also specify a default which OpsManager uses as a minimum bound when it selects a default value. It can also specify constraints, which can be any set of constraints that can be specified for an integer property.For examples of supported constraint types, see integer above. See example above.

Accessors

value Returns a string which is the name of the selected VM type.

Example

property_blueprints:
  - name: example_vm_type_dropdown
    type: vm_type_dropdown
    configurable: true
    resource_definitions:
    - name: ram
      default: 4096
    - name: cpu
      default: 1
    - name: ephemeral_disk
      default: 4096
      constraints:
        min: 2048

form_types:
  - name: example_vm_type_dropdown
    label: 'Example form'
    description: 'An example form'
    property_inputs:
      - reference: .properties.example_vm_type_dropdown
        label: Example VM Type Dropdown
        description: 'Configure a property of type vm_type_dropdown'

job_types:
  - name: example-job
    resource_label: An Example Job
    <<: *job_type_boilerplate
    templates:
      - name: login_banner
        release: os-conf
        manifest: |
          login_banner:
            text: Hello. Your chosen VM Type is (( .properties.example_vm_type_dropdown.value )).

Example Product with VM Types Dropdown

wildcard_domain

Ensures the string value is a domain prefixed with *..

credential no
supports auto-generation no
supports operator configuration yes

Property Blueprint Attributes

default Optional. Specifies a default value. When provided, must be set to a value which is valid for this type. Cannot be used when the property also has optional: true.

Accessors

to_wildcard Returns a string of the value prefixed with *. if not present
value Returns a string or null.
value_present? Returns true if value is a non-empty string.

Example

property_blueprints:
  - name: example_wildcard_domain
    type: wildcard_domain
    configurable: true
    default: 'example.com'

form_types:
  - name: example_form
    label: 'Example form'
    description: 'An example form'
    property_inputs:
      - reference: .properties.example_wildcard_domain
        label: Example Wildcard Domain
        description: 'Configure a property of type wildcard_domain'

job_types:
  - name: example-job
    resource_label: An Example Job
    <<: *job_type_boilerplate
    templates:
    - name: login_banner
      release: os-conf
      manifest: |
        login_banner:
          text: Hello. Your wildcard domain is (( .properties.example_wildcard_domain.value )).

Example Product with Wildcard Domain

Using the Examples Provided

You can copy each example into the metadata.yml template below and package it together along with the os-conf release as a .pivotal file to make a working tile.

---
name: p-example
label: Example Tile
description: An example tile
product_version: '1.1'
minimum_version_for_upgrade: '1.0'
metadata_version: '2.2'
rank: 1
 stemcell_criteria:
  os: ubuntu-xenial
  version: '97.3'
 releases:
  - name: os-conf
    file: os-conf
    version: '15'
 # a base 64 encoded PNG with a teal square
icon_image: iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVQI12NgaC8BAAGGAPwUz8ygAAAAAElFTkSuQmCC

 includes: # This top-level key will be ignored by OpsManager.
  # This anchor is only to make the examples below more terse, and is not required.
  job_type_boilerplate: &job_type_boilerplate
    max_in_flight: 1
    single_az_only: true
    resource_definitions:
      - name: ram
        configurable: true
        default: 1024
       - name: ephemeral_disk
         configurable: true
         default: 1024
       - name: persistent_disk
         configurable: true
         default: 1024
         constraints:
           min: 1024
       - name: cpu
         configurable: true
         default: 1
     instance_definition:
      name: instances
      configurable: true
      default: 1
Create a pull request or raise an issue on the source for this page in GitHub