OSDOCS#15568: Add MicroShift DNS hosts configuration feature #104923

tmalove · 2026-01-17T02:39:34Z

Version(s):
4.21+

Issue:
OSDOCS-15568

Link to docs preview:
Configuring custom hostnames
Parameters and values for the MicroShift config.yaml file

QE review:

[x ] QE has approved this change. (Kasturi)

ocpdocs-previewbot · 2026-01-17T02:46:25Z

🤖 Thu Jan 29 18:22:54 - Prow CI generated the docs preview:

https://104923--ocpdocs-pr.netlify.app/microshift/latest/microshift_configuring/microshift-using-config-yaml.html

ocpdocs-vale-bot · 2026-01-17T02:47:42Z

modules/microshift-config-resolve-custom-hostnames.adoc

+* Add the following `hosts` plugin at the end of the file:
+
+[source,yaml]
+----


🤖 [error] AsciiDocDITA.TaskStep: Content other than a single list cannot be mapped to DITA tasks.

ocpdocs-vale-bot · 2026-01-19T06:18:30Z

modules/microshift-config-resolve-custom-hostnames.adoc

+
+* Save your change in the file.
+
+[NOTE]


🤖 [error] AsciiDocDITA.TaskStep: Content other than a single list cannot be mapped to DITA tasks.

After editing Microshift configuration, a service restart is required.
After the restart, will be monitored for changes (without requiring further service restarts),
So we need to restart to activate the feature (so it will start monitoring the specified file), after that, no restart is needed. (unless we change )

eslutsky · 2026-01-19T11:19:03Z

modules/microshift-config-resolve-custom-hostnames.adoc

+* You have root access to the node.
+
+.Procedure
+. Edit the `config.yaml` file in the `etc/hosts` directory.


config.yaml is the standard Microshift configuration file, and that's what we are editing,
/etc/hosts is the default file on the Microshift hosts that will be propagated to the coreDNS to respond to DNS queries originating from the pods (in case is not set).
That file can be changed with the "file: " in the hosts section, as mentioned below.

eslutsky · 2026-01-19T11:21:06Z

modules/microshift-config-resolve-custom-hostnames.adoc

+
+.Procedure
+. Edit the `config.yaml` file in the `etc/hosts` directory.
+. Add the following `hosts` plugin at the end of the file:


Suggested change

. Add the following `hosts` plugin at the end of the file:

. Add the following `hosts` configuration at the end of the file:

plugin is not the correct term we use.

eslutsky · 2026-01-21T16:41:49Z

modules/microshift-config-resolve-custom-hostnames.adoc

+* You have root access to the node.
+
+.Procedure
+. Edit the `/etc/hosts` file.


Suggested change

. Edit the `/etc/hosts` file.

. Edit the microShift configuration in `/etc/microshift/config.yaml` file.

There is a table describing all the various configuration options in config.yaml, we should add the new options under dns.baseDomain

| hosts.status | Enabled, Disabled | by default set to Disabled when not configured | | host.file | String| filepath by default set to '/etc/hosts' |

eslutsky · 2026-01-21T16:43:22Z

modules/microshift-config-resolve-custom-hostnames.adoc

+ hosts:
+----
+
+. Save your file update.


Suggested change

. Save your file update.

. Save your configuration yaml file.

eslutsky · 2026-01-21T16:44:43Z

modules/microshift-config-resolve-custom-hostnames.adoc

+$ sudo systemctl restart microshift
+----
+
+After this initial restart, MicroShift automatically monitors the `hosts` file for updates. You do not have to restart the service for additional changes to the `hosts` file to take effect.


Suggested change

After this initial restart, MicroShift automatically monitors the `hosts` file for updates. You do not have to restart the service for additional changes to the `hosts` file to take effect.

After this initial restart, MicroShift automatically monitors the `hosts.file` for updates. You do not have to restart the service for additional changes to the `hosts.file` file to take effect.

eslutsky · 2026-01-21T16:47:06Z

modules/microshift-config-resolve-custom-hostnames.adoc

