terraform-provider-libvirt/contrib/README.md

Community Driven Docker Examples

These docker containers are meant to serve as an isolated development environment. The most common use case for these containers are to run your terraform environment in an isolate container talking to a remote libvirt system.

Please refer to the distro's README.md for specific instructions.

Additionally, you will find a Build folder along side the distro folders. The docker containers within the Build folder will compile the terraform libvirt provider for you. Please refer to the Build folder's README.md for more information and instructions.

Table of Content

Distro Containers

• Alpine Containers
• Debian Containers
• openSUSE Containers

Build Containers

• Build Containers

Quickstart

1. Grab the all-in-one container for the distro you want, in this case we are using openSUSE

   git clone https://github.com/dmacvicar/terraform-provider-libvirt.git; cd ./terraform-provider-libvirt/contrib/openSUSE/
   

2. Build the all-in-one container

   docker build -f Dockerfile_all_in_one -t terraform:development-tumbleweed . --build-arg GO_OS=linux --build-arg GO_ARCH=amd64
   

3. Run the docker container

   docker run -it terraform:development-tumbleweed /bin/bash
   

General Usage

There are two types of containers you'll find for each distro, All-in-One and Build-Dependent.

All-in-One v.s Build-Dependent Containers

The All-in-One container is a single Dockerfile that you can build and run. The Dockerfile takes advantage of Docker's multi-stage build functionality. It allows you to build a binary object in a "sub container" and then access the binary object in your "main container". This Dockerfile is useful if you want to get up and running quickly, but might lead to confusion down the road if plan on using multiple versions of the terraform libvirt provider.

The Build-Dependent container relies on another Dockerfile which contains the build of the plugin. To use this container you need to first build the appropriate build Dockerfile and tag it correctly. Once that is done, you are able to reference it inside the Build-Dependent's Dockerfile. This design is useful when you are dealing with multiple versions of the terraform libvirt provider such as, 0.5.2, which works with Terraform 0.11.X and the latest branch, master, which currently works with Terraform 0.12.x.

Build Argument Reference

The following arguments are supported:

• VERSION - (Required) A name of a branch or tag of the terraform libvirt plugin to build
• TERRAFORM_VERSION - (Optional) - A tag of the official docker terraform image to pull from
• GO_ARCH - (Required) The GO name of your given architecture
• GO_OS - (Required) The GO name of your given OS

Examples

Build containers examples:

docker build -f Dockerfile_glibc -t provider-libvirt:v0.5.2-glibc . --build-arg VERSION=v0.5.2

This command would checkout the tag v0.5.2.

docker build -f Dockerfile_glibc -t provider-libvirt:master-glibc . --build-arg VERSION=master

This command would checkout the master branch.

distro containers examples:

docker build -f Dockerfile_build_dependent -t terraform:development-tumbleweed . --build-arg GO_OS=linux --build-arg GO_ARCH=amd64 --build-arg TERRAFORM_VERSION=0.11.14

This command builds a distro container, tags it as terraform:development-tumbleweed, sets the GO_OS to linux and GO_ARCH to amd64 and sets the terraform version to 0.11.14.

docker build -f Dockerfile_build_dependent -t terraform:development-debian . --build-arg GO_OS=linux --build-arg GO_ARCH=s390x

This command builds a distro container, tags it as terraform:development-debian, sets the GO_OS to linux and GO_ARCH to s390x and will use the default value of 0.12.0 for terraform.

Running on non-supported Terraform Architectures

Terraform currently does support other architectures other then amd64, thus running on other architectures like s390x can be troublesome.

The docker containers only needs a slight modification to run on s390x. Note: The Build containers will run on any architectures that support GO and should not need modification.

In the distro containers you should see a line like:

# Grab the Terraform binary
FROM hashicorp/terraform:$TERRAFORM_VERSION AS terraform

Currently, that is pulling in the official Terraform docker container. To get it to work on your desired architecture you need to build the Terraform binary yourself. You can do that by building the Dockerfile below:

FROM golang:alpine

ARG TERRAFORM_VERSION
ENV TERRAFORM_VERSION=$TERRAFORM_VERSION

RUN apk add --update git bash openssh

ENV TF_DEV=true
ENV TF_RELEASE=true

WORKDIR $GOPATH/src/github.com/hashicorp/terraform
RUN git clone https://github.com/hashicorp/terraform.git ./ && \
    git checkout v${TERRAFORM_VERSION} && \
    /bin/bash scripts/build.sh

WORKDIR $GOPATH
ENTRYPOINT ["terraform"]

With this Dockerfile built, you now need to swap the FROM hashicorp/terraform:$TERRAFORM_VERSION AS terraform with your images name and tag.

Note: Even if you get the terraform binary built for your respective architecture, you might need to build other providers you utilize in your terraform files. As the default providers are not built for unsupported architectures.

Tips and Tricks

• The use of Docker Volumes helps transfer Terraform config files back and forth between your local system and the docker container.

• Most remote libvirt systems require SSH Key auth. To generate a new SSH Key in Dockerfile use the following code:

  # Make SSH Key
  RUN mkdir -p /root/.ssh/
  RUN touch /root/.ssh/id_rsa
  RUN chmod 600 /root/.ssh/id_rsa
  RUN echo "Host *" > /root/.ssh/config && echo " StrictHostKeyChecking no" >> /root/.ssh/config