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 - OS: Debian (jessie, wheezy), Ubuntu (xenial, trusty, precise), CentOS (7, 6), Alpine (3).
  20
  21 - Ansible: four versions -
  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 *minimal* images out of playbooks; i.e., the Ansible body will be removed when mission completed.
  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
  29 Each version is further divided into two variants:
  30
  31 - Normal variant: intended to be used as Ansible *control machines*, or in cases that is unsuitable in the onbuild variants.
  32 - Onbuild variant: intended to be used to build Docker images.
  33
  34
  35 ## Images and tags
  36
  37 ### Stable version (installed from official PyPI repo):
  38
  39 - Normal variants:
  40
  41   - `williamyeh/ansible:debian8`
  42   - `williamyeh/ansible:debian7`
  43   - `williamyeh/ansible:ubuntu16.04`
  44   - `williamyeh/ansible:ubuntu14.04`
  45   - `williamyeh/ansible:ubuntu12.04`
  46   - `williamyeh/ansible:centos7`
  47   - `williamyeh/ansible:centos6`
  48   - `williamyeh/ansible:alpine3`
  49
  50 - Onbuild variants (*recommended for common cases*):
  51
  52   - `williamyeh/ansible:debian8-onbuild`
  53   - `williamyeh/ansible:debian7-onbuild`
  54   - `williamyeh/ansible:ubuntu16.04-onbuild`
  55   - `williamyeh/ansible:ubuntu14.04-onbuild`
  56   - `williamyeh/ansible:ubuntu12.04-onbuild`
  57   - `williamyeh/ansible:centos7-onbuild`
  58   - `williamyeh/ansible:centos6-onbuild`
  59   - `williamyeh/ansible:alpine3-onbuild`
  60
  61
  62 ### Minimal configuration (the Ansible body will be removed when mission completed):
  63
  64 - Onbuild variants:
  65
  66   - `williamyeh/ansible:mini-alpine3`
  67   - `williamyeh/ansible:mini-debian8`
  68
  69
  70 ### Old 1.9 version:
  71
  72 - Normal variants:
  73
  74   - `williamyeh/ansible:1.9-debian8`
  75   - `williamyeh/ansible:1.9-debian7`
  76   - `williamyeh/ansible:1.9-ubuntu14.04`
  77   - `williamyeh/ansible:1.9-ubuntu12.04`
  78   - `williamyeh/ansible:1.9-centos7`
  79   - `williamyeh/ansible:1.9-centos6`
  80   - `williamyeh/ansible:1.9-alpine3`
  81
  82 - Onbuild variants (*recommended for common cases*):
  83
  84   - `williamyeh/ansible:1.9-debian8-onbuild`
  85   - `williamyeh/ansible:1.9-debian7-onbuild`
  86   - `williamyeh/ansible:1.9-ubuntu14.04-onbuild`
  87   - `williamyeh/ansible:1.9-ubuntu12.04-onbuild`
  88   - `williamyeh/ansible:1.9-centos7-onbuild`
  89   - `williamyeh/ansible:1.9-centos6-onbuild`
  90   - `williamyeh/ansible:1.9-alpine3-onbuild`
  91
  92
  93 ### Experimental version (building directly from the git `master` source tree; use at your own risk!):
  94
  95 - Normal variants:
  96
  97   - `williamyeh/ansible:master-debian8`
  98   - `williamyeh/ansible:master-debian7`
  99   - `williamyeh/ansible:master-ubuntu16.04`
 100   - `williamyeh/ansible:master-ubuntu14.04`
 101   - `williamyeh/ansible:master-ubuntu12.04`
 102   - `williamyeh/ansible:master-centos7`
 103   - `williamyeh/ansible:master-centos6`
 104
 105 - Onbuild variants (*recommended for common cases*):
 106
 107   - `williamyeh/ansible:master-debian8-onbuild`
 108   - `williamyeh/ansible:master-debian7-onbuild`
 109   - `williamyeh/ansible:master-ubuntu16.04-onbuild`
 110   - `williamyeh/ansible:master-ubuntu14.04-onbuild`
 111   - `williamyeh/ansible:master-ubuntu12.04-onbuild`
 112   - `williamyeh/ansible:master-centos7-onbuild`
 113   - `williamyeh/ansible:master-centos6-onbuild`
 114
 115
 116
 117 ## For the impatient
 118
 119 Here comes a simplest working example for the impatient.
 120
 121 First, choose a base image you'd like to begin with. For example, `williamyeh/ansible:ubuntu14.04-onbuild`.
 122
 123 Second, put the following `Dockerfile` along with your playbook directory:
 124
 125 ```
 126 FROM williamyeh/ansible:ubuntu14.04-onbuild
 127
 128 # ==> Specify requirements filename;  default = "requirements.yml"
 129 #ENV REQUIREMENTS  requirements.yml
 130
 131 # ==> Specify playbook filename;      default = "playbook.yml"
 132 #ENV PLAYBOOK      playbook.yml
 133
 134 # ==> Specify inventory filename;     default = "/etc/ansible/hosts"
 135 #ENV INVENTORY     inventory.ini
 136
 137 # ==> Executing Ansible (with a simple wrapper)...
 138 RUN ansible-playbook-wrapper
 139 ```
 140
 141 Third, `docker build .`
 142
 143 Done!
 144
 145 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.
 146
 147
 148
 149
 150 ## Why yet another Ansible image for Docker?
 151
 152 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?
 153
 154 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:
 155
 156 - *Base OS image* - It provides only `centos:centos7` and `ubuntu:14.04`.  Insufficent for me.
 157
 158 - *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.
 159
 160 Therefore, I built these Docker images on my own.
 161
 162 **NOTE:** [`ansible/ansible-docker-base`](https://github.com/ansible/ansible-docker-base) announced in September 2015: “Ansible no longer maintains images in Dockerhub directly.”
 163
 164 ### Comparison: image size
 165
 166 ```
 167 REPOSITORY                    TAG                   VIRTUAL SIZE
 168 ---------------------------   -------------------   ------------
 169 ansible/centos7-ansible       stable                367.5 MB
 170 ansible/ubuntu14.04-ansible   stable                286.6 MB
 171
 172 williamyeh/ansible            alpine3-onbuild        66.4 MB
 173 williamyeh/ansible            centos6-onbuild       264.2 MB
 174 williamyeh/ansible            centos7-onbuild       275.3 MB
 175 williamyeh/ansible            debian7-onbuild       134.4 MB
 176 williamyeh/ansible            debian8-onbuild       178.3 MB
 177 williamyeh/ansible            ubuntu12.04-onbuild   181.9 MB
 178 williamyeh/ansible            ubuntu14.04-onbuild   238.3 MB
 179 ```
 180
 181
 182 ## Usage
 183
 184 Used mostly as a *base image* for configuring other software stack on some specified Linux distribution(s).
 185
 186 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:
 187
 188 ```ruby
 189 # Vagrantfile
 190
 191 Vagrant.configure(2) do |config|
 192
 193     # ==> Choose a Vagrant box to emulate Linux distribution...
 194     #config.vm.box = "ubuntu/xenial64"
 195     config.vm.box = "ubuntu/trusty64"
 196     #config.vm.box = "ubuntu/precise64"
 197     #config.vm.box = "debian/jessie64"
 198     #config.vm.box = "debian/wheezy64"
 199     #config.vm.box = "bento/centos-7.2"
 200     #config.vm.box = "bento/centos-6.7"
 201     #config.vm.box = "maier/alpine-3.3.1-x86_64"
 202
 203
 204     # ==> Executing Ansible...
 205     config.vm.provision "ansible" do |ansible|
 206         ansible.playbook = "playbook.yml"
 207     end
 208
 209 end
 210 ```
 211
 212 Virtual machines can emulate a variety of Linux distributions with good quality, at the cost of runtime overhead.
 213
 214
 215 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:
 216
 217
 218 ```dockerfile
 219 # Dockerfile
 220
 221 # ==> Choose a base image to emulate Linux distribution...
 222 #FROM williamyeh/ansible:ubuntu16.04
 223 FROM williamyeh/ansible:ubuntu14.04
 224 #FROM williamyeh/ansible:ubuntu12.04
 225 #FROM williamyeh/ansible:debian8
 226 #FROM williamyeh/ansible:debian7
 227 #FROM williamyeh/ansible:centos7
 228 #FROM williamyeh/ansible:centos6
 229 #FROM williamyeh/ansible:alpine3
 230
 231
 232 # ==> Copying Ansible playbook...
 233 WORKDIR /tmp
 234 COPY  .  /tmp
 235
 236 # ==> Creating inventory file...
 237 RUN echo localhost > inventory
 238
 239 # ==> Executing Ansible...
 240 RUN ansible-playbook -i inventory playbook.yml \
 241       --connection=local --sudo
 242 ```
 243
 244 You may also work with `onbuild` variants, which take care of many routine steps for you:
 245
 246 ```dockerfile
 247 # Dockerfile
 248
 249 # ==> Choose a base image to emulate Linux distribution...
 250 #FROM williamyeh/ansible:ubuntu16.04-onbuild
 251 FROM williamyeh/ansible:ubuntu14.04-onbuild
 252 #FROM williamyeh/ansible:ubuntu12.04-onbuild
 253 #FROM williamyeh/ansible:debian8-onbuild
 254 #FROM williamyeh/ansible:debian7-onbuild
 255 #FROM williamyeh/ansible:centos7-onbuild
 256 #FROM williamyeh/ansible:centos6-onbuild
 257 #FROM williamyeh/ansible:alpine3-onbuild
 258
 259
 260 # ==> Specify requirements filename;  default = "requirements.yml"
 261 #ENV REQUIREMENTS  requirements.yml
 262
 263 # ==> Specify playbook filename;      default = "playbook.yml"
 264 #ENV PLAYBOOK      playbook.yml
 265
 266 # ==> Specify inventory filename;     default = "/etc/ansible/hosts"
 267 #ENV INVENTORY     inventory.ini
 268
 269 # ==> Executing Ansible (with a simple wrapper)...
 270 RUN ansible-playbook-wrapper
 271 ```
 272
 273
 274
 275 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!
 276
 277 If better OS emulation (virtualization) isn't required, the Docker approach (containerization) should give you a more efficient Ansible experience.
 278
 279
 280
 281 ## License
 282
 283 Author: William Yeh <william.pjyeh@gmail.com>
 284
 285 Licensed under the Apache License V2.0. See the [LICENSE file](LICENSE) for details.