> For the complete documentation index, see [llms.txt](https://stakpak.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stakpak.gitbook.io/docs/how-it-works/rulebooks/infrastructure-software-upgrades.md).

# Infrastructure Software Upgrades

## Introduction

This rulebook defines a technology-agnostic methodology for upgrading infrastructure components safely and efficiently, ensuring reliable deployments through:

* Identifying current and target versions with clear upgrade intent
* Reviewing all change logs between the current and target versions for breaking changes
* Assessing dependencies, risks, and required upgrade tools or steps
* Planning and executing upgrades in a reversible, non-destructive manner
* Verifying functionality and health checks post-upgrade

## Goal

### Why did we make this rule book?

* To avoid failed or unstable upgrades caused by missing critical change log information.
* To ensure upgrades are planned, tested, and executed in a safe and reversible manner.
* To prevent downtime or service disruption by accounting for dependencies and breaking changes.

### What will you achieve?

* Smooth, predictable upgrades with minimal risk of downtime.
* Clear, repeatable workflows for assessing and executing component upgrades.
* Verified functionality and stability of upgraded components and their dependencies.

### Who is this for?

This rulebook is for anyone responsible for maintaining or upgrading infrastructure components who needs a safe, reliable, and repeatable upgrade process.

## Workflow

This methodology provides a structured, safe approach for upgrading infrastructure components while minimizing downtime and risk.

1. Identify Current Version: Determine the version of the component you plan to upgrade.
2. Select Target Version: Research available versions, preferring stable releases unless testing or specific requirements dictate otherwise.
3. Review Change Logs: Examine the change logs for all versions between the current and target versions to identify breaking changes.
4. Assess Risks and Dependencies: Note potential breaking changes, dependencies, and tools required for the upgrade.
5. Plan for Safety: Design a reversible, non-destructive upgrade path, including backups or rolling deployments.
6. Document the Plan: Write the upgrade plan in markdown for review or approval.
7. Execute the Upgrade: Proceed according to the plan, adjusting as needed for unexpected issues.
8. Validate the Upgrade: Test the upgraded component and its dependencies to ensure proper functionality and stability.

## Use Cases

### **Upgrading Kubernetes Clusters**

Upgrade Kubernetes for better security, stability, and new features.

## References

* [Kubernetes Upgrade Documentation](https://kubernetes.io/docs/tasks/administer-cluster/cluster-upgrade/)