canonical-ubuntu-qa team mailing list archive

[Tim Andersson <mp+469839@xxxxxxxxxxxxxxxxxx>]

Tim Andersson has proposed merging ~andersson123/autopkgtest-cloud:api-key-howto into autopkgtest-cloud:master.

Commit message:
docs: add more details regarding API keys

Currently, the docs only mention **how** an individual can use an API
key - there is no mention or guideline regarding how an admin should
create an API key for a requested user, group or bot.

This commit amends the issue by making the pre-existing section a little
bit more clear, as well as adding a new section which details how an
`autopkgtest-cloud` admin should create an API key.

Requested reviews:
  Canonical's Ubuntu QA (canonical-ubuntu-qa)

For more details, see:
https://code.launchpad.net/~andersson123/autopkgtest-cloud/+git/autopkgtest-cloud/+merge/469839

Adds more detail to the documentation regarding how an autopkgtest admin should create API keys, as well as a minor extra detail regarding the usage of API keys.
-- 
Your team Canonical's Ubuntu QA is requested to review the proposed merge of ~andersson123/autopkgtest-cloud:api-key-howto into autopkgtest-cloud:master.

diff --git a/docs/administration.rst b/docs/administration.rst
index 6040a9c..d49d90a 100644
--- a/docs/administration.rst
+++ b/docs/administration.rst
@@ -222,8 +222,47 @@ Once those steps are done then the rows can be deleted from the database.
 * ``sqlite3 -header -column autopkgtest.db "DELETE FROM test WHERE test.release='impish';"``
 * ``sqlite3 -header -column autopkgtest.db "vacuum;"``
 
-API Key Integration
--------------------
+Create a new API key for a user or group
+----------------------------------------
+
+API keys exist on the web workers with the following format:
+
+.. code-block:: bash
+
+  {"username": "api-key", "username": "api-key"}
+
+And so on and so forth. The ``username`` should be the launchpad username of the individual who is
+requesting an API key. This is not strict, however, and could potentially be anything, as long as the user
+attaches their API key using the correct name as provided by the Ubuntu Release Management Team. It just makes
+the most sense to just use launchpad usernames.
+
+The ``username`` can also potentially be a name to refer to a group of individuals sharing the same key, or a bot.
+
+The convention to create API keys has thus far been the following, utilising uuid4:
+
+.. code-block:: bash
+
+  python3 -c 'import uuid; print(uuid.uuid4())'
+
+Once the ``uuid`` for the api key has been created, add it to:
+
+.. code-block:: bash
+
+  /home/$STAGE-proposed-migration-environment/.local/share/mojo/LOCAL/mojo-prod-proposed-migration/production/external-web-requests-api-keys.json
+
+Where ``$STAGE`` is either ``prod`` or ``stg``.
+
+After this, do a ``mojo run`` to deploy the altered file.
+
+Alternatively, if a ``mojo run`` is for some reason, undesirable at the time, one can also directly add the new api key to:
+
+``/home/ubuntu/external-web-requests-api-keys.json``
+
+on the web units.
+
+
+Using API Keys
+--------------
 
 Requests can be requested by using an API key instead of authenticating using SSO.
 To do so, attach a cookie to whatever script is making the test request, with the name
@@ -233,6 +272,7 @@ To do so, attach a cookie to whatever script is making the test request, with th
 
 Where the user and api-key fields are provided by the Ubuntu Release Management team.
 
+One can also attach the API key to Python scripts.
 
 Integration with GitHub and GitLab pull/merge requests
 ------------------------------------------------------