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