Update API docs for PKI multi-issuer functionality #15238
Conversation
cipherboy
force-pushed
the
cipherboy-pki-pod-rotation-docs
branch
from
3b7dd43 to
810eb20
Compare
cipherboy
changed the title
cipherboy
force-pushed
the
cipherboy-pki-pod-rotation-docs
branch
from
810eb20 to
bd36d00
Compare
cipherboy
force-pushed
the
cipherboy-pki-pod-rotation-docs
branch
from
bd36d00 to
1fb2577
Compare
There was a problem hiding this comment.
So, this is a draft, and my nits are probably unhelpful - you'll fix them anyway, I'm sure.
I guess I'm a little concerned that we are throwing a lot at someone who probably doesn't want to deal with multiple issuers (at least at first). It would make a lot of sense to me to include a tiny issuer section, maybe:
*) Read Issuer (sample Default)
*) Import Issuer / Generate Issuer
*) Set Default Issuer
And then either include a jump directly to Roles (the Issuing certificate section), or put that section first, and put a larger "advanced issuer configuration" later.
It would be cool if Revoke Certificate was paired with reading the CRL.
| ``` | ||
|
|
||
| ## Read Certificate | ||
| <a name="read-ca-certificate"></a> |
There was a problem hiding this comment.
Can we remove this, or what does this do? Nothing points to #read-ca-certificate anymore
There was a problem hiding this comment.
This allows bookmarks to the (existing, soon to be old) docs persist and link to the right thing in the new updated format. :-)
| - [Sign Verbatim](#sign-verbatim) | ||
| - [Tidy](#tidy) | ||
| - [Tidy Status](#tidy-status) | ||
| - [Notice About New Multi-Issuer Functionality](#notice-about-new-multi-issuer-functionality) |
There was a problem hiding this comment.
maybe I'm doing this wrong, but none of these links seem to work?
There was a problem hiding this comment.
If you cd website && make it should launch a Vercel server that'll let you view it at e.g., http://localhost:3000/api-docs/secret/pki and the links definitely work for me. Maybe not all of them, but most of them definitely do and this one does.
I think GH's markdown rendering just doesn't do the linking the same as Vercel or maybe they don't render anchors for PR pages? Not sure.
There was a problem hiding this comment.
| - [Delete Key](#delete-key) | ||
| - [Delete All Issuers and Keys](#delete-all-issuers-and-keys) | ||
| - [Managing Authority Information](#managing-authority-information) | ||
| - [List Roles](#list-roles) |
There was a problem hiding this comment.
list roles is listed twice (line 29)
There was a problem hiding this comment.
Yes, this was intentional to give a logical grouping of information (list/create/read/delete as allotted by the usage) per section. The first-most section contains all the information about it and later ones refer back.
cipherboy
force-pushed
the
cipherboy-pki-pod-rotation-docs
branch
from
6344dd2 to
ab2b027
Compare
This substantially restructures the PKI secret engine's docs for two
purposes:
1. To provide an explicit grouping of APIs by user usage and roles,
2. To add all of the new APIs, hopefully with as minimal duplication
as possible.
Signed-off-by: Alexander Scheel <[email protected]>
- Add [1] links next to the DER/PEM format entries within various PKI response tables. These link to a new section explaining that the vault cli does not support DER/PEM response formats - Remove repetition of vault cli blurb in various description fields. - Fix up some typos
cipherboy
force-pushed
the
cipherboy-pki-pod-rotation-docs
branch
from
ab2b027 to
f075c47
Compare
Signed-off-by: Alexander Scheel <[email protected]>