How tiles work

Learn about how a service tile works in Tanzu Operations Manager.

You can use product tiles to offer new and upgraded software services to developers in a Tanzu Operations Manager deployment. Broadcom Support portal distributes these tiles as zipped code directories, with the .pivotal filename extension. They contain or point to all of the software elements that use the tile’s functions.

This topic explains what each functional element of a tile does and how you create or specify it as input to the Tile Generator tool that creates .pivotal files. It also describes the typical structure of a tile directory. This helps in editing generated tiles or legacy tiles that were created without the Tile Generator.

For more information about the Tile Generator, see Tile Generator.

Tile functions

The Tanzu Operations Manager service tiles perform multiple functions that streamline the use of software services, including:

• Deploy a service broker that interfaces between the Cloud Controller, VMware Tanzu Application Service for VMs’s main executive component, and the service. For more information, see Service Broker.

• Publish a catalog of available service plans to the Services Marketplace. For more information, see Catalog.

• Define an interface for configuring service properties in Tanzu Operations Manager. For more information, see Configuration.

• Generate a BOSH manifest for deploying instances of the service, populating it with both user-configured and fixed properties. For more information, see Fixed Properties.

• Run BOSH errands: Deploy errands that set up TAS for VMs to run the service when an operator first deploys the service, and then delete errands that clean up when an operator deletes the service. For more information, see Errands.

• Define dependencies for the tile to prevent Tanzu Operations Manager from installing the service when its dependencies are missing. For more information, see Dependencies.

• Support one-click installation and upgrading from previous versions. For more information, see Update Rules.

These functions are described in more detail here:

Service broker

Service brokers integrate services with TAS for VMs by providing an API for the Cloud Controller to create service instances, bind them to apps, and perform other operations. For more information about requirements for this API, see Service Broker API.

Each service tile acts as a wrapper for a service broker. Installing the tile creates the service broker, registers it with the Cloud Controller, and publishes the service plans that the broker offers. For more information, see Catalog.

You can write a service broker in any language, and it can run anywhere, inside your TAS for VMs installation or external. For sample code in Ruby, Java, and Go, see Example Service Brokers.

Specify the service broker for a tile in the tile directory’s tile.yml file, as a package with type set to app-broker, docker-app-broker, or external-broker. The external-broker type requires a uri value for the service broker location. For more information, see Packages.

Catalog

Service brokers include catalog metadata that lists their service plans. This information publishes to the Marketplace that app developers use to browse and select services.

Developers on either TAS for VMs or open-source Cloud Foundry can see a plain-text version of the Marketplace by running cf marketplace. But TAS for VMs also features a graphical Marketplace, and service brokers support this Marketplace with additional catalog metadata text boxes for display names, logo images, and links to more information and documentation.

Define this catalog metadata for your service by writing your service broker to return the API calls listed in the Service Metadata section of Open Service Broker API Profile (v2.16) in the Open Service Broker API repository on GitHub.

Configuration

In the Tanzu Operations Manager Installation Dashboard, service tiles present a form-based interface that you can use to configure the service. These configured properties become part of the BOSH manifest that Tanzu Operations Manager uses to deploy instances of the service.

You define this configuration interface in the forms section of the tile.yml configuration file that you pass to the Tile Generator. Each named form element defines a configuration pane accessible under the Settings tab of the tile.

The drop-down menu lists all configuration panes and indicates with check marks which have been configured. The drop-down menu includes service-specific panes, defined by the tile developer, between system-level panes like Assign AZs and Networks and Resource Config that all Tanzu Operations Manager products and services use.

Each form, or configuration pane, uses label for the menu text, a description to appear at the top, and property_inputs that define the configuration text boxes themselves. To construct your forms, see Property and Template References.

For each property, you can combine specifications for name, type, default, configurable, options, and constraints. For more information, see the Form Properties and Property Blueprints sections of the Property and Template References topic.

