Property Reference

Page last updated:

This topic explains how PCF Tiles describe properties.

Double-Parentheses Expressions

The product template .yml file in a tile’s metadata subdirectory defines how the tile interface collects configurable properties from the user, and how Ops Manager incorporates these properties into the deployment manifest that it creates.

The product template contains manifest snippets in both the form_types section that defines the tile interface, and the job_types section describing the jobs that the manifest deploys. Within these snippets, you can use special expressions to include property values that are otherwise not known ahead of time, such as configurable properties or system properties:

  • Double-parentheses expressions designate property values that Ops Manager fills in when it generates the deployment manifest, after the user clicks Apply Changes. These values include configurable properties and properties supplied by Ops Manager.

  • Triple-parentheses expressions designate property values that BOSH supplies when it deploys instances of the tile service, such as CredHub credentials.

Referencing Properties

Evaluating a property can be represented by piecing two segments together:

  • The location of the property
  • What information from the property you are looking to access, or accessors

Together, the double-parentheses expression can be written as:

(( LOCATION_OF_PROPERTY.ACCESSOR ))

The method of referencing the location of the property varies. Here is a complete list of ways to reference a property with some help text to indicate the situation.

.properties.top_level_property Refers to the property blueprint whose name is “top_level_property” found in the global list of properties of the same product
.job_one.job_level_property Refers to the property blueprint whose name is “job_level_property” found in the list of properties of the job “job_one” of the same product
job_level_property Refers to the property blueprint whose name is “top_level_property” found in the same product and job whose manifest is currently being evaluated
..other_product.properties.top_level_property Refers to the property blueprint whose name is “top_level_property” found in the global list of properties of the product “other_product”
..other_product.job_two.job_level_property Refers to the property blueprint whose name is “job_level_property” found in the list of properties of the job “job_one” of the product “other_product”

Accessors vary between property blueprint types. See the Property Blueprint Reference for available properties and their accessors.

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

Dollar Contexts

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

  • $ops_manager: used by any product to obtain information about specific OpsManager
  • $director: used by any product to obtain information about the Director
  • $runtime: used by any product to obtain information about the CF tile (Pivotal Application Service)
  • $self: used by your own product to obtain information about your product’s 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 are applied by the Director to all VMs
http_proxy Provides the comma separated values that are entered if Ops Manager traffic is directed to an HTTP Proxy
https_proxy Provides the comma separated values that are entered if Ops Manager traffic is directed to an HTTPS Proxy
no_proxy Provides the comma separated values that should not go through a proxy
dns_enabled Provides boolean flag indicating if BOSH DNS is enabled

$director

deployment_ip Provides the IP address that the BOSH Director is deployed on
username Provides the username for the Director VM
passwordProvides the password for the Director VM
ntp_serversProvides a list of ntp servers that are deployed by the Director
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

Note: Support for the $director.username and $director.password accessors will be removed in future versions of Ops Manager.

$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 that has been assigned to your product
stemcell_version Provides the stemcell version that is being used by your product

Property Reference Guide

Below is a reference to every property blueprint type.

Common property blueprint attributes

All property blueprints may 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, OpsManager 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 true, for property types which support operator configuration, the operator will be allowed to configure this value. Please do not set configurable: true for property types which do not support operator configuration.

When set to false, OpsManager 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, OpsManager 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, OpsManager 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 then the operator will be able to configure the value of that property. Alternatively, a property can have configurable: false and will have a value auto-generated by OpsManager. 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.

The following example uses a named manifest called for_routing that belongs to the certificate_collection job:

- 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 below about Selector and Collection types.

All Property Blueprint Types

boolean

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

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

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

Holds 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. See example 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

Holds a string value which 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 nil
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

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

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

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

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 example below for all supported constraint types.

Accessors

value Returns an integer, or nil
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 nil
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

Holds a string which 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 nil
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 nil
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

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

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

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

Holds a single integer value. Allowed values are 0 through 65535, and nil.

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 nil
value_present? Returns true if value is not nil

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

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, and returns false if the value is nil

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

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 has been generated already

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

Holds credentials with salt and hashed password. 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

Holds a single string value

credential yes
supports auto-generation yes
supports operator configuration yes

Accessors

value Returns the secret as a string, or nil
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

Holds an arrays of string value selected from allowed 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

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

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

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

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

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

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

Holds a string uuid value

credential no
supports auto-generation yes
supports operator configuration no

Accessors

value Returns a string, or nil
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

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. See example below.

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

Each example can be copied into the following metadata.yml skeleton and packaged 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-trusty
  version: '3586.24'

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


# end of boilerplate
# paste the property example here