Cloudflare Tunnel Ingress Controller

https://github.com/strrl/cloudflare-tunnel-ingress-controller
Admin
This project simplifies exposing Kubernetes services to the internet easily and securely using...
Tokens:29,764
Snippets:431
Trust Score:10
License:MIT
Update:3 months ago
Show doc for...
Tokens:
Raw
### Setup IngressController instance

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/02-ingress-controller.md

Example implementation showing how to instantiate the controller within a manager context.

```go
package main

import (
    "github.com/STRRL/cloudflare-tunnel-ingress-controller/pkg/controller"
    "github.com/STRRL/cloudflare-tunnel-ingress-controller/pkg/cloudflare-controller"
    "github.com/go-logr/logr"
    "sigs.k8s.io/controller-runtime/pkg/client"
    "sigs.k8s.io/controller-runtime/pkg/manager"
)

func setupController(mgr manager.Manager, logger logr.Logger, tunnelClient *cloudflarecontroller.TunnelClient) *controller.IngressController {
    return controller.NewIngressController(
        logger.WithName("ingress-controller"),
        mgr.GetClient(),
        mgr.GetEventRecorderFor("cloudflare-tunnel-ingress-controller"),
        "cloudflare-tunnel",
        "strrl.dev/cloudflare-tunnel-ingress-controller",
        "cluster.local",
        tunnelClient,
    )
}
```

--------------------------------

### RegisterIngressController Usage Example

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/07-bootstrap.md

Demonstrates how to invoke RegisterIngressController within a setup function using required configuration options.

```go
package main

import (
    "github.com/STRRL/cloudflare-tunnel-ingress-controller/pkg/controller"
    "github.com/go-logr/logr"
    "sigs.k8s.io/controller-runtime/pkg/manager"
)

func setupControllers(logger logr.Logger, mgr manager.Manager) error {
    return controller.RegisterIngressController(
        logger,
        mgr,
        controller.IngressControllerOptions{
            IngressClassName:    "cloudflare-tunnel",
            ControllerClassName: "strrl.dev/cloudflare-tunnel-ingress-controller",
            ClusterDomain:       "cluster.local",
            CFTunnelClient:      tunnelClient,
        },
    )
}
```

--------------------------------

### Usage example for LoadCloudflaredDeploymentConfig

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/06-cloudflared-connector.md

Demonstrates how to load a configuration and use the resulting hash to track changes.

```go
package main

import (
    "github.com/STRRL/cloudflare-tunnel-ingress-controller/pkg/controller"
)

func loadConfig(path string) error {
    config, hash, err := controller.LoadCloudflaredDeploymentConfig(path)
    if err != nil {
        return err
    }

    // Use config and track changes via hash
    cloudflaredConfig := controller.CloudflaredConfig{
        Image:             "cloudflare/cloudflared:latest",
        Customization:     config,
        CustomizationHash: hash,
    }

    return nil
}
```

--------------------------------

### Usage example for bootstrapping

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/07-bootstrap.md

Demonstrates how to initialize a Cloudflare API client and bootstrap the tunnel client.

```go
package main

import (
    "context"
    "github.com/STRRL/cloudflare-tunnel-ingress-controller/pkg/cloudflare-controller"
    "github.com/cloudflare/cloudflare-go"
    "github.com/go-logr/logr"
)

func bootstrapCloudflare(logger logr.Logger) (*cloudflarecontroller.TunnelClient, error) {
    cfClient, _ := cloudflare.NewWithAPIToken("your-api-token")

    return cloudflarecontroller.BootstrapTunnelClientWithTunnelName(
        context.Background(),
        logger.WithName("tunnel-client"),
        cfClient,
        "account-id-xyz",
        "my-tunnel",
        "managed by cloudflare-tunnel-ingress-controller, tunnel [{{.TunnelName}}]",
    )
}
```

--------------------------------

### Usage example for syncDNSRecord

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/05-dns-management.md

Example implementation showing how to call syncDNSRecord to plan DNS changes.

```go
package main

import (
    "github.com/STRRL/cloudflare-tunnel-ingress-controller/pkg/cloudflare-controller"
    "github.com/STRRL/cloudflare-tunnel-ingress-controller/pkg/exposure"
    "github.com/cloudflare/cloudflare-go"
)

func planDNSChanges(
    logger logr.Logger,
    exposures []exposure.Exposure,
    existingCNAME []cloudflare.DNSRecord,
    existingTXT []cloudflare.DNSRecord,
) error {
    creates, updates, deletes, err := cloudflarecontroller.syncDNSRecord(
        logger,
        exposures,
        existingCNAME,
        existingTXT,
        "tunnel-abc123",
        "my-tunnel",
    )
    
    if err != nil {
        return err
    }
    
    // Apply operations...
    return nil
}
```

--------------------------------

### Usage Example for TunnelClient

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/04-tunnel-client.md

Demonstrates initializing the Cloudflare API client and creating a TunnelClient instance.

```go
package main

import (
    "github.com/STRRL/cloudflare-tunnel-ingress-controller/pkg/cloudflare-controller"
    "github.com/cloudflare/cloudflare-go"
    "github.com/go-logr/logr"
)

func createClient(logger logr.Logger) *cloudflarecontroller.TunnelClient {
    cfClient, _ := cloudflare.NewWithAPIToken("your-api-token")
    
    return cloudflarecontroller.NewTunnelClient(
        logger,
        cfClient,
        "account-id-12345",
        "tunnel-uuid-abcde",
        "my-tunnel",
        "managed by cloudflare-tunnel-ingress-controller, tunnel [{{.TunnelName}}]",
    )
}
```

--------------------------------

### Example output of buildCloudflaredCommand

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/06-cloudflared-connector.md

Demonstrates the resulting command slice when calling the build function with specific arguments.

```go
// buildCloudflaredCommand("auto", []string{"--loglevel", "info"})
// Returns:
// []string{
//     "cloudflared",
//     "--protocol", "auto",
//     "--no-autoupdate",
//     "tunnel",
//     "--loglevel", "info",
//     "--metrics", "0.0.0.0:44483",
//     "run",
// }
```

--------------------------------

### Install Controller with Helm

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/README.md

