Guide to deploying Genesis kits to BOSH/CredHub

December 12, 2019

Genesis is an awesome deployment framework for deploying systems with BOSH to any infrastructure cloud. It has a whole catalog of open source production ready kits which make it super easy to deploy, scale, and upgrade systems such as Cloud Foundry Application Runtime (PaaS), Vault (Secrets), Concourse CI, SHIELD (backup/restore), and Minio (Object Store).

Genesis is built to support any deployment pipeline dev -> {your stage here} -> prod across any number of infrastructures and their regions.

Genesis Kits require a special-purpose BOSH/Vault environment. This article introduces how to deploy Genesis Kits to a BOSH/Credhub environment, thanks to a Vault <–> Credhub proxy, which adds Vault API compatibility to Credhub.

We can now announce experimental Genesis compatibility in BUCC, a way to quickly deploy a BOSH/UAA/Credhub/Concourse environment. With BUCC v0.8.0 you can now run a production BUCC or --lite BUCC and begin deploying our Genesis Kits to either any BOSH infrastructure or your local laptop.

Let’s show how easy it is to deploy Minio using the minio-genesis-kit starting with BUCC. Thanks to the Concourse pipeline provided by Genesis, our Minio system will forever stay upgraded.

Prerequisites

To get started, make sure to have the following tools installed:

Genesis
Spruce (used by genesis)
VirtualBox (will be used by BUCC to create a virtual machine)
OS specific bosh cli dependencies
hub (used to streamline GitHub interaction)
curl used by BUCC
GitHub Account (signup here )

On a linux distro with apt support the Stark & Wayne apt repository can be used:

apt-get update && apt install gnupg wget -ywget -q -O - https://raw.githubusercontent.com/starkandwayne/homebrew-cf/master/public.key | apt-key add -
echo "deb http://apt.starkandwayne.com stable main" | tee /etc/apt/sources.list.d/starkandwayne.list
apt-get update
sudo apt install spruce safe bosh-cli genesis curl hub virtualbox jq

Create a BUCC VM

Let’s clone the BUCC repo and use the BUCC CLI to create our VM.

git clone https://github.com/starkandwayne/bucc ~/workspace/bucc
~/workspace/bucc/bin/bucc up --cpi virtualbox --lite
source <(~/workspace/bucc/bin/bucc env)

Create a Genesis Deployment

When generating a deployment file, Genesis will look at your locally configured Safe and BOSH CLI targets to figure out where to store secrets and where to get the BOSH cloud-config from. Let’s make sure these targets are configured using the bucc CLI authentication helpers.

bucc bosh # performs a bosh login with the credentials generated by bucc up
bucc safe # installs the safe cli and targets the vault-credhub-proxy

We will also need a proper cloud and runtime config for BOSH. The ones below have been tested with BUCC lite and the minio-genesis-kit. If you are not using the bosh_warden_cpi (this is what makes BUCC lite) or are using a different kit, you might need to make changes.

read -r -d '' cloud_config <<'EOF'
azs: [{ name: z1 }, {name: z2}, {name: z3}]
compilation:
  az: z1
  network: minio
  reuse_compilation_vms: true
  vm_type: default
  workers: 5
disk_types: [{ disk_size: 10240, name: minio }]
networks:
- name: minio
  subnets:
  - azs: [z1, z2, z3]
    dns: [8.8.8.8]
    gateway: 10.244.0.1
    range: 10.244.0.0/24
    reserved: [10.244.0.129 - 10.244.0.254]
    static: []
  type: manual
vm_types:
 - name: default
EOF
bosh -e bucc update-cloud-config <(echo -e "${cloud_config}")
bosh -e bucc update-runtime-config <(echo "{}")

Now it’s time to let Genesis do its magic and create our deployments repo and deployment file. We are targeting the BOSH environment named bucc and will store secrets generated by Genesis in CredHub via a vault proxy.

genesis init --kit minio --cwd ~/workspace
genesis new bucc \
  --cwd ~/workspace/minio-deployments \
  --environment bucc

At the prompts, choose the following answers:

Select choice > Please have Genesis create a self-signed certificate for Minio
External Domain or IP: > 10.244.0.134
[y|n] > n

We could now run genesis deploy 'bucc' and be done with it, but let’s take it a step further and use Concourse to automate our deploy instead.

Create the Concourse Pipeline

Genesis can generate a pipeline for us, but to do so it needs some help in the form of a ci.yml file the contents of which are documented here . However, since we are using BUCC, almost all (expect GitHub) secrets we need are already available in CredHub (use bucc credhub && credhub find to see for yourself).

