cookbooks/docker-grid/README.md

   1 docker-grid Cookbook
   2 ====================
   3
   4 This cookbook sets up Docker engine.
   5
   6 ## Contents
   7
   8 - [Requirements](#requirements)
   9   - [platforms](#platforms)
  10   - [packages](#packages)
  11 - [Attributes](#attributes)
  12 - [Usage](#usage)
  13   - [Recipes](#recipes)
  14     - [docker-grid::default](#docker-griddefault)
  15     - [docker-grid::compose](#docker-gridcompose)
  16     - [docker-grid::engine](#docker-gridengine)
  17     - [docker-grid::registry](#docker-gridregistry)
  18   - [Role Examples](#role-examples)
  19 - [License and Authors](#license-and-authors)
  20
  21 ## Requirements
  22
  23 ### platforms
  24 - CentOS, Red Hat Enterprise Linux >= 7.2
  25 - Ubuntu >= 14.04
  26
  27 ### packages
  28 - none.
  29
  30 ## Attributes
  31
  32 |Key|Type|Description, example|Default|
  33 |:--|:--|:--|:--|
  34 |`['docker-grid']['apt_repo']['url']`|String||`'https://apt.dockerproject.org/repo'`|
  35 |`['docker-grid']['apt_repo']['keyserver']`|String||`'hkp://p80.pool.sks-keyservers.net:80'`|
  36 |`['docker-grid']['apt_repo']['recv-keys']`|String||`'58118E89F3A912897C070ADBF76221572C52609D'`|
  37 |`['docker-grid']['apt_repo']['override_apt_line']`|String|If you set this attribute, apt-line settings with the `['docker-grid']['apt_repo']['url']` attribute is overrridden. e.g. `'deb https://apt.dockerproject.org/repo ubuntu-xenial main'`|`''`|
  38 |`['docker-grid']['yum_repo']['baseurl']`|String||`'https://yum.dockerproject.org/repo/main/centos/$releasever/'`|
  39 |`['docker-grid']['yum_repo']['gpgcheck']`|String|`'0'`: disabled, `'1'`: enabled.|`'1'`|
  40 |`['docker-grid']['yum_repo']['gpgkey']`|String||`'https://yum.dockerproject.org/gpg'`|
  41 |`['docker-grid']['compose']['auto_upgrade']`|String|upgrade/reinstall the docker-compose automatically.|`false`|
  42 |`['docker-grid']['compose']['release_base_url']`|String||`'https://github.com/docker/compose/releases/download/1.9.0'`|
  43 |`['docker-grid']['compose']['release_url']`|String||`"#{node['docker-grid']['compose']['release_base_url']}/docker-compose-#{node['kernel']['name']}-#{node['kernel']['machine']}"`|
  44 |`['docker-grid']['compose']['home_dir']`|String||`'/opt/docker-compose'`|
  45 |`['docker-grid']['compose']['app_dir']`|String||`"#{node['docker-grid']['compose']['home_dir']}/app`|
  46 |`['docker-grid']['engine']['version_on_centos']`|String|Docker version for CentOS.|`'1.11.2-1'`|
  47 |`['docker-grid']['engine']['version_on_ubuntu']`|String|Docker version for Ubuntu.|`'1.11.2-0'`|
  48 |`['docker-grid']['engine']['version']`|String|Docker 1.9.x - 1.11.x is recommended for stability reasons. Note: this **default** value is overwritten by the `version_on_{centos or ubuntu}`.|See default.rb|
  49 |`['docker-grid']['engine']['storage-driver_on_centos']`|String|Docker storage driver (overlay, devicemapper, ...) for CentOS.|`'overlay'`|
  50 |`['docker-grid']['engine']['storage-driver_on_ubuntu']`|String|Docker storage driver (aufs, overlay, ...) for Ubuntu.|`'aufs'`|
  51 |`['docker-grid']['engine']['storage-driver']`|String||See default.rb|
  52 |`['docker-grid']['engine']['userns-remap']`|String|e.g. `'default'` (`dockremap` user/group) or your specified user/group name. Note: it is available in Docker 1.10/later and (Ubuntu or RHEL family 7.2/later).|`nil` (inactive)|
  53 |`['docker-grid']['engine']['daemon_extra_options']`|String|ref. `docker daemon --help`.|`'-H fd://'`|
  54 |`['docker-grid']['engine']['users_allow']`|Array|Non-root users allowed to manage Docker daemon.|`[]`|
  55 |`['docker-grid']['registry']['with_ssl_cert_cookbook']`|Boolean|If this attribute is true, `node['docker-grid']['registry']['docker-compose']['config']` are are overridden by the following `common_name` attributes.|`false`|
  56 |`['docker-grid']['registry']['ssl_cert']['common_name']`|String|Registry server common name for TLS|`node['fqdn']`|
  57 |`['docker-grid']['registry']['docker-compose']['app_dir']`|String||`"#{node['docker-grid']['compose']['app_dir']}/registry"`|
  58 |`['docker-grid']['registry']['docker-compose']['host_data_volume']`|String|Data directory path on the host filesystem or `nil` (unset).|`'/var/lib/docker-registry'`|
  59 |`['docker-grid']['registry']['docker-compose']['config_format_version']`|String|`docker-compose.yml` format version. `'1'` or `'2'`|`'1'`|
  60 |`['docker-grid']['registry']['docker-compose']['service_name']`|String|Docker registry service name in the `docker-compose.yml`|`'registry'`|
  61 |`['docker-grid']['registry']['docker-compose']['config']`|Hash|`docker-compose.yml` configurations. See attributes/default.rb and [_Deploying a registry server_](https://docs.docker.com/registry/deploying/#/managing-with-compose) |See `attributes/default.rb`|
  62 |`['docker-grid']['registry']['docker-compose']['registry-config']`|Hash|See [_Overriding the entire configuration file_](https://docs.docker.com/registry/configuration/#/overriding-the-entire-configuration-file)|`nil`|
  63
  64 ## Usage
  65
  66 ### Recipes
  67
  68 #### docker-grid::default
  69
  70 This recipe does nothing.
  71
  72 #### docker-grid::compose
  73
  74 This recipe installs docker-compose.
  75
  76 #### docker-grid::engine
  77
  78 This recipe sets up Docker engine.
  79
  80 #### docker-grid::registry
  81
  82 This recipe sets up Docker Compose configurations for the Docker registry service.
  83
  84 ### Role Examples
  85
  86 - `roles/docker.rb`
  87
  88 ```ruby
  89 name 'docker'
  90 description 'Docker Engine'
  91
  92 run_list(
  93   'recipe[docker-grid::engine]',
  94 )
  95
  96 override_attributes(
  97   'docker-grid' => {
  98     'engine' => {
  99       'version_on_centos' => '1.11.2-1',
 100       'version_on_ubuntu' => '1.11.2-0',
 101       'storage-driver_on_centos' => 'overlay',
 102       'storage-driver_on_ubuntu' => 'overlay',  # default: 'aufs'
 103       'userns-remap' => 'default',  # default: nil (inactive)
 104       'daemon_extra_options' => '-H fd:// --bip=192.168.128.1/24 --fixed-cidr=192.168.128.0/24',
 105     },
 106   },
 107 )
 108 ```
 109
 110 - `roles/docker-registry.rb`
 111
 112 ```ruby
 113 name 'docker-registry'
 114 description 'Docker Registry Server'
 115
 116 run_list(
 117   'recipe[docker-grid::registry]',
 118 )
 119
 120 override_attributes(
 121   'docker-grid' => {
 122     'engine' => {
 123       'version_on_centos' => '1.11.2-1',
 124       'version_on_ubuntu' => '1.11.2-0',
 125       'storage-driver_on_centos' => 'overlay',
 126       'storage-driver_on_ubuntu' => 'overlay',  # default: 'aufs'
 127       'userns-remap' => '',
 128       'daemon_extra_options' => \
 129         '-H fd:// --bip=192.168.128.1/24 --fixed-cidr=192.168.128.0/24', \
 130         # for development environment only.
 131         #+ ' --insecure-registry registry.docker.example.com:5000',
 132     },
 133     'registry' => {
 134       'docker-compose' => {
 135         'config_format_version' => '1',
 136         'host_data_volume' => nil,
 137         'config' => {
 138           # in docker-compose.yml
 139           # See: https://docs.docker.com/registry/deploying/#/managing-with-compose
 140           'registry' => {
 141             'restart' => 'always',
 142             'image' => 'registry:2',
 143             'ports' => [
 144               '5000:5000',
 145             ],
 146             'environment' => {
 147               'REGISTRY_HTTP_TLS_CERTIFICATE' => '/certs/domain.crt',
 148               'REGISTRY_HTTP_TLS_KEY' =>         '/certs/domain.key',
 149               'REGISTRY_AUTH' =>                'htpasswd',
 150               'REGISTRY_AUTH_HTPASSWD_PATH' =>  '/auth/htpasswd',
 151               'REGISTRY_AUTH_HTPASSWD_REALM' => 'Registry Realm',
 152             },
 153             'volumes' => [
 154               '/path/data:/var/lib/registry',
 155               '/path/certs:/certs',
 156               '/path/auth:/auth',
 157             ],
 158           },
 159         },
 160       },
 161     },
 162   },
 163 )
 164 ```
 165
 166 - `roles/docker-registry-with-ssl-cert.rb`
 167
 168 ```ruby
 169 name 'docker-registry-with-ssl-cert'
 170 description 'Docker Registry Server'
 171
 172 run_list(
 173   'recipe[docker-grid::registry]',
 174 )
 175
 176 registry_fqdn = 'registry.docker.example.com'
 177
 178 override_attributes(
 179   'docker-grid' => {
 180     'engine' => {
 181       'version_on_centos' => '1.11.2-1',
 182       'version_on_ubuntu' => '1.11.2-0',
 183       'storage-driver_on_centos' => 'overlay',
 184       'storage-driver_on_ubuntu' => 'overlay',  # default: 'aufs'
 185       'userns-remap' => '',
 186       'daemon_extra_options' => \
 187         '-H fd:// --bip=192.168.128.1/24 --fixed-cidr=192.168.128.0/24',
 188     },
 189     'registry' => {
 190       'with_ssl_cert_cookbook' => true,
 191       'ssl_cert' => {
 192         'common_name' => registry_fqdn,
 193       },
 194       'docker-compose' => {
 195         'config_format_version' => '1',
 196         'host_data_volume' => nil,
 197         'config' => {
 198           # in docker-compose.yml
 199           # See: https://docs.docker.com/registry/deploying/#/managing-with-compose
 200           'registry' => {
 201             'restart' => 'always',
 202             'image' => 'registry:2',
 203             'ports' => [
 204               '5000:5000',
 205             ],
 206             'environment' => {
 207               # REGISTRY_HTTP_TLS_{CERTIFICATE,KEY} will be set automatically.
 208               'REGISTRY_AUTH' =>                'htpasswd',
 209               'REGISTRY_AUTH_HTPASSWD_PATH' =>  '/auth/htpasswd',
 210               'REGISTRY_AUTH_HTPASSWD_REALM' => 'Registry Realm',
 211             },
 212             'volumes' => [
 213               # Volumes for the server certificate and key files will be set automatically.
 214               '/path/data:/var/lib/registry',
 215               '/path/auth:/auth',
 216             ],
 217           },
 218         },
 219       },
 220     },
 221   },
 222 )
 223 ```
 224
 225 - `roles/docker-registry-by-entire-config.rb`
 226
 227 ```ruby
 228 name 'docker-registry-by-entire-config'
 229 description 'Docker Registry Server'
 230
 231 run_list(
 232   'recipe[docker-grid::registry]',
 233 )
 234
 235 override_attributes(
 236   'docker-grid' => {
 237     'engine' => {
 238       'version_on_centos' => '1.11.2-1',
 239       'version_on_ubuntu' => '1.11.2-0',
 240       'storage-driver_on_centos' => 'overlay',
 241       'storage-driver_on_ubuntu' => 'overlay',  # default: 'aufs'
 242       'userns-remap' => '',
 243       'daemon_extra_options' => \
 244         '-H fd:// --bip=192.168.128.1/24 --fixed-cidr=192.168.128.0/24', \
 245         # for development environment only.
 246         #+ ' --insecure-registry registry.docker.example.com:5000',
 247     },
 248     'registry' => {
 249       'docker-compose' => {
 250         'registry-config' => {
 251           # NOT nil
 252           # in ./etc/config.yml
 253           # See: https://docs.docker.com/registry/configuration/#/overriding-the-entire-configuration-file
 254           'version' => '0.1',
 255           # ...
 256         },
 257         'config_format_version' => '1',
 258         'config' => {
 259           # in ./docker-compose.yml
 260           # See: https://docs.docker.com/registry/deploying/#/managing-with-compose
 261           'registry' => {
 262             'restart' => 'always',
 263             'image' => 'registry:2',
 264             'ports' => [
 265               '5000:5000',
 266             ],
 267             'environment' => {
 268               # -> ./etc/config.yml
 269             },
 270             'volumes' => [
 271               # Volumes for the ./etc/config.yml will be set automatically.
 272               #'./etc/config.yml:/etc/docker/registry/config.yml:ro',
 273               '/path/data:/var/lib/registry',
 274               '/path/auth:/auth',
 275             ],
 276           },
 277         },
 278       },
 279     },
 280   },
 281 )
 282 ```
 283
 284 ## License and Authors
 285
 286 - Author:: whitestar at osdn.jp
 287
 288 ```text
 289 Copyright 2016, whitestar
 290
 291 Licensed under the Apache License, Version 2.0 (the "License");
 292 you may not use this file except in compliance with the License.
 293 You may obtain a copy of the License at
 294
 295     http://www.apache.org/licenses/LICENSE-2.0
 296
 297 Unless required by applicable law or agreed to in writing, software
 298 distributed under the License is distributed on an "AS IS" BASIS,
 299 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 300 See the License for the specific language governing permissions and
 301 limitations under the License.
 302 ```