diff --git a/apis/v1alpha1/gateway_types.go b/apis/v1alpha1/gateway_types.go
index 08c2a6f7b3..a61e1075b7 100644
--- a/apis/v1alpha1/gateway_types.go
+++ b/apis/v1alpha1/gateway_types.go
@@ -484,8 +484,14 @@ type GatewayAddress struct {
// AddressType defines how a network address is represented as a text string.
// Valid AddressType values are:
//
-// * "IPAddress"
-// * "NamedAddress"
+// * "IPAddress": an IPv4 or IPv6 address
+// * "NamedAddress": an opaque identifier. The interpretation
+// of the name is dependent on the controller. If a NamedAddress is
+// requested but unsupported by an implementation, the controller
+// should raise the "Detached" listener status condition on the Gateway
+// with the "UnsupportedAddress" reason.
+//
+// A NamedAddress might be a cloud-dependent ID for a "static" or "elastic" IP
//
// +kubebuilder:validation:Enum=IPAddress;NamedAddress
type AddressType string
@@ -503,7 +509,7 @@ const (
// Support: Extended.
IPAddressType AddressType = "IPAddress"
- // NamedAddressType is an address selected by name. The interpretation
+ // NamedAddressType is an opaque identifier. The interpretation
// of the name is dependent on the controller. If a NamedAddress is
// requested but unsupported by an implementation, the controller
// should raise the "Detached" listener status condition on the Gateway
diff --git a/docs-src/spec.md b/docs-src/spec.md
index 1119b90108..7ba5098d60 100644
--- a/docs-src/spec.md
+++ b/docs-src/spec.md
@@ -891,9 +891,14 @@ UDPRouteStatus
AddressType defines how a network address is represented as a text string.
Valid AddressType values are:
-- “IPAddress”
-- “NamedAddress”
+- “IPAddress”: an IPv4 or IPv6 address
+- “NamedAddress”: an opaque identifier. The interpretation
+of the name is dependent on the controller. If a NamedAddress is
+requested but unsupported by an implementation, the controller
+should raise the “Detached” listener status condition on the Gateway
+with the “UnsupportedAddress” reason.
+A NamedAddress might be a cloud-dependent ID for a “static” or “elastic” IP
BackendPolicyConditionType
(string alias)
diff --git a/docs/spec/index.html b/docs/spec/index.html
index 760d7fd42a..74914fee5e 100644
--- a/docs/spec/index.html
+++ b/docs/spec/index.html
@@ -1422,9 +1422,14 @@ AddressType
AddressType defines how a network address is represented as a text string.
Valid AddressType values are:
-- “IPAddress”
-- “NamedAddress”
+- “IPAddress”: an IPv4 or IPv6 address
+- “NamedAddress”: an opaque identifier. The interpretation
+of the name is dependent on the controller. If a NamedAddress is
+requested but unsupported by an implementation, the controller
+should raise the “Detached” listener status condition on the Gateway
+with the “UnsupportedAddress” reason.
+A NamedAddress might be a cloud-dependent ID for a “static” or “elastic” IP
BackendPolicyConditionType
(string alias)