Awesome
Stembuild
The stembuild binary is used to build BOSH stemcells for Windows 2012R2,Windows Server, version v1709, Windows Server, version 1803, Windows Server 2019 on vSphere.
Instructions: See here for instructions to build Windows stemcells for vSphere.
Installation
Download the latest stembuild from the Releases Page that corresponds to the operating system of your local host and the stemcell version that you want to build
Dependencies
LGPO must be downloaded in the same folder as your stembuild
Current Commands
stembuild version <STEMCELL-VERSION>, Windows Stemcell Building Tool
Usage: stembuild <global options> <command> <command flags>
Commands:
help Describe commands and their syntax
package Create a BOSH Stemcell from a VMDK file or a provisioned vCenter VM
construct Provisions and syspreps an existing VM on vCenter, ready to be packaged into a stemcell
Global Options:
-color Colorize debug output
-debug Print lots of debugging information
-v Stembuild version (shorthand)
-version Show Stembuild version
stembuild construct
This command provisions and syspreps an existing VM on vCenter. It prepares a VM to be used by stembuild package
.
stembuild construct -vm-ip <IP of VM> -vm-username <vm username> -vm-password <vm password> -vcenter-url <vCenter URL> -vcenter-username <vCenter username> -vcenter-password <vCenter password> -vm-inventory-path <vCenter VM inventory path>
Requirements
- LGPO.zip in current working directory
- Running Windows VM with:
- Up-to-date Operating System
- Reachable by IP over port 5985
- Username and password with Administrator privileges
- vCenter URL, username and password
- vCenter Inventory Path
- The
vm-ip
,vm-username
,vm-password
,vcenter-url
,vcenter-username
,vcenter-password
,vm-inventory-path
must be specified
Example:
stembuild construct -vm-ip '10.0.0.5' -vm-username Admin -vm-password 'password' -vcenter-url vcenter.example.com -vcenter-username root -vcenter-password 'password' -vm-inventory-path '/datacenter/vm/folder/vm-name'
Flags:
-vcenter-ca-certs string
filepath for custom ca certs
-vcenter-password string
vCenter password
-vcenter-url string
vCenter url
-vcenter-username string
vCenter username
-vm-inventory-path string
vCenter VM inventory path. (e.g: /<datacenter>/vm/<vm-folder>/<vm-name>)
-vm-ip string
IP of target machine
-vm-password string
Password of target machine. Needs to be wrapped in single quotations.
-vm-username string
Username of target machine
Troubleshooting
After running stembuild construct
, you may find yourself with a connection issue to the VM
- Confirm port 5985 is reachable via something like
nmap [vm-ip] -Pn
stembuild package
This command creates a BOSH Stemcell from a provisioned vCenter VM
stembuild package -vcenter-url <vCenter URL> -vcenter-username <vCenter username> -vcenter-password <vCenter password> -vm-inventory-path <vCenter VM inventory path> [-patch-version <patch version string>]
Requirements:
- VM provisioned using the stembuild construct command
- Access to vCenter environment
- The
vcenter-url
,vcenter-username
,vcenter-password
, andvm-inventory-path
flags must be specified. - NOTE: The 'vm' keyword must be included between the datacenter name and folder name for the vm-inventory-path (e.g: /<datacenter>/vm/<vm-folder>/<vm-name>)
Example:
stembuild package -vcenter-url vcenter.example.com -vcenter-username root -vcenter-password 'password' -vm-inventory-path '/my-datacenter/vm/my-folder/my-vm'
Flags:
-o string
Output directory (shorthand)
-outputDir string
Output directory, default is the current working directory.
-vcenter-ca-certs string
filepath for custom ca certs
-vcenter-password string
vCenter password
-vcenter-url string
vCenter url
-vcenter-username string
vCenter username
-vm-inventory-path string
vCenter VM inventory path. (e.g: /<datacenter>/vm/<vm-folder>/<vm-name>)
-patch-version string
Number or name of the patch version for the stemcell being built (e.g: for 2019.12.3 the string would be “3”)
Compiling & Running Stembuild Locally
Assuming you've followed these instructions and you've created a Windows VM at 10.9.9.115 whose Administrator's password is "c1oudc0w".
export TARGET_VM_PASSWORD=c1oudc0w VCENTER_PASSWORD='Admin!23'
BOSH_AGENT_REPO=~/workspace/bosh-agent STEMBUILD_VERSION=2019.2 make
GOVC_INSECURE=true out/stembuild -debug \
construct \
-vm-ip 10.9.9.115 \
-vm-username Administrator \
-vm-password $TARGET_VM_PASSWORD \
-vcenter-url vcenter-70.nono.io \
-vcenter-username administrator@vsphere.local \
-vcenter-password $VCENTER_PASSWORD \
-vm-inventory-path "/dc/vm/Discovered virtual machine/w2019-stemcell"
GOVC_INSECURE=true out/stembuild -debug \
package \
-vcenter-url vcenter-70.nono.io \
-vcenter-username administrator@vsphere.local \
-vcenter-password $VCENTER_PASSWORD \
-vm-inventory-path "/dc/vm/Discovered virtual machine/w2019-stemcell"
[DEPRECATED] Package a Windows Stemcell from a VMDK using stembuild package
This command converts a VMDK into a bosh-deployable Windows Stemcell
The VMware 'ovftool' binary must be on your path or Fusion/Workstation must be installed (both include the 'ovftool').
stembuild package -vmdk <path-to-vmdk>
Requirements
- The VMware 'ovftool' binary must be on your path or Fusion/Workstation must be installed (both include the 'ovftool').
- The
vmdk
flag must be specified. If theoutput
flag is not specified the stemcell will be created in the current working directory.
Example:
stembuild package -vmdk my-1803-vmdk.vmdk
Will create an Windows 1803 stemcell using [vmdk] 'my-1803-vmdk.vmdk'
The final stemcell will be found in the current working directory.
Flags:
-o string
Output directory (shorthand)
-outputDir string
Output directory, default is the current working directory.
-vmdk string
VMDK file to create stemcell from
Process can take between 10 and 20 minutes. See Progress with -debug
flag.
Testing
Testing stembuild itself
Older tests were written using the default testing framework. However, more recent code has been test-driven with Ginkgo. We recommend that any new code be test-driven using Ginkgo. Below are steps to run the tests:
Make puts some files in out
dir. To clean state of this dir:
make clean
To run only unit tests:
make units
To run integration tests:
make integration
Testing stemcell-automation
stemcell-automation
contains powershell scripts which stembuild runs on the target VM. This directory also contains tests
for the scripts, which are written with the test framework Pester. These require running in powershell on a Windows environment.
cd stemcell-automation
invoke-pester
Vendoring
Vendoring for this project is done using dep
.
To sync all the dependencies run
dep ensure
To add a new dependency run
dep ensure -add <git package url>
like
dep ensure -add github.com/google/subcommands
To check if dependencies are in sync or not run
dep sync
The output should be nothing if there are no out-of-sync dependencies.
Compile stembuild locally
Some of the make targets require the use of curl and xq to download the latest dependencies from S3 to create the embedded StemcellAutomation.zip resource. The dependencies downloaded from s3 are the same ones used by stembuild CI.
Download or clone the bosh-agent repository
git clone https://github.com/cloudfoundry/bosh-agent.git
Download or clone the stembuild repository and navigate to it
git clone https://github.com/cloudfoundry/stembuild.git
cd stembuild
Use make build
to build stembuild, providing the corresponding values for the bosh-agent path and stemcell version you
would like to build, for example:
BOSH_AGENT_REPO=../bosh-agent STEMBUILD_VERSION=2019.70 make build