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