docs/install.rst

   1 #######
   2 Install
   3 #######
   4
   5 global-jjb requires configuration in 2 places; ``Jenkins`` and the
   6 :term:`ci-management` repository.
   7
   8 .. _jenkins-config:
   9
  10 Jenkins configuration
  11 =====================
  12
  13 On the Jenkins side, we need to prep ``environment variables`` and
  14 ``plugins`` required by the jobs in global-jjb before we can start our first
  15 jobs.
  16
  17 .. _jenkins-install-plugins:
  18
  19 Install Jenkins plugins
  20 -----------------------
  21
  22 Install the following required Jenkins plugins and any optional ones as
  23 necessary by the project.
  24
  25 **Required**
  26
  27 - `Config File Provider <https://plugins.jenkins.io/config-file-provider>`_
  28 - `Description Setter <https://plugins.jenkins.io/description-setter>`_
  29 - `Environment Injector Plugin <https://plugins.jenkins.io/envinject>`_
  30 - `Git plugin <https://plugins.jenkins.io/git>`_
  31 - `Post Build Script <https://plugins.jenkins.io/postbuildscript>`_
  32 - `SSH Agent <https://plugins.jenkins.io/ssh-agent>`_
  33 - `Workspace Cleanup <https://plugins.jenkins.io/ws-cleanup>`_
  34
  35 **Required for Gerrit connected systems**
  36
  37 - `Gerrit Trigger <https://plugins.jenkins.io/gerrit-trigger>`_
  38
  39 **Required for GitHub connected systems**
  40
  41 - `GitHub plugin <https://plugins.jenkins.io/github>`_
  42 - `GitHub Pull Request Builder <https://plugins.jenkins.io/ghprb>`_
  43
  44 **Optional**
  45
  46 - `Mask Passwords <https://plugins.jenkins.io/mask-passwords>`_
  47 - `MsgInject <https://plugins.jenkins.io/msginject>`_
  48 - `OpenStack Cloud <https://plugins.jenkins.io/openstack-cloud>`_
  49 - `Timestamper <https://plugins.jenkins.io/timestamper>`_
  50
  51 .. _jenkins-envvars:
  52
  53 Environment Variables
  54 ---------------------
  55
  56 The :ref:`lf-global-jjb-jenkins-cfg-merge` job can manage environment variables
  57 job but we must first bootstrap them in Jenkins so that the job can run and
  58 take over.
  59
  60 **Required**::
  61
  62     GIT_URL=ssh://jenkins-$SILO@git.opendaylight.org:29418
  63     JENKINS_HOSTNAME=jenkins092
  64     NEXUS_URL=https://nexus.opendaylight.org
  65     SILO=production
  66     SONAR_URL=https://sonar.opendaylight.org
  67
  68 **Gerrit**::
  69
  70     GERRIT_URL=https://git.opendaylight.org/gerrit
  71
  72 **GitHub**::
  73
  74     GIT_URL=https://github.com
  75     GIT_CLONE_URL=git@github.com:
  76
  77 .. note::
  78
  79    Use ``GIT_CLONE_URL`` for GitHub projects as this will be different from the
  80    URL used in the properties configuration.
  81
  82 **Optional**::
  83
  84     LOGS_SERVER=https://logs.opendaylight.org
  85
  86 Steps
  87
  88 #. Navigate to https://jenkins.example.org/configure
  89 #. Configure the environment variables as described above
  90 #. Configure the same environment variables in the :term:`ci-management` repo
  91
  92 .. _jenkins-ci-management:
  93
  94 ci-management
  95 =============
  96
  97 :term:`ci-management` is a git repository containing :term:`JJB` configuration
  98 files for Jenkins Jobs. Deploying Global JJB here as a submodule allows us easy
  99 management to install, upgrade, and rollback changes via git tags. Install
 100 Global JJB as follows:
 101
 102 #. Install Global JJB
 103
 104    .. code-block:: bash
 105
 106       GLOBAL_JJB_VERSION=v0.1.0
 107       git submodule add https://github.com/lfit/releng-global-jjb.git
 108       cd global-jjb
 109       git checkout $GLOBAL_JJB_VERSION
 110       cd ..
 111       git add jjb/global-jjb
 112
 113       # Setup symlinks
 114       mkdir jjb/global-jjb
 115       ln -s ../../global-jjb/shell jjb/global-jjb/shell
 116       ln -s ../../global-jjb/jjb jjb/global-jjb/jjb
 117       ln -s ../../global-jjb/jenkins-admin jjb/global-jjb/jenkins-admin
 118       ln -s ../../global-jjb/jenkins-init-scripts jjb/global-jjb/jenkins-init-scripts
 119       git add jjb/global-jjb
 120
 121       git commit -sm "Install global-jjb $GLOBAL_JJB_VERSION"
 122
 123    .. note::
 124
 125       We are purposely using github for production deploys of global-jjb so that
 126       uptime of LF Gerrit does not affect projects using global-jjb. In a test
 127       environment we can use
 128       https://gerrit.linuxfoundation.org/infra/releng/global-jjb if desired.
 129
 130 #. Setup ``jjb/defaults.yaml``
 131
 132    Create and configure the following parameters in the
 133    ``jjb/defaults.yaml`` file as described in the
 134    `defaults.yaml configuration docs <defaults-yaml>`.
 135
 136    Once configured commit the modifications:
 137
 138    .. code-block:: bash
 139
 140       git add jjb/defaults.yaml
 141       git commit -sm "Setup defaults.yaml"
 142
 143 #. Push patches to Gerrit / GitHub using your favourite push method
 144
 145 At this point global-jjb installation is complete in the :term:`ci-management`
 146 repo and is ready for use.
 147
 148 .. _deploy-ci-jobs:
 149
 150 Deploy ci-jobs
 151 ==============
 152
 153 The CI job group contains jobs that should deploy in all LF
 154 Jenkins infra. The minimal configuration to deploy the
 155 **{project-name}-ci-jobs** job group as defined in **lf-ci-jobs.yaml** is as
 156 follows:
 157
 158 jjb/ci-management/ci-management.yaml:
 159
 160 .. code-block:: yaml
 161
 162    - project:
 163        name: ci-jobs
 164
 165        jobs:
 166          - '{project-name}-ci-jobs'
 167
 168        project: ci-management
 169        project-name: ci-management
 170        build-node: centos7-builder-2c-1g
 171
 172 **Required parameters**:
 173
 174 :project: The project repo as defined in source control.
 175 :project-name: A custom name to call the job in Jenkins.
 176 :build-node: The name of the builder to use when building (Jenkins label).
 177
 178 **Optional parameters**:
 179
 180 :branch: The git branch to build from. (default: master)
 181 :jjb-version: The version of JJB to install in the build minion. (default:
 182     <defined by the global-jjb project>)
 183
 184 .. _deploy-packer-jobs:
 185
 186 Deploy packer-jobs
 187 ==================
 188
 189 The packer job group contains jobs to build custom minion images. The minimal
 190 configuration needed to deploy the packer jobs is as follows which deploys the
 191 **{project-name}-packer-jobs** job group as defined in **lf-ci-jobs.yaml**.
 192
 193 jjb/ci-management/packer.yaml:
 194
 195 .. code-block:: yaml
 196
 197    - project:
 198        name: packer-builder-jobs
 199
 200        jobs:
 201          - '{project-name}-packer-jobs'
 202
 203        project: ci-management
 204        project-name: ci-management
 205        branch: master
 206        build-node: centos7-builder-2c-1g
 207
 208        platforms:
 209          - centos
 210          - ubuntu-16.04
 211
 212        templates: builder
 213
 214    - project:
 215        name: packer-docker-jobs
 216
 217        jobs:
 218          - '{project-name}-packer-jobs'
 219
 220        project: ci-management
 221        project-name: ci-management
 222        branch: master
 223        build-node: centos7-builder-2c-1g
 224
 225        templates: docker
 226
 227        platforms:
 228          - centos
 229          - ubuntu-16.04
 230
 231 **Required parameters**:
 232
 233 :project: The project repo as defined in source control.
 234 :project-name: A custom name to call the job in Jenkins.
 235 :build-node: The name of the builder to use when building (Jenkins label).
 236 :platforms: A list of supported platforms.
 237 :templates: A list of templates to build. We recommend setting one template per
 238     ``project`` section so that we can control which platforms to build for
 239     specific templates.
 240
 241 **Optional parameters**:
 242
 243 :branch: The git branch to build from. (default: master)
 244 :packer-version: The version of packer to install in the build minion,
 245     when packer is not available. (default: <defined by global-jjb>)