1# Advanced configuration 2 3## Table of Contents 4* <a href='#opsfile'>Using a BOSH ops-file with bbl</a> 5* <a href='#terraform'>Customizing IaaS Paving with Terraform</a> 6* <a href='#plan-patches'>Applying and authoring plan patches, bundled modifications to default bbl configurations.</a> 7 8## <a name='opsfile'></a>Using a BOSH ops-file with bbl 9 10### About BOSH ops-files 11 12Certain features of BOSH, particularly experimental features or tuning parameters, must be enabled by modifying your 13Director's deployment manifest. [`bosh-deployment`](https://github.com/cloudfoundry/bosh-deployment) contains many such [ops files](https://bosh.io/docs/terminology.html#operations-file) for common features and options. 14 15### Using the pre-made operations files 16You can provide any number of ops files or variables to `bosh create-env` by creating `create-director-override.sh`. This file will not be overridden by bbl. You can use `create-director.sh` as a template, and you can even edit that file instead, but if you do, your changes will be overridden the next time you run `bbl plan`. 17 18In this example, I use a local version of BOSH director that I have built based off of a branch by referencing an ops file that is included as part of `bosh-deployment`: 19```diff 20bosh create-env \ 21 ${BBL_STATE_DIR}/bosh-deployment/bosh.yml \ 22 --state ${BBL_STATE_DIR}/vars/bosh-state.json \ 23 --vars-store ${BBL_STATE_DIR}/vars/director-vars-store.yml \ 24 --vars-file ${BBL_STATE_DIR}/vars/director-vars-file.yml \ 25+ -o ${BBL_STATE_DIR}/bosh-deployment/local-bosh-release.yml 26+ -v local_bosh_release=${BBL_STATE_DIR}/../../build/bosh-dev.tgz 27 -o ${BBL_STATE_DIR}/bosh-deployment/cpi.yml \ 28 -o ${BBL_STATE_DIR}/bosh-deployment/jumpbox-user.yml \ 29 -o ${BBL_STATE_DIR}/bosh-deployment/uaa.yml \ 30 -o ${BBL_STATE_DIR}/../shared/bosh-deployment/credhub.yml 31``` 32 33### Authoring an ops-file 34The [operations files](http://bosh.io/docs/cli-ops-files.html) provided by `bosh-deployment` may not meet your needs. In this case you will have to write your own 35custom ops-file. Store it somewhere outside of the bosh-deployment directory. New versions of bbl will keep the 36bosh-deployment directory in sync with the latest configuration and releases, so modifications may be lost when 37`bbl plan` is run in the future. Consider storing it in the top level of your state directory if it is environmentally 38specific, or above the state directory if it is true for all environments. 39 40Here is an example of adding an ops file that configures a few settings on all of my BOSH directors: 41```diff 42#!/bin/sh 43bosh create-env \ 44 ${BBL_STATE_DIR}/bosh-deployment/bosh.yml \ 45 --state ${BBL_STATE_DIR}/vars/bosh-state.json \ 46 --vars-store ${BBL_STATE_DIR}/vars/director-vars-store.yml \ 47 --vars-file ${BBL_STATE_DIR}/vars/director-vars-file.yml \ 48+ -o ${BBL_STATE_DIR}/../../bbl-envs/shared/increase-workers-threads-and-flush-arp.yml 49 -o ${BBL_STATE_DIR}/bosh-deployment/cpi.yml \ 50 -o ${BBL_STATE_DIR}/bosh-deployment/jumpbox-user.yml \ 51 -o ${BBL_STATE_DIR}/bosh-deployment/uaa.yml \ 52 -o ${BBL_STATE_DIR}/../shared/bosh-deployment/credhub.yml 53``` 54## <a name='terraform'></a>Customizing IaaS Paving with Terraform 55Numerous settings can be reconfigured repeatedly by editing `$BBL_STATE_DIR/vars/terraform.tfvars` or adding a terraform override into `$BBL_STATE_DIR/terraform/my-cool-template-override.tf`. Some settings, like VPCs, are not able to be changed after initial creation so it may be better to `bbl plan` first before running `bbl up` for the first time. 56 57### Example: adjusting the cidr on AWS 581. Plan the environment: 59 ``` 60 mkdir some-env && cd some-env 61 export BBL_IAAS=aws 62 export BBL_AWS_REGION=us-west-1 63 export BBL_AWS_ACCESS_KEY_ID=12345678 64 export BBL_AWS_SECRET_ACCESS_KEY=12345678 65 bbl plan 66 echo -e "\nvpc_cidr=\"192.168.0.0/20\"" >> vars/terraform.tfvars 67 ``` 681. Create the environment: 69 ``` 70 bbl up 71 ``` 72 That's it. Your director is now at `192.168.0.6`. 73 74## <a name='plan-patches'> [Plan Patches](https://github.com/cloudfoundry/bosh-bootloader/tree/master/plan-patches) 75 76Through operations files and terraform overrides, all sorts of wild modifications can be done to the vanilla bosh environments that bbl creates. The basic principal of a plan patch is to make several modifications to a bbl plan in override files that bbl finds under `terraform/`, `cloud-config/`, and `{create,delete}-{jumpbox,director}.sh` . BBL will read and merge those into it's plan when you run `bbl up`. 77 78We've used plan patches to [deploy bosh-lite directors on gcp](https://github.com/cloudfoundry/bosh-bootloader/tree/master/plan-patches/bosh-lite-gcp), to deploy CF Isolation Segments on [public](https://github.com/cloudfoundry/bosh-bootloader/tree/master/plan-patches/iso-segs-gcp) [clouds](https://github.com/cloudfoundry/bosh-bootloader/tree/master/plan-patches/iso-segs-aws), and to deploy bosh managed k8s clusters with working cloud-providers using [cfcr](https://github.com/cloudfoundry-incubator/kubo-deployment/tree/master/manifests). 79 80Our plan patches are experimental. They were tested a bit when we wrote them, but we don't continuously integrate against their dependencies or even check if they still work with recent versions of terraform. They should be used with caution. Operators should make sure they understand each modification and its implications before using our patches in their own environments. Regardless, the plan-patches in this repo are great examples of the different ways you can configure bbl to deploy whatever you might need. To see all the plan patches, visit the [Plan Patches README.md](https://github.com/cloudfoundry/bosh-bootloader/tree/master/plan-patches). If you write your own plan patch that gets you what you need, please consider upstreaming it in a PR. 81 82