-
Notifications
You must be signed in to change notification settings - Fork 23
/
tile-structure.html.md.erb
218 lines (139 loc) · 14 KB
/
tile-structure.html.md.erb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
---
title: How Tiles Work
owner: Services
---
<strong><%= modified_date %></strong>
Product tiles make it easy for cloud operators to offer new and upgraded software services to developers in a Pivotal Cloud Foundry (PCF) deployment. [Pivotal Network](https://network.pivotal.io) distributes these tiles as zipped code directories, with filename extension `.pivotal`, that contain or point to all of the software elements that perform 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](./tile-generator.html) tool that creates `.pivotal` files.
This topic also describes the typical [structure](#structure) of a tile directory. This is useful information for modifying generated tiles or legacy tiles that were created without the Tile Generator.
## <a id='functions'></a>Tile Functions
PCF service tiles perform multiple functions that streamline the use of software services on PCF, including:
* Deploy a [service broker](#broker) that interfaces between the Cloud Controller, PCF's main executive component, and the service.
* [Publish a catalog](#catalog) of available service plans to the **Services Marketplace**.
* Define an interface for [configuring service properties](#configure) in Ops Manager.
* Generate a BOSH manifest for deploying instances of the service, populating it with both user-configured and [fixed](#fixed) properties.
* Run BOSH [errands](#errands): deploy errands that set PCF up to run the service when an operator first deploys the service, and delete errands that clean up when an operator deletes the service.
* Define [dependencies](#dependencies) for the tile, to prevent Ops Manager from installing the service when its dependencies are missing.
* Support one-click installation and [upgrading](#upgrading) from previous versions.
These functions are described in more detail below.
### <a id='broker'></a> Service Broker
Service brokers integrate services with PCF by providing an API for the Cloud Controller to create service instances, bind them to apps, and perform other operations. The [Service Broker API v2.10](http://docs.pivotal.io/pivotalcf/services/api.html) topic specifies requirements for this API.
Each service tile acts as a wrapper for a service broker. Installing the tile creates its service broker, registers it with the Cloud Controller, and [publishes](#catalog) the service plans that the broker offers.
You can write a service broker in any language, and it can run anywhere, inside your PCF installation or external. See [Example Service Brokers](http://docs.pivotal.io/pivotalcf/services/examples.html) for sample code in Ruby, Java, and Go.
Specify the service broker for a tile in the tile directory's `tile.yml` file, as a [package](#packages) 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.
#### <a id='catalog'></a> Catalog
Service brokers include [catalog metadata](http://docs.pivotal.io/pivotalcf/services/catalog-metadata.html) that list their service plans. This information publishes to the Marketplace that app developers use to browse and select services.
Developers on either PCF or open-source Cloud Foundry see a plain-text version of the Marketplace by running `cf marketplace`.
But PCF also features a graphical Marketplace, and PCF service brokers support this Marketplace with additional catalog metadata fields 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 [Catalog Metadata](http://docs.pivotal.io/pivotalcf/services/catalog-metadata.html) topic.
### <a id='configure'></a> Configuration
In the Ops Manager Installation Dashboard, service tiles present a form-based interface that cloud operators use to configure the service. These configured properties become part of the BOSH manifest that PCF 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 tile's **Settings** tab.
A left-side menu lists all configuration panes and indicates with check marks which ones have been configured. The menu lists service-specific panes, defined by the tile developer, between system-level panes like **Assign AZs and Networks** and **Resource Config** that all PCF products and services use.
Each form, or configuration pane, has `label` for the menu text, a `description` to appear up top, and `property_inputs` that define the configuration fields themselves. Construct your `forms` by following the [Product Template Reference](./product-template-reference.html) topic and the [Property Blueprint Reference](./property-reference.html#property-ref) section of the About PCF Tiles topic.
For each property, you can combine specifications for `name`, `type`, `default`, `configurable`, `options`, and `constraints`, under both the [Form Properties](./product-template-reference.html#form-properties] and [Property Blueprints](./product-template-reference.html#property-blueprints) sections of the topic.
<p class="note"><strong>Note</strong>: In the tile installer <code>.yml</code> that Tile Generator creates, form properties appear in two locations: a <code>form_types</code> section that defines the contents and layout of the configuration interface, and a <code>property_blueprints</code> section that defines the corresponding field value types and constraints.</p>
#### <a id='appearance'></a> Tile Appearance
In the Ops Manager Installation Dashboard, your service tile bears 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` should be the name of a 128×128 pixel PNG image.
### <a id='fixed'></a> Fixed Properties
A tile also writes fixed, unconfigurable properties into the BOSH manifest that it creates. You specify these properties in your `tile.yml` configuration file using [Double-Paren Expressions](./property-reference.html#expressions) format.
#### <a id='credentials'></a> Credentials
Include credentials to pass into a BOSH manifest as `salted_credentials` in your `tile.yml` file. But you need not include credentials that already exist in other tiles, such as Elastic Runtime. BOSH automatically generates these for any packages that require them.
### <a id='errands'></a> Errands
Tile Generator automatically generates `deploy` and `delete` lifecycle errands for [packages](#packages) that deploy to PCF.
These errand scripts deploy the service to PCF and publish its plans in the Marketplace, and remove the service from PCF and the Marketplace.
You can also define additional `post_deploy` and `pre_delete` errand scripts in `tile.yml` that prepare PCF to host the service or clean up before deleting it. You can configure these errands to run on their own dedicated VMs or co-locate them on existing errand VMs.
For `bosh-release` and `docker-bosh` packages, which run jobs directly on BOSH rather than on the PCF layer, you need to include `post_deploy` and `pre_delete` errands with their package definitions in `tile.yml`. Label them as lifecycle 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.
### <a id='dependencies'></a> Dependencies
Include product dependencies under `requires_product_versions` at the top of your `tile.yml` file.
### <a id='update'></a> Update Rules
Tile Generator automatically generates the JavaScript migration file that enables one-click updates from Ops Manager. This file describes how to change existing tile property names and values in order to match the new version of the tile.
A mature tile may contain several of these `.js` files, from previous versions and the current one, to enable 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 the [Migrating Tile Versions](./tile-upgrades.html#import) topic.
## <a id='structure'></a>Tile File Format and Structure
Tile directories contain the following components, which include each other 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
```
### <a id='dot-pivotal'></a>.pivotal File Format
Within the tile directory, the BOSH release exists as a gzipped tarfile.
The entire tile directory is also a gzipped tarfile, with the `.tgz` extension renamed to `.pivotal`.
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.
#### Example Workflow
<pre class='terminal'>
$ 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
</pre>
### <a id='repo'></a>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
```
### <a id='packages'></a>Packages
PCF 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, which do not run as jobs, but nevertheless need to remain available.
The `tile yml` file that you pass to Tile Generator defines these service components it its `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](https://github.com/cf-platform-eng/tile-generator/blob/master/tile_generator/config.py#L59-L70). It includes:
* app - `cf push`ed to PCF
* docker-app - `cf push`ed to PCF (image will not be embedded so requires Docker registry access)
* app-broker - `cf push`ed to PCF and registered as a broker
* docker-app-broker - `cf push`ed to PCF and registered as a broker (image is not embedded, so 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 PCF
* bosh-release - a pre-existing BOSH release wrapped in a tile, to run on BOSH-managed VMs, not PCF; 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).
#### <a id='where'></a>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.
#### <a id='process'></a>Package VM Resources
The service tile's **Resource Config** pane lets the operator configure resources individually for each package. This pane also lets operators provision resources for VMs that handle one-time tasks, with the `acceptance-tests`, `deploy-all`, and `delete-all` rows.