+= Configuring custom hostnames
+
+[role="_abstract"]
+You can use the `hosts` file to resolve custom hostnames for pod workloads. This enables applications to resolve fixed hostnames, such as the local machine or external services, by applying `/etc/hosts` functionality to DNS queries within the node. The functionality is applied by adding specific configuration to the `etc/hosts` file and completing a service restart.


Suggested change

You can use the `hosts` file to resolve custom hostnames for pod workloads. This enables applications to resolve fixed hostnames, such as the local machine or external services, by applying `/etc/hosts` functionality to DNS queries within the node. The functionality is applied by adding specific configuration to the `etc/hosts` file and completing a service restart.

You can use the `hosts` file to resolve custom hostnames for pod workloads. This enables applications to resolve fixed hostnames, such as the local machine or external services, by applying `/etc/hosts` functionality to DNS queries within the node. The functionality is applied by adding specific configuration to the Microshift configuration yaml file and completing a service restart.

tmalove · 2026-01-22T05:18:34Z

@eslutsky @kasturinarra I have the updated section links available. Thanks!

eslutsky · 2026-01-22T14:19:02Z

modules/microshift-config-parameters-table.adoc

 |`valid domain`
 |Base domain of the node. All managed DNS records are subdomains of this base.

+|`hosts.status`


Suggested change

|`hosts.status`

|`dns.hosts.status`

eslutsky · 2026-01-22T14:19:28Z

modules/microshift-config-parameters-table.adoc

+|`Enabled`, `Disabled`
+|Default set to `Disabled` when not configured.
+
+|`host.file`


Suggested change

|`host.file`

|`dns.hosts.file`

eslutsky · 2026-01-22T14:20:23Z

modules/microshift-config-resolve-custom-hostnames.adoc

+$ sudo systemctl restart microshift
+----
+
+After this initial restart, MicroShift automatically monitors the `hosts.file` file for updates. You do not have to restart the service for additional changes to the `hosts.file` file to take effect.


Suggested change

After this initial restart, MicroShift automatically monitors the `hosts.file` file for updates. You do not have to restart the service for additional changes to the `hosts.file` file to take effect.

After this initial restart, if dns.hosts.status is Enabled , MicroShift automatically monitors the `dns.hosts.file` file for updates. You do not have to restart the service for additional changes to the `dns.hosts.file` file to take effect.

tmalove · 2026-01-23T05:56:15Z

@eslutsky one more review...thank you!

eslutsky · 2026-01-26T08:48:49Z

modules/microshift-config-resolve-custom-hostnames.adoc

+$ sudo systemctl restart microshift
+----
+
+After this initial restart, if `dns.hosts.status` is set to `Enabled`, MicroShift automatically monitors the `dns.hosts.file` file for updates. You do not have to restart the service before additional changes to the `dns.hosts.file` file are active.


Suggested change

After this initial restart, if `dns.hosts.status` is set to `Enabled`, MicroShift automatically monitors the `dns.hosts.file` file for updates. You do not have to restart the service before additional changes to the `dns.hosts.file` file are active.

After this initial restart, if `dns.hosts.status` is set to `Enabled`, MicroShift automatically monitors the `dns.hosts.file` file for updates. You do not have to restart the MicroShift service until the MicroShift configuration yaml is edited again.

.

eslutsky · 2026-01-26T08:50:34Z

modules/microshift-config-resolve-custom-hostnames.adoc

+dns:
+ hosts:
+   status: <Enabled|Disabled>
+   file: <filepath>
+dns:
+ hosts:


Suggested change

dns:

hosts:

status: <Enabled|Disabled>

file: <filepath>

dns:

hosts:

This part is a duplicate and not needed

eslutsky

few nits.

tmalove · 2026-01-27T02:17:19Z

Thanks @eslutsky, I made the updates. @kasturinarra will you review? Thanks !

eslutsky · 2026-01-27T10:14:30Z

/lgtm
look goods to me

kasturinarra · 2026-01-28T07:24:11Z

/lgtm

openshift-ci · 2026-01-28T20:19:56Z

New changes are detected. LGTM label has been removed.

tmalove · 2026-01-28T20:30:08Z

/label merge-review-needed

bergerhoffer · 2026-01-28T20:34:10Z

/label merge-review-in-progress

bergerhoffer

One blocker (the DITA migration error) and a few other suggestions to fix before merging!

