diego-release

README

Cloud Foundry Diego [BOSH release]

---

This repo is a BOSH release for deploying Diego and associated tasks for testing a Diego deployment. Diego builds out the new runtime architecture for Cloud Foundry, replacing the DEAs and Health Manager.

This release relies on a separate deployment to provide Consul, NATS and Loggregator. In practice these come from cf-release.

Table of Contents

1. Deployment Examples
2. BOSH-Lite
3. AWS
4. Additional Diego Resources
5. BOSH Dependencies
6. Deploying Alongside an Existing CF Deployment
7. Release Compatibility
8. Manifest Generation
9. Deployment Constraints
10. Required Dependencies
11. Diego Manifest Jobs
12. Pushing a CF Application to the Diego Runtime
13. Recommended Instance Types
14. Benchmarks

---

Deployment Examples

BOSH-Lite

To deploy CF and Diego to BOSH-Lite, follow the instructions at examples/bosh-lite.

AWS

In order to deploy Diego to AWS, follow the instructions in examples/aws to deploy BOSH, CF, and Diego to a new CloudFormation stack, or follow the instructions in examples/minimal-aws to deploy Diego alongside a minimal CF deployment.

Additional Diego Resources

• The Contribution Guidelines describes the developer workflow for making changes to Diego.
• The Diego Design Notes present an overview of Diego, and links to the various Diego components.
• The Migration Guide describes how developers and operators can manage a transition from the DEAs to Diego.
• The Docker Support Notes describe how Diego runs Docker-image-based apps in Cloud Foundry.
• The Diego-CF Compatibility Log records which versions of cf-release and diego-release are compatible, according to the Diego team's automated testing pipeline.
• Supported Data Stores for Diego
• Data Store Encryption
• TLS Configuration
• Diego's Pivotal Tracker project shows what we're working on these days.
• Diego Metrics lists the various metrics that Diego emits through the Loggregator system.

---

BOSH Dependencies

When deploying diego-release via BOSH, the following minimum versions are required:

• BOSH Release v255.4+ (Director version 1.3213.0)
• BOSH Stemcell 3125+

These versions ensure that the pre-start script in the rootfses job will be run to extract and configure the cflinuxfs2 rootfs and that the drain scripts will be called for all jobs on each VM during updates, instead of only the first job. We also require post-start for the initial cell health check, which is also provided by the same versions listed above.

---

Deploying Alongside an Existing CF Deployment

Diego is typically deployed alongside a CF deployment to serve as its new container runtime. See "Deploying Diego Alongside an Existing CF Deployment" for general instructions and guidelines to deploy Diego this way.

Release Compatibility

Diego releases are tested against Cloud Foundry, Garden, and ETCD. Compatible versions of Garden and ETCD are listed with Diego on the Github releases page.

Checking out a release of Diego

The Diego git repository is tagged with every release. To move the git repository to match a release, do the following:

cd diego-release/
# checking out release v0.1437.0
git checkout v0.1437.0
./scripts/update
git clean -ffd

From a final release of CF

On the CF Release GitHub Releases page, recommended versions of Diego, Garden, and ETCD are listed with each CF Release. This is the easiest way to correlate releases.

Alternatively, you can use records of CF and Diego compatibility captured from automated testing. First look up the release candidate SHA for your CF release. This is listed as the commit_hash in the release yaml file. Find the SHA in diego-cf-compatibility/compatibility-v2.csv to look up tested versions of Diego Release, Garden, and ETCD.

Example: Let's say you want to deploy Diego alongside CF final release 222. The release file releases/cf-222.yml in the cf-release repository contains the line commit_hash: 53014242. Finding 53014242 in diego-cf-compatibility/compatibility-v2.csv reveals Diego 0.1437.0, Garden 0.308.0, and ETCD 16 have been verified to be compatible.

From a specific CF Release commit SHA

Not every cf-release commit will appear in the diego-cf compatibility table, but many will work with some version of Diego.

If you can't find a specific cf-release SHA in the table, deploy the diego-release that matches the most recent cf-release relative to that commit. To do this, go back through cf-release's git log from your commit until you find a Final Release commit and then look up that commit's SHA in the diego-cf compatibility table.

Manifest Generation

The Diego manifest generation documentation can be found in docs/manifest-generation.md.

Deployment Constraints

Required Dependencies

Before deploying the Diego cluster, ensure that the consul server cluster it will connect to is already deployed. In most deployment scenarios, these consul servers come from a CF deployment.

Additionally, if configuring the BBS to use a relational data store such as a CF-MySQL database, that data store must be deployed or otherwise provisioned before deploying the Diego cluster.

Diego Manifest Jobs

In your manifest, ensure that the following constraints on job update order and rate are met:

1. BBS servers should update before BBS clients. This can be achieved by placing database_zN instances at the beginning of the jobs list in your manifest. For example:

   jobs:
   - instances: 1
     name: database_z1
   

2. database_zN nodes update one at a time. This can be achieved by setting max_in_flight to 1 and serial to true for database_zN jobs.

   - instances: 1
     name: database_z1
     ...
     update:
       max_in_flight: 1
       serial: true
   

3. brain_zN jobs update separately from cells. This can be achieved by setting max_in_flight to 1 and serial to true for brain_zN jobs.

   - instances: 1
     name: brain_z1
     ...
     update:
       max_in_flight: 1
       serial: true
   

Pushing a CF Application to the Diego Runtime

1. Create and target a CF org and space:

cf api --skip-ssl-validation api.bosh-lite.com
cf auth admin admin
cf create-org diego
cf target -o diego
cf create-space diego
cf target -s diego

1. Change into your application directory and push your application without starting it:

cd <app-directory>
cf push my-app --no-start

1. Enable Diego for your application.

2. Start your application:

cf start my-app

---

Recommended Instance Types

If you are deploying to AWS, you can use our recommended instance types by spiff merging your iaas-settings.yml with our provided manifest-generation/misc-templates/aws-iaas-settings.yml:

spiff merge \
	manifest-generation/misc-templates/aws-iaas-settings.yml \
	/path/to/iaas-settings.yml \
	> /tmp/iaas-settings.yml

You can then use the template generated as the iaas-settings.yml for the scripts/generate-deployment-manifest tool. The cell jobs currently use r3.xlarge as their instance_type. For production deployments, we recommend that you increase the ephemeral_disk size. This can be done by specifying the following in your iaas-settings.yml under the cell resource pool definitions:

ephemeral_disk:
  size: 174_080
  type: gp2

Benchmarks

Viewing Results

Diego benchmark results can be found here. You can also visit this dashboard to view the results for all benchmark runs in the last 24 hours.

Descriptions of the metrics from the benchmark runs are available in the BBS Benchmark documentation.