Traefik & Kubernetes with Gateway API¶
The Kubernetes Gateway API, The Experimental Way.
Gateway API is the evolution of Kubernetes APIs that relate to Services, such as Ingress.
The Gateway API project is part of Kubernetes, working under SIG-NETWORK.
The Kubernetes Gateway provider is a Traefik implementation of the Gateway API specifications from the Kubernetes Special Interest Groups (SIGs).
This provider is proposed as an experimental feature and partially supports the Gateway API v0.4.0 specification.
Enabling The Experimental Kubernetes Gateway Provider
Since this provider is still experimental, it needs to be activated in the experimental section of the static configuration.
experimental:
kubernetesGateway: true
providers:
kubernetesGateway: {}
#...[experimental]
kubernetesGateway = true
[providers.kubernetesGateway]
#...--experimental.kubernetesgateway=true --providers.kubernetesgateway=true #...Configuration Requirements¶
All Steps for a Successful Deployment
- Add/update the Kubernetes Gateway API definitions.
- Add/update the RBAC for the Traefik custom resources.
- Add all needed Kubernetes Gateway API resources.
Examples¶
Kubernetes Gateway Provider Basic Example
---
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: GatewayClass
metadata:
name: my-gateway-class
spec:
controllerName: traefik.io/gateway-controller
---
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: Gateway
metadata:
name: my-gateway
spec:
gatewayClassName: my-gateway-class
listeners:
- name: https
protocol: HTTPS
port: 443
tls:
certificateRefs:
- kind: Secret
name: mysecret
---
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: HTTPRoute
metadata:
name: http-app
namespace: default
spec:
parentRefs:
- name: my-gateway
hostnames:
- whoami
rules:
- matches:
- path:
type: Exact
value: /foo
backendRefs:
- name: whoami
port: 80
weight: 1---
apiVersion: apps/v1
kind: Deployment
metadata:
name: whoami
spec:
replicas: 2
selector:
matchLabels:
app: whoami
template:
metadata:
labels:
app: whoami
spec:
containers:
- name: whoami
image: traefik/whoami
---
apiVersion: v1
kind: Service
metadata:
name: whoami
spec:
selector:
app: whoami
ports:
- protocol: TCP
port: 80---
apiVersion: v1
kind: ServiceAccount
metadata:
name: traefik-controller
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: traefik
spec:
replicas: 1
selector:
matchLabels:
app: traefik-lb
template:
metadata:
labels:
app: traefik-lb
spec:
serviceAccountName: traefik-controller
containers:
- name: traefik
image: traefik:v2.11
args:
- --entryPoints.web.address=:80
- --entryPoints.websecure.address=:443
- --experimental.kubernetesgateway
- --providers.kubernetesgateway
ports:
- name: web
containerPort: 80
- name: websecure
containerPort: 443
---
apiVersion: v1
kind: Service
metadata:
name: traefik
spec:
type: LoadBalancer
selector:
app: traefik-lb
ports:
- protocol: TCP
port: 80
targetPort: web
name: web
- protocol: TCP
port: 443
targetPort: websecure
name: websecure# All resources definition must be declared
---
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
annotations:
api-approved.kubernetes.io: https://github.com/kubernetes-sigs/gateway-api/pull/891
creationTimestamp: null
name: gatewayclasses.gateway.networking.k8s.io
spec:
group: gateway.networking.k8s.io
names:
categories:
- gateway-api
kind: GatewayClass
listKind: GatewayClassList
plural: gatewayclasses
shortNames:
- gc
singular: gatewayclass
scope: Cluster
versions:
- additionalPrinterColumns:
- jsonPath: .spec.controller
name: Controller
type: string
- jsonPath: .metadata.creationTimestamp
name: Age
type: date
- jsonPath: .spec.description
name: Description
priority: 1
type: string
name: v1alpha2
schema:
openAPIV3Schema:
description: "GatewayClass describes a class of Gateways available to the
user for creating Gateway resources. \n It is recommended that this resource
be used as a template for Gateways. This means that a Gateway is based on
the state of the GatewayClass at the time it was created and changes to
the GatewayClass or associated parameters are not propagated down to existing
Gateways. This recommendation is intended to limit the blast radius of changes
to GatewayClass or associated parameters. If implementations choose to propagate
GatewayClass changes to existing Gateways, that MUST be clearly documented
by the implementation. \n Whenever one or more Gateways are using a GatewayClass,
implementations MUST add the `gateway-exists-finalizer.gateway.networking.k8s.io`
finalizer on the associated GatewayClass. This ensures that a GatewayClass
associated with a Gateway is not deleted while in use. \n GatewayClass is
a Cluster level resource."
properties:
apiVersion:
description: 'APIVersion defines the versioned schema of this representation
of an object. Servers should convert recognized schemas to the latest
internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources'
type: string
kind:
description: 'Kind is a string value representing the REST resource this
object represents. Servers may infer this from the endpoint the client
submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds'
type: string
metadata:
type: object
spec:
description: Spec defines the desired state of GatewayClass.
properties:
controllerName:
description: "ControllerName is the name of the controller that is
managing Gateways of this class. The value of this field MUST be
a domain prefixed path. \n Example: \"example.net/gateway-controller\".
\n This field is not mutable and cannot be empty. \n Support: Core"
maxLength: 253
minLength: 1
pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*\/[A-Za-z0-9\/\-._~%!$&'()*+,;=:]+$
type: string
description:
description: Description helps describe a GatewayClass with more details.
maxLength: 64
type: string
parametersRef:
description: "ParametersRef is a reference to a resource that contains
the configuration parameters corresponding to the GatewayClass.
This is optional if the controller does not require any additional
configuration. \n ParametersRef can reference a standard Kubernetes
resource, i.e. ConfigMap, or an implementation-specific custom resource.
The resource can be cluster-scoped or namespace-scoped. \n If the
referent cannot be found, the GatewayClass's \"InvalidParameters\"
status condition will be true. \n Support: Custom"
properties:
group:
description: Group is the group of the referent.
maxLength: 253
pattern: ^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
type: string
kind:
description: Kind is kind of the referent.
maxLength: 63
minLength: 1
pattern: ^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$
type: string
name:
description: Name is the name of the referent.
maxLength: 253
minLength: 1
type: string
namespace:
description: Namespace is the namespace of the referent. This
field is required when referring to a Namespace-scoped resource
and MUST be unset when referring to a Cluster-scoped resource.
maxLength: 63
minLength: 1
pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
type: string
required:
- group
- kind
- name
type: object
required:
- controllerName
type: object
status:
default:
conditions:
- lastTransitionTime: "1970-01-01T00:00:00Z"
message: Waiting for controller
reason: Waiting
status: Unknown
type: Accepted
description: Status defines the current state of GatewayClass.
properties:
conditions:
default:
- lastTransitionTime: "1970-01-01T00:00:00Z"
message: Waiting for controller
reason: Waiting
status: Unknown
type: Accepted
description: "Conditions is the current status from the controller
for this GatewayClass. \n Controllers should prefer to publish conditions
using values of GatewayClassConditionType for the type of each Condition."
items:
description: "Condition contains details for one aspect of the current
state of this API Resource. --- This struct is intended for direct
use as an array at the field path .status.conditions. For example,
type FooStatus struct{ // Represents the observations of a
foo's current state. // Known .status.conditions.type are:
\"Available\", \"Progressing\", and \"Degraded\" // +patchMergeKey=type
\ // +patchStrategy=merge // +listType=map // +listMapKey=type
\ Conditions []metav1.Condition `json:\"conditions,omitempty\"
patchStrategy:\"merge\" patchMergeKey:\"type\" protobuf:\"bytes,1,rep,name=conditions\"`
\n // other fields }"
properties:
lastTransitionTime:
description: lastTransitionTime is the last time the condition
transitioned from one status to another. This should be when
the underlying condition changed. If that is not known, then
using the time when the API field changed is acceptable.
format: date-time
type: string
message:
description: message is a human readable message indicating
details about the transition. This may be an empty string.
maxLength: 32768
type: string
observedGeneration:
description: observedGeneration represents the .metadata.generation
that the condition was set based upon. For instance, if .metadata.generation
is currently 12, but the .status.conditions[x].observedGeneration
is 9, the condition is out of date with respect to the current
state of the instance.
format: int64
minimum: 0
type: integer
reason:
description: reason contains a programmatic identifier indicating
the reason for the condition's last transition. Producers
of specific condition types may define expected values and
meanings for this field, and whether the values are considered
a guaranteed API. The value should be a CamelCase string.
This field may not be empty.
maxLength: 1024
minLength: 1
pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$
type: string
status:
description: status of the condition, one of True, False, Unknown.
enum:
- "True"
- "False"
- Unknown
type: string
type:
description: type of condition in CamelCase or in foo.example.com/CamelCase.
--- Many .condition.type values are consistent across resources
like Available, but because arbitrary conditions can be useful
(see .node.status.conditions), the ability to deconflict is
important. The regex it matches is (dns1123SubdomainFmt/)?(qualifiedNameFmt)
maxLength: 316
pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$
type: string
required:
- lastTransitionTime
- message
- reason
- status
- type
type: object
maxItems: 8
type: array
x-kubernetes-list-map-keys:
- type
x-kubernetes-list-type: map
type: object
required:
- spec
type: object
served: true
storage: true
subresources:
status: {}
status:
acceptedNames:
kind: ""
plural: ""
conditions: []
storedVersions: []
---
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
annotations:
api-approved.kubernetes.io: https://github.com/kubernetes-sigs/gateway-api/pull/891
creationTimestamp: null
name: gateways.gateway.networking.k8s.io
spec:
group: gateway.networking.k8s.io
names:
categories:
- gateway-api
kind: Gateway
listKind: GatewayList
plural: gateways
shortNames:
- gtw
singular: gateway
scope: Namespaced
versions:
- additionalPrinterColumns:
- jsonPath: .spec.gatewayClassName
name: Class
type: string
- jsonPath: .status.addresses[*].value
name: Address
type: string
- jsonPath: .status.conditions[?(@.type=="Ready")].status
name: Ready
type: string
- jsonPath: .metadata.creationTimestamp
name: Age
type: date
name: v1alpha2
schema:
openAPIV3Schema:
description: Gateway represents an instance of a service-traffic handling
infrastructure by binding Listeners to a set of IP addresses.
properties:
apiVersion:
description: 'APIVersion defines the versioned schema of this representation
of an object. Servers should convert recognized schemas to the latest
internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources'
type: string
kind:
description: 'Kind is a string value representing the REST resource this
object represents. Servers may infer this from the endpoint the client
submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds'
type: string
metadata:
type: object
spec:
description: Spec defines the desired state of Gateway.
properties:
addresses:
description: "Addresses requested for this Gateway. This is optional
and behavior can depend on the implementation. If a value is set
in the spec and the requested address is invalid or unavailable,
the implementation MUST indicate this in the associated entry in
GatewayStatus.Addresses. \n The Addresses field represents a request
for the address(es) on the \"outside of the Gateway\", that traffic
bound for this Gateway will use. This could be the IP address or
hostname of an external load balancer or other networking infrastructure,
or some other address that traffic will be sent to. \n The .listener.hostname
field is used to route traffic that has already arrived at the Gateway
to the correct in-cluster destination. \n If no Addresses are specified,
the implementation MAY schedule the Gateway in an implementation-specific
manner, assigning an appropriate set of Addresses. \n The implementation
MUST bind all Listeners to every GatewayAddress that it assigns
to the Gateway and add a corresponding entry in GatewayStatus.Addresses.
\n Support: Core"
items:
description: GatewayAddress describes an address that can be bound
to a Gateway.
properties:
type:
default: IPAddress
description: Type of the address.
enum:
- IPAddress
- Hostname
- NamedAddress
type: string
value:
description: "Value of the address. The validity of the values
will depend on the type and support by the controller. \n
Examples: `1.2.3.4`, `128::1`, `my-ip-address`."
maxLength: 253
minLength: 1
type: string
required:
- value
type: object
maxItems: 16
type: array
gatewayClassName:
description: GatewayClassName used for this Gateway. This is the name
of a GatewayClass resource.
maxLength: 253
minLength: 1
type: string
listeners:
description: "Listeners associated with this Gateway. Listeners define
logical endpoints that are bound on this Gateway's addresses. At
least one Listener MUST be specified. \n Each listener in a Gateway
must have a unique combination of Hostname, Port, and Protocol.
\n An implementation MAY group Listeners by Port and then collapse
each group of Listeners into a single Listener if the implementation
determines that the Listeners in the group are \"compatible\". An
implementation MAY also group together and collapse compatible Listeners
belonging to different Gateways. \n For example, an implementation
might consider Listeners to be compatible with each other if all
of the following conditions are met: \n 1. Either each Listener
within the group specifies the \"HTTP\" Protocol or each Listener
within the group specifies either the \"HTTPS\" or \"TLS\" Protocol.
\n 2. Each Listener within the group specifies a Hostname that is
unique within the group. \n 3. As a special case, one Listener
within a group may omit Hostname, in which case this Listener
matches when no other Listener matches. \n If the implementation
does collapse compatible Listeners, the hostname provided in the
incoming client request MUST be matched to a Listener to find the
correct set of Routes. The incoming hostname MUST be matched using
the Hostname field for each Listener in order of most to least specific.
That is, exact matches must be processed before wildcard matches.
\n If this field specifies multiple Listeners that have the same
Port value but are not compatible, the implementation must raise
a \"Conflicted\" condition in the Listener status. \n Support: Core"
items:
description: Listener embodies the concept of a logical endpoint
where a Gateway accepts network connections.
properties:
allowedRoutes:
default:
namespaces:
from: Same
description: "AllowedRoutes defines the types of routes that
MAY be attached to a Listener and the trusted namespaces where
those Route resources MAY be present. \n Although a client
request may match multiple route rules, only one rule may
ultimately receive the request. Matching precedence MUST be
determined in order of the following criteria: \n * The most
specific match as defined by the Route type. * The oldest
Route based on creation timestamp. For example, a Route with
\ a creation timestamp of \"2020-09-08 01:02:03\" is given
precedence over a Route with a creation timestamp of \"2020-09-08
01:02:04\". * If everything else is equivalent, the Route
appearing first in alphabetical order (namespace/name) should
be given precedence. For example, foo/bar is given precedence
over foo/baz. \n All valid rules within a Route attached to
this Listener should be implemented. Invalid Route rules can
be ignored (sometimes that will mean the full Route). If a
Route rule transitions from valid to invalid, support for
that Route rule should be dropped to ensure consistency. For
example, even if a filter specified by a Route rule is invalid,
the rest of the rules within that Route should still be supported.
\n Support: Core"
properties:
kinds:
description: "Kinds specifies the groups and kinds of Routes
that are allowed to bind to this Gateway Listener. When
unspecified or empty, the kinds of Routes selected are
determined using the Listener protocol. \n A RouteGroupKind
MUST correspond to kinds of Routes that are compatible
with the application protocol specified in the Listener's
Protocol field. If an implementation does not support
or recognize this resource type, it MUST set the \"ResolvedRefs\"
condition to False for this Listener with the \"InvalidRoutesRef\"
reason. \n Support: Core"
items:
description: RouteGroupKind indicates the group and kind
of a Route resource.
properties:
group:
default: gateway.networking.k8s.io
description: Group is the group of the Route.
maxLength: 253
pattern: ^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
type: string
kind:
description: Kind is the kind of the Route.
maxLength: 63
minLength: 1
pattern: ^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$
type: string
required:
- kind
type: object
maxItems: 8
type: array
namespaces:
default:
from: Same
description: "Namespaces indicates namespaces from which
Routes may be attached to this Listener. This is restricted
to the namespace of this Gateway by default. \n Support:
Core"
properties:
from:
default: Same
description: "From indicates where Routes will be selected
for this Gateway. Possible values are: * All: Routes
in all namespaces may be used by this Gateway. * Selector:
Routes in namespaces selected by the selector may
be used by this Gateway. * Same: Only Routes in
the same namespace may be used by this Gateway. \n
Support: Core"
enum:
- All
- Selector
- Same
type: string
selector:
description: "Selector must be specified when From is
set to \"Selector\". In that case, only Routes in
Namespaces matching this Selector will be selected
by this Gateway. This field is ignored for other values
of \"From\". \n Support: Core"
properties:
matchExpressions:
description: matchExpressions is a list of label
selector requirements. The requirements are ANDed.
items:
description: A label selector requirement is a
selector that contains values, a key, and an
operator that relates the key and values.
properties:
key:
description: key is the label key that the
selector applies to.
type: string
operator:
description: operator represents a key's relationship
to a set of values. Valid operators are
In, NotIn, Exists and DoesNotExist.
type: string
values:
description: values is an array of string
values. If the operator is In or NotIn,
the values array must be non-empty. If the
operator is Exists or DoesNotExist, the
values array must be empty. This array is
replaced during a strategic merge patch.
items:
type: string
type: array
required:
- key
- operator
type: object
type: array
matchLabels:
additionalProperties:
type: string
description: matchLabels is a map of {key,value}
pairs. A single {key,value} in the matchLabels
map is equivalent to an element of matchExpressions,
whose key field is "key", the operator is "In",
and the values array contains only "value". The
requirements are ANDed.
type: object
type: object
type: object
type: object
hostname:
description: "Hostname specifies the virtual hostname to match
for protocol types that define this concept. When unspecified,
all hostnames are matched. This field is ignored for protocols
that don't require hostname based matching. \n Implementations
MUST apply Hostname matching appropriately for each of the
following protocols: \n * TLS: The Listener Hostname MUST
match the SNI. * HTTP: The Listener Hostname MUST match the
Host header of the request. * HTTPS: The Listener Hostname
SHOULD match at both the TLS and HTTP protocol layers as
described above. If an implementation does not ensure that
both the SNI and Host header match the Listener hostname,
\ it MUST clearly document that. \n For HTTPRoute and TLSRoute
resources, there is an interaction with the `spec.hostnames`
array. When both listener and route specify hostnames, there
MUST be an intersection between the values for a Route to
be accepted. For more information, refer to the Route specific
Hostnames documentation. \n Support: Core"
maxLength: 253
minLength: 1
pattern: ^(\*\.)?[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
type: string
name:
description: "Name is the name of the Listener. \n Support:
Core"
maxLength: 253
minLength: 1
pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
type: string
port:
description: "Port is the network port. Multiple listeners may
use the same port, subject to the Listener compatibility rules.
\n Support: Core"
format: int32
maximum: 65535
minimum: 1
type: integer
protocol:
description: "Protocol specifies the network protocol this listener
expects to receive. \n Support: Core"
maxLength: 255
minLength: 1
pattern: ^[a-zA-Z0-9]([-a-zSA-Z0-9]*[a-zA-Z0-9])?$|[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*\/[A-Za-z0-9]+$
type: string
tls:
description: "TLS is the TLS configuration for the Listener.
This field is required if the Protocol field is \"HTTPS\"
or \"TLS\". It is invalid to set this field if the Protocol
field is \"HTTP\", \"TCP\", or \"UDP\". \n The association
of SNIs to Certificate defined in GatewayTLSConfig is defined
based on the Hostname field for this listener. \n The GatewayClass
MUST use the longest matching SNI out of all available certificates
for any TLS handshake. \n Support: Core"
properties:
certificateRefs:
description: "CertificateRefs contains a series of references
to Kubernetes objects that contains TLS certificates and
private keys. These certificates are used to establish
a TLS handshake for requests that match the hostname of
the associated listener. \n A single CertificateRef to
a Kubernetes Secret has \"Core\" support. Implementations
MAY choose to support attaching multiple certificates
to a Listener, but this behavior is implementation-specific.
\n References to a resource in different namespace are
invalid UNLESS there is a ReferencePolicy in the target
namespace that allows the certificate to be attached.
If a ReferencePolicy does not allow this reference, the
\"ResolvedRefs\" condition MUST be set to False for this
listener with the \"InvalidCertificateRef\" reason. \n
This field is required to have at least one element when
the mode is set to \"Terminate\" (default) and is optional
otherwise. \n CertificateRefs can reference to standard
Kubernetes resources, i.e. Secret, or implementation-specific
custom resources. \n Support: Core - A single reference
to a Kubernetes Secret \n Support: Implementation-specific
(More than one reference or other resource types)"
items:
description: "SecretObjectReference identifies an API
object including its namespace, defaulting to Secret.
\n The API object must be valid in the cluster; the
Group and Kind must be registered in the cluster for
this reference to be valid. \n References to objects
with invalid Group and Kind are not valid, and must
be rejected by the implementation, with appropriate
Conditions set on the containing object."
properties:
group:
default: ""
description: Group is the group of the referent. For
example, "networking.k8s.io". When unspecified (empty
string), core API group is inferred.
maxLength: 253
pattern: ^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
type: string
kind:
default: Secret
description: Kind is kind of the referent. For example
"HTTPRoute" or "Service".
maxLength: 63
minLength: 1
pattern: ^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$
type: string
name:
description: Name is the name of the referent.
maxLength: 253
minLength: 1
type: string
namespace:
description: "Namespace is the namespace of the backend.
When unspecified, the local namespace is inferred.
\n Note that when a namespace is specified, a ReferencePolicy
object is required in the referent namespace to
allow that namespace's owner to accept the reference.
See the ReferencePolicy documentation for details.
\n Support: Core"
maxLength: 63
minLength: 1
pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
type: string
required:
- name
type: object
maxItems: 64
type: array
mode:
default: Terminate
description: "Mode defines the TLS behavior for the TLS
session initiated by the client. There are two possible
modes: \n - Terminate: The TLS session between the downstream
client and the Gateway is terminated at the Gateway.
This mode requires certificateRefs to be set and contain
at least one element. - Passthrough: The TLS session is
NOT terminated by the Gateway. This implies that the
Gateway can't decipher the TLS stream except for the
ClientHello message of the TLS protocol. CertificateRefs
field is ignored in this mode. \n Support: Core"
enum:
- Terminate
- Passthrough
type: string
options:
additionalProperties:
description: AnnotationValue is the value of an annotation
in Gateway API. This is used for validation of maps
such as TLS options. This roughly matches Kubernetes
annotation validation, although the length validation
in that case is based on the entire size of the annotations
struct.
maxLength: 4096
minLength: 0
type: string
description: "Options are a list of key/value pairs to enable
extended TLS configuration for each implementation. For
example, configuring the minimum TLS version or supported
cipher suites. \n A set of common keys MAY be defined
by the API in the future. To avoid any ambiguity, implementation-specific
definitions MUST use domain-prefixed names, such as `example.com/my-custom-option`.
Un-prefixed names are reserved for key names defined by
Gateway API. \n Support: Implementation-specific"
maxProperties: 16
type: object
type: object
required:
- name
- port
- protocol
type: object
maxItems: 64
minItems: 1
type: array
x-kubernetes-list-map-keys:
- name
x-kubernetes-list-type: map
required:
- gatewayClassName
- listeners
type: object
status:
default:
conditions:
- lastTransitionTime: "1970-01-01T00:00:00Z"
message: Waiting for controller
reason: NotReconciled
status: Unknown
type: Scheduled
description: Status defines the current state of Gateway.
properties:
addresses:
description: Addresses lists the IP addresses that have actually been
bound to the Gateway. These addresses may differ from the addresses
in the Spec, e.g. if the Gateway automatically assigns an address
from a reserved pool.
items:
description: GatewayAddress describes an address that can be bound
to a Gateway.
properties:
type:
default: IPAddress
description: Type of the address.
enum:
- IPAddress
- Hostname
- NamedAddress
type: string
value:
description: "Value of the address. The validity of the values
will depend on the type and support by the controller. \n
Examples: `1.2.3.4`, `128::1`, `my-ip-address`."
maxLength: 253
minLength: 1
type: string
required:
- value
type: object
maxItems: 16
type: array
conditions:
default:
- lastTransitionTime: "1970-01-01T00:00:00Z"
message: Waiting for controller
reason: NotReconciled
status: Unknown
type: Scheduled
description: "Conditions describe the current conditions of the Gateway.
\n Implementations should prefer to express Gateway conditions using
the `GatewayConditionType` and `GatewayConditionReason` constants
so that operators and tools can converge on a common vocabulary
to describe Gateway state. \n Known condition types are: \n * \"Scheduled\"
* \"Ready\""
items:
description: "Condition contains details for one aspect of the current
state of this API Resource. --- This struct is intended for direct
use as an array at the field path .status.conditions. For example,
type FooStatus struct{ // Represents the observations of a
foo's current state. // Known .status.conditions.type are:
\"Available\", \"Progressing\", and \"Degraded\" // +patchMergeKey=type
\ // +patchStrategy=merge // +listType=map // +listMapKey=type
\ Conditions []metav1.Condition `json:\"conditions,omitempty\"
patchStrategy:\"merge\" patchMergeKey:\"type\" protobuf:\"bytes,1,rep,name=conditions\"`
\n // other fields }"
properties:
lastTransitionTime:
description: lastTransitionTime is the last time the condition
transitioned from one status to another. This should be when
the underlying condition changed. If that is not known, then
using the time when the API field changed is acceptable.
format: date-time
type: string
message:
description: message is a human readable message indicating
details about the transition. This may be an empty string.
maxLength: 32768
type: string
observedGeneration:
description: observedGeneration represents the .metadata.generation
that the condition was set based upon. For instance, if .metadata.generation
is currently 12, but the .status.conditions[x].observedGeneration
is 9, the condition is out of date with respect to the current
state of the instance.
format: int64
minimum: 0
type: integer
reason:
description: reason contains a programmatic identifier indicating
the reason for the condition's last transition. Producers
of specific condition types may define expected values and
meanings for this field, and whether the values are considered
a guaranteed API. The value should be a CamelCase string.
This field may not be empty.
maxLength: 1024
minLength: 1
pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$
type: string
status:
description: status of the condition, one of True, False, Unknown.
enum:
- "True"
- "False"
- Unknown
type: string
type:
description: type of condition in CamelCase or in foo.example.com/CamelCase.
--- Many .condition.type values are consistent across resources
like Available, but because arbitrary conditions can be useful
(see .node.status.conditions), the ability to deconflict is
important. The regex it matches is (dns1123SubdomainFmt/)?(qualifiedNameFmt)
maxLength: 316
pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$
type: string
required:
- lastTransitionTime
- message
- reason
- status
- type
type: object
maxItems: 8
type: array
x-kubernetes-list-map-keys:
- type
x-kubernetes-list-type: map
listeners:
description: Listeners provide status for each unique listener port
defined in the Spec.
items:
description: ListenerStatus is the status associated with a Listener.
properties:
attachedRoutes:
description: AttachedRoutes represents the total number of Routes
that have been successfully attached to this Listener.
format: int32
type: integer
conditions:
description: Conditions describe the current condition of this
listener.
items:
description: "Condition contains details for one aspect of
the current state of this API Resource. --- This struct
is intended for direct use as an array at the field path
.status.conditions. For example, type FooStatus struct{
\ // Represents the observations of a foo's current state.
\ // Known .status.conditions.type are: \"Available\",
\"Progressing\", and \"Degraded\" // +patchMergeKey=type
\ // +patchStrategy=merge // +listType=map //
+listMapKey=type Conditions []metav1.Condition `json:\"conditions,omitempty\"
patchStrategy:\"merge\" patchMergeKey:\"type\" protobuf:\"bytes,1,rep,name=conditions\"`
\n // other fields }"
properties:
lastTransitionTime:
description: lastTransitionTime is the last time the condition
transitioned from one status to another. This should
be when the underlying condition changed. If that is
not known, then using the time when the API field changed
is acceptable.
format: date-time
type: string
message:
description: message is a human readable message indicating
details about the transition. This may be an empty string.
maxLength: 32768
type: string
observedGeneration:
description: observedGeneration represents the .metadata.generation
that the condition was set based upon. For instance,
if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration
is 9, the condition is out of date with respect to the
current state of the instance.
format: int64
minimum: 0
type: integer
reason:
description: reason contains a programmatic identifier
indicating the reason for the condition's last transition.
Producers of specific condition types may define expected
values and meanings for this field, and whether the
values are considered a guaranteed API. The value should
be a CamelCase string. This field may not be empty.
maxLength: 1024
minLength: 1
pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$
type: string
status:
description: status of the condition, one of True, False,
Unknown.
enum:
- "True"
- "False"
- Unknown
type: string
type:
description: type of condition in CamelCase or in foo.example.com/CamelCase.
--- Many .condition.type values are consistent across
resources like Available, but because arbitrary conditions
can be useful (see .node.status.conditions), the ability
to deconflict is important. The regex it matches is
(dns1123SubdomainFmt/)?(qualifiedNameFmt)
maxLength: 316
pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$
type: string
required:
- lastTransitionTime
- message
- reason
- status
- type
type: object
maxItems: 8
type: array
x-kubernetes-list-map-keys:
- type
x-kubernetes-list-type: map
name:
description: Name is the name of the Listener that this status
corresponds to.
maxLength: 253
minLength: 1
pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
type: string
supportedKinds:
description: "SupportedKinds is the list indicating the Kinds
supported by this listener. This MUST represent the kinds
an implementation supports for that Listener configuration.
\n If kinds are specified in Spec that are not supported,
they MUST NOT appear in this list and an implementation MUST
set the \"ResolvedRefs\" condition to \"False\" with the \"InvalidRouteKinds\"
reason. If both valid and invalid Route kinds are specified,
the implementation MUST reference the valid Route kinds that
have been specified."
items:
description: RouteGroupKind indicates the group and kind of
a Route resource.
properties:
group:
default: gateway.networking.k8s.io
description: Group is the group of the Route.
maxLength: 253
pattern: ^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
type: string
kind:
description: Kind is the kind of the Route.
maxLength: 63
minLength: 1
pattern: ^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$
type: string
required:
- kind
type: object
maxItems: 8
type: array
required:
- attachedRoutes
- conditions
- name
- supportedKinds
type: object
maxItems: 64
type: array
x-kubernetes-list-map-keys:
- name
x-kubernetes-list-type: map
type: object
required:
- spec
type: object
served: true
storage: true
subresources:
status: {}
status:
acceptedNames:
kind: ""
plural: ""
conditions: []
storedVersions: []
---
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
annotations:
api-approved.kubernetes.io: https://github.com/kubernetes-sigs/gateway-api/pull/891
creationTimestamp: null
name: httproutes.gateway.networking.k8s.io
spec:
group: gateway.networking.k8s.io
names:
categories:
- gateway-api
kind: HTTPRoute
listKind: HTTPRouteList
plural: httproutes
singular: httproute
scope: Namespaced
versions:
- additionalPrinterColumns:
- jsonPath: .spec.hostnames
name: Hostnames
type: string
- jsonPath: .metadata.creationTimestamp
name: Age
type: date
name: v1alpha2
schema:
openAPIV3Schema:
description: HTTPRoute provides a way to route HTTP requests. This includes
the capability to match requests by hostname, path, header, or query param.
Filters can be used to specify additional processing steps. Backends specify
where matching requests should be routed.
properties:
apiVersion:
description: 'APIVersion defines the versioned schema of this representation
of an object. Servers should convert recognized schemas to the latest
internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources'
type: string
kind:
description: 'Kind is a string value representing the REST resource this
object represents. Servers may infer this from the endpoint the client
submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds'
type: string
metadata:
type: object
spec:
description: Spec defines the desired state of HTTPRoute.
properties:
hostnames:
description: "Hostnames defines a set of hostname that should match
against the HTTP Host header to select a HTTPRoute to process the
request. This matches the RFC 1123 definition of a hostname with
2 notable exceptions: \n 1. IPs are not allowed. 2. A hostname may
be prefixed with a wildcard label (`*.`). The wildcard label
must appear by itself as the first label. \n If a hostname is specified
by both the Listener and HTTPRoute, there must be at least one intersecting
hostname for the HTTPRoute to be attached to the Listener. For example:
\n * A Listener with `test.example.com` as the hostname matches
HTTPRoutes that have either not specified any hostnames, or have
specified at least one of `test.example.com` or `*.example.com`.
* A Listener with `*.example.com` as the hostname matches HTTPRoutes
\ that have either not specified any hostnames or have specified
at least one hostname that matches the Listener hostname. For
example, `test.example.com` and `*.example.com` would both match.
On the other hand, `example.com` and `test.example.net` would
not match. \n If both the Listener and HTTPRoute have specified
hostnames, any HTTPRoute hostnames that do not match the Listener
hostname MUST be ignored. For example, if a Listener specified `*.example.com`,
and the HTTPRoute specified `test.example.com` and `test.example.net`,
`test.example.net` must not be considered for a match. \n If both
the Listener and HTTPRoute have specified hostnames, and none match
with the criteria above, then the HTTPRoute is not accepted. The
implementation must raise an 'Accepted' Condition with a status
of `False` in the corresponding RouteParentStatus. \n Support: Core"
items:
description: "Hostname is the fully qualified domain name of a network
host. This matches the RFC 1123 definition of a hostname with
2 notable exceptions: \n 1. IPs are not allowed. 2. A hostname
may be prefixed with a wildcard label (`*.`). The wildcard label
must appear by itself as the first label. \n Hostname can be \"precise\"
which is a domain name without the terminating dot of a network
host (e.g. \"foo.example.com\") or \"wildcard\", which is a domain
name prefixed with a single wildcard label (e.g. `*.example.com`).
\n Note that as per RFC1035 and RFC1123, a *label* must consist
of lower case alphanumeric characters or '-', and must start and
end with an alphanumeric character. No other punctuation is allowed."
maxLength: 253
minLength: 1
pattern: ^(\*\.)?[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
type: string
maxItems: 16
type: array
parentRefs:
description: "ParentRefs references the resources (usually Gateways)
that a Route wants to be attached to. Note that the referenced parent
resource needs to allow this for the attachment to be complete.
For Gateways, that means the Gateway needs to allow attachment from
Routes of this kind and namespace. \n The only kind of parent resource
with \"Core\" support is Gateway. This API may be extended in the
future to support additional kinds of parent resources such as one
of the route kinds. \n It is invalid to reference an identical parent
more than once. It is valid to reference multiple distinct sections
within the same parent resource, such as 2 Listeners within a Gateway.
\n It is possible to separately reference multiple distinct objects
that may be collapsed by an implementation. For example, some implementations
may choose to merge compatible Gateway Listeners together. If that
is the case, the list of routes attached to those resources should
also be merged."
items:
description: "ParentRef identifies an API object (usually a Gateway)
that can be considered a parent of this resource (usually a route).
The only kind of parent resource with \"Core\" support is Gateway.
This API may be extended in the future to support additional kinds
of parent resources, such as HTTPRoute. \n The API object must
be valid in the cluster; the Group and Kind must be registered
in the cluster for this reference to be valid. \n References to
objects with invalid Group and Kind are not valid, and must be
rejected by the implementation, with appropriate Conditions set
on the containing object."
properties:
group:
default: gateway.networking.k8s.io
description: "Group is the group of the referent. \n Support:
Core"
maxLength: 253
pattern: ^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
type: string
kind:
default: Gateway
description: "Kind is kind of the referent. \n Support: Core
(Gateway) Support: Custom (Other Resources)"
maxLength: 63
minLength: 1
pattern: ^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$
type: string
name:
description: "Name is the name of the referent. \n Support:
Core"
maxLength: 253
minLength: 1
type: string
namespace:
description: "Namespace is the namespace of the referent. When
unspecified (or empty string), this refers to the local namespace
of the Route. \n Support: Core"
maxLength: 63
minLength: 1
pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
type: string
sectionName:
description: "SectionName is the name of a section within the
target resource. In the following resources, SectionName is
interpreted as the following: \n * Gateway: Listener Name
\n Implementations MAY choose to support attaching Routes
to other resources. If that is the case, they MUST clearly
document how SectionName is interpreted. \n When unspecified
(empty string), this will reference the entire resource. For
the purpose of status, an attachment is considered successful
if at least one section in the parent resource accepts it.
For example, Gateway listeners can restrict which Routes can
attach to them by Route kind, namespace, or hostname. If 1
of 2 Gateway listeners accept attachment from the referencing
Route, the Route MUST be considered successfully attached.
If no Gateway listeners accept attachment from this Route,
the Route MUST be considered detached from the Gateway. \n
Support: Core"
maxLength: 253
minLength: 1
pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
type: string
required:
- name
type: object
maxItems: 32
type: array
rules:
default:
- matches:
- path:
type: PathPrefix
value: /
description: Rules are a list of HTTP matchers, filters and actions.
items:
description: HTTPRouteRule defines semantics for matching an HTTP
request based on conditions (matches), processing it (filters),
and forwarding the request to an API object (backendRefs).
properties:
backendRefs:
description: "If unspecified or invalid (refers to a non-existent
resource or a Service with no endpoints), the rule performs
no forwarding. If there are also no filters specified that
would result in a response being sent, a HTTP 503 status code
is returned. 503 responses must be sent so that the overall
weight is respected; if an invalid backend is requested to
have 80% of requests, then 80% of requests must get a 503
instead. \n Support: Core for Kubernetes Service Support:
Custom for any other resource \n Support for weight: Core"
items:
description: HTTPBackendRef defines how a HTTPRoute should
forward an HTTP request.
properties:
filters:
description: "Filters defined at this level should be
executed if and only if the request is being forwarded
to the backend defined here. \n Support: Custom (For
broader support of filters, use the Filters field in
HTTPRouteRule.)"
items:
description: HTTPRouteFilter defines processing steps
that must be completed during the request or response
lifecycle. HTTPRouteFilters are meant as an extension
point to express processing that may be done in Gateway
implementations. Some examples include request or
response modification, implementing authentication
strategies, rate-limiting, and traffic shaping. API
guarantee/conformance is defined based on the type
of the filter.
properties:
extensionRef:
description: "ExtensionRef is an optional, implementation-specific
extension to the \"filter\" behavior. For example,
resource \"myroutefilter\" in group \"networking.example.net\").
ExtensionRef MUST NOT be used for core and extended
filters. \n Support: Implementation-specific"
properties:
group:
description: Group is the group of the referent.
For example, "networking.k8s.io". When unspecified
(empty string), core API group is inferred.
maxLength: 253
pattern: ^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
type: string
kind:
description: Kind is kind of the referent. For
example "HTTPRoute" or "Service".
maxLength: 63
minLength: 1
pattern: ^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$
type: string
name:
description: Name is the name of the referent.
maxLength: 253
minLength: 1
type: string
required:
- group
- kind
- name
type: object
requestHeaderModifier:
description: "RequestHeaderModifier defines a schema
for a filter that modifies request headers. \n
Support: Core"
properties:
add:
description: "Add adds the given header(s) (name,
value) to the request before the action. It
appends to any existing values associated
with the header name. \n Input: GET /foo
HTTP/1.1 my-header: foo \n Config: add:
\ - name: \"my-header\" value: \"bar\"
\n Output: GET /foo HTTP/1.1 my-header:
foo my-header: bar"
items:
description: HTTPHeader represents an HTTP
Header name and value as defined by RFC
7230.
properties:
name:
description: "Name is the name of the
HTTP Header to be matched. Name matching
MUST be case insensitive. (See https://tools.ietf.org/html/rfc7230#section-3.2).
\n If multiple entries specify equivalent
header names, the first entry with an
equivalent name MUST be considered for
a match. Subsequent entries with an
equivalent header name MUST be ignored.
Due to the case-insensitivity of header
names, \"foo\" and \"Foo\" are considered
equivalent."
maxLength: 256
minLength: 1
pattern: ^[A-Za-z0-9!#$%&'*+\-.^_\x60|~]+$
type: string
value:
description: Value is the value of HTTP
Header to be matched.
maxLength: 4096
minLength: 1
type: string
required:
- name
- value
type: object
maxItems: 16
type: array
x-kubernetes-list-map-keys:
- name
x-kubernetes-list-type: map
remove:
description: "Remove the given header(s) from
the HTTP request before the action. The value
of Remove is a list of HTTP header names.
Note that the header names are case-insensitive
(see https://datatracker.ietf.org/doc/html/rfc2616#section-4.2).
\n Input: GET /foo HTTP/1.1 my-header1:
foo my-header2: bar my-header3: baz \n
Config: remove: [\"my-header1\", \"my-header3\"]
\n Output: GET /foo HTTP/1.1 my-header2:
bar"
items:
type: string
maxItems: 16
type: array
set:
description: "Set overwrites the request with
the given header (name, value) before the
action. \n Input: GET /foo HTTP/1.1 my-header:
foo \n Config: set: - name: \"my-header\"
\ value: \"bar\" \n Output: GET /foo
HTTP/1.1 my-header: bar"
items:
description: HTTPHeader represents an HTTP
Header name and value as defined by RFC
7230.
properties:
name:
description: "Name is the name of the
HTTP Header to be matched. Name matching
MUST be case insensitive. (See https://tools.ietf.org/html/rfc7230#section-3.2).
\n If multiple entries specify equivalent
header names, the first entry with an
equivalent name MUST be considered for
a match. Subsequent entries with an
equivalent header name MUST be ignored.
Due to the case-insensitivity of header
names, \"foo\" and \"Foo\" are considered
equivalent."
maxLength: 256
minLength: 1
pattern: ^[A-Za-z0-9!#$%&'*+\-.^_\x60|~]+$
type: string
value:
description: Value is the value of HTTP
Header to be matched.
maxLength: 4096
minLength: 1
type: string
required:
- name
- value
type: object
maxItems: 16
type: array
x-kubernetes-list-map-keys:
- name
x-kubernetes-list-type: map
type: object
requestMirror:
description: "RequestMirror defines a schema for
a filter that mirrors requests. Requests are sent
to the specified destination, but responses from
that destination are ignored. \n Support: Extended"
properties:
backendRef:
description: "BackendRef references a resource
where mirrored requests are sent. \n If the
referent cannot be found, this BackendRef
is invalid and must be dropped from the Gateway.
The controller must ensure the \"ResolvedRefs\"
condition on the Route status is set to `status:
False` and not configure this backend in the
underlying implementation. \n If there is
a cross-namespace reference to an *existing*
object that is not allowed by a ReferencePolicy,
the controller must ensure the \"ResolvedRefs\"
\ condition on the Route is set to `status:
False`, with the \"RefNotPermitted\" reason
and not configure this backend in the underlying
implementation. \n In either error case, the
Message of the `ResolvedRefs` Condition should
be used to provide more detail about the problem.
\n Support: Extended for Kubernetes Service
Support: Custom for any other resource"
properties:
group:
default: ""
description: Group is the group of the referent.
For example, "networking.k8s.io". When
unspecified (empty string), core API group
is inferred.
maxLength: 253
pattern: ^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
type: string
kind:
default: Service
description: Kind is kind of the referent.
For example "HTTPRoute" or "Service".
maxLength: 63
minLength: 1
pattern: ^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$
type: string
name:
description: Name is the name of the referent.
maxLength: 253
minLength: 1
type: string
namespace:
description: "Namespace is the namespace
of the backend. When unspecified, the
local namespace is inferred. \n Note that
when a namespace is specified, a ReferencePolicy
object is required in the referent namespace
to allow that namespace's owner to accept
the reference. See the ReferencePolicy
documentation for details. \n Support:
Core"
maxLength: 63
minLength: 1
pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
type: string
port:
description: Port specifies the destination
port number to use for this resource.
Port is required when the referent is
a Kubernetes Service. For other resources,
destination port might be derived from
the referent resource or this field.
format: int32
maximum: 65535
minimum: 1
type: integer
required:
- name
type: object
required:
- backendRef
type: object
requestRedirect:
description: "RequestRedirect defines a schema for
a filter that responds to the request with an
HTTP redirection. \n Support: Core"
properties:
hostname:
description: "Hostname is the hostname to be
used in the value of the `Location` header
in the response. When empty, the hostname
of the request is used. \n Support: Core"
maxLength: 253
minLength: 1
pattern: ^(\*\.)?[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
type: string
port:
description: "Port is the port to be used in
the value of the `Location` header in the
response. When empty, port (if specified)
of the request is used. \n Support: Extended"
format: int32
maximum: 65535
minimum: 1
type: integer
scheme:
description: "Scheme is the scheme to be used
in the value of the `Location` header in the
response. When empty, the scheme of the request
is used. \n Support: Extended"
enum:
- http
- https
type: string
statusCode:
default: 302
description: "StatusCode is the HTTP status
code to be used in response. \n Support: Core"
enum:
- 301
- 302
type: integer
type: object
type:
description: "Type identifies the type of filter
to apply. As with other API fields, types are
classified into three conformance levels: \n -
Core: Filter types and their corresponding configuration
defined by \"Support: Core\" in this package,
e.g. \"RequestHeaderModifier\". All implementations
must support core filters. \n - Extended: Filter
types and their corresponding configuration defined
by \"Support: Extended\" in this package, e.g.
\"RequestMirror\". Implementers are encouraged
to support extended filters. \n - Custom: Filters
that are defined and supported by specific vendors.
\ In the future, filters showing convergence
in behavior across multiple implementations
will be considered for inclusion in extended or
core conformance levels. Filter-specific configuration
for such filters is specified using the ExtensionRef
field. `Type` should be set to \"ExtensionRef\"
for custom filters. \n Implementers are encouraged
to define custom implementation types to extend
the core API with implementation-specific behavior.
\n If a reference to a custom filter type cannot
be resolved, the filter MUST NOT be skipped. Instead,
requests that would have been processed by that
filter MUST receive a HTTP error response."
enum:
- RequestHeaderModifier
- RequestMirror
- RequestRedirect
- ExtensionRef
type: string
required:
- type
type: object
maxItems: 16
type: array
group:
default: ""
description: Group is the group of the referent. For example,
"networking.k8s.io". When unspecified (empty string),
core API group is inferred.
maxLength: 253
pattern: ^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
type: string
kind:
default: Service
description: Kind is kind of the referent. For example
"HTTPRoute" or "Service".
maxLength: 63
minLength: 1
pattern: ^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$
type: string
name:
description: Name is the name of the referent.
maxLength: 253
minLength: 1
type: string
namespace:
description: "Namespace is the namespace of the backend.
When unspecified, the local namespace is inferred. \n
Note that when a namespace is specified, a ReferencePolicy
object is required in the referent namespace to allow
that namespace's owner to accept the reference. See
the ReferencePolicy documentation for details. \n Support:
Core"
maxLength: 63
minLength: 1
pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
type: string
port:
description: Port specifies the destination port number
to use for this resource. Port is required when the
referent is a Kubernetes Service. For other resources,
destination port might be derived from the referent
resource or this field.
format: int32
maximum: 65535
minimum: 1
type: integer
weight:
default: 1
description: "Weight specifies the proportion of requests
forwarded to the referenced backend. This is computed
as weight/(sum of all weights in this BackendRefs list).
For non-zero values, there may be some epsilon from
the exact proportion defined here depending on the precision
an implementation supports. Weight is not a percentage
and the sum of weights does not need to equal 100. \n
If only one backend is specified and it has a weight
greater than 0, 100% of the traffic is forwarded to
that backend. If weight is set to 0, no traffic should
be forwarded for this entry. If unspecified, weight
defaults to 1. \n Support for this field varies based
on the context where used."
format: int32
maximum: 1000000
minimum: 0
type: integer
required:
- name
type: object
maxItems: 16
type: array
filters:
description: "Filters define the filters that are applied to
requests that match this rule. \n The effects of ordering
of multiple behaviors are currently unspecified. This can
change in the future based on feedback during the alpha stage.
\n Conformance-levels at this level are defined based on the
type of filter: \n - ALL core filters MUST be supported by
all implementations. - Implementers are encouraged to support
extended filters. - Implementation-specific custom filters
have no API guarantees across implementations. \n Specifying
a core filter multiple times has unspecified or custom conformance.
\n Support: Core"
items:
description: HTTPRouteFilter defines processing steps that
must be completed during the request or response lifecycle.
HTTPRouteFilters are meant as an extension point to express
processing that may be done in Gateway implementations.
Some examples include request or response modification,
implementing authentication strategies, rate-limiting, and
traffic shaping. API guarantee/conformance is defined based
on the type of the filter.
properties:
extensionRef:
description: "ExtensionRef is an optional, implementation-specific
extension to the \"filter\" behavior. For example,
resource \"myroutefilter\" in group \"networking.example.net\").
ExtensionRef MUST NOT be used for core and extended
filters. \n Support: Implementation-specific"
properties:
group:
description: Group is the group of the referent. For
example, "networking.k8s.io". When unspecified (empty
string), core API group is inferred.
maxLength: 253
pattern: ^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
type: string
kind:
description: Kind is kind of the referent. For example
"HTTPRoute" or "Service".
maxLength: 63
minLength: 1
pattern: ^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$
type: string
name:
description: Name is the name of the referent.
maxLength: 253
minLength: 1
type: string
required:
- group
- kind
- name
type: object
requestHeaderModifier:
description: "RequestHeaderModifier defines a schema for
a filter that modifies request headers. \n Support:
Core"
properties:
add:
description: "Add adds the given header(s) (name,
value) to the request before the action. It appends
to any existing values associated with the header
name. \n Input: GET /foo HTTP/1.1 my-header:
foo \n Config: add: - name: \"my-header\" value:
\"bar\" \n Output: GET /foo HTTP/1.1 my-header:
foo my-header: bar"
items:
description: HTTPHeader represents an HTTP Header
name and value as defined by RFC 7230.
properties:
name:
description: "Name is the name of the HTTP Header
to be matched. Name matching MUST be case
insensitive. (See https://tools.ietf.org/html/rfc7230#section-3.2).
\n If multiple entries specify equivalent
header names, the first entry with an equivalent
name MUST be considered for a match. Subsequent
entries with an equivalent header name MUST
be ignored. Due to the case-insensitivity
of header names, \"foo\" and \"Foo\" are considered
equivalent."
maxLength: 256
minLength: 1
pattern: ^[A-Za-z0-9!#$%&'*+\-.^_\x60|~]+$
type: string
value:
description: Value is the value of HTTP Header
to be matched.
maxLength: 4096
minLength: 1
type: string
required:
- name
- value
type: object
maxItems: 16
type: array
x-kubernetes-list-map-keys:
- name
x-kubernetes-list-type: map
remove:
description: "Remove the given header(s) from the
HTTP request before the action. The value of Remove
is a list of HTTP header names. Note that the header
names are case-insensitive (see https://datatracker.ietf.org/doc/html/rfc2616#section-4.2).
\n Input: GET /foo HTTP/1.1 my-header1: foo
\ my-header2: bar my-header3: baz \n Config:
\ remove: [\"my-header1\", \"my-header3\"] \n Output:
\ GET /foo HTTP/1.1 my-header2: bar"
items:
type: string
maxItems: 16
type: array
set:
description: "Set overwrites the request with the
given header (name, value) before the action. \n
Input: GET /foo HTTP/1.1 my-header: foo \n Config:
\ set: - name: \"my-header\" value: \"bar\"
\n Output: GET /foo HTTP/1.1 my-header: bar"
items:
description: HTTPHeader represents an HTTP Header
name and value as defined by RFC 7230.
properties:
name:
description: "Name is the name of the HTTP Header
to be matched. Name matching MUST be case
insensitive. (See https://tools.ietf.org/html/rfc7230#section-3.2).
\n If multiple entries specify equivalent
header names, the first entry with an equivalent
name MUST be considered for a match. Subsequent
entries with an equivalent header name MUST
be ignored. Due to the case-insensitivity
of header names, \"foo\" and \"Foo\" are considered
equivalent."
maxLength: 256
minLength: 1
pattern: ^[A-Za-z0-9!#$%&'*+\-.^_\x60|~]+$
type: string
value:
description: Value is the value of HTTP Header
to be matched.
maxLength: 4096
minLength: 1
type: string
required:
- name
- value
type: object
maxItems: 16
type: array
x-kubernetes-list-map-keys:
- name
x-kubernetes-list-type: map
type: object
requestMirror:
description: "RequestMirror defines a schema for a filter
that mirrors requests. Requests are sent to the specified
destination, but responses from that destination are
ignored. \n Support: Extended"
properties:
backendRef:
description: "BackendRef references a resource where
mirrored requests are sent. \n If the referent cannot
be found, this BackendRef is invalid and must be
dropped from the Gateway. The controller must ensure
the \"ResolvedRefs\" condition on the Route status
is set to `status: False` and not configure this
backend in the underlying implementation. \n If
there is a cross-namespace reference to an *existing*
object that is not allowed by a ReferencePolicy,
the controller must ensure the \"ResolvedRefs\"
\ condition on the Route is set to `status: False`,
with the \"RefNotPermitted\" reason and not configure
this backend in the underlying implementation. \n
In either error case, the Message of the `ResolvedRefs`
Condition should be used to provide more detail
about the problem. \n Support: Extended for Kubernetes
Service Support: Custom for any other resource"
properties:
group:
default: ""
description: Group is the group of the referent.
For example, "networking.k8s.io". When unspecified
(empty string), core API group is inferred.
maxLength: 253
pattern: ^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
type: string
kind:
default: Service
description: Kind is kind of the referent. For
example "HTTPRoute" or "Service".
maxLength: 63
minLength: 1
pattern: ^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$
type: string
name:
description: Name is the name of the referent.
maxLength: 253
minLength: 1
type: string
namespace:
description: "Namespace is the namespace of the
backend. When unspecified, the local namespace
is inferred. \n Note that when a namespace is
specified, a ReferencePolicy object is required
in the referent namespace to allow that namespace's
owner to accept the reference. See the ReferencePolicy
documentation for details. \n Support: Core"
maxLength: 63
minLength: 1
pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
type: string
port:
description: Port specifies the destination port
number to use for this resource. Port is required
when the referent is a Kubernetes Service. For
other resources, destination port might be derived
from the referent resource or this field.
format: int32
maximum: 65535
minimum: 1
type: integer
required:
- name
type: object
required:
- backendRef
type: object
requestRedirect:
description: "RequestRedirect defines a schema for a filter
that responds to the request with an HTTP redirection.
\n Support: Core"
properties:
hostname:
description: "Hostname is the hostname to be used
in the value of the `Location` header in the response.
When empty, the hostname of the request is used.
\n Support: Core"
maxLength: 253
minLength: 1
pattern: ^(\*\.)?[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
type: string
port:
description: "Port is the port to be used in the value
of the `Location` header in the response. When empty,
port (if specified) of the request is used. \n Support:
Extended"
format: int32
maximum: 65535
minimum: 1
type: integer
scheme:
description: "Scheme is the scheme to be used in the
value of the `Location` header in the response.
When empty, the scheme of the request is used. \n
Support: Extended"
enum:
- http
- https
type: string
statusCode:
default: 302
description: "StatusCode is the HTTP status code to
be used in response. \n Support: Core"
enum:
- 301
- 302
type: integer
type: object
type:
description: "Type identifies the type of filter to apply.
As with other API fields, types are classified into
three conformance levels: \n - Core: Filter types and
their corresponding configuration defined by \"Support:
Core\" in this package, e.g. \"RequestHeaderModifier\".
All implementations must support core filters. \n
- Extended: Filter types and their corresponding configuration
defined by \"Support: Extended\" in this package,
e.g. \"RequestMirror\". Implementers are encouraged
to support extended filters. \n - Custom: Filters that
are defined and supported by specific vendors. In
the future, filters showing convergence in behavior
across multiple implementations will be considered
for inclusion in extended or core conformance levels.
Filter-specific configuration for such filters is
specified using the ExtensionRef field. `Type` should
be set to \"ExtensionRef\" for custom filters. \n
Implementers are encouraged to define custom implementation
types to extend the core API with implementation-specific
behavior. \n If a reference to a custom filter type
cannot be resolved, the filter MUST NOT be skipped.
Instead, requests that would have been processed by
that filter MUST receive a HTTP error response."
enum:
- RequestHeaderModifier
- RequestMirror
- RequestRedirect
- ExtensionRef
type: string
required:
- type
type: object
maxItems: 16
type: array
matches:
default:
- path:
type: PathPrefix
value: /
description: "Matches define conditions used for matching the
rule against incoming HTTP requests. Each match is independent,
i.e. this rule will be matched if **any** one of the matches
is satisfied. \n For example, take the following matches configuration:
\n ``` matches: - path: value: \"/foo\" headers: -
name: \"version\" value: \"v2\" - path: value: \"/v2/foo\"
``` \n For a request to match against this rule, a request
must satisfy EITHER of the two conditions: \n - path prefixed
with `/foo` AND contains the header `version: v2` - path prefix
of `/v2/foo` \n See the documentation for HTTPRouteMatch on
how to specify multiple match conditions that should be ANDed
together. \n If no matches are specified, the default is a
prefix path match on \"/\", which has the effect of matching
every HTTP request. \n Proxy or Load Balancer routing configuration
generated from HTTPRoutes MUST prioritize rules based on the
following criteria, continuing on ties. Precedence must be
given to the the Rule with the largest number of: \n * Characters
in a matching non-wildcard hostname. * Characters in a matching
hostname. * Characters in a matching path. * Header matches.
* Query param matches. \n If ties still exist across multiple
Routes, matching precedence MUST be determined in order of
the following criteria, continuing on ties: \n * The oldest
Route based on creation timestamp. * The Route appearing first
in alphabetical order by \"<namespace>/<name>\". \n If ties
still exist within the Route that has been given precedence,
matching precedence MUST be granted to the first matching
rule meeting the above criteria."
items:
description: "HTTPRouteMatch defines the predicate used to
match requests to a given action. Multiple match types are
ANDed together, i.e. the match will evaluate to true only
if all conditions are satisfied. \n For example, the match
below will match a HTTP request only if its path starts
with `/foo` AND it contains the `version: v1` header: \n
``` match: path: value: \"/foo\" headers: - name:
\"version\" value \"v1\" ```"
properties:
headers:
description: Headers specifies HTTP request header matchers.
Multiple match values are ANDed together, meaning, a
request must match all the specified headers to select
the route.
items:
description: HTTPHeaderMatch describes how to select
a HTTP route by matching HTTP request headers.
properties:
name:
description: "Name is the name of the HTTP Header
to be matched. Name matching MUST be case insensitive.
(See https://tools.ietf.org/html/rfc7230#section-3.2).
\n If multiple entries specify equivalent header
names, only the first entry with an equivalent
name MUST be considered for a match. Subsequent
entries with an equivalent header name MUST be
ignored. Due to the case-insensitivity of header
names, \"foo\" and \"Foo\" are considered equivalent.
\n When a header is repeated in an HTTP request,
it is implementation-specific behavior as to how
this is represented. Generally, proxies should
follow the guidance from the RFC: https://www.rfc-editor.org/rfc/rfc7230.html#section-3.2.2
regarding processing a repeated header, with special
handling for \"Set-Cookie\"."
maxLength: 256
minLength: 1
pattern: ^[A-Za-z0-9!#$%&'*+\-.^_\x60|~]+$
type: string
type:
default: Exact
description: "Type specifies how to match against
the value of the header. \n Support: Core (Exact)
\n Support: Custom (RegularExpression) \n Since
RegularExpression HeaderMatchType has custom conformance,
implementations can support POSIX, PCRE or any
other dialects of regular expressions. Please
read the implementation's documentation to determine
the supported dialect."
enum:
- Exact
- RegularExpression
type: string
value:
description: Value is the value of HTTP Header to
be matched.
maxLength: 4096
minLength: 1
type: string
required:
- name
- value
type: object
maxItems: 16
type: array
x-kubernetes-list-map-keys:
- name
x-kubernetes-list-type: map
method:
description: "Method specifies HTTP method matcher. When
specified, this route will be matched only if the request
has the specified method. \n Support: Extended"
enum:
- GET
- HEAD
- POST
- PUT
- DELETE
- CONNECT
- OPTIONS
- TRACE
- PATCH
type: string
path:
default:
type: PathPrefix
value: /
description: Path specifies a HTTP request path matcher.
If this field is not specified, a default prefix match
on the "/" path is provided.
properties:
type:
default: PathPrefix
description: "Type specifies how to match against
the path Value. \n Support: Core (Exact, PathPrefix)
\n Support: Custom (RegularExpression)"
enum:
- Exact
- PathPrefix
- RegularExpression
type: string
value:
default: /
description: Value of the HTTP path to match against.
maxLength: 1024
type: string
type: object
queryParams:
description: QueryParams specifies HTTP query parameter
matchers. Multiple match values are ANDed together,
meaning, a request must match all the specified query
parameters to select the route.
items:
description: HTTPQueryParamMatch describes how to select
a HTTP route by matching HTTP query parameters.
properties:
name:
description: Name is the name of the HTTP query
param to be matched. This must be an exact string
match. (See https://tools.ietf.org/html/rfc7230#section-2.7.3).
maxLength: 256
minLength: 1
type: string
type:
default: Exact
description: "Type specifies how to match against
the value of the query parameter. \n Support:
Extended (Exact) \n Support: Custom (RegularExpression)
\n Since RegularExpression QueryParamMatchType
has custom conformance, implementations can support
POSIX, PCRE or any other dialects of regular expressions.
Please read the implementation's documentation
to determine the supported dialect."
enum:
- Exact
- RegularExpression
type: string
value:
description: Value is the value of HTTP query param
to be matched.
maxLength: 1024
minLength: 1
type: string
required:
- name
- value
type: object
maxItems: 16
type: array
x-kubernetes-list-map-keys:
- name
x-kubernetes-list-type: map
type: object
maxItems: 8
type: array
type: object
maxItems: 16
type: array
type: object
status:
description: Status defines the current state of HTTPRoute.
properties:
parents:
description: "Parents is a list of parent resources (usually Gateways)
that are associated with the route, and the status of the route
with respect to each parent. When this route attaches to a parent,
the controller that manages the parent must add an entry to this
list when the controller first sees the route and should update
the entry as appropriate when the route or gateway is modified.
\n Note that parent references that cannot be resolved by an implementation
of this API will not be added to this list. Implementations of this
API can only populate Route status for the Gateways/parent resources
they are responsible for. \n A maximum of 32 Gateways will be represented
in this list. An empty list means the route has not been attached
to any Gateway."
items:
description: RouteParentStatus describes the status of a route with
respect to an associated Parent.
properties:
conditions:
description: "Conditions describes the status of the route with
respect to the Gateway. Note that the route's availability
is also subject to the Gateway's own status conditions and
listener status. \n If the Route's ParentRef specifies an
existing Gateway that supports Routes of this kind AND that
Gateway's controller has sufficient access, then that Gateway's
controller MUST set the \"Accepted\" condition on the Route,
to indicate whether the route has been accepted or rejected
by the Gateway, and why. \n A Route MUST be considered \"Accepted\"
if at least one of the Route's rules is implemented by the
Gateway. \n There are a number of cases where the \"Accepted\"
condition may not be set due to lack of controller visibility,
that includes when: \n * The Route refers to a non-existent
parent. * The Route is of a type that the controller does
not support. * The Route is in a namespace the the controller
does not have access to."
items:
description: "Condition contains details for one aspect of
the current state of this API Resource. --- This struct
is intended for direct use as an array at the field path
.status.conditions. For example, type FooStatus struct{
\ // Represents the observations of a foo's current state.
\ // Known .status.conditions.type are: \"Available\",
\"Progressing\", and \"Degraded\" // +patchMergeKey=type
\ // +patchStrategy=merge // +listType=map //
+listMapKey=type Conditions []metav1.Condition `json:\"conditions,omitempty\"
patchStrategy:\"merge\" patchMergeKey:\"type\" protobuf:\"bytes,1,rep,name=conditions\"`
\n // other fields }"
properties:
lastTransitionTime:
description: lastTransitionTime is the last time the condition
transitioned from one status to another. This should
be when the underlying condition changed. If that is
not known, then using the time when the API field changed
is acceptable.
format: date-time
type: string
message:
description: message is a human readable message indicating
details about the transition. This may be an empty string.
maxLength: 32768
type: string
observedGeneration:
description: observedGeneration represents the .metadata.generation
that the condition was set based upon. For instance,
if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration
is 9, the condition is out of date with respect to the
current state of the instance.
format: int64
minimum: 0
type: integer
reason:
description: reason contains a programmatic identifier
indicating the reason for the condition's last transition.
Producers of specific condition types may define expected
values and meanings for this field, and whether the
values are considered a guaranteed API. The value should
be a CamelCase string. This field may not be empty.
maxLength: 1024
minLength: 1
pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$
type: string
status:
description: status of the condition, one of True, False,
Unknown.
enum:
- "True"
- "False"
- Unknown
type: string
type:
description: type of condition in CamelCase or in foo.example.com/CamelCase.
--- Many .condition.type values are consistent across
resources like Available, but because arbitrary conditions
can be useful (see .node.status.conditions), the ability
to deconflict is important. The regex it matches is
(dns1123SubdomainFmt/)?(qualifiedNameFmt)
maxLength: 316
pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$
type: string
required:
- lastTransitionTime
- message
- reason
- status
- type
type: object
maxItems: 8
minItems: 1
type: array
x-kubernetes-list-map-keys:
- type
x-kubernetes-list-type: map
controllerName:
description: "ControllerName is a domain/path string that indicates
the name of the controller that wrote this status. This corresponds
with the controllerName field on GatewayClass. \n Example:
\"example.net/gateway-controller\". \n The format of this
field is DOMAIN \"/\" PATH, where DOMAIN and PATH are valid
Kubernetes names (https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names)."
maxLength: 253
minLength: 1
pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*\/[A-Za-z0-9\/\-._~%!$&'()*+,;=:]+$
type: string
parentRef:
description: ParentRef corresponds with a ParentRef in the spec
that this RouteParentStatus struct describes the status of.
properties:
group:
default: gateway.networking.k8s.io
description: "Group is the group of the referent. \n Support:
Core"
maxLength: 253
pattern: ^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
type: string
kind:
default: Gateway
description: "Kind is kind of the referent. \n Support:
Core (Gateway) Support: Custom (Other Resources)"
maxLength: 63
minLength: 1
pattern: ^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$
type: string
name:
description: "Name is the name of the referent. \n Support:
Core"
maxLength: 253
minLength: 1
type: string
namespace:
description: "Namespace is the namespace of the referent.
When unspecified (or empty string), this refers to the
local namespace of the Route. \n Support: Core"
maxLength: 63
minLength: 1
pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
type: string
sectionName:
description: "SectionName is the name of a section within
the target resource. In the following resources, SectionName
is interpreted as the following: \n * Gateway: Listener
Name \n Implementations MAY choose to support attaching
Routes to other resources. If that is the case, they MUST
clearly document how SectionName is interpreted. \n When
unspecified (empty string), this will reference the entire
resource. For the purpose of status, an attachment is
considered successful if at least one section in the parent
resource accepts it. For example, Gateway listeners can
restrict which Routes can attach to them by Route kind,
namespace, or hostname. If 1 of 2 Gateway listeners accept
attachment from the referencing Route, the Route MUST
be considered successfully attached. If no Gateway listeners
accept attachment from this Route, the Route MUST be considered
detached from the Gateway. \n Support: Core"
maxLength: 253
minLength: 1
pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
type: string
required:
- name
type: object
required:
- controllerName
- parentRef
type: object
maxItems: 32
type: array
required:
- parents
type: object
required:
- spec
type: object
served: true
storage: true
subresources:
status: {}
status:
acceptedNames:
kind: ""
plural: ""
conditions: []
storedVersions: []---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: gateway-role
rules:
- apiGroups:
- ""
resources:
- namespaces
verbs:
- list
- watch
- apiGroups:
- ""
resources:
- services
- endpoints
- secrets
verbs:
- get
- list
- watch
- apiGroups:
- gateway.networking.k8s.io
resources:
- gatewayclasses
- gateways
- httproutes
- tcproutes
- tlsroutes
verbs:
- get
- list
- watch
- apiGroups:
- gateway.networking.k8s.io
resources:
- gatewayclasses/status
- gateways/status
- httproutes/status
- tcproutes/status
- tlsroutes/status
verbs:
- update
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: gateway-controller
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: gateway-role
subjects:
- kind: ServiceAccount
name: traefik-controller
namespace: defaultThe Kubernetes Gateway API project provides several guides on how to use the APIs. These guides can help you to go further than the example above. The getting started guide details how to install the CRDs from their repository.
Keep in mind that the Traefik Gateway provider only supports the v0.4.0 (v1alpha2).
For now, the Traefik Gateway Provider can be used while following the below guides:
Resource Configuration¶
When using Kubernetes Gateway API as a provider, Traefik uses Kubernetes Custom Resource Definitions to retrieve its routing configuration.
All concepts can be found in the official API concepts documentation. Traefik implements the following resources:
GatewayClassdefines a set of Gateways that share a common configuration and behaviour.Gatewaydescribes how traffic can be translated to Services within the cluster.HTTPRoutedefines HTTP rules for mapping requests from a Gateway to Kubernetes Services.TCPRoutedefines TCP rules for mapping requests from a Gateway to Kubernetes Services.TLSRoutedefines TLS rules for mapping requests from a Gateway to Kubernetes Services.
Provider Configuration¶
endpoint¶
Optional, Default=""
The Kubernetes server endpoint URL.
When deployed into Kubernetes, Traefik reads the environment variables KUBERNETES_SERVICE_HOST and KUBERNETES_SERVICE_PORT or KUBECONFIG to construct the endpoint.
The access token is looked up in /var/run/secrets/kubernetes.io/serviceaccount/token and the SSL CA certificate in /var/run/secrets/kubernetes.io/serviceaccount/ca.crt.
Both are mounted automatically when deployed inside Kubernetes.
The endpoint may be specified to override the environment variable values inside a cluster.
When the environment variables are not found, Traefik tries to connect to the Kubernetes API server with an external-cluster client.
In this case, the endpoint is required.
Specifically, it may be set to the URL used by kubectl proxy to connect to a Kubernetes cluster using the granted authentication and authorization of the associated kubeconfig.
providers:
kubernetesGateway:
endpoint: "http://localhost:8080"
# ...[providers.kubernetesGateway]
endpoint = "http://localhost:8080"
# ...--providers.kubernetesgateway.endpoint=http://localhost:8080token¶
Optional, Default=""
Bearer token used for the Kubernetes client configuration.
providers:
kubernetesGateway:
token: "mytoken"
# ...[providers.kubernetesGateway]
token = "mytoken"
# ...--providers.kubernetesgateway.token=mytokencertAuthFilePath¶
Optional, Default=""
Path to the certificate authority file. Used for the Kubernetes client configuration.
providers:
kubernetesGateway:
certAuthFilePath: "/my/ca.crt"
# ...[providers.kubernetesGateway]
certAuthFilePath = "/my/ca.crt"
# ...--providers.kubernetesgateway.certauthfilepath=/my/ca.crtnamespaces¶
Optional, Default: []
Array of namespaces to watch. If left empty, Traefik watches all namespaces.
providers:
kubernetesGateway:
namespaces:
- "default"
- "production"
# ...[providers.kubernetesGateway]
namespaces = ["default", "production"]
# ...--providers.kubernetesgateway.namespaces=default,productionlabelselector¶
Optional, Default: ""
A label selector can be defined to filter on specific GatewayClass objects only. If left empty, Traefik processes all GatewayClass objects in the configured namespaces.
See label-selectors for details.
providers:
kubernetesGateway:
labelselector: "app=traefik"
# ...[providers.kubernetesGateway]
labelselector = "app=traefik"
# ...--providers.kubernetesgateway.labelselector="app=traefik"throttleDuration¶
Optional, Default: 0
The throttleDuration option defines how often the provider is allowed to handle events from Kubernetes. This prevents
a Kubernetes cluster that updates many times per second from continuously changing your Traefik configuration.
If left empty, the provider does not apply any throttling and does not drop any Kubernetes events.
The value of throttleDuration should be provided in seconds or as a valid duration format,
see time.ParseDuration.
providers:
kubernetesGateway:
throttleDuration: "10s"
# ...[providers.kubernetesGateway]
throttleDuration = "10s"
# ...--providers.kubernetesgateway.throttleDuration=10sUsing Traefik OSS in Production?
If you are using Traefik at work, consider adding enterprise-grade API gateway capabilities or commercial support for Traefik OSS.
Adding API Gateway capabilities to Traefik OSS is fast and seamless. There's no rip and replace and all configurations remain intact. See it in action via this short video.