Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Support

Red Hat build of MicroShift 4.20

Using support tools for MicroShift

Red Hat OpenShift Documentation Team

Abstract

This document provides information about how to use support tools for MicroShift.

Chapter 1. The etcd service
Copy link

The Red Hat build of MicroShift RPM includes the etcd service. The etcd service runs as a separate process. MicroShift automatically manages the etcd lifecycle.

1.1. Observe and debug the MicroShift etcd server
Copy link

Monitoring the etcd server is critical for maintaining system stability and diagnosing errors. You can gather journalctl logs to observe and debug the etcd server logs.

Prerequisites

  • The MicroShift service is running.

Procedure

  • To get the logs for etcd, run the following command: 

    $ sudo journalctl -u microshift-etcd.scope
    Copy to Clipboard Toggle word wrap
    Note

    MicroShift logs can be accessed separately from etcd logs using the journalctl -u microshift command.

1.2. Checking the etcd version
Copy link

You can get the version information for the etcd database included with your MicroShift by using one or both of the following methods, depending on the level of information that you need.

Procedure

  • To display the base database version information, run the following command: 

    $ microshift-etcd version
    Copy to Clipboard Toggle word wrap

    Example output

    microshift-etcd Version: 4.20.0
Base etcd Version: 3.5.13
    Copy to Clipboard Toggle word wrap

  • To display the full database version information, run the following command: 

    $ microshift-etcd version -o json
    Copy to Clipboard Toggle word wrap

    Example output

    {
  "major": "4",
  "minor": "20",
  "gitVersion": "4.20.0",
  "gitCommit": "140777711962eb4e0b765c39dfd325fb0abb3622",
  "gitTreeState": "clean",
  "buildDate": "2025-11-03T16:37:53Z",
  "goVersion": "go1.21.9"
  "compiler": "gc",
  "platform": "linux/amd64",
  "patch": "",
  "etcdVersion": "3.5.13"
}
    Copy to Clipboard Toggle word wrap

1.3. Troubleshooting etcd
Copy link

MicroShift runs etcd as a managed, separate process to store cluster state. To ensure optimal performance and resolve issues, as an administrator, you can observe system activity and enforce memory usage limits by using the MicroShift configuration file.

By default, etcd uses as much memory as necessary to handle the load on the system. In memory-constrained systems, you might need to limit the amount of memory etcd uses. Configure the memoryLimitMB parameter to manually restrict the memory consumption of the etcd server.

Procedure

  • Edit the /etc/microshift/config.yaml file to set the memoryLimitMB value. 

    etcd:
  memoryLimitMB: 128
    Copy to Clipboard Toggle word wrap
    Note

    The minimum required value for memoryLimitMB on MicroShift is 128 MB. Values close to the minimum value are more likely to impact etcd performance. The lower the limit, the longer etcd takes to respond to queries. If the limit is too low or the etcd usage is high, queries time out.

Verification

  1. After modifying the memoryLimitMB value in /etc/microshift/config.yaml, restart MicroShift by running the following command: 

    $ sudo systemctl restart microshift
    Copy to Clipboard Toggle word wrap

  2. Verify the new memoryLimitMB value is in use by running the following command: 

    $ systemctl show --property=MemoryHigh microshift-etcd.scope
    Copy to Clipboard Toggle word wrap

Chapter 2. Using sos reports
Copy link

As an administrator, you can use the sos tool to collect troubleshooting information about a {op-system-full} host and share that information with Red Hat support.

2.1. About sos reports
Copy link

You can use an sos report to troubleshoot a failing host or problems with Red Hat OpenShift GitOps. The sos tool combines plugins that help you gather information from different applications. The sos report command generates a detailed report that shows all of the enabled plugins and data from the different components and applications in a system.

A MicroShift-specific plugin from sos version 4.5.1 gathers the following data:

  • MicroShift configuration and version
  • YAML output for node and system namespaced resources
  • OVN-Kubernetes information

2.2. Gathering data from an sos report
Copy link

You can create an sos report about a failing {op-system-full} host that you can share with Red Hat support for troubleshooting.

Prerequisites

  • You must have the sos package installed.
  • You have root access to the host.

Procedure

  1. Log in to the failing host as a root user.

  2. Perform the debug report creation procedure by running the following command: 

    $ microshift-sos-report
    Copy to Clipboard Toggle word wrap

    Example output

    sosreport (version 4.5.1)

