cookbooks/dcos-grid/README.md

   1 dcos-grid Cookbook
   2 ==================
   3
   4 This cookbook sets up your customized DC/OS cluster on bare metal, virtual machines and every cloud. This install method is based on [_Advanced DC/OS Installation Guide_](https://dcos.io/docs/1.8/administration/installing/custom/advanced/).
   5
   6 ## Contents
   7
   8 - [Requirements](#requirements)
   9   - [platforms](#platforms)
  10   - [packages](#packages)
  11   - [cookbooks](#cookbooks)
  12 - [Attributes](#attributes)
  13 - [Usage](#usage)
  14   - [Recipes](#recipes)
  15     - [dcos-grid::default](#dcos-griddefault)
  16     - [dcos-grid::agent](#dcos-gridagent)
  17     - [dcos-grid::bootstrap](#dcos-gridbootstrap)
  18     - [dcos-grid::cli (ver. 0.3.0 or later)](#dcos-gridcli-ver-030-or-later)
  19     - [dcos-grid::cloud-config (for CoreOS only)](#dcos-gridcloud-config-for-coreos-only)
  20     - [dcos-grid::master](#dcos-gridmaster)
  21     - [dcos-grid::node](#dcos-gridnode)
  22     - [dcos-grid::node-commons](#dcos-gridnode-commons)
  23     - [dcos-grid::public-agent](#dcos-gridpublic-agent)
  24     - [dcos-grid::universe-build-env (ver. 0.4.8 or later)](#dcos-griduniverse-build-env-ver-048-or-later)
  25     - [dcos-grid::universe-server (ver. 0.4.9 or later)](#dcos-griduniverse-server-ver-049-or-later)
  26   - [Role Examples](#role-examples)
  27   - [Upgrade DC/OS (ver. 0.4.3 or later)](#upgrade-dcos-ver-043-or-later)
  28   - [Uninstall DC/OS](#uninstall-dcos)
  29 - [License and Authors](#license-and-authors)
  30
  31 ## Requirements
  32
  33 ### platforms
  34 - CentOS, Red Hat Enterprise Linux >= 7.2
  35 - CoreOS Latest version.
  36 - Ubuntu 16.04 (Experimental). DC/OS does not officially support Ubuntu yet. See [_Ubuntu 16.04 Enablement_](https://dcosjira.atlassian.net/browse/DCOS-25).
  37   - DC/OS requires systemd, which is only fully supported in Ubuntu 15.04 and later releases. See [_SystemdForUpstartUsers_](https://wiki.ubuntu.com/SystemdForUpstartUsers)
  38
  39 ### packages
  40 - none.
  41
  42 ### cookbooks
  43 - `docker-grid` (for `dcos-grid` ver. 0.4.0 or later).
  44
  45 ## Attributes
  46
  47 |Key|Type|Description, example|Default|
  48 |:--|:--|:--|:--|
  49 |`['dcos-grid']['dcos_release_url']`|String|DC/OS download URL.|`'https://downloads.dcos.io/dcos/stable/dcos_generate_config.sh'`|
  50 |`['dcos-grid']['dcos_release_checksum']`|String|sha256 checksum of the DC/OS release. (ver. 0.5.0 or later)|`nil` (no check)|
  51 |`['dcos-grid']['dcos_release_script_name']`|String|OSS edition: `'dcos_generate_config.sh'`, Enterprise edition: `'dcos_generate_config.ee.sh'`  (ver. 0.4.8 or later).|`Pathname(URI(node['dcos-grid']['dcos_release_url']).path).basename`|
  52 |`['dcos-grid']['dcos_cli_release_url']`|String|DEPRECATED: DC/OS CLI download URL (ver. 0.3.0 or later).|`"https://downloads.dcos.io/binaries/cli/linux/x86-64/#{node['dcos-grid']['cli']['version']}/dcos"`|
  53 |`['dcos-grid']['dcos_cli_upgrade']`|Boolean|DEPRECATED: Whether upgrade DC/OS CLI or not (ver. 0.4.3 or later).|`false`|
  54 |`['dcos-grid']['cli']['version']`|String|DC/OS CLI version (ver. 0.5.0 or later)|`'0.4.14'`|
  55 |`['dcos-grid']['cli']['release_url']`|String| (ver. 0.5.0 or later)|`node['dcos-grid']['dcos_cli_release_url']`|
  56 |`['dcos-grid']['cli']['release_checksum']`|String|sha256 checksum of the DC/OS CLI release. (ver. 0.5.0 or later)|`nil` (no check)|
  57 |`['dcos-grid']['cli']['auto_upgrade']`|Boolean| (ver. 0.5.0 or later)|`node['dcos-grid']['dcos_cli_upgrade']`|
  58 |`['dcos-grid']['cli']['install_path']`|String| (ver. 0.5.0 or later)|`'/usr/local/bin/dcos'`|
  59 |`['dcos-grid']['docker']['apt_repo']['url']`|String|DEPRECATED: use `['docker-grid']['apt_repo']['url']` (ver. 0.4.0 or later)|`nil`|
  60 |`['dcos-grid']['docker']['apt_repo']['keyserver']`|String|DEPRECATED: use `['docker-grid']['apt_repo']['keyserver']` (ver. 0.4.0 or later)|`nil`|
  61 |`['dcos-grid']['docker']['apt_repo']['recv-keys']`|String|DEPRECATED: use `['docker-grid']['apt_repo']['recv-keys']` (ver. 0.4.0 or later)|`nil`|
  62 |`['dcos-grid']['docker']['yum_repo']['baseurl']`|String|DEPRECATED: use `['docker-grid']['yum_repo']['baseurl']` (ver. 0.4.0 or later)|`nil`|
  63 |`['dcos-grid']['docker']['yum_repo']['gpgcheck']`|String|DEPRECATED: use `['docker-grid']['yum_repo']['gpgcheck']` (ver. 0.4.0 or later). `'0'`: disabled, `'1'`: enabled.|`nil`|
  64 |`['dcos-grid']['docker']['yum_repo']['gpgkey']`|String|DEPRECATED: use `['docker-grid']['yum_repo']['gpgkey']` (ver. 0.4.0 or later)|`nil`|
  65 |`['dcos-grid']['docker-engine']['setup']`|Boolean|Docker setup by this cookbook. If you will set up Docker by another cookbook, verify that this attribute is false. (ver. 0.3.0 or later)|`true`|
  66 |`['dcos-grid']['docker-engine']['version_on_centos']`|String|DEPRECATED: use `['docker-grid']['engine']['version_on_centos']` (ver. 0.4.0 or later). Docker version for CentOS.|`nil`|
  67 |`['dcos-grid']['docker-engine']['version_on_ubuntu']`|String|DEPRECATED: use `['docker-grid']['engine']['version_on_ubuntu']` (ver. 0.4.0 or later). Docker version for Ubuntu.|`nil`|
  68 |`['dcos-grid']['docker-engine']['version']`|String|DEPRECATED: use `['docker-grid']['engine']['version']` (ver. 0.4.0 or later). 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|
  69 |`['dcos-grid']['docker-engine']['storage-driver_on_centos']`|String|DEPRECATED: use `['docker-grid']['engine']['storage-driver_on_centos']` (ver. 0.4.0 or later). Docker storage driver (overlay, devicemapper, ...) for CentOS.|`nil`|
  70 |`['dcos-grid']['docker-engine']['storage-driver_on_ubuntu']`|String|DEPRECATED: use `['docker-grid']['engine']['storage-driver_on_ubuntu']` (ver. 0.4.0 or later). Docker storage driver (aufs, overlay, ...) for Ubuntu.|`nil`|
  71 |`['dcos-grid']['docker-engine']['storage-driver']`|String|DEPRECATED: use `['docker-grid']['engine']['storage-driver']` (ver. 0.4.0 or later).|See default.rb|
  72 |`['dcos-grid']['docker-engine']['daemon_extra_options']`|String|DEPRECATED: use `['docker-grid']['engine']['daemon_extra_options']` (ver. 0.4.0 or later). ref. `docker daemon --help`.|`nil`|
  73 |`['dcos-grid']['bootstrap']['ip']`|String|Bootstrap node IP address.|`'127.0.0.1'`|
  74 |`['dcos-grid']['bootstrap']['port']`|String|Bootstrap node port number.|`'8080'`|
  75 |`['dcos-grid']['bootstrap']['genconf_dir']`|String|genconf directory path. Note: This is overridden by the value `"#{node['dcos-grid']['cloud-config']['target_dir']}/genconf"` in the `cloud-config` recipe (ver. 0.3.5 or later).|`'/opt/dcos-grid/genconf'`|
  76 |`['dcos-grid']['bootstrap']['config']`|Hash|Install configurations.|see [_Install Configuration Parameters_](https://dcos.io/docs/1.8/administration/installing/custom/configuration-parameters/)|
  77 |`['dcos-grid']['bootstrap']['config']['bootstrap_url']`|String||`"http://#{node['dcos-grid']['bootstrap']['ip']}:#{node['dcos-grid']['bootstrap']['port']}"`|
  78 |`['dcos-grid']['bootstrap']['config']['cluster_name']`|String||`'dcos0'`|
  79 |`['dcos-grid']['bootstrap']['config']['exhibitor_storage_backend']`|String||`'static'`|
  80 |`['dcos-grid']['bootstrap']['config']['ip_detect_filename']`|String||`'/genconf/ip-detect'`|
  81 |`['dcos-grid']['bootstrap']['config']['master_discovery']`|String|(ver. 0.3.2 or later)|`'static'`|
  82 |`['dcos-grid']['bootstrap']['config']['master_list']`|Array|e.g. `['192.168.1.101','192.168.1.102','192.168.1.103']`|`nil`|
  83 |`['dcos-grid']['bootstrap']['config']['oauth_auth_host']`|String|(ver. 0.3.2 or later)|`'https://dcos.auth0.com'`|
  84 |`['dcos-grid']['bootstrap']['config']['oauth_auth_redirector']`|String|(ver. 0.3.2 or later)|`'https://auth.dcos.io'`|
  85 |`['dcos-grid']['bootstrap']['config']['oauth_available']`|String|(ver. 0.3.2 or later)|`'true'`|
  86 |`['dcos-grid']['bootstrap']['config']['oauth_enabled']`|String|(ver. 0.3.2 or later)|`'true'`|
  87 |`['dcos-grid']['bootstrap']['config']['oauth_issuer_url']`|String|(ver. 0.3.2 or later)|`'https://dcos.auth0.com/'`|
  88 |`['dcos-grid']['bootstrap']['config']['resolvers']`|Array|e.g. `['8.8.8.8','8.8.4.4']` (Google DNS)|`nil`|
  89 |`['dcos-grid']['bootstrap']['config']['telemetry_enabled']`|String||`'false'` (ver. 0.4.1 or later)|
  90 |`['dcos-grid']['bootstrap']['bootstrap']['ip-detect']['interface']`|String|Network interface on each node for the `ip-detect` script. Note: If you set comma-delimited interface list (e.g. `'eth0,enp0s3'`), the first detected interface's ip is adopted (ver. 0.3.0 or later). |`'eth0'`|
  91 |`['dcos-grid']['node']['auto_setup']`|Boolean|execute the node setup script automatically or not.|`false`|
  92 |`['dcos-grid']['cloud-config']['target_platform']`|String|CoreOS only now.|`'coreos'`|
  93 |`['dcos-grid']['cloud-config']['target_dir']`|String||`'/home/core'`|
  94 |`['dcos-grid']['cloud-config']['target_owner']`|String||`'core:core'`|
  95 |`['dcos-grid']['cloud-config']['hostname']`|String||`'<fqdn>'`|
  96 |`['dcos-grid']['cloud-config']['timezone']`|String||`'Etc/GMT'`|
  97 |`['dcos-grid']['cloud-config']['ssh_authorized_keys']`|Array||`['<your_ssh_pub_key>',]`|
  98 |`['dcos-grid']['universe-server']['docker-compose']['app_dir']`|String||`'/opt/docker-compose/app/dcos-universe'`|
  99 |`['dcos-grid']['universe-server']['docker-compose']['config']`|Hash|`docker-compose.yml` configurations.|See `attributes/default.rb`|
 100
 101 ## Usage
 102
 103 ### Recipes
 104
 105 #### dcos-grid::default
 106
 107 This recipe does nothing.
 108
 109 #### dcos-grid::agent
 110
 111 This recipe sets up a private agent node. Note: If `node['dcos-grid']['node']['auto_setup']` is `false`, you must execute the following manually.
 112
 113 ```
 114 $ /opt/dcos-grid/node_setup.sh slave
 115 ```
 116
 117 #### dcos-grid::bootstrap
 118
 119 This recipe sets up a bootstrap node. Note: Please execute the following manually.
 120
 121 ```
 122 $ /opt/dcos-grid/bootstrap_setup.sh
 123 ```
 124
 125 #### dcos-grid::cli (ver. 0.3.0 or later)
 126
 127 This recipe installs DC/OS CLI.
 128
 129 #### dcos-grid::cloud-config (for CoreOS only)
 130
 131 This recipe generates a `/home/core/cloud-config.yaml` template file on local machine by the following `chef-solo` command.
 132
 133 ```
 134 $ sudo chef-solo -c solo.rb -j nodes/local-dcos0-cloud-config.json
 135 ```
 136
 137 - `nodes/local-dcos0-cloud-config.json`
 138
 139 ```json
 140 {
 141   "run_list": [
 142     "role[dcos0-cloud-config]"
 143   ]
 144 }
 145 ```
 146
 147 - `roles/dcos0-cloud-config.rb`
 148
 149 ```ruby
 150 cluster_name = 'dcos0'
 151
 152 name "#{cluster_name}-cloud-config"
 153 description "#{cluster_name} cloud-config.yaml file."
 154
 155 run_list(
 156   "role[#{cluster_name}]",  # includes common attributes.
 157   'recipe[dcos-grid::cloud-config]',
 158 )
 159 ```
 160
 161 Then edit this yaml template (hostname, ssh_authorized_keys, IP address and so on) and install CoreOS by the `cloud-config.yaml`.
 162
 163 ```
 164 $ coreos-cloudinit -from-file ~/cloud-config.yaml -validate
 165 ...
 166 $ sudo coreos-install -d /dev/sda -C stable -c ~/cloud-config.yaml
 167 ```
 168
 169 #### dcos-grid::master
 170
 171 This recipe sets up a master node. Note: If `node['dcos-grid']['node']['auto_setup']` is `false`, you must execute the following manually.
 172
 173 ```
 174 $ /opt/dcos-grid/node_setup.sh master
 175 ```
 176
 177 #### dcos-grid::node
 178
 179 This recipe sets up a base node (particular role is not assigned yet). Note: Please execute the following manually.
 180
 181 ```
 182 $ /opt/dcos-grid/node_setup.sh {master|slave|slave_public}
 183 ```
 184
 185 #### dcos-grid::node-commons
 186
 187 This recipe sets up common environment for DC/OS node.
 188
 189 #### dcos-grid::public-agent
 190
 191 This recipe sets up a public node. Note: If `node['dcos-grid']['node']['auto_setup']` is `false`, you must execute the following manually.
 192
 193 ```
 194 $ /opt/dcos-grid/node_setup.sh slave_public
 195 ```
 196
 197 #### dcos-grid::universe-build-env (ver. 0.4.8 or later)
 198
 199 This recipe sets up the build environment for DC/OS Universe (package repository) server.
 200
 201 #### dcos-grid::universe-server (ver. 0.4.9 or later)
 202
 203 This recipe sets up a DC/OS Universe (package repository) server.
 204
 205 ### Role Examples
 206
 207 - `roles/dcos0.rb`: Common attributes.
 208
 209 ```ruby
 210 cluster_name = 'dcos0'
 211
 212 name cluster_name
 213 description "#{cluster_name} cluster"
 214
 215 run_list(
 216 )
 217
 218 override_attributes(
 219   'docker-grid' => {
 220     'engine' => {
 221       'version_on_centos' => '1.11.2-1',
 222       'version_on_ubuntu' => '1.11.2-0',
 223       #'version' => '1.11.2-1.el7.centos',
 224     },
 225   },
 226   'dcos-grid' => {
 227     'dcos_release_url' => 'https://downloads.dcos.io/dcos/stable/dcos_generate_config.sh',
 228     #'dcos_release_url' => 'https://downloads.dcos.io/dcos/EarlyAccess/dcos_generate_config.sh',
 229     # DC/OS 1.8.7
 230     'dcos_release_checksum' => 'ddd9a86e4fc6ab149fb6c2ce38fc7d7c2f5891e62fb5ed41b91c3e99e02ed536',
 231     'bootstrap' => {
 232       'ip' => '192.168.56.100',
 233       'port' => '8080',
 234       'config' => {
 235         'cluster_name' => cluster_name,
 236         'master_list' => [
 237           '192.168.56.101',
 238           '192.168.56.102',
 239           '192.168.56.103',
 240         ],
 241         'resolvers' => [
 242           '8.8.8.8',
 243           '8.8.4.4',
 244         ],
 245       },
 246       'ip-detect' => {
 247         'interface' => 'eth1,enp0s8',
 248       },
 249     },
 250     'node' => {
 251       'auto_setup' => false,
 252     },
 253   },
 254 )
 255 ```
 256
 257 - `roles/dcos0-boot.rb`
 258
 259 ```ruby
 260 cluster_name = 'dcos0'
 261
 262 name "#{cluster_name}-boot"
 263 description "#{cluster_name} cluster bootstrap node"
 264
 265 run_list(
 266   "role[#{cluster_name}]",
 267   'recipe[dcos-grid::bootstrap]',
 268 )
 269 ```
 270
 271 - `roles/dcos0-master.rb`
 272
 273 ```ruby
 274 cluster_name = 'dcos0'
 275
 276 name "#{cluster_name}-master"
 277 description "#{cluster_name} cluster master node"
 278
 279 run_list(
 280   "role[#{cluster_name}]",
 281   'recipe[dcos-grid::master]',
 282 )
 283
 284 override_attributes(
 285   'dcos-grid' => {
 286     'node' => {
 287       'auto_setup' => false,
 288     },
 289   },
 290 )
 291 ```
 292
 293 - `roles/dcos0-agent.rb`
 294
 295 ```ruby
 296 cluster_name = 'dcos0'
 297
 298 name "#{cluster_name}-agent"
 299 description "#{cluster_name} cluster private agent node"
 300
 301 run_list(
 302   "role[#{cluster_name}]",
 303   'recipe[dcos-grid::agent]',
 304 )
 305
 306 override_attributes(
 307   'dcos-grid' => {
 308     'node' => {
 309       'auto_setup' => true,
 310     },
 311   },
 312 )
 313 ```
 314
 315 - `roles/dcos0-cli.rb`
 316
 317 ```ruby
 318 cluster_name = 'dcos0'
 319
 320 name "#{cluster_name}-cli"
 321 description "#{cluster_name} CLI setup"
 322
 323 run_list(
 324   "role[#{cluster_name}]",
 325   'recipe[dcos-grid::cli]',
 326 )
 327
 328 override_attributes(
 329   'dcos-grid' => {
 330     'cli' => {
 331       'version' => '0.4.14',
 332       'release_checksum' => '070587062c7c0b926e2438a383b05c942e99ccf909421feed4941d06e3846fa7',
 333       'auto_upgrade' => true,
 334       'install_path' => '/usr/local/bin/dcos',
 335     },
 336   },
 337 )
 338 ```
 339
 340 - `roles/dcos0-universe-server.rb`
 341
 342 ```ruby
 343 cluster_name = 'dcos0'
 344
 345 name "#{cluster_name}-universe-server"
 346 description "#{cluster_name} universe server"
 347
 348 run_list(
 349   "role[#{cluster_name}]",
 350   'recipe[dcos-grid::universe-server]',
 351 )
 352
 353 override_attributes(
 354   'dcos-grid' => {
 355     'universe-server' => {
 356       'docker-compose' => {
 357         'config' => {
 358           'version' => '2',
 359           'services' => {
 360             'universe' => {
 361               'image' => 'my_account/universe-server:my_tag',
 362               'ports' => [
 363                 '8085:80',
 364               ],
 365             },
 366           },
 367         },
 368       },
 369     },
 370   },
 371 )
 372 ```
 373
 374 ### Upgrade DC/OS (ver. 0.4.3 or later)
 375
 376 - Update attributes about DC/OS release URL (`['dcos-grid']['dcos_release_url']`) and configurations (`['dcos-grid']['bootstrap']['config']`).
 377
 378 - execute `sudo chef-client` on each node.
 379
 380 - upgrade the boostrap node.
 381
 382 ```
 383 $ /opt/dcos-grid/bootstrap_upgrade.sh
 384 ```
 385
 386 - upgrade each follower master node at first, and then upgrade the leader master node.
 387
 388 ```
 389 $ /opt/dcos-grid/node_upgrade.sh master
 390 ```
 391
 392 - upgrade each agent node.
 393
 394 ```
 395 $ /opt/dcos-grid/node_upgrade.sh {slave|slave_public}
 396 ```
 397
 398 - commit the upgrade on the bootstrap node.
 399
 400 ```
 401 $ /opt/dcos-grid/bootstrap_upgrade.sh -c
 402 ```
 403
 404 ### Uninstall DC/OS
 405
 406 Please log in each node and execute the following.
 407
 408 ```
 409 $ /opt/dcos-grid/uninstall.sh
 410 ```
 411
 412 ## License and Authors
 413
 414 - Author:: whitestar at osdn.jp
 415
 416 ```text
 417 Copyright 2016-2017, whitestar
 418
 419 Licensed under the Apache License, Version 2.0 (the "License");
 420 you may not use this file except in compliance with the License.
 421 You may obtain a copy of the License at
 422
 423     http://www.apache.org/licenses/LICENSE-2.0
 424
 425 Unless required by applicable law or agreed to in writing, software
 426 distributed under the License is distributed on an "AS IS" BASIS,
 427 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 428 See the License for the specific language governing permissions and
 429 limitations under the License.
 430 ```