Note In the tile installer YAML file that Tile Generator creates, form properties appear in two locations: a form_types section that defines the contents and layout of the configuration interface, and a property_blueprints section that defines the corresponding text box value types and constraints.

Tile appearance

In the Tanzu Operations Manager Installation Dashboard, your service tile has an identifying label, description, and logo icon. Specify these at the top of your tile.yml configuration file as label, description, and icon_file. The value of icon_file can be the name of a 128×128 pixel PNG image file.

Fixed properties

A tile writes fixed, unconfigurable properties into the BOSH manifest that it creates. You can specify these properties in your tile.yml configuration file using double parentheses expressions format.

For more information, see the Double Parentheses Expressions section of the Property and Template References topic.

Credentials

Include credentials to pass into a BOSH manifest as salted_credentials in your tile.yml file. You do not need to include credentials that already exist in other tiles, such as the TAS for VMs tile. BOSH automatically generates credentials for any packages that require them.

Errands

Tile Generator automatically generates deploy and delete life cycle errands for packages that deploy to Tanzu Operations Manager. These errand scripts deploy the service and publish the plans in the Marketplace, and they are also used to remove the service from Tanzu Operations Manager and the Marketplace.

You can define additional post_deploy and pre_delete errand scripts in tile.yml file that prepare Cloud Foundry to host the service or clean up before deleting it. You can configure these errands to run on their own dedicated VMs or you can co-locate them on existing errand VMs.

For bosh-release and docker-bosh packages, which run jobs directly on BOSH rather than on the Tanzu Operations Manager layer, you need to include post_deploy and pre_delete errands with their package definitions in the tile.yml file. Label them as life cycle errands using lifecycle: errand and either post_deploy: true or pre_delete: true.

Tile Generator writes the bosh-release errands into the main BOSH release that it creates for the service, and adds docker-bosh errands into a separate Docker BOSH release that the main release depends on.

Dependencies

You can include both required and optional product dependencies for tiles.

• Required dependencies: Required dependencies are always required. To deploy the dependent tile, you must also deploy the dependency.

• Optional dependencies: Optional dependencies are required only if you upload both the dependent tile and the optional dependency to your environment. For example, a tile can be dependent on either TAS for VMs or Tanzu Kubernetes Grid Integrated Edition (TKGI). If you define TAS for VMs and TKGI as optional dependencies, you can upload either TAS for VMs or TKGI to successfully deploy the dependent tile.

Note After the dependency is installed, it is mandatory even if it is marked as optional.

Include product dependencies under requires_product_versions at the top of the tile.yml file. To add an optional dependency, use an optional text box under requires_product_versions.

For example:

requires_product_versions:
  - name: cf
    version: 2
    optional: false
  - name: pks
    version: 1.5
    optional: true

Update rules

Tile Generator automatically generates the JavaScript migration file that allows one-click updates from Tanzu Operations Manager. This file describes how to change existing tile property names and values to match the new version of the tile.

A tile can contain several of .js files, from previous versions and the current one, to allow tile updates to automatically chain together in sequence.

You can add custom update code in the tile.yml Tile Generator configuration file, following the properties documented in Update values or property names using JavaScript in Upgrading Tiles.

Tile file format and structure

Tile directories contain the following components, with sub-components as shown:

• BOSH release
  • Service source code
  • Service broker
  • Language-specific buildpack(s)
  • Errands (service start and stop scripts)
  • BOSH manifest (deployment properties for service)
    • Packages
    • Dependencies
• Tile manifest template (adds properties into BOSH manifest)
  • Configuration forms and properties
  • Catalog metadata (for the Marketplace)
• Migrations

The three required top-level subdirectories in a .pivotal tile directory are:

• metadata: High-level information for configuring and publishing your service.
• migrations: Rules that govern tile upgrades.
• releases: The BOSH releases that deploy your service.

The tile manifest template defines these subdirectory locations, so they can reside anywhere in the directory, but the typical structure looks like this:

