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