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_allowlist: 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_allowlist:
  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' **Managed Files** configuration (eg: https://jenkins.example.org/configfiles/index).
 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 .. _clouds-yaml:
 123
 124 clouds-yaml
 125 -----------
 126
 127 Needed by ``openstack client`` and ``packer`` to fetch OpenStack
 128 credentials and configuration. This file is OpenStack's `clouds.yaml
 129 <https://docs.openstack.org/python-openstackclient/pike/configuration/index.html>`_
 130 file.
 131
 132 :Optional: Needed for jobs that use ``openstack client``. ``packer`` if
 133     building against OpenStack infra.
 134 :type: Custom file
 135
 136 Create a **Custom file** with contents:
 137
 138 .. code-block:: yaml
 139
 140    clouds:
 141    vex:
 142     auth:
 143       project_name: OS_PROJECT_NAME
 144       username: OS_USERNAME
 145       password: OS_PASSWORD
 146       auth_url: 'https://auth.vexxhost.net/v3/'
 147       user_domain_name: Default
 148       project_domain_name: Default
 149     region_name: ca-ymq-1
 150
 151 .. warning::
 152
 153    If using packer 1.3.0 make sure that the clouds.yaml **profile**
 154    configuration is **NOT** configured. Using **profile** causes packer to look
 155    for another file called ``clouds-public.yaml`` for configuration.
 156
 157
 158 .. _pipconf:
 159
 160 pipconf
 161 -------
 162
 163 This file contains default configuration for the python-pip tool and lives
 164 in $HOME/.config/pip/pip.conf. Documentation for pip.conf is available via the
 165 `pip project <https://pip.readthedocs.io/en/stable/user_guide/#configuration>`_.
 166
 167 :Required: This file MUST exist. An empty file is acceptable if a
 168     proxy is not available for the project.
 169 :type: Custom file
 170
 171 Create a **Custom file** with contents:
 172
 173 .. code-block:: ini
 174
 175    [global]
 176    timeout = 60
 177    index-url = https://nexus3.opendaylight.org/repository/PyPi/simple
 178
 179 .. _jjbini:
 180
 181 jjbini
 182 ------
 183
 184 This file contains the Jenkins Job Builder `configuration
 185 <https://jenkins-job-builder.readthedocs.io/en/latest/execution.html#configuration-file>`_
 186 for :doc:`jjb/lf-ci-jobs`.
 187
 188 :Required: This file MUST exist.
 189 :type: Custom file
 190
 191 Create a **Custom file** with contents:
 192
 193 .. code-block:: ini
 194
 195     [job_builder]
 196     ignore_cache=True
 197     keep_descriptions=False
 198     include_path=.:scripts:~/git/
 199     recursive=True
 200
 201     [jenkins]
 202     user=jenkins-jobbuilder
 203     password=1234567890abcdef1234567890abcdef
 204     url=https://jenkins.example.org
 205     query_plugins_info=False
 206
 207     [production]
 208     user=jenkins-jobbuilder
 209     password=1234567890abcdef1234567890abcdef
 210     url=https://jenkins.example.org
 211     query_plugins_info=False
 212
 213     [sandbox]
 214     user=jenkins-jobbuilder
 215     password=1234567890abcdef1234567890abcdef
 216     url=https://jenkins.example.org/sandbox
 217     query_plugins_info=False
 218
 219 The last 2 sections are for the ``jenkins-cfg`` job use, they should match the
 220 ``silo`` names for the respective Jenkins systems, typically ``production`` and
 221 ``sandbox``.
 222
 223 .. _jenkins-log-archives-settings:
 224
 225 jenkins-log-archives-settings
 226 -----------------------------
 227
 228 See :ref:`lf-infra-ship-logs` for usage. If not archiving logs then keep this
 229 file with default settings, global-jjb needs the file to exist to function.
 230
 231 Requires a *credential* named 'logs' of type 'Username and Password' created in
 232 the Jenkins Credentials system.
 233
 234 #. Add Server Credentials
 235 #. Set ``ServerId`` to ``logs``
 236 #. Set ``Credentials`` to the ``logs`` user created in the Credentials System
 237
 238 :Required: This file MUST exist if using log archiving.
 239 :type: Maven settings.xml
 240
 241 .. code-block:: xml
 242
 243    <?xml version="1.0" encoding="UTF-8"?>
 244    <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
 245              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 246              xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
 247    </settings>
 248
 249 .. note::
 250
 251    This example is the default boilerplate generated by Jenkins with
 252    the comments stripped out. We can also use the default generated by Jenkins
 253    without modifying it.
 254
 255 .. _packer-cloud-env:
 256
 257 packer-cloud-env
 258 ----------------
 259
 260 Cloud environment configuration variables for Packer jobs. These can
 261 contain credentials and configuration for whichever clouds packer jobs
 262 are using.
 263
 264 :Required: This file MUST exist to use packer jobs.
 265 :type: Json file
 266
 267 .. code-block:: json
 268
 269    {
 270      "cloud_auth_url": "https://auth.vexxhost.net/v3/",
 271      "cloud_tenant": "TENANT_ID",
 272      "cloud_user": "CLOUD_USERNAME",
 273      "cloud_pass": "CLOUD_PASSWORD",
 274      "cloud_network": "CLOUD_NETWORK",
 275      "ssh_proxy_host": ""
 276    }
 277
 278 .. _jenkins-ci-jobs:
 279
 280 Jenkins CI Jobs
 281 ===============
 282
 283 .. _jenkins-cfg-merge:
 284
 285 jenkins-cfg-merge
 286 -----------------
 287
 288 This job manages Jenkins Global configuration. Refer to
 289 the :ref:`CI Documentation <lf-global-jjb-jenkins-cfg-merge>` for job
 290 configuration details.
 291
 292 .. _log-archiving:
 293
 294 Log Archiving
 295 =============
 296
 297 The logs account requires a Maven Settings file created called
 298 **jenkins-log-archives-settings** with a server ID of **logs** containing the
 299 credentials for the logs user in Nexus.