This command will collect diagnostic and configuration information from
this Red Hat Enterprise Linux system and installed applications.

An archive containing the collected information will be generated in
/var/tmp/sos.o0sznf_8 and may be provided to a Red Hat support
representative.

Any information provided to Red Hat will be treated in accordance with
the published support policies at:

        Distribution Website : https://www.redhat.com/
        Commercial Support   : https://www.access.redhat.com/

The generated archive may contain data considered sensitive and its
content should be reviewed by the originating organization before being
passed to any third party.

No changes will be made to system configuration.


 Setting up archive ...
 Setting up plugins ...
 Running plugins. Please wait ...

  Starting 1/2   microshift      [Running: microshift]
  Starting 2/2   microshift_ovn  [Running: microshift microshift_ovn]
  Finishing plugins              [Running: microshift]

  Finished running plugins

Found 1 total reports to obfuscate, processing up to 4 concurrently

sosreport-microshift-rhel9-2023-03-31-axjbyxw :    Beginning obfuscation...
sosreport-microshift-rhel9-2023-03-31-axjbyxw :    Obfuscation completed

Successfully obfuscated 1 report(s)

Creating compressed archive...

A mapping of obfuscated elements is available at
	/var/tmp/sosreport-microshift-rhel9-2023-03-31-axjbyxw-private_map

Your sosreport has been generated and saved in:
	/var/tmp/sosreport-microshift-rhel9-2023-03-31-axjbyxw-obfuscated.tar.xz

 Size	444.14KiB
 Owner	root
 sha256	922e5ff2db25014585b7c6c749d2c44c8492756d619df5e9838ce863f83d4269

Please send this file to your support representative.
    Copy to Clipboard Toggle word wrap

Chapter 3. Getting your node ID
Copy link

When providing information to Red Hat Support, it is helpful to provide the unique identifier of your node. For MicroShift, you can get your node ID manually by using the OpenShift CLI (oc) or by retrieving the ID from a file.

Note

A node ID is created only after the MicroShift service runs for the first time after installation.

3.1. Getting the node ID of a running node
Copy link

Retrieving the node ID enables you to uniquely identify a device within your deployment. The node ID is required to register the node with central management systems, analyze system logs and alerts, and ensure that configuration updates are targeted accurately.

Procedure

  • Get the ID of a running node using oc get by entering the following command: 

    $ oc get namespaces kube-system -o jsonpath={.metadata.uid}
    Copy to Clipboard Toggle word wrap

    Example output

    7cf13853-68f4-454e-8f5c-1af748cbfb1a
    Copy to Clipboard Toggle word wrap

  • Get the ID of a running node by retrieving it from the cluster-id file by entering the following command: 

    $ sudo cat /var/lib/microshift/cluster-id
    Copy to Clipboard Toggle word wrap

    Example output

    7cf13853-68f4-454e-8f5c-1af748cbfb1a
    Copy to Clipboard Toggle word wrap

3.2. Getting the node ID of a stopped node
Copy link

When the MicroShift service is inactive, you can prevent the use of standard API commands by retrieving the node ID from the file system. You can use this ID to identify offline nodes for disaster recovery, verify backup compatibility, and troubleshoot issues.

Procedure

  • Get the ID of a stopped node by retrieving it from the cluster-id file by entering the following command: 

    $ sudo cat /var/lib/microshift/cluster-id
    Copy to Clipboard Toggle word wrap

    Example output

    7cf13853-68f4-454e-8f5c-1af748cbfb1a
    Copy to Clipboard Toggle word wrap

Chapter 4. Support resources
Copy link

Use the following information to get more help with Red Hat Device Edge, including Red Hat build of MicroShift or Red Hat Enterprise Linux for Edge (RHEL for Edge). You can search the Red Hat Knowledgebase for immediate solutions, provide feedback on documentation, or open a formal support case through the Red Hat Customer Portal if you cannot resolve the issue yourself.

4.1. Getting support
Copy link

If you experience difficulty with a procedure described in this documentation, or with Red Hat build of MicroShift in general, visit the Red Hat Customer Portal.

From the Customer Portal, you can:

  • Search or browse through the Red Hat Knowledgebase of articles and solutions relating to Red Hat products.
  • Submit a support case to Red Hat Support.
  • Access other product documentation.

