opendev/system-config
Code Issues Proposed changes

Merge "gerrit docs: cleanup and use shell-session"

Browse Source
This commit is contained in:
Zuul 2022-06-24 05:56:55 +00:00 committed by Gerrit Code Review
commit 2599cdccb8
2 changed files with 118 additions and 131 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

202
doc/source/gerrit.rst
View File

@ -45,26 +45,6 @@ The Gerrit installation at /home/gerrit2 is located on a Cinder
volume. See :ref:`cinder` for details on volume management. Note
that SSD volumes are used (and they have a minimum size of 100G).
Gerrit Configuration
--------------------
Most of Gerrit's configuration is in configuration files or Git
repositories (and in our case, managed by Puppet), but a few items
must be configured in the database. The following is a record of
these changes:
Add information about the CLA:
.. code-block:: mysql
sudo -u root
mysql
use reviewdb;
insert into contributor_agreements values (
'Y', 'Y', 'Y', 'ICLA',
'OpenStack Individual Contributor License Agreement',
'static/cla.html', 2);
Groups
------
@ -99,9 +79,11 @@ Once you've created your groups you should create the
``openstack-project-creator`` account by hand (the account name is
referenced from
:git_file:`playbooks/roles/gerrit/templates/projects.ini.j2`)
using::
using
cat $pubkey | ssh -p 29418 $USER@$HOST gerrit create-account \
.. code-block:: shell-session
$ cat $pubkey | ssh -p 29418 $USER@$HOST gerrit create-account \
--group "'Project Bootstrappers'" \
--group Administrators \
--full-name "'Project Creator'" \
@ -123,10 +105,12 @@ with instructions to use Gerrit.
These are both handled automatically by :ref:`jeepyb`.
Note that the user running Gerrit will need to accept the GitHub host
keys. e.g.::
keys. e.g.
sudo su - gerrit2
ssh github.com
.. code-block:: shell-session
$ sudo su - gerrit2
$ ssh github.com
Troubleshooting
---------------
@ -138,9 +122,9 @@ be created, but will appear empty. When trying replication from Gerrit,
it will show a `Permission denied` error when trying to push content.
To solve that, following steps are needed:
#. Login into github.com, using openstack-project-creator user.
#. Navigate to the failed repository, and enter on Settings > Collaborators
& teams option.
#. Login into ``github.com``, using ``openstack-project-creator`` user.
#. Navigate to the failed repository, and enter on ``Settings > Collaborators
& teams`` option.
#. Add Gerrit as Team member to that project.
After the team has been added, project will start replicating successfully
@ -151,17 +135,16 @@ Gerrit IRC Bot
==============
Gerritbot consumes the Gerrit event stream and announces relevant
events on IRC. :ref:`gerritbot` is an openstack-infra project and is
also available on Pypi.
events on IRC. :ref:`gerritbot` is an ``OpenDev`` project and is also
available on Pypi.
Launchpad Bug Integration
=========================
In addition to the hyperlinks provided by the regex in gerrit.config,
In addition to the hyperlinks provided by the regex in ``gerrit.config``,
we use a Gerrit hook to update Launchpad bugs when changes referencing
them are applied. This is managed by the :ref:`jeepyb`
openstack-infra project.
them are applied. This is managed by the :ref:`jeepyb` project.
Storyboard Integration
======================
@ -175,17 +158,10 @@ New Project Creation
====================
Gerrit project creation is now managed through changes to the
openstack/project-config repository. :ref:`jeepyb` handles
``openstack/project-config`` repository. :ref:`jeepyb` handles
automatically creating any new projects defined in the configuration
files.
Local Git Replica
=================
Gerrit replicates all repos to a local directory so that Apache can
serve the anonymous http requests out directly. This is automatically
configured by :ref:`jeepyb`.
.. _acl:
Access Controls
@ -199,7 +175,7 @@ High level goals:
#. Zuul can perform verification (blocking or approving: +/-2).
#. Third Party CI systems can perform informational verification (+/-1).
#. All registered users can create changes.
#. Members of $PROJECT-core group can perform full code review
#. Members of ``$PROJECT-core`` group can perform full code review
(blocking or approving: +/- 2), and submit changes to be merged.
#. Drivers (PTL and delegates) of client library projects should be
able to add tags (which are automatically used to trigger
@ -215,8 +191,8 @@ SSH because it's fast, and it gets syntax checked).
#. Visit ``https://$HOST/#/admin/projects/All-Projects,access`` and click on Edit.
#. Look for the reference to 'refs/meta/config', click on the drop-box
for 'add permission' and choose 'PUSH'.
#. Look for the reference to ``refs/meta/config``, click on the drop-box
for ``add permission`` and choose ``PUSH``.
#. Type in Administrators as the group name
@ -225,22 +201,24 @@ SSH because it's fast, and it gets syntax checked).
#. Click on Save Changes
Then... we need to fetch the All-Projects ACLs, update them, then push the
updates back into Gerrit::
updates back into Gerrit
export USER=$your_gerrit_user
export HOST=$your_gerrit_host
cd $anywhereyoulike
mkdir All-Projects-ACLs
cd All-Projects-ACLs
git init
git remote add gerrit ssh://$USER@$HOST:29418/All-Projects.git
git fetch gerrit +refs/meta/*:refs/remotes/gerrit-meta/*
git checkout -b config remotes/gerrit-meta/config
.. code-block:: shell-session
There will be two interesting files, `groups` and `project.config`.
`groups` contains UUIDs and names of groups that will be referenced
in `project.config`. UUIDs can be found on the group page in Gerrit.
Next, edit `project.config` to look like::
$ export USER=$your_gerrit_user
$ export HOST=$your_gerrit_host
$ cd $anywhereyoulike
$ mkdir All-Projects-ACLs
$ cd All-Projects-ACLs
$ git init
$ git remote add gerrit ssh://$USER@$HOST:29418/All-Projects.git
$ git fetch gerrit +refs/meta/*:refs/remotes/gerrit-meta/*
$ git checkout -b config remotes/gerrit-meta/config
There will be two interesting files, ``groups`` and ``project.config``.
``groups`` contains UUIDs and names of groups that will be referenced
in ``project.config``. UUIDs can be found on the group page in Gerrit.
Next, edit ``project.config`` to look like::
[access "refs/*"]
create = group Project Bootstrappers
@ -355,10 +333,12 @@ the built in groups such as 'Service Users' which may or may not be
present in the initial groups file. You can find the UUID values by navigating
to Admin -> Groups -> Group Name -> General in the Web UI.
Finally, commit the changes and push the config back up to Gerrit::
Finally, commit the changes and push the config back up to Gerrit
git commit -am "Initial All-Projects config"
git push gerrit HEAD:refs/meta/config
.. code-block:: shell-session
$ git commit -am "Initial All-Projects config"
$ git push gerrit HEAD:refs/meta/config
Manual Administrative Tasks
@ -408,9 +388,11 @@ To rename a project:
responding to ssh to ensure the next step can run successfully.
#. Run the ansible rename repos playbook, passing in the path to your yaml
file::
file
sudo ansible-playbook -f 10 /home/zuul/src/opendev.org/opendev/system-config/playbooks/rename_repos.yaml -e repolist=ABSOLUTE_PATH_TO_VARS_FILE
.. code-block:: shell-session
$ sudo ansible-playbook -f 10 /home/zuul/src/opendev.org/opendev/system-config/playbooks/rename_repos.yaml -e repolist=ABSOLUTE_PATH_TO_VARS_FILE
#. :ref:`Force-merge <force-merging-a-change>` the prepared configuration
changes.
@ -429,9 +411,11 @@ To rename a project:
or review servers. It should be a noop.
Developers will either need to re-clone a new copy of the repository,
or manually update their remotes with something like::
or manually update their remotes with something like
git remote set-url origin https://opendev.org/$ORG/$PROJECT
.. code-block:: shell-session
$ git remote set-url origin https://opendev.org/$ORG/$PROJECT
Third-Party Testing Access
@ -441,14 +425,9 @@ The command to add an account for an automated system which gets -1/+1
code verify voting rights (as outlined in :ref:`third-party-testing`)
looks like:
.. code-block:: bash
.. code-block:: shell-session
ssh -p 29418 review.opendev.org "gerrit create-account \
--group 'Third-Party CI' \
--full-name 'Some CI Bot' \
--email ci-bot@third-party.org \
--ssh-key 'ssh-rsa AAAAB3Nz...zaUCse1P ci-bot@third-party.org' \
some-ci-bot"
$ ssh -p 29418 review.opendev.org "gerrit create-account --group 'Third-Party CI' --full-name 'Some CI Bot' --email ci-bot@third-party.org --ssh-key 'ssh-rsa AAAAB3Nz...zaUCse1P ci-bot@third-party.org' some-ci-bot"
Details on the create-account_ command can be found in the Gerrit
API documentation.
@ -476,32 +455,32 @@ The first step to resolve this is to confirm the ID of the unwanted
account, . As an admin user with a HTTP password set, search for the
new account:
..
.. code-block:: shell-session
curl -u you.admin -i -H "Accept: application/json" 'https://review.opendev.org/a/accounts/foo@new.com'
$ curl -u you.admin -i -H "Accept: application/json" 'https://review.opendev.org/a/accounts/foo@new.com'
That will return an ``_acount_id``. For this example, assume it is
``12345``. The user should check in their settings they are *not*
using this account.
Clone ``All-Users`` to modify the account, and checkout the account
config, which is sharded by the last two digits of the account-id.
config, which is sharded by the last two digits of the ``_account_id``.
..
.. code-block:: shell-session
git clone ssh://you.admin@review.opendev.org:29418/All-Users
git fetch refs/users/45/12345
git checkout FETCH_HEAD
$ git clone ssh://you.admin@review.opendev.org:29418/All-Users
$ git fetch origin refs/users/45/12345
$ git checkout FETCH_HEAD
Edit the ``[account]`` section of ``account.conf`` to remove
``preferredEmail`` and have a line ``active = false``. Put your admin
account into ``Project Bootstrappers`` (see :ref:`sysadmin`) and
commit this
..
.. code-block:: shell-session
git commit -m "Make duplicate account inactive" --author <your@email.com>
git push origin HEAD:refs/users/45/12345
$ git commit -m "Make duplicate account inactive" --author <your@email.com>
$ git push origin HEAD:refs/users/45/12345
There will still be an OpenID external ID associated with this now
inactive account. This will prevent adding ``foo@new.com`` to another
@ -509,17 +488,17 @@ account until this is removed.
Check this via the API with
..
.. code-block:: shell-session
curl -u you.admin -i -H "Accept: application/json" https://review.opendev.org/a/accounts/12345/external.ids
$ curl -u you.admin -i -H "Accept: application/json" https://review.opendev.org/a/accounts/12345/external.ids
This will give a json result with an ``identity`` URL like
``"identity":"https://login.ubuntu.com/+id/RaND0m``. Use this to
delete the record with another call
..
.. code-block:: shell-session
curl -XPOST -u you.admin -i -H "Content-Type: application/json" -d '["https://login.ubuntu.com/+id/RaND0m"]' https://review.opendev.org/a/accounts/12345/external.ids:delete
$ curl -XPOST -u you.admin -i -H "Content-Type: application/json" -d '["https://login.ubuntu.com/+id/RaND0m"]' https://review.opendev.org/a/accounts/12345/external.ids:delete
The user should now be able to add ``foo@new.com`` to their old
account.
@ -534,40 +513,47 @@ must follow that steps:
members can be found on: https://review.opendev.org/#/admin/groups/270,members
That will give you the name and email of all members. Then you can get the matching
numerical account ID with the help of REST API::
numerical account ID with the help of REST API
curl -i -H "Accept: application/json" --digest --user <<gerrit_user>>:<<http_pass>> -X GET https://review.opendev.org/a/accounts/{email}
.. code-block:: shell-session
$ curl -i -H "Accept: application/json" --digest --user <<gerrit_user>>:<<http_pass>> -X GET https://review.opendev.org/a/accounts/{email}
This will return a JSON dictionary, that will contain _account_id field.
2. Mark the account as inactive using gerrit ssh api, with::
2. Mark the account as inactive using gerrit ssh api, with
ssh -p 29418 review.opendev.org gerrit set-account --inactive {account-id}
.. code-block:: shell-session
Alternatively you can use REST API, sending a DELETE for::
$ ssh -p 29418 review.opendev.org gerrit set-account --inactive {account-id}
curl -i -H "Accept: application/json" --digest --user <<gerrit_user>>:<<http_pass>> -X DELETE https://review.opendev.org/a/accounts/{account-id}/active
Alternatively you can use REST API, sending a DELETE for
3. Check if there are active gerrit ssh connections::
.. code-block:: shell-session
ssh -p 29418 review.opendev.org gerrit show-connections -n | grep {account-id}
$ curl -i -H "Accept: application/json" --digest --user <<gerrit_user>>:<<http_pass>> -X DELETE https://review.opendev.org/a/accounts/{account-id}/active
And kill all of them with subsequent::
3. Check if there are active gerrit ssh connections
ssh -p 29418 review.opendev.org gerrit close-connection {connection-id}
.. code-block:: shell-session
$ ssh -p 29418 review.opendev.org gerrit show-connections -n | grep {account-id}
And kill all of them with subsequent
.. code-block:: shell-session
$ ssh -p 29418 review.opendev.org gerrit close-connection {connection-id}
4. You can check if the account is properly marked as inactive using REST API,
sending a GET for::
sending a GET for
curl -i -H "Accept: application/json" --digest --user <<gerrit_user>>:<<http_pass>> -X GET https://review.opendev.org/a/accounts/{account-id}/active
.. code-block:: shell-session
$ curl -i -H "Accept: application/json" --digest --user <<gerrit_user>>:<<http_pass>> -X GET https://review.opendev.org/a/accounts/{account-id}/active
A 200 return code means the account is active, and 204 means account inactive.
4. In the case of a failing Third Party CI, if the account caused a loop of comments in
a change, you can delete them with following query::
delete from change_messages where author_id={account-id} and change_id={change-id};
Generating a Thread Dump for Debugging
--------------------------------------
@ -577,8 +563,10 @@ still possible with java command line tools. You may find yourself wanting
to do this if Gerrit is suffering from poor performance or you are trying to
debug odd Gerrit behavior.
To run jstack and produce a thread dump do::
To run ``jstack`` and produce a thread dump do
review02# docker exec -it gerrit-compose_gerrit_1 bash
gerrit@review02:/$ ps -ef | grep java # find the Gerrit java process PID
gerrit@review02:/$ jstack $PID > /tmp/dump.yearmonthday
.. code-block:: shell-session
root@review02 # docker exec -it gerrit-compose_gerrit_1 bash
gerrit@review02 $ ps -ef | grep java # find the Gerrit java process PID
gerrit@review02 $ jstack ${PID} > /tmp/dump.yearmonthday

37
doc/source/sysadmin.rst
View File

@ -62,39 +62,36 @@ have no OpenID so that it is only accessable by API/CLI methods so they
cannot be compromised at the third-party ID provider.
To create a personal Gerrit admin account from a shell on the server, run
the following command::
the following command
sudo -u gerrit2 ssh -i ~gerrit2/review_site/etc/ssh_host_rsa_key \
-p 29418 -l 'Gerrit Code Review' localhost \
"suexec --as openstack-project-creator -- \
gerrit create-account --group Administrators --full-name myname.admin \
--ssh-key 'ssh-rsa AAAA...BCDE myname@computer' myname.admin"
.. code-block:: shell-session
$ sudo -u gerrit2 ssh -i ~gerrit2/review_site/etc/ssh_host_rsa_key -p 29418 -l 'Gerrit Code Review' localhost "suexec --as openstack-project-creator -- gerrit create-account --group Administrators --full-name myname.admin --ssh-key 'ssh-rsa AAAA...BCDE myname@computer' myname.admin"
We ``suexec`` as the ``openstack-project-creator`` account because the
magic ``Gerrit Code Review`` pseudoaccount can't set group memberships so
we need to run that command as a user which is already in the
``Administrators`` group. With an account like this, routine actions like
populating new groups with initial members is still quite simple::
populating new groups with initial members is still quite simple
ssh -p 29418 myname.admin@review.opendev.org \
"gerrit set-members some-new-group --add somebody@example.org"
.. code-block:: shell-session
$ ssh -p 29418 myname.admin@review.opendev.org "gerrit set-members some-new-group --add somebody@example.org"
Another common example is bypassing Zuul to submit a change for merging
directly to a project. In this case we must first add our account to
another group which has permission to set the relevant labels (it doesn't
get that simply by being an administrator), and then do the
commenting/voting/submitting, followed by cleaning up the extra group
membership again at the end::
membership again at the end
ssh -p 29418 myname.admin@review.opendev.org \
"gerrit set-members 'Project Bootstrappers' --add myname.admin"
.. code-block:: shell-session
ssh -p 29418 myname.admin@review.opendev.org \
"gerrit review 12345,6 --message 'Bypassing Zuul to merge this.' \
--code-review=2 --verified=2 --label workflow=1 --submit"
$ ssh -p 29418 myname.admin@review.opendev.org "gerrit set-members 'Project Bootstrappers' --add myname.admin"
ssh -p 29418 myname.admin@review.opendev.org \
"gerrit set-members 'Project Bootstrappers' --remove myname.admin"
$ ssh -p 29418 myname.admin@review.opendev.org "gerrit review 12345,6 --message 'Bypassing Zuul to merge this.' --code-review=2 --verified=2 --label workflow=1 --submit"
$ ssh -p 29418 myname.admin@review.opendev.org "gerrit set-members 'Project Bootstrappers' --remove myname.admin"
Note that it's possible to temporarily add your normal OpenID-associated
WebUI account to the ``Administrators`` group or other groups with similar
@ -141,9 +138,11 @@ Accessing Clouds
================
As an unprivileged user who is a member of the `sudo` group on bridge,
you can inspect any of the clouds with::
you can inspect any of the clouds with
sudo openstack --os-cloud <cloud name> --os-cloud-region <region name>
.. code-block:: shell-session
$ sudo openstack --os-cloud <cloud name> --os-cloud-region <region name>
Backups
=======