Skip to content

Commit c16fe68

Browse files
Andrew Pattersonbalasankarc
Andrew Patterson
authored and
balasankarc
committed
Added updating software components instructions
Added documentation on how to upgrade and test software components.
1 parent 7cae36d commit c16fe68

9 files changed

+494
-0
lines changed

‎.gitlab/merge_request_templates/Component upgrade.md

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
<!-- After merging changes to this template, update the `Default description template for merge requests` -->
2+
<!-- found under Settings - General Merge Requests -->
3+
## What does this MR do?
4+
5+
<!-- Briefly describe what this MR is about. -->
6+
7+
%{first_multiline_commit}
8+
9+
## Related issues
10+
11+
<!-- Link related issues below. Insert the issue link or reference after the word "Closes" if merging this should automatically close it. -->
12+
13+
## Checklist
14+
15+
See [Definition of done](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/CONTRIBUTING.md#definition-of-done).
16+
17+
For anything in this list which will not be completed, please provide a reason in the MR discussion.
18+
19+
### Required
20+
21+
- [ ] MR title and description are up to date, accurate, and descriptive.
22+
- [ ] MR targets the appropriate branch.
23+
- [ ] Component test plan copied into MR description.
24+
- [ ] Latest merged results pipeline is green.
25+
- [ ] When ready for review, MR is labeled "~workflow::ready for review" per the [Distribution MR workflow](https://about.gitlab.com/handbook/engineering/development/enablement/systems/distribution/merge_requests.html).
26+
27+
#### For GitLab team members
28+
29+
If you don't have permissions to trigger pipelines for this MR, the reviewer
30+
should trigger these jobs for you during the review process.
31+
32+
- [ ] The manual `Trigger:ee-package` jobs have a green pipeline running against latest commit. To debug QA failures, refer to [Investigate QA failures](https://about.gitlab.com/handbook/engineering/quality/quality-engineering/enablement-saas-platforms-qe-team/distribution/#investigate-qa-failures).
33+
- [ ] If `config/software` or `config/patches` directories are changed, `build-package-on-all-os` job within the `Trigger:ee-package` downstream pipeline succeeded.
34+
- [ ] If you are changing anything SSL related, the `Trigger:package:fips` manual job within the `Trigger:ee-package` downstream pipeline succeeded.
35+
- [ ] If CI/CD configuration is changed, the branch is pushed to [`dev.gitlab.org`](https://dev.gitlab.org/gitlab/omnibus-gitlab) to confirm regular branch builds aren't broken.
36+
37+
### Expected (please provide an explanation if not completing)
38+
39+
- [ ] Test plan indicating conditions for success has been posted and passes.
40+
- [ ] Documentation created or updated.
41+
- [ ] Tests added.
42+
- [ ] Integration tests added to [GitLab QA](https://gitlab.com/gitlab-org/gitlab-qa).
43+
- [ ] Equivalent MR/issue for the [GitLab Chart](https://gitlab.com/gitlab-org/charts/gitlab) opened.
44+
- [ ] Potential values for new configuration settings validated. Formats such as integer `10`, duration `10s`, URI `scheme://user:passwd@host:port` may require quotation or other special handling when rendered in a template and written to a configuration file.
45+
46+
## Test plan
47+
48+
<!--
49+
* Create a test plan file if it does already exist. Refer to
50+
[Upgrading software components](../upgrading-software-component#test-plans) for
51+
details. Consider modifying existing an existing plan to meet new requirements.
52+
53+
* Copy the contents of the test plan here.
54+
-->

‎doc/development/contribute-to-omnibus-gitlab.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
1616

1717
## Common maintenance tasks
1818

19+
- [Upgrading software components](upgrading-software-components.md)
1920
- [Patching upstream software](creating-patches.md)
2021
- [Managing PostgreSQL versions](managing-postgresql-versions.md)
2122
- [Upgrading the bundled Chef version](upgrading-chef.md)

‎doc/development/upgrading-software-components.md

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
---
2+
stage: Systems
3+
group: Distribution
4+
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
5+
---
6+
7+
# Upgrading software components
8+
9+
The Linux package is created from a series of software components, some of which
10+
are developed by GitLab and others which are sourced from free and open source
11+
projects. Software components can be updated individually as new features, bug
12+
fixes, and security vulnerabilities become available.
13+
14+
Software component upgrades can be risky, especially when non-backwards
15+
compatible changes are made. Considering [Semantic versioning](https://semver.org/)], examining changelogs, and examining release
16+
notes can give a sense of the amount of risk involved in an upgrade. In all
17+
cases, upgrades should be thoroughly tested before merging.
18+
19+
The [CNG](https://gitlab.com/gitlab-org/build/CNG) project uses some of these
20+
same software components. Components common to both projects should be updated
21+
in both.
22+
23+
## Types of software components
24+
25+
There are two types of software components used in the Linux package:
26+
27+
- External software components
28+
- Internal software components
29+
30+
### External software components
31+
32+
External software components source is downloaded directly from an external site
33+
or copied from the
34+
[`omnibus-mirror`](https://gitlab.com/gitlab-org/build/omnibus-mirror) repository.
35+
A component can be provided using a `git clone`, extracting from a source
36+
tarball, performing a `gem install` (for Ruby modules), or performing a `pip
37+
install` (for Python modules).
38+
39+
### Internal software components
40+
41+
Internal software component are developed by GitLab and external contributors.
42+
Source for internal software components is downloaded from a project's GitLab
43+
repository. Versions used in a build are set by the Git reference contained in
44+
the project's corresponding `*VERSION` files. These versions can be overridden
45+
by environment variables. For more information, see
46+
[Use specific branches or versions of a GitLab component](../build/team_member_docs.md#use-specific-branches-or-versions-of-a-gitlab-component).
47+
48+
Updates to internal software components are done by merge requests in the
49+
corresponding repository.
50+
51+
## Internal software component update workflow
52+
53+
A typical workflow for updating an internal software component.
54+
55+
### Create a fork/branch
56+
57+
External contributors should create a fork of the
58+
[`gitlab-org/omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab) repository.
59+
60+
Create a new branch from the target branch (usually `master` of the
61+
[`gitlab-org/omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab) repository.
62+
63+
### Modify `config/software/<component.rb>`
64+
65+
1. Find the corresponding configure file for the component that you want to
66+
update in the `config/software` directory. For example
67+
`config/software/prometheus.rb` is used for the Prometheus component.
68+
69+
1. Change the version to the version you want to update to. If applicable, also
70+
change the corresponding `sha256` to the value of the corresponding version
71+
source tarball.
72+
73+
### Add or modify any required patches
74+
75+
The new component version may require:
76+
77+
- Adding new patches.
78+
- Removing existing patches.
79+
- Changing existing patches.
80+
81+
All patch files go in `config/patches/<component name>`. They are then
82+
referenced in the corresponding `config/software/<component name>.rb` file.
83+
Examples can be found at:
84+
85+
- [unzip component](https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/master/config/software/unzip.rb)
86+
- [unzip patches](https://gitlab.com/gitlab-org/omnibus-gitlab/-/tree/master/config/patches/unzip).
87+
88+
### Push branch
89+
90+
Push the branch to the to the upstream repository.
91+
92+
### Create merge request (MR)
93+
94+
Create a merge request using your development branch and the target branch.
95+
96+
### Build
97+
98+
Build the Linux package either:
99+
100+
- Using the CI/CD system.
101+
- Building locally using [Build local Linux package](../build/build_package.md).
102+
103+
You must build on all architectures using the CI/CD system before a merge
104+
request for an updated software component can be accepted.
105+
106+
### Test
107+
108+
Install the resulting Linux package and test the component changes.
109+
110+
## Testing software component updates
111+
112+
### Minimum test requirements
113+
114+
At a minimum, the following tests should be performed when updating a software
115+
component.
116+
117+
- Perform a successful GitLab Enterprise Edition (EE) build on all supported platforms.
118+
- Run `qa-test` CI/CD test job for both GitLab Enterprise Edition and GitLab Community Edition.
119+
- Install and verify that component version has been upgraded.
120+
- Verify basic functionality of the software component.
121+
122+
Additional testing is almost always required and varies depending on the
123+
software component.
124+
125+
### Test plans
126+
127+
Here are test plans for individual components. They are meant to be copied into
128+
the merge request where their execution can be recorded.
129+
130+
Not every component is listed here. Please consider creating a merge request to
131+
add one for a component upgrade that you are working on. Use
132+
`test-plans/upgrade-component-testplan-template.md` as a starting point.
133+
134+
These test plans are not exhaustive. The might need to be supplemented depending
135+
on the degree of change made to the component. Record these additions in the
136+
merge request and consider adding them here. Use the following filename pattern
137+
when creating the test plan file:
138+
139+
```plaintext
140+
upgrade-<component-name>-testplan.md
141+
```
142+
143+
And add a link in `test-plans/index.md`.

‎test-plans/index.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Omnibus GitLab test plans
2+
3+
## Updating components
4+
5+
<!-- Keep this list sorted alphabetically. -->
6+
- [golang](upgrade-golang-testplan.md)
7+
- [libre2](upgrade-libre2-testplan.md)
8+
- [Mattermost](upgrade-mattermost-testplan.md)
9+
- [redis](upgrade-redis-testplan.md)

‎test-plans/upgrade-component-testplan-template.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# `<component name>` component upgrade test plan
2+
3+
<!-- Copy and paste the following into your MR description. -->
4+
## Test plan
5+
6+
<!-- -
7+
Add the component test-plan here. Use "[ ]" for each step/task to be completed.
8+
9+
At a minimum, the following test should be run:
10+
11+
- [ ] Performed a successful GitLab Enterprise Edition (EE) build on all supported platforms.
12+
- [ ] Ran `qa-test` CI/CD test job for both GitLab Enterprise Edition and GitLab Community Edition.
13+
- [ ] Installed and verified that the component version has been upgraded.
14+
- [ ] Verified basic functionality of the software component.
15+
-->

‎test-plans/upgrade-golang-testplan.md

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# `golang` component upgrade test plan
2+
3+
<!-- Copy and paste the following into your MR description. -->
4+
## Test plan
5+
6+
- [ ] QA tests passed for FIPS and non FIPS builds
7+
- [ ] Confirmed build was done with go 1.19 `strings /opt/gitlab/embedded/bin/gitaly | grep 'go1\.' | tail -1`
8+
- [ ] Confirmed Omnibus-built services that are owned by distribution are working
9+
- [ ] prometheus - (is scraping metrics)
10+
11+
```shell
12+
curl 'localhost:9090/api/v1/query?query=up'
13+
```
14+
15+
- [ ] pgbouncer exporter - (metrics endpoint returns data)
16+
17+
1. Configured pgbouncer using https://docs.gitlab.com/ee/administration/postgresql/pgbouncer.html
18+
1. Run:
19+
20+
```shell
21+
curl http://localhost:9188/metrics
22+
```
23+
24+
- [ ] redis-exporter - (metrics endpoint returns data)
25+
26+
```shell
27+
curl http://localhost:9121/metrics
28+
```
29+
30+
- [ ] postgres-exporter - (metrics endpoint returns data)
31+
32+
```shell
33+
curl http://localhost:9187/metrics
34+
```
35+
36+
- [ ] node-exporter - (metrics endpoint returns data)
37+
38+
```shell
39+
curl http://localhost:9100/metrics
40+
```
41+
42+
- [ ] alertmanager - (test trigger an alert)
43+
44+
1. Set `prometheus['listen_address'] = '0.0.0.0:9090'` in `/etc/gitlab/gitlab.rb` and run `sudo gitlab-ctl reconfigure`.
45+
1. Shut down `gitaly` service:
46+
47+
```shell
48+
gitlab-ctl stop gitaly
49+
```
50+
51+
1. Wait 5 minutes and check prometheus console `http://<gitlab host>:9090/alerts?search=` for service down alert.
52+
1. Start `gitaly` service:
53+
54+
```shell
55+
gitlab-ctl start gitaly
56+
```
57+
58+
1. Wait 5 minutes and check prometheus console `http://<gitlab host>:9090/alerts?search=` for service back up.

‎test-plans/upgrade-libre2-testplan.md

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# libre2 component upgrade test plan
2+
3+
## Test plan
4+
5+
- [ ] Green pipeline on gitlab.com including `Trigger:ce-package` and `Trigger:ee-package`. These pipelines should have ran their respective `build-package-on-all-os` pipelines.
6+
- [ ] Verified build options for CC and CXX are correct.
7+
-[ ] CentOS 7
8+
-[ ] Modern OS, e.g Ubuntu jammy.
9+
- [ ] Installed package or container. Verified no installation issues.
10+
-[ ] CentOS 7
11+
-[ ] Modern OS
12+
- Ran ldd on re2 gem and verified correct `libre2`` library is used.
13+
-[ ] CentOS 7
14+
-[ ] Modern OS
15+
- [ ] Ran `re2` Spec test to verify correct ruby integration:
16+
17+
```shell
18+
docker run -it registry.gitlab.com/gitlab-org/gitlab-omnibus-builder/debian_10:4.10.0 bash
19+
cd /tmp
20+
git clone -b 2023-03-01 https://github.com/google/re2 google-re2
21+
git clone -b v1.6.0 https://github.com/mudge/re2.git
22+
cd google-re2
23+
make install
24+
cd ..
25+
cd re2
26+
bundle install
27+
bundle exec rake compile
28+
bundle exec rspec
29+
```
30+
31+
- [ ] Ran gitlab-rails console smoke test
32+
- [ ] CentOS 7
33+
- [ ] Modern OS
34+
35+
```ruby
36+
irb(main):005:0> regex = RE2('\(iP.+; CPU .*OS (\d+)[_\d]*.*\) AppleWebKit\/')
37+
=> #<RE2::Regexp /\(iP.+; CPU .*OS (\d+)[_\d]*.*\) AppleWebKit\//>
38+
irb(main):006:0> regex.match?('foo')
39+
=> false
40+
irb(main):017:0> regex.match?("Mozilla/5.0 (iPhone; CPU iPhone OS 12_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/12.0 Mobile/15E148 Safari/604.1")
41+
=> true
42+
```

0 commit comments

Comments
 (0)