- Release Signoff Checklist
- Summary
- Motivation
- Proposal
- Design Details
- Production Readiness Review Questionnaire
- Implementation History
- Drawbacks
- Alternatives
- Infrastructure Needed (Optional)
Items marked with (R) are required prior to targeting to a milestone / release.
- (R) Enhancement issue in release milestone, which links to KEP dir in kubernetes/enhancements (not the initial KEP PR)
- (R) KEP approvers have approved the KEP status as
implementable - (R) Design details are appropriately documented
- (R) Test plan is in place, giving consideration to SIG Architecture and SIG Testing input (including test refactors)
- e2e Tests for all Beta API Operations (endpoints)
- (R) Ensure GA e2e tests meet requirements for Conformance Tests
- (R) Minimum Two Week Window for GA e2e tests to prove flake free
- (R) Graduation criteria is in place
- (R) all GA Endpoints must be hit by Conformance Tests
- (R) Production readiness review completed
- (R) Production readiness review approved
- "Implementation History" section is up-to-date for milestone
- User-facing documentation has been created in kubernetes/website, for publication to kubernetes.io
- Supporting documentation—e.g., additional design documents, links to mailing list discussions/SIG meetings, relevant PRs/issues, release notes
The proposal aims to improve the Pod's ability to obtain the address of the node
- Field
status.hostIPsadded for Pod - Downward API support for
status.hostIPs
Applications that originally used IPv4 migrated to IPv6 during the dual-stack transition phase, For smooth migration, IP-related attributes should have both IPv4 and IPv6.
In order to maintain backwards compatibility for the core V1 API, this proposal retains the existing (singular) "HostIP" field in the core V1 version of the PodStatus V1 core API and adds a new array of structures that store host IPs along with associated metadata for that IP.
// HostIP represents the IP address of a host.
// IP address information. Each entry includes:
// IP: An IP address allocated to the host.
type HostIP struct {
// ip is an IP address (IPv4 or IPv6) assigned to the host
IP string
}
// HostIPs holds the IP addresses allocated to the host. If this field is specified, the 0th entry must
// match the hostIP field. This list is empty if no IPs have been allocated yet.
// +optional
HostIPs []HostIPPodStatus internally indicates that the original use of HostIP will remain unchanged, and HostIPs is added for subsequent use
// HostIP address information for entries in the (plural) HostIPs field.
// Each entry includes:
// IP: An IP address allocated to the host.
type HostIP struct {
// ip is an IP address (IPv4 or IPv6) assigned to the host
IP string `json:"ip,omitempty" protobuf:"bytes,1,opt,name=ip"`
}
// HostIPs holds the IP addresses allocated to the host. If this field is specified, the 0th entry must
// match the hostIP field. This list is empty if no IPs have been allocated yet.
// +optional
// +patchStrategy=merge
// +patchMergeKey=ip
HostIPs []HostIP `json:"hostIPs,omitempty" protobuf:"bytes,14,rep,name=hostIPs" patchStrategy:"merge" patchMergeKey:"ip"`See the making a singular field plural
The Downward API status.hostIP
will preserve the existing single IP address, and will be set to the default IP for each pod.
A new pod API field named status.hostIPs will contain a list of IP addresses.
The new pod API will have a slice of structures for the additional IP addresses.
Kubelet will translate the pod structures and return status.hostIPs as a comma-delimited string.
Here is an example of how to define a pluralized MY_HOST_IPS environmental
variable in a pod definition yaml file:
- name: MY_HOST_IPS
valueFrom:
fieldRef:
fieldPath: status.hostIPsThis definition will cause an environmental variable setting in the pod similar to the following:
# PodHostIPs FeatureGate is enabled
MY_HOST_IPS=fd00:10:20:0:3::3,10.20.3.3
# PodHostIPs FeatureGate is disabled
MY_HOST_IPS=
[x] I/we understand the owners of the involved components may require updates to existing tests to make this code solid enough prior to committing the changes necessary to implement this enhancement.
N/A
Every added code should have complete unit test coverage
N/A
Test whether FeatureGate behaves as expected when it is turned on or off
Test whether Downward API supports status.hostIPs
- If PodHostIPs FeatureGate is enabled:
status.hostIPsthere will be all host IPs (IPv4 and IPv6)
- Else:
status.hostIPswill be empty and the ApiServer will reject Downward APIstatus.hostIPs, if Pods already existing Downward APIstatus.hostIPs, ensure to ignore it and not affect others.
- Feature implemented behind a feature flag
- Add
status.hostIPsto the PodStatus API - Downward API support for
status.hostIPs
- Add
- Basic units and e2e tests completed and enabled
- Gather feedback from developers and users
- Expand the e2e tests with more scenarios
- Tests are in Testgrid and linked in the KEP
- 2 examples of end users using this field
- Allowing time for feedback
- Announce deprecation and support policy of the existing flag
- Two versions passed since introducing the functionality that deprecates the flag (to address version skew)
- Address feedback on usage/changed behavior, provided on GitHub issues
- Deprecate the flag
N/A
N/A
- Feature gate (also fill in values in
kep.yaml)- Feature gate name: PodHostIPs
- Components depending on the feature gate:
kube-apiserver,kubelet
- Other
- Describe the mechanism:
- Will enabling / disabling the feature require downtime of the control plane?
- Will enabling / disabling the feature require downtime or reprovisioning of a node?
It changes default behavior of k8s itself by automatically propagating HostIPs field.
Yes. Using the featuregate is the only way to enable/disable this feature.
The feature should continue to work just fine.
There are tests for feature enablement/disablement in util_test.go and validation_test.go.
If the dependent KEP 563-dual-stack is wrong, or could not get IP of host, or setting the field is crashing, this feature may fail to rollout/rollback. The field is only informative, it doesn't affect running workloads.
It will immediately update all running Pods on the node where this feature is enabled.
If any of these phenomena imply that the feature is abnormal and needs to be rolled back, the status.hostIPs field in the pod is empty, or it is updated frequently, or it causes other Pods to crash.
So if the apiserver_requests_total for pods increases significantly, this may indicate a problem.
It will test upgrade and rollback in e2e tests if it can be done in e2e.
Upgrade->downgrade->upgrade testing was done manually using the following steps:
Build and run the latest version using Kind
$ kind build node-image
$ kind create cluster --image kindest/node:latest
...
$ kubectl get node
NAME STATUS ROLES AGE VERSION
kind-control-plane Ready control-plane 6m40s v1.28.0-alpha.2.1529+c649dadff44981Deploy a webserver
apiVersion: apps/v1
kind: Deployment
metadata:
name: agnhost-server
labels:
app: agnhost-server
spec:
replicas: 1
selector:
matchLabels:
app: agnhost-server
template:
metadata:
labels:
app: agnhost-server
spec:
containers:
- name: agnhost
image: registry.k8s.io/e2e-test-images/agnhost:2.40
args:
- serve-hostname
- --port=80
ports:
- containerPort: 80Waiting pod be ready
$ kubectl get pod
NAME READY STATUS RESTARTS AGE
agnhost-server-76fb5c696c-2rqnh 1/1 Running 0 6sCheck pod hostIPs
$ kubectl get pod agnhost-server-76fb5c696c-2rqnh -o jsonpath='{.status.hostIPs}'
[{"ip":"172.18.0.2"}]To disable the feature
$ docker exec -it kind-control-plane bash
$ cat <<EOF >>/var/lib/kubelet/config.yaml
featureGates:
PodHostIPs: false
EOF
$ systemctl restart kubeletAdd more pod
$ kubectl scale --replicas=2 kubectl deploy/agnhost-serverCheck that both Pods do not have HostIPs
$ kubectl get pod -o jsonpath='{.items[*].status.hostIPs}'To enable the feature
$ docker exec -it kind-control-plane bash
$ sed -i 's/PodHostIPs: false/PodHostIPs: true/g' /var/lib/kubelet/config.yaml
$ systemctl restart kubeletCheck that both Pods have HostIPs
$ kubectl get pod -o jsonpath='{.items[*].status.hostIPs}'
[{"ip":"172.18.0.2"}] [{"ip":"172.18.0.2"}]Is the rollout accompanied by any deprecations and/or removals of features, APIs, fields of API types, flags, etc.?
No.
Pod has a status.hostIPs field and use it in downwardAPI to expose it.
- Events
- Event Reason:
- API .status
- Other field:
pod.status.hostIPsis not empty.
- Other field:
- Other (treat as last resort)
- Details:
- The feature is only informative, no increased failure rates during use the feature.
What are the SLIs (Service Level Indicators) an operator can use to determine the health of the service?
No, having a metric for this feature is overkill.
Are there any missing metrics that would be useful to have to improve observability of this feature?
No additional metrics needed for this new API field.
N/A
No
No
No
Yes.
- API type(s): Pod
- Estimated increase in size:
- New field in Status about 8 bytes, additional bytes based on whether IPv4(about 4 bytes) or IPv6(about 16 bytes) exists
Will enabling / using this feature result in increasing time taken by any operations covered by existing SLIs/SLOs?
No
Will enabling / using this feature result in non-negligible increase of resource usage (CPU, RAM, disk, IO, ...) in any components?
No
Can enabling / using this feature result in resource exhaustion of some node resources (PIDs, sockets, inodes, etc.)?
No
N/A -- since the feature is part of kube-apiserver.
N/A
N/A
- 2021-05-06: Initial KEP
- 2023-08-15: Alpha release with Kubernetes 1.28
- 2023-10-30: Beta release with Kubernetes 1.29
- 2024-03-01: GA release with Kubernetes 1.30
N/A
N/A
N/A