bergerhoffer · 2026-01-28T20:38:24Z

modules/microshift-config-resolve-custom-hostnames.adoc

+
+After this initial restart, if `dns.hosts.status` is set to `Enabled`, MicroShift automatically monitors the `dns.hosts.file` file for updates. You do not have to restart the {microshift-short} service until the {microshift-short} configuration YAML file is changed again.
+
+[NOTE]


The DITA message above is correct - you can't have this NOTE here after the procedure steps. You either have to attach it at the end of the last step, or move it up above the prerequisites. Check out the confluence page if you need more info: https://spaces.redhat.com/spaces/OSDOCS/pages/654185635/Content+updates+in+preparation+for+migrating+to+DITA

bergerhoffer · 2026-01-28T20:41:59Z

modules/microshift-config-resolve-custom-hostnames.adoc

+$ sudo systemctl restart microshift
+----
+
+After this initial restart, if `dns.hosts.status` is set to `Enabled`, MicroShift automatically monitors the `dns.hosts.file` file for updates. You do not have to restart the {microshift-short} service until the {microshift-short} configuration YAML file is changed again.


There are a handful of places that hardcode "MicroShift" - not critical but consider using the attribute like you do elsewhere

bergerhoffer · 2026-01-28T20:43:10Z

modules/microshift-config-resolve-custom-hostnames.adoc

@@ -0,0 +1,42 @@
+// Module included in the following assemblies:
+//
+// * microshift/using-config-tools.adoc


This looks like it should be:

Suggested change

// * microshift/using-config-tools.adoc

// * microshift_configuring/microshift-using-config-yaml.adoc

openshift-ci · 2026-01-29T18:24:20Z

@tmalove: all tests passed!

Full PR test history. Your PR dashboard.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

tmalove · 2026-01-29T18:28:47Z

@bergerhoffer I updated the content per your feedback...thanks!

bergerhoffer

LGTM now, thanks! Merging

bergerhoffer · 2026-01-29T18:33:13Z

/cherrypick enterprise-4.21

openshift-cherrypick-robot · 2026-01-29T18:34:05Z

@bergerhoffer: new pull request created: #105698

Details

In response to this:

/cherrypick enterprise-4.21

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

openshift-ci bot added the size/M Denotes a PR that changes 30-99 lines, ignoring generated files. label Jan 17, 2026

ocpdocs-vale-bot reviewed Jan 17, 2026

View reviewed changes

ocpdocs-vale-bot reviewed Jan 19, 2026

View reviewed changes

eslutsky reviewed Jan 19, 2026

View reviewed changes

tmalove changed the title ~~OSDOCS#15568: Add MicroShift DNS hosts plugin feature~~ OSDOCS#15568: Add MicroShift DNS hosts configuration feature Jan 20, 2026

eslutsky reviewed Jan 21, 2026

View reviewed changes

tmalove force-pushed the ms-osdocs-15568-tlove branch from 30079b3 to 513c0d9 Compare January 22, 2026 03:58

eslutsky reviewed Jan 22, 2026

View reviewed changes

tmalove force-pushed the ms-osdocs-15568-tlove branch 2 times, most recently from 834fba4 to a5d8a72 Compare January 23, 2026 05:30

eslutsky reviewed Jan 26, 2026

View reviewed changes

openshift-ci bot assigned eslutsky Jan 27, 2026

openshift-ci bot added the lgtm Indicates that a PR is ready to be merged. label Jan 27, 2026

openshift-ci bot assigned kasturinarra Jan 28, 2026

tmalove force-pushed the ms-osdocs-15568-tlove branch from 888c1c2 to 7ba0eb6 Compare January 28, 2026 20:19

openshift-ci bot removed the lgtm Indicates that a PR is ready to be merged. label Jan 28, 2026

openshift-ci bot added the merge-review-needed Signifies that the merge review team needs to review this PR label Jan 28, 2026

openshift-ci bot added the merge-review-in-progress Signifies that the merge review team is reviewing this PR label Jan 28, 2026

bergerhoffer reviewed Jan 28, 2026

View reviewed changes

