cookbooks/jenkins-grid/README.md

   1 jenkins-grid Cookbook
   2 =====================
   3
   4 This cookbook sets up a Jenkins service.
   5
   6 ## Contents
   7
   8 - [Requirements](#requirements)
   9     - [platforms](#platforms)
  10     - [packages](#packages)
  11 - [Attributes](#attributes)
  12 - [Usage](#usage)
  13     - [Recipes](#recipes)
  14         - [jenkins-grid::default](#jenkins-griddefault)
  15         - [jenkins-grid::docker-compose](#jenkins-griddocker-compose)
  16     - [Role Examples](#role-examples)
  17     - [SSL server keys and certificates management by ssl_cert cookbook](#ssl-server-keys-and-certificates-management-by-ssl_cert-cookbook)
  18 - [License and Authors](#license-and-authors)
  19
  20 ## Requirements
  21
  22 ### platforms
  23
  24 - Debian >= 9.0
  25 - Ubuntu >= 14.04
  26 - CentOS,RHEL >= 7.3
  27
  28 ### packages
  29 - none.
  30
  31 ## Attributes
  32
  33 |Key|Type|Description, example|Default|
  34 |:--|:--|:--|:--|
  35 |`['jenkins-grid']['with_ssl_cert_cookbook']`|Boolean|If this attribute is true, `node['jenkins-grid']['docker-compose']['config']` are are overridden by the following `common_name` attributes.|`false`|
  36 |`['jenkins-grid']['ssl_cert']['common_name']`|String|Jenkins server common name for TLS|`node['fqdn']`|
  37 |`['jenkins-grid']['num_executors']`|Integer|Number of executors.|`2`|
  38 |`['jenkins-grid']['log.properties']`|Hash|java.util.logging configurations.|See `attributes/default.rb`|
  39 |`['jenkins-grid']['docker-compose']['app_dir']`|String||`"#{node['docker-grid']['compose']['app_dir']}/jenkins"`|
  40 |`['jenkins-grid']['docker-compose']['jenkins_home']['path']`|String|Path string or nil (unset).|`'/var/lib/jenkins_home'`|
  41 |`['jenkins-grid']['docker-compose']['jenkins_home']['owner']`|String, Integer|Jenkins owner uid (read only). |`1000`|
  42 |`['jenkins-grid']['docker-compose']['config']`|Hash|`docker-compose.yml` configurations.|See `attributes/default.rb`|
  43
  44 ## Usage
  45
  46 ### Recipes
  47
  48 #### jenkins-grid::default
  49
  50 This recipe does nothing.
  51
  52 #### jenkins-grid::docker-compose
  53
  54 This recipe generates a docker-compose.yml for the Jenkins CI service.
  55
  56 ### Role Examples
  57
  58 - `roles/jenkins.rb`
  59
  60 ```ruby
  61 name 'jenkins'
  62 description 'Jenkins'
  63
  64 run_list(
  65   'role[docker]',
  66   'recipe[jenkins-grid::docker-compose]',
  67 )
  68
  69 #env_run_lists()
  70
  71 #default_attributes()
  72
  73 override_attributes(
  74   'jenkins-grid' => {
  75     'docker-compose' => {
  76       'config' => {
  77         # Version 2 docker-compose format
  78         'version' => '2',
  79         'services' => {
  80           'jenkins' => {
  81             'restart' => 'always',
  82             'image' => 'jenkins:latest',
  83             'ports' => [
  84               '8080:8080',
  85               '50000:50000',
  86             ],
  87             #'environment' => {
  88             #},
  89             #'volumes' => [
  90             #  # set automatically, if the node['jenkins-grid']['docker-compose']['jenkins_home']['path'] is not nil.
  91             #  "#{node['jenkins-grid']['docker-compose']['jenkins_home']['path']}:/var/jenkins_home",
  92             #],
  93           },
  94         },
  95       },
  96     },
  97   },
  98 )
  99 ```
 100
 101 - `roles/jenkins-with-ssl-cert.rb`
 102
 103 ```ruby
 104 name 'jenkins-with-ssl-cert'
 105 description 'Jenkins setup with ssl_cert cookbook'
 106
 107 run_list(
 108   #'recipe[ssl_cert::server_key_pairs]',  # jenkins-grid <= 0.2.3
 109   'role[docker]',
 110   'recipe[jenkins-grid::docker-compose]',
 111 )
 112
 113 #env_run_lists()
 114
 115 #default_attributes()
 116
 117 jenkins_cn = 'jenkins.io.example.com'
 118
 119 override_attributes(
 120   'jenkins-grid' => {
 121     'with_ssl_cert_cookbook' => true,
 122     'ssl_cert' => {
 123       'common_name' => jenkins_cn,
 124     },
 125     'docker-compose' => {
 126       'config' => {
 127         # Version 2 docker-compose format
 128         'version' => '2',
 129         'services' => {
 130           'jenkins' => {
 131             'restart' => 'always',
 132             'image' => 'jenkins:latest',
 133             'expose' => [
 134               '8083',  # for https
 135             ],
 136             'ports' => [
 137               '8083:8083',
 138               '50000:50000',
 139             ],
 140             'environment' => {
 141               'JENKINS_OPTS' => [
 142                 '--httpPort=-1 --httpsPort=8083',
 143                 # These options will be set by the jenkins-grid::docker-compose recipe automatically.
 144                 #'--httpsCertificate=/var/lib/jenkins/server.crt',
 145                 #'--httpsPrivateKey=/var/lib/jenkins/server.key',
 146               ].join(' '),
 147             },
 148             # These volumes will be set by the jenkins-grid::docker-compose recipe automatically.
 149             #'volumes' => [
 150             #  "#{node['jenkins-grid']['docker-compose']['jenkins_home']['path']}:/var/jenkins_home",
 151             #  "#{server_cert_path(node['jenkins-grid']['ssl_cert']['common_name'])}:/var/lib/jenkins/server.crt:ro",
 152             #  "#{node['jenkins-grid']['docker-compose']['app_dir']}/certs/server.key:/var/lib/jenkins/server.key:ro",
 153             #],
 154           },
 155         },
 156       },
 157     },
 158   },
 159   'ssl_cert' => {
 160     'common_names' => [
 161       jenkins_cn,
 162     ],
 163   }
 164 )
 165 ```
 166
 167 ### SSL server keys and certificates management by `ssl_cert` cookbook
 168
 169 - create vault items.
 170
 171 ```text
 172 $ ruby -rjson -e 'puts JSON.generate({"private" => File.read("jenkins.io.example.com.prod.key")})' \
 173 > > ~/tmp/jenkins.io.example.com.prod.key.json
 174
 175 $ ruby -rjson -e 'puts JSON.generate({"public" => File.read("jenkins.io.example.com.prod.crt")})' \
 176 > > ~/tmp/jenkins.io.example.com.prod.crt.json
 177
 178 $ cd $CHEF_REPO
 179
 180 $ knife vault create ssl_server_keys jenkins.io.example.com.prod \
 181 > --json ~/tmp/jenkins.io.example.com.prod.key.json
 182
 183 $ knife vault create ssl_server_certs jenkins.io.example.com.prod \
 184 > --json ~/tmp/jenkins.io.example.com.prod.crt.json
 185 ```
 186
 187 - grant reference permission to the Jenkins host
 188
 189 ```text
 190 $ knife vault update ssl_server_keys  jenkins.io.example.com.prod -S 'name:jenkins-host.example.com'
 191 $ knife vault update ssl_server_certs jenkins.io.example.com.prod -S 'name:jenkins-host.example.com'
 192 ```
 193
 194 - modify run_list and attributes
 195
 196 ```ruby
 197 run_list(
 198   #'recipe[ssl_cert::server_key_pairs]',  # jenkins-grid <= 0.2.3
 199   'recipe[jenkins-grid::docker-compose]',
 200 )
 201
 202 override_attributes(
 203   'ssl_cert' => {
 204     'common_names' => [
 205       'jenkins.io.example.com',
 206     ],
 207   },
 208   'jenkins-grid' => {
 209     'with_ssl_cert_cookbook' => true,
 210     'ssl_cert' => {
 211       'common_name' => 'jenkins.io.example.com',
 212     },
 213     # ...
 214   },
 215 )
 216 ```
 217
 218 ## License and Authors
 219
 220 - Author:: whitestar at osdn.jp
 221
 222 ```text
 223 Copyright 2016-2017, whitestar
 224
 225 Licensed under the Apache License, Version 2.0 (the "License");
 226 you may not use this file except in compliance with the License.
 227 You may obtain a copy of the License at
 228
 229     http://www.apache.org/licenses/LICENSE-2.0
 230
 231 Unless required by applicable law or agreed to in writing, software
 232 distributed under the License is distributed on an "AS IS" BASIS,
 233 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 234 See the License for the specific language governing permissions and
 235 limitations under the License.
 236 ```