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 (stretch, 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:debian9`
  47   - `williamyeh/ansible:debian8`
  48   - `williamyeh/ansible:ubuntu16.04`
  49   - `williamyeh/ansible:ubuntu14.04`
  50   - `williamyeh/ansible:centos7`
  51   - `williamyeh/ansible:alpine3`
  52
  53 - Onbuild variants (*recommended for common cases*):
  54
  55   - `williamyeh/ansible:debian9-onbuild`
  56   - `williamyeh/ansible:debian8-onbuild`
  57   - `williamyeh/ansible:ubuntu16.04-onbuild`
  58   - `williamyeh/ansible:ubuntu14.04-onbuild`
  59   - `williamyeh/ansible:centos7-onbuild`
  60   - `williamyeh/ansible:alpine3-onbuild`
  61
  62
  63 ### Minimal configuration (the Ansible body will be removed when mission completed):
  64
  65 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.
  66
  67 - Onbuild variants:
  68
  69   - `williamyeh/ansible:mini-alpine3`
  70   - `williamyeh/ansible:mini-debian9`
  71   - `williamyeh/ansible:mini-debian8`
  72
  73
  74 ### Old 1.9 version (will be retired someday):
  75
  76 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).
  77
  78 - Normal variants:
  79
  80   - `williamyeh/ansible:1.9-debian8`
  81   - `williamyeh/ansible:1.9-ubuntu14.04`
  82   - `williamyeh/ansible:1.9-alpine3`
  83
  84 - Onbuild variants (*recommended for common cases*):
  85
  86   - `williamyeh/ansible:1.9-debian8-onbuild`
  87   - `williamyeh/ansible:1.9-ubuntu14.04-onbuild`
  88   - `williamyeh/ansible:1.9-alpine3-onbuild`
  89
  90
  91 ### Experimental version (building directly from the git `master` source tree; use at your own risk!):
  92
  93 - Normal variants:
  94
  95   - `williamyeh/ansible:master-debian9`
  96   - `williamyeh/ansible:master-debian8`
  97   - `williamyeh/ansible:master-ubuntu16.04`
  98   - `williamyeh/ansible:master-ubuntu14.04`
  99   - `williamyeh/ansible:master-centos7`
 100
 101 - Onbuild variants (*recommended for common cases*):
 102
 103   - `williamyeh/ansible:master-debian9-onbuild`
 104   - `williamyeh/ansible:master-debian8-onbuild`
 105   - `williamyeh/ansible:master-ubuntu16.04-onbuild`
 106   - `williamyeh/ansible:master-ubuntu14.04-onbuild`
 107   - `williamyeh/ansible:master-centos7-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://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?
 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 = "debian/stretch64"
 191     #config.vm.box = "debian/jessie64"
 192     #config.vm.box = "bento/centos-7.2"
 193     #config.vm.box = "maier/alpine-3.3.1-x86_64"
 194
 195
 196     # ==> Executing Ansible...
 197     config.vm.provision "ansible" do |ansible|
 198         ansible.playbook = "playbook.yml"
 199     end
 200
 201 end
 202 ```
 203
 204 Virtual machines can emulate a variety of Linux distributions with good quality, at the cost of runtime overhead.
 205
 206
 207 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:
 208
 209
 210 ```dockerfile
 211 # Dockerfile
 212
 213 # ==> Choose a base image to emulate Linux distribution...
 214 FROM williamyeh/ansible:ubuntu16.04
 215 #FROM williamyeh/ansible:ubuntu14.04
 216 #FROM williamyeh/ansible:debian9
 217 #FROM williamyeh/ansible:debian8
 218 #FROM williamyeh/ansible:centos7
 219 #FROM williamyeh/ansible:alpine3
 220
 221
 222 # ==> Copying Ansible playbook...
 223 WORKDIR /tmp
 224 COPY  .  /tmp
 225
 226 # ==> Creating inventory file...
 227 RUN echo localhost > inventory
 228
 229 # ==> Executing Ansible...
 230 RUN ansible-playbook -i inventory playbook.yml \
 231       --connection=local --sudo
 232 ```
 233
 234 You may also work with `onbuild` variants, which take care of many routine steps for you:
 235
 236 ```dockerfile
 237 # Dockerfile
 238
 239 # ==> Choose a base image to emulate Linux distribution...
 240 FROM williamyeh/ansible:ubuntu16.04-onbuild
 241 #FROM williamyeh/ansible:ubuntu14.04-onbuild
 242 #FROM williamyeh/ansible:debian9-onbuild
 243 #FROM williamyeh/ansible:debian8-onbuild
 244 #FROM williamyeh/ansible:centos7-onbuild
 245 #FROM williamyeh/ansible:alpine3-onbuild
 246
 247
 248 # ==> Specify requirements filename;  default = "requirements.yml"
 249 #ENV REQUIREMENTS  requirements.yml
 250
 251 # ==> Specify playbook filename;      default = "playbook.yml"
 252 #ENV PLAYBOOK      playbook.yml
 253
 254 # ==> Specify inventory filename;     default = "/etc/ansible/hosts"
 255 #ENV INVENTORY     inventory.ini
 256
 257 # ==> Executing Ansible (with a simple wrapper)...
 258 RUN ansible-playbook-wrapper
 259 ```
 260
 261
 262
 263 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!
 264
 265 If better OS emulation (virtualization) isn't required, the Docker approach (containerization) should give you a more efficient Ansible experience.
 266
 267
 268
 269 ## License
 270
 271 Author: William Yeh <william.pjyeh@gmail.com>
 272
 273 Licensed under the Apache License V2.0. See the [LICENSE file](LICENSE) for details.