4.3. About the Red Hat Knowledgebase
Copy link

The Red Hat Knowledgebase provides rich content aimed at helping you make the most of Red Hat’s products and technologies. The Red Hat Knowledgebase consists of articles, product documentation, and videos outlining best practices on installing, configuring, and using Red Hat products. In addition, you can search for solutions to known issues, each providing concise root cause descriptions and remedial steps.

4.4. Searching the Red Hat Knowledgebase
Copy link

In the event of an Red Hat build of MicroShift issue, you can perform an initial search to determine if a solution already exists within the Red Hat Knowledgebase.

Prerequisites

  • You have a Red Hat Customer Portal account.

Procedure

  1. Log in to the Red Hat Customer Portal.
  2. Click Search.

  3. In the search field, input keywords and strings relating to the problem, including:

    • Red Hat build of MicroShift components (such as etcd)
    • Related procedure (such as installation)
    • Warnings, error messages, and other outputs related to explicit failures
  4. Click the Enter key.
  5. Optional: Select the Red Hat build of MicroShift product filter.
  6. Optional: Select the Documentation content type filter.

4.5. Submitting a support case
Copy link

If you encounter issues with MicroShift that cannot be resolved through the standard troubleshooting, you can submit a support case to Red Hat. Providing detailed descriptions and diagnostic data helps Red Hat Support to analyze the problem and help you with a resolution.

Prerequisites

  • The MicroShift service is running.
  • You have installed the OpenShift CLI (oc).
  • You have a Red Hat Customer Portal account.
  • You have a Red Hat Standard or Premium subscription.

Procedure

  1. Log in to the Customer Support page of the Red Hat Customer Portal.
  2. Click Get support.

  3. On the Cases tab of the Customer Support page:

    1. Optional: Change the pre-filled account and owner details if needed.
    2. Select the appropriate category for your issue, such as Bug or Defect, and click Continue.

  4. Enter the following information:

    1. In the Summary field, enter a concise but descriptive problem summary and further details about the symptoms being experienced, as well as your expectations.
    2. Select Red Hat Device Edge from the Product drop-down menu.
    3. Select 4 from the Version drop-down.
  5. Review the list of suggested Red Hat Knowledgebase solutions for a potential match against the problem that is being reported. If the suggested articles do not address the issue, click Continue.
  6. Review the updated list of suggested Red Hat Knowledgebase solutions for a potential match against the problem that is being reported. The list is refined as you provide more information during the case creation process. If the suggested articles do not address the issue, click Continue.
  7. Ensure that the account information presented is as expected, and if not, amend accordingly.

  8. Complete the following questions where prompted. Include which type of install type you are using, either RPM or embedded-image. Click Continue:

    • What are you experiencing? What are you expecting to happen?
    • Define the value or impact to you or the business.
    • Where are you experiencing this behavior? What environment?
    • When does this behavior occur? Frequency? Repeatedly? At certain times?
  9. Upload relevant diagnostic data files and click Continue. Include data gathered using the sos tool or etcd as a starting point, plus any issue-specific data that is not collected in those logs.
  10. Add relevant case management details and click Continue.
  11. Preview the case details and click Submit.

Red Hat build of MicroShift (MicroShift) includes a remote health monitoring service that uses the Telemetry API to collect data about your node’s performance, configuration, and usage. By analyzing lightweight telemetry data, such as, system version, resource capacity, and usage metrics, Red{bsp}Hat can proactively identify issues and prioritize new features.

Remote health monitoring is conducted in MicroShift by the collection of telemetry and configuration data about your node that is reported to Red Hat with the Telemeter API. A node that reports Telemetry to Red Hat is considered a connected node.

Telemetry is the term that Red Hat uses to describe the information being sent to Red Hat by the MicroShift Telemeter API. Lightweight attributes are sent from a connected node to Red Hat to monitor the health of a node.

Telemetry provides the following benefits:

  • Enhanced identification and resolution of issues. Events that might seem normal to an end-user can be observed by Red Hat from a broader perspective. Some issues can be more rapidly identified from this point of view and resolved without an end-user needing to open a support case or file a Jira issue.
  • Targeted prioritization of new features and functionality. The data collected provides information about system capabilities and usage characteristics. With this information, Red Hat can focus on developing the new features and functionality that have the greatest impact for our customers.

