Adding a Custom Stack
Page last updated:
This topic outlines how to add a custom stack under the Diego architecture. To add a stack, you first build a BOSH job template that installs the stack on the host machine. Then you configure your deployment manifests so that Cloud Foundry can run the job when it creates cells.
The Cloud Foundry cflinuxfs2 repository contains scripts for building your own custom stacks, as well as the available Cloud Foundry stacks.
The following example adds a new Linux-based
pancakes stack for use with the Garden-runC operating system. This
pancakes stack could, for example, support applications that require an old version of CentOS or Ubuntu.
Stacks exist in a subdirectory on their host machine, typically under
/var/vcap/data. Your BOSH job template must deploy the stack onto a host machine, and provide lifecycle binaries that work with your stack. The lifecycle binaries for your stack are helper programs that stage and run apps on the stack file system. To create a
pancakes-release job template that deploys a custom stack, follow these steps:
Create a BOSH release
pancakes-releasefor a job template that expands a stack into place in its subdirectory. The rootfs must be packaged as a
.tarfile, for example, a
pancakes-rootfstemplate might create a tarred full Linux root file system at
/var/vcap/packages/pancakes-rootfs/rootfs.tar. See the ‘rootfses’ job template in diego-release for one way to do this.
Create lifecycle binaries for your stack. See the diego-release repository for examples of app lifecycle binary source code:
Generate a gzipped tar archive of the lifecycle binaries,
Create a dummy
pancakes-app-lifecyclejob template as a package within
pancakes-release. Include the
pancakes-app-lifecycle.tgzfile in the job template directory.
pancakes-app-lifecyclejob template does not need to run any process of its own.
List the dummy
pancakes-app-lifecyclejob as a dependency in the
pancakes-releasespec file. This makes BOSH publish the lifecycle binaries to
/var/vcap/packagesfor inclusion in any cells that use the
pancakes-rootfsjob and release name to the Diego manifest, to the list of job templates defined for the
base_job_templates. This makes the expanded rootfs available locally on the Diego cell, at
/var/vcap/packages/pancakes-rootfs/rootfs. For example, in the manifests generated with the spiff-based tooling in diego-release, add the lines shown in bold to the following list of cell job templates:
cell: - name: rep release: diego - name: consul_agent release: cf - name: garden release: garden-runc - name: rootfses release: diego - name: pancakes-rootfs release: pancakes - name: metron_agent release: cf
base_job_templateslist under the
file_serverDiego job. In diego-release, the
file_serverjob resides in the
accessjob template group. For example, add the lines shown in bold to the following list of job templates:
access: - name: ssh_proxy release: diego - name: consul_agent release: cf - name: metron_agent release: cf - name: file_server release: diego - name: pancakes-app-lifecycle release: pancakes
diego.rep.preloaded_rootfsesproperty of the Cell Rep holds an array associating stacks with the location of their tarred rootfs in the filesystem. Add a pair to this list to associate the
pancakesstack with its file system root location, set up on the cell by the
pancakes-rootfsjob. For example, in the
rep:in your Diego manifest, set the array to the following by adding the text shown in bold:
Configure the stager and nsync components to use the
pancakeslifecycle binary bundle to start and stop apps running on the
pancakesstack. For example, in CAPI release, add the line shown in bold to the
defaultlist under the manifest definitions for both
description: "List of lifecycle bundles arguments for different stacks in form 'lifecycle-name:path/to/bundle'" default: - "buildpack/cflinuxfs2:buildpack_app_lifecycle/buildpack_app_lifecycle.tgz" - "buildpack/pancakes:pancakes-app-lifecycle/pancakes-app-lifecycle.tgz" - "buildpack/windows2012R2:windows_app_lifecycle/windows_app_lifecycle.tgz" - "docker:docker_app_lifecycle/docker_app_lifecycle.tgz"
Configure the Cloud Controller for the new stack by adding it to the ‘cc.stacks’ property in the CF manifest. For example, in the diego-release manifest generation stubs for CF, add the lines shown in bold:
properties: cc: stacks: - name: "cflinuxfs2" description: "Cloud Foundry Linux-based filesystem" - name: "windows2012R2" description: "Windows Server 2012 R2" - name: "pancakes" description: "Linux-based filesystem, with delicious pancakes"