mirror of
https://github.com/kubernetes-sigs/external-dns.git
synced 2025-12-14 08:11:48 +01:00
04ef733d48
* docs: fix mkdoc build * Revert "docs: fix mkdoc build" This reverts commit b3a1aab00f6edbe5cd488147529b5479e9ea8c8a. * fix mkdocs config
141 lines
6.7 KiB
Markdown
141 lines
6.7 KiB
Markdown
# Kubernetes Events in External-DNS
|
||
|
||
External-DNS manages DNS records dynamically based on Kubernetes resources like Services and Ingresses.
|
||
Emitting Kubernetes Events provides a lightweight observable way for users and systems to understand what External-DNS is doing, especially in production environments where DNS correctness is essential.
|
||
|
||
> Note; events is currently alpha feature. Functionality is limited and subject to change
|
||
|
||
## ✨ Why Events Matter
|
||
|
||
Kubernetes Events enable External-DNS to provide real-time feedback to users and controllers, complementing logs with a simpler way to track DNS changes. This enhances debugging, monitoring, and automation around DNS operations.
|
||
|
||
### Use Cases of Emitting Events
|
||
|
||
| Use Case | Description |
|
||
|---------------------------------------------------|--------------------------------------------------------------------------------------------------------------|
|
||
| **DNS Record Visibility** | Events show what DNS records were created, updated, or deleted (e.g., `Created A record "api.example.com"`). |
|
||
| **Developer Feedback** | Users deploying Ingresses or Services can see if External-DNS processed their resource. |
|
||
| **Surface Errors, Debugging and Troubleshooting** | Easily identify resource misannotations, sync failures, or IAM permission issues. |
|
||
| **Error Reporting** | Emit warning events when record sync fails due to provider issues, duplicate records, or misconfigurations. |
|
||
| **Integration with Alerting/Automation/Auditing** | This enables automated remediation or notifications when DNS sync fails or changes unexpectedly. |
|
||
| **Observability** | Trace why a DNS record wasn’t created. |
|
||
| **Alerting/automation** | Trigger actions based on failed events. |
|
||
| **Operator and Developer feedback** | It removes the black-box feeling of "I deployed an Ingress, but why doesn’t the DNS work?" |
|
||
|
||
## Consuming Events
|
||
|
||
You can observe External-DNS events using:
|
||
|
||
```sh
|
||
kubectl describe service <name>
|
||
kubectl get events --field-selector involvedObject.kind=Service
|
||
kubectl get events --field-selector type=Normal|Warning
|
||
kubectl get events --field-selector reason=RecordReady|RecordDeleted|RecordError
|
||
```
|
||
|
||
Or integrate with tools like:
|
||
|
||
- Prometheus (via event exporters)
|
||
- Loki/Fluentd for log/event aggregation
|
||
- Argo CD / Flux for GitOps monitoring
|
||
|
||
### Practices for Understanding Events
|
||
|
||
- **Action field**: Events include a short label describing the `Action`, such as `Created`, `Updated`, `Deleted`, or `FailedSync`
|
||
- **Reason field**: Events include a short label `Reason` is why the action was taken, such as `RecordReady`, `RecordDeleted`, or `RecordError`.
|
||
- **Type field**:
|
||
- `Normal` means the operation succeeded (e.g., a DNS record was created).
|
||
- `Warning` indicates a problem (e.g., DNS sync failed due to configuration or provider issues).
|
||
- **Linked** resource: Events are attached to the relevant Kubernetes resource (like an `Ingress` or `Service`), so you can view them with tools like `kubectl describe`.
|
||
- **Event noise**: If you see repeated identical events, it may indicate a misconfiguration or an issue worth investigating.
|
||
|
||
### Sequence Overview: External-DNS Endpoint Reconciliation and Event Emission
|
||
|
||
The following sequence diagram illustrates the core workflow of how External-DNS processes endpoints, applies DNS changes, and emits Kubernetes events:
|
||
|
||
1. **Endpoint Collection**
|
||
The `Source` component generates `Endpoint` objects, each linked to a `ReferenceObject` (such as a Service or Ingress).
|
||
|
||
2. **Plan Construction**
|
||
A `Plan` aggregates multiple `Endpoints` and prepares a list of desired DNS changes.
|
||
|
||
3. **Change Application**
|
||
The `Plan` sends the changes to a DNS `Provider`, which attempts to apply them. Each `Endpoint` is labeled with the result: `Success`, `Failed`, or `Skip`.
|
||
|
||
4. **Event Emission**
|
||
Based on the result, an `Event` is created for each `Endpoint`, referencing the original `ReferenceObject`. These events are then emitted via the `EventEmitter`.
|
||
|
||
This sequence ensures DNS records are managed declaratively and provides real-time visibility into the system’s behavior through Kubernetes Events.
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Source
|
||
participant ReferenceObject
|
||
participant Endpoint
|
||
participant Plan
|
||
participant Event
|
||
participant Provider
|
||
participant EventEmitter
|
||
|
||
|
||
loop Process each Endpoint
|
||
Source->>Endpoint: Add Endpoint with Reference
|
||
end
|
||
|
||
Endpoint-->>ReferenceObject: Contains
|
||
Plan-->>Endpoint: Contains multiple
|
||
|
||
loop Apply Changes
|
||
Plan->>Provider: Apply Endpoint Changes
|
||
Provider-->>Endpoint: Label with Skip/Success/Failed
|
||
Provider-->>Plan: Return Result
|
||
end
|
||
|
||
|
||
loop Process each Event
|
||
Provider->>Plan: Label with Skip/Success/Failed
|
||
Plan-->>Event: Construct Event
|
||
Event-->>ReferenceObject: Contains
|
||
Event->>EventEmitter: Emit
|
||
end
|
||
```
|
||
|
||
### Caveats
|
||
|
||
- Events are ephemeral (default retention is ~1 hour).
|
||
- They are best-effort and not guaranteed to be delivered or stored long-term.
|
||
- Not a substitute for logging or metrics, but complementary.
|
||
|
||
## Supported Sources
|
||
|
||
Events are emitted for all sources that External-DNS supports. The following table lists the sources and whether they currently emit events.
|
||
If a source does not emit events, it may in the future.
|
||
|
||
| Source | Supported |
|
||
|:-----------------------|:---------:|
|
||
| `ambassador-host` | |
|
||
| `cloudfoundry` | |
|
||
| `connector` | |
|
||
| `contour-httpproxy` | |
|
||
| `crd` | |
|
||
| `empty` | |
|
||
| `f5-transportserver` | |
|
||
| `f5-virtualserver` | |
|
||
| `fake` | ✅ |
|
||
| `gateway-grpcroute` | |
|
||
| `gateway-httproute` | |
|
||
| `gateway-tcproute` | |
|
||
| `gateway-tlsroute` | |
|
||
| `gateway-udproute` | |
|
||
| `gloo-proxy` | |
|
||
| `ingress` | |
|
||
| `istio-gateway` | |
|
||
| `istio-virtualservice` | |
|
||
| `kong-tcpingress` | |
|
||
| `node` | |
|
||
| `openshift-route` | |
|
||
| `pod` | |
|
||
| `service` | |
|
||
| `skipper-routegroup` | |
|
||
| `traefik-proxy` | |
|