Troubleshooting

Procedure

• Check the version information by running the following command:

  $ microshift version

  Example output

  MicroShift Version: 4.18-0.microshift-e6980e25
  Base OCP Version: 4.18

Procedure

• To get the version number using the OpenShift CLI (oc), view the kube-public/microshift-version config map by running the following command:

  $ oc get configmap -n kube-public microshift-version -o yaml

  Example output

  apiVersion: v1
  data:
    major: "4"
    minor: "20"
    version: 4.20.0-0.microshift-fa441af87431
  kind: ConfigMap
  metadata:
    creationTimestamp: "2025-11-03T21:06:11Z"
    name: microshift-version
    namespace: kube-public

Procedure

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

  $ microshift-etcd version

  Example output

  microshift-etcd Version: 4.20.0
  Base etcd Version: 3.5.13

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

  $ microshift-etcd version -o json

  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"
  }

Procedure

• Check the system status, which returns the node status, by running the following command:

  $ sudo systemctl status microshift

  If MicroShift fails to start, this command returns the logs from the earlier run.

  Example healthy output

  ● microshift.service - MicroShift
       Loaded: loaded (/usr/lib/systemd/system/microshift.service; enabled; preset: disabled)
       Active: active (running) since <day> <date> 12:39:06 UTC; 47min ago
     Main PID: 20926 (microshift)
        Tasks: 14 (limit: 48063)
       Memory: 542.9M
          CPU: 2min 41.185s
       CGroup: /system.slice/microshift.service
               └─20926 microshift run
  
  <Month-Day> 13:23:06 i-06166fbb376f14a8b.<hostname> microshift[20926]: kube-apiserver I0528 13:23:06.876001   20926 controll>
  <Month-Day> 13:23:06 i-06166fbb376f14a8b.<hostname> microshift[20926]: kube-apiserver I0528 13:23:06.876574   20926 controll>
  # ...

• Optional: Get comprehensive logs by running the following command:

  $ sudo journalctl -u microshift

  Note

  The default configuration of the systemd journal service stores data in a volatile directory, which does not persist across restarts. To retain logs across system restarts, enable log persistence and set a maximum size limit for journal data.

• If MicroShift is running, check the status of active pods by entering the following command:

  $ oc get pods -A

  Example output

  NAMESPACE                   NAME                                                     READY   STATUS   RESTARTS  AGE
  default                     i-06166fbb376f14a8bus-west-2computeinternal-debug-qtwcr  1/1     Running  0		    46m
  kube-system                 csi-snapshot-controller-5c6586d546-lprv4                 1/1     Running  0		    51m
  openshift-dns               dns-default-45jl7                                        2/2     Running  0		    50m
  openshift-dns               node-resolver-7wmzf                                      1/1     Running  0		    51m
  openshift-ingress           router-default-78b86fbf9d-qvj9s                          1/1     Running  0		    51m
  openshift-ovn-kubernetes    ovnkube-master-5rfhh                                     4/4     Running  0		    51m
  openshift-ovn-kubernetes    ovnkube-node-gcnt6                                       1/1     Running  0		    51m
  openshift-service-ca        service-ca-bf5b7c9f8-pn6rk                               1/1     Running  0		    51m
  openshift-storage           topolvm-controller-549f7fbdd5-7vrmv                      5/5     Running  0		    51m
  openshift-storage           topolvm-node-rht2m                                       3/3     Running  0		    50m

  Note

  This example output shows a basic MicroShift installation. If you installed optional RPMs, the status of pods running those services is displayed in the output.

Prerequisites

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

• Manual backup logs are displayed in the terminal output.
• Automatic backup logs for rpm-ostree systems are available in the MicroShift journal logs.

Procedure

• Check the journal logs:

  $ sudo journalctl -u microshift

Procedure

• Get comprehensive MicroShift journal logs by running the following command:

  $ sudo journalctl -u microshift

• Check the greenboot journal logs by running the following command:

  $ sudo journalctl -u greenboot-healthcheck

• Examining the comprehensive logs of a specific boot uses three steps. First list the boots, then select the one you want from the list you obtained:

  • List the boots present in the journal logs by running the following command:

    $ sudo journalctl --list-boots

    Example output

    IDX  BOOT ID                          	FIRST ENTRY                 LAST ENTRY
     0   681ece6f5c3047e183e9d43268c5527f 	<Day> <Date> 12:27:58 UTC 	<Day> <Date>> 13:39:41 UTC
    #....

  • Check the journal logs for the specific boot by running the following command:

    $ sudo journalctl --boot _<idx_or_boot_id>

    where:

    idx_or_boot_id

    Replace <idx_or_boot_id> with the IDX or the BOOT ID number assigned to the specific boot that you want to check.

  • Check the journal logs for the boot of a specific service by running the following command:

    $ sudo journalctl --boot <idx_or_boot_id> -u <service_name>

    where:

    idx_or_boot_id

    Replace <idx_or_boot_id> with the IDX or the BOOT ID number assigned to the specific boot that you want to check.

    service_name

    Replace <service_name> with the name of the service that you want to check.

Procedure

• Check the current greenboot health check status by running the following command:

  $ systemctl show --property=SubState --value greenboot-healthcheck.service

  where:

  start

  Greenboot checks are still running.

  exited

  Checks have passed and greenboot has exited. Greenboot runs the scripts in the green.d directory when the system is in a healthy state.

  failed

  Checks have not passed. Greenboot runs the scripts in the red.d directory when the system is in this state and restarts the system.

• Check the numerical exit code of the greenboot health check service by running the following command:

  $ systemctl show --property=ExecMainStatus --value greenboot-healthcheck.service

  An exit code of 0 means the health check succeeded. A non-zero exit code means the health check failed.

• To see a report showing a message about boot status, such as Boot Status is GREEN - Health Check SUCCESS, use the following command:

  $ cat /run/motd.d/boot-status

  Example output

  Boot Status is GREEN - Health Check SUCCESS

Prerequisites

• You have installed the jq utility.
• You have root access to the node.

Procedure

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

  etcd:
    memoryLimitMB: 128

  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. Lower limits increase the time etcd takes to respond to queries. If the limit is too low or etcd usage is high, queries might time out.

• Stop and disable all MicroShift services
• Delete all MicroShift pods
• Delete all container image storage
• Reset network configuration
• Delete the /var/lib/microshift data directory
• Delete OVN-K networking configuration

Prerequisites

• You are logged into MicroShift.
• You have filed a support case.

• Stop and disable all MicroShift services
• Delete all MicroShift pods
• Reset network configuration
• Delete the /var/lib/microshift data directory
• Delete OVN-K networking configuration

Prerequisites

• You are logged into MicroShift.
• You have filed a support case.

• Stop all MicroShift services
• Delete all MicroShift pods
• Delete the OVN-K networking configuration

Prerequisites

• You are logged into MicroShift.
• You have filed a support case.

• Stop all MicroShift services
• Delete all MicroShift pods
• Delete all MicroShift certificates

Prerequisites

• You are logged into MicroShift.
• You have filed a support case.