Add documentation for Kubernetes credential management #213
Conversation
See #96 Signed-off-by: Ciro S. Costa <cscosta@pivotal.io> Co-authored-by: Mark Huang <mhuang@pivotal.io>
Signed-off-by: Ciro S. Costa <cscosta@pivotal.io>
Signed-off-by: Ciro S. Costa <cscosta@pivotal.io>
| --- | ||
| # Identifies the `web` service as an actor. | ||
| # | ||
| # ref: https://kubernetes.io/docs/reference/access-authn-authz/service-accounts-admin/ |
There was a problem hiding this comment.
@vito do you think this kind of comment is too much? Providing references to the document from the official Kubernetes website?
| - name: CONCOURSE_KUBERNETES_NAMESPACE_PREFIX | ||
| value: "myprefix-" | ||
| # ... | ||
| }}} |
There was a problem hiding this comment.
this YAML file is quite big 😬 I'm not sure if this would be the best way of presenting it - I tried separating them into separate code blocks, but I feel that this way looks a bit better (and it's quite common to see docs like this when it comes to k8s).
wdyt?
There was a problem hiding this comment.
Would an alternative be to split it up and move the comments into the Booklit document? Or is having it all in one YAML document useful for copy-pasting and submitting everything at once?
There was a problem hiding this comment.
ooooh good point, those side comments would be nice. I'll give them a try here 👍
Or is having it all in one YAML document useful for copy-pasting and submitting everything at once?
hmmm I saw a couple of times people having multiple yaml blocks altogether when it comes to k8s, but I'd personally split 😅
(for some reason I thought you mentioned using \aside lol)
There was a problem hiding this comment.
after splitting, seems easier to follow; wdyt?
|
|
||
| \codeblock{bash}{{{ | ||
| CONCOURSE_KUBERNETES_NAMESPACE_PREFIX=some-other-prefix- | ||
| }}} |
There was a problem hiding this comment.
I was a bit divided by letting this configuration piece here - it seemed quite far from the other two configurations at the top of the page 🤔 any thoughts on this?
There was a problem hiding this comment.
I think it's fine - it's the same as with the other credential managers. I'm not sure how often folks will set this but since it has a sane default I think it can be "below the fold".
| \title{Configuring Kubernetes RBAC} | ||
|
|
||
| As the Web nodes need to retrieve secrets from namespaces that are not its | ||
| own, it needs extra permissions to do so. |
There was a problem hiding this comment.
web nodes are plural but its and it are singular.
Previously, in the kubernetes RBAC example we had all of the kubernetes objects needed tied together in a single multi-object yaml block, which was quite bad to read. Now, each object has its own descriptions through regular comments, making it more appealing to read. Signed-off-by: Ciro S. Costa <cscosta@pivotal.io>
Signed-off-by: Ciro S. Costa <cscosta@pivotal.io>
fixes #96