This repository contains the code used to build the Ubuntu-based Delphix Appliance, leveraging open-source tools such as Debian's live-build, Docker, Ansible, OpenZFS, and others. It is capable of producing virtual machine images containing the Delphix Dynamic Data Platform, that are capable of running in cloud and non-cloud hypervisors alike (e.g. Amazon EC2, Microsoft Azure, VMware, OpenStack).
Run this command on "dlpxdc.co" to create the VM used to do the build:
$ dc clone-latest --size COMPUTE_LARGE bootstrap-18-04 $USER-bootstrap
Log into that VM using the "ubuntu" user, and run these commands:
$ git clone https://github.com/delphix/appliance-build.git
$ cd appliance-build
$ ansible-playbook bootstrap/playbook.yml
$ ./scripts/docker-run.sh make internal-minimal
$ sudo qemu-system-x86_64 -nographic -m 1G \
> -drive file=live-build/artifacts/internal-minimal.qcow2
To exit "qemu", use "Ctrl-A X".
This software is provided as-is, without warranty of any kind or commercial support through Delphix. See the associated license for additional details. Questions, issues, feature requests, and contributions should be directed to the community as outlined in the Delphix Community Guidelines.
The Delphix Appliance build system has the following assuptions about the environment from which it will be executed:
-
Docker must be installed and available to be used on the host that'll run the build. A Dockerfile is included in this repository, which captures nearly all of the runtime dependencies needed to execute the build. It is assumed that a Docker image will be generated using this Dockerfile, and then the build executed in a Docker container based on that Docker image. This way, the amount of dependencies on the host system running the build is minimal.
-
The Docker host used to run the build must be based on Ubuntu 18.04. As part of the build system, a ZFS pool and dataset will be generated. The userspace ZFS utilities will be executed from the Docker container, but they interact with the ZFS kernel modules provided by the host. Thus, to ensure compatibility between the ZFS userspace utilities in the Docker container, and the ZFS kernel modules in the host, we require the host system to be running the same Ubuntu release as the Docker container that will be used.
-
The Docker container must have access to Delphix's Artifactory service, as well as Delphix's AWS S3 buckets; generally this is accomplished by running the build within Delphix's VPN. This is required so that the build can download Delphix's Java distribution stored in Artifactory, along with the Delphix specific packages stored in S3.
The following section will attempt to outline the steps required to execute the build, resulting in the Delphix Appliance virtual machine images.
Delphix maintains the "bootstrap-18-04" group in DCenter on AWS that fulfills the required build dependencies previously described. Thus, the first step is to use this group to create the host that will be used to execute the build. This can be done as usual, using "dc clone-latest".
Example commands running on "dlpxdc.co":
$ export DLPX_DC_INSTANCE_PUB_KEY=~/.ssh/id_rsa.pub
$ dc clone-latest --size COMPUTE_LARGE bootstrap-18-04 ps-build
Use the "ubuntu" user to log in to the VM after it's cloned; all of the following steps assume their being run on the cloned VM.
Once the "bootstrap" DCenter on AWS VM is created, the "appliance-build" repository needs to be populated on it. Generally this is done using "git" primitives, e.g. "git clone", "git checkout", etc. For this example, we'll do a new "git clone" of the upstream repository:
$ git clone https://github.com/delphix/appliance-build.git
$ cd appliance-build
Next, we need to apply the "bootstrap" Ansible configuration, which will verify all the necessary build dependencies are fulfilled, while also correcting any deficencies that may exist. This is easily done like so:
$ ansible-playbook bootstrap/playbook.yml
Now, with the "bootstrap" VM properly configured, we can run the build:
$ ./scripts/docker-run.sh make
This will create a new container based on the image we previously created, and then execute "make" inside of that container.
The "./scripts/docker-run" script can also be run without any arguments, which will provide an interactive shell running in the container environment, with the appliance-build git repository mounted inside of the container; this can be useful for debugging and/or experimenting.
By default, all "internal" variants will be built when "make" is specified without any options. Each variant will have ansible roles applied according to playbooks in per variant directories under live-build/variants. A specific variant can be built by passing in the variant's name:
$ ./scripts/docker-run.sh make internal-minimal
When this completes, the newly built VM artifacts will be contained in the "live-build/artifacts" directory:
$ ls -l live-build/artifacts
total 6.0G
-rw-r--r-- 1 root root 975M Apr 30 19:47 internal-minimal.ova
-rw-r--r-- 1 root root 1009M Apr 30 19:43 internal-minimal.qcow2
-rw-r--r-- 1 root root 2.8G Apr 30 19:44 internal-minimal.vhdx
-rw-r--r-- 1 root root 975M Apr 30 19:47 internal-minimal.vmdk
Once the live-build artifacts have been generated, we can then leverage the "qemu" tool to test the "qcow2" artifact:
$ sudo qemu-system-x86_64 -nographic -m 1G \
> -drive file=live-build/artifacts/internal-minimal.qcow2
This will attempt to boot the "qcow2" VM image, minimally verifying that any changes to the build don't cause a boot failure. Further, after the image boots (assuming it boots successfully), one can log in via the console and perform any post-boot verification that's required (e.g. verify certain packages are installed, etc).
To exit "qemu", one can use "Ctrl-A X".
This repository contains different build variants which are used to generate customized images, leveraging different Ansible roles to customize those variants. The following instructions can be used to create a new build variant and roles.
The different variants are located in the "live-build/variants" directory:
$ ls -l live-build/variants
total 0
drwxr-xr-x 5 root root 160 Jun 4 22:56 external-standard
drwxr-xr-x 5 root root 160 Jun 4 22:56 internal-dev
drwxr-xr-x 5 root root 160 Jun 4 22:56 internal-minimal
drwxr-xr-x 5 root root 160 Jun 4 22:56 internal-qa
To create a new variant, run the "create-variant.sh" script. Note that variant names use the "internal" and "external" prefixes:
$ ./scripts/create-variant.sh internal-dcenter
The new variant that was just created may require some customizations applied to it, that are specific to this new variant. In order to apply these customization, a new Ansible role can be created and used. All existing Ansible roles that are used to customize existing build variants are located in the "live-build/misc/ansible-roles" directory, and follow the standard Ansible role directory structure (i.e. tasks, handlers, files, etc.)
To create a new Ansible role, a new Ansible role directory will need to be created. In this example, the name of our Ansible role will be "appliance-build.dcenter" to match the name of our variant:
$ mkdir -p live-build/misc/ansible-roles/appliance-build.dcenter/tasks
There are many roles that exist in "live-build/misc/ansible-roles" which can serve as good examples.
With the role[s] created, you can populate the "playbook.yml" file in the new variant's "ansible" directory:
$ ls -l live-build/variants/internal-dcenter/ansible
total 8
-rw-r--r-- 1 root root 891 Jun 29 14:43 playbook.yml
lrwxr-xr-x 1 root root 27 Jun 19 19:17 roles -> ../../../misc/ansible-roles
For this example, we add our new role to the playboodk as shown below:
---
- hosts: all
connection: chroot
gather_facts: no
vars:
ansible_python_interpreter: /usr/bin/python3
roles:
- appliance-build.minimal-common
- appliance-build.minimal-internal
- appliance-build.dcenter
See the instructions above to setup your build environment and kick off the build:
$ ./scripts/docker-run.sh make internal-dcenter