Fixing `upgrade.yaml --check` Failure In K3s-ansible

Dec 4, 2025 by Alex Johnson 53 views

Introduction

When managing K3s clusters using k3s-ansible, the upgrade.yaml playbook's --check mode is invaluable for previewing changes before they are applied. However, users might encounter an error where the check fails due to a missing K3s service backup file. This article delves into the root cause of this issue and provides a solution to ensure the upgrade.yaml --check command functions as expected, enhancing your K3s cluster management workflow.

Understanding the Issue

The problem arises during the execution of the upgrade.yaml playbook in check mode. Specifically, the task aimed at restoring the K3s service fails because a backup file, k3s.service.bak, is not found. The error message typically looks like this:

TASK [k3s_upgrade : Restore K3s service] **********************************************************************************************************************************************************************************************************************************************
[ERROR]: Task failed: Module failed: Source /etc/systemd/system/k3s.service.bak not found
Origin: /Users/mbathe/workspace/ansible/k3s-ansible/roles/k3s_upgrade/tasks/main.yml:48:7

This error indicates that the Restore K3s service task cannot find the expected backup file. The reason for this absence lies in the preceding step, Save current K3s service, which is responsible for creating this backup. When the playbook is run with the --check flag, certain tasks are skipped to simulate the execution without making actual changes. By default, the ansible.builtin.copy module respects the check mode, and therefore, the K3s service file is not backed up.

Root Cause Analysis

To reiterate, the core issue is that the Save current K3s service task, which uses the ansible.builtin.copy module, does not execute when the playbook is run in check mode. This is because Ansible's check mode prevents tasks that modify the system from running. Consequently, the k3s.service.bak file, which is crucial for the Restore K3s service task, is never created. This leads to the failure of the Restore K3s service task during the check execution.

This behavior is problematic because the --check mode is intended to provide a preview of the changes that will be made when the playbook is executed without the flag. If the check fails due to a missing file that would normally be created during a full run, the check mode loses its value as a reliable predictor of the playbook's outcome. Therefore, it is essential to ensure that all necessary files and configurations are in place, even when running in check mode.

Ensuring the integrity of the K3s service configuration is paramount for the stability and reliability of the cluster. The service file dictates how K3s operates, including its dependencies, execution parameters, and restart policies. A corrupted or missing service file can lead to K3s failing to start, resulting in downtime and potential data loss. Therefore, any process that modifies or restores the K3s service configuration must be handled with utmost care and precision.

In the context of k3s-ansible, the upgrade.yaml playbook automates the process of upgrading a K3s cluster. This involves updating the K3s binaries, modifying the service configuration, and restarting the K3s service. During this process, it is crucial to back up the existing service configuration before making any changes. This backup allows for easy rollback in case the upgrade fails or introduces unexpected issues. The Save current K3s service task is specifically designed to create this backup, ensuring that the original service configuration can be restored if needed.

The Solution: Disabling Check Mode for the Copy Task

The solution to this problem is to explicitly disable check mode for the Save current K3s service task. This can be achieved by adding the check_mode: false directive to the task definition in the upgrade.yaml playbook. By doing so, the ansible.builtin.copy module will always execute, regardless of whether the playbook is run with the --check flag or not. This ensures that the k3s.service.bak file is always created, allowing the Restore K3s service task to succeed even in check mode.

Here's the corrected task definition:

- name: Save current K3s service
  ansible.builtin.copy:
    src: "{{ item.path }}"
    dest: "{{ item.path }}.bak"
    remote_src: true
    mode: preserve
    force: true
  loop: "{{ k3s_service_files.files }}"
  check_mode: false

By adding check_mode: false, you are instructing Ansible to ignore the global check mode setting for this specific task. This means that the copy module will always execute, ensuring that the K3s service file is backed up, even when the playbook is run with the --check flag. This resolves the issue of the missing backup file and allows the Restore K3s service task to succeed during check mode execution.

Implementing this fix ensures that the --check mode accurately reflects the changes that will be made during a full playbook run. This provides peace of mind and allows you to confidently preview the upgrade process before applying it to your K3s cluster. By addressing this issue, you enhance the reliability and predictability of your K3s cluster management workflow.

Benefits of the Fix

Implementing this fix offers several key benefits:

Accurate Check Mode: Ensures that the --check mode accurately reflects the changes that will be made during a full playbook run.
Prevents Errors: Avoids the error caused by the missing k3s.service.bak file during check mode execution.
Improved Reliability: Enhances the reliability and predictability of the K3s cluster management workflow.
Peace of Mind: Provides confidence in the upgrade process by allowing you to preview the changes before applying them.
Streamlined Workflow: Simplifies the upgrade process by ensuring that all necessary files and configurations are in place, even when running in check mode.

By addressing this issue, you can streamline your K3s cluster management workflow and ensure that your upgrades are performed smoothly and reliably. The fix is simple to implement and offers significant benefits in terms of accuracy, reliability, and peace of mind.

Implementing the Fix

To implement the fix, follow these steps:

Locate the Task: Open the upgrade.yaml playbook and locate the Save current K3s service task.
Add the Directive: Add the check_mode: false directive to the task definition, as shown in the corrected example above.
Save the Playbook: Save the changes to the upgrade.yaml playbook.
Test the Fix: Run the upgrade.yaml playbook with the --check flag to verify that the error is resolved.

After implementing these steps, the upgrade.yaml --check command should execute without errors, providing an accurate preview of the changes that will be made during a full playbook run.

Conclusion

The error encountered when running upgrade.yaml --check in k3s-ansible due to a missing K3s service backup file can be easily resolved by disabling check mode for the Save current K3s service task. This ensures that the necessary backup file is always created, allowing the Restore K3s service task to succeed even in check mode. By implementing this fix, you can enhance the reliability and predictability of your K3s cluster management workflow.

By understanding the root cause of the issue and applying the simple solution outlined in this article, you can ensure that the upgrade.yaml --check command functions as expected, providing valuable insights into the changes that will be made during a full playbook run. This allows you to confidently manage your K3s clusters and avoid unexpected errors during the upgrade process.

For more information on Ansible check mode, refer to the official Ansible documentation.