Traefik

Chart reference	Description
`coreweave/traefik`	CoreWeave’s Helm chart for deploying Traefik on CKS clusters

About Traefik

The CoreWeave Traefik Helm chart is based on the upstream Traefik chart. The CoreWeave chart includes additional templating for configurations commonly used in CKS clusters. The chart’s default values are set to work best on the CoreWeave platform. All code examples in this repository assume the default values. If you install the chart with different namespaces or resource names, update the values to match.

Configuration

The following sections describe the chart’s default Ingress behavior and how to enable TLS on Ingresses.

Ingress DNS

By default, the chart applies a wildcard hostname through a service.beta.kubernetes.io/external-hostname annotation:

service.beta.kubernetes.io/external-hostname: '*'

This lets Traefik route to Ingress hosts within the CKS cluster. CKS automatically suffixes the wildcard hostname (*) with the appropriate domain name for your cluster. For Services that don’t route through Traefik, specific DNS hostnames still take precedence. To retrieve the applied value at any time, use kubectl:

kubectl get svc traefik -n traefik -o=jsonpath='{.status.conditions[?(@.type=="ExternalRecords")].message}'

For more information on exposing Services, see How to: Expose a Service.

IngressRouteTCP and Kubernetes API proxy

The chart’s default values include a Traefik IngressRouteTCP TCP router for your cluster’s Kubernetes API server. This Service proxies HTTP traffic to your cluster over Direct Connect and provides TLS passthrough. To locate the hostname of this Service, run the following command:

kubectl get svc traefik-k8s -n traefik -o=jsonpath='{.status.conditions[?(@.type=="ExternalRecords")].message}'

When you reach the Kubernetes API server over Direct Connect, use the publicly resolvable hostname from the traefik-k8s Service, not the private load balancer IP. The API server certificate includes a DNS subject alternative name (SAN) for this hostname, but it doesn’t include the traefik-k8s load balancer IP. Connecting by IP causes TLS verification errors.For example, k8s.[ORG-ID]-[CLUSTER-NAME].coreweave.app. This hostname resolves to the private load balancer IP.

Configure client trust and authentication

The Traefik API proxy passes TLS through without terminating it, so clients connect directly to the Kubernetes API server. The API server presents a certificate signed by the cluster certificate authority (CA) and authenticates each request itself. A Managed Auth kubeconfig instead relies on a publicly trusted certificate and uses a CoreWeave API access token. If you change only the kubeconfig’s server value, certificate verification fails with an error such as x509: certificate signed by unknown authority on Linux and Windows, or certificate is not trusted on macOS. Adding the cluster CA fixes verification, but the API server still rejects the CoreWeave API access token. CKS publishes the cluster CA in the cluster-info ConfigMap in the kube-public namespace, which you can read without credentials. On a public cluster, read it from the unmanaged endpoint:

CA_DATA=$(curl -s https://api.[ORG-ID]-[CLUSTER-HASH].k8s.[ZONE].coreweave.com/api/v1/namespaces/kube-public/configmaps/cluster-info \
  | jq -r '.data.kubeconfig | capture("certificate-authority-data:\\s*(?<ca>\\S+)") | .ca')

If you already have a kubeconfig context that reaches the cluster, such as a Managed Auth kubeconfig through the Tailscale proxy in CoreWeave Managed Auth mode on a private cluster, read it with kubectl instead. Replace [CONTEXT] with that context’s name:

CA_DATA=$(kubectl --context [CONTEXT] get configmap cluster-info --namespace kube-public --output json \
  | jq -r '.data.kubeconfig | capture("certificate-authority-data:\\s*(?<ca>\\S+)") | .ca')

Add a cluster entry for the traefik-k8s hostname that uses the CA as its certificate-authority-data. Then create a context that pairs it with a user that authenticates through OIDC or an authentication webhook, such as the kubelogin user from Configure a kubectl context with kubelogin. Replace [USER] with that user’s name:

kubectl config set-cluster cks-traefik \
  --server=https://k8s.[ORG-ID]-[CLUSTER-NAME].coreweave.app
kubectl config set clusters.cks-traefik.certificate-authority-data "$CA_DATA"
kubectl config set-context cks-traefik --cluster=cks-traefik --user=[USER]

Requests through the Traefik API proxy don’t pass through Managed Auth, so CoreWeave IAM access policies don’t apply to them. Kubernetes RBAC authorizes them.

Create Ingresses with TLS

