{"id":13581600,"url":"https://github.com/borchero/switchboard","last_synced_at":"2025-04-12T20:47:22.681Z","repository":{"id":37184199,"uuid":"259491817","full_name":"borchero/switchboard","owner":"borchero","description":"Kubernetes Operator for Automatically Issuing DNS Records and TLS Certificates for Traefik Ingress Routes.","archived":false,"fork":false,"pushed_at":"2025-03-31T17:59:55.000Z","size":438,"stargazers_count":159,"open_issues_count":11,"forks_count":15,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-12T20:46:47.319Z","etag":null,"topics":["dns","kubernetes","kubernetes-crd","kubernetes-operator","networking"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/borchero.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/funding.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"borchero"}},"created_at":"2020-04-28T00:44:41.000Z","updated_at":"2025-04-12T13:34:00.000Z","dependencies_parsed_at":"2023-11-07T01:48:07.387Z","dependency_job_id":"29da41b7-269d-4d47-8796-44618abfee50","html_url":"https://github.com/borchero/switchboard","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/borchero%2Fswitchboard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/borchero%2Fswitchboard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/borchero%2Fswitchboard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/borchero%2Fswitchboard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/borchero","download_url":"https://codeload.github.com/borchero/switchboard/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248631718,"owners_count":21136559,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dns","kubernetes","kubernetes-crd","kubernetes-operator","networking"],"created_at":"2024-08-01T15:02:07.166Z","updated_at":"2025-04-12T20:47:22.646Z","avatar_url":"https://github.com/borchero.png","language":"Go","funding_links":["https://github.com/sponsors/borchero"],"categories":["Go"],"sub_categories":[],"readme":"# Switchboard\n\n![License](https://img.shields.io/github/license/borchero/switchboard)\n[![Artifact Hub](https://img.shields.io/endpoint?url=https://artifacthub.io/badge/repository/switchboard)](https://artifacthub.io/packages/search?repo=switchboard)\n[![CI - Application](https://github.com/borchero/switchboard/actions/workflows/ci-application.yml/badge.svg?branch=main)](https://github.com/borchero/switchboard/actions/workflows/ci-application.yml)\n[![CI - Chart](https://github.com/borchero/switchboard/actions/workflows/ci-chart.yml/badge.svg?branch=main)](https://github.com/borchero/switchboard/actions/workflows/ci-chart.yml)\n[![codecov](https://codecov.io/gh/borchero/switchboard/branch/main/graph/badge.svg?token=CI8KJLDRUP)](https://codecov.io/gh/borchero/switchboard)\n\nSwitchboard is a Kubernetes operator that automates the creation of DNS records and TLS\ncertificates when using [Traefik](https://github.com/traefik/traefik) v2 and its\n[`IngressRoute` custom resource](https://doc.traefik.io/traefik/routing/providers/kubernetes-crd/#kind-ingressroute).\n\nTraefik is an amazing reverse proxy and load balancer for Kubernetes, but has two major issues when\nusing it in production:\n\n- You cannot use Traefik to automatically issue TLS certificates from Let's Encrypt when running\n  multiple Traefik instances (see\n  [the documentation](https://doc.traefik.io/traefik/providers/kubernetes-crd/#letsencrypt-support-with-the-custom-resource-definition-provider)).\n- External tools do not support sourcing hostnames for DNS records from custom resources (including\n  the Traefik `IngressRoute` CRD).\n\nSwitchboard solves these two issues by integrating the Traefik `IngressRoute` CRD with external\ntools (_integrations_):\n\n- [cert-manager](https://cert-manager.io) can be used to create TLS certificates: Switchboard\n  automatically creates a `Certificate` resource when an `IngressRoute` has the\n  `.spec.tls.secretName` field set. The DNS alt names are taken either from `.spec.tls.domains` or\n  (if unavailable) extracted automatically from all rules. The created certificate will then be\n  used by Traefik to secure the connection.\n- [external-dns](https://github.com/kubernetes-sigs/external-dns) can be used to create DNS A\n  records. First, DNS names are extracted from `.spec.tls.domains` and all rules as for the DNS alt\n  names. Subsequently, a `DNSEndpoint` resource is created where all DNS names point to your\n  Traefik instance. External-dns will pick up the `DNSEndpoint` and add appropriate DNS records in\n  your configured provider.\n\nSwitchboard allows you to freely choose which integrations you want to use and can, thus, be easily\nadopted incrementally.\n\n_Note: This version of Switchboard is a complete rewrite of Switchboard v0.1 which will not be\nmaintained anymore. Please refer to the appropriate tags in this repository if you still need to\nuse it. Be aware that this version of Switchboard provides significantly more functionality while\nbeing considerably more reliable due to its integration with external-dns._\n\n## Installation\n\nSwitchboard can be conveniently installed using [Helm](https://helm.sh) version `\u003e= 3.8.0`:\n\n```bash\nhelm install switchboard oci://ghcr.io/borchero/charts/switchboard\n```\n\nFor a full installation guide, consult the\n[Switchboard Helm chart documentation](./chart/README.md).\n\n## Usage\n\nAs mentioned above, Switchboard processes Traefik `IngressRoute` resources. Let's assume, we have\nthe following ingress route which forwards requests to an nginx backend:\n\n```yaml\napiVersion: traefik.io/v1alpha1\nkind: IngressRoute\nmetadata:\n  name: my-ingress\nspec:\n  routes:\n    - kind: Rule\n      match: Host(`www.example.com`) \u0026\u0026 PathPrefix(`/images`)\n      services:\n        - name: nginx\n  tls:\n    secretName: www-tls-certificate\n```\n\nSwitchboard now automatically extracts information from the ingress route object:\n\n- The ingress route is concerned with a single host, namely `www.example.com`.\n- Requests should be TLS-protected and a TLS certificate should be put into the\n  `www-tls-certificate` secret.\n\nThis information is now passed onto all _integrations_ that Switchboard is configured with.\n\n### Integrations\n\nIntegrations are entirely independent of each other. Enabling an integration causes Switchboard to\ngenerate an integration-specific resource (typically a CRD) for each ingress route that it\nprocesses.\n\nConsult the [Switchboard Helm chart documentation](./chart/README.md) for an overview of how to\nenable individual integrations.\n\n#### Cert-Manager\n\nThe cert-manager integration allows Switchboard to create a `Certificate` resource for an\n`IngressRoute` if the ingress (1) specifies `.spec.tls.secretName` and (2) references at least one\nhost. Using the example ingress route from above, Switchboard creates the following resource:\n\n```yaml\napiVersion: cert-manager.io/v1\nkind: Certificate\nmetadata:\n  # The name is automatically generated from the name of the ingress route.\n  name: my-ingress-tls\n  labels:\n    kubernetes.io/managed-by: switchboard\nspec:\n  # The issuer reference is obtained from the configuration of the cert-manager integration.\n  issuerRef:\n    kind: ClusterIssuer\n    name: ca-issuer\n  dnsNames:\n    - www.example.com\n  secretName: www-tls-certificate\n```\n\n#### External-DNS\n\nThe external-dns integration causes Switchboard to create a `DNSEndpoint` resource for an\n`IngressRoute` if the ingress references at least one host. Given the example ingress route above,\nSwitchboard creates the following endpoint:\n\n```yaml\napiVersion: externaldns.k8s.io/v1alpha1\nkind: DNSEndpoint\nmetadata:\n  # The name is the same as the ingress's name.\n  name: my-ingress\n  labels:\n    kubernetes.io/managed-by: switchboard\nspec:\n  endpoints:\n    - dnsName: www.example.com\n      recordTTL: 300\n      recordType: A\n      targets:\n        # The target is the public (or, if unavailable, private) IP address of your Traefik\n        # instance. The Kubernetes service to source the IP from is obtained from the configuration\n        # of the external-dns integration.\n        - 10.96.0.10\n```\n\n### Customization\n\n#### Manually Set Hosts\n\nBy default, Switchboard automatically extracts hosts from an ingress route by processing all rules\nand extracting hosts from `` Host(`...`) `` blocks. If you want to specify the set of hosts that\nare used for TLS certificates and DNS endpoints yourself, set `.spec.tls.domains`, e.g.:\n\n```yaml\nspec:\n  tls:\n    domains:\n      - main: example.com\n        sans:\n          - www.example.com\n```\n\n#### Disable Processing of an Ingress Route\n\nBy default, Switchboard process all `IngressRoute` objects in your cluster. While you can constrain\nSwitchboard to only process objects with the `kubernetes.io/ingress.class` annotation set to a\nspecific value (see the\n[Switchboard Helm chart documentation](https://github.com/borchero/switchboard-chart)), you can\nalso disable processing for individual ingress routes by setting an additional annotation:\n\n```yaml\nmetadata:\n  annotations:\n    switchboard.borchero.com/ignore: \"all\"\n```\n\nBy setting the `ignore` annotation to `all` (or `true`), Switchboard does not process the ingress\nroute at all. For more fine-grained control, the value of this annotation can also be set to a\ncomma-separated list of integrations (possible values `cert-manager`, `external-dns`).\n\n## License\n\nSwitchboard is licensed under the [MIT License](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fborchero%2Fswitchboard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fborchero%2Fswitchboard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fborchero%2Fswitchboard/lists"}