From 4272ac92a761cdd36b5c4c598d34fb965ad79f70 Mon Sep 17 00:00:00 2001 From: Dan Winship Date: Mon, 17 Aug 2020 19:29:01 -0400 Subject: [PATCH] Document the NodeAddressType values --- pkg/apis/core/types.go | 41 ++++++++++++++++++++++--- staging/src/k8s.io/api/core/v1/types.go | 41 ++++++++++++++++++++++--- 2 files changed, 74 insertions(+), 8 deletions(-) diff --git a/pkg/apis/core/types.go b/pkg/apis/core/types.go index a5ec5093617..3f4d7a80c75 100644 --- a/pkg/apis/core/types.go +++ b/pkg/apis/core/types.go @@ -4255,11 +4255,44 @@ type NodeAddressType string // These are valid values of node address type const ( - NodeHostName NodeAddressType = "Hostname" - NodeExternalIP NodeAddressType = "ExternalIP" - NodeInternalIP NodeAddressType = "InternalIP" - NodeExternalDNS NodeAddressType = "ExternalDNS" + // NodeHostName identifies a name of the node. Although every node can be assumed + // to have a NodeAddress of this type, its exact syntax and semantics are not + // defined, and are not consistent between different clusters. + NodeHostName NodeAddressType = "Hostname" + + // NodeInternalIP identifies an IP address which is assigned to one of the node's + // network interfaces. Every node should have at least one address of this type. + // + // An internal IP is normally expected to be reachable from every other node, but + // may not be visible to hosts outside the cluster. By default it is assumed that + // kube-apiserver can reach node internal IPs, though it is possible to configure + // clusters where this is not the case. + // + // NodeInternalIP is the default type of node IP, and does not necessarily imply + // that the IP is ONLY reachable internally. If a node has multiple internal IPs, + // no specific semantics are assigned to the additional IPs. + NodeInternalIP NodeAddressType = "InternalIP" + + // NodeExternalIP identifies an IP address which is, in some way, intended to be + // more usable from outside the cluster then an internal IP, though no specific + // semantics are defined. It may be a globally routable IP, though it is not + // required to be. + // + // External IPs may be assigned directly to an interface on the node, like a + // NodeInternalIP, or alternatively, packets sent to the external IP may be NAT'ed + // to an internal node IP rather than being delivered directly (making the IP less + // efficient for node-to-node traffic than a NodeInternalIP). + NodeExternalIP NodeAddressType = "ExternalIP" + + // NodeInternalDNS identifies a DNS name which resolves to an IP address which has + // the characteristics of a NodeInternalIP. The IP it resolves to may or may not + // be a listed NodeInternalIP address. NodeInternalDNS NodeAddressType = "InternalDNS" + + // NodeExternalDNS identifies a DNS name which resolves to an IP address which has + // the characteristics of a NodeExternalIP. The IP it resolves to may or may not + // be a listed NodeExternalIP address. + NodeExternalDNS NodeAddressType = "ExternalDNS" ) // NodeAddress represents node's address diff --git a/staging/src/k8s.io/api/core/v1/types.go b/staging/src/k8s.io/api/core/v1/types.go index be3a9ae73f9..97a721a046a 100644 --- a/staging/src/k8s.io/api/core/v1/types.go +++ b/staging/src/k8s.io/api/core/v1/types.go @@ -4931,11 +4931,44 @@ type NodeAddressType string // These are valid address type of node. const ( - NodeHostName NodeAddressType = "Hostname" - NodeExternalIP NodeAddressType = "ExternalIP" - NodeInternalIP NodeAddressType = "InternalIP" - NodeExternalDNS NodeAddressType = "ExternalDNS" + // NodeHostName identifies a name of the node. Although every node can be assumed + // to have a NodeAddress of this type, its exact syntax and semantics are not + // defined, and are not consistent between different clusters. + NodeHostName NodeAddressType = "Hostname" + + // NodeInternalIP identifies an IP address which is assigned to one of the node's + // network interfaces. Every node should have at least one address of this type. + // + // An internal IP is normally expected to be reachable from every other node, but + // may not be visible to hosts outside the cluster. By default it is assumed that + // kube-apiserver can reach node internal IPs, though it is possible to configure + // clusters where this is not the case. + // + // NodeInternalIP is the default type of node IP, and does not necessarily imply + // that the IP is ONLY reachable internally. If a node has multiple internal IPs, + // no specific semantics are assigned to the additional IPs. + NodeInternalIP NodeAddressType = "InternalIP" + + // NodeExternalIP identifies an IP address which is, in some way, intended to be + // more usable from outside the cluster then an internal IP, though no specific + // semantics are defined. It may be a globally routable IP, though it is not + // required to be. + // + // External IPs may be assigned directly to an interface on the node, like a + // NodeInternalIP, or alternatively, packets sent to the external IP may be NAT'ed + // to an internal node IP rather than being delivered directly (making the IP less + // efficient for node-to-node traffic than a NodeInternalIP). + NodeExternalIP NodeAddressType = "ExternalIP" + + // NodeInternalDNS identifies a DNS name which resolves to an IP address which has + // the characteristics of a NodeInternalIP. The IP it resolves to may or may not + // be a listed NodeInternalIP address. NodeInternalDNS NodeAddressType = "InternalDNS" + + // NodeExternalDNS identifies a DNS name which resolves to an IP address which has + // the characteristics of a NodeExternalIP. The IP it resolves to may or may not + // be a listed NodeExternalIP address. + NodeExternalDNS NodeAddressType = "ExternalDNS" ) // NodeAddress contains information for the node's address.