README.md

   1 Docker-Ansible base images
   2 ===================
   3
   4 [![Circle CI](https://circleci.com/gh/William-Yeh/docker-ansible.svg?style=shield)](https://circleci.com/gh/William-Yeh/docker-ansible) [![Build Status](https://travis-ci.org/William-Yeh/docker-ansible.svg?branch=master)](https://travis-ci.org/William-Yeh/docker-ansible)
   5
   6
   7 ## Summary
   8
   9 Repository name in Docker Hub: **[williamyeh/ansible](https://hub.docker.com/r/williamyeh/ansible/)**
  10
  11 This repository contains Dockerized [Ansible](https://github.com/ansible/ansible), published to the public [Docker Hub](https://hub.docker.com/) via **automated build** mechanism.
  12
  13
  14
  15 ## Configuration
  16
  17 These are Docker images for [Ansible](https://github.com/ansible/ansible) software, installed in a selected Linux distributions.
  18
  19 Base OS: Debian (jessie, wheezy), Ubuntu (xenial, trusty, precise), CentOS (7, 6), Alpine (3).
  20
  21 Ansible: four versions are provided -
  22
  23   1. provides the most recent *stable* version of Ansible; suitable for most people.
  24   2. same as stable version, but is designed for building (near-)*minimal* images out of playbooks; i.e., the Ansible body will be removed when mission completed. Refer to “[Build Docker images with Ansible: A half-blood approach](https://github.com/William-Yeh/build-docker-with-ansible)” for working examples and slides.
  25   3. provides the old 1.9 version of Ansible.
  26   4. provides the *experimental* version of Ansible; i.e., the master branch of git.
  27
  28 Each version is further divided into two variants:
  29
  30 - *Normal* variant: intended to be used as Ansible *control machines*, or in cases that is inadequate in the onbuild variants.
  31 - *Onbuild* variant: intended to be used to build Docker images.
  32
  33
  34 ## Images and tags
  35
  36 ### Stable version (installed from official PyPI repo):
  37
  38 - Normal variants:
  39
  40   - `williamyeh/ansible:debian8`
  41   - `williamyeh/ansible:debian7`
  42   - `williamyeh/ansible:ubuntu16.04`
  43   - `williamyeh/ansible:ubuntu14.04`
  44   - `williamyeh/ansible:ubuntu12.04`
  45   - `williamyeh/ansible:centos7`
  46   - `williamyeh/ansible:centos6`
  47   - `williamyeh/ansible:alpine3`
  48
  49 - Onbuild variants (*recommended for common cases*):
  50
  51   - `williamyeh/ansible:debian8-onbuild`
  52   - `williamyeh/ansible:debian7-onbuild`
  53   - `williamyeh/ansible:ubuntu16.04-onbuild`
  54   - `williamyeh/ansible:ubuntu14.04-onbuild`
  55   - `williamyeh/ansible:ubuntu12.04-onbuild`
  56   - `williamyeh/ansible:centos7-onbuild`
  57   - `williamyeh/ansible:centos6-onbuild`
  58   - `williamyeh/ansible:alpine3-onbuild`
  59
  60
  61 ### Minimal configuration (the Ansible body will be removed when mission completed):
  62
  63 Refer to “[Build Docker images with Ansible: A half-blood approach](https://github.com/William-Yeh/build-docker-with-ansible)” for working examples and slides.
  64
  65 - Onbuild variants:
  66
  67   - `williamyeh/ansible:mini-alpine3`
  68   - `williamyeh/ansible:mini-debian8`
  69
  70
  71 ### Old 1.9 version:
  72
  73 - Normal variants:
  74
  75   - `williamyeh/ansible:1.9-debian8`
  76   - `williamyeh/ansible:1.9-debian7`
  77   - `williamyeh/ansible:1.9-ubuntu14.04`
  78   - `williamyeh/ansible:1.9-ubuntu12.04`
  79   - `williamyeh/ansible:1.9-centos7`
  80   - `williamyeh/ansible:1.9-centos6`
  81   - `williamyeh/ansible:1.9-alpine3`
  82
  83 - Onbuild variants (*recommended for common cases*):
  84
  85   - `williamyeh/ansible:1.9-debian8-onbuild`
  86   - `williamyeh/ansible:1.9-debian7-onbuild`
  87   - `williamyeh/ansible:1.9-ubuntu14.04-onbuild`
  88   - `williamyeh/ansible:1.9-ubuntu12.04-onbuild`
  89   - `williamyeh/ansible:1.9-centos7-onbuild`
  90   - `williamyeh/ansible:1.9-centos6-onbuild`
  91   - `williamyeh/ansible:1.9-alpine3-onbuild`
  92
  93
  94 ### Experimental version (building directly from the git `master` source tree; use at your own risk!):
  95
  96 - Normal variants:
  97
  98   - `williamyeh/ansible:master-debian8`
  99   - `williamyeh/ansible:master-debian7`
 100   - `williamyeh/ansible:master-ubuntu16.04`
 101   - `williamyeh/ansible:master-ubuntu14.04`
 102   - `williamyeh/ansible:master-ubuntu12.04`
 103   - `williamyeh/ansible:master-centos7`
 104   - `williamyeh/ansible:master-centos6`
 105
 106 - Onbuild variants (*recommended for common cases*):
 107
 108   - `williamyeh/ansible:master-debian8-onbuild`
 109   - `williamyeh/ansible:master-debian7-onbuild`
 110   - `williamyeh/ansible:master-ubuntu16.04-onbuild`
 111   - `williamyeh/ansible:master-ubuntu14.04-onbuild`
 112   - `williamyeh/ansible:master-ubuntu12.04-onbuild`
 113   - `williamyeh/ansible:master-centos7-onbuild`
 114   - `williamyeh/ansible:master-centos6-onbuild`
 115
 116
 117
 118 ## For the impatient
 119
 120 Here comes a simplest working example for the impatient.
 121
 122 First, choose a base image you'd like to begin with. For example, `williamyeh/ansible:ubuntu14.04-onbuild`.
 123
 124 Second, put the following `Dockerfile` along with your playbook directory:
 125
 126 ```
 127 FROM williamyeh/ansible:ubuntu14.04-onbuild
 128
 129 # ==> Specify requirements filename;  default = "requirements.yml"
 130 #ENV REQUIREMENTS  requirements.yml
 131
 132 # ==> Specify playbook filename;      default = "playbook.yml"
 133 #ENV PLAYBOOK      playbook.yml
 134
 135 # ==> Specify inventory filename;     default = "/etc/ansible/hosts"
 136 #ENV INVENTORY     inventory.ini
 137
 138 # ==> Executing Ansible (with a simple wrapper)...
 139 RUN ansible-playbook-wrapper
 140 ```
 141
 142 Third, `docker build .`
 143
 144 Done!
 145
 146 For more advanced usage, the role in Ansible Galaxy [`williamyeh/nginx`](https://galaxy.ansible.com/williamyeh/nginx/) demonstrates how to perform a simple smoke test (*configuration needs test, too!*) on a variety of (*containerized*) Linux distributions on [CircleCI](https://circleci.com/)'s Ubuntu 12.04 and [Travis CI](https://travis-ci.org/)’s Ubuntu 14.04 worker instances.
 147
 148
 149
 150
 151 ## Why yet another Ansible image for Docker?
 152
 153 There has been quite a few Ansible images for Docker (e.g., [search](https://hub.docker.com/search/?q=ansible&isAutomated=0&isOfficial=0&page=1&pullCount=1&starCount=0) in the Docker Hub), so why reinvent the wheel?
 154
 155 In the beginning I used the [`ansible/ansible-docker-base`](https://github.com/ansible/ansible-docker-base) created by Ansible Inc. It worked well, but left some room for improvement:
 156
 157 - *Base OS image* - It provides only `centos:centos7` and `ubuntu:14.04`.  Insufficent for me.
 158
 159 - *Unnecessary dependencies* - It installed, at the very beginning of its Dockerfile, the `software-properties-common` package, which in turns installed some Python packages. I prefered to incorporate these stuff only when absolutely needed.
 160
 161 Therefore, I built these Docker images on my own.
 162
 163 **NOTE:** [`ansible/ansible-docker-base`](https://github.com/ansible/ansible-docker-base) announced in September 2015: “Ansible no longer maintains images in Dockerhub directly.”
 164
 165 ### Comparison: image size
 166
 167 ```
 168 REPOSITORY                    TAG                   VIRTUAL SIZE
 169 ---------------------------   -------------------   ------------
 170 ansible/centos7-ansible       stable                367.5 MB
 171 ansible/ubuntu14.04-ansible   stable                286.6 MB
 172
 173 williamyeh/ansible            alpine3-onbuild        66.4 MB
 174 williamyeh/ansible            centos6-onbuild       264.2 MB
 175 williamyeh/ansible            centos7-onbuild       275.3 MB
 176 williamyeh/ansible            debian7-onbuild       134.4 MB
 177 williamyeh/ansible            debian8-onbuild       178.3 MB
 178 williamyeh/ansible            ubuntu12.04-onbuild   181.9 MB
 179 williamyeh/ansible            ubuntu14.04-onbuild   238.3 MB
 180 ```
 181
 182
 183 ## Usage
 184
 185 Used mostly as a *base image* for configuring other software stack on some specified Linux distribution(s).
 186
 187 Take Debian/Ubuntu/CentOS for example. To test an Ansible `playbook.yml` against a variety of Linux distributions, we may use [Vagrant](https://www.vagrantup.com/) as follows:
 188
 189 ```ruby
 190 # Vagrantfile
 191
 192 Vagrant.configure(2) do |config|
 193
 194     # ==> Choose a Vagrant box to emulate Linux distribution...
 195     #config.vm.box = "ubuntu/xenial64"
 196     config.vm.box = "ubuntu/trusty64"
 197     #config.vm.box = "ubuntu/precise64"
 198     #config.vm.box = "debian/jessie64"
 199     #config.vm.box = "debian/wheezy64"
 200     #config.vm.box = "bento/centos-7.2"
 201     #config.vm.box = "bento/centos-6.7"
 202     #config.vm.box = "maier/alpine-3.3.1-x86_64"
 203
 204
 205     # ==> Executing Ansible...
 206     config.vm.provision "ansible" do |ansible|
 207         ansible.playbook = "playbook.yml"
 208     end
 209
 210 end
 211 ```
 212
 213 Virtual machines can emulate a variety of Linux distributions with good quality, at the cost of runtime overhead.
 214
 215
 216 Docker to be a rescue. Now, with these **williamyeh/ansible** series, we may test an Ansible `playbook.yml` against a variety of Linux distributions as follows:
 217
 218
 219 ```dockerfile
 220 # Dockerfile
 221
 222 # ==> Choose a base image to emulate Linux distribution...
 223 #FROM williamyeh/ansible:ubuntu16.04
 224 FROM williamyeh/ansible:ubuntu14.04
 225 #FROM williamyeh/ansible:ubuntu12.04
 226 #FROM williamyeh/ansible:debian8
 227 #FROM williamyeh/ansible:debian7
 228 #FROM williamyeh/ansible:centos7
 229 #FROM williamyeh/ansible:centos6
 230 #FROM williamyeh/ansible:alpine3
 231
 232
 233 # ==> Copying Ansible playbook...
 234 WORKDIR /tmp
 235 COPY  .  /tmp
 236
 237 # ==> Creating inventory file...
 238 RUN echo localhost > inventory
 239
 240 # ==> Executing Ansible...
 241 RUN ansible-playbook -i inventory playbook.yml \
 242       --connection=local --sudo
 243 ```
 244
 245 You may also work with `onbuild` variants, which take care of many routine steps for you:
 246
 247 ```dockerfile
 248 # Dockerfile
 249
 250 # ==> Choose a base image to emulate Linux distribution...
 251 #FROM williamyeh/ansible:ubuntu16.04-onbuild
 252 FROM williamyeh/ansible:ubuntu14.04-onbuild
 253 #FROM williamyeh/ansible:ubuntu12.04-onbuild
 254 #FROM williamyeh/ansible:debian8-onbuild
 255 #FROM williamyeh/ansible:debian7-onbuild
 256 #FROM williamyeh/ansible:centos7-onbuild
 257 #FROM williamyeh/ansible:centos6-onbuild
 258 #FROM williamyeh/ansible:alpine3-onbuild
 259
 260
 261 # ==> Specify requirements filename;  default = "requirements.yml"
 262 #ENV REQUIREMENTS  requirements.yml
 263
 264 # ==> Specify playbook filename;      default = "playbook.yml"
 265 #ENV PLAYBOOK      playbook.yml
 266
 267 # ==> Specify inventory filename;     default = "/etc/ansible/hosts"
 268 #ENV INVENTORY     inventory.ini
 269
 270 # ==> Executing Ansible (with a simple wrapper)...
 271 RUN ansible-playbook-wrapper
 272 ```
 273
 274
 275
 276 With Docker, we can test any Ansible playbook against any version of any Linux distribution without the help of Vagrant. More lightweight, and more portable across IaaS, PaaS, and even CaaS (Container as a Service) providers!
 277
 278 If better OS emulation (virtualization) isn't required, the Docker approach (containerization) should give you a more efficient Ansible experience.
 279
 280
 281
 282 ## License
 283
 284 Author: William Yeh <william.pjyeh@gmail.com>
 285
 286 Licensed under the Apache License V2.0. See the [LICENSE file](LICENSE) for details.