Deploys the controller into the cluster using the official Helm chart.

```bash
helm upgrade --install --wait \
  cloudflare-tunnel-ingress-controller \
  cloudflare-tunnel-ingress-controller \
  --repo https://helm.strrl.dev \
  --namespace cloudflare-tunnel-ingress-controller \
  --create-namespace \
  --set cloudflare.apiToken="<CLOUDFLARE_API_TOKEN>" \
  --set cloudflare.accountId="<CLOUDFLARE_ACCOUNT_ID>" \
  --set cloudflare.tunnelName="<TUNNEL_NAME>"
```

--------------------------------

### Start Development Environment with Skaffold

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/README.md

Initializes the local development loop using the integrated Makefile.

```bash
skaffold dev
```

--------------------------------

### Prepare Local Development Secret File

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/README.md

Copies the example configuration file to a local version for credential entry.

```bash
cp hack/dev/cloudflare-api.example.yaml hack/dev/cloudflare-api.yaml
```

--------------------------------

### Example ManagedRecordTXTContent JSON

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/05-dns-management.md

Sample JSON content stored in TXT records.

```json
{"controller":"strrl.dev/cloudflare-tunnel-ingress-controller","tunnel":"my-tunnel"}
```

--------------------------------

### Reconcile Usage Example

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/02-ingress-controller.md

Demonstrates how to manually invoke the Reconcile method for a specific Ingress resource.

```go
package main

import (
    "context"
    "github.com/STRRL/cloudflare-tunnel-ingress-controller/pkg/controller"
    "sigs.k8s.io/controller-runtime/pkg/reconcile"
)

func exampleUsage(ic *controller.IngressController) {
    ctx := context.Background()
    request := reconcile.Request{
        NamespacedName: struct {
            Namespace string
            Name      string
        }{
            Namespace: "default",
            Name:      "my-ingress",
        },
    }

    result, err := ic.Reconcile(ctx, request)
    if err != nil {
        // Handle reconciliation error
        return
    }

    if result.Requeue {
        // Will be requeued automatically by the manager
    }
}
```

--------------------------------

### Deploy via Helm

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/00-README.md

Install the controller using the official Helm chart with required Cloudflare credentials.

```bash
helm upgrade --install cloudflare-tunnel-ingress-controller \
  cloudflare-tunnel-ingress-controller \
  --repo https://helm.strrl.dev \
  --namespace cloudflare-tunnel-ingress-controller \
  --create-namespace \
  --set cloudflare.apiToken="<TOKEN>" \
  --set cloudflare.accountId="<ACCOUNT_ID>" \
  --set cloudflare.tunnelName="<TUNNEL_NAME>"
```

--------------------------------

### Example Usage of IsSubDomainOf

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/10-domain.md

Demonstrates subdomain checks, case-insensitivity, and edge cases like same-domain comparisons.

```go
package main

import (
    "fmt"
    "github.com/STRRL/cloudflare-tunnel-ingress-controller/pkg/cloudflare-controller"
)

func main() {
    // Subdomain examples
    app := cloudflarecontroller.Domain{Name: "app.example.com"}
    example := cloudflarecontroller.Domain{Name: "example.com"}
    
    fmt.Println(app.IsSubDomainOf(example))        // true
    
    api := cloudflarecontroller.Domain{Name: "api.app.example.com"}
    fmt.Println(api.IsSubDomainOf(example))        // true
    fmt.Println(api.IsSubDomainOf(app))            // true
    
    // Not subdomains
    other := cloudflarecontroller.Domain{Name: "other.com"}
    fmt.Println(app.IsSubDomainOf(other))          // false
    
    // Same domain (not a subdomain of itself)
    fmt.Println(example.IsSubDomainOf(example))    // false
    
    // Case insensitive
    APP := cloudflarecontroller.Domain{Name: "APP.EXAMPLE.COM"}
    fmt.Println(APP.IsSubDomainOf(example))        // true
}
```

--------------------------------

### Development and Build Commands

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/docs/README.md

Commands for installing dependencies, running the local development server, building the static site, and previewing the production build.

```bash
pnpm install
```

```bash
pnpm dev
```

```bash
pnpm build
```

```bash
pnpm preview
```

--------------------------------

### Transforming Ingress to Exposure Usage

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/03-transform.md

Example demonstrating how to invoke the transformation function within a controller context.

```go
package main

import (
    "context"
    "fmt"
    "github.com/STRRL/cloudflare-tunnel-ingress-controller/pkg/controller"
    "sigs.k8s.io/controller-runtime/pkg/log"
    networkingv1 "k8s.io/api/networking/v1"
)

func transformIngress(
    ctx context.Context,
    kubeClient client.Client,
    ingress networkingv1.Ingress,
) error {
    logger := log.FromContext(ctx)
    recorder := mgr.GetEventRecorderFor("my-app")

    exposures, err := controller.FromIngressToExposure(
        ctx,
        logger,
        kubeClient,
        recorder,
        ingress,
        "cluster.local",
    )
    if err != nil {
        return fmt.Errorf("transform failed: %w", err)
    }

    for _, exp := range exposures {
        fmt.Printf("Exposure: %s -> %s (%s)\n", 
            exp.Hostname, exp.ServiceTarget, exp.PathPrefix)
    }
    return nil
}
```

--------------------------------

### Syncing Exposures Example

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/04-tunnel-client.md

Demonstrates how to define a slice of Exposure objects and invoke the PutExposures method to update the tunnel configuration.

```go
package main

import (
    "context"
    "github.com/STRRL/cloudflare-tunnel-ingress-controller/pkg/exposure"
    "k8s.io/utils/ptr"
)

func syncExposures(ctx context.Context, client *cloudflarecontroller.TunnelClient) error {
    exposures := []exposure.Exposure{
        {
            Hostname:      "api.example.com",
            ServiceTarget: "http://api.default.svc.cluster.local:8080",
            PathPrefix:    "/",
            IsDeleted:     false,
        },
        {
            Hostname:      "www.example.com",
            ServiceTarget: "http://web.default.svc.cluster.local:3000",
            PathPrefix:    "/",
            ProxySSLVerifyEnabled: ptr.To(true),
            IsDeleted:     false,
        },
    }

    return client.PutExposures(ctx, exposures)
}
```