Telemetry sends a carefully chosen subset of the node monitoring metrics to Red Hat. The Telemeter API fetches the metrics values every hour and uploads the data to Red Hat. This stream of data is used by Red Hat to monitor nodes over time.

This debugging information is available to Red Hat Support and Engineering teams with the same restrictions as accessing data reported through support cases. All connected node information is used by Red Hat to help make MicroShift better.

Note

MicroShift does not support Prometheus. To view the Telemetry gathered from your node, you must contact Red Hat Support.

The MicroShift Telemetry API collects a lightweight set of metrics to assist with remote health monitoring and product improvement. The data payload is minimal, generally under 2KB, and is designed to have very minimal impact on node resources. The collected information is categorized into system configuration, node capacity, and usage metrics.

The following information is collected by Telemetry:

System information

The system information describes the basic configuration of your MicroShift node and where it is running, for example:

  • Version information, including the MicroShift node version.
  • The Red Hat Enterprise Linux (RHEL) version.
  • The RHEL deployment type.
Sizing information

Sizing information details the node capacity, for example:

  • The CPU cores MicroShift can use.
  • Architecture information.
  • The usable bytes of memory.
Usage information

Usage information outlines what is happening in the node, for example:

  • The CPU usage in percentage.
  • The memory usage in percentage.
  • The number of Kubernetes objects by resource type (CRDs).
  • The number of running containers, namespaces, and running pods.
  • The number of routes, ingress, services.
Note

Telemetry does not collect identifying information such as usernames or passwords. Red Hat does not intend to collect personal information. If Red Hat discovers that personal information has been inadvertently received, Red Hat deletes such information. To the extent that any Telemetry constitutes personal data, refer to the Red Hat Privacy Statement for more information about Red Hat’s privacy practices.

Additional details about how remote health monitoring data is used

Red Hat collects data about your use of the Red Hat product(s) for purposes such as providing support and troubleshooting, improving the offerings and user experience, responding to issues, and for billing purposes if applicable.

  • Collection safeguards: Red Hat employs technical and organizational measures designed to protect Telemetry data.
  • Sharing: Red Hat might share the data collected through the Telemetry API internally within Red Hat to improve your user experience. Red Hat might share Telemetry data with its business partners in an aggregated form that does not identify customers to help the partners better understand their markets and their customers' use of Red Hat offerings, or to ensure the successful integration of products jointly supported by those partners.
  • Third parties: Red Hat might engage certain third parties to assist in the collection, analysis, and storage of Telemetry data.
  • Disabling Telemetry data collection: You can disable MicroShift Telemetry by following the instructions in the "Opting out of remote health reporting for MicroShift" section.

5.3. Opting out of Telemetry for MicroShift
Copy link

By default, MicroShift enables the Telemetry service to collect health and usage data. You can disable this service if your node is operating in a disconnected environment or if you want to opt out of data collection.

Prerequisites

  • You installed OpenShift CLI (oc).
  • You have root access to the node.

Procedure

  1. If you have not done so, make a copy of the provided config.yaml.default file in the /etc/microshift/ directory, renaming it config.yaml.

  2. Keep the new MicroShift config.yaml in the /etc/microshift/ directory. Your config.yaml file is read every time the MicroShift service starts.

    Note

    After you create it, the config.yaml file takes precedence over built-in settings.

  3. Optional: Use a configuration snippet if you are using an existing MicroShift YAML. See "Using configuration snippets" in the Additional resources section for more information.

  4. Set the telemetry.status section of the MicroShift YAML with the Disabled value.

    Example disabled Telemetry configuration

    apiServer:
# ...
telemetry:
    endpoint: https://infogw.api.openshift.com
    status: Disabled
# ...
    Copy to Clipboard Toggle word wrap

Legal Notice
Copy link

Copyright © Red Hat.
Except as otherwise noted below, the text of and illustrations in this documentation are licensed by Red Hat under the Creative Commons Attribution–Share Alike 3.0 Unported license . If you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, the Red Hat logo, JBoss, Hibernate, and RHCE are trademarks or registered trademarks of Red Hat, LLC. or its subsidiaries in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
XFS is a trademark or registered trademark of Hewlett Packard Enterprise Development LP or its subsidiaries in the United States and other countries.
The OpenStack® Word Mark and OpenStack logo are trademarks or registered trademarks of the Linux Foundation, used under license.
All other trademarks are the property of their respective owners.
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top