-
Notifications
You must be signed in to change notification settings - Fork 14.3k
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
document kube-apiserver identity #24921
Conversation
Deploy preview for kubernetes-io-vnext-staging processing. Building with commit 2ad9e02 https://app.netlify.com/sites/kubernetes-io-vnext-staging/deploys/5fbd7ccec1b1ad000709bdaf |
a1f9d61
to
300bce0
Compare
/assign @reylejano-rxm |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hi. Here's some early feedback - I hope it's helpful.
The API Server Identity feature is controlled by a feature gate | ||
and is not enabled by default. See | ||
[Feature Gates](/docs/reference/command-line-tools-reference/feature-gates/) | ||
for a general explanation of feature gates and how to enable and disable them. The | ||
name of the feature gate is "APIServerIdentity". You can enable API Server Identity | ||
by adding the following command-line flag to your `kube-apiserver` invocation: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd write this as:
The API Server Identity feature is controlled by a feature gate | |
and is not enabled by default. See | |
[Feature Gates](/docs/reference/command-line-tools-reference/feature-gates/) | |
for a general explanation of feature gates and how to enable and disable them. The | |
name of the feature gate is "APIServerIdentity". You can enable API Server Identity | |
by adding the following command-line flag to your `kube-apiserver` invocation: | |
The API Server Identity feature is controlled by a | |
[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) | |
and is not enabled by default. You can activate API Server Identity by enabling | |
the feature gate named `APIServerIdentity` when you start the | |
{{< glossary_tooltip text="API Server" term_id="kube-apiserver" >}}: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
or:
The API Server Identity feature is controlled by a feature gate | |
and is not enabled by default. See | |
[Feature Gates](/docs/reference/command-line-tools-reference/feature-gates/) | |
for a general explanation of feature gates and how to enable and disable them. The | |
name of the feature gate is "APIServerIdentity". You can enable API Server Identity | |
by adding the following command-line flag to your `kube-apiserver` invocation: | |
_API Server identity_ is behind a | |
[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) | |
named `APIServerIdentity`, that is not enabled by default. | |
You can enable API Server Identity by adding the following command-line | |
flag to your `kube-apiserver` invocation: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks. Updated the paragraph with the first suggestion.
# …and other flags as usual | ||
``` | ||
|
||
Each API server will be assigned with an unique ID on bootstrap. The list of |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Each API server will be assigned with an unique ID on bootstrap. The list of | |
During bootstrap, NAME_OF_THING assigns a unique ID to each API server. Each kube-apiserver | |
manages a [Lease](/docs/reference/generated/kubernetes-api/{{< param "version" >}}//#lease-v1-coordination-k8s-io) | |
in the _kube-apiserver-lease_ {{< glossary_tooltip text="namespaces" term_id="namespace">}}. | |
The Lease contains the unique ID for the kube-apiserver. If another kube-apiserver tries to join | |
same control plane, the additional API server [picks a unique ID that is not used within the cluster?] | |
Enabling this feature [provides benefits?]. | |
Each API server also exposes its own ID as a label dimension in its metrics: `TBD`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Updated the mechanism and the benefit.
The metrics didn't made it into alpha. Dropped the sentence.
/hold cancel hi @roycaihw with k/k prs merged in, Sig Docs would appreciate it if you could get the docs content ready to be reviewed early, if possible, before kubecon. It will give us more time to make sure we get both tech/docs review on time before the release. Thank you! Please don't forget to change the PR title once it's ready to be reviewed. (remove wip) |
and is not enabled by default. See | ||
[Feature Gates](/docs/reference/command-line-tools-reference/feature-gates/) | ||
for a general explanation of feature gates and how to enable and disable them. The | ||
name of the feature gate is "APIServerIdentity". You can enable API Server Identity |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hi there, please don't forget to add APIServerIdentity
to https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/ and a short description of what functionality it provides. thank you!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done. Copied the one-sentence descriptions from https://github.com/kubernetes/kubernetes/blob/master/staging/src/k8s.io/apiserver/pkg/features/kube_features.go
* `kube-system` The namespace for objects created by the Kubernetes system | ||
* `kube-public` This namespace is created automatically and is readable by all users (including those not authenticated). This namespace is mostly reserved for cluster usage, in case that some resources should be visible and readable publicly throughout the whole cluster. The public aspect of this namespace is only a convention, not a requirement. | ||
* `kube-node-lease` This namespace for the lease objects associated with each node which improves the performance of the node heartbeats as the cluster scales. | ||
* `kube-apiserver-lease` TODO(roycaihw): behind feature gate |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Remember to change “four” to “several”. Also, I suggest sorting the list.
Here are some wording suggestions that can either go in this PR or land after this one merges.
* `kube-system` The namespace for objects created by the Kubernetes system | |
* `kube-public` This namespace is created automatically and is readable by all users (including those not authenticated). This namespace is mostly reserved for cluster usage, in case that some resources should be visible and readable publicly throughout the whole cluster. The public aspect of this namespace is only a convention, not a requirement. | |
* `kube-node-lease` This namespace for the lease objects associated with each node which improves the performance of the node heartbeats as the cluster scales. | |
* `kube-apiserver-lease` TODO(roycaihw): behind feature gate | |
* `kube-apiserver-lease` *⚠????TODO????TODO????⚠* _behind feature gate_ | |
* `kube-node-lease` A namespace for the lease objects associated with each node. Node leases improve the performance of node heartbeats for large clusters. | |
* `kube-public` A namespace that is created automatically and is readable by all users (including those not authenticated). This namespace is mostly reserved for cluster usage, in case some resources should be visible and readable publicly throughout the whole cluster. | |
* `kube-system` General namespace for Kubernetes system objects. | |
{{< note >}} | |
Making the `kube-public` namespace and its contents world-readable is a convention, not a requirement. | |
{{< /note >}} |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for the suggestion. We decided to reuse kube-system
for this feature. Reverted the change.
Hi @roycaihw , please change the PR title to remove the words "wip: placeholder" when the PR is ready for review |
@roycaihw, please keep in mind that the Docs PR Ready for Review deadline is coming up on Monday, November 23 |
300bce0
to
b2e09a4
Compare
It's ready for review. Please take a look. Thanks! |
Hi @kubernetes/sig-api-machinery-pr-reviews , can we get a tech review (lgtm) |
/assign @kubernetes/sig-api-machinery-api-reviews |
/unasign @kubernetes/sig-api-machinery-api-reviews |
/remove-label kind/api-change |
@irvifa: The label(s) In response to this:
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. |
/remove-kind api-change |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm puzzled about the StorageVersionAPI feature gate that this PR is now adding.
@@ -150,6 +151,7 @@ different Kubernetes components. | |||
| `ServiceTopology` | `false` | Alpha | 1.17 | | | |||
| `SetHostnameAsFQDN` | `false` | Alpha | 1.19 | 1.19 | | |||
| `SetHostnameAsFQDN` | `true` | Beta | 1.20 | | | |||
| `StorageVersionAPI` | `false` | Alpha | 1.20 | | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is this intended? The PR title doesn't mention StorageVersionAPI
.
If I were documenting 2 different features I'd probably do that in 2 separate commits - it's easier to revert if ever needed.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes there's two separate things, storage version depends on the identity flag being on. @roycaihw is there a second PR documenting storage version? Should these be moved there?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Storage version API is not user-facing. The only user of it is the storage migrator. Currently there is no plan to have a k8s.io doc for it. We may document it in the storage migrator repo. cc @caesarxuchao
I removed this line.
(we have the k8s.io doc for apiserver-identity because it can be used for other features, e.g. priority & fairness)
b2e09a4
to
8bb995b
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM otherwise.
in the _kube-system_ {{< glossary_tooltip text="namespaces" term_id="namespace">}}. | ||
The Lease name is the unique ID for the kube-apiserver. The Lease contains a | ||
label `k8s.io/component=kube-apiserver`. Each kube-apiserver manages deleting | ||
identity leases for kube-apiservers that are gone. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Shall we also introduce the lease duration and gc period flags?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
added the flags
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hi, a bit more feedback.
label `k8s.io/component=kube-apiserver`. Each kube-apiserver manages deleting | ||
identity leases for kube-apiservers that are gone. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Each kube-apiserver manages deleting identity leases for kube-apiservers that are gone.
How is “gone” defined?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
updated with details. Thanks
Enabling this feature is a prerequisite for using features that involve HA API | ||
server coodination (e.g. the StorageVersion API feature). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
nits (we avoid Latin abbreviations; typo fix)
Enabling this feature is a prerequisite for using features that involve HA API | |
server coodination (e.g. the StorageVersion API feature). | |
Enabling this feature is a prerequisite for using features that involve HA API | |
server coordination (for example, the StorageVersion API feature). |
Is StorageVersion a kind
or the name of a feature gate? I'm not sure readers can work that out.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
it's the feature gate. Updated
8bb995b
to
6ca33fe
Compare
Hi @roycaihw if you address some of the comments above, I think this will be able to merge soon. |
6ca33fe
to
2ad9e02
Compare
LGTM label has been added. Git tree hash: d31ecd48abedb8bc0d556e60c04aaa4714089886
|
/approve |
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: sftim The full list of commands accepted by this bot can be found here. The pull request process is described here
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
enhancement issue: kubernetes/enhancements#1965