--------------------------------

### JSON configuration file format

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/06-cloudflared-connector.md

Example JSON structure for defining pod resources, security context, labels, and probes.

```json
{
  "resources": {
    "requests": {
      "cpu": "50m",
      "memory": "64Mi"
    },
    "limits": {
      "cpu": "200m",
      "memory": "256Mi"
    }
  },
  "securityContext": {
    "runAsNonRoot": true,
    "runAsUser": 65534
  },
  "podLabels": {
    "custom": "label"
  },
  "nodeSelector": {
    "cloud.google.com/gke-nodepool": "tunnel-pool"
  },
  "tolerations": [
    {
      "key": "workload",
      "operator": "Equal",
      "value": "tunnel",
      "effect": "NoSchedule"
    }
  ],
  "affinity": {
    "podAntiAffinity": {
      "preferredDuringSchedulingIgnoredDuringExecution": [
        {
          "weight": 100,
          "podAffinityTerm": {
            "labelSelector": {
              "matchExpressions": [
                {
                  "key": "app",
                  "operator": "In",
                  "values": ["controlled-cloudflared-connector"]
                }
              ]
            },
            "topologyKey": "kubernetes.io/hostname"
          }
        }
      ]
    }
  },
  "probes": {
    "liveness": {
      "httpGet": {
        "path": "/healthz",
        "port": 44483,
        "scheme": "HTTP"
      },
      "initialDelaySeconds": 30,
      "periodSeconds": 10
    },
    "readiness": {
      "httpGet": {
        "path": "/ready",
        "port": 44483,
        "scheme": "HTTP"
      },
      "initialDelaySeconds": 10,
      "periodSeconds": 5
    }
  }
}
```

--------------------------------

### Configure Backend Protocol in Ingress

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/08-annotations.md

Example Ingress configuration setting the backend protocol to HTTPS.

```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: https-backend
  annotations:
    cloudflare-tunnel-ingress-controller.strrl.dev/backend-protocol: "https"
spec:
  # ...
```

--------------------------------

### Implement Cloudflared Connector Management

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/06-cloudflared-connector.md

Example demonstrating how to configure and invoke the CreateOrUpdateControlledCloudflared function within a main application flow.

```go
package main

import (
    "context"
    "github.com/STRRL/cloudflare-tunnel-ingress-controller/pkg/controller"
)

func manageConnector(
    ctx context.Context,
    kubeClient client.Client,
    tunnelClient *cloudflarecontroller.TunnelClient,
) error {
    config := controller.CloudflaredConfig{
        Image:           "cloudflare/cloudflared:2024.1.1",
        ImagePullPolicy: "IfNotPresent",
        Replicas:        2,
        Protocol:        "auto",
        ExtraArgs:       []string{"--loglevel", "info"},
    }

    return controller.CreateOrUpdateControlledCloudflared(
        ctx,
        kubeClient,
        tunnelClient,
        "cloudflare-tunnel-ingress-controller",
        config,
    )
}
```

--------------------------------

### Get Annotation Helper

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/03-transform.md

Retrieves an annotation value and existence status from a map.

```go
func getAnnotation(annotations map[string]string, key string) (string, bool)
```

--------------------------------

### Get Host from Service Helper

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/03-transform.md

Determines the FQDN or ExternalName for a given Kubernetes Service.

```go
func getHostFromService(service *v1.Service, clusterDomain string) (string, error)
```

--------------------------------

### Example Secret Configuration YAML

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/README.md

The structure of the Kubernetes Secret required for the controller to authenticate.

```yaml
apiVersion: v1
kind: Secret
metadata:
 name: cloudflare-api
 namespace: cloudflare-tunnel-ingress-controller-dev
stringData:
  api-token: "<your_api_token>"
  cloudflare-account-id: "<your_account_id>"
  cloudflare-tunnel-name: "<your_tunnel_name>"
```

--------------------------------

### Connect to PostgreSQL via TCP Proxy

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/docs/src/content/docs/how-to/expose-non-http-services.md

Start a local TCP proxy for the PostgreSQL hostname and connect using the psql client.

```bash
cloudflared access tcp \
  --hostname postgres.example.com \
  --url localhost:15432
```

```bash
psql \
  --host localhost \
  --port 15432 \
  --username "<DATABASE_USER>" \
  --dbname "<DATABASE_NAME>"
```

--------------------------------

### Configure Proxy SSL Verification in Ingress

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/08-annotations.md

Example Ingress configuration to enable TLS verification for HTTPS backends.

```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: secure-backend
  annotations:
    cloudflare-tunnel-ingress-controller.strrl.dev/proxy-ssl-verify: "on"
spec:
  # ...
```

--------------------------------

### Configure Helm with Credentials

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/docs/src/content/docs/reference/cloudflare-credentials.md

Pass Cloudflare credentials directly during Helm installation to create the required Kubernetes secret.

```bash
helm upgrade --install cloudflare-tunnel-ingress-controller \
  strrl.dev/cloudflare-tunnel-ingress-controller \
  --set cloudflare.apiToken="<CLOUDFLARE_API_TOKEN>" \
  --set cloudflare.accountId="<CLOUDFLARE_ACCOUNT_ID>" \
  --set cloudflare.tunnelName="<TUNNEL_NAME>"
```

--------------------------------

### Configure Ingress with Annotations

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/08-annotations.md

Example of an Ingress resource utilizing various Cloudflare Tunnel annotations for protocol, SSL verification, headers, and DNS management.

```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: full-example
  namespace: default
  annotations:
    # Configure tunnel behavior
    cloudflare-tunnel-ingress-controller.strrl.dev/backend-protocol: "https"
    cloudflare-tunnel-ingress-controller.strrl.dev/proxy-ssl-verify: "on"
    
    # Custom headers
    cloudflare-tunnel-ingress-controller.strrl.dev/http-host-header: "api.internal"
    cloudflare-tunnel-ingress-controller.strrl.dev/origin-server-name: "api.internal"
    
    # External DNS management
    cloudflare-tunnel-ingress-controller.strrl.dev/disable-dns-management: "false"

spec:
  ingressClassName: cloudflare-tunnel
  rules:
  - host: api.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: api-service
            port:
              number: 443
```

