Document admin bootstrapping and recovery #31039
Conversation
ca95f75 to
4858789
Compare
4c9dc9e to
0c9a072
Compare
|
|
||
| This command creates a temporary admin user with the username `tmpadm` and the password `tmpadmpass`. | ||
|
|
||
| NOTE: The command can be executed even before the {project_name} first ever start. However, it leaves the {project_name} server in a state, where the temporary admin account will be the only account that exists in the master realm - the default admin will not be created. If the intention is to recover a lost admin access, the default admin should exist within the master realm prior to the command execution. Also, it is strongly recommended to use the dedicated command with the very sane options that the {project_name} server is started with (e.g. `db` options). |
There was a problem hiding this comment.
It'd be also good to add a section for bootstrapping at server startup. Explaining the difference from the dedicated command (that on startup master realm must on exist, making the dedicated command the only suitable option for recovery).
I tried to address this one via a note.
@shawkins wdyt?
|
I tried to incorporate every suggestion mentioned above. For now the changes are in a separate commit in order to make it easier to see the differences. I will do the squash later. cc: @shawkins Edit: I also tried to adjust the punctuation, articles and wording. |
b52cfef to
906a107
Compare
shawkins
left a comment
There was a problem hiding this comment.
I tried to incorporate every suggestion mentioned above. For now the changes are in a separate commit in order to make it easier to see the differences. I will do the squash later.
cc: @shawkins
Edit: I also tried to adjust the punctuation, articles and wording.
Thanks @Pepo48 it looks good. Just a conflict to clear up and it should be set.
@shawkins thanks for the review. The conflict happened in the release notes - I merged both of our inputs together into one section. |
|
|
||
| This command creates a temporary admin user with the username `tmpadm` and the password `tmpadmpass`. | ||
|
|
||
| NOTE: The command can be executed even before the first-ever start of {project_name}. However, this will leave the {project_name} server in a state where the temporary admin account is the only account that exists in the master realm and the default admin will not be created. The initial admin creation happens only when the master realm is created. If the intention is to recover lost admin access, the default admin must exist in the master realm prior to executing the command (see <@links.server id="configuration" anchor="create-initial-admin"/>). Additionally, it is strongly recommended to use the dedicated command with the same options that the {project_name} server is started with (e.g., `db` options). |
There was a problem hiding this comment.
IMHO the db options would not only be "strongly recommended", but "required" as it would otherwise not write to the correct database and it will not work.
At the same time I am not sure if all of the options I use on the start command will also work on the boostrap commands (like: setting a HTTP port).
There was a problem hiding this comment.
This is a somewhat confusing area in general for us #29200 - we do some configuration exclusions for the CLI, but those same options will still work via the other config sources (the operator effectively uses this for export because almost everything is set via an env variable). Only a handful of options have hard-coded overrides when running a non-server command.
There was a problem hiding this comment.
I tried to clarify the cases with #29200 (comment) - as there are potentially 3 different ways users could be invoking non-server commands which have some nuance that we trying to address here quickly with this recommendation.
|
@Pepo48 - I pushed one commit to make the external link check pass. I also found that anchors in the IDs don't work, so I updated the Freemarker makros to support it. It is already part of the scaling guide, but not yet in main. If you consider this documentation ready-to-be-merged, please ask Andrew Munro for a review from the technical writer's perspective to make sure the wording aligns with all the other docs. |
50b7168 to
69016e5
Compare
|
@Pepo48 Could you also please address this comment in this PR since #30711 was merged sooner than this? |
5be0072 to
b865903
Compare
Addressed by adding a new section with the link to the operator's advanced configuration. |
b22291c to
3e74501
Compare
vmuzikar
left a comment
There was a problem hiding this comment.
@Pepo48 Thanks for the latest changes. Overall LGTM, added some last minor comments.
@ahus1 @shawkins @mhajas Do you want to re-review as well?
I'd like to merge this rather sooner than later. Not sure we need to wait for a review from @andymunro (as he's quite busy). We could incorporate his review changes as a follow up. WDYT?
|
|
||
| If a master realm has already been created for you cluster, then the spec.boostrapAdmin is effectively ignored. If you need to create a recovery admin account, then you'll need to run the CLI command against a Pod directly. | ||
|
|
||
| For more information on how to bootstrap a temporary admin user or service account and recover lost admin access, refer to the link:{bootstrapadminrecovery_link}[{bootstrapadminrecovery_name}] guide. |
There was a problem hiding this comment.
This does not seem to render correctly?
There was a problem hiding this comment.
Some of these are not rendered for me when building the docs locally, yet they're used and seems to work fine when deployed. What's the general approach here? Should we use a hard-coded links or should we alway try to use variables and link anchors, especially when cross-referencing.
Am I actually allowed to define and use new document attributes for this specific case?
There was a problem hiding this comment.
I guess for the guide itself I can replace it with <@links.server id="bootstrap-admin-recovery"/>. But what about the release notes then?
There was a problem hiding this comment.
Release notes seem to work fine for my local build.
There was a problem hiding this comment.
For me as well. The question is whether it's fine to use it that way.
There was a problem hiding this comment.
For me as well. The question is whether it's fine to use it that way.
For release note and upgrading guide, sure from my PoV. For Operator guide, I'm not sure – locally it doesn't work.
There was a problem hiding this comment.
@vmuzikar are the rest of the links in the operator's advanced configuration guide rendered correctly for your local build?
There was a problem hiding this comment.
Yes, other links render fine for me.
|
@vmuzikar, I went through the changes quickly and it looks good. Still, I am not 100% confident to approve so I will leave it for the others to add final approvals. If you would like me to have a proper look let me know. |
Closes: keycloak#30011 Co-authored-by: Alexander Schwartz <[email protected]> Signed-off-by: Peter Zaoral <[email protected]>
Co-authored-by: Václav Muzikář <[email protected]> Signed-off-by: Peter Zaoral <[email protected]>
Signed-off-by: Peter Zaoral <[email protected]>
|
@vmuzikar - no further comments from me. IMHO this is really a big change, and people will need to adjust. For example on the Keycloak Benchmark Project, we had the KEYCLOAK_ADMIN/KEYCLOAK_ADMIN_PASSWORD env variables set, and now the Operator created a different admin account. Only once I put my env variables into KC_BOOTSTRAP_ADMIN_USERNAME/KC_BOOTSTRAP_ADMIN_PASSWORD it worked as before. Yes, I know this is non-standard, still people might fall into similar traps they have built for themselves in the past. Please reach out to the community to try this out (blog post, user mailing list, GitHub discussion) so the community can adjust. |
Closes: #30011
Signed-off-by: Peter Zaoral [email protected]