# Cloudflare DNS Integration

The Container Mom Operator can automatically create CNAME records in Cloudflare for OpenShift routes, ensuring your domains point to the OpenShift router. This integration will keep your DNS records synchronized with your Kubernetes resources.

## Setup

1. **Create a Cloudflare API Token**:
   - Log in to your Cloudflare dashboard
   - Navigate to "My Profile" > "API Tokens" > "Create Token"
   - Use the "Edit zone DNS" template or create a custom token with:
     - Permissions: `Zone:DNS:Edit` and `Zone:Zone:Read`
     - Zone Resources: Include specific domains or "All Zones"
   - Copy the generated token

2. **Identify your Cloudflare Zone ID**:
   - In the Cloudflare dashboard, select your domain
   - The Zone ID is displayed on the right side of the overview page
   - This is a 32+ character string

3. **Update the Cloudflare Secret**:
   - Edit the file at `deploy/cloudflare-secret.yaml` with your credentials
   - Replace the placeholder values with your actual:
     - `CLOUDFLARE_API_TOKEN`: Your API token from step 1
     - `CLOUDFLARE_ZONE_ID`: Your Zone ID from step 2
     - `OPENSHIFT_ROUTER_URL`: The hostname of your OpenShift router (e.g., `router-default.apps.your-cluster-domain`)

4. **Apply the Secret to your Cluster**:
   ```bash
   kubectl apply -f deploy/cloudflare-secret.yaml
   ```

5. **Deploy or Update the Operator**:
   ```bash
   kubectl apply -f deploy/operator-deployment.yaml
   ```

### Credential Formats

The operator supports two different formats for storing Cloudflare credentials in your vault:

1. **Nested Structure** (preferred for Container Mom Operator):
   ```yaml
   global:
     cloudflare:
       api_token: "your_token"
       zone_id: "your_zone_id"
       router_url: "your_router_url"
   ```

2. **Direct Token** (compatible with cert-manager):
   ```yaml
   global:
     cloudflare: "your_token"
   ```

The Ansible deployment will automatically detect which format you're using and configure the operator accordingly.

## How It Works

When a `ContainerMomDeployment` is created:
1. The operator creates an OpenShift route with a hostname based on your configuration
2. The hostname is generated using the namespace, deployment name, and your domain settings
3. Environment variables in the hostname (formatted as `${VAR_NAME}`) are automatically expanded
4. A CNAME record is created in Cloudflare pointing this hostname to your OpenShift router

When a `ContainerMomDeployment` or namespace is deleted:
1. The operator automatically finds associated DNS records
2. All CNAME records related to the deleted resources are removed from Cloudflare

### DNS Cleanup

DNS records are automatically cleaned up in the following scenarios:

1. **When a ContainerMomDeployment is deleted**:
   - The operator searches for routes in the namespace to identify hostnames
   - It then deletes the corresponding CNAME records from Cloudflare
   - If no specific routes are found, it attempts to delete records matching the deployment name and namespace patterns

2. **During periodic cleanup of dangling namespaces**:
   - Orphaned namespaces are identified based on your retention policies
   - Before deleting an orphaned namespace, DNS records for all routes in the namespace are removed
   - This ensures no dangling DNS records remain in Cloudflare

### Environment Variables

The operator uses the following environment variables:

- `CLOUDFLARE_API_TOKEN`: Your Cloudflare API token
- `CLOUDFLARE_ZONE_ID`: The Zone ID for your domain in Cloudflare
- `OPENSHIFT_ROUTER_URL`: The OpenShift router URL to use as the CNAME target
- `SKIP_CLOUDFLARE_INTEGRATION`: Set to "true" to disable Cloudflare integration (for testing)

### Troubleshooting

If you encounter issues with DNS records:

1. **Check the Operator Logs**:
   ```bash
   kubectl logs -n container-mom-system deploy/container-mom-operator
   ```

2. **Verify Credentials**:
   - Ensure your API token and Zone ID are correct
   - Verify the API token has the necessary permissions
   - Check that the Zone ID corresponds to the correct domain

3. **Unexpanded Variables**:
   If you see errors like `CLOUDFLARE_ZONE_ID contains unexpanded variable: ${CLOUDFLARE_ZONE_ID}`, it means your secret contains environment variable references instead of actual values.

   ```bash
   # Run the verification script
   ./scripts/verify-cloudflare-config.sh
   
   # For temporary testing, enable fallbacks
   kubectl set env deployment/container-mom-operator -n container-mom-system ALLOW_CLOUDFLARE_FALLBACKS=true
   ```

4. **Test DNS Updates**:
   You can temporarily disable Cloudflare integration to isolate issues:
   ```bash
   kubectl set env deployment/container-mom-operator -n container-mom-system SKIP_CLOUDFLARE_INTEGRATION=true
   ```

5. **Manual Cleanup**:
   If you need to manually trigger DNS cleanup for a specific namespace:
   ```bash
   kubectl exec -n container-mom-system deploy/container-mom-operator -- curl -X POST http://localhost:8080/cleanup/dns/your-namespace-name
   ```

### Common Issues

1. **Unexpanded Environment Variables**: If you see errors about unexpanded environment variables like `${CLOUDFLARE_ZONE_ID}`, ensure that:
   - Your secret contains the actual values without `${}` placeholders
   - The operator deployment correctly references the secret
   - Use the verification script to diagnose and fix issues: `./scripts/verify-cloudflare-config.sh`
   - In a development environment, you can temporarily enable fallbacks with `ALLOW_CLOUDFLARE_FALLBACKS=true`

2. **Duplicate Hostnames**: If you encounter hostnames with duplications (e.g., `prefix.prefix.domain.com`), this is now automatically handled by the operator. The operator prevents duplication by checking if the domain already contains the prefix.

3. **Invalid Zone ID**: The operator now validates the zone ID format and connection to the Cloudflare API. If you're seeing errors about an invalid zone ID:
   - Verify that your Zone ID is correct (it should be a 32+ character string)
   - Ensure the API token has access to that zone
   - Check if the zone is active in your Cloudflare account

4. **API Authentication Errors**: If you see authentication failures:
   - Confirm your API token has the necessary permissions (Zone: DNS: Edit, Zone: Zone: Read)
   - Verify the token is still active in your Cloudflare dashboard

5. **DNS Record Creation Failures**: The operator now provides detailed error messages for DNS record creation failures. Common causes include:
   - Rate limiting by Cloudflare
   - Invalid hostname format
   - Network connectivity issues
   
The operator includes robust error handling and will continue to function even if the Cloudflare integration encounters issues.