Skip to content

Commit 95cf3b0

Browse files
eslutskyeslutsky
committed
microshift dns hosts plugin
Signed-off-by: Evgeny Slutsky <[email protected]>
1 parent 7f59958 commit 95cf3b0

File tree

1 file changed

+152
-0
lines changed

1 file changed

+152
-0
lines changed

‎enhancements/microshift/microshift-coredns-hosts.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
2+
---
3+
title: microshift-coredns-hosts
4+
authors:
5+
- eslutsky
6+
reviewers:
7+
- pacevedom, MicroShift contributor
8+
- pmtk, MicroShift contributor
9+
- copejon, MicroShift contributor
10+
approvers:
11+
- jerpeter1, MicroShift principal engineer
12+
api-approvers:
13+
- None
14+
creation-date: 2025-10-06
15+
last-updated: 2025-10-06
16+
tracking-link:
17+
- https://issues.redhat.com/browse/OCPSTRAT-2206
18+
---
19+
20+
# MicroShift CoreDNS `hosts` Plugin Integration
21+
22+
## Summary
23+
24+
MicroShift relies on CoreDNS to provide DNS resolution for workloads running inside pods within the cluster. In these environments, it is often necessary for applications running in pods to resolve custom, fixed hostnames (such as the local machine's hostname or external services not resolvable via standard DNS) using a **hosts file mechanism**—functionality analogous to `/etc/hosts`, but applied to DNS queries originating from within pods.
25+
26+
27+
## Motivation
28+
29+
The current CoreDNS configuration does not include the **`hosts` plugin**, which prevents users from defining custom, static IP-to-hostname mappings that are honored by the cluster's DNS resolver. Introducing this plugin enhances MicroShift's flexibility, allowing deployments to accommodate use cases requiring custom hostname resolution without relying on complex external DNS services .
30+
31+
### Goals
32+
33+
1. Integrate the standard **CoreDNS `hosts` plugin** into the MicroShift configuration.
34+
2. Configure the `hosts` plugin to load static host mappings from a configuration source within the CoreDNS container.
35+
3. Ensure that changes to the hosts file are reflected immediately, without requiring any service or pod restarts or causing disruption to DNS services.
36+
37+
### Non-Goals
38+
39+
1. Removing or replacing any existing CoreDNS plugins (e.g., `kubernetes`, `forward`).
40+
41+
42+
## Proposal
43+
44+
The proposal is to modify the MicroShift manifest that deploys CoreDNS (specifically the Corefile configuration) to include the `hosts` plugin. The hosts file referenced by CoreDNS will be an external file, managed directly by MicroShift cluster administrators—MicroShift itself does not author or control the contents of this file. Instead, MicroShift acts as a broker: it monitors the administrator-managed hosts file and ensures its contents are synchronized into a ConfigMap that is mounted into the CoreDNS pods. This approach allows any changes made by cluster admins to the hosts file to be automatically and immediately reflected in CoreDNS, ensuring that custom hostname mappings are always up to date and available to workloads, without requiring manual intervention or pod restarts.
45+
46+
The Corefile configuration will be updated to include a section for the `hosts` plugin and pointing to a hosts file mounted into the CoreDNS Pod.
47+
48+
**Example Corefile snippet (Conceptual Change):**
49+
50+
```corefile
51+
. {
52+
...
53+
# New hosts plugin entry:
54+
hosts /tmp/hosts/hosts {
55+
fallthrough
56+
}
57+
58+
reload
59+
60+
}
61+
```
62+
The `hosts` plugin is placed at the end of the plugin order to ensure that the default OpenShift service resolution is not overridden or disrupted; CoreDNS will only consult the custom hosts file if the standard resolution mechanisms do not provide an answer.
63+
64+
65+
### hosts file watcher service
66+
A new service, called the **hosts file watcher**, is introduced to MicroShift. This service is automatically started by MicroShift if the `dns.hosts.status` feature is enabled in the configuration.
67+
68+
Its primary responsibility is to monitor a specified hosts file (by default `/etc/hosts`, but configurable) for any changes and synchronize its contents into a MicroShift ConfigMap within the `openshift-dns` namespace. This ConfigMap is then mounted into the CoreDNS pods, enabling the CoreDNS `hosts` plugin to serve custom host-to-IP mappings in real time.
69+
70+
### Propagation Delay
71+
After making changes to the underlying hosts file (whether the default `/etc/hosts` or a custom path), administrators should be aware that it can take **up to 60-90 seconds** for the changes to be propagated and reflected within CoreDNS pods. This delay is primarily due to the Kubelet's sync period and the TTL (time-to-live) configured on the ConfigMap that delivers the hosts file to the CoreDNS pods.
72+
73+
During this propagation window, pods may not immediately resolve hostnames added, removed, or modified in the hosts file. No service restart is required for synchronization; propagation will occur automatically.
74+
75+
76+
### Workflow Description
77+
78+
**MicroShift** is the MicroShift main process.
79+
80+
1. MicroShift starts up.
81+
2. MicroShift loads its configuration. If the hosts feature is not enabled, no further action is taken. If enabled, continue to the next step.
82+
3. MicroShift launches a service that monitors the specified hosts file (default: /etc/hosts).
83+
4. The contents of the hosts file are synchronized to a ConfigMap in the openshift-dns namespace.
84+
5. MicroShift ensures that CoreDNS pods mount this ConfigMap.
85+
6. Any manual changes made to the hosts file are automatically propagated to the CoreDNS service in real time.
86+
87+
88+
### API Extensions
89+
The following changes in the configuration file are proposed:
90+
```yaml
91+
dns:
92+
hosts:
93+
status: <Enabled|Disabled>
94+
file: <filepath>
95+
```
96+
By default, the `dns.hosts.status` feature is **Disabled**. If a Admin enables this feature (i.e., sets `dns.hosts.status` to `Enabled`) but does not specify a file, MicroShift will automatically default `dns.hosts.file` to "/etc/hosts".
97+
98+
### Topology Considerations
99+
#### Hypershift / Hosted Control Planes
100+
N/A
101+
102+
### User Stories
103+
N/A
104+
105+
#### Standalone Clusters
106+
N/A
107+
108+
#### Single-node Deployments or MicroShift
109+
Enhancement is intended for MicroShift only.
110+
111+
### Implementation Details/Notes/Constraints
112+
https://github.com/openshift/microshift/pull/5491
113+
114+
### Risks and Mitigations
115+
116+
### Drawbacks
117+
N/A
118+
119+
## Test Plan
120+
## Graduation Criteria
121+
N/A
122+
123+
### Dev Preview -> Tech Preview
124+
N/A
125+
126+
### Tech Preview -> GA
127+
- Ability to utilize the enhancement end to end
128+
- End user documentation completed and published
129+
- Available by default
130+
- End-to-end tests
131+
132+
### Removing a deprecated feature
133+
N/A
134+
135+
## Upgrade / Downgrade Strategy
136+
When upgrading from 4.20 or earlier to 4.21, the new configuration fields will remain
137+
unset, causing the existing defaults to be used. (so the hosts values wont be passed to coredns)
138+
139+
## Version Skew Strategy
140+
N/A
141+
142+
## Operational Aspects of API Extensions
143+
N/A
144+
145+
## Support Procedures
146+
N/A
147+
148+
## Alternatives (Not Implemented)
149+
An alternative to this enhancement would be to mount the hosts file directly into the CoreDNS pods as a volume. In this approach, the `/etc/hosts` file (or a custom hosts file) from the host node would be mounted into the CoreDNS container, allowing CoreDNS to reference the latest hosts entries.
150+
151+
However, this method has significant drawbacks:
152+
- **Pod Restart Required:** Any changes to the hosts file would require a restart of the CoreDNS pods to take effect, as the file is only read at pod startup. This disrupts DNS resolution during the restart and does not provide seamless updates.

0 commit comments

Comments
 (0)