README.md

Switchboard

Switchboard is a Kubernetes operator that automates the creation of DNS records and TLS certificates when using Traefik v2 and its IngressRoute custom resource.

Traefik is an amazing reverse proxy and load balancer for Kubernetes, but has two major issues when using it in production:

• You cannot use Traefik to automatically issue TLS certificates from Let's Encrypt when running multiple Traefik instances (see the documentation).
• External tools do not support sourcing hostnames for DNS records from custom resources (including the Traefik IngressRoute CRD).

Switchboard solves these two issues by integrating the Traefik IngressRoute CRD with external tools (integrations):

• cert-manager can be used to create TLS certificates: Switchboard automatically creates a Certificate resource when an IngressRoute has the .spec.tls.secretName field set. The DNS alt names are taken either from .spec.tls.domains or (if unavailable) extracted automatically from all rules. The created certificate will then be used by Traefik to secure the connection.
• external-dns can be used to create DNS A records. First, DNS names are extracted from .spec.tls.domains and all rules as for the DNS alt names. Subsequently, a DNSEndpoint resource is created where all DNS names point to your Traefik instance. External-dns will pick up the DNSEndpoint and add appropriate DNS records in your configured provider.

Switchboard allows you to freely choose which integrations you want to use and can, thus, be easily adopted incrementally.

Note: This version of Switchboard is a complete rewrite of Switchboard v0.1 which will not be maintained anymore. Please refer to the appropriate tags in this repository if you still need to use it. Be aware that this version of Switchboard provides significantly more functionality while being considerably more reliable due to its integration with external-dns.

Installation

Switchboard can be conveniently installed using Helm version >= 3.8.0:

helm install switchboard oci://ghcr.io/borchero/charts/switchboard

For a full installation guide, consult the Switchboard Helm chart documentation.

Usage

As mentioned above, Switchboard processes Traefik IngressRoute resources. Let's assume, we have the following ingress route which forwards requests to an nginx backend:

apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
  name: my-ingress
spec:
  routes:
    - kind: Rule
      match: Host(`www.example.com`) && PathPrefix(`/images`)
      services:
        - name: nginx
  tls:
    secretName: www-tls-certificate

Switchboard now automatically extracts information from the ingress route object:

• The ingress route is concerned with a single host, namely www.example.com.
• Requests should be TLS-protected and a TLS certificate should be put into the www-tls-certificate secret.

This information is now passed onto all integrations that Switchboard is configured with.

Integrations

Integrations are entirely independent of each other. Enabling an integration causes Switchboard to generate an integration-specific resource (typically a CRD) for each ingress route that it processes.

Consult the Switchboard Helm chart documentation for an overview of how to enable individual integrations.

Cert-Manager

The cert-manager integration allows Switchboard to create a Certificate resource for an IngressRoute if the ingress (1) specifies .spec.tls.secretName and (2) references at least one host. Using the example ingress route from above, Switchboard creates the following resource:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  # The name is automatically generated from the name of the ingress route.
  name: my-ingress-tls
  labels:
    kubernetes.io/managed-by: switchboard
spec:
  # The issuer reference is obtained from the configuration of the cert-manager integration.
  issuerRef:
    kind: ClusterIssuer
    name: ca-issuer
  dnsNames:
    - www.example.com
  secretName: www-tls-certificate

External-DNS

The external-dns integration causes Switchboard to create a DNSEndpoint resource for an IngressRoute if the ingress references at least one host. Given the example ingress route above, Switchboard creates the following endpoint:

apiVersion: externaldns.k8s.io/v1alpha1
kind: DNSEndpoint
metadata:
  # The name is the same as the ingress's name.
  name: my-ingress
  labels:
    kubernetes.io/managed-by: switchboard
spec:
  endpoints:
    - dnsName: www.example.com
      recordTTL: 300
      recordType: A
      targets:
        # The target is the public (or, if unavailable, private) IP address of your Traefik
        # instance. The Kubernetes service to source the IP from is obtained from the configuration
        # of the external-dns integration.
        - 10.96.0.10

Customization

Manually Set Hosts

By default, Switchboard automatically extracts hosts from an ingress route by processing all rules and extracting hosts from Host(`...`) blocks. If you want to specify the set of hosts that are used for TLS certificates and DNS endpoints yourself, set .spec.tls.domains, e.g.:

spec:
  tls:
    domains:
      - main: example.com
        sans:
          - www.example.com

Disable Processing of an Ingress Route

By default, Switchboard process all IngressRoute objects in your cluster. While you can constrain Switchboard to only process objects with the kubernetes.io/ingress.class annotation set to a specific value (see the Switchboard Helm chart documentation), you can also disable processing for individual ingress routes by setting an additional annotation:

metadata:
  annotations:
    switchboard.borchero.com/ignore: "all"

By setting the ignore annotation to all (or true), Switchboard does not process the ingress route at all. For more fine-grained control, the value of this annotation can also be set to a comma-separated list of integrations (possible values cert-manager, external-dns).

License

Switchboard is licensed under the MIT License.