Repository: zarf-dev/zarf
Pull request #3551: 2335 docs best practices
Author: login: brandtkeller
Labels: name: documentation 📘
description: Improvements or additions to documentation
Created: 2025-03-03T21:35:35Z | Merged: 2025-03-05T22:49:23Z

## Description

Need for documentation of the `zarf init` day 2 operations. Following helm with the use of a `Best Practices` section of the docs that we can expand for other opportunities. 

## Related Issue

Fixes #2335

Relates to #1684

## Checklist before merging

- [x] Test, docs, adr added or updated as needed
- [x] [Contributor Guide Steps](https://github.com/zarf-dev/zarf/blob/main/CONTRIBUTING.md#developer-workflow) followed


Linked issue #2335: Document workflow for deploying a newer version of the init package onto an existing zarf clusters
### Is your feature request related to a problem? Please describe.
Currently we don't have much on the docs site explaining how zarf clusters in should be updated in the day two scenario. I believe, it should just be redeploying the init package, then the new zarf package, but we should make sure that info is easy to find. We should also talk about rolling back the deployment of a package to an earlier package. Not sure if there are any pitfalls there or other common day two "traps" one might fall into. 

The best practices page proposed in #1684 could be a decent spot, otherwise we could have a page dedicated to day two advice

Diff:
diff --git a/site/astro.config.ts b/site/astro.config.ts
index d00b26b4af..00193880c7 100644
--- a/site/astro.config.ts
+++ b/site/astro.config.ts
@@ -71,6 +71,11 @@ export default defineConfig({
           autogenerate: { directory: "commands" },
           collapsed: true,
         },
+        {
+          label: "Best Practices",
+          autogenerate: { directory: "best-practices" },
+          collapsed: true,
+        },
         {
           label: "Reference",
           autogenerate: { directory: "ref", collapsed: true },
diff --git a/site/package-lock.json b/site/package-lock.json
index fb0765eb60..009295afe1 100644
--- a/site/package-lock.json
+++ b/site/package-lock.json
@@ -106,11 +106,12 @@
       }
     },
     "node_modules/@astrojs/markdown-remark": {
-      "version": "4.3.2",
-      "resolved": "https://registry.npmjs.org/@astrojs/markdown-remark/-/markdown-remark-4.3.2.tgz",
-      "integrity": "sha512-4Oa4VaYiBd0MatB+rWIU/0A8pZH/sK3c2QkRYb+OO2lPl+qzevJtWaZY8hAQc4qurIOlRdn6B6ofDAGhWw+DSg==",
+      "version": "5.1.0",
+      "resolved": "https://registry.npmjs.org/@astrojs/markdown-remark/-/markdown-remark-5.1.0.tgz",
+      "integrity": "sha512-S6Z3K2hOB7MfjeDoHsotnP/q2UsnEDB8NlNAaCjMDsGBZfTUbWxyLW3CaphEWw08f6KLZi2ibK9yC3BaMhh2NQ==",
+      "license": "MIT",
       "dependencies": {
-        "@astrojs/prism": "^3.0.0",
+        "@astrojs/prism": "^3.1.0",
         "github-slugger": "^2.0.0",
         "hast-util-from-html": "^2.0.0",
         "hast-util-to-text": "^4.0.0",
@@ -131,11 +132,12 @@
       }
     },
     "node_modules/@astrojs/mdx": {
-      "version": "2.2.2",
-      "resolved": "https://registry.npmjs.org/@astrojs/mdx/-/mdx-2.2.2.tgz",
-      "integrity": "sha512-5SIFtOctC813HFyqJwBf5TBvlT9sbiOOv+bdvzAoiBSab95dC7PZhss22EvUEx+897c81YoIZ4F9fg4ZkxBFIw==",
+      "version": "2.3.1",
+      "resolved": "https://registry.npmjs.org/@astrojs/mdx/-/mdx-2.3.1.tgz",
+      "integrity": "sha512-BOQFKD2Pi9cRntNQJlpF2fh4xV8doNpmVy9NKI95r4jsitrY4X5aTOhAowi+fkQgP/zW1A4HwCyQ6Pdam6z8zQ==",
+      "license": "MIT",
       "dependencies": {
-        "@astrojs/markdown-remark": "4.3.2",
+        "@astrojs/markdown-remark": "5.1.0",
         "@mdx-js/mdx": "^3.0.0",
         "acorn": "^8.11.2",
         "es-module-lexer": "^1.4.1",
@@ -152,7 +154,7 @@
         "vfile": "^6.0.1"
       },
       "engines": {
-        "node": ">=18.14.1"
+        "node": "^18.17.1 || ^20.3.0 || >=21.0.0"
       },
       "peerDependencies": {
         "astro": "^4.0.0"
@@ -179,9 +181,10 @@
       }
     },
     "node_modules/@astrojs/starlight": {
-      "version": "0.21.2",
-      "resolved": "https://registry.npmjs.org/@astrojs/starlight/-/starlight-0.21.2.tgz",
-      "integrity": "sha512-ziDfrbhBjw/+HwMITk6yz7SbkQKQJZY9GlaPHntSPq4kYs+b2ru3toIxj2l3T9LUFtUpNWHkj+C1wJTmfLZfaw==",
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@astrojs/starlight/-/starlight-0.21.5.tgz",
+      "integrity": "sha512-cvftxu7DM4C25KGSxqyIk81DiQGX0zx9s5sfmprd1kKQK1h/MQXaRVDCpJrK4SjrgWtpG1UoKLJZBgD5w4k9kw==",
+      "license": "MIT",
       "dependencies": {
         "@astrojs/mdx": "^2.1.1",
         "@astrojs/sitemap": "^3.0.5",
@@ -200,7 +203,6 @@
         "rehype": "^13.0.1",
         "remark-directive": "^3.0.0",
         "unified": "^11.0.4",
-        "unist-util-remove": "^4.0.0",
         "unist-util-visit": "^5.0.0",
         "vfile": "^6.0.1"
       },
@@ -2389,14 +2391,16 @@
       "version": "1.0.4",
       "resolved": "https://registry.npmjs.org/@types/nlcst/-/nlcst-1.0.4.tgz",
       "integrity": "sha512-ABoYdNQ/kBSsLvZAekMhIPMQ3YUZvavStpKYs7BjLLuKVmIMA0LUgZ7b54zzuWJRbHF80v1cNf4r90Vd6eMQDg==",
+      "license": "MIT",
       "dependencies": {
         "@types/unist": "^2"
       }
     },
     "node_modules/@types/nlcst/node_modules/@types/unist": {
-      "version": "2.0.10",
-      "resolved": "https://registry.npmjs.org/@types/unist/-/unist-2.0.10.tgz",
-      "integrity": "sha512-IfYcSBWE3hLpBg8+X2SEa8LVkJdJEkT2Ese2aaLs3ptGdVtABxndrMaxuFlQ1qdFf9Q5rDvDpxI3WwgvKFAsQA=="
+      "version": "2.0.11",
+      "resolved": "https://registry.npmjs.org/@types/unist/-/unist-2.0.11.tgz",
+      "integrity": "sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA==",
+      "license": "MIT"
     },
     "node_modules/@types/node": {
       "version": "20.11.30",
@@ -3699,10 +3703,11 @@
       }
     },
     "node_modules/cross-spawn": {
-      "version": "7.0.3",
-      "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.3.tgz",
-      "integrity": "sha512-iRDPJKUPVEND7dHPO8rkbOnPpyDygcDFtWjpeWNCgy8WP2rXcxXL8TskReQl6OrB2G7+UJrags1q15Fudc7G6w==",
+      "version": "7.0.6",
+      "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
+      "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==",
       "dev": true,
+      "license": "MIT",
       "dependencies": {
         "path-key": "^3.1.0",
         "shebang-command": "^2.0.0",
@@ -5527,13 +5532,14 @@
       "integrity": "sha512-H8jvkz1O50L3dMZCsLqiuB2tA7muqbSg1AtGEkN0leAqGjsUzDJir3Zwr02BhqdcITPg3ei3mZ+HjMocAknhhg=="
     },
     "node_modules/katex": {
-      "version": "0.16.10",
-      "resolved": "https://registry.npmjs.org/katex/-/katex-0.16.10.tgz",
-      "integrity": "sha512-ZiqaC04tp2O5utMsl2TEZTXxa6WSC4yo0fv5ML++D3QZv/vx2Mct0mTlRx3O+uUkjfuAgOkzsCmq5MiUEsDDdA==",
+      "version": "0.16.21",
+      "resolved": "https://registry.npmjs.org/katex/-/katex-0.16.21.tgz",
+      "integrity": "sha512-XvqR7FgOHtWupfMiigNzmh+MgUVmDGU2kXZm899ZkPfcuoPuFxyHmXsgATDpFZDAXCI8tvinaVcDo8PIIJSo4A==",
       "funding": [
         "https://opencollective.com/katex",
         "https://github.com/sponsors/katex"
       ],
+      "license": "MIT",
       "dependencies": {
         "commander": "^8.3.0"
       },
@@ -7514,6 +7520,7 @@
       "version": "3.1.1",
       "resolved": "https://registry.npmjs.org/nlcst-to-string/-/nlcst-to-string-3.1.1.tgz",
       "integrity": "sha512-63mVyqaqt0cmn2VcI2aH6kxe1rLAmSROqHMA0i4qqg1tidkfExgpb0FGMikMCn86mw5dFtBtEANfmSSK7TjNHw==",
+      "license": "MIT",
       "dependencies": {
         "@types/nlcst": "^1.0.0"
       },
@@ -7746,6 +7753,7 @@
       "version": "5.0.1",
       "resolved": "https://registry.npmjs.org/parse-latin/-/parse-latin-5.0.1.tgz",
       "integrity": "sha512-b/K8ExXaWC9t34kKeDV8kGXBkXZ1HCSAZRYE7HR14eA1GlXX5L8iWhs8USJNhQU9q5ci413jCKF0gOyovvyRBg==",
+      "license": "MIT",
       "dependencies": {
         "nlcst-to-string": "^3.0.0",
         "unist-util-modify-children": "^3.0.0",
@@ -8467,6 +8475,7 @@
       "version": "2.1.0",
       "resolved": "https://registry.npmjs.org/remark-smartypants/-/remark-smartypants-2.1.0.tgz",
       "integrity": "sha512-qoF6Vz3BjU2tP6OfZqHOvCU0ACmu/6jhGaINSQRI9mM7wCxNQTKB3JUAN4SVoN2ybElEDTxBIABRep7e569iJw==",
+      "license": "MIT",
       "dependencies": {
         "retext": "^8.1.0",
         "retext-smartypants": "^5.2.0",
@@ -8522,6 +8531,7 @@
       "version": "8.1.0",
       "resolved": "https://registry.npmjs.org/retext/-/retext-8.1.0.tgz",
       "integrity": "sha512-N9/Kq7YTn6ZpzfiGW45WfEGJqFf1IM1q8OsRa1CGzIebCJBNCANDRmOrholiDRGKo/We7ofKR4SEvcGAWEMD3Q==",
+      "license": "MIT",
       "dependencies": {
         "@types/nlcst": "^1.0.0",
         "retext-latin": "^3.0.0",
@@ -8537,6 +8547,7 @@
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/retext-latin/-/retext-latin-3.1.0.tgz",
       "integrity": "sha512-5MrD1tuebzO8ppsja5eEu+ZbBeUNCjoEarn70tkXOS7Bdsdf6tNahsv2bY0Z8VooFF6cw7/6S+d3yI/TMlMVVQ==",
+      "license": "MIT",
       "dependencies": {
         "@types/nlcst": "^1.0.0",
         "parse-latin": "^5.0.0",
@@ -8549,14 +8560,16 @@
       }
     },
     "node_modules/retext-latin/node_modules/@types/unist": {
-      "version": "2.0.10",
-      "resolved": "https://registry.npmjs.org/@types/unist/-/unist-2.0.10.tgz",
-      "integrity": "sha512-IfYcSBWE3hLpBg8+X2SEa8LVkJdJEkT2Ese2aaLs3ptGdVtABxndrMaxuFlQ1qdFf9Q5rDvDpxI3WwgvKFAsQA=="
+      "version": "2.0.11",
+      "resolved": "https://registry.npmjs.org/@types/unist/-/unist-2.0.11.tgz",
+      "integrity": "sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA==",
+      "license": "MIT"
     },
     "node_modules/retext-latin/node_modules/unified": {
       "version": "10.1.2",
       "resolved": "https://registry.npmjs.org/unified/-/unified-10.1.2.tgz",
       "integrity": "sha512-pUSWAi/RAnVy1Pif2kAoeWNBa3JVrx0MId2LASj8G+7AiHWoKZNTomq6LG326T68U7/e263X6fTdcXIy7XnF7Q==",
+      "license": "MIT",
       "dependencies": {
         "@types/unist": "^2.0.0",
         "bail": "^2.0.0",
@@ -8575,6 +8588,7 @@
       "version": "3.0.3",
       "resolved": "https://registry.npmjs.org/unist-util-stringify-position/-/unist-util-stringify-position-3.0.3.tgz",
       "integrity": "sha512-k5GzIBZ/QatR8N5X2y+drfpWG8IDBzdnVj6OInRNWm1oXrzydiaAT2OQiA8DPRRZyAKb9b6I2a6PxYklZD0gKg==",
+      "license": "MIT",
       "dependencies": {
         "@types/unist": "^2.0.0"
       },
@@ -8587,6 +8601,7 @@
       "version": "5.3.7",
       "resolved": "https://registry.npmjs.org/vfile/-/vfile-5.3.7.tgz",
       "integrity": "sha512-r7qlzkgErKjobAmyNIkkSpizsFPYiUPuJb5pNW1RB4JcYVZhs4lIbVqk8XPk033CV/1z8ss5pkax8SuhGpcG8g==",
+      "license": "MIT",
       "dependencies": {
         "@types/unist": "^2.0.0",
         "is-buffer": "^2.0.0",
@@ -8602,6 +8617,7 @@
       "version": "3.1.4",
       "resolved": "https://registry.npmjs.org/vfile-message/-/vfile-message-3.1.4.tgz",
       "integrity": "sha512-fa0Z6P8HUrQN4BZaX05SIVXic+7kE3b05PWAtPuYP9QLHsLKYR7/AlLW3NtOrpXRLeawpDLMsVkmk5DG0NXgWw==",
+      "license": "MIT",
       "dependencies": {
         "@types/unist": "^2.0.0",
         "unist-util-stringify-position": "^3.0.0"
@@ -8615,6 +8631,7 @@
       "version": "5.2.0",
       "resolved": "https://registry.npmjs.org/retext-smartypants/-/retext-smartypants-5.2.0.tgz",
       "integrity": "sha512-Do8oM+SsjrbzT2UNIKgheP0hgUQTDDQYyZaIY3kfq0pdFzoPk+ZClYJ+OERNXveog4xf1pZL4PfRxNoVL7a/jw==",
+      "license": "MIT",
       "dependencies": {
         "@types/nlcst": "^1.0.0",
         "nlcst-to-string": "^3.0.0",
@@ -8627,14 +8644,16 @@
       }
     },
     "node_modules/retext-smartypants/node_modules/@types/unist": {
-      "version": "2.0.10",
-      "resolved": "https://registry.npmjs.org/@types/unist/-/unist-2.0.10.tgz",
-      "integrity": "sha512-IfYcSBWE3hLpBg8+X2SEa8LVkJdJEkT2Ese2aaLs3ptGdVtABxndrMaxuFlQ1qdFf9Q5rDvDpxI3WwgvKFAsQA=="
+      "version": "2.0.11",
+      "resolved": "https://registry.npmjs.org/@types/unist/-/unist-2.0.11.tgz",
+      "integrity": "sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA==",
+      "license": "MIT"
     },
     "node_modules/retext-smartypants/node_modules/unified": {
       "version": "10.1.2",
       "resolved": "https://registry.npmjs.org/unified/-/unified-10.1.2.tgz",
       "integrity": "sha512-pUSWAi/RAnVy1Pif2kAoeWNBa3JVrx0MId2LASj8G+7AiHWoKZNTomq6LG326T68U7/e263X6fTdcXIy7XnF7Q==",
+      "license": "MIT",
       "dependencies": {
         "@types/unist": "^2.0.0",
         "bail": "^2.0.0",
@@ -8653,6 +8672,7 @@
       "version": "5.2.1",
       "resolved": "https://registry.npmjs.org/unist-util-is/-/unist-util-is-5.2.1.tgz",
       "integrity": "sha512-u9njyyfEh43npf1M+yGKDGVPbY/JWEemg5nH05ncKPfi+kBbKBJoTdsogMu33uhytuLlv9y0O7GH7fEdwLdLQw==",
+      "license": "MIT",
       "dependencies": {
         "@types/unist": "^2.0.0"
       },
@@ -8665,6 +8685,7 @@
       "version": "3.0.3",
       "resolved": "https://registry.npmjs.org/unist-util-stringify-position/-/unist-util-stringify-position-3.0.3.tgz",
       "integrity": "sha512-k5GzIBZ/QatR8N5X2y+drfpWG8IDBzdnVj6OInRNWm1oXrzydiaAT2OQiA8DPRRZyAKb9b6I2a6PxYklZD0gKg==",
+      "license": "MIT",
       "dependencies": {
         "@types/unist": "^2.0.0"
       },
@@ -8677,6 +8698,7 @@
       "version": "4.1.2",
       "resolved": "https://registry.npmjs.org/unist-util-visit/-/unist-util-visit-4.1.2.tgz",
       "integrity": "sha512-MSd8OUGISqHdVvfY9TPhyK2VdUrPgxkUtWSuMHF6XAAFuL4LokseigBnZtPnJMu+FbynTkFNnFlyjxpVKujMRg==",
+      "license": "MIT",
       "dependencies": {
         "@types/unist": "^2.0.0",
         "unist-util-is": "^5.0.0",
@@ -8691,6 +8713,7 @@
       "version": "5.1.3",
       "resolved": "https://registry.npmjs.org/unist-util-visit-parents/-/unist-util-visit-parents-5.1.3.tgz",
       "integrity": "sha512-x6+y8g7wWMyQhL1iZfhIPhDAs7Xwbn9nRosDXl7qoPTSCy0yNxnKc+hWokFifWQIDGi154rdUqKvbCa4+1kLhg==",
+      "license": "MIT",
       "dependencies": {
         "@types/unist": "^2.0.0",
         "unist-util-is": "^5.0.0"
@@ -8704,6 +8727,7 @@
       "version": "5.3.7",
       "resolved": "https://registry.npmjs.org/vfile/-/vfile-5.3.7.tgz",
       "integrity": "sha512-r7qlzkgErKjobAmyNIkkSpizsFPYiUPuJb5pNW1RB4JcYVZhs4lIbVqk8XPk033CV/1z8ss5pkax8SuhGpcG8g==",
+      "license": "MIT",
       "dependencies": {
         "@types/unist": "^2.0.0",
         "is-buffer": "^2.0.0",
@@ -8719,6 +8743,7 @@
       "version": "3.1.4",
       "resolved": "https://registry.npmjs.org/vfile-message/-/vfile-message-3.1.4.tgz",
       "integrity": "sha512-fa0Z6P8HUrQN4BZaX05SIVXic+7kE3b05PWAtPuYP9QLHsLKYR7/AlLW3NtOrpXRLeawpDLMsVkmk5DG0NXgWw==",
+      "license": "MIT",
       "dependencies": {
         "@types/unist": "^2.0.0",
         "unist-util-stringify-position": "^3.0.0"
@@ -8732,6 +8757,7 @@
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/retext-stringify/-/retext-stringify-3.1.0.tgz",
       "integrity": "sha512-767TLOaoXFXyOnjx/EggXlb37ZD2u4P1n0GJqVdpipqACsQP+20W+BNpMYrlJkq7hxffnFk+jc6mAK9qrbuB8w==",
+      "license": "MIT",
       "dependencies": {
         "@types/nlcst": "^1.0.0",
         "nlcst-to-string": "^3.0.0",
@@ -8743,14 +8769,16 @@
       }
     },
     "node_modules/retext-stringify/node_modules/@types/unist": {
-      "version": "2.0.10",
-      "resolved": "https://registry.npmjs.org/@types/unist/-/unist-2.0.10.tgz",
-      "integrity": "sha512-IfYcSBWE3hLpBg8+X2SEa8LVkJdJEkT2Ese2aaLs3ptGdVtABxndrMaxuFlQ1qdFf9Q5rDvDpxI3WwgvKFAsQA=="
+      "version": "2.0.11",
+      "resolved": "https://registry.npmjs.org/@types/unist/-/unist-2.0.11.tgz",
+      "integrity": "sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA==",
+      "license": "MIT"
     },
     "node_modules/retext-stringify/node_modules/unified": {
       "version": "10.1.2",
       "resolved": "https://registry.npmjs.org/unified/-/unified-10.1.2.tgz",
       "integrity": "sha512-pUSWAi/RAnVy1Pif2kAoeWNBa3JVrx0MId2LASj8G+7AiHWoKZNTomq6LG326T68U7/e263X6fTdcXIy7XnF7Q==",
+      "license": "MIT",
       "dependencies": {
         "@types/unist": "^2.0.0",
         "bail": "^2.0.0",
@@ -8769,6 +8797,7 @@
       "version": "3.0.3",
       "resolved": "https://registry.npmjs.org/unist-util-stringify-position/-/unist-util-stringify-position-3.0.3.tgz",
       "integrity": "sha512-k5GzIBZ/QatR8N5X2y+drfpWG8IDBzdnVj6OInRNWm1oXrzydiaAT2OQiA8DPRRZyAKb9b6I2a6PxYklZD0gKg==",
+      "license": "MIT",
       "dependencies": {
         "@types/unist": "^2.0.0"
       },
@@ -8781,6 +8810,7 @@
       "version": "5.3.7",
       "resolved": "https://registry.npmjs.org/vfile/-/vfile-5.3.7.tgz",
       "integrity": "sha512-r7qlzkgErKjobAmyNIkkSpizsFPYiUPuJb5pNW1RB4JcYVZhs4lIbVqk8XPk033CV/1z8ss5pkax8SuhGpcG8g==",
+      "license": "MIT",
       "dependencies": {
         "@types/unist": "^2.0.0",
         "is-buffer": "^2.0.0",
@@ -8796,6 +8826,7 @@
       "version": "3.1.4",
       "resolved": "https://registry.npmjs.org/vfile-message/-/vfile-message-3.1.4.tgz",
       "integrity": "sha512-fa0Z6P8HUrQN4BZaX05SIVXic+7kE3b05PWAtPuYP9QLHsLKYR7/AlLW3NtOrpXRLeawpDLMsVkmk5DG0NXgWw==",
+      "license": "MIT",
       "dependencies": {
         "@types/unist": "^2.0.0",
         "unist-util-stringify-position": "^3.0.0"
@@ -8806,14 +8837,16 @@
       }
     },
     "node_modules/retext/node_modules/@types/unist": {
-      "version": "2.0.10",
-      "resolved": "https://registry.npmjs.org/@types/unist/-/unist-2.0.10.tgz",
-      "integrity": "sha512-IfYcSBWE3hLpBg8+X2SEa8LVkJdJEkT2Ese2aaLs3ptGdVtABxndrMaxuFlQ1qdFf9Q5rDvDpxI3WwgvKFAsQA=="
+      "version": "2.0.11",
+      "resolved": "https://registry.npmjs.org/@types/unist/-/unist-2.0.11.tgz",
+      "integrity": "sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA==",
+      "license": "MIT"
     },
     "node_modules/retext/node_modules/unified": {
       "version": "10.1.2",
       "resolved": "https://registry.npmjs.org/unified/-/unified-10.1.2.tgz",
       "integrity": "sha512-pUSWAi/RAnVy1Pif2kAoeWNBa3JVrx0MId2LASj8G+7AiHWoKZNTomq6LG326T68U7/e263X6fTdcXIy7XnF7Q==",
+      "license": "MIT",
       "dependencies": {
         "@types/unist": "^2.0.0",
         "bail": "^2.0.0",
@@ -8832,6 +8865,7 @@
       "version": "3.0.3",
       "resolved": "https://registry.npmjs.org/unist-util-stringify-position/-/unist-util-stringify-position-3.0.3.tgz",
       "integrity": "sha512-k5GzIBZ/QatR8N5X2y+drfpWG8IDBzdnVj6OInRNWm1oXrzydiaAT2OQiA8DPRRZyAKb9b6I2a6PxYklZD0gKg==",
+      "license": "MIT",
       "dependencies": {
         "@types/unist": "^2.0.0"
       },
@@ -8844,6 +8878,7 @@
       "version": "5.3.7",
       "resolved": "https://registry.npmjs.org/vfile/-/vfile-5.3.7.tgz",
       "integrity": "sha512-r7qlzkgErKjobAmyNIkkSpizsFPYiUPuJb5pNW1RB4JcYVZhs4lIbVqk8XPk033CV/1z8ss5pkax8SuhGpcG8g==",
+      "license": "MIT",
       "dependencies": {
         "@types/unist": "^2.0.0",
         "is-buffer": "^2.0.0",
@@ -8859,6 +8894,7 @@
       "version": "3.1.4",
       "resolved": "https://registry.npmjs.org/vfile-message/-/vfile-message-3.1.4.tgz",
       "integrity": "sha512-fa0Z6P8HUrQN4BZaX05SIVXic+7kE3b05PWAtPuYP9QLHsLKYR7/AlLW3NtOrpXRLeawpDLMsVkmk5DG0NXgWw==",
+      "license": "MIT",
       "dependencies": {
         "@types/unist": "^2.0.0",
         "unist-util-stringify-position": "^3.0.0"
@@ -9471,6 +9507,7 @@
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/unherit/-/unherit-3.0.1.tgz",
       "integrity": "sha512-akOOQ/Yln8a2sgcLj4U0Jmx0R5jpIg2IUyRrWOzmEbjBtGzBdHtSeFKgoEcoH4KYIG/Pb8GQ/BwtYm0GCq1Sqg==",
+      "license": "MIT",
       "funding": {
         "type": "github",
         "url": "https://github.com/sponsors/wooorm"
@@ -9535,6 +9572,7 @@
       "version": "3.1.1",
       "resolved": "https://registry.npmjs.org/unist-util-modify-children/-/unist-util-modify-children-3.1.1.tgz",
       "integrity": "sha512-yXi4Lm+TG5VG+qvokP6tpnk+r1EPwyYL04JWDxLvgvPV40jANh7nm3udk65OOWquvbMDe+PL9+LmkxDpTv/7BA==",
+      "license": "MIT",
       "dependencies": {
         "@types/unist": "^2.0.0",
         "array-iterate": "^2.0.0"
@@ -9545,9 +9583,10 @@
       }
     },
     "node_modules/unist-util-modify-children/node_modules/@types/unist": {
-      "version": "2.0.10",
-      "resolved": "https://registry.npmjs.org/@types/unist/-/unist-2.0.10.tgz",
-      "integrity": "sha512-IfYcSBWE3hLpBg8+X2SEa8LVkJdJEkT2Ese2aaLs3ptGdVtABxndrMaxuFlQ1qdFf9Q5rDvDpxI3WwgvKFAsQA=="
+      "version": "2.0.11",
+      "resolved": "https://registry.npmjs.org/@types/unist/-/unist-2.0.11.tgz",
+      "integrity": "sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA==",
+      "license": "MIT"
     },
     "node_modules/unist-util-position": {
       "version": "5.0.0",
@@ -9573,20 +9612,6 @@
         "url": "https://opencollective.com/unified"
       }
     },
-    "node_modules/unist-util-remove": {
-      "version": "4.0.0",
-      "resolved": "https://registry.npmjs.org/unist-util-remove/-/unist-util-remove-4.0.0.tgz",
-      "integrity": "sha512-b4gokeGId57UVRX/eVKej5gXqGlc9+trkORhFJpu9raqZkZhU0zm8Doi05+HaiBsMEIJowL+2WtQ5ItjsngPXg==",
-      "dependencies": {
-        "@types/unist": "^3.0.0",
-        "unist-util-is": "^6.0.0",
-        "unist-util-visit-parents": "^6.0.0"
-      },
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/unified"
-      }
-    },
     "node_modules/unist-util-remove-position": {
       "version": "5.0.0",
       "resolved": "https://registry.npmjs.org/unist-util-remove-position/-/unist-util-remove-position-5.0.0.tgz",
@@ -9630,6 +9655,7 @@
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/unist-util-visit-children/-/unist-util-visit-children-2.0.2.tgz",
       "integrity": "sha512-+LWpMFqyUwLGpsQxpumsQ9o9DG2VGLFrpz+rpVXYIEdPy57GSy5HioC0g3bg/8WP9oCLlapQtklOzQ8uLS496Q==",
+      "license": "MIT",
       "dependencies": {
         "@types/unist": "^2.0.0"
       },
@@ -9639,9 +9665,10 @@
       }
     },
     "node_modules/unist-util-visit-children/node_modules/@types/unist": {
-      "version": "2.0.10",
-      "resolved": "https://registry.npmjs.org/@types/unist/-/unist-2.0.10.tgz",
-      "integrity": "sha512-IfYcSBWE3hLpBg8+X2SEa8LVkJdJEkT2Ese2aaLs3ptGdVtABxndrMaxuFlQ1qdFf9Q5rDvDpxI3WwgvKFAsQA=="
+      "version": "2.0.11",
+      "resolved": "https://registry.npmjs.org/@types/unist/-/unist-2.0.11.tgz",
+      "integrity": "sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA==",
+      "license": "MIT"
     },
     "node_modules/unist-util-visit-parents": {
       "version": "6.0.1",
@@ -9759,9 +9786,10 @@
       }
     },
     "node_modules/vite": {
-      "version": "5.4.11",
-      "resolved": "https://registry.npmjs.org/vite/-/vite-5.4.11.tgz",
-      "integrity": "sha512-c7jFQRklXua0mTzneGW9QVyxFjUgwcihC4bXEtujIo2ouWCe1Ajt/amn2PCxYnhYfd5k09JX3SB7OYWFKYqj8Q==",
+      "version": "5.4.14",
+      "resolved": "https://registry.npmjs.org/vite/-/vite-5.4.14.tgz",
+      "integrity": "sha512-EK5cY7Q1D8JNhSaPKVK4pwBFvaTmZxEnoKXLG/U9gmdDcihQGNzFlgIvaxezFR4glP1LsuiedwMBqCXH3wZccA==",
+      "license": "MIT",
       "dependencies": {
         "esbuild": "^0.21.3",
         "postcss": "^8.4.43",
diff --git a/site/src/content/docs/best-practices/upgrading-zarf.mdx b/site/src/content/docs/best-practices/upgrading-zarf.mdx
new file mode 100644
index 0000000000..6d00f61d9c
--- /dev/null
+++ b/site/src/content/docs/best-practices/upgrading-zarf.mdx
@@ -0,0 +1,62 @@
+---
+title: "Upgrading Zarf"
+---
+
+Optimally the version of Zarf performing the `package create` and `package deploy` operations aligns to the version of [Init Package](/ref/init-package) that is installed within the cluster.
+
+Follow [CLI Installation](/getting-started/install) steps for installing updates to the version of binary installed on the machine executing zarf commands.
+
+# Upgrading the Init Package
+
+Upgrading the init package is a bit different from upgrading a regular application package because it establishes your cluster's foundational infrastructure. Follow these steps to upgrade your init package:
+
+## 1. Obtain the Updated Init Package
+
+- **Default Package:** If you're using the default package, run the following command to fetch the latest init package (if it's not already present locally):
+
+  ```bash
+  zarf tools download-init
+  ```
+
+  - **Validate:** This will download the associated init package to your current working directory unless `--output-directory` is specified.
+
+- **Manual:** The Init Package can also be manually downloaded from the Github releases to a storage location of your choice.
+
+  ```bash
+  VERSION="<target version>"; ARCH="<target architecture>"; curl -LO https://github.com/zarf-dev/zarf/releases/download/${VERSION}/zarf-init-${ARCH}-${VERSION}.tar.zst
+  ```
+
+## 2. Re-initialize the cluster
+
+- **Init:** The init process can be executed to upgrade a cluster from one version to another.
+
+  ```bash
+  zarf init --confirm
+  ```
+
+- **Deploy:** Init Packages can also be deployed directly with `package deploy` - allowing for explicit deployment specification and the use of [custom init packages](/tutorials/7-custom-init-packages).
+
+  ```bash
+  zarf package deploy <zarf-init-package tarball> --confirm
+  ```
+
+  **Note:** The use of package deploy for zarf init operations will not expose any configuration for external git/registry options.
+
+## 3. Validate Zarf Infrastructure
+
+- **Validate:** Ensure the following zarf resources are healthy:
+  - Registry (if deployed)
+  - Agent pods
+  - Git server (if deployed)
+
+  ```bash
+  zarf tools kubectl get pods -n zarf
+  ```
+
+# Special Considerations
+
+After the original `zarf init` has taken place - any following initialize actions will use the values in the `zarf-state` secret in the `zarf` namespace to obtain information for Zarf infrastructure such as the registry. For example, the `--registry-pull-password` flag is ignored on subsequent runs.
+
+See the [init command](/commands/zarf_init/#options) for reference.
+
+In order to update any configuration passed into the `zarf init` command, you will need to run [zarf tools update-creds](/commands/zarf_tools_update-creds/#options) with the information necessary.


Reviews:
user: login: AustinAbro321
body: Few small comments, adding this will be a plus.
state: CHANGES_REQUESTED
author_association: MEMBER
submitted_at: 2025-03-04T13:24:27Z
user: login: brandtkeller
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-04T21:52:29Z
user: login: brandtkeller
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-04T21:53:20Z
user: login: AustinAbro321
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-05T13:17:31Z
user: login: AustinAbro321
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-05T13:51:51Z
user: login: brandtkeller
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-05T15:27:24Z
user: login: AustinAbro321
body: LGTM
state: APPROVED
author_association: MEMBER
submitted_at: 2025-03-05T16:26:42Z

Review comments:
diff_hunk: @@ -0,0 +1,61 @@
+---
+title: "Upgrading Zarf"
+---
+
+Optimally the version of Zarf performing the `package create` and `package deploy` operations aligns to the version of [Init Package]() that is installed within the cluster.
path: site/src/content/docs/best-practices/upgrading-zarf.mdx
user: login: AustinAbro321
body: Missing the [Init Package] link here
created_at: 2025-03-04T13:17:29Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,61 @@
+---
+title: "Upgrading Zarf"
+---
+
+Optimally the version of Zarf performing the `package create` and `package deploy` operations aligns to the version of [Init Package]() that is installed within the cluster.
+
+Follow [CLI Installation](../../getting-started/install) steps for installing updates to the version of binary installed on the machine executing zarf commands.
+
+# Upgrading the Init Package
+
+Upgrading the init package is a bit different from upgrading a regular application package because it establishes your cluster's foundational infrastructure. Follow these steps to upgrade your init package:
+
+## 1. Obtain the Updated Init Package
+
+- **Default Package:** If you're using the default package, run the following command to fetch the latest init package (if it's not already present locally):
+
+  ```bash
+  zarf tools download-init
+  ```
+
+  - **Validate:** This will download the associated init package to your current working directory unless `--output-directory` is specified.
+
+- **Manual:** The Init Package can also be manually downloaded from the Github releases to a storage location of your choice.
+
+  ```bash
+  VERSION="<target version>"; ARCH="<target architecture>"; curl -LO https://github.com/zarf-dev/zarf/releases/download/${VERSION}/zarf-init-${ARCH}-${VERSION}.tar.zst
+  ```
+
+## 2. Re-initialize the cluster
+
+- **Init:** The init process can be executed to upgrade a cluster from one version to another.
+
+  ```bash
+  zarf init --confirm
+  ```
+
+- **Deploy:** The Init Package can also be deployed directly with `package deploy` - allowing for explicit deployment specification.
path: site/src/content/docs/best-practices/upgrading-zarf.mdx
user: login: AustinAbro321
body: I think it's worth mentioning here that custom init packages can be deployed this way
created_at: 2025-03-04T13:20:53Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,61 @@
+---
+title: "Upgrading Zarf"
+---
+
+Optimally the version of Zarf performing the `package create` and `package deploy` operations aligns to the version of [Init Package]() that is installed within the cluster.
+
+Follow [CLI Installation](../../getting-started/install) steps for installing updates to the version of binary installed on the machine executing zarf commands.
+
+# Upgrading the Init Package
+
+Upgrading the init package is a bit different from upgrading a regular application package because it establishes your cluster's foundational infrastructure. Follow these steps to upgrade your init package:
+
+## 1. Obtain the Updated Init Package
+
+- **Default Package:** If you're using the default package, run the following command to fetch the latest init package (if it's not already present locally):
+
+  ```bash
+  zarf tools download-init
+  ```
+
+  - **Validate:** This will download the associated init package to your current working directory unless `--output-directory` is specified.
+
+- **Manual:** The Init Package can also be manually downloaded from the Github releases to a storage location of your choice.
+
+  ```bash
+  VERSION="<target version>"; ARCH="<target architecture>"; curl -LO https://github.com/zarf-dev/zarf/releases/download/${VERSION}/zarf-init-${ARCH}-${VERSION}.tar.zst
+  ```
+
+## 2. Re-initialize the cluster
+
+- **Init:** The init process can be executed to upgrade a cluster from one version to another.
+
+  ```bash
+  zarf init --confirm
+  ```
+
+- **Deploy:** The Init Package can also be deployed directly with `package deploy` - allowing for explicit deployment specification.
+
+  ```bash
+  zarf package deploy <zarf-init-package tarball> --confirm
+  ```
+
+  **Note:** The use of package deploy for zarf init operations will not expose any configuration for external git/registry options.
+
+## 3. Validate Zarf Infrastructure
+
+- **Validate:** Ensure the following zarf resources are healthy:
+  - Registry if deployed
+  - Agent pods
path: site/src/content/docs/best-practices/upgrading-zarf.mdx
user: login: AustinAbro321
body: ```suggestion
- **Validate:** Ensure the following zarf resources are healthy:
  - Registry
  - Agent pods
  - Git server if deployed
```
In the default init package the Git Server is an optional component, but the rest of the services are required. 
created_at: 2025-03-04T13:23:45Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,61 @@
+---
+title: "Upgrading Zarf"
+---
+
+Optimally the version of Zarf performing the `package create` and `package deploy` operations aligns to the version of [Init Package]() that is installed within the cluster.
+
+Follow [CLI Installation](../../getting-started/install) steps for installing updates to the version of binary installed on the machine executing zarf commands.
+
+# Upgrading the Init Package
+
+Upgrading the init package is a bit different from upgrading a regular application package because it establishes your cluster's foundational infrastructure. Follow these steps to upgrade your init package:
+
+## 1. Obtain the Updated Init Package
+
+- **Default Package:** If you're using the default package, run the following command to fetch the latest init package (if it's not already present locally):
+
+  ```bash
+  zarf tools download-init
+  ```
+
+  - **Validate:** This will download the associated init package to your current working directory unless `--output-directory` is specified.
+
+- **Manual:** The Init Package can also be manually downloaded from the Github releases to a storage location of your choice.
+
+  ```bash
+  VERSION="<target version>"; ARCH="<target architecture>"; curl -LO https://github.com/zarf-dev/zarf/releases/download/${VERSION}/zarf-init-${ARCH}-${VERSION}.tar.zst
+  ```
+
+## 2. Re-initialize the cluster
+
+- **Init:** The init process can be executed to upgrade a cluster from one version to another.
+
+  ```bash
+  zarf init --confirm
+  ```
+
+- **Deploy:** The Init Package can also be deployed directly with `package deploy` - allowing for explicit deployment specification.
path: site/src/content/docs/best-practices/upgrading-zarf.mdx
user: login: brandtkeller
body: agreed!
created_at: 2025-03-04T21:52:28Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,61 @@
+---
+title: "Upgrading Zarf"
+---
+
+Optimally the version of Zarf performing the `package create` and `package deploy` operations aligns to the version of [Init Package]() that is installed within the cluster.
+
+Follow [CLI Installation](../../getting-started/install) steps for installing updates to the version of binary installed on the machine executing zarf commands.
+
+# Upgrading the Init Package
+
+Upgrading the init package is a bit different from upgrading a regular application package because it establishes your cluster's foundational infrastructure. Follow these steps to upgrade your init package:
+
+## 1. Obtain the Updated Init Package
+
+- **Default Package:** If you're using the default package, run the following command to fetch the latest init package (if it's not already present locally):
+
+  ```bash
+  zarf tools download-init
+  ```
+
+  - **Validate:** This will download the associated init package to your current working directory unless `--output-directory` is specified.
+
+- **Manual:** The Init Package can also be manually downloaded from the Github releases to a storage location of your choice.
+
+  ```bash
+  VERSION="<target version>"; ARCH="<target architecture>"; curl -LO https://github.com/zarf-dev/zarf/releases/download/${VERSION}/zarf-init-${ARCH}-${VERSION}.tar.zst
+  ```
+
+## 2. Re-initialize the cluster
+
+- **Init:** The init process can be executed to upgrade a cluster from one version to another.
+
+  ```bash
+  zarf init --confirm
+  ```
+
+- **Deploy:** The Init Package can also be deployed directly with `package deploy` - allowing for explicit deployment specification.
+
+  ```bash
+  zarf package deploy <zarf-init-package tarball> --confirm
+  ```
+
+  **Note:** The use of package deploy for zarf init operations will not expose any configuration for external git/registry options.
+
+## 3. Validate Zarf Infrastructure
+
+- **Validate:** Ensure the following zarf resources are healthy:
+  - Registry if deployed
+  - Agent pods
path: site/src/content/docs/best-practices/upgrading-zarf.mdx
user: login: brandtkeller
body: The registry wouldn't be deployed is an external registry is used correct?
created_at: 2025-03-04T21:53:20Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,61 @@
+---
+title: "Upgrading Zarf"
+---
+
+Optimally the version of Zarf performing the `package create` and `package deploy` operations aligns to the version of [Init Package]() that is installed within the cluster.
+
+Follow [CLI Installation](../../getting-started/install) steps for installing updates to the version of binary installed on the machine executing zarf commands.
+
+# Upgrading the Init Package
+
+Upgrading the init package is a bit different from upgrading a regular application package because it establishes your cluster's foundational infrastructure. Follow these steps to upgrade your init package:
+
+## 1. Obtain the Updated Init Package
+
+- **Default Package:** If you're using the default package, run the following command to fetch the latest init package (if it's not already present locally):
+
+  ```bash
+  zarf tools download-init
+  ```
+
+  - **Validate:** This will download the associated init package to your current working directory unless `--output-directory` is specified.
+
+- **Manual:** The Init Package can also be manually downloaded from the Github releases to a storage location of your choice.
+
+  ```bash
+  VERSION="<target version>"; ARCH="<target architecture>"; curl -LO https://github.com/zarf-dev/zarf/releases/download/${VERSION}/zarf-init-${ARCH}-${VERSION}.tar.zst
+  ```
+
+## 2. Re-initialize the cluster
+
+- **Init:** The init process can be executed to upgrade a cluster from one version to another.
+
+  ```bash
+  zarf init --confirm
+  ```
+
+- **Deploy:** The Init Package can also be deployed directly with `package deploy` - allowing for explicit deployment specification.
+
+  ```bash
+  zarf package deploy <zarf-init-package tarball> --confirm
+  ```
+
+  **Note:** The use of package deploy for zarf init operations will not expose any configuration for external git/registry options.
+
+## 3. Validate Zarf Infrastructure
+
+- **Validate:** Ensure the following zarf resources are healthy:
+  - Registry if deployed
+  - Agent pods
path: site/src/content/docs/best-practices/upgrading-zarf.mdx
user: login: AustinAbro321
body: Ah yeah totally forgot about that
created_at: 2025-03-05T13:17:31Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,62 @@
+---
+title: "Upgrading Zarf"
+---
+
+Optimally the version of Zarf performing the `package create` and `package deploy` operations aligns to the version of [Init Package](/ref/init-package) that is installed within the cluster.
+
+Follow [CLI Installation](/getting-started/install) steps for installing updates to the version of binary installed on the machine executing zarf commands.
+
+# Upgrading the Init Package
+
+Upgrading the init package is a bit different from upgrading a regular application package because it establishes your cluster's foundational infrastructure. Follow these steps to upgrade your init package:
+
+## 1. Obtain the Updated Init Package
+
+- **Default Package:** If you're using the default package, run the following command to fetch the latest init package (if it's not already present locally):
+
+  ```bash
+  zarf tools download-init
+  ```
+
+  - **Validate:** This will download the associated init package to your current working directory unless `--output-directory` is specified.
+
+- **Manual:** The Init Package can also be manually downloaded from the Github releases to a storage location of your choice.
+
+  ```bash
+  VERSION="<target version>"; ARCH="<target architecture>"; curl -LO https://github.com/zarf-dev/zarf/releases/download/${VERSION}/zarf-init-${ARCH}-${VERSION}.tar.zst
+  ```
+
+## 2. Re-initialize the cluster
+
+- **Init:** The init process can be executed to upgrade a cluster from one version to another.
+
+  ```bash
+  zarf init --confirm
+  ```
+
+- **Deploy:** Init Packages can also be deployed directly with `package deploy` - allowing for explicit deployment specification and the use of [custom init packages](/tutorials/7-custom-init-packages).
+
+  ```bash
+  zarf package deploy <zarf-init-package tarball> --confirm
+  ```
+
+  **Note:** The use of package deploy for zarf init operations will not expose any configuration for external git/registry options.
+
+## 3. Validate Zarf Infrastructure
+
+- **Validate:** Ensure the following zarf resources are healthy:
+  - Registry (if deployed)
+  - Agent pods
+  - Git server (if deployed)
+
+  ```bash
+  zarf tools kubectl get pods -n zarf
+  ```
+
+# Special Considerations
+
+After the original `zarf init` has taken place - any following initialize actions will use the same `secret` for obtaining information provided by any `zarf init` flags.
path: site/src/content/docs/best-practices/upgrading-zarf.mdx
user: login: AustinAbro321
body: ```suggestion
After the original `zarf init` has taken place - any following initialize actions will use the values in the `zarf-state` secret in the `zarf` namespace to obtain information for Zarf infrastructure such as the registry. For example, the `--registry-pull-password` flag is ignored on subsequent runs.
```
Thoughts on adding some more detail here? I think specifying that this is for flags related infrastructure and not flags like `--components` would make this more clear.
created_at: 2025-03-05T13:51:51Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,62 @@
+---
+title: "Upgrading Zarf"
+---
+
+Optimally the version of Zarf performing the `package create` and `package deploy` operations aligns to the version of [Init Package](/ref/init-package) that is installed within the cluster.
+
+Follow [CLI Installation](/getting-started/install) steps for installing updates to the version of binary installed on the machine executing zarf commands.
+
+# Upgrading the Init Package
+
+Upgrading the init package is a bit different from upgrading a regular application package because it establishes your cluster's foundational infrastructure. Follow these steps to upgrade your init package:
+
+## 1. Obtain the Updated Init Package
+
+- **Default Package:** If you're using the default package, run the following command to fetch the latest init package (if it's not already present locally):
+
+  ```bash
+  zarf tools download-init
+  ```
+
+  - **Validate:** This will download the associated init package to your current working directory unless `--output-directory` is specified.
+
+- **Manual:** The Init Package can also be manually downloaded from the Github releases to a storage location of your choice.
+
+  ```bash
+  VERSION="<target version>"; ARCH="<target architecture>"; curl -LO https://github.com/zarf-dev/zarf/releases/download/${VERSION}/zarf-init-${ARCH}-${VERSION}.tar.zst
+  ```
+
+## 2. Re-initialize the cluster
+
+- **Init:** The init process can be executed to upgrade a cluster from one version to another.
+
+  ```bash
+  zarf init --confirm
+  ```
+
+- **Deploy:** Init Packages can also be deployed directly with `package deploy` - allowing for explicit deployment specification and the use of [custom init packages](/tutorials/7-custom-init-packages).
+
+  ```bash
+  zarf package deploy <zarf-init-package tarball> --confirm
+  ```
+
+  **Note:** The use of package deploy for zarf init operations will not expose any configuration for external git/registry options.
+
+## 3. Validate Zarf Infrastructure
+
+- **Validate:** Ensure the following zarf resources are healthy:
+  - Registry (if deployed)
+  - Agent pods
+  - Git server (if deployed)
+
+  ```bash
+  zarf tools kubectl get pods -n zarf
+  ```
+
+# Special Considerations
+
+After the original `zarf init` has taken place - any following initialize actions will use the same `secret` for obtaining information provided by any `zarf init` flags.
path: site/src/content/docs/best-practices/upgrading-zarf.mdx
user: login: brandtkeller
body: I like it. Iterating on adding more detail to new and existing docs is a win.
created_at: 2025-03-05T15:27:23Z
author_association: MEMBER

PR comments:
user: login: netlify[bot]
created_at: 2025-03-03T21:36:22Z
body: ### <span aria-hidden="true">✅</span> Deploy Preview for *zarf-docs* ready!


|  Name | Link |
|:-:|------------------------|
|<span aria-hidden="true">🔨</span> Latest commit | ceeab3c0a870fd89416908a25ac358c907d808fa |
|<span aria-hidden="true">🔍</span> Latest deploy log | https://app.netlify.com/sites/zarf-docs/deploys/67c86d629a06040008904227 |
|<span aria-hidden="true">😎</span> Deploy Preview | [https://deploy-preview-3551--zarf-docs.netlify.app](https://deploy-preview-3551--zarf-docs.netlify.app) |
|<span aria-hidden="true">📱</span> Preview on mobile | <details><summary> Toggle QR Code... </summary><br /><br />![QR Code](https://app.netlify.com/qr-code/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1cmwiOiJodHRwczovL2RlcGxveS1wcmV2aWV3LTM1NTEtLXphcmYtZG9jcy5uZXRsaWZ5LmFwcCJ9.vXs6t2ePhxxg58Yvz88CfCJT2VE1QgYO4zFVJCjFtDI)<br /><br />_Use your smartphone camera to open QR code link._</details> |
---
<!-- [zarf-docs Preview](https://deploy-preview-3551--zarf-docs.netlify.app) -->
_To edit notification comments on pull requests, go to your [Netlify site configuration](https://app.netlify.com/sites/zarf-docs/configuration/notifications#deploy-webhooks)._
author_association: NONE
user: login: codecov[bot]
created_at: 2025-03-03T21:38:15Z
body: ## [Codecov](https://app.codecov.io/gh/zarf-dev/zarf/pull/3551?dropdown=coverage&src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=zarf-dev) Report
All modified and coverable lines are covered by tests :white_check_mark:

<details><summary>🚀 New features to boost your workflow: </summary>

- ❄ [Test Analytics](https://docs.codecov.com/docs/test-analytics): Detect flaky tests, report on failures, and find test suite problems.
- 📦 [JS Bundle Analysis](https://docs.codecov.com/docs/javascript-bundle-analysis): Save yourself from yourself by tracking and limiting bundle sizes in JS merges.
</details>
author_association: NONE