Skip to content

Commit a3ce9bb

Browse files
joostvdgjoostvdg
committed
add docs for jenkins x on openshift
including with bitbucket and lighthouse
1 parent 22a4483 commit a3ce9bb

File tree

6 files changed

+1574
-26
lines changed

6 files changed

+1574
-26
lines changed

‎docs/jenkinsx/lighthouse-bitbucket.md‎

Lines changed: 288 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,288 @@
1+
title: Jenkins X - Lighthouse & Bitbucket
2+
description: Installing Jenkins X using Bitbucket and Lighthouse for environment repositories
3+
4+
# Jenkins X - Lighthouse & Bitbucket
5+
6+
This guide is about using Jenkins X with Lighthouse[^1] as webhook manager and Bitbucket for the environment repositories[^2].
7+
8+
## Run Bitbucket on Kubernetes
9+
10+
Unfortunately, Atlassian doesn't have an officially supported Bitbucket for Kubernetes.
11+
12+
So I've taken the courtesy of creating my own basic configuration - read, ***not*** production ready.
13+
14+
!!! example "service.yaml"
15+
16+
```yaml
17+
apiVersion: v1
18+
kind: Service
19+
metadata:
20+
labels:
21+
app: bitbucket
22+
name: bitbucket
23+
namespace: default
24+
spec:
25+
ports:
26+
- name: http
27+
port: 80
28+
protocol: TCP
29+
targetPort: http
30+
selector:
31+
app: bitbucket
32+
sessionAffinity: None
33+
type: ClusterIP
34+
```
35+
36+
!!! example "ingress.yaml"
37+
38+
I've taken the assumption that your cluster supports Ingress resources (even if its an OpenShift cluster).
39+
40+
```yaml
41+
apiVersion: extensions/v1beta1
42+
kind: Ingress
43+
metadata:
44+
name: bitbucket
45+
namespace: default
46+
spec:
47+
rules:
48+
- host: bitbucket.openshift.example.com
49+
http:
50+
paths:
51+
- backend:
52+
serviceName: bitbucket
53+
servicePort: 80
54+
```
55+
56+
!!! example "stateful-set.yaml"
57+
58+
```yaml
59+
apiVersion: apps/v1
60+
kind: StatefulSet
61+
metadata:
62+
name: bitbucket
63+
namespace: default
64+
spec:
65+
serviceName: "bitbucket"
66+
replicas: 1
67+
selector:
68+
matchLabels:
69+
app: bitbucket
70+
template:
71+
metadata:
72+
labels:
73+
app: bitbucket
74+
spec:
75+
containers:
76+
- name: bitbucket
77+
image: atlassian/bitbucket-server:7.0.0
78+
ports:
79+
- containerPort: 7990
80+
name: http
81+
- containerPort: 7999
82+
name: web
83+
volumeMounts:
84+
- name: data
85+
mountPath: /var/atlassian/application-data/bitbucket
86+
volumeClaimTemplates:
87+
- metadata:
88+
name: data
89+
spec:
90+
accessModes: [ "ReadWriteOnce" ]
91+
resources:
92+
requests:
93+
storage: 5Gi
94+
```
95+
96+
## JX Boot Configuration
97+
98+
We use `jx boot`[^3] to install Jenkins X.
99+
If we want to use Bitbucket for the environment repositories, we have to use Lighthouse[^1][^4].
100+
101+
In order to jx to install correctly, we have configure several parameters in the `jx-requirements.yml` with specific values.
102+
See the docs for all the possible values[^5].
103+
104+
* **webhook: lighthouse**: we have to set the webhook manager to `lighthouse`, as Prow only works with GitHub
105+
* **environmentGitOwner: jx**: the project in Bitbucket where the repositories need to be created
106+
* **gitKind: bitbucketserver**: the `kind` of git server, in this case `bitbucketserver`, because `bitbucket` refers to [Bitbucket Cloud](https://bitbucket.org/)
107+
* **gitName: bs**: the name for our gitserver configuration
108+
* **gitServer: http://bitbucket.openshift.example.com**: the url to our Bitbucket Server
109+
110+
We also have to set the storage for at least the logs.
111+
If we do not configure the storage for our logs, they will be assumed to be written to github pages of our application.
112+
That is, regardless of where our application resides. So, if you use anything other than GitHub (cloud), you *have* to configure the logs storage.
113+
114+
The easiest solution, is to create a seperate repository for the build logs in your Bitbucket Server project.
115+
116+
```yaml
117+
storage:
118+
logs:
119+
enabled: true
120+
url: "http://bitbucket.openshift.example.com/scm/jx/build-logs.git"
121+
```
122+
123+
If you have forgotten to set the storage before the installation, you can rectify this afterwards via the `jx edit storage` command.
124+
125+
```bash
126+
jx edit storage -c logs --git-url http://bitbucket.openshift.kearos.net/scm/jx/build-logs.git --git-branch master
127+
```
128+
129+
??? example "jx-requirements.yml"
130+
131+
```yaml
132+
bootConfigURL: https://github.com/jenkins-x/jenkins-x-boot-config.git
133+
cluster:
134+
clusterName: rhos11
135+
devEnvApprovers:
136+
- jvandergriendt
137+
environmentGitOwner: jx
138+
gitKind: bitbucketserver
139+
gitName: bs
140+
gitServer: http://bitbucket.openshift.example.com
141+
namespace: jx
142+
provider: kubernetes
143+
registry: docker.io
144+
environments:
145+
- ingress:
146+
domain: openshift.example.com
147+
namespaceSubDomain: -jx.
148+
key: dev
149+
repository: environment-rhos11-dev
150+
- ingress:
151+
domain: staging.openshift.example.com
152+
namespaceSubDomain: ""
153+
key: staging
154+
repository: env-rhos311-staging
155+
- key: production
156+
repository: env-rhos311-prod
157+
gitops: true
158+
ingress:
159+
domain: openshift.example.com
160+
namespaceSubDomain: -jx.
161+
kaniko: true
162+
repository: nexus
163+
secretStorage: local
164+
storage:
165+
logs:
166+
enabled: true
167+
url: "http://bitbucket.openshift.example.com/scm/jx/build-logs.git"
168+
versionStream:
169+
ref: v1.0.361
170+
url: https://github.com/jenkins-x/jenkins-x-versions.git
171+
webhook: lighthouse
172+
```
173+
174+
### Bitbucket API Token
175+
176+
To authenticate with Bitbucket server, Jenkins X needs a API token of a user that has admin permissions.
177+
178+
First, create this user API token in Bitbucket.
179+
You can do so, via `Manage Account`(top right menu) -> `Personal access tokens` -> `Create a token` (top right).
180+
181+
Then use the `jx create token addon `[^6] command to create the API token for Bitbucket server.
182+
Make sure to use the same `--name <NAME>`, as the `gitName` in your `jx-requirements.yml` file.
183+
184+
> Creates a new User Token for an Addon service
185+
186+
For example, lets create the token for my configuration:
187+
188+
```bash
189+
jx create token addon --name bs --url http://bitbucket.openshift.example.com --api-token <API_TOKEN> <USER>
190+
```
191+
192+
This should give the following response.
193+
194+
```bash
195+
Created user <USER> API Token for addon server bs at http://bitbucket.openshift.example.com
196+
```
197+
198+
## Installation
199+
200+
Before running the Jenkins X installation with `jx boot`, make sure you meet the pre-requisites.
201+
202+
### Pre-requisites
203+
204+
* Kubernetes cluster
205+
* cluster admin access to Kubernetes cluster
206+
* Bitbucket server
207+
* Project in Bitbucket server
208+
* API token in Bitbucket server
209+
* API token for Jenkins X in the Kubernetes cluster
210+
211+
Once these are met, we can install Jenkins X via `jx boot`[^3].
212+
213+
### Issue with controllerbuild
214+
215+
A potential issue you can run into, is that the deployment `jenkins-x-controllerbuild` fails to come up.
216+
217+
```bash
218+
could not lock config file //.gitconfig: Permission denied: failed to run 'git config --global --add user.name jenkins-x-bot' command in directory '',
219+
```
220+
221+
The issue here, seems to be some missing configuration, as the the two `/`'s in `//.gitconfig`, give the idea there's supposed to be some folder defined.
222+
223+
A way to solve this, is to ensure we have a home folder git can write into, and tell git where this home folder is.
224+
225+
The image seems to set its working directory to `/home/jenkins`, so lets use that.
226+
In order to tell git where to write its configuration to, we can set the `HOME` environment variable.
227+
228+
So in the `jenkins-x-controllerbuild` deployment, set the HOME environment variable to `/home/jenkins`.
229+
230+
```yaml
231+
- name: HOME
232+
value: /home/jenkins
233+
```
234+
235+
Add folder for `home/jenkins` via volume and volumeMount.
236+
237+
```yaml
238+
volumeMounts:
239+
- mountPath: /home/jenkins
240+
name: jenkinshome
241+
```
242+
243+
```yaml
244+
volumes:
245+
- name: jenkinshome
246+
emptyDir: {}
247+
```
248+
249+
## Errata
250+
251+
### Import & Quickstarts Source Repositories Always HTTPS
252+
253+
When you add applications to Jenkins X, either via the `jx import` or `jx create quickstart` processes, a `SourceRepository` CRD gets created.
254+
255+
This resource will contain the the value `spec.httpCloneURL`. This is used in the Tekton pipelines for cloning the repository.
256+
This `httpCloneURL` is always set to `https://`, even if the repository `url` is `http://`.
257+
258+
To retrieve the existing source repositories, you can do the following:
259+
260+
```bash
261+
kubectl get sourcerepository
262+
```
263+
264+
You can edit a specific source repository via:
265+
266+
```bash
267+
kubectl edit sourcerepository jx-jx-go
268+
```
269+
270+
And if required, change the `https://` into a `http://`.
271+
272+
### PullRequest Updates
273+
274+
Bitbucket Server does not send a specific webhook when there's an update to a branch participating in a PullRequest.
275+
It only sends a generic `Push` event, which does not give Jenkins X the information required to trigger a new build for the specific PullRequest.
276+
277+
Atlassian has recently add this feature in Bitbucket Server `7.0.0`, confirmed by the [March 5th update in this Jira ticket](https://jira.atlassian.com/browse/BSERV-10279).
278+
279+
As of March 2020, this is not yet supported by Jenkins X, nor is it expected at this point in time to find its way into earlier releases (such as 6.x) of Bitbucket server.
280+
281+
## References
282+
283+
[^1]: https://jenkins-x.io/docs/reference/components/lighthouse/
284+
[^2]: https://jenkins-x.io/docs/reference/components/lighthouse/#bitbucket-server
285+
[^3]: https://jenkins-x.io/docs/getting-started/setup/boot/how-it-works/
286+
[^4]: https://jenkins-x.io/docs/getting-started/setup/boot/#bitbucket-server
287+
[^5]: https://jenkins-x.io/docs/reference/config/config/#config.jenkins.io/v1.ClusterConfig
288+
[^6]: https://jenkins-x.io/commands/jx_create_token_addon/

‎docs/jenkinsx/multi-cluster.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
## Multi Cluster
2+
3+
4+
## Namespace & TLS
5+
6+
* get DNS tokens from jx
7+
* get cert/issuer from jx
8+
* `kubectl label namespace jx-staging certmanager.k8s.io/disable-validation="true"`
9+
*

0 commit comments

Comments
 (0)