.
├── example-product
│   ├── metadata
│   │   └── example-product.yml
│   ├── migrations
│   │   └── v1
│   │       ├── 201512301616_convert_14_transmogrifier_rules.js
│   │       ├── 201512301631_convert_15_16_transmogrifier_rules.js
│   │       └── 201611060205_example_migration.js
│   └── releases
│       └── example-release-18.tgz

.pivotal file format

The entire tile directory is a ZIP file, with the .zip extension renamed to .pivotal.

$ file TILE-NAME-TILE-VERSION.pivotal
p-example-product-1.0.0.pivotal: Zip archive data, at least v1.0 to extract

Where:

• TILE-NAME is the name of the tile.
• TILE-VERSION is the version of the tile.

You can use any ZIP utility to create a .pivotal file. Ensure that the top-level subfolders, as seen above in the example-product folder, remain.

In the releases subfolder for the file, the BOSH release exists as a gzipped tar file.

Example workflow

$ cd example-product
$ zip -r example-product.pivotal metadata/ migrations/ releases/
$ unzip -l example-product.pivotal
Archive:  example-product.pivotal
  Length     Date   Time    Name
 --------    ----   ----    ----
        0  08-09-16 16:10   metadata/
    89458  08-09-16 16:10   metadata/example-product.yml
        0  07-08-16 09:32   migrations/
        0  07-08-16 09:32   migrations/v1/
      423  07-08-16 09:32   migrations/v1/201512301616_convert_14_transmogrifier_rules.js
     1228  07-08-16 09:32   migrations/v1/201512301631_convert_15_16_transmogrifier_rules.js
      582  07-08-16 09:32   migrations/v1/201611060205_example_migration.js
        0  08-09-16 16:11   releases/
        0  07-12-16 17:19   releases/example-release-18.tgz

GitHub repository structure

Tile developers typically develop and archive their code on GitHub, and their Concourse build pipeline pulls from GitHub to perform continuous integration.

Tile Generator does not dictate any directory structure for a GitHub repository, but by convention your tile repository might look like this:

/tile.yml
/src        # source code for all components deployed by the tile
/resources  # other resources, such as icon images and imported Docker images or bosh releases
/release    # generated bosh release(s)
/product    # generated tile

Packages

TAS for VMs services typically require multiple component job processes to run concurrently, such as a main app, a helper app, and a service broker. They also require buildpacks that run as one-time compilation tasks. Services also require components, such as external brokers or storage, that do not run as jobs but must remain available.

The tile yml file that you pass to Tile Generator defines these service components in the packages: section. Each package has a name and a package type. The list of possible package types to pass to Tile Generator is in the Tile Generator code on GitHub.

It includes:

• app: Pushed to TAS for VMs

• docker-app: Pushed to TAS for VMs (image is not embedded, so this package type requires Docker registry access).

• app-broker: Pushed to TAS for VMs and registered as a broker.

• docker-app-broker: Pushed to TAS for VMs and registered as a broker. Image is not embedded, so this package type requires Docker registry access.

• external-broker: Registered as a broker.

• buildpack: Installed with cf create-buildpack. Runs as a one-time task rather than a long-running process.

• docker-bosh: Describes a collection of Docker images that embed in the tile and run on BOSH-managed VMs, not TAS for VMs.

• bosh-release: An existing BOSH release wrapped in a tile, to run on BOSH-managed VMs, not TAS for VMs. Requires you to describe all jobs (long-running processes and errands).

Packages typically contain a single process, but can include more than one, packaged to run in the same location.

Where Package processes run

Where packaged processes run depends on their package type, as follows:

• app, docker-app, app-broker, and docker-app-broker packages call cf push to run processes in containers on a Diego Cell.

• docker-bosh and bosh-release packages run their processes on VMs in the underlying BOSH layer.

• external-broker and buildpack packages run one-time tasks (not long-running processes) on Diego Cells.

Package VM resources

You can use the service tile’s Resource Config pane to configure resources individually for each package. You can also provision resources for VMs that handle one-time tasks, with the acceptance-tests, deploy-all, and delete-all rows.