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   - [Role Examples](#role-examples)
  25   - [Uninstall DC/OS](#uninstall-dcos)
  26 - [License and Authors](#license-and-authors)
  27
  28 ## Requirements
  29
  30 ### platforms
  31 - CentOS, Red Hat Enterprise Linux >= 7.2
  32 - CoreOS Latest version.
  33 - Ubuntu 16.04 (Experimental). DC/OS does not officially support Ubuntu yet. See [_Ubuntu 16.04 Enablement_](https://dcosjira.atlassian.net/browse/DCOS-25).
  34   - DC/OS requires systemd, which is only fully supported in Ubuntu 15.04 and later releases. See [_SystemdForUpstartUsers_](https://wiki.ubuntu.com/SystemdForUpstartUsers)
  35
  36 ### packages
  37 - none.
  38
  39 ### cookbooks
  40 - `docker-grid` (for `dcos-grid` ver. 0.4.0 or later).
  41
  42 ## Attributes
  43
  44 |Key|Type|Description, example|Default|
  45 |:--|:--|:--|:--|
  46 |`['dcos-grid']['dcos_release_url']`|String|DC/OS download URL.|`'https://downloads.dcos.io/dcos/stable/dcos_generate_config.sh'`|
  47 |`['dcos-grid']['dcos_cli_release_url']`|String|DC/OS CLI download URL (ver. 0.3.0 or later).|`'https://downloads.dcos.io/binaries/cli/linux/x86-64/0.4.10/dcos'`|
  48 |`['dcos-grid']['docker']['apt_repo']['url']`|String|DEPRECATED: use `['docker-grid']['apt_repo']['url']` (ver. 0.4.0 or later)|`nil`|
  49 |`['dcos-grid']['docker']['apt_repo']['keyserver']`|String|DEPRECATED: use `['docker-grid']['apt_repo']['keyserver']` (ver. 0.4.0 or later)|`nil`|
  50 |`['dcos-grid']['docker']['apt_repo']['recv-keys']`|String|DEPRECATED: use `['docker-grid']['apt_repo']['recv-keys']` (ver. 0.4.0 or later)|`nil`|
  51 |`['dcos-grid']['docker']['yum_repo']['baseurl']`|String|DEPRECATED: use `['docker-grid']['yum_repo']['baseurl']` (ver. 0.4.0 or later)|`nil`|
  52 |`['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`|
  53 |`['dcos-grid']['docker']['yum_repo']['gpgkey']`|String|DEPRECATED: use `['docker-grid']['yum_repo']['gpgkey']` (ver. 0.4.0 or later)|`nil`|
  54 |`['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`|
  55 |`['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`|
  56 |`['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`|
  57 |`['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|
  58 |`['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`|
  59 |`['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`|
  60 |`['dcos-grid']['docker-engine']['storage-driver']`|String|DEPRECATED: use `['docker-grid']['engine']['storage-driver']` (ver. 0.4.0 or later).|See default.rb|
  61 |`['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`|
  62 |`['dcos-grid']['bootstrap']['ip']`|String|Bootstrap node IP address.|`'127.0.0.1'`|
  63 |`['dcos-grid']['bootstrap']['port']`|String|Bootstrap node port number.|`'8080'`|
  64 |`['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'`|
  65 |`['dcos-grid']['bootstrap']['config']`|Hash|Install configurations.|see [_Install Configuration Parameters_](https://dcos.io/docs/1.8/administration/installing/custom/configuration-parameters/)|
  66 |`['dcos-grid']['bootstrap']['config']['bootstrap_url']`|String||`"http://#{node['dcos-grid']['bootstrap']['ip']}:#{node['dcos-grid']['bootstrap']['port']}"`|
  67 |`['dcos-grid']['bootstrap']['config']['cluster_name']`|String||`'dcos0'`|
  68 |`['dcos-grid']['bootstrap']['config']['exhibitor_storage_backend']`|String||`'static'`|
  69 |`['dcos-grid']['bootstrap']['config']['ip_detect_filename']`|String||`'/genconf/ip-detect'`|
  70 |`['dcos-grid']['bootstrap']['config']['master_discovery']`|String|(ver. 0.3.2 or later)|`'static'`|
  71 |`['dcos-grid']['bootstrap']['config']['master_list']`|Array|e.g. `['192.168.1.101','192.168.1.102','192.168.1.103']`|`nil`|
  72 |`['dcos-grid']['bootstrap']['config']['oauth_auth_host']`|String|(ver. 0.3.2 or later)|`'https://dcos.auth0.com'`|
  73 |`['dcos-grid']['bootstrap']['config']['oauth_auth_redirector']`|String|(ver. 0.3.2 or later)|`'https://auth.dcos.io'`|
  74 |`['dcos-grid']['bootstrap']['config']['oauth_available']`|String|(ver. 0.3.2 or later)|`'true'`|
  75 |`['dcos-grid']['bootstrap']['config']['oauth_enabled']`|String|(ver. 0.3.2 or later)|`'true'`|
  76 |`['dcos-grid']['bootstrap']['config']['oauth_issuer_url']`|String|(ver. 0.3.2 or later)|`'https://dcos.auth0.com/'`|
  77 |`['dcos-grid']['bootstrap']['config']['resolvers']`|Array|e.g. `['8.8.8.8','8.8.4.4']` (Google DNS)|`nil`|
  78 |`['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'`|
  79 |`['dcos-grid']['node']['auto_setup']`|Boolean|execute the node setup script automatically or not.|`false`|
  80 |`['dcos-grid']['cloud-config']['target_platform']`|String|CoreOS only now.|`'coreos'`|
  81 |`['dcos-grid']['cloud-config']['target_dir']`|String||`'/home/core'`|
  82 |`['dcos-grid']['cloud-config']['target_owner']`|String||`'core:core'`|
  83 |`['dcos-grid']['cloud-config']['hostname']`|String||`'<fqdn>'`|
  84 |`['dcos-grid']['cloud-config']['ssh_authorized_keys']`|Array||`['<your_ssh_pub_key>',]`|
  85
  86 ## Usage
  87
  88 ### Recipes
  89
  90 #### dcos-grid::default
  91
  92 This recipe does nothing.
  93
  94 #### dcos-grid::agent
  95
  96 This recipe sets up a private agent node. Note: If `node['dcos-grid']['node']['auto_setup']` is `false`, you must execute the following manually.
  97
  98 ```
  99 $ /opt/dcos-grid/node_setup.sh slave
 100 ```
 101
 102 #### dcos-grid::bootstrap
 103
 104 This recipe sets up a bootstrap node. Note: Please execute the following manually.
 105
 106 ```
 107 $ /opt/dcos-grid/bootstrap_setup.sh
 108 ```
 109
 110 #### dcos-grid::cli (ver. 0.3.0 or later)
 111
 112 This recipe installs DC/OS CLI.
 113
 114 #### dcos-grid::cloud-config (for CoreOS only)
 115
 116 This recipe generates a `/home/core/cloud-config.yaml` template file on local machine by the following `chef-solo` command.
 117
 118 ```
 119 $ sudo chef-solo -c solo.rb -j nodes/local-dcos0-cloud-config.json
 120 ```
 121
 122 - `nodes/local-dcos0-cloud-config.json`
 123
 124 ```json
 125 {
 126   "run_list": [
 127     "role[dcos0-cloud-config]"
 128   ]
 129 }
 130 ```
 131
 132 - `roles/dcos0-cloud-config.rb`
 133
 134 ```ruby
 135 cluster_name = 'dcos0'
 136
 137 name "#{cluster_name}-cloud-config"
 138 description "#{cluster_name} cloud-config.yaml file."
 139
 140 run_list(
 141   "role[#{cluster_name}]",  # includes common attributes.
 142   'recipe[dcos-grid::cloud-config]',
 143 )
 144 ```
 145
 146 Then edit this yaml template (hostname, ssh_authorized_keys, IP address and so on) and install CoreOS by the `cloud-config.yaml`.
 147
 148 ```
 149 $ coreos-cloudinit -from-file ~/cloud-config.yaml -validate
 150 ...
 151 $ sudo coreos-install -d /dev/sda -C stable -c ~/cloud-config.yaml
 152 ```
 153
 154 #### dcos-grid::master
 155
 156 This recipe sets up a master node. Note: If `node['dcos-grid']['node']['auto_setup']` is `false`, you must execute the following manually.
 157
 158 ```
 159 $ /opt/dcos-grid/node_setup.sh master
 160 ```
 161
 162 #### dcos-grid::node
 163
 164 This recipe sets up a base node (particular role is not assigned yet). Note: Please execute the following manually.
 165
 166 ```
 167 $ /opt/dcos-grid/node_setup.sh {master|slave|slave_public}
 168 ```
 169
 170 #### dcos-grid::node-commons
 171
 172 This recipe sets up common environment for DC/OS node.
 173
 174 #### dcos-grid::public-agent
 175
 176 This recipe sets up a public node. Note: If `node['dcos-grid']['node']['auto_setup']` is `false`, you must execute the following manually.
 177
 178 ```
 179 $ /opt/dcos-grid/node_setup.sh slave_public
 180 ```
 181
 182 ### Role Examples
 183
 184 - `roles/dcos0.rb`: Common attributes.
 185
 186 ```ruby
 187 cluster_name = 'dcos0'
 188
 189 name cluster_name
 190 description "#{cluster_name} cluster"
 191
 192 run_list(
 193 )
 194
 195 override_attributes(
 196   'docker-grid' => {
 197     'engine' => {
 198       'version_on_centos' => '1.11.2-1',
 199       'version_on_ubuntu' => '1.11.2-0',
 200       #'version' => '1.11.2-1.el7.centos',
 201     },
 202   },
 203   'dcos-grid' => {
 204     'dcos_release_url' => 'https://downloads.dcos.io/dcos/stable/dcos_generate_config.sh',
 205     #'dcos_release_url' => 'https://downloads.dcos.io/dcos/EarlyAccess/dcos_generate_config.sh',
 206     'bootstrap' => {
 207       'ip' => '192.168.56.100',
 208       'port' => '8080',
 209       'config' => {
 210         'cluster_name' => cluster_name,
 211         'master_list' => [
 212           '192.168.56.101',
 213           '192.168.56.102',
 214           '192.168.56.103',
 215         ],
 216         'resolvers' => [
 217           '8.8.8.8',
 218           '8.8.4.4',
 219         ],
 220       },
 221       'ip-detect' => {
 222         'interface' => 'eth1,enp0s8',
 223       },
 224     },
 225     'node' => {
 226       'auto_setup' => false,
 227     },
 228   },
 229 )
 230 ```
 231
 232 - `roles/dcos0-boot.rb`
 233
 234 ```ruby
 235 cluster_name = 'dcos0'
 236
 237 name "#{cluster_name}-boot"
 238 description "#{cluster_name} cluster bootstrap node"
 239
 240 run_list(
 241   "role[#{cluster_name}]",
 242   'recipe[dcos-grid::bootstrap]',
 243 )
 244 ```
 245
 246 - `roles/dcos-master.rb`
 247
 248 ```ruby
 249 cluster_name = 'dcos0'
 250
 251 name "#{cluster_name}-master"
 252 description "#{cluster_name} cluster master node"
 253
 254 run_list(
 255   "role[#{cluster_name}]",
 256   'recipe[dcos-grid::master]',
 257 )
 258
 259 override_attributes(
 260   'dcos-grid' => {
 261     'node' => {
 262       'auto_setup' => false,
 263     },
 264   },
 265 )
 266 ```
 267
 268 - `roles/dcos0-agent.rb`
 269
 270 ```ruby
 271 cluster_name = 'dcos0'
 272
 273 name "#{cluster_name}-agent"
 274 description "#{cluster_name} cluster private agent node"
 275
 276 run_list(
 277   "role[#{cluster_name}]",
 278   'recipe[dcos-grid::agent]',
 279 )
 280
 281 override_attributes(
 282   'dcos-grid' => {
 283     'node' => {
 284       'auto_setup' => true,
 285     },
 286   },
 287 )
 288 ```
 289
 290 ### Uninstall DC/OS
 291
 292 Please log in each node and execute the following.
 293
 294 ```
 295 $ /opt/dcos-grid/uninstall.sh
 296 ```
 297
 298 ## License and Authors
 299
 300 - Author:: whitestar at osdn.jp
 301
 302 ```text
 303 Copyright 2016, whitestar
 304
 305 Licensed under the Apache License, Version 2.0 (the "License");
 306 you may not use this file except in compliance with the License.
 307 You may obtain a copy of the License at
 308
 309     http://www.apache.org/licenses/LICENSE-2.0
 310
 311 Unless required by applicable law or agreed to in writing, software
 312 distributed under the License is distributed on an "AS IS" BASIS,
 313 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 314 See the License for the specific language governing permissions and
 315 limitations under the License.
 316 ```