How to enable debug logging for the rancher-system-agent

This document (000021631) is provided subject to the disclaimer at the end of this document.

Environment

A Rancher-provisioned RKE2 or K3s cluster

Situation

The Rancher System Agent is a daemon designed to run on a system and apply "plans" to the system. This is deployed on Linux nodes in Rancher-provisioned RKE2 and K3s clusters, and used by Rancher for node provisioning and configuration management.

During troubleshooting, it may be helpful to enable debug level logging on the rancher-system-agent, and this process is detailed below.

Resolution

Enable debug of custom clusters at provisioning time

1) Add the DEBUG environment variable to the Registration command, by setting CATTLE_AGENT_LOGLEVEL=debug when running the registration command on RKE2 and K3s Linux hosts, e.g.:

curl -fL https://<RANCHER_FQDN>/system-agent-install.sh | sudo CATTLE_AGENT_LOGLEVEL=debug sh -s - --server https://<RANCHER_FQDN> --label 'cattle.io/os=linux' --token <RANCHER_TOEKN> --ca-checksum <RANCHER_CA_CHECKSUM> --etcd --controlplane --worker

Enable debug for running clusters

Open a SSH session into the node and modify the rancher-system-agent service configuration file.

1) Run the command `systemctl edit rancher-system-agent.service` to open a systemd unit file override editor for the rancher-system-agent service.

2) Add a [Service] block to the file, below the top-level comment, with the single entry Environment=CATTLE_LOGLEVEL=debug per the example below, and save the file.

### Editing /etc/systemd/system/rancher-system-agent.service.d/override.conf
### Anything between here and the comment below will become the new contents of the file
[Service]
Environment=CATTLE_LOGLEVEL=debug

The changes will be saved to /etc/systemd/system/rancher-system-agent.service.d/override.conf

3) Restart the rancher-system-agent systemd service to apply the changes:

systemctl restart rancher-system-agent

4) You can now view and collect rancher-system-agent logs at debug level for troubleshooting.

5) Once you no longer required rancher-system-agent debug logs, you can run `systemctl edit rancher-system-agent.service` to remove the contents previously added, or set Environment=CATTLE_LOGLEVEL=info to return to info level logging.

Disclaimer

This Support Knowledgebase provides a valuable tool for SUSE customers and parties interested in our products and solutions to acquire information, ideas and learn from one another. Materials are provided for informational, personal or non-commercial use within your organization and are presented "AS IS" WITHOUT WARRANTY OF ANY KIND.