Reword Service Accounts docs #14681

sftim · 2019-06-01T15:50:07Z

Reword:

netlify · 2019-06-01T15:58:24Z

Deploy preview for kubernetes-io-master-staging ready!

Built with commit 1024e1e

https://deploy-preview-14681--kubernetes-io-master-staging.netlify.com

tengqm · 2019-06-03T03:38:13Z

content/en/docs/reference/access-authn-authz/service-accounts-admin.md

-  - Typically, a cluster's User accounts might be synced from a corporate
-    database, where new user account creation requires special privileges and
+    {{< glossary_tooltip text="namespaces" term_id="namespace" >}} of a cluster.
+    Service accounts *are* namespaced; [human] user identities are not namespaced.


maybe we should avoid mixing 'user accounts' and 'user identities'.

tengqm · 2019-06-03T03:39:28Z

content/en/docs/reference/access-authn-authz/service-accounts-admin.md

@@ -10,99 +10,107 @@ weight: 50
 ---

 {{% capture overview %}}
-This is a Cluster Administrator guide to service accounts. It assumes knowledge of
+This is a Cluster Operator guide to service accounts. It assumes knowledge of


I believe most of the contents in this page are for "administrators' rather than average users.

I've borrowed this wording from https://kubernetes.io/docs/reference/glossary/?all=true#term-cluster-operator

Maybe it doesn't make sense to have two separate documents explicitly aimed at people with different experience levels. Rather, we could have a detailed Reference-section guide and also a simpler Task guide.

Something for a future PR? I want to keep this one focused.

content/en/docs/reference/access-authn-authz/service-accounts-admin.md

content/en/docs/tasks/configure-pod-container/configure-service-account.md

kbhawkey · 2019-06-03T16:41:25Z

content/en/docs/tasks/configure-pod-container/configure-service-account.md

@@ -9,7 +9,7 @@ weight: 90
 ---

 {{% capture overview %}}
-A service account provides an identity for processes that run in a Pod.
+A _service account_ provides an identity for processes that run in a Pod.


Service account vs service account?

I think “service account” is fine for English grammar. The Kubernetes resource is ServiceAccount, which gets introduced below.

Do you need italics, above and below? Check the style guide.

kbhawkey · 2019-06-03T16:42:07Z

content/en/docs/tasks/configure-pod-container/configure-service-account.md

-## Use the Default Service Account to access the API server.
+## Use the default Service Account to access the API server
+
+Each namespace has a default ServiceAccount, named `default`.


ServiceAccount is the resource?

OK. Check the heading.

kbhawkey · 2019-06-03T17:05:51Z

https://deploy-preview-14681--kubernetes-io-master-staging.netlify.com/docs/reference/access-authn-authz/service-accounts-admin/

https://deploy-preview-14681--kubernetes-io-master-staging.netlify.com/docs/tasks/configure-pod-container/configure-service-account/

sftim · 2019-06-03T18:23:23Z

I'd left “user account” in a heading. Fixed.
(this will break inbound links to that fragment, but as it's at the top of the page I'm not worried)

kbhawkey · 2019-06-03T19:00:17Z

content/en/docs/tasks/configure-pod-container/configure-service-account.md