--------------------------------

### Configure HTTP Host Header in Ingress

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/08-annotations.md

Example Ingress configuration to set a custom Host header for the backend.

```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-ingress
  annotations:
    cloudflare-tunnel-ingress-controller.strrl.dev/http-host-header: "backend.internal"
spec:
  # ...
```

--------------------------------

### Define Cloudflared Deployment JSON Schema

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/11-configuration.md

Example JSON structure for defining pod resources, security context, and affinity rules.

```json
{
  "resources": {
    "requests": {
      "cpu": "50m",
      "memory": "64Mi"
    },
    "limits": {
      "cpu": "200m",
      "memory": "256Mi"
    }
  },
  "securityContext": {
    "runAsNonRoot": true,
    "runAsUser": 65534
  },
  "nodeSelector": {
    "workload": "tunnel"
  },
  "affinity": {
    "podAntiAffinity": {
      "preferredDuringSchedulingIgnoredDuringExecution": [
        {
          "weight": 100,
          "podAffinityTerm": {
            "labelSelector": {
              "matchExpressions": [
                {
                  "key": "app",
                  "operator": "In",
                  "values": ["controlled-cloudflared-connector"]
                }
              ]
            },
            "topologyKey": "kubernetes.io/hostname"
          }
        }
      ]
    }
  }
}
```

--------------------------------

### Connect to Redis via TCP Proxy

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/docs/src/content/docs/how-to/expose-non-http-services.md

Start a local TCP proxy using cloudflared and connect the redis-cli client to the local port.

```bash
cloudflared access tcp \
  --hostname redis.example.com \
  --url localhost:16379
```

```bash
redis-cli -h localhost -p 16379
```

--------------------------------

### Initialize Exposure Configurations

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/01-exposure.md

Demonstrates creating various Exposure instances, including those with SSL verification and external DNS management.

```go
package main

import (
    "github.com/STRRL/cloudflare-tunnel-ingress-controller/pkg/exposure"
    "k8s.io/utils/ptr"
)

func main() {
    // Create a basic exposure
    exp := exposure.Exposure{
        Hostname:      "api.example.com",
        ServiceTarget: "http://my-service.default.svc.cluster.local:8080",
        PathPrefix:    "/api",
        IsDeleted:     false,
    }

    // Create an exposure with SSL verification enabled
    expWithSSL := exposure.Exposure{
        Hostname:              "secure.example.com",
        ServiceTarget:         "https://my-service.default.svc.cluster.local:443",
        PathPrefix:            "/",
        ProxySSLVerifyEnabled: ptr.To(true),
        OriginServerName:      ptr.To("backend.internal"),
    }

    // Create an exposure with external DNS management
    expExternalDNS := exposure.Exposure{
        Hostname:             "external.example.com",
        ServiceTarget:        "http://my-service.default.svc.cluster.local:3000",
        PathPrefix:           "/app",
        DisableDNSManagement: true,
    }
}
```

--------------------------------

### Error Message Format

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/00-README.md

Example of the wrapped error message structure used by the controller.

```text
fetch ingress default/my-ingress: failed to get object
update cloudflare tunnel config: update tunnel ingress rules: transform to cloudflare ingress: ...
```

--------------------------------

### Development Commands

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/CLAUDE.md

Standard Makefile commands for setting up the environment, running tests, and building the project.

```bash
# Initial setup (installs pre-commit hooks via prek)
make setup

# Run unit tests
make unit-test

# Run a single test
go test -run TestFunctionName ./pkg/path/to/package/...

# Run integration tests (requires setup-envtest)
make integration-test

# Build Docker image
make image

# Development with live reload (also runs setup)
make dev
```

--------------------------------

### Configure controller via CLI flags or environment variables

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/docs/src/content/docs/reference/controller-configuration.md

Demonstrates the equivalence between CLI flags and environment variables for configuration.

```bash
# These are equivalent:
--cloudflare-api-token=xxx
CLOUDFLARE_API_TOKEN=xxx
```

--------------------------------

### Initialize IngressController

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/02-ingress-controller.md

Constructor signature for creating a new IngressController instance.

```go
func NewIngressController(
    logger logr.Logger,
    kubeClient client.Client,
    recorder record.EventRecorder,
    ingressClassName string,
    controllerClassName string,
    clusterDomain string,
    tunnelClient *cloudflarecontroller.TunnelClient,
) *IngressController
```

--------------------------------

### Configure Disable DNS Management in Ingress

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/08-annotations.md

Example Ingress configuration to prevent the controller from managing DNS records.

```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: external-dns-managed
  annotations:
    cloudflare-tunnel-ingress-controller.strrl.dev/disable-dns-management: "true"
spec:
  ingressClassName: cloudflare-tunnel
  rules:
  - host: app.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-app
            port:
              number: 8080
```

--------------------------------

### Initialize TunnelClient

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/04-tunnel-client.md

Constructor signature for creating a new TunnelClient instance.

```go
func NewTunnelClient(
    logger logr.Logger,
    cfClient *cloudflare.API,
    accountId string,
    tunnelId string,
    tunnelName string,
    dnsCommentTemplate string,
) *TunnelClient
```

--------------------------------

### Inspect connector deployment and pods

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/docs/src/content/docs/how-to/monitoring.md

Verify the deployment configuration and pod status after applying health probes.

```bash
kubectl describe deployment controlled-cloudflared-connector \
  -n cloudflare-tunnel-ingress-controller

kubectl get pods \
  -n cloudflare-tunnel-ingress-controller \
  -l app=controlled-cloudflared-connector
```

--------------------------------

### Get Port with Name Helper

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/03-transform.md

Finds a specific port number within a list of Service ports by name.

```go
func getPortWithName(ports []v1.ServicePort, portName string) (bool, int32)
```

--------------------------------

### Bootstrap Controller Stack in Go

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/07-bootstrap.md

Initializes the Cloudflare API client, provisions the tunnel, and registers the ingress controller with the manager. Requires a valid Cloudflare API token and account ID.

