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