diff --git a/doc/source/gerrit.rst b/doc/source/gerrit.rst index 9c29956657..8668c3f31f 100644 --- a/doc/source/gerrit.rst +++ b/doc/source/gerrit.rst @@ -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,14 +79,16 @@ 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 \ - --group "'Project Bootstrappers'" \ - --group Administrators \ - --full-name "'Project Creator'" \ - --email openstack-infra@lists.openstack.org \ - --ssh-key - openstack-project-creator +.. code-block:: shell-session + + $ cat $pubkey | ssh -p 29418 $USER@$HOST gerrit create-account \ + --group "'Project Bootstrappers'" \ + --group Administrators \ + --full-name "'Project Creator'" \ + --email openstack-infra@lists.openstack.org \ + --ssh-key - openstack-project-creator .. _gerrit_github_integration: @@ -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 ` 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 - git push origin HEAD:refs/users/45/12345 + $ git commit -m "Make duplicate account inactive" --author + $ 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 <>:<> -X GET https://review.opendev.org/a/accounts/{email} + .. code-block:: shell-session + + $ curl -i -H "Accept: application/json" --digest --user <>:<> -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 <>:<> -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 <>:<> -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 <>:<> -X GET https://review.opendev.org/a/accounts/{account-id}/active + .. code-block:: shell-session + + $ curl -i -H "Accept: application/json" --digest --user <>:<> -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 diff --git a/doc/source/sysadmin.rst b/doc/source/sysadmin.rst index 8df4b5ee53..9fd9ea6d7e 100644 --- a/doc/source/sysadmin.rst +++ b/doc/source/sysadmin.rst @@ -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 --os-cloud-region +.. code-block:: shell-session + + $ sudo openstack --os-cloud --os-cloud-region Backups =======