```go
package main

import (
    "context"
    "log"
    "os"

    "github.com/STRRL/cloudflare-tunnel-ingress-controller/pkg/cloudflare-controller"
    "github.com/STRRL/cloudflare-tunnel-ingress-controller/pkg/controller"
    "github.com/cloudflare/cloudflare-go"
    "github.com/go-logr/stdr"
    "sigs.k8s.io/controller-runtime/pkg/manager"
)

func setupControllerStack(
    mgr manager.Manager,
    apiToken string,
    accountId string,
    tunnelName string,
) error {
    logger := stdr.NewWithOptions(
        log.New(os.Stderr, "", log.LstdFlags),
        stdr.Options{LogCaller: stdr.All},
    ).WithName("setup")

    ctx := context.Background()

    // 1. Create Cloudflare API client
    cfClient, err := cloudflare.NewWithAPIToken(apiToken)
    if err != nil {
        return err
    }

    // 2. Bootstrap Tunnel Client (creates tunnel if needed)
    tunnelClient, err := cloudflarecontroller.BootstrapTunnelClientWithTunnelName(
        ctx,
        logger.WithName("tunnel-client"),
        cfClient,
        accountId,
        tunnelName,
        "managed by cloudflare-tunnel-ingress-controller, tunnel [{{.TunnelName}}]",
    )
    if err != nil {
        return err
    }

    // 3. Register Ingress Controller
    return controller.RegisterIngressController(
        logger.WithName("ingress-controller"),
        mgr,
        controller.IngressControllerOptions{
            IngressClassName:    "cloudflare-tunnel",
            ControllerClassName: "strrl.dev/cloudflare-tunnel-ingress-controller",
            ClusterDomain:       "cluster.local",
            CFTunnelClient:      tunnelClient,
        },
    )
}
```

--------------------------------

### Configure via Environment Variables

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/11-configuration.md

Set configuration flags using uppercase environment variables with underscores replacing hyphens.

```bash
export CLOUDFLARE_API_TOKEN="token-value"
export CLOUDFLARE_ACCOUNT_ID="account-id"
export CLOUDFLARE_TUNNEL_NAME="tunnel-name"
export INGRESS_CLASS="custom-class"
export LOG_LEVEL=2
```

--------------------------------

### Apply and Verify ExternalDNS

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/docs/src/content/docs/how-to/use-with-external-dns.md

Apply the manifest and check the ExternalDNS logs to confirm the CNAME creation.

```bash
kubectl apply -f ingress.yaml
kubectl logs deployment/external-dns -n external-dns
```

--------------------------------

### Apply and Verify Ingress Configuration

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/docs/src/content/docs/how-to/expose-non-http-services.md

Commands to apply the Ingress resource and verify the controller's status through events and logs.

```bash
kubectl apply -f postgres-tunnel.yaml
```

```bash
kubectl describe ingress postgres-tunnel -n database
```

```bash
kubectl logs deployment/cloudflare-tunnel-ingress-controller \
  -n cloudflare-tunnel-ingress-controller
```

--------------------------------

### Project Directory Structure

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/docs/README.md

Overview of the project layout, highlighting the documentation source directory and configuration files.

```text
src/
  content/docs/       # Markdown and MDX sources for the documentation
  assets/             # Images and additional media referenced in docs
public/               # Static files copied verbatim to the build output
astro.config.mjs      # Starlight configuration (title, sidebar, social links)
```

--------------------------------

### Run Controller via CLI

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/11-configuration.md

Execute the controller with required Cloudflare credentials and Kubernetes configuration flags.

```bash
cloudflare-tunnel-ingress-controller \
  --cloudflare-api-token "my-api-token" \
  --cloudflare-account-id "abc123" \
  --cloudflare-tunnel-name "my-tunnel" \
  --ingress-class "cloudflare-tunnel" \
  --controller-class "strrl.dev/cloudflare-tunnel-ingress-controller" \
  --namespace "cloudflare-tunnel-ingress-controller" \
  --cloudflared-image "cloudflare/cloudflared:2024.1.1" \
  --cloudflared-replica-count 2 \
  --log-level 1 \
  --cluster-domain "cluster.local" \
  --leader-elect \
  --dns-comment-template "Managed by K8s tunnel [{{.TunnelName}}]"
```

--------------------------------

### Configure Origin Server Name in Ingress

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/08-annotations.md

Example Ingress configuration for HTTPS backends requiring specific certificate hostname validation.

```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: https-backend
  annotations:
    cloudflare-tunnel-ingress-controller.strrl.dev/backend-protocol: "https"
    cloudflare-tunnel-ingress-controller.strrl.dev/origin-server-name: "backend.internal"
    cloudflare-tunnel-ingress-controller.strrl.dev/proxy-ssl-verify: "on"
spec:
  # ...
```

--------------------------------

### Run Project Tests

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/00-README.md

Execute unit and integration tests using the provided Makefile targets.

```bash
make unit-test
make integration-test
```

--------------------------------

### Load Cloudflared deployment configuration

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/06-cloudflared-connector.md

Function signature for loading pod template customizations from a JSON file.

```go
func LoadCloudflaredDeploymentConfig(
    path string,
) (*CloudflaredDeploymentConfig, string, error)
```

--------------------------------

### Execute E2E Tests

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/test/e2e/README.md

Run the full end-to-end test suite using the project's Makefile.

```bash
make e2e
```

--------------------------------

### Bootstrap TunnelClient by name

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/07-bootstrap.md

Initializes a TunnelClient by looking up or creating a Cloudflare tunnel by name.

```go
func BootstrapTunnelClientWithTunnelName(
    ctx context.Context,
    logger logr.Logger,
    cfClient *cloudflare.API,
    accountId string,
    tunnelName string,
    dnsCommentTemplate string,
) (*TunnelClient, error)
```

--------------------------------

### Find matching TXT record

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/05-dns-management.md

Finds a TXT record matching both the hostname and content to verify ownership.

```go
func findMatchingTXTRecord(
    records []cloudflare.DNSRecord,
    name string,
    content string,
) (bool, cloudflare.DNSRecord)
```

--------------------------------

### Configure via Helm Chart Values

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/11-configuration.md

