vRealize Automation Code Stream uses a Docker host to run CI Tasks by spinning up a specified container for the lifetime of the Pipeline, allowing you to execute scripted tasks inside the container and return the results.
One question I get asked a lot is “how do I set up a Docker host for Code Stream?” – well, here’s the answer!
Choose your Guest OS
I’ve tested these processes on the Ubuntu 18.04 and CentOS 7, but any supported Linux distribution can be used, so long as the outcome of the steps is the same. Deploy a VM with enough CPU and RAM for your needs – I’d suggest 2CPU/4GB is enough for a development environment, and I’d probably double that for production. Of course, the actual requirement depends on how many concurrent containers you’re running, the requirements of those containers and the task you’ll be performing.
Install a Docker Host
I install docker using the Docker Repositories with the default storage drivers. You don’t have to use this method to install Docker, again, any supported method and storage overlay is fine. I used the official docker install documentation – CentOS, Debian, Fedora, Ubuntu
Enable Docker Host Remote API
Create an override file for the Docker Service:
sudo systemctl edit docker.service
Add the following to configure the override to allow the docker daemon to listen on any IP (or specify the IP address you want to listen on):
[Service]
ExecStart=
ExecStart=/usr/bin/dockerd -H fd:// -H tcp://0.0.0.0:2375
Reload the systemd configuration, and restart the service:
sudo systemctl daemon-reload && sudo systemctl restart docker.service
You can then use netstat to validate that dockerd is listening on the configured port:
sudo netstat -lntp | grep dockerd
At this point we could add the Docker host to Code Stream and it would work perfectly well – however, the connection will unencrypted and data can potentially be intercepted.
Enable Docker Host Remote API over TLS
Code Stream can connect to the Docker endpoint using TLS to ensure traffic between the two hosts is encrypted (we can’t currently use a client certificate for mutual TLS – i.e. Docker doesn’t authenticate Code Stream).
To enable TLS we need obviously need a certificate for the Docker daemon to present. To generate a self-signed certificate, you can follow the official instructions Create a CA, server and client keys with OpenSSL on the Docker site. If you’re using an external CA signed certificate you need to make sure that the subjectAltName includes both the DNS and IPs of the Docker host, and extendedKeyUsage includes serverAuth. You do not need to generate a client certificate or key, since we will not configure the daemon with --tlsverify.
Once you’ve got the certificates, make sure to change the file permissions for both the keys and the certificate files. I’ve moved my certificate files into a folder I created in /etc/docker/ssl.
Finally, we need to update the override file for the Docker service using
sudo systemctl edit docker.service
Append the ExecStart command with --tls, --tlscacert, --tlscert and --tlskey flags, and update the port to 2376.
[Service]
ExecStart=
ExecStart=/usr/bin/dockerd -H fd:// -H tcp://0.0.0.0:2376 --tls --tlscacert=/path/to/ca.pem --tlscert=/path/to/server-cert.pem --tlskey=/path/to/server-key.pem
Reload the systemd configuration, and restart the service:
sudo systemctl daemon-reload && sudo systemctl restart docker.service
You can then use netstat again to validate that dockerd is listening on the configured port:
sudo netstat -lntp | grep dockerd
Restricting access with the host firewall
To further lock down the access to the API, you can also use a host firewall to restrict which IPs can connect to the Docker daemon port. Check the status of your firewall first, to ensure you’re not locking yourself out!
Add an allow rule for each of your vRealize Automation appliance IPs, or the vRealize Automation Cloud Proxy IP – and don’t forget to allow your SSH connection! I also added my local workstation IP to the rules to allow me to test the connection.
The following code was required from my newly installed CentOS/Ubuntu VMs:
Update: Thanks to Mark Monce for pointing out in the comments section that the cs-agent (which runs on the Docker image and allows Code Stream to configure and monitor the CI task) requires access on port in the range of 30000-32767, so that will also need to be opened to the vRA Appliance or vRA Cloud Proxy IP.
Adding a Docker Host to Code Stream
With the Docker daemon now running, encrypted and locked down for remote access, we can add it as an endpoint in Code Stream. Log onto Code Stream and then select Endpoints > + NEW ENDPOINT
- Select the Project to add the Docker endpoint to
- Select the Type as Docker
- Enter the name of the endpoint
- Add a description, if needed
- Select the Cloud Proxy (not required for vRealize Automation 8.x on premises)
- Enter the URL for the Docker host – when you add it with the https:// prefix, the ACCEPT CERTIFICATE button appears
Click ACCEPT CERTIFICATE and check the details to ensure it’s the correct certificate – the thumbprint of the certificate will be added to the endpoint to ensure it doesn’t change.
Finally, click VALIDATE and then CREATE to add the new endpoint.
Now the endpoint is available for consumption in your Pipelines:
Next Steps…
Building, configuring and adding a Docker host for vRealize Automation Code Stream is a basic building block that allows you create pipelines that automate highly complex build, test and release processes.
If you want to find out more about vRealize Automation please visit our website, or to learn more about our features, vRealize Automation Code Stream and explore vRealize Automation Cloud get started with a free 45-day trial!