An Ingress with TLS requires cert-manager to create and manage the certificates. If you don’t have an existing deployment, you can deploy CoreWeave’s cert-manager and its subchart, cert-issuer for this purpose.

After you deploy the chart, you can use Traefik as the IngressClass for a Kubernetes Ingress with TLS. To create the TLS certificate, cert-manager uses the ClusterIssuer specified by the cert-manager.io/cluster-issuer annotation on the Ingress object.

Example chart

In this example manifest, the Ingress uses the default Let’s Encrypt ClusterIssuer from CoreWeave’s cert-issuer chart. You can also configure your own TLS certificate solution.

ingress-example.yaml - An example using Traefik with TLS and DNS

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    # This value must match either the ClusterIssuer created by Traefik,
    # or another pre-existing ClusterIssuer
        cert-manager.io/cluster-issuer: letsencrypt-prod
  name: ingress1
  namespace: namespace1
spec:
  ingressClassName: traefik
  rules:
  # The FQDN used to access this Ingress via the Traefik Service
  - host: &host ingress1.myorg-mycluster.coreweave.app
    http:
      paths:
      - backend:
          service:
            name: my-service
            port:
              number: 80
        path: /
        pathType: Prefix
  tls:
  - hosts:
    - *host
    # This secret will be automatically created for you
    secretName: ingress1-tls

For more information on Traefik as a Kubernetes Ingress provider, see the official Traefik documentation.

Gateway API

The chart can also run Traefik as a Gateway API controller. When you enable the Gateway API provider, the chart creates a GatewayClass named traefik and a Gateway named traefik-gateway in the traefik namespace. The Gateway uses the same traefik LoadBalancer Service as Ingress. Gateway API routes and Ingresses share one IP address and the cluster’s wildcard DNS name, so you can run both on the same Traefik Pods and move workloads from Ingress to Gateway API one at a time. The Traefik version in the chart supports the Gateway API standard channel, including HTTPRoute, GRPCRoute, TLSRoute, and BackendTLSPolicy. The standard channel CRDs on this page don’t support TCPRoute with Traefik. To use TCPRoute, install the experimental channel CRDs instead and set traefik.providers.kubernetesGateway.experimentalChannel: true. For details, see the Traefik Kubernetes Gateway API provider documentation. To follow these steps, you need kubectl and helm access to the cluster, with permissions to create cluster-scoped resources such as CRDs and the GatewayClass.

Each CKS cluster has one wildcard DNS name, and the traefik Service claims it. Don’t install a second Gateway API controller that creates its own LoadBalancer Service with the wildcard hostname, because only one Service can hold it. The second Service reports a HostnameConflict. See Why is my Service not getting a DNS name?

Install the Gateway API CRDs

Gateway API adds resource types through cluster-wide Custom Resource Definitions (CRDs) that every controller in the cluster shares. Install them before you enable the provider.

Separate install (recommended)
Bundled with the chart

Apply the standard channel CRDs from the Gateway API release:

kubectl apply --server-side \
  -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.6.3/standard-install.yaml

Before you upgrade the chart, check the Requirements section of Traefik’s Kubernetes Gateway provider documentation for the Gateway API version that the new Traefik version supports, and upgrade the CRDs to match.The CRDs stay in the cluster if you later uninstall or reconfigure Traefik.If another component, such as Cilium or a service mesh, already installed a compatible Gateway API CRD bundle, skip this step. Otherwise, coordinate the CRD upgrade with the component that manages them. To check the installed bundle version, run:

kubectl get crd gateways.gateway.networking.k8s.io \
  -o jsonpath='{.metadata.annotations.gateway\.networking\.k8s\.io/bundle-version}'

The chart can install the CRDs as part of the Traefik release, through the optional gateway-crds-helm dependency. The bundled CRDs use the standard channel.

When the chart installs the CRDs, the Traefik release owns them. If you uninstall Traefik or disable the gateway-crds-helm dependency in an upgrade, Helm deletes the CRDs. Kubernetes then deletes every Gateway API resource in the cluster, including resources that belong to other controllers. If cert-manager’s Gateway API support is enabled, cert-manager also fails to start on its next restart until you reinstall the CRDs.If an upgrade deletes the CRDs, the release still contains the Gateway and GatewayClass, so helm uninstall traefik fails with no matches for kind "Gateway". To uninstall, first reinstall the CRDs with the kubectl apply command in the Separate install tab.The install also fails if the CRDs already exist in the cluster, with the error exists and cannot be imported into the current release.

