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