Define controller and cloudflared settings using the values.yaml file in the Helm chart.

```yaml
cloudflare:
  apiToken: "<API_TOKEN>"
  accountId: "<ACCOUNT_ID>"
  tunnelName: "<TUNNEL_NAME>"

ingressClass: "cloudflare-tunnel"
controllerClass: "strrl.dev/cloudflare-tunnel-ingress-controller"
logLevel: 0
namespace: "cloudflare-tunnel-ingress-controller"

cloudflared:
  protocol: "auto"
  image: "cloudflare/cloudflared:latest"
  imagePullPolicy: "IfNotPresent"
  replicaCount: 1
  extraArgs: []
  deploymentConfig: null

clusterDomain: "cluster.local"
leaderElection: false
dnsCommentTemplate: "managed by cloudflare-tunnel-ingress-controller, tunnel [{{.TunnelName}}]"
```

--------------------------------

### LoadCloudflaredDeploymentConfig

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/06-cloudflared-connector.md

Loads pod template customization from a specified JSON file path. Returns the configuration object, a SHA256 hash of the file content, and any potential errors.

```APIDOC
## Function: LoadCloudflaredDeploymentConfig

### Description
Loads pod template customization from a JSON file. This function is used to configure deployment settings such as resources, security contexts, and probes.

### Signature
`func LoadCloudflaredDeploymentConfig(path string) (*CloudflaredDeploymentConfig, string, error)`

### Parameters
- **path** (string) - Optional - Path to the JSON file. If empty, returns an empty configuration.

### Returns
- **config** (*CloudflaredDeploymentConfig) - The loaded configuration or an empty config if the path is empty.
- **hash** (string) - The SHA256 hash of the file content (hex-encoded); empty if the path is empty.
- **err** (error) - An error object if file reading or JSON parsing fails.
```

--------------------------------

### Configure Namespace

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/11-configuration.md

Specifies the Kubernetes namespace for deployment resources.

```bash
--namespace "cloudflare-tunnel-ingress-controller"
```

--------------------------------

### Implement DNS Zone Matching

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/10-domain.md

Uses IsSubDomainOf to verify if a hostname belongs to a specific Cloudflare zone.

```go
func zoneBelongedByExposure(exposure exposure.Exposure, zones []string) (bool, string) {
    hostnameDomain := Domain{Name: exposure.Hostname}

    for _, zone := range zones {
        zoneDomain := Domain{Name: zone}
        if hostnameDomain.IsSubDomainOf(zoneDomain) || 
           hostnameDomain.Name == zoneDomain.Name {
            return true, zone
        }
    }
    return false, ""
}
```

--------------------------------

### Define CloudflaredDeploymentConfig struct

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/12-types.md

Defines pod template customizations for cloudflared deployments.

```go
type CloudflaredDeploymentConfig struct {
    Resources                   *v1.ResourceRequirements
    SecurityContext             *v1.SecurityContext
    PodSecurityContext          *v1.PodSecurityContext
    PodLabels                   map[string]string
    PodAnnotations              map[string]string
    NodeSelector                map[string]string
    Tolerations                 []v1.Toleration
    Affinity                    *v1.Affinity
    TopologySpreadConstraints   []v1.TopologySpreadConstraint
    PriorityClassName           string
    Probes                      *CloudflaredProbes
    Volumes                     []v1.Volume
    VolumeMounts                []v1.VolumeMount
}
```

--------------------------------

### Configure SSH Access

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/docs/src/content/docs/how-to/expose-non-http-services.md

Add the ProxyCommand to the SSH configuration file and connect using standard SSH commands.

```text
Host ssh.example.com
  ProxyCommand cloudflared access ssh --hostname %h
```

```bash
ssh user@ssh.example.com
```

--------------------------------

### Configure cloudflared health probes

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/docs/src/content/docs/how-to/monitoring.md

Add liveness, readiness, and startup probes to the cloudflared connector configuration in Helm values.

```yaml
cloudflared:
  probes:
    liveness:
      httpGet:
        path: /ready
        port: 44483
      initialDelaySeconds: 10
    readiness:
      httpGet:
        path: /ready
        port: 44483
    startup:
      httpGet:
        path: /ready
        port: 44483
      failureThreshold: 30
      periodSeconds: 2
```

--------------------------------

### FromIngressToExposure

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/03-transform.md

Transforms a Kubernetes Ingress resource into a slice of Exposure objects by extracting configuration from rules, annotations, and referenced Services.

```APIDOC
## func FromIngressToExposure

### Description
Transforms a Kubernetes Ingress resource into a slice of Exposure objects, extracting all necessary configuration from the Ingress rules, annotations, and referenced Services.

### Signature
`func FromIngressToExposure(ctx context.Context, logger logr.Logger, kubeClient client.Client, recorder record.EventRecorder, ingress networkingv1.Ingress, clusterDomain string) ([]exposure.Exposure, error)`

### Parameters
- **ctx** (context.Context) - Required - Context for cancellation and timeouts
- **logger** (logr.Logger) - Required - Structured logger for operations
- **kubeClient** (client.Client) - Required - Kubernetes client for Service lookups
- **recorder** (record.EventRecorder) - Required - Event recorder for Kubernetes events
- **ingress** (networkingv1.Ingress) - Required - The Ingress resource to transform
- **clusterDomain** (string) - Required - The cluster domain for FQDN construction

### Returns
- **[]exposure.Exposure** - Slice of Exposure objects, one per HTTP path rule
- **error** - Error if transformation failed
```

--------------------------------

### Define IngressControllerOptions structure

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/07-bootstrap.md

Configuration options for the IngressController, including class names and the Cloudflare Tunnel client.

```go
type IngressControllerOptions struct {
    IngressClassName    string
    ControllerClassName string
    ClusterDomain       string
    CFTunnelClient      *cloudflarecontroller.TunnelClient
}
```

--------------------------------

### Define CloudflaredConfig struct

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/12-types.md

Contains configuration settings for the managed cloudflared Deployment.

```go
type CloudflaredConfig struct {
    Image               string
    ImagePullPolicy     string
    Replicas            int32
    Protocol            string
    ExtraArgs           []string
    Customization       *CloudflaredDeploymentConfig
    CustomizationHash   string
}
```