We can consume these via Concourse CredHub Credential Manager. Now use the snippets below to generate the config file, use BUCC to set the fly target, and instruct Genesis to generate a pipeline config.

cd ~/workspace/minio-deployments
cat << EOF > ci.yml
pipeline:
  name: minio-deployments
  git:
    owner: ((github.owner))
    repo:  ((github.repo))
    private_key: ((github.private))
  email:
  vault:
    url:    ((vault_url))
    secret: ((vault_secret))
    role: none
    verify: no
  boshes:
    bucc:
      url:      ((bosh_environment))
      ca_cert:  ((bosh_ca_cert))
      username: ((bosh_client))
      password: ((bosh_client_secret))
      stemcells: [ default ]
  layouts:
    default: |+
      auto *bucc
      bucc
EOF
bucc fly
genesis repipe -t bucc

All that’s left now is making sure Concourse can access our deployment file. For this we will be using GitHub.

Create Minio-Deployments GitHub Repo

To simplify the process of creating a GitHub repository we are using the hub CLI tool. The created repo can be private or public, since all secrets will be stored inside CredHub. To create a public repo instead of a private one, remove the --private flag from the snippet below.

cd ~/workspace/minio-deployments
git config hub.protocol https
hub create --private
git add . && git commit -m "initial minio bucc deployment"
git push -u origin master

With our repo created, it’s time to add a deployment key. This SSH key will be used by Concourse to clone and push changes to the repo. We will use the Safe CLI to generate a SSH key pair in CredHub. Copy the public key and enter it in the GitHub page that’s opened when the hub browse command from the snippet blow is executed. Make sure to check Allow write access so genesis can update the repo after the deploy.

safe ssh /concourse/main/minio-deployments/github
safe get /concourse/main/minio-deployments/github:public
hub browse -- settings/keys

The last thing is making sure our Concourse pipeline knows where to find the repo. For this it needs to know the owner and the repo name, which can be extracted from your git config and stored in CredHub with the snippet below.

cd ~/workspace/minio-deployments
owner=$(git remote -v | head -n1 | cut -d/ -f4)
repo=$(git remote -v | head -n1 | cut -d/ -f5 | cut -d. -f1)
echo "Repo: ${repo} Owner: ${owner}"
safe set /concourse/main/minio-deployments/github owner=${owner}
safe set /concourse/main/minio-deployments/github repo=${repo}

At this point the Concourse pipeline is not uploading/updating the stemcells so this is still a manual step to take. Instruct the bosh director to download the latest stemcell from bosh.io:

bosh -e bucc upload-stemcell https://bosh.io/d/stemcells/bosh-warden-boshlite-ubuntu-xenial-go_agent

Start Deploying with Concourse

To kick off a build in Concourse using the fly CLI, the following snippet can be used.

source <(~/workspace/bucc/bin/bucc env)
bucc fly
fly -t bucc trigger-job --watch --job minio-deployments/bucc-minio

Alternatively, details for logging in to the Concourse web-ui can be found this way.

bucc info

Uploading a file to our created Minio instance

Since we are using the bosh_warden_cpi, our deployed minio instance is actually running inside a container. As such we can not access it via it’s ip address. We can however use the bosh cli to setup port forwarding:

bosh -d bucc-minio ssh minio --opts='-NCL 8443:127.0.0.1:443'
# --opts Options to pass through to SSH
# -N tells SSH that no command will be sent once the tunnel is up
# -C compresses data before sending
# -L given port on the local host forwarded to port on remote side.

Now open Minio in your browser https://127.0.0.1:8443, and use genesis to lookup the credentials:

genesis info bucc.yml

Use to web interface to create a bucket (bottom right corner) and upload a file.

I want more Genesis!

If you do think Genesis is awesome sauce, check out the other kits and see if anything tickles your fancy. Official Genesis Kits live on GitHub, in the Genesis Community organization. Notable Kits include:

SHIELD – A data protection solution for the cloud. Schedule backups and perform restores on databases, key-value stores, even file systems.
Cloud Foundry – The Cloud Foundry PaaS itself. Now deployed via Genesis.
Blacksmith – Data services, on-demand, leveraging BOSH. Available for CF marketplaces and Kubernetes!

Additionally if you are interested in replicating deployments to multiple different environments and building pipelines to keep them all in sync, you should take a look the Genesis management plane.

Written by:
Ruben Koster

Senior Cloud Architect