@@ -70,15 +76,17 @@ spec:
  ...
 ```

-The pod spec takes precedence over the service account if both specify a `automountServiceAccountToken` value.
+If both the ServiceAccount and the pod spec specify a value for
+`automountServiceAccountToken`, the pod spec takes precedence.


PodSpec is the object

From a cluster operator's point of view, Pods have specifications. Pods are Kubernetes objects.
Maybe “the Pod's specification” or “the Pod's .spec”?

content/en/docs/tasks/configure-pod-container/configure-service-account.md

kbhawkey · 2019-06-03T19:12:49Z

content/en/docs/reference/access-authn-authz/service-accounts-admin.md

+between the concept of a user and a service account for a number of reasons:
+
+  - Users represent humans. Service accounts are for processes, which
+    run in {{< glossary_tooltip text="pods" term_id="pod" >}}.


I'm not sure this change helps clarify a user account vs. service account.

are italics needed?

tengqm · 2019-06-04T00:59:29Z

/lgtm
When other feedbacks are addressed, we can move this in.

k8s-ci-robot · 2019-07-11T08:00:52Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
To complete the pull request process, please assign tengqm
You can assign the PR to them by writing /assign @tengqm in a comment when ready.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

content/en/OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

content/en/docs/reference/access-authn-authz/service-accounts-admin.md

zacharysarah · 2019-08-06T22:54:30Z

@sftim 👋 Just checking in. Do you have what you need to continue?

sftim · 2019-08-06T22:55:52Z

Hi @zacharysarah
Yep, this does need more work but (I hope) not much more, and I've got feedback to draw on.

sftim · 2019-08-25T12:53:05Z

Revised

sftim · 2019-09-09T10:39:26Z

@chenopis or @tengqm - can you review?

tengqm · 2019-09-25T02:55:43Z

/lgtm

kbhawkey · 2019-09-25T15:09:18Z

content/en/docs/tasks/configure-pod-container/configure-service-account.md

 content_template: templates/task
 weight: 90
 ---

 {{% capture overview %}}
-A service account provides an identity for processes that run in a Pod.
+Kubernetes recognises two distinct ways for clients outside the


hello @sftim . I read through the page. There are a few minor nits that could be addressed before merging.
line 12: recognizes 😄
line 19: spelling yoy, recognizes
line 40: capitalize namespace or not?
line 61: the kubelet? enclose in backticks or not?
line 95: possible edit: You can list all ServiceAccount resources in your current namespace with:
line 120: possible edit: You can get a YAML output of ...
line 314: fix the link with forward slash before docs, projected volume type called

k8s-ci-robot · 2019-09-25T22:18:41Z

New changes are detected. LGTM label has been removed.

sftim · 2019-09-25T22:29:01Z

Thanks for the feedback @kbhawkey
I think it's all fixed now(?)

kbhawkey · 2019-09-26T14:32:53Z

@sftim , I read through the Configure ServiceAccounts ... page again. Some of the small nits remain (spelling:recognises) and there is a link to automatically that needs to be corrected. Also check for a typo where you changed the sentence about YAML output.
The second part of this PR, Managing ServiceAccounts, is missing the reference information about ServiceAccount automation and Kubernetes controllers. For me, this part of the page is the most important. I realize that there are some dependencies with this PR, but perhaps the controller content should stay with the page until the controller reference section is created in another commit (unless the content is entirely outdated).

sftim · 2019-09-27T08:43:05Z

I think what I'll do is close this PR, keep the branch around, and try to get these changes in once there are other Controller-related PRs already merged.
Thanks for all feedback so far.

k8s-ci-robot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Jun 1, 2019

k8s-ci-robot requested review from bprashanth and davidopp June 1, 2019 15:50

k8s-ci-robot added language/en Issues or PRs related to English language sig/docs Categorizes an issue or PR as relevant to SIG Docs. labels Jun 1, 2019

tengqm reviewed Jun 3, 2019

View reviewed changes

sftim force-pushed the 20190601_task_configure_service_account_reword branch from 4e17983 to 37ed864 Compare June 3, 2019 10:36

kbhawkey reviewed Jun 3, 2019

View reviewed changes

content/en/docs/tasks/configure-pod-container/configure-service-account.md Outdated Show resolved Hide resolved

kbhawkey reviewed Jun 3, 2019

View reviewed changes

content/en/docs/tasks/configure-pod-container/configure-service-account.md Outdated Show resolved Hide resolved

kbhawkey reviewed Jun 3, 2019

View reviewed changes

sftim force-pushed the 20190601_task_configure_service_account_reword branch 3 times, most recently from 5c5e7e3 to 4f4805a Compare June 3, 2019 16:50

sftim force-pushed the 20190601_task_configure_service_account_reword branch from 4f4805a to 22a526d Compare June 3, 2019 18:22

kbhawkey reviewed Jun 3, 2019

View reviewed changes

content/en/docs/tasks/configure-pod-container/configure-service-account.md Show resolved Hide resolved

kbhawkey reviewed Jun 3, 2019

View reviewed changes

k8s-ci-robot assigned tengqm Jun 4, 2019

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Jun 4, 2019

sftim changed the title ~~Reword Service Accounts docs~~ [WIP] Reword Service Accounts docs Jun 5, 2019

k8s-ci-robot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Jun 5, 2019

sftim force-pushed the 20190601_task_configure_service_account_reword branch from 22a526d to d67e7d4 Compare July 11, 2019 08:00

k8s-ci-robot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Jul 11, 2019

kbhawkey reviewed Jul 30, 2019

View reviewed changes

content/en/docs/reference/access-authn-authz/service-accounts-admin.md Show resolved Hide resolved

sftim changed the title ~~Reword Service Accounts docs~~ [WIP] Reword Service Accounts docs Aug 3, 2019

k8s-ci-robot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Aug 3, 2019

sftim force-pushed the 20190601_task_configure_service_account_reword branch from 0d1ff97 to 9668687 Compare August 3, 2019 09:18

sftim force-pushed the 20190601_task_configure_service_account_reword branch from 9668687 to 66e78d6 Compare August 25, 2019 12:51

sftim changed the title ~~[WIP] Reword Service Accounts docs~~ Reword Service Accounts docs Aug 25, 2019

k8s-ci-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Aug 25, 2019

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Sep 25, 2019

kbhawkey reviewed Sep 25, 2019

View reviewed changes

sftim changed the title ~~Reword Service Accounts docs~~ [WIP] Reword Service Accounts docs Sep 25, 2019

k8s-ci-robot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Sep 25, 2019

sftim force-pushed the 20190601_task_configure_service_account_reword branch from 66e78d6 to 82b4734 Compare September 25, 2019 22:18

k8s-ci-robot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Sep 25, 2019

sftim added 2 commits September 25, 2019 23:24

Reword “Configure Service Accounts for Pods”

cb4ee6a

Reword “Managing Service Accounts” task

1024e1e

sftim force-pushed the 20190601_task_configure_service_account_reword branch from 82b4734 to 1024e1e Compare September 25, 2019 22:24

sftim closed this Sep 27, 2019

sftim changed the title ~~[WIP] Reword Service Accounts docs~~ Reword Service Accounts docs Dec 12, 2019

k8s-ci-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Dec 12, 2019

sftim deleted the 20190601_task_configure_service_account_reword branch June 9, 2021 17:48

sftim mentioned this pull request May 13, 2022

Reword tasks relating to ServiceAccounts #33654

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Reword Service Accounts docs #14681

Reword Service Accounts docs #14681

sftim commented Jun 1, 2019

netlify bot commented Jun 1, 2019 •

edited

Loading

tengqm Jun 3, 2019

tengqm Jun 3, 2019

sftim Jun 3, 2019

kbhawkey Jun 3, 2019

sftim Jun 3, 2019

kbhawkey Jun 3, 2019 •

edited

Loading

sftim Jul 29, 2019

kbhawkey Jun 3, 2019

sftim Jun 3, 2019

kbhawkey Jun 3, 2019

kbhawkey commented Jun 3, 2019 •

edited

Loading

sftim commented Jun 3, 2019

kbhawkey Jun 3, 2019

sftim Jul 29, 2019

kbhawkey Jul 30, 2019

kbhawkey Jun 3, 2019

tengqm commented Jun 4, 2019

k8s-ci-robot commented Jul 11, 2019

zacharysarah commented Aug 6, 2019

sftim commented Aug 6, 2019

sftim commented Aug 25, 2019

sftim commented Sep 9, 2019

tengqm commented Sep 25, 2019

kbhawkey Sep 25, 2019

k8s-ci-robot commented Sep 25, 2019

sftim commented Sep 25, 2019

kbhawkey commented Sep 26, 2019

sftim commented Sep 27, 2019

Reword Service Accounts docs #14681

Reword Service Accounts docs #14681

Conversation

sftim commented Jun 1, 2019

netlify bot commented Jun 1, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kbhawkey Jun 3, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kbhawkey commented Jun 3, 2019 • edited Loading

sftim commented Jun 3, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tengqm commented Jun 4, 2019

k8s-ci-robot commented Jul 11, 2019

zacharysarah commented Aug 6, 2019

sftim commented Aug 6, 2019

sftim commented Aug 25, 2019

sftim commented Sep 9, 2019

tengqm commented Sep 25, 2019

Choose a reason for hiding this comment

k8s-ci-robot commented Sep 25, 2019

sftim commented Sep 25, 2019

kbhawkey commented Sep 26, 2019

sftim commented Sep 27, 2019

netlify bot commented Jun 1, 2019 •

edited

Loading

kbhawkey Jun 3, 2019 •

edited

Loading

kbhawkey commented Jun 3, 2019 •

edited

Loading