butlergroup/caddy-ingress repository overview

⁠Caddy K8s Ingress Controller

The Caddy K8s Ingress Controller includes functionality for monitoring Ingress resources on a Kubernetes cluster. It is capable of automatically provisioning and renewing SSL/TLS certificates for all hostnames defined in the ingress resources that it is managing.

⁠Notes on this fork

• This ingress controller works with Cloudflare (as of v0.3.0/1.4.0) to perform DNS-based challenges for auto-generated certificates. A Cloudflare API key with Zone.Zone:Read and Zone.DNS:Edit is needed to use this functionality, along with a private HTTP endpoint that approves a given domain for automatic certificate generation.
• It is also configured to write auto-generated certificates to the source ingress namespace instead of the Caddy installation namespace. This aligns with established K8s best practices regarding namespace-constrained secret access (as of v0.4.0/1.5.0).
• Created to update dependencies and include the latest version of Caddy when building the ingress-controller binary
• Several security scanners have been added to the repo to ensure any issues are found quickly
• Will be maintained (depenencies/packages updated & CVEs addressed in a timely manner, etc.)

⁠Prerequisites

• Helm 3+
• Kubernetes 1.19+

⁠Setup

In the charts folder, a Helm Chart is provided to make installing the Caddy Ingress Controller on a Kubernetes cluster straightforward. To install the Caddy Ingress Controller adhere to the following steps:

1. Add the Helm chart:

helm repo add caddy-ingress http://butlergroup.net/caddy-ingress/

1. Create a new namespace in your cluster to isolate all Caddy resources.

kubectl create namespace caddy-system

1. Create a Kubernetes opaque secret named "cloudflare-api-token" with the following key and value:

• CF_API_TOKEN / your Cloudflare API token with Zone.Zone:Read and Zone.DNS:Edit permissions for the domain(s) you're managing with Caddy

kubectl create secret generic cloudflare-api-token \
  --from-literal=CF_API_TOKEN=your_cloudflare_api_token \
  -n caddy-system

1. (a) Install the Helm chart:

helm install caddy-ingress caddy-ingress/caddy-ingress-controller \
  --namespace=caddy-system 

1. (b) Install the Helm chart with on-demand TLS enabled:

helm install caddy-ingress caddy-ingress/caddy-ingress-controller \
  --namespace=caddy-system \
  --set [email protected] \
  --set ingressController.config.onDemandTLS=true \
  --set ingressController.config.acmeDNSProvider=cloudflare \
  --set ingressController.config.acmeDNSResolvers[0]=1.1.1.1 \
  --set ingressController.config.permissionEndpoint=http://your-permission-endpoint

Note: Caddy expects to be able to query a local HTTP endpoint and receive an HTTP 200 OK response for domains authorized for on-demand TLS. See this link⁠ for details.

This will create a service of type LoadBalancer in the caddy-system namespace on your cluster. You'll want to set any DNS records for accessing this cluster to the external IP address of this LoadBalancer when the external IP is provisioned by your cloud provider.

You can get the external IP address with kubectl get svc -n caddy-system

⁠Debugging

To view any logs generated by Caddy or the Ingress Controller you can view the pod logs of the Caddy Ingress Controller.

Get the pod name with:

kubectl get pods -n caddy-system

View the pod logs:

kubectl logs <pod-name> -n caddy-system

⁠Automatic HTTPS

To have automatic HTTPS (not to be confused with On-demand TLS), you simply have to specify your email in the config map. When using Helm chart, you can add --set [email protected] when installing.

⁠On-Demand TLS

On-demand TLS⁠ can generate SSL certs on the fly and can be enabled in this controller by setting the onDemandTLS config to true:

helm install ...\
  --set ingressController.config.onDemandTLS=true

⁠Bringing Your Own Certificates

If you would like to disable automatic HTTPS for a specific host and use your own certificates you can create a new TLS secret in Kubernetes and define what certificates to use when serving your application on the ingress resource.

Example:

Create TLS secret mycerts, where ./tls.key and ./tls.crt are valid certificates for test.com.

kubectl create secret tls mycerts --key ./tls.key --cert ./tls.crt

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example
  annotations:
    kubernetes.io/ingress.class: caddy
spec:
  rules:
  - host: test.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: test
            port:
              number: 8080
  tls:
    - secretName: mycerts # use mycerts for host test.com
      hosts:
        - test.com

⁠Contribution

Learn how to start contributing on the Contributing Guidline⁠.

⁠License

AGPL 3.0⁠

⁠Terms of Service

Please read our Terms of Service⁠ before using our software. Violators of these Terms are not supported by the community or contributors.

⁠Privacy Policy

Please also read our Privacy Policy⁠ to understand how we handle your personal information.

⁠Contact

Have questions or suggestions? Reach out to us at [email protected]⁠. Thank you and happy coding! :)

⁠Star History