bergerhoffer added branch/enterprise-4.21 and removed merge-review-in-progress Signifies that the merge review team is reviewing this PR merge-review-needed Signifies that the merge review team needs to review this PR labels Jan 28, 2026

bergerhoffer added this to the Planned for 4.21 GA milestone Jan 28, 2026

initial update to add dns file and update the assembly

8563937

tmalove force-pushed the ms-osdocs-15568-tlove branch from db36ae1 to 8563937 Compare January 29, 2026 18:15

bergerhoffer reviewed Jan 29, 2026

View reviewed changes

bergerhoffer merged commit 185916c into openshift:main Jan 29, 2026
2 checks passed

openshift-cherrypick-robot mentioned this pull request Jan 29, 2026

[enterprise-4.21] OSDOCS#15568: Add MicroShift DNS hosts configuration feature #105698

Merged

	. Add the following `hosts` plugin at the end of the file:
	. Add the following `hosts` configuration at the end of the file:

	. Edit the `/etc/hosts` file.
	. Edit the microShift configuration in `/etc/microshift/config.yaml` file.

	. Save your file update.
	. Save your configuration yaml file.

	After this initial restart, MicroShift automatically monitors the `hosts` file for updates. You do not have to restart the service for additional changes to the `hosts` file to take effect.
	After this initial restart, MicroShift automatically monitors the `hosts.file` for updates. You do not have to restart the service for additional changes to the `hosts.file` file to take effect.

	You can use the `hosts` file to resolve custom hostnames for pod workloads. This enables applications to resolve fixed hostnames, such as the local machine or external services, by applying `/etc/hosts` functionality to DNS queries within the node. The functionality is applied by adding specific configuration to the `etc/hosts` file and completing a service restart.
	You can use the `hosts` file to resolve custom hostnames for pod workloads. This enables applications to resolve fixed hostnames, such as the local machine or external services, by applying `/etc/hosts` functionality to DNS queries within the node. The functionality is applied by adding specific configuration to the Microshift configuration yaml file and completing a service restart.

	After this initial restart, MicroShift automatically monitors the `hosts.file` file for updates. You do not have to restart the service for additional changes to the `hosts.file` file to take effect.
	After this initial restart, if dns.hosts.status is Enabled , MicroShift automatically monitors the `dns.hosts.file` file for updates. You do not have to restart the service for additional changes to the `dns.hosts.file` file to take effect.

	After this initial restart, if `dns.hosts.status` is set to `Enabled`, MicroShift automatically monitors the `dns.hosts.file` file for updates. You do not have to restart the service before additional changes to the `dns.hosts.file` file are active.
	After this initial restart, if `dns.hosts.status` is set to `Enabled`, MicroShift automatically monitors the `dns.hosts.file` file for updates. You do not have to restart the MicroShift service until the MicroShift configuration yaml is edited again.
	.

	// * microshift/using-config-tools.adoc
	// * microshift_configuring/microshift-using-config-yaml.adoc

OSDOCS#15568: Add MicroShift DNS hosts configuration feature #104923

OSDOCS#15568: Add MicroShift DNS hosts configuration feature #104923

Conversation

tmalove commented Jan 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ocpdocs-previewbot commented Jan 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tmalove commented Jan 22, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tmalove commented Jan 23, 2026

Uh oh!

eslutsky Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eslutsky left a comment

Choose a reason for hiding this comment

Uh oh!

tmalove commented Jan 27, 2026

Uh oh!

eslutsky commented Jan 27, 2026

Uh oh!

kasturinarra commented Jan 28, 2026

Uh oh!

openshift-ci bot commented Jan 28, 2026

Uh oh!

tmalove commented Jan 28, 2026

Uh oh!

bergerhoffer commented Jan 28, 2026

Uh oh!

bergerhoffer left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

openshift-ci bot commented Jan 29, 2026

Uh oh!

tmalove commented Jan 29, 2026

Uh oh!

bergerhoffer left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

bergerhoffer commented Jan 29, 2026

Uh oh!

openshift-cherrypick-robot commented Jan 29, 2026

Uh oh!

Reviewers

tmalove commented Jan 17, 2026 •

edited

Loading

ocpdocs-previewbot commented Jan 17, 2026 •

edited

Loading

eslutsky Jan 26, 2026 •

edited

Loading