cookbooks/gitlab-grid/README.md

   1 gitlab-grid Cookbook
   2 =====================
   3
   4 This cookbook sets up a GitLab server.
   5
   6 ## Contents
   7
   8 - [Requirements](#requirements)
   9     - [platforms](#platforms)
  10     - [packages](#packages)
  11 - [Attributes](#attributes)
  12 - [Usage](#usage)
  13     - [Recipes](#recipes)
  14         - [gitlab-grid::default](#gitlab-griddefault)
  15         - [gitlab-grid::server](#gitlab-gridserver)
  16         - [gitlab-grid::docker-compose](#gitlab-griddocker-compose)
  17         - [gitlab-grid::runner-docker-compose](#gitlab-gridrunner-docker-compose)
  18     - [Role Examples](#role-examples)
  19     - [Internal CA certificates management by ssl_cert cookbook](#internal-ca-certificates-management-by-ssl_cert-cookbook)
  20     - [SSL server keys and certificates management by ssl_cert cookbook](#ssl-server-keys-and-certificates-management-by-ssl_cert-cookbook)
  21 - [License and Authors](#license-and-authors)
  22
  23 ## Requirements
  24
  25 ### platforms
  26 - none.
  27
  28 ### packages
  29 - none.
  30
  31 ## Attributes
  32
  33 |Key|Type|Description, example|Default|
  34 |:--|:--|:--|:--|
  35 |`['gitlab-grid']['with_ssl_cert_cookbook']`|Boolean|If this attribute is true, CA certificate and server key pairs are deployed and the `node['gitlab-grid']['gitlab.rb']` settings are overridden by the following `common_name` attributes.|`false`|
  36 |`['gitlab-grid']['ssl_cert']['ca_name']`|String|Internal CA name that signs server certificates.|`nil`|
  37 |`['gitlab-grid']['ssl_cert']['common_name']`|String|GitLab server common name for TLS|`node['fqdn']`|
  38 |`['gitlab-grid']['ssl_cert']['registry']['reuse_gitlab_common_name']`|Boolean|Reuse GitLab domain (same common name) for TLS|`false`|
  39 |`['gitlab-grid']['ssl_cert']['registry']['common_name']`|String|Container registry service's unique common name for TLS|`nil`|
  40 |`['gitlab-grid']['gitlab.rb']`|Hash|`gitlab.rb` configurations.|See `attributes/default.rb`|
  41 |`['gitlab-grid']['gitlab.rb_extra_config_str']`|String|`gitlab.rb` extra configuration string (source code in Ruby).|`nil`|
  42 |`['gitlab-grid']['runner-docker-compose']['import_ca']`|Boolean|Import an internal CA certificate to a gitlab-runner container or not.|`false`|
  43 |`['gitlab-grid']['runner-docker-compose']['app_dir']`|String||`"#{node['docker-grid']['compose']['app_dir']}/gitlab-runner"`|
  44 |`['gitlab-grid']['runner-docker-compose']['etc_dir']`|String||`"#{node['gitlab-grid']['runner-docker-compose']['app_dir']}/etc"`|
  45 |`['gitlab-grid']['runner-docker-compose']['config']`|Hash|`docker-compose.yml` configurations.|See `attributes/default.rb`|
  46
  47 ## Usage
  48
  49 ### Recipes
  50
  51 #### gitlab-grid::default
  52
  53 This recipe does nothing.
  54
  55 #### gitlab-grid::server
  56
  57 This recipe sets up a GitLab server.
  58
  59 #### gitlab-grid::docker-compose
  60
  61 This recipe generates a `docker-compose.yml` for the GitLab server.
  62
  63 #### gitlab-grid::runner-docker-compose
  64
  65 This recipe generates a `docker-compose.yml` for the gitlab-runner.
  66
  67 ### Role Examples
  68
  69 - `roles/gitlab.rb`
  70
  71 ```ruby
  72 name 'gitlab'
  73 description 'GitLab'
  74
  75 run_list(
  76   'recipe[gitlab-grid::server]',
  77 )
  78
  79 #env_run_lists()
  80
  81 #default_attributes()
  82
  83 gitlab_cn = 'gitlab.io.example.com'
  84
  85 override_attributes(
  86   'gitlab-grid' => {
  87     # See https://docs.gitlab.com/omnibus/settings/configuration.html
  88     'gitlab.rb' => {
  89       'external_url' => "http://#{gitlab_cn}",
  90       'gitlab_rails' => {
  91         'time_zone' => 'Asia/Tokyo',
  92       },
  93     },
  94   },
  95 )
  96 ```
  97
  98 - `roles/gitlab-with-ssl-cert.rb`
  99
 100 ```ruby
 101 name 'gitlab-with-ssl-cert'
 102 description 'GitLab setup with ssl_cert cookbook'
 103
 104 run_list(
 105   'recipe[ssl_cert::server_key_pairs]',
 106   'recipe[gitlab-grid::server]',
 107 )
 108
 109 #env_run_lists()
 110
 111 #default_attributes()
 112
 113 gitlab_cn = 'gitlab.io.example.com'
 114
 115 override_attributes(
 116   'ssl_cert' => {
 117     'common_names' => [
 118       gitlab_cn,
 119     ],
 120   },
 121   'gitlab-grid' => {
 122     'with_ssl_cert_cookbook' => true,
 123     'ssl_cert' => {
 124       'common_name' => gitlab_cn,
 125     },
 126     'gitlab.rb' => {
 127       'external_url' => "https://#{gitlab_cn}",
 128       'gitlab_rails' => {
 129         'time_zone' => 'Asia/Tokyo',
 130       },
 131       'nginx' => {
 132         'redirect_http_to_https' => true,
 133       },
 134     },
 135   },
 136 )
 137 ```
 138
 139 - `roles/gitlab-on-docker.rb`
 140
 141 ```ruby
 142 name 'gitlab-on-docker'
 143 description 'GitLab on Docker'
 144
 145 gitlab_cn = 'gitlab.io.example.com'
 146 gitlab_http_port = '8080'
 147 gitlab_ssh_port = '2022'
 148
 149 run_list(
 150   'role[docker]',
 151   'recipe[gitlab-grid::docker-compose]',
 152 )
 153
 154 #env_run_lists()
 155
 156 #default_attributes()
 157
 158 override_attributes(
 159   'gitlab-grid' => {
 160     'gitlab.rb' => {
 161       'external_url' => "http://#{gitlab_cn}:#{gitlab_http_port}",
 162       'gitlab_rails' => {
 163         'time_zone' => 'Asia/Tokyo',
 164         'gitlab_shell_ssh_port' => gitlab_ssh_port.to_i,
 165       },
 166       'nginx' => {
 167         'redirect_http_to_https' => false,
 168       },
 169     },
 170     'docker-compose' => {
 171       'config' => {
 172         # Version 2 docker-compose format
 173         'version' => '2',
 174         'services' => {
 175           'gitlab' => {
 176             'restart' => 'always',
 177             'image' => 'gitlab/gitlab-ce:latest',
 178             'hostname' => gitlab_cn,
 179             'ports' => [
 180               "#{gitlab_http_port}:#{gitlab_http_port}",
 181               "#{gitlab_ssh_port}:22",
 182             ],
 183             'environment' => {
 184             },
 185             #'volumes' => [
 186             #],
 187           },
 188         },
 189       },
 190     },
 191   },
 192 )
 193 ```
 194
 195 - `roles/gitlab-with-ssl-on-docker.rb`: and activates Container registry feature.
 196
 197 ```ruby
 198 name 'gitlab-with-ssl-on-docker'
 199 description 'GitLab with SSL on Docker'
 200
 201 gitlab_cn = 'gitlab.io.example.com'
 202 gitlab_https_port = '8443'
 203 gitlab_ssh_port = '2022'
 204 gitlab_registry_port = '5050'
 205
 206 run_list(
 207   'recipe[ssl_cert::server_key_pairs]',
 208   'role[docker]',
 209   'recipe[gitlab-grid::docker-compose]',
 210 )
 211
 212 #env_run_lists()
 213
 214 #default_attributes()
 215
 216 override_attributes(
 217   'ssl_cert' => {
 218     'common_names' => [
 219       gitlab_cn,
 220     ],
 221   },
 222   'gitlab-grid' => {
 223     'with_ssl_cert_cookbook' => true,
 224     'ssl_cert' => {
 225       'common_name' => gitlab_cn,
 226       'registry' => {
 227         'reuse_gitlab_common_name' => true,
 228         # or
 229         #'reuse_gitlab_common_name' => false,
 230         #'common_name' => registry_gitlab_cn,
 231       },
 232     },
 233     'gitlab.rb' => {
 234       'external_url' => "https://#{gitlab_cn}:#{gitlab_https_port}",
 235       'registry_external_url' => "https://#{gitlab_cn}:#{gitlab_registry_port}",  # Do not use 5000 if same domain (common name)
 236       'gitlab_rails' => {
 237         'time_zone' => 'Asia/Tokyo',
 238         'gitlab_shell_ssh_port' => gitlab_ssh_port.to_i,
 239       },
 240       'nginx' => {
 241         'redirect_http_to_https' => true,
 242       },
 243       'registry_nginx' => {
 244         'redirect_http_to_https' => true,
 245       },
 246     },
 247     'docker-compose' => {
 248       'config' => {
 249         # Version 2 docker-compose format
 250         'version' => '2',
 251         'services' => {
 252           'gitlab' => {
 253             'restart' => 'always',
 254             'image' => 'gitlab/gitlab-ce:latest',
 255             'hostname' => gitlab_cn,
 256             'ports' => [
 257               "#{gitlab_https_port}:#{gitlab_https_port}",
 258               "#{gitlab_registry_port}:#{gitlab_registry_port}",
 259               "#{gitlab_ssh_port}:22",
 260             ],
 261             'environment' => {
 262             },
 263             #'volumes' => [
 264             #],
 265           },
 266         },
 267       },
 268     },
 269   },
 270 )
 271 ```
 272
 273 - `roles/gitlab-runner.rb`
 274
 275 ```ruby
 276 name 'gitlab-runner'
 277 description 'GitLab-runner'
 278
 279 run_list(
 280   #'recipe[ssl_cert::ca_certs]',
 281   'role[docker]',
 282   'recipe[gitlab-grid::runner-docker-compose]',
 283 )
 284
 285 #env_run_lists()
 286
 287 #default_attributes()
 288
 289 ca_name = 'grid_ca'  # Internal CA
 290
 291 override_attributes(
 292   'ssl_cert' => {
 293     'ca_names' => [
 294       ca_name,
 295     ],
 296   },
 297   'gitlab-grid' => {
 298     #'with_ssl_cert_cookbook' => true,
 299     'ssl_cert' => {
 300       'ca_name' => ca_name,
 301     },
 302     'runner-docker-compose' => {
 303       #'import_ca' => true,
 304       'config' => {
 305         'services' => {
 306           'runner' => {
 307             'volumes' => [
 308               # for Docker executor
 309               '/var/run/docker.sock:/var/run/docker.sock',
 310             ],
 311           },
 312         },
 313       },
 314     },
 315   },
 316 )
 317 ```
 318
 319 ### Internal CA certificates management by ssl_cert cookbook
 320
 321 See https://supermarket.chef.io/cookbooks/ssl_cert
 322
 323 ### SSL server keys and certificates management by ssl_cert cookbook
 324
 325 - create vault items.
 326
 327 ```text
 328 $ ruby -rjson -e 'puts JSON.generate({"private" => File.read("gitlab.io.example.com.prod.key")})' \
 329 > > ~/tmp/gitlab.io.example.com.prod.key.json
 330
 331 $ ruby -rjson -e 'puts JSON.generate({"public" => File.read("gitlab.io.example.com.prod.crt")})' \
 332 > > ~/tmp/gitlab.io.example.com.prod.crt.json
 333
 334 $ cd $CHEF_REPO_PATH
 335
 336 $ knife vault create ssl_server_keys gitlab.io.example.com.prod \
 337 > --json ~/tmp/gitlab.io.example.com.prod.key.json
 338
 339 $ knife vault create ssl_server_certs gitlab.io.example.com.prod \
 340 > --json ~/tmp/gitlab.io.example.com.prod.crt.json
 341 ```
 342
 343 - grant reference permission to the gitlab host
 344
 345 ```text
 346 $ knife vault update ssl_server_keys  gitlab.io.example.com.prod -S 'name:gitlab*.io.example.com'
 347 $ knife vault update ssl_server_certs gitlab.io.example.com.prod -S 'name:gitlab*.io.example.com'
 348 ```
 349
 350 - modify run_list and attributes
 351
 352 ```ruby
 353 run_list(
 354   'recipe[ssl_cert::server_key_pairs]',
 355   'recipe[gitlab-grid::server]',
 356   #'recipe[gitlab-grid::docker-compose]',
 357 )
 358
 359 override_attributes(
 360   'ssl_cert' => {
 361     'common_names' => [
 362       'gitlab.io.example.com',
 363     ],
 364   },
 365   'gitlab-grid' => {
 366     'with_ssl_cert_cookbook' => true,
 367     'ssl_cert' => {
 368       'common_name' => 'gitlab.io.example.com',
 369     },
 370     # ...
 371   },
 372 )
 373 ```
 374
 375 ## License and Authors
 376
 377 - Author:: whitestar at osdn.jp
 378
 379 ```text
 380 Copyright 2017, whitestar
 381
 382 Licensed under the Apache License, Version 2.0 (the "License");
 383 you may not use this file except in compliance with the License.
 384 You may obtain a copy of the License at
 385
 386     http://www.apache.org/licenses/LICENSE-2.0
 387
 388 Unless required by applicable law or agreed to in writing, software
 389 distributed under the License is distributed on an "AS IS" BASIS,
 390 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 391 See the License for the specific language governing permissions and
 392 limitations under the License.
 393 ```