Add the following to your values file. Keep it in the file for every later upgrade:

traefik-gateway-values.yaml

gateway-crds-helm:
  crds:
    gatewayAPI:
      enabled: true
      channel: standard

Helm checks every resource kind in a release before it creates any of them, so the release that installs the CRDs can’t also create the Gateway and GatewayClass. Install the chart once with creation of those two resources turned off:

helm upgrade --install traefik coreweave/traefik \
  --namespace traefik \
  --create-namespace \
  -f traefik-gateway-values.yaml \
  --set traefik.gateway.enabled=false \
  --set traefik.gatewayClass.enabled=false

Then continue with Enable the Gateway API provider, which creates them.

Enable Gateway API support in cert-manager

As with Ingresses, cert-manager issues the TLS certificate for the Gateway from an annotation. Enable cert-manager’s Gateway API support and provide an existing issuer. The example uses letsencrypt-prod, which CoreWeave’s cert-manager chart creates when you enable the cert-issuers subchart. See Gateway API support on the cert-manager page. The chart doesn’t automatically restart cert-manager when you change values in an existing controller configuration. After you change an existing configuration or install the CRDs after cert-manager, restart cert-manager and confirm that its gateway-shim controller is running, as described on that page.

Enable the Gateway API provider

Add the provider, certificate annotation, and listener configuration to your Traefik values file. Keep your existing chart settings, including the CRD values if you use the bundled installation. Replace [ORG-ID] and [CLUSTER-NAME] with your organization ID and cluster name:

traefik-gateway-values.yaml

traefik:
  providers:
    kubernetesGateway:
      enabled: true
  gateway:
    annotations:
      # This value must match an existing ClusterIssuer
      cert-manager.io/cluster-issuer: letsencrypt-prod
    listeners:
      web:
        port: 8000
        protocol: HTTP
        namespacePolicy:
          from: All
      websecure:
        port: 8443
        protocol: HTTPS
        hostname: "*.[ORG-ID]-[CLUSTER-NAME].coreweave.app"
        certificateRefs:
          - kind: Secret
            name: gateway-wildcard-tls
        namespacePolicy:
          from: All

The configuration has the following settings and behavior:

Each listener port is a Traefik container port: 8000 for web and 8443 for websecure. The traefik Service publishes them on ports 80 and 443. The chart rejects listener ports that aren’t declared in traefik.ports. For a user-created Gateway, a listener whose port doesn’t match a configured Traefik entry point reports Accepted=False with the reason PortUnavailable.
namespacePolicy.from: All lets routes in any namespace attach to the Gateway. By default, a Gateway accepts routes only from its own namespace.
With the cert-manager.io/cluster-issuer annotation, cert-manager creates a Certificate for the websecure listener’s hostname and stores it in the gateway-wildcard-tls Secret. The listener terminates TLS with that Secret.
This example requests one wildcard certificate for the Gateway listener. It covers every route hostname under *.[ORG-ID]-[CLUSTER-NAME].coreweave.app, so routes don’t need their own certificates. For the Let’s Encrypt quota that applies to .coreweave.app certificates, see cert-manager.

Install or upgrade the chart with the values file:

helm upgrade --install traefik coreweave/traefik \
  --namespace traefik \
  --create-namespace \
  -f traefik-gateway-values.yaml

Verify that Traefik accepted the GatewayClass and programmed the Gateway:

kubectl get gatewayclass traefik
kubectl get gateway -n traefik

You should see output similar to the following:

NAME      CONTROLLER                      ACCEPTED   AGE
traefik   traefik.io/gateway-controller   True       11s

NAME              CLASS     ADDRESS          PROGRAMMED   AGE
traefik-gateway   traefik   [IP-ADDRESS]     True         11s

The ADDRESS is the IP address of the traefik LoadBalancer Service.

Traefik doesn’t create Pods or a Service for each Gateway. Every Gateway with gatewayClassName: traefik configures the same Traefik Pods and reports the traefik Service’s address. Its listener ports must match Traefik’s entry points. You can create your own Gateways instead of, or in addition to, the one the chart creates. To disable the chart’s Gateway, set traefik.gateway.enabled: false.

Wait for cert-manager to issue the certificate. cert-manager creates the Certificate in the traefik namespace, with the same name as the Secret:

