forked from mboldt/docs-tiledev
-
Notifications
You must be signed in to change notification settings - Fork 0
/
tile-generator.html.md.erb
834 lines (682 loc) · 28.9 KB
/
tile-generator.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
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
---
title: Tile Generator
owner: Services
---
This topic describes the Tile Generator tool, which helps tile authors develop, package, test, and deploy services and other add-ons to <%= vars.platform_name %>.
## <a id="overview"></a> Overview
Tiles are the
installation package format used by Ops Manager to deploy services and other add-ons to both public and private cloud deployments. Tile Generator
uses templates and patterns that are based on years of experience integrating
third-party services into Cloud Foundry and eliminates much of the need for
you to have intimate knowledge of all the tools involved.
![Overview](img/tilegenerator.png)
Tile Generator takes your software components and a simple configuration file
that provides the minimal amount of information to describe and customize your
tile. It then creates everything that's required to deploy your software into
<%= vars.platform_name %>:
- **BOSH errands** to deploy and delete your software, including blue/green
deployments for zero-downtime upgrades
- A **BOSH release** suitable for deploying your software to <%= vars.app_runtime_full %> (<%= vars.app_runtime_abbr %>) or open-source Cloud Foundry
- An **Ops Manager Tile** that can be imported into Ops Manager, installed,
configured, and deployed, including UI forms and automatic upgrades from
previous versions
- A **Concourse pipeline configuration** to enable Continuous Integration of
your software with the latest versions of <%= vars.platform_name %>
Use Tile Generator in combination with the [pcf utility](pcf-command.html)
to enable rapid deploy and test cycles of your software.
The current release of Tile Generator supports tiles that have any
combination of the following package types:
- Cloud Foundry Applications
- Cloud Foundry Buildpacks
- Cloud Foundry Service Brokers (both inside and outside <%= vars.app_runtime_abbr %>)
- Docker images (both inside and outside <%= vars.app_runtime_abbr %>)
### <a id="legacy"></a> Legacy Tiles and OSS-Compatible Service Brokers
Many tile authors, in both <%= vars.company_name %>-internal teams and at external partner companies, built their <%= vars.platform_name %> tiles before Tile Generator existed.
Many other tile authors serve two markets with their service integrations, offering both a Cloud Foundry-compatible service broker to open-source users and corresponding <%= vars.platform_name %> tile for <%= vars.app_runtime_abbr %> users.
They want to continue serving both sets of users.
All of these tile authors can now use Tile Generator to simplify and speed up their development. Tile Generator can generate an OSS-compatible BOSH release service broker BOSH release in addition to a VMware Tanzu-ready <%= vars.platform_name %> tile.
## <a id="screencast"></a> Screencast
For a 7-minute introduction into what Tile Generator is and does, see
[this screencast](https://www.youtube.com/watch?v=_WeJbqNJWzQ).
## <a id="how-to"></a> How to Use
1. Install the Tile Generator by doing one of the following:<br><br>
- Download the Tile Generator binary for your platform from
[GitHub](https://github.com/cf-platform-eng/tile-generator/releases/latest),
and then make it executable and available by running the following commands:
```
chmod +x TILE-BINARY
mv TILE-BINARY /usr/local/bin/tile
```
Where:<br>
`TILE-BINARY` is the name of the tile binary file.<br><br>
For example:
<pre class="terminal">
chmod +x tile_darwin-64bit
mv tile_darwin-64bit /usr/local/bin/tile
</pre>
<br>
- Use Python 2 and [Virtualenv](https://virtualenv.pypa.io/en/stable/).
<%= vars.company_name %> recommends using a Virtualenv environment
to avoid conflicts with other Python packages.
<br><br>
A virtualenv is a directory containing dependencies for a project.
When a virtual environment is active, packages install into the
virtualenv instead of the system-wide Python installation.
<br><br>
To use this method run the following commands:
virtualenv -p python2 tile-generator-env
source tile-generator-env/bin/activate
pip install tile-generator
This puts the `tile` and `pcf` commands in your `PATH` when the virtualenv is active.
To deactivate the virtualenv, run the command `deactivate`.
<p class="note"><strong>Note</strong>: To upgrade Tile Generator, run <code>pip install tile-generator --upgrade</code>
with the virtualenv activated.</p>
2. Install the [BOSH CLI](https://bosh.io/docs/cli-v2.html).
3. From within the root directory of the project for which you want to create a tile,
initialize the directory as a tile repository by running the following commands:
<p class="note"><strong>Note</strong>: <%= vars.company_name %> recommends that you use a git repository.</p>
```
cd YOUR-PROD-DIRECTORY
tile init
```
4. Edit the generated `tile.yml` file to define your tile.
5. Build your tile by running:
tile build
The generator first creates a BOSH release in the `release` subdirectory,
then wraps that release into a tile, in the `product` subdirectory.
If required for the installation, it automatically pulls down the latest
release version of the Cloud Foundry CLI.
Tile Generator is also available pre-installed in a Docker image on
[Docker Hub](https://hub.docker.com/r/cfplatformeng/tile-generator/).
This image contains the tile-generator `tile` and `pcf` commands, the
necessary Python dependencies and the BOSH CLI.
You can use this in Concourse pipelines by specifying it as the base image
for your tasks:
```
- task: tile-build
config:
platform: linux
image: cfplatformeng/tile-generator
```
Or, you can derive your own Docker images from this one by using it as the base
image in your Dockerfile:
```
FROM cfplatformeng/tile-generator
```
## <a id="sample"></a> Build the Sample
The [tile-generator repository](https://github.com/cf-platform-eng/tile-generator) includes a [sample tile](https://github.com/cf-platform-eng/tile-generator/tree/master/sample) that exercises most of the features of Tile Generator. This sample tile is used by Tile Generator's CI pipeline to verify that things work correctly.
You can build this sample using the following steps:
1. Download the [Redis BOSH release](https://github.com/cloudfoundry-community/redis-boshrelease/releases/tag/v13.1.2) and save it to `sample/resources/redis-13.1.2.tgz`.
1. Run the following commands:
```bash
cd sample
src/build.sh
tile build
```
<p class="note"><strong>Note</strong>: The sample tile includes a Python app that is re-used in several packages,
sometimes as an app, sometimes as a service broker. One of the deployments (app3)
uses the sample app inside a Docker image that is currently only modified
by the CI pipeline. If you modify the sample app, you have to build your own
Docker image using the provided <code>Dockerfile</code> and change the image name in
<code>sample/tile.yml</code> to include the modified code in app3.</p>
## <a id="define"></a> Define your Tile in <i>tile.yml</i>
All required configuration for your tile is in the file called `tile.yml`.
`tile init` creates an initial version for you that can serve as a template.
### <a id="branding"></a> Branding
The first section in the file describes the branding of your tile:
```yaml
name: tile-name # Match VMware Tanzu Network product name, lowercase with dashes
icon_file: resources/icon.png
label: Brief Text for the Tile Icon
description: Longer description of the tile's purpose
```
- The `name` should be informative.
For example, you might want to use a name composed of your company and product names such as `acme-anvil`.
The name should also match your product slug on
VMware Tanzu Network, which enables update notifications for customers. Coordinate
with your product team to agree on a name; marketing teams often care about the
name because it appears in VMware Tanzu Network URLs.
- The `icon_file` should be a 128 x 128 pixel image that appears on your tile in the Ops Manager UI.
By convention, place any resources used by the tile in the `resources` sub-directory of your repository.
- The `label` text appears on the tile under your icon. This should
match your product name on VMware Tanzu Network. Coordinate with your
product team to agree on a product name; marketing teams often care about
the product name because it appears on VMware Tanzu Network.
- The `description` should contain a description of the product. This
is not currently used, but might be displayed in a future version of
Ops Manager.
### <a id="packages"></a> Packages
Next you can specify the packages to be included in your tile. The format of
each package entry depends on the type of package you are adding.
#### <a id="pushed"></a> Pushed Apps
Apps (including service brokers) that are being `cf push`ed into the
<%= vars.app_runtime_abbr %> use the following format:
```yaml
- name: my-application
type: app # or app-broker
manifest:
# any options that you would normally specify in a cf manifest.yml, including</i>
buildpack: # required
command:
domain:
host:
instances:
memory:
path:
env:
services:
health_check: none # optional
configurable_persistence: true # optional
needs_cf_credentials: true # optional
auto_services: # optional
- name: p-mysql
plan: 100MB
- name: p-redis
plan: shared-vm
consumes: # optional
redis:
from: redis
```
For apps that are normally pushed as multiple files (node.js for example)
zip up the project files plus all dependencies into a single ZIP file, then
edit <code>tile.yml</code> to point to the zipped file:
```bash
cd <your project dir>
zip -r resources/<your project name>.zip <list of file and dirs to include in the zip>
```
If your app is a service broker, use `app-broker` as the type instead of just
`app`. The app is then automatically registered as a broker on install,
and deleted on uninstall.
`health_check` lets you configure the value of the cf cli `--health_check_type`
option. Expect this option to move into the manifest as soon as CF supports it there.
Currently, the only valid options are `none` and `port`.
`configurable_persistence: true` results in the user being able to select a backing
service for data persistence. If there is a specific broker you want to use, you can
use the `auto-services` feature described below. If you want to bind to an already
existing service instance, use the `services` property of the `manifest` instead.
`needs_cf_credentials` causes the app to receive two additional environment
variables named `CF_ADMIN_USER` and `CF_ADMIN_PASSWORD` with the admin credentials
for the <%= vars.app_runtime_abbr %> into which they are being deployed. This allows apps and
services to interact with the Cloud Controller.
The `auto_services` feature is described in more detail below.
`consumes` specifies the [BOSH links](https://bosh.io/docs/links.html) to
consume and presents the hosts and properties from the links as
environment variables on the app:
- `<LINK>_HOST`: The address of the first instance of the link.
- `<LINK>_HOSTS`: A JSON array of the addresses of all instances of the link.
- `<LINK>_PROPERTIES`: A JSON object of the properties on the link.
#### <a id="brokers"></a> Service Brokers
Most modern service brokers are pushed into <%= vars.app_runtime_abbr %> as normal
CF apps. For these types of brokers, use the Pushed Application format
specified above, but set the type to `app-broker` or `docker-app-broker` instead
of just `app` or `docker-app`:
```
- name: my-broker
type: app-broker
manifest:
buildpack: # required
command:
domain:
path:
# ...
needs_cf_credentials: true # optional
auto_services: # optional
- name: p-mysql
plan: 100MB
- name: p-redis
plan: shared-vm
enable_global_access_to_plans: true # optional
```
<p class="note"><strong>Note</strong>: Unless you specify the `enable_global_access_to_plans: true` option, your
broker's services do not appear in the user's Marketplaces.
Operators have to use the `cf enable-service-access` command to allow
specific users, orgs, and spaces to access your services.</p>
Your broker is automatically registered with the Cloud Controller. The
Cloud Controller invokes your broker's endpoints, and it uses basic
authentication to secure those API calls. The credentials it uses are
passed to your broker in two environment variables:
```
SECURITY_USER_NAME
SECURITY_USER_PASSWORD
```
Your broker is expected to accept those credentials. If it doesn't, automatic
broker registration fails.
Some service brokers support operator-defined service plans, for instance when
the plans reflect customer license keys. To allow operators to add plans from
the tile configuration, add the following section at the top level of your `tile.yml`:
```
service_plan_forms:
- name: service_plans_1
label: Service 1 Plans
description: Specify the plans you want Service 1 to offer
properties:
- name: description
type: string
description: "Some Description"
configurable: true
- name: license_key1
type: string
configurable: true
description: The license key for this plan
- name: num_seats1
type: integer
configurable: true
description: The number of available seats for this license
default: 1
constraints:
min: 1
max: 500
```
Name and GUID fields are supplied by default for each plan, but all other fields
are optional and customizable. Multiple forms are supported. The operator-configured
plans are passed to your service broker in JSON format in an environment variable
named after your form but in ALL CAPS (in this case `SERVICE_PLANS_1`).
For an external service broker, use:
```
- name: my-application
type: external-broker
uri: http://broker3.example.com
username: user
password: #secret
internal_service_names: 'service1,service2'
```
#### <a id="bosh"></a> BOSH Releases
You can include [BOSH releases](http://bosh.io/docs/release.html) in
your tile with the `bosh-release` package type. For example, here is a
package definition to include a Redis BOSH release:
```
- name: redis
type: bosh-release
path: resources/redis-13.1.2.tgz
jobs:
- name: redis
templates:
- name: redis
release: redis
memory: 512
ephemeral_disk: 4096
persistent_disk: 4096
instances: 2
cpu: 2
static_ip: 0
dynamic_ip: 1
default_internet_connected: false
max_in_flight: 1
properties:
password: red!s
- name: sanity-tests
templates:
- name: sanity-tests
release: redis
lifecycle: errand
post_deploy: true
run_post_deploy_errand_default: when-changed
memory: 512
ephemeral_disk: 4096
persistent_disk: 0
cpu: 2
dynamic_ip: 1
```
To include [BOSH links](https://bosh.io/docs/links.html) in your
bosh-release package's deployment manifest, you can include the
`consumes` and/or `provides` declarations *as strings* in the job's
`templates` section, e.g.:
```
# ...
jobs:
- name: job_name
templates:
- name: template_name
consumes:
consumed_link: {from: foo}
provides:
provided_link: {as: bar}
```
#### <a id="buildpacks"></a> Buildpacks
```
- name: my-buildpack
type: buildpack
path: resources/buildpack.zip
buildpack_order: 99 # optional, 99 means end of the list
```
#### <a id="docker"></a> Docker Images
Apps packaged as Docker images can be deployed inside or outside <%= vars.app_runtime_abbr %>.
To push a Docker image as a CF app, use the *Pushed Application*
format specified above, but use the `docker-app` or `docker-app-broker` type instead
of just `app` or `app-broker`. The Docker image to be used is then specified using
the `image` property:
```
- name: app1
type: docker-app
image: test/dockerimage
manifest:
...
```
If this app is also a service broker, use `docker-app-broker` instead of just
`docker-app`. This option is appropriate for Docker-wrapped 12-factor apps that
delegate their persistence to bound services.
Docker apps that require persistent storage can not be deployed into
<%= vars.app_runtime_abbr %>. These can be deployed to separate BOSH-managed VMs instead
by using the `docker-bosh` type:
```
- name: docker-bosh1
type: docker-bosh
cpu: 5
memory: 4096
ephemeral_disk: 4096
persistent_disk: 2048
instances: 1
manifest: |
containers:
- name: redis
image: "redis"
command: "--dir /var/lib/redis/ --appendonly yes"
bind_ports:
- "6379:6379"
bind_volumes:
- "/var/lib/redis"
entrypoint: "redis-server"
memory: "256m"
env_vars:
- "EXAMPLE_VAR=1"
- name: mysql
image: "google/mysql"
bind_ports:
- "3306:3306"
bind_volumes:
- "/mysql"
- name: elasticsearch
image: "bosh/elasticsearch"
links:
- mysql:db
depends_on:
- mysql
bind_ports:
- "9200:9200"
```
If a Docker image cannot be downloaded by BOSH dynamically, provide a ready-made Docker image
and package it as part of the BOSH release. In that case, specify the image as a local file.
This file must be a `.tgz`.
```
- name: docker-bosh2
type: docker-bosh
files:
- path: resources/cfplatformeng-docker-tile-example.tgz
cpu: 5
memory: 4096
ephemeral_disk: 4096
persistent_disk: 2048
instances: 1
manifest: |
containers:
- name: test_docker_image
image: "cfplatformeng/docker-tile-example"
env_vars:
- "EXAMPLE_VAR=1"
# See below on custom forms/variables and binding it to the Docker env variable
- "custom_variable_name=((.properties.customer_name.value))"
```
To expose a container via the
[<%= vars.app_runtime_abbr %> Routing Architecture](https://docs.cloudfoundry.org/concepts/cf-routing-architecture.html),
for example, one of the Docker containers hosts an admin webapp interface,
use the [`routes` property of the apps manifest](https://docs.cloudfoundry.org/devguide/deploy-apps/manifest-attributes.html#routes) to choose a port and prefix. The external URL
is `[prefix]-[package.name].[system-domain]`.
In this case, the URL is `https://admin-docker-bosh3.sys.example.com`, where `sys.example.com` is the <%= vars.app_runtime_abbr %> system domain.
`routes` is a list, so multiple containers can be exposed.
```
- name: docker-bosh3
type: docker-bosh
docker_images:
- "cfplatformeng/database"
- "cfplatformeng/admin_ui"
routes:
- prefix: admin
port: 8080
cpu: 5
memory: 4096
ephemeral_disk: 4096
instances: 1
manifest: |
containers:
- name: database
image: "cfplatformeng/database"
bind_ports:
- "5432:5432"
- name: admin_ui
image: "cfplatformeng/admin_ui"
bind_ports:
- "8080:8080"
```
### <a id="custom-forms"></a> Custom Forms and Properties
You can pass custom properties to all apps deployed by your tile by adding
the to the properties section of `tile.yml`:
```
properties:
- name: author
type: string
label: Author
value: Tile Ninja
```
If you want the properties to be configurable by the tile installer, place them on
a custom form instead:
```
forms:
- name: custom-form1
label: Test Tile
description: Custom Properties for Test Tile
properties:
- name: customer_name
type: string
label: Full Name
- name: street_address
type: string
label: Street Address
description: Address to use for junk mail
- name: city
type: string
label: City
- name: zip_code
type: string
label: ZIP+4
default: '90310'
- name: country
type: dropdown_select
label: Country
default: country_us
options:
- name: country_us
label: US
- name: country_elsewhere
label: Elsewhere
- name: account-info-1
label: Account Info
description: Example Account Information Form
properties:
- name: username
type: string
label: Username
- name: password
type: secret
label: Password
```
Properties defined in either section are passed to all pushed apps
as environment variables (the name of the environment variable is the same
as the property name but in ALL_CAPS). They can also be referenced in other parts
of the configuration file by using `(( .properties.<property-name> ))` instead
of a hardcoded value.
All properties supported by Ops Manager may be used. The syntax is the same
as used by Ops Manager, except that for simplicity property blueprints for
form fields do not need to be declared separately. Instead, the declaration
is included in the form itself. For a complete list of supported property
types and syntax, see the
[Property and Template References](./property-template-references.html).
Ops Manager supports text areas for any type of multi-line credential. If you want a `secret` property to use a text area instead of the default single-line text field, you must set `display_type` to `text_area` in the `property_inputs` section of your property blueprint, as in the example below.
```
property_inputs:
- reference: secret_meaning
label: 'Secret Meaning'
description: 'If you play it backwards...'
display_type: 'text_area'
```
### <a id='auto-provision'></a> Automatic Provisioning of Services
Tile Generator automates the provisioning of services. Any app (including
service brokers and Docker-based apps) that are being pushed into <%= vars.app_runtime_abbr %>
can automatically be bound to services through the `auto_services`
feature:
```
- name: app1
type: app
auto_services:
- name: p-mysql
plan: 100mb-dev
- name: p-redis
```
You can specify any number of service names, optionally specifying a specific
plan. During deployment, the generated tile creates an instance of each
service if one does not already exist and then bind that instance to your
package.
Service instances provisioned this way survive updates, but are deleted
when the tile is uninstalled.
<p class="note"><strong>Note</strong>: The name is the name of the provided <em>service, not the broker</em>.
In many cases these are not the same, and a single broker might even offer
multiple services. Use <code>cf service-access</code> to see the services and plans
offered by installed service brokers.</p>
If you do not specify a plan, Tile Generator uses the first plan
listed for the service in the broker catalog. It is a good idea to always
specify a service plan. If you *change* the plan between versions of your
tile, Tile Generator attempts to update the plan while preserving
the service (thus not causing data loss during upgrade). If the service
does not support plan changes, this causes the upgrade to fail.
`configurable_persistence` is really just a special case of `auto_services`,
letting the user choose between some standard brokers.
### <a id='declare-dependencies'></a> Declaring Product Dependencies
When your product has dependencies on others, you can have Ops Manager
enforce that dependency by declaring it in your `tile.yml` file as follows:
```
requires_product_versions:
- name: p-mysql
version: '~> 1.7'
```
If the required product is not present in the <%= vars.platform_name %> installation, Ops Manager
displays a message saying
`<your-tile> requires 'p-mysql' version '~> 1.7' as a dependency` and
refuses to install your tile until that dependency is satisfied.
When using automatic provisioning of services as described above, it is
often appropriate to add those products as a dependency. Tile Generator can
not do this automatically as it can't always determine which product provides
the requested service.
### <a id='orgs-spaces'></a> Orgs and Spaces
By default, Tile Generator creates a single new org and space for any
packages that install into <%= vars.app_runtime_abbr %>, using the name of the tile and
appending `-org` and `-space`, respectively. The default memory quota for a
newly created org is 1024 (1 G). You can change any of these defaults by
specifying the following properties in `tile.yml`:
```
org: test-org
org_quota: 4096
space: test-space
```
### <a id="security"></a> Security
If your cf packages need outbound access (including access to other packages
within the same tile), you need to apply an appropriate security group.
The following option removes all constraints on outbound traffic:
```
apply_open_security_group: true
```
### <a id="stemcells"></a> Stemcells
Tile Generator defaults to a recent stemcell supported by Ops Manager.
In most cases the default is fine, because the stemcell is only used to execute
CF command lines and/or the Docker daemon. But if you have specific stemcell
requirements, you can override the defaults in your `tile.yml` file by including
a `stemcell-criteria` section and replacing the appopriate values:
```yaml
stemcell_criteria:
os: 'ubuntu-trusty'
version: '3146.5' #NOTE: You must quote the version to force the type to be string
```
### <a id="custom-errands"></a> Custom Errands
Tile Generator supplies standard errands to deploy and delete CF type packages. You can
replace or augment those errands by specifying errand shell commands in your tile.yml
file. Here is an example of a custom deploy errand to install a buildpack only if a newer
version of that same buildpack is not already present:
```
packages:
- name: my-buildpack
type: buildpack
buildpack_order: 0 # Go to head of list
path: my_buildpack.zip
deploy: |
cp my_buildpack.zip my_buildpack-v{{context.version}}.zip
existing=`cf buildpacks | grep '^my_buildpack'`
if [ -z "$existing" ]; then
cf create-buildpack my_buildpack my_buildpack-v{{context.version}}.zip 0
else
semver=`echo "$existing" | sed 's/.* my_buildpack-v\(.*\)\.zip/\1/'`
if is_newer "{{context.version}}" "$semver"; then
cf update-buildpack my_buildpack -p my_buildpack-v{{context.version}}.zip
else
echo "Newer version ($semver) of my_buildpack is already present"
fi
cf update-buildpack my_buildpack -i 0
fi
delete: |
# Intentional no-op, as others may have a dependency on this
```
`deploy` and `delete` completely replace the standard errand commands for the
package in which you include them. If you want to keep the standard commands, but
add additional commands to execute before or after the standard errand, use
`pre_deploy`, `post_deploy`, `pre_delete`, and/or `post_delete` instead.
## <a id="versioning"></a> Versioning
Tile Generator uses [semver versioning](http://semver.org/). By default, `tile build`
generates the next patch release. Major and minor releases can be generated
by explicitly specifying `tile build major` or `tile build minor`. Or to
override the version number completely, specify a valid semver version on
the build command, e.g. `tile build 3.4.5`.
No-op content migration rules are generated for every prior release to the
current release, so that Ops Manager allows tile upgrades from any
version to any newer version. This depends on the existence of the file
`tile-history.yml`. In a pinch, if you need to be able to upgrade from a
random old version to a new one, you can edit that file, or do:
```
tile build <old-version>
tile build <new-version>
```
The new tile then supports upgrades from `old-version`.
## <a id="upgrades"></a> Upgrades
By default, Tile Generator produces all code necessary to do a blue/green,
zero-downtime deployment of all tile components when installing a newer version
over an older one. For most tile versions this is all that is needed.
Ops Manager has support for performing upgrade actions, like database migrations,
during a tile upgrade, but this capability is not yet exposed through tile
generator. For example:
```bash
$ tile build
name: tibco-bwce
icon: icon.png
label: TIBCO BusinessWorks Container Edition
description: BusinessWorks edition that supports deploying to Cloud Foundry
version: 0.0.2
bosh init-release --dir=cf
bosh generate-package cf_cli
bosh generate-package bwce_buildpack
bosh generate-job install_bwce_buildpack
bosh generate-job remove_bwce_buildpack
bosh create-release --final --tarball=cf_incubator --version 0.0.2
tile generate release
tile generate metadata
tile generate errand install_bwce_buildpack
tile generate errand remove_bwce_buildpack
tile generate content-migrations
created tile tibco-bwce-0.0.2.pivotal
```
This tile includes a single large buildpack and takes less than 15 seconds
to build including the CF CLI download and the BOSH release generation.
## <a id="commands"></a> Supported Commands
```bash
tile init [<tile-name>]
tile build [patch|minor|major|<version>]
```
## <a id="credits"></a> Credits
- [sparameswaran](https://github.com/sparameswaran) supplied most of the actual template content, originally built as part of [cf-platform-eng/bosh-generic-sb-release](https://github.com/cf-platform-eng/bosh-generic-sb-release.git)
- [frodenas](https://github.com/frodenas) contributed most of the Docker content through [cloudfoundry-community/docker-boshrelease](https://github.com/cloudfoundry-community/docker-boshrelease.git)
- [joshuamckenty](https://github.com/joshuamckenty) suggested the jinja template approach he employed in [opencontrol](https://github.com/opencontrol)