X-Git-Url: https://gerrit.linuxfoundation.org/infra/gitweb?a=blobdiff_plain;f=docs%2Fconfiguration.rst;h=239ee6af244244b029a18c7ae482df5eaa86281d;hb=b9d610a9e522d71a89d2daeb6f71b2bc2a71cdf7;hp=af98c6e22f0518248c9f5203f18052b6100a470f;hpb=757650c835599c0aa4fe62ed99f05eab324c6f37;p=releng%2Fglobal-jjb.git diff --git a/docs/configuration.rst b/docs/configuration.rst index af98c6e2..239ee6af 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -1,15 +1,106 @@ -.. _global-jjb-configuration: - ############# Configuration ############# +.. _defaults-yaml: + +defaults.yaml +============= + +This file lives in the ci-management repo typically under the path +``jjb/defaults.yaml``. The purpose of this file is to store default variable +values used by global-jjb templates. + +**Required** + +:jenkins-ssh-credential: The name of the Jenkins Credential to + use for ssh connections. (ex: jenkins-ssh) + +:lftools-version: Version of lftools to install. Can be a specific version + like '0.6.1' or a `PEP-440 definition `_ + For example `<1.0.0` or `>=1.0.0,<2.0.0`. + +:mvn-site-id: Maven Server ID from settings.xml containing the credentials + to push to a Maven site repository. + +:mvn-staging-id: Maven Server ID from settings.xml containing the credentials + to push to a Maven staging repository. + +**Gerrit required parameters**: + +:gerrit-server-name: The name of the Gerrit Server as defined in Gerrit + Trigger global configuration. (ex: Primary) + +**GitHub required parameters**: + +:git-url: Set this to the base URL of your GitHub repo. In + general this should be https://github.com. If you are using + GitHub Enterprise, or some other GitHub-style system, then it + should be whatever your installation base URL is. This sets a job + property that GitHub Pull Request Builder requires to work. + Note that this is the web url to your project: (eg. https://github.com/$ORG/$PROJECT) + +:git-clone-url: This is the clone prefix used by GitHub jobs. + Set this to either the same base url as **git-url**, or to + 'git@github.com:' including the trailing ':'. Determined + by your clone method (https or git). + +:github-org: The name of the GitHub organization interpolated + into the scm config. + +:github_pr_org: The name of the GitHub organization. All members + of this organization will be able to trigger jobs. + +:github_pr_allowlist: List of GitHub members you wish to be able to + trigger jobs. + +:github_pr_admin_list: List of GitHub members that will have admin + privileges on the jobs. + +Example Gerrit Infra: + +.. code-block:: yaml + + - defaults: + name: global + + # lf-infra defaults + jenkins-ssh-credential: jenkins-ssh + gerrit-server-name: OpenDaylight + lftools-version: '<1.0.0' + mvn-site-id: opendaylight-site + mvn-staging-id: opendaylight-staging + +Example GitHub Infra: + +.. code-block:: yaml + + - defaults: + name: global + + # lf-infra defaults + jenkins-ssh-credential: jenkins-ssh + github-org: lfit + github_pr_allowlist: + - jpwku + - tykeal + - zxiiro + github_pr_admin_list: + - tykeal + lftools-version: '<1.0.0' + mvn-site-id: opendaylight-site + mvn-staging-id: opendaylight-staging + +.. _jenkins-files: + Jenkins Files ============= global-jjb makes use of the Jenkins Config File Provider plugin to provide some default configurations for certain tools. This section details the files to -define in Jenkins' **Manage Files** configuration. +define in Jenkins' **Managed Files** configuration (eg: https://jenkins.example.org/configfiles/index). + +.. _npmrc: npmrc ----- @@ -19,30 +110,190 @@ Documentation for npmrc is available via the `npm project `_. :Required: This file MUST exist. An empty file is acceptable if a -proxy is not available for the project. + proxy is not available for the project. :type: Custom file -Create a "Custom file" with contents: +Create a **Custom file** with contents: -.. code:: +.. code-block:: ini registry = https://nexus.opendaylight.org/content/repositories/npmjs/ -pip.conf --------- +.. _clouds-yaml: + +clouds-yaml +----------- + +Needed by ``openstack client`` and ``packer`` to fetch OpenStack +credentials and configuration. This file is OpenStack's `clouds.yaml +`_ +file. + +:Optional: Needed for jobs that use ``openstack client``. ``packer`` if + building against OpenStack infra. +:type: Custom file + +Create a **Custom file** with contents: + +.. code-block:: yaml + + clouds: + vex: + auth: + project_name: OS_PROJECT_NAME + username: OS_USERNAME + password: OS_PASSWORD + auth_url: 'https://auth.vexxhost.net/v3/' + user_domain_name: Default + project_domain_name: Default + region_name: ca-ymq-1 + +.. warning:: + + If using packer 1.3.0 make sure that the clouds.yaml **profile** + configuration is **NOT** configured. Using **profile** causes packer to look + for another file called ``clouds-public.yaml`` for configuration. + + +.. _pipconf: + +pipconf +------- This file contains default configuration for the python-pip tool and lives in $HOME/.config/pip/pip.conf. Documentation for pip.conf is available via the `pip project `_. :Required: This file MUST exist. An empty file is acceptable if a -proxy is not available for the project. + proxy is not available for the project. :type: Custom file -Create a "Custom file" with contents: +Create a **Custom file** with contents: -.. code:: +.. code-block:: ini [global] timeout = 60 index-url = https://nexus3.opendaylight.org/repository/PyPi/simple + +.. _jjbini: + +jjbini +------ + +This file contains the Jenkins Job Builder `configuration +`_ +for :doc:`jjb/lf-ci-jobs`. + +:Required: This file MUST exist. +:type: Custom file + +Create a **Custom file** with contents: + +.. code-block:: ini + + [job_builder] + ignore_cache=True + keep_descriptions=False + include_path=.:scripts:~/git/ + recursive=True + + [jenkins] + user=jenkins-jobbuilder + password=1234567890abcdef1234567890abcdef + url=https://jenkins.example.org + query_plugins_info=False + + [production] + user=jenkins-jobbuilder + password=1234567890abcdef1234567890abcdef + url=https://jenkins.example.org + query_plugins_info=False + + [sandbox] + user=jenkins-jobbuilder + password=1234567890abcdef1234567890abcdef + url=https://jenkins.example.org/sandbox + query_plugins_info=False + +The last 2 sections are for the ``jenkins-cfg`` job use, they should match the +``silo`` names for the respective Jenkins systems, typically ``production`` and +``sandbox``. + +.. _jenkins-log-archives-settings: + +jenkins-log-archives-settings +----------------------------- + +See :ref:`lf-infra-ship-logs` for usage. If not archiving logs then keep this +file with default settings, global-jjb needs the file to exist to function. + +Requires a *credential* named 'logs' of type 'Username and Password' created in +the Jenkins Credentials system. + +#. Add Server Credentials +#. Set ``ServerId`` to ``logs`` +#. Set ``Credentials`` to the ``logs`` user created in the Credentials System + +:Required: This file MUST exist if using log archiving. +:type: Maven settings.xml + +.. code-block:: xml + + + + + +.. note:: + + This example is the default boilerplate generated by Jenkins with + the comments stripped out. We can also use the default generated by Jenkins + without modifying it. + +.. _packer-cloud-env: + +packer-cloud-env +---------------- + +Cloud environment configuration variables for Packer jobs. These can +contain credentials and configuration for whichever clouds packer jobs +are using. + +:Required: This file MUST exist to use packer jobs. +:type: Json file + +.. code-block:: json + + { + "cloud_auth_url": "https://auth.vexxhost.net/v3/", + "cloud_tenant": "TENANT_ID", + "cloud_user": "CLOUD_USERNAME", + "cloud_pass": "CLOUD_PASSWORD", + "cloud_network": "CLOUD_NETWORK", + "ssh_proxy_host": "" + } + +.. _jenkins-ci-jobs: + +Jenkins CI Jobs +=============== + +.. _jenkins-cfg-merge: + +jenkins-cfg-merge +----------------- + +This job manages Jenkins Global configuration. Refer to +the :ref:`CI Documentation ` for job +configuration details. + +.. _log-archiving: + +Log Archiving +============= + +The logs account requires a Maven Settings file created called +**jenkins-log-archives-settings** with a server ID of **logs** containing the +credentials for the logs user in Nexus.