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']['engine']['version_on_centos']`|String|Docker version for CentOS.|`'1.11.2-1'`|
  45 |`['docker-grid']['engine']['version_on_ubuntu']`|String|Docker version for Ubuntu.|`'1.11.2-0'`|
  46 |`['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|
  47 |`['docker-grid']['engine']['storage-driver_on_centos']`|String|Docker storage driver (overlay, devicemapper, ...) for CentOS.|`'overlay'`|
  48 |`['docker-grid']['engine']['storage-driver_on_ubuntu']`|String|Docker storage driver (aufs, overlay, ...) for Ubuntu.|`'aufs'`|
  49 |`['docker-grid']['engine']['storage-driver']`|String||See default.rb|
  50 |`['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)|
  51 |`['docker-grid']['engine']['daemon_extra_options']`|String|ref. `docker daemon --help`.|`'-H fd://'`|
  52 |`['docker-grid']['engine']['users_allow']`|Array|Non-root users allowed to manage Docker daemon.|`[]`|
  53 |`['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`|
  54 |`['docker-grid']['registry']['ssl_cert']['common_name']`|String|Registry server common name for TLS|`node['fqdn']`|
  55 |`['docker-grid']['registry']['docker-compose']['app_dir']`|String||`'/opt/docker-compose/app/registry'`|
  56 |`['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`|
  57 |`['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`|
  58
  59 ## Usage
  60
  61 ### Recipes
  62
  63 #### docker-grid::default
  64
  65 This recipe does nothing.
  66
  67 #### docker-grid::compose
  68
  69 This recipe installs docker-compose.
  70
  71 #### docker-grid::engine
  72
  73 This recipe sets up Docker engine.
  74
  75 #### docker-grid::registry
  76
  77 This recipe sets up Docker Compose configurations for the Docker registry service.
  78
  79 ### Role Examples
  80
  81 - `roles/docker.rb`
  82
  83 ```ruby
  84 name 'docker'
  85 description 'Docker Engine'
  86
  87 run_list(
  88   'recipe[docker-grid::engine]',
  89 )
  90
  91 override_attributes(
  92   'docker-grid' => {
  93     'engine' => {
  94       'version_on_centos' => '1.11.2-1',
  95       'version_on_ubuntu' => '1.11.2-0',
  96       'storage-driver_on_centos' => 'overlay',
  97       'storage-driver_on_ubuntu' => 'overlay',  # default: 'aufs'
  98       'userns-remap' => 'default',  # default: nil (inactive)
  99       'daemon_extra_options' => '-H fd:// --bip=192.168.128.1/24 --fixed-cidr=192.168.128.0/24',
 100     },
 101   },
 102 )
 103 ```
 104
 105 - `roles/docker-registry.rb`
 106
 107 ```ruby
 108 name 'docker-registry'
 109 description 'Docker Registry Server'
 110
 111 run_list(
 112   'recipe[docker-grid::registry]',
 113 )
 114
 115 override_attributes(
 116   'docker-grid' => {
 117     'engine' => {
 118       'version_on_centos' => '1.11.2-1',
 119       'version_on_ubuntu' => '1.11.2-0',
 120       'storage-driver_on_centos' => 'overlay',
 121       'storage-driver_on_ubuntu' => 'overlay',  # default: 'aufs'
 122       'userns-remap' => '',
 123       'daemon_extra_options' => \
 124         '-H fd:// --bip=192.168.128.1/24 --fixed-cidr=192.168.128.0/24' \
 125         + ' --insecure-registry registry.docker.example.com:5000',
 126     },
 127     'registry' => {
 128       'docker-compose' => {
 129         'config' => {
 130           # in docker-compose.yml
 131           # See: https://docs.docker.com/registry/deploying/#/managing-with-compose
 132           'registry' => {
 133             'restart' => 'always',
 134             'image' => 'registry:2',
 135             'ports' => [
 136               '5000:5000',
 137             ],
 138             'environment' => {
 139               'REGISTRY_HTTP_TLS_CERTIFICATE' => '/certs/domain.crt',
 140               'REGISTRY_HTTP_TLS_KEY' =>         '/certs/domain.key',
 141               'REGISTRY_AUTH' =>                'htpasswd',
 142               'REGISTRY_AUTH_HTPASSWD_PATH' =>  '/auth/htpasswd',
 143               'REGISTRY_AUTH_HTPASSWD_REALM' => 'Registry Realm',
 144             },
 145             'volumes' => [
 146               '/path/data:/var/lib/registry',
 147               '/path/certs:/certs',
 148               '/path/auth:/auth',
 149             ],
 150           },
 151         },
 152       },
 153     },
 154   },
 155 )
 156 ```
 157
 158 - `roles/docker-registry-with-ssl-cert.rb`
 159
 160 ```ruby
 161 name 'docker-registry-with-ssl-cert'
 162 description 'Docker Registry Server'
 163
 164 run_list(
 165   'recipe[docker-grid::registry]',
 166 )
 167
 168 registry_fqdn = 'registry.docker.example.com'
 169
 170 override_attributes(
 171   'docker-grid' => {
 172     'engine' => {
 173       'version_on_centos' => '1.11.2-1',
 174       'version_on_ubuntu' => '1.11.2-0',
 175       'storage-driver_on_centos' => 'overlay',
 176       'storage-driver_on_ubuntu' => 'overlay',  # default: 'aufs'
 177       'userns-remap' => '',
 178       'daemon_extra_options' => \
 179         '-H fd:// --bip=192.168.128.1/24 --fixed-cidr=192.168.128.0/24' \
 180         + " --insecure-registry #{registry_fqdn}:5000",
 181     },
 182     'registry' => {
 183       'with_ssl_cert_cookbook' => true,
 184       'ssl_cert' => {
 185         'common_name' => registry_fqdn,
 186       },
 187       'docker-compose' => {
 188         'config' => {
 189           # in docker-compose.yml
 190           # See: https://docs.docker.com/registry/deploying/#/managing-with-compose
 191           'registry' => {
 192             'restart' => 'always',
 193             'image' => 'registry:2',
 194             'ports' => [
 195               '5000:5000',
 196             ],
 197             'environment' => {
 198               # REGISTRY_HTTP_TLS_{CERTIFICATE,KEY} will be set automatically.
 199               'REGISTRY_AUTH' =>                'htpasswd',
 200               'REGISTRY_AUTH_HTPASSWD_PATH' =>  '/auth/htpasswd',
 201               'REGISTRY_AUTH_HTPASSWD_REALM' => 'Registry Realm',
 202             },
 203             'volumes' => [
 204               # Volumes for the server certificate and key files will be set automatically.
 205               '/path/data:/var/lib/registry',
 206               '/path/auth:/auth',
 207             ],
 208           },
 209         },
 210       },
 211     },
 212   },
 213 )
 214 ```
 215
 216 - `roles/docker-registry-by-entire-config.rb`
 217
 218 ```ruby
 219 name 'docker-registry-by-entire-config'
 220 description 'Docker Registry Server'
 221
 222 run_list(
 223   'recipe[docker-grid::registry]',
 224 )
 225
 226 override_attributes(
 227   'docker-grid' => {
 228     'engine' => {
 229       'version_on_centos' => '1.11.2-1',
 230       'version_on_ubuntu' => '1.11.2-0',
 231       'storage-driver_on_centos' => 'overlay',
 232       'storage-driver_on_ubuntu' => 'overlay',  # default: 'aufs'
 233       'userns-remap' => '',
 234       'daemon_extra_options' => \
 235         '-H fd:// --bip=192.168.128.1/24 --fixed-cidr=192.168.128.0/24' \
 236         + ' --insecure-registry registry.docker.example.com:5000',
 237     },
 238     'registry' => {
 239       'docker-compose' => {
 240         'registry-config' => {
 241           # NOT nil
 242           # in ./etc/config.yml
 243           # See: https://docs.docker.com/registry/configuration/#/overriding-the-entire-configuration-file
 244           'version' => '0.1',
 245           # ...
 246         },
 247         'config' => {
 248           # in ./docker-compose.yml
 249           # See: https://docs.docker.com/registry/deploying/#/managing-with-compose
 250           'registry' => {
 251             'restart' => 'always',
 252             'image' => 'registry:2',
 253             'ports' => [
 254               '5000:5000',
 255             ],
 256             'environment' => {
 257               # -> ./etc/config.yml
 258             },
 259             'volumes' => [
 260               # Volumes for the ./etc/config.yml will be set automatically.
 261               #'./etc/config.yml:/etc/docker/registry/config.yml:ro',
 262               '/path/data:/var/lib/registry',
 263               '/path/auth:/auth',
 264             ],
 265           },
 266         },
 267       },
 268     },
 269   },
 270 )
 271 ```
 272
 273 ## License and Authors
 274
 275 - Author:: whitestar at osdn.jp
 276
 277 ```text
 278 Copyright 2016, whitestar
 279
 280 Licensed under the Apache License, Version 2.0 (the "License");
 281 you may not use this file except in compliance with the License.
 282 You may obtain a copy of the License at
 283
 284     http://www.apache.org/licenses/LICENSE-2.0
 285
 286 Unless required by applicable law or agreed to in writing, software
 287 distributed under the License is distributed on an "AS IS" BASIS,
 288 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 289 See the License for the specific language governing permissions and
 290 limitations under the License.
 291 ```