kubectl wait certificate/gateway-wildcard-tls -n traefik --for=condition=Ready --timeout=300s
kubectl get certificate -n traefik

You should see output similar to the following:

NAME                   READY   SECRET                 AGE
gateway-wildcard-tls   True    gateway-wildcard-tls   14s

Until the Secret exists, the websecure listener reports ResolvedRefs: False with the reason InvalidCertificateRef. If no Certificate appears, check that cert-manager’s Gateway API support is enabled. To check the status of each listener, run:

kubectl get gateway traefik-gateway -n traefik \
  -o jsonpath='{range .status.listeners[*]}{.name}{": "}{range .conditions[*]}{.type}={.status} {end}{"\n"}{end}'

After the certificate is ready, both listeners report Programmed=True:

web: Accepted=True ResolvedRefs=True Programmed=True
websecure: Accepted=True ResolvedRefs=True Programmed=True

Route traffic with an HTTPRoute

Before you create the route, deploy a backend Service named my-service in namespace1 that serves HTTP on port 80, or replace those values with an existing Service and namespace. Replace [ORG-ID] and [CLUSTER-NAME] in the examples with your organization ID and cluster name. An HTTPRoute attaches to the Gateway through parentRefs and sends requests for its hostnames to a backend Service. In this example, the route sends traffic for app.[ORG-ID]-[CLUSTER-NAME].coreweave.app to the my-service Service on port 80:

httproute-example.yaml

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-app
  namespace: namespace1
spec:
  parentRefs:
    - name: traefik-gateway
      namespace: traefik
  hostnames:
    - app.[ORG-ID]-[CLUSTER-NAME].coreweave.app
  rules:
    - backendRefs:
        - name: my-service
          port: 80

Without a sectionName, the route attaches to both listeners and serves HTTP and HTTPS. Because the wildcard DNS name and wildcard certificate cover the hostname, you don’t need a DNS record or a certificate for each route. Apply the route and check that the Gateway accepted it:

kubectl apply -f httproute-example.yaml
kubectl get httproute my-app -n namespace1 \
  -o jsonpath='{range .status.parents[*].conditions[*]}{.type}={.status} {end}{"\n"}'

You should see Accepted=True ResolvedRefs=True. Then send a request:

curl https://app.[ORG-ID]-[CLUSTER-NAME].coreweave.app

Redirect HTTP to HTTPS

To serve a hostname over HTTPS only, attach one route to the web listener that redirects requests, and another to the websecure listener that sends them to the backend. The sectionName field selects the listener:

httproute-https-redirect.yaml

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-app-redirect
  namespace: namespace1
spec:
  parentRefs:
    - name: traefik-gateway
      namespace: traefik
      sectionName: web
  hostnames:
    - app.[ORG-ID]-[CLUSTER-NAME].coreweave.app
  rules:
    - filters:
        - type: RequestRedirect
          requestRedirect:
            scheme: https
            statusCode: 301
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-app
  namespace: namespace1
spec:
  parentRefs:
    - name: traefik-gateway
      namespace: traefik
      sectionName: websecure
  hostnames:
    - app.[ORG-ID]-[CLUSTER-NAME].coreweave.app
  rules:
    - backendRefs:
        - name: my-service
          port: 80

Create and manage clusters

Configure cluster access

Deploy workloads

Secure your cluster

Tutorials

Reference

About Traefik

Configuration

Ingress DNS

IngressRouteTCP and Kubernetes API proxy

Configure client trust and authentication

Create Ingresses with TLS

Example chart

Gateway API

Install the Gateway API CRDs

Enable Gateway API support in cert-manager

Enable the Gateway API provider

Route traffic with an HTTPRoute

Redirect HTTP to HTTPS

​About Traefik

​Configuration

​Ingress DNS

​IngressRouteTCP and Kubernetes API proxy

​Configure client trust and authentication

​Create Ingresses with TLS

​Example chart

​Gateway API

​Install the Gateway API CRDs

​Enable Gateway API support in cert-manager

​Enable the Gateway API provider

​Route traffic with an HTTPRoute

​Redirect HTTP to HTTPS

About Traefik

Configuration

Ingress DNS

IngressRouteTCP and Kubernetes API proxy

Configure client trust and authentication

Create Ingresses with TLS

Example chart

Gateway API

Install the Gateway API CRDs

Enable Gateway API support in cert-manager

Enable the Gateway API provider

Route traffic with an HTTPRoute

Redirect HTTP to HTTPS