]> git.immae.eu Git - github/fretlink/docker-ansible.git/blob - README.md
c02360d229afa23f8e82af16b57b7ab34b49e888
[github/fretlink/docker-ansible.git] / 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.