docs/configuration.rst

   1 #############
   2 Configuration
   3 #############
   4
   5 .. _defaults-yaml:
   6
   7 defaults.yaml
   8 =============
   9
  10 This file lives in the ci-management repo typically under the path
  11 ``jjb/defaults.yaml``. The purpose of this file is to store default variable
  12 values used by global-jjb templates.
  13
  14 **Required**
  15
  16 :jenkins-ssh-credential: The name of the Jenkins Credential to
  17     use for ssh connections. (ex: jenkins-ssh)
  18
  19 :lftools-version: Version of lftools to install. Can be a specific version
  20     like '0.6.1' or a `PEP-440 definition <https://www.python.org/dev/peps/pep-0440/>`_
  21     For example `<1.0.0` or `>=1.0.0,<2.0.0`.
  22
  23 :mvn-site-id: Maven Server ID from settings.xml containing the credentials
  24     to push to a Maven site repository.
  25
  26 :mvn-staging-id: Maven Server ID from settings.xml containing the credentials
  27     to push to a Maven staging repository.
  28
  29 **Gerrit required parameters**:
  30
  31 :gerrit-server-name: The name of the Gerrit Server as defined in Gerrit
  32     Trigger global configuration. (ex: Primary)
  33
  34 **GitHub required parameters**:
  35
  36 :git-url: Set this to the base URL of your GitHub repo. In
  37     general this should be <https://github.com>. If you are using
  38     GitHub Enterprise, or some other GitHub-style system, then it
  39     should be whatever your installation base URL is.
  40
  41 :git-clone-url: This is the clone prefix used by GitHub jobs.
  42     Set this to either the same thing as **git-url** or the
  43     'git@github.com:' including the trailing ':'
  44
  45 :github-org: The name of the GitHub organization interpolated
  46     into the scm config.
  47
  48 :github_pr_org: The name of the GitHub organization. All members
  49     of this organization will be able to trigger any job using the
  50     `lf-infra-github-pr` macro.
  51
  52 :github_pr_whitelist: List of GitHub members you wish to be able to
  53     trigger any job that uses the `lf-infra-github-pr-trigger` macro.
  54
  55 :github_pr_admin_list: List of GitHub members that will have admin
  56     privileges on any job using the `lf-infra-github-pr-trigger` macro.
  57
  58 Example Gerrit Infra:
  59
  60 .. code-block:: yaml
  61
  62    - defaults:
  63        name: global
  64
  65        # lf-infra defaults
  66        jenkins-ssh-credential: jenkins-ssh
  67        gerrit-server-name: OpenDaylight
  68        lftools-version: '<1.0.0'
  69        mvn-site-id: opendaylight-site
  70        mvn-staging-id: opendaylight-staging
  71
  72 Example GitHub Infra:
  73
  74 .. code-block:: yaml
  75
  76    - defaults:
  77        name: global
  78
  79        # lf-infra defaults
  80        jenkins-ssh-credential: jenkins-ssh
  81        github-org: lfit
  82        github_pr_whitelist:
  83          - jpwku
  84          - tykeal
  85          - zxiiro
  86        github_pr_admin_list:
  87          - tykeal
  88        lftools-version: '<1.0.0'
  89        mvn-site-id: opendaylight-site
  90        mvn-staging-id: opendaylight-staging
  91
  92 .. _jenkins-files:
  93
  94 Jenkins Files
  95 =============
  96
  97 global-jjb makes use of the Jenkins Config File Provider plugin to provide some
  98 default configurations for certain tools. This section details the files to
  99 define in Jenkins' **Manage Files** configuration.
 100
 101 .. _npmrc:
 102
 103 npmrc
 104 -----
 105
 106 This file contains default npmrc configuration and lives in $HOME/.npmrc.
 107 Documentation for npmrc is available via the `npm project
 108 <https://docs.npmjs.com/files/npmrc>`_.
 109
 110 :Required: This file MUST exist. An empty file is acceptable if a
 111     proxy is not available for the project.
 112 :type: Custom file
 113
 114 Create a "Custom file" with contents:
 115
 116 .. code-block:: ini
 117
 118    registry = https://nexus.opendaylight.org/content/repositories/npmjs/
 119
 120 .. _pipconf:
 121
 122 pipconf
 123 -------
 124
 125 This file contains default configuration for the python-pip tool and lives
 126 in $HOME/.config/pip/pip.conf. Documentation for pip.conf is available via the
 127 `pip project <https://pip.readthedocs.io/en/stable/user_guide/#configuration>`_.
 128
 129 :Required: This file MUST exist. An empty file is acceptable if a
 130     proxy is not available for the project.
 131 :type: Custom file
 132
 133 Create a "Custom file" with contents:
 134
 135 .. code-block:: ini
 136
 137    [global]
 138    timeout = 60
 139    index-url = https://nexus3.opendaylight.org/repository/PyPi/simple
 140
 141 .. _jjbini:
 142
 143 jjbini
 144 ------
 145
 146 This file contains the Jenkins Job Builder `configuration
 147 <https://docs.openstack.org/infra/jenkins-job-builder/execution.html#configuration-file>`_
 148 for :doc:`jjb/lf-ci-jobs`.
 149
 150 :Required: This file MUST exist.
 151 :type: Custom file
 152
 153 Create a "Custom file" with contents:
 154
 155 .. code-block:: ini
 156
 157     [job_builder]
 158     ignore_cache=True
 159     keep_descriptions=False
 160     include_path=.:scripts:~/git/
 161     recursive=True
 162
 163     [jenkins]
 164     user=jenkins-jobbuilder
 165     password=1234567890abcdef1234567890abcdef
 166     url=https://jenkins.example.org
 167     query_plugins_info=False
 168
 169     [production]
 170     user=jenkins-jobbuilder
 171     password=1234567890abcdef1234567890abcdef
 172     url=https://jenkins.example.org
 173     query_plugins_info=False
 174
 175     [sandbox]
 176     user=jenkins-jobbuilder
 177     password=1234567890abcdef1234567890abcdef
 178     url=https://jenkins.example.org/sandbox
 179     query_plugins_info=False
 180
 181 The last 2 sections are for the ``jenkins-cfg`` job use, they should match the
 182 ``silo`` names for the respective Jenkins systems, typically ``production`` and
 183 ``sandbox``.
 184
 185 .. _jenkins-log-archives-settings:
 186
 187 jenkins-log-archives-settings
 188 -----------------------------
 189
 190 See :ref:`lf-infra-ship-logs` for usage. If not archiving logs then keep this
 191 file with default settings, global-jjb needs the file to exist to function.
 192
 193 Requires a *credential* named 'logs' of type 'Username and Password' created in
 194 the Jenkins Credentials system.
 195
 196 #. Add Server Credentials
 197 #. Set ``ServerId`` to ``logs``
 198 #. Set ``Credentials`` to the ``logs`` user created in the Credentials System
 199
 200 :Required: This file MUST exist if using log archiving.
 201 :type: Maven settings.xml
 202
 203 .. code-block:: xml
 204
 205    <?xml version="1.0" encoding="UTF-8"?>
 206    <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
 207              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 208              xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
 209    </settings>
 210
 211 .. note::
 212
 213    This example is the default boilerplate generated by Jenkins with
 214    the comments stripped out. We can also use the default generated by Jenkins
 215    without modifying it.
 216
 217 .. _packer-cloud-env:
 218
 219 packer-cloud-env
 220 ----------------
 221
 222 Cloud environment configuration variables for Packer jobs. These can
 223 contain credentials and configuration for whichever clouds packer jobs
 224 are using.
 225
 226 :Required: This file MUST exist to use packer jobs.
 227 :type: Json file
 228
 229 .. code-block:: json
 230
 231    {
 232      "cloud_auth_url": "https://auth.vexxhost.net/v3/",
 233      "cloud_tenant": "TENANT_ID",
 234      "cloud_user": "CLOUD_USERNAME",
 235      "cloud_pass": "CLOUD_PASSWORD",
 236      "cloud_network": "CLOUD_NETWORK",
 237      "ssh_proxy_host": ""
 238    }
 239
 240 .. _jenkins-ci-jobs:
 241
 242 Jenkins CI Jobs
 243 ===============
 244
 245 .. _jenkins-cfg-merge:
 246
 247 jenkins-cfg-merge
 248 -----------------
 249
 250 This job manages Jenkins Global configuration. Refer to
 251 the :ref:`CI Documentation <lf-global-jjb-jenkins-cfg-merge>` for job
 252 configuration details.
 253
 254 .. _log-archiving:
 255
 256 Log Archiving
 257 =============
 258
 259 The logs account requires a Maven Settings file created called
 260 **jenkins-log-archives-settings** with a server ID of **logs** containing the
 261 credentials for the logs user in Nexus.