posted

2 Comments

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!