--------------------------------

### Verify redundancy

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/docs/src/content/docs/how-to/high-availability.md

Check the status of deployments, the leader election lease, and the pod disruption budget to confirm high availability settings.

```bash
kubectl get deployment cloudflare-tunnel-ingress-controller \
  -n cloudflare-tunnel-ingress-controller

kubectl get lease cloudflare-tunnel-ingress-controller.strrl.dev \
  -n cloudflare-tunnel-ingress-controller

kubectl get deployment controlled-cloudflared-connector \
  -n cloudflare-tunnel-ingress-controller

kubectl get pdb controlled-cloudflared-connector \
  -n cloudflare-tunnel-ingress-controller
```

--------------------------------

### View controller logs

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/docs/src/content/docs/guides/troubleshooting.md

Retrieve logs from the controller deployment to troubleshoot reconciliation errors.

```bash
kubectl logs deployment/cloudflare-tunnel-ingress-controller \
  -n cloudflare-tunnel-ingress-controller
```

--------------------------------

### Check controller and connector pod status

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/docs/src/content/docs/guides/troubleshooting.md

Verify that the controller and connector pods are running in the specified namespace.

```bash
kubectl get pods -n cloudflare-tunnel-ingress-controller
```

--------------------------------

### Define Origin Server Name Constant

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/08-annotations.md

Go constant for specifying the hostname on the origin server certificate.

```go
const AnnotationOriginServerName = "cloudflare-tunnel-ingress-controller.strrl.dev/origin-server-name"
```

--------------------------------

### Define Domain Struct

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/10-domain.md

Represents a DNS domain name.

```go
type Domain struct {
    Name string
}
```

--------------------------------

### Apply the Ingress manifest

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/docs/src/content/docs/guides/quickstart.md

Applies the previously saved YAML file to the Kubernetes cluster.

```bash
kubectl apply -f dashboard-ingress.yaml
```

--------------------------------

### Define buildCloudflaredCommand function signature

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/06-cloudflared-connector.md

Defines the function signature for constructing the cloudflared command array.

```go
func buildCloudflaredCommand(protocol string, extraArgs []string) []string
```

--------------------------------

### Verify Controller Pods

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/helm/cloudflare-tunnel-ingress-controller/templates/NOTES.txt

Use this command to check the status of the controller pods within the release namespace.

```bash
kubectl -n {{ .Release.Namespace }} get pods -l app.kubernetes.io/name={{ include "cloudflare-tunnel-ingress-controller.name" . }}
```

--------------------------------

### BootstrapTunnelClientWithTunnelName

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/07-bootstrap.md

Creates and initializes a TunnelClient for managing a Cloudflare Tunnel by name, creating it if it does not exist.

```APIDOC
## func BootstrapTunnelClientWithTunnelName

### Description
Creates and initializes a TunnelClient for managing a Cloudflare Tunnel by name. If the tunnel does not exist, it is created automatically.

### Signature
`func BootstrapTunnelClientWithTunnelName(ctx context.Context, logger logr.Logger, cfClient *cloudflare.API, accountId string, tunnelName string, dnsCommentTemplate string) (*TunnelClient, error)`

### Parameters
- **ctx** (context.Context) - Required - Context for API calls
- **logger** (logr.Logger) - Required - Structured logger
- **cfClient** (*cloudflare.API) - Required - Cloudflare API client
- **accountId** (string) - Required - Cloudflare account ID
- **tunnelName** (string) - Required - Human-readable tunnel name
- **dnsCommentTemplate** (string) - Optional - Go template for DNS record comments

### Returns
- ***TunnelClient** - Initialized client ready for use
- **error** - Error if bootstrap fails
```

--------------------------------

### Monitor Rollout Status

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/docs/src/content/docs/how-to/rotate-cloudflare-credentials.md

Wait for the controller deployment rollout to complete successfully.

```bash
kubectl rollout status deployment <CONTROLLER_DEPLOYMENT> \
  -n <CONTROLLER_NAMESPACE>
```

--------------------------------

### Inspect Ingress configuration and events

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/docs/src/content/docs/guides/troubleshooting.md

Retrieve the YAML configuration and detailed events for a specific Ingress resource to identify configuration errors.

```bash
kubectl get ingress <name> -n <namespace> -o yaml
kubectl describe ingress <name> -n <namespace>
```

--------------------------------

### Configure Cloudflared Extra Arguments

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/11-configuration.md

Passes additional arguments to the cloudflared process.

```bash
--cloudflared-extra-args="--loglevel,debug" --cloudflared-extra-args="--post-quantum"
```

--------------------------------

### Configure Cloudflared Image

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/11-configuration.md

Sets the container image for the cloudflared connector.

```bash
--cloudflared-image "cloudflare/cloudflared:2024.1.1"
```

--------------------------------

### Configure Cloudflared Deployment

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/11-configuration.md

Specifies the path to a JSON file for customizing pod templates such as resources and affinity.

```bash
--cloudflared-deployment-config "/etc/cloudflare-tunnel/pod-config.json"
```

--------------------------------

### Define Proxy SSL Verification Constants

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/08-annotations.md

Go constants for configuring TLS certificate verification settings.

```go
const AnnotationProxySSLVerify = "cloudflare-tunnel-ingress-controller.strrl.dev/proxy-ssl-verify"
const AnnotationProxySSLVerifyOn = "on"
const AnnotationProxySSLVerifyOff = "off"
```

--------------------------------

### Define Configuration Struct

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/11-configuration.md

Internal Go struct representing the root command flags used for application configuration.

```go
type rootCmdFlags struct {
    logger                      logr.Logger
    ingressClass                string
    controllerClass             string
    logLevel                    int
    cloudflareAPIToken          string
    cloudflareAccountId         string
    cloudflareTunnelName        string
    namespace                   string
    cloudflaredProtocol         string
    cloudflaredExtraArgs        []string
    cloudflaredImage            string
    cloudflaredImagePullPolicy  string
    cloudflaredReplicaCount     int32
    cloudflaredDeploymentConfig string
    clusterDomain               string
    leaderElect                 bool
    dnsCommentTemplate          string
}
```

--------------------------------

### Search exposure by hostname

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/05-dns-management.md

Searches for an exposure with a specific hostname.

```go
func exposureContainsHostname(
    exposures []exposure.Exposure,
    hostname string,
) (bool, exposure.Exposure)
```

--------------------------------

### Create a Simple Ingress Exposure

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/00-README.md

Defines a basic Kubernetes Ingress resource using the cloudflare-tunnel ingress class to expose a service.

```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-app
  namespace: default
spec:
  ingressClassName: cloudflare-tunnel
  rules:
  - host: app.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-service
            port:
              number: 8080
```

--------------------------------

### Configure DNS Comment Template

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/11-configuration.md

Sets the Go template for DNS record comments or disables them entirely.

```bash
--dns-comment-template "K8s: {{.TunnelName}} ({{.TunnelId}})"
```

```bash
--dns-comment-template ""
```

--------------------------------

### Verify Connector Availability

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/docs/src/content/docs/how-to/rotate-cloudflare-credentials.md

Confirm that the managed cloudflared connector deployment has successfully rolled out.

```bash
kubectl rollout status deployment controlled-cloudflared-connector \
  -n <CONTROLLER_NAMESPACE>
```

--------------------------------

### Define DNSOperationCreate struct

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/05-dns-management.md

Structure representing a DNS record creation operation.

```go
type DNSOperationCreate struct {
    Hostname string
    Type     string
    Content  string
}
```

--------------------------------

### Verify Handover

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/docs/src/content/docs/how-to/use-with-external-dns.md

Use dig to verify that the CNAME record points to the correct tunnel target.

```bash
dig CNAME <HOSTNAME>
```

--------------------------------

### Define Backend Protocol Constant

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/08-annotations.md

Go constant for specifying the connection protocol to the backend service.

```go
const AnnotationBackendProtocol = "cloudflare-tunnel-ingress-controller.strrl.dev/backend-protocol"
```

--------------------------------

### Restart Controller Deployment

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/docs/src/content/docs/how-to/rotate-cloudflare-credentials.md

Trigger a rolling restart of the controller deployment to ensure all replicas load the new credentials.

```bash
kubectl rollout restart deployment <CONTROLLER_DEPLOYMENT> \
  -n <CONTROLLER_NAMESPACE>
```

--------------------------------

### Configure HTTP Host header

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/09-cloudflare-transform.md

Sets the custom HTTP Host header for backend requests if specified in the exposure object.

```go
if exposure.HTTPHostHeader != nil {
    result.OriginRequest.HTTPHostHeader = exposure.HTTPHostHeader
}
```

--------------------------------

### Project Directory Structure

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/00-README.md

The file system layout of the project, highlighting the separation between Kubernetes controller logic, Cloudflare API interactions, and core data structures.

```text
pkg/
├── controller/                          # Kubernetes controller logic
│   ├── ingress-controller.go           # Main IngressController
│   ├── transform.go                    # Ingress → Exposure transformation
│   ├── well_known_annotations.go       # Annotation constants
│   ├── controlled-cloudflared-connector.go  # Cloudflared connector management
│   ├── controlled-cloudflared-deployment.go # Deployment builder
│   ├── cloudflared_config.go           # Pod customization config
│   └── bootstrap.go                    # Controller registration
├── cloudflare-controller/              # Cloudflare API logic
│   ├── tunnel-client.go               # Main TunnelClient
│   ├── dns.go                         # DNS record management
│   ├── transform.go                   # Exposure → Cloudflare ingress rule
│   ├── domain.go                      # Domain utility
│   └── bootstrap.go                   # Tunnel client initialization
├── exposure/                            # Core data structures
│   └── exposure.go                    # Exposure type and Active() function
└── coverage/                            # Code coverage utilities
    └── flush.go                       # Signal handler for test coverage
```

--------------------------------

### Define cloudflared command structure

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/06-cloudflared-connector.md

Represents the standard command structure used to execute the cloudflared process.

```bash
cloudflared --protocol <protocol> --no-autoupdate [<extraArgs>...] --metrics 0.0.0.0:44483 run
```

--------------------------------

### Render DNS Comment

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/04-tunnel-client.md

Generates a DNS comment for a hostname based on the configured template.

```go
func (t *TunnelClient) renderDNSComment(hostname string) string
```

--------------------------------

### Create an HTTPS Ingress Exposure with SSL Verification

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/00-README.md

Configures an Ingress resource with specific annotations to enable HTTPS backend protocol and SSL verification.

```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: secure-app
  namespace: default
  annotations:
    cloudflare-tunnel-ingress-controller.strrl.dev/backend-protocol: "https"
    cloudflare-tunnel-ingress-controller.strrl.dev/proxy-ssl-verify: "on"
spec:
  ingressClassName: cloudflare-tunnel
  rules:
  - host: secure.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: secure-service
            port:
              number: 443
```

--------------------------------

### Configure Controller Class

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/11-configuration.md

Sets the identifier used in IngressClass resources for controller matching.

```bash
--controller-class "my.company/tunnel-controller"
```

--------------------------------

### PutExposures Method Signature

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/04-tunnel-client.md

The function signature for synchronizing exposures to the Cloudflare Tunnel.

```go
func (t *TunnelClient) PutExposures(
    ctx context.Context,
    exposures []exposure.Exposure,
) error
```

--------------------------------

### Update DNS CNAME Records for Zone

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/_autodocs/04-tunnel-client.md

Manages CNAME and TXT records for exposures within a specific zone.

```go
func (t *TunnelClient) updateDNSCNAMERecordForZone(
    ctx context.Context,
    exposures []exposure.Exposure,
    zone cloudflare.Zone,
) error
```

--------------------------------

### Check Controller Logs

Source: https://github.com/strrl/cloudflare-tunnel-ingress-controller/blob/master/docs/src/content/docs/how-to/rotate-cloudflare-credentials.md

Inspect recent logs to verify the controller is reconciling resources without authentication errors.

```bash
kubectl logs deployment/<CONTROLLER_DEPLOYMENT> \
  -n <CONTROLLER_NAMESPACE> \
  --since=10m
```
Tokens:
Raw