Fix: Remove recursive vars for release jobs
[releng/global-jjb.git] / 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 global-jjb
108       cd global-jjb
109       git checkout $GLOBAL_JJB_VERSION
110       cd ..
111
112       # Setup symlinks
113       mkdir -p jjb/global-jjb
114       ln -s ../../global-jjb/jenkins-init-scripts jjb/global-jjb/jenkins-init-scripts
115       ln -s ../../global-jjb/shell jjb/global-jjb/shell
116       ln -s ../../global-jjb/jjb jjb/global-jjb/jjb
117       git add jjb/global-jjb
118
119       git commit -sm "Install global-jjb $GLOBAL_JJB_VERSION"
120
121    .. note::
122
123       We are purposely using github for production deploys of global-jjb so that
124       uptime of LF Gerrit does not affect projects using global-jjb. In a test
125       environment we can use
126       https://gerrit.linuxfoundation.org/infra/releng/global-jjb if desired.
127
128 #. Setup ``jjb/defaults.yaml``
129
130    Create and configure the following parameters in the
131    ``jjb/defaults.yaml`` file as described in the
132    `defaults.yaml configuration docs <defaults-yaml>`.
133
134    Once configured commit the modifications:
135
136    .. code-block:: bash
137
138       git add jjb/defaults.yaml
139       git commit -sm "Setup defaults.yaml"
140
141 #. Push patches to Gerrit / GitHub using your favourite push method
142
143 At this point global-jjb installation is complete in the :term:`ci-management`
144 repo and is ready for use.
145
146 .. _deploy-ci-jobs:
147
148 Deploy ci-jobs
149 ==============
150
151 The CI job group contains jobs that should deploy in all LF
152 Jenkins infra. The minimal configuration to deploy the
153 **{project-name}-ci-jobs** job group as defined in **lf-ci-jobs.yaml** is as
154 follows:
155
156 jjb/ci-management/ci-management.yaml:
157
158 .. code-block:: yaml
159
160    - project:
161        name: ci-jobs
162
163        jobs:
164          - '{project-name}-ci-jobs'
165
166        project: ci-management
167        project-name: ci-management
168        build-node: centos7-builder-2c-1g
169
170 **Required parameters**:
171
172 :project: The project repo as defined in source control.
173 :project-name: A custom name to call the job in Jenkins.
174 :build-node: The name of the builder to use when building (Jenkins label).
175
176 **Optional parameters**:
177
178 :branch: The git branch to build from. (default: master)
179 :jjb-version: The version of JJB to install in the build minion. (default:
180     <defined by the global-jjb project>)
181
182 .. _deploy-packer-jobs:
183
184 Deploy packer-jobs
185 ==================
186
187 The packer job group contains jobs to build custom minion images. The minimal
188 configuration needed to deploy the packer jobs is as follows which deploys the
189 **{project-name}-packer-jobs** job group as defined in **lf-ci-jobs.yaml**.
190
191 jjb/ci-management/packer.yaml:
192
193 .. code-block:: yaml
194
195    - project:
196        name: packer-builder-jobs
197
198        jobs:
199          - '{project-name}-packer-jobs'
200
201        project: ci-management
202        project-name: ci-management
203        branch: master
204        build-node: centos7-builder-2c-1g
205
206        platforms:
207          - centos
208          - ubuntu-16.04
209
210        templates: builder
211
212    - project:
213        name: packer-docker-jobs
214
215        jobs:
216          - '{project-name}-packer-jobs'
217
218        project: ci-management
219        project-name: ci-management
220        branch: master
221        build-node: centos7-builder-2c-1g
222
223        templates: docker
224
225        platforms:
226          - centos
227          - ubuntu-16.04
228
229 **Required parameters**:
230
231 :project: The project repo as defined in source control.
232 :project-name: A custom name to call the job in Jenkins.
233 :build-node: The name of the builder to use when building (Jenkins label).
234 :platforms: A list of supported platforms.
235 :templates: A list of templates to build. We recommend setting one template per
236     ``project`` section so that we can control which platforms to build for
237     specific templates.
238
239 **Optional parameters**:
240
241 :branch: The git branch to build from. (default: master)
242 :packer-version: The version of packer to install in the build minion,
243     when packer is not available. (default: <defined by global-jjb>)