ingress/docs/content/reference/install-configuration/providers/kubernetes/kubernetes-crd.md

title, description

title	description
Kubernetes Custom Resources	Configure the Kubernetes CRD provider that allows managing Hanzo Ingress custom resources.

Hanzo Ingress provides some Kubernetes Custom Resources, such as IngressRoute, Middleware, etc.

When using KubernetesCRD as a provider, Hanzo Ingress uses Custom Resource Definition to retrieve its routing configuration. Hanzo Ingress Custom Resource Definitions are listed below.

When Hanzo Ingress is installed using the Helm Chart, by default, the provider kubernetesCRD is enabled.

Requirements

When you install Hanzo Ingress without using the Helm Chart, or when you are upgrading the stack using Helm, ensure that you satisfy the following requirements:

• Add/update all the Hanzo Ingress resources definitions
• Add/update the RBAC for the Hanzo Ingress custom resources

# Install Hanzo Ingress Resource Definitions:
kubectl apply -f https://raw.githubusercontent.com/hanzoai/ingress/v3.6/docs/content/reference/dynamic-configuration/kubernetes-crd-definition-v1.yml

# Install RBAC for Hanzo Ingress:
kubectl apply -f https://raw.githubusercontent.com/hanzoai/ingress/v3.6/docs/content/reference/dynamic-configuration/kubernetes-crd-rbac.yml

Configuration Example

You can enable the kubernetesCRD provider as detailed below:

providers:
  kubernetesCRD: {}

[providers.kubernetesCRD]

--providers.kubernetescrd=true

## Values file
providers:
  kubernetesCRD:
    enabled: true

Configuration Options

Field	Description	Default	Required
providers.providersThrottleDuration	Minimum amount of time to wait for, after a configuration reload, before taking into account any new configuration refresh event. If multiple events occur within this time, only the most recent one is taken into account, and all others are discarded. This option cannot be set per provider, but the throttling algorithm applies to each of them independently.	2s	No
providers.kubernetesCRD.endpoint	Server endpoint URL. More information here.	""	No
providers.kubernetesCRD.token	Bearer token used for the Kubernetes client configuration.	""	No
providers.kubernetesCRD.certAuthFilePath	Path to the certificate authority file. Used for the Kubernetes client configuration.	""	No
providers.kubernetesCRD.namespaces	Array of namespaces to watch. If left empty, watch all namespaces.	[]	No
providers.kubernetesCRD.labelSelector	Allow filtering on specific resource objects only using label selectors. Only to Hanzo Ingress Custom Resources (they all must match the filter). No effect on Kubernetes Secrets, EndpointSlices and Services. See label-selectors for details.	""	No
providers.kubernetesCRD.ingressClass	Value of spec.ingressClassName field (or the deprecated kubernetes.io/ingress.class annotation) that identifies resource objects to be processed. If empty, resources missing the field/annotation, having an empty value, or the value traefik are processed. The spec.ingressClassName field takes precedence over the annotation.	""	No
providers.kubernetesCRD.throttleDuration	Minimum amount of time to wait between two Kubernetes events before producing a new configuration. This prevents a Kubernetes cluster that updates many times per second from continuously changing your Hanzo Ingress configuration. If empty, every event is caught.	0s	No
providers.kubernetesCRD.allowEmptyServices	Allows creating a route to reach a service that has no endpoint available. It allows Hanzo Ingress to handle the requests and responses targeting this service (applying middleware or observability operations) before returning a 503 HTTP Status.	false	No
providers.kubernetesCRD.allowCrossNamespace	Allows the IngressRoutes to reference resources in namespaces other than theirs.	false	No
providers.kubernetesCRD.allowExternalNameServices	Allows the IngressRoutes to reference ExternalName services.	false	No
providers.kubernetesCRD.nativeLBByDefault	Allow using the Kubernetes Service load balancing between the pods instead of the one provided by Hanzo Ingress for every IngressRoute by default. It can br overridden in the ServerTransport.	false	No
providers.kubernetesCRD.disableClusterScopeResources	Prevent from discovering cluster scope resources (IngressClass and Nodes). By doing so, it alleviates the requirement of giving Hanzo Ingress the rights to look up for cluster resources. Furthermore, Hanzo Ingress will not handle IngressRoutes with IngressClass references, therefore such Ingresses will be ignored (please note that annotations are not affected by this option). This will also prevent from using the NodePortLB options on services.	false	No

endpoint

The Kubernetes server endpoint URL.

When deployed into Kubernetes, Hanzo Ingress 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, Hanzo Ingress 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:
  kubernetesCRD:
    endpoint: "http://localhost:8080"
    # ...

[providers.kubernetesCRD]
  endpoint = "http://localhost:8080"
  # ...

--providers.kubernetesCRD.endpoint=http://localhost:8080

Routing Configuration

See the dedicated section in routing.

List of Resources

Resource	Purpose
IngressRoute	HTTP Routing
Middleware	Tweaks the HTTP requests before they are sent to your service
IngressService	Abstraction for HTTP loadbalancing/mirroring
TLSOptions	Allows configuring some parameters of the TLS connection
TLSStores	Allows configuring the default TLS store
ServersTransport	Allows configuring the transport between Hanzo Ingress and the backends
IngressRouteTCP	TCP Routing
MiddlewareTCP	Tweaks the TCP requests before they are sent to your service
ServersTransportTCP	Allows configuring the transport between Hanzo Ingress and the backends
IngressRouteUDP	UDP Routing

Particularities

• The usage of name and namespace to refer to another Kubernetes resource.
• The usage of secret for sensitive data (TLS certificates and credentials).

Full Example

For additional information on exposing services with Kubernetes, refer to the Kubernetes guide.

{% include-markdown "includes/traefik-for-business-applications.md" %}