Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Task: add documentation for metadata update #527

Open
1 task done
MVrachev opened this issue Oct 12, 2023 · 3 comments
Open
1 task done

Task: add documentation for metadata update #527

MVrachev opened this issue Oct 12, 2023 · 3 comments
Labels
documentation Improvements or additions to documentation

Comments

@MVrachev
Copy link
Member

MVrachev commented Oct 12, 2023

What is the task about?

Describe how our users can do a successful metadata update.

We want to cover in the doc:

  • what can be updated from the metadata update RSTUF CLI command
  • explaining how offline keys can be updated
  • explaining the process of how to correctly update the online key

Code of Conduct

  • I agree to follow this project's Code of Conduct
@MVrachev MVrachev added the documentation Improvements or additions to documentation label Oct 12, 2023
@kairoaraujo
Copy link
Member

kairoaraujo commented Oct 12, 2023

https://repository-service-tuf.readthedocs.io/en/stable/guide/general/usage.html#metadata-update

I think we can improve it.

@MVrachev
Copy link
Member Author

MVrachev commented Oct 12, 2023

I think it's really important to describe well as an algorithm how to update the online key.
I think this should happen as follows:

  1. Append a new keyid to the RSTUF_*_KEYVAULT_KEYS env variable
  2. Finish a successful metadata update ceremony from the RSTUF CLI.
  3. Call POST /api/v1/metadata with the new payload.
  4. Restart your container

It's important that you do steps 1 to 3 before you restart your container so that the new root.json has the new keyid otherwise you will end up with an invalid repository that cannot sign.
If you forgot to do step 1 you will end up with a new root with a new online key id which doesn't match the key used by your signer.
If you forgot to do steps 2 or 3 you won't have a new root.json and you will continue using the old signer based on the old online key.

@MVrachev
Copy link
Member Author

After a conversation with @kairoaraujo we came up with the following steps for AWS KeyVault online key rotation

  1. Create AWS key
  2. Update env variable
  3. Restart containers
    1. Init all possible signers
  4. Do a "metadata update" ceremony
  5. Publish new root version

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

2 participants