refactor: Re-organize docs layout for better usability/discoverability (

#40)

docs/guides/blue-green.md

@@ -0,0 +1,5 @@
+# Blue/Green Upgrade
+
+## Cluster
+
+## Nodegroup

docs/guides/in-place.md

@@ -0,0 +1 @@
+# In-Place Upgrade

docs/guides/process.md

@@ -0,0 +1,12 @@
+# Process
+
+This guide is intended to highlight the process for planning and preparing for routine cluster upgrades. It includes the timing of various activities, testing and validation strategies, as well as helpful tips on reducing the amount of time and effort required to perform upgrades.
+
+## Planning
+
+It is important to plan for upgrades in advance to allow for ample time to test, validate, and perform the upgrades. The target for users is to aim to be on at least the 2nd latest version of Kubernetes provided by Amazon EKS. If the current latest version supported by Amazon EKS is 1.25, users should either be on 1.24 or in the process of upgrading to 1.24. There is no harm in trying to stay on the latest version supported by Amazon EKS, but you may run into issues with 3rd party/OSS software that you run on top of Kubernetes depending on how quickly the 3rd party/OSS software is updated to support the latest version.
+
+## Testing & Validation
+
+## Helpful Tips
+

docs/index.md

@@ -10,14 +10,22 @@ Kubernetes releases a new version [approximately every 4 months](https://kuberne
 - Various changes and deprecations in the components used by Kubernetes (i.e - moving from `kube-dns` to `CoreDNS`, moving from Docker engine to `containerd` for container runtime, dropping support for `dockershim`, etc.)
 - Changes in your applications, your architecture, or the amount of traffic your clusters are handling. Over time, the number of available IPs for the cluster resources may shrink, stateful workloads may have been added to the cluster, etc., and these factors can influence the upgrade process.
 
-### What Is `eksup`
+## What Is `eksup`
 
 `eksup` is a CLI that helps users prepare for a cluster upgrade - providing users as much relevant information as possible for their upgrade.
 
-`eksup` gives users the ability to analyze their cluster(s) against the next version of Kubernetes, highlighting any findings that may affect the upgrade process. In addition, `eksup` has the ability to generate a playbook tailored to the cluster analyzed that provides the process for upgrading the cluster including the findings that require remediation. The playbook output allows users to edit the upgrade steps to suit their cluster configuration and business requirements plus capture any specific learnings during the upgrade process. Since most users typically perform upgrades on nonproduction clusters first, any additional steps or call-outs that are discovered during the upgrade process can be captured and used to improve the upgrade process for their production clusters. Users are encouraged to save their playbooks as historical artifacts for future reference to ensure that with each cycle, the team has a better understanding of the upgrade process and more confidence in swiftly working through cluster upgrades before their Kubernetes version support expires.
+`eksup` gives users the ability to analyze their cluster(s) against the next version of Kubernetes, highlighting any findings that may affect the upgrade process. In addition, `eksup` has the ability to generate a [playbook tailored to the cluster analyzed](https://github.com/clowdhaus/eksup/blob/main/examples/test-mixed_v1.24_upgrade.md) that details the process for upgrading the cluster, including the findings that require remediation. The playbook output allows users to edit the upgrade steps to suit their cluster configuration and business requirements plus capture any specific learnings during the upgrade process. Since most users typically perform upgrades on nonproduction clusters first, any additional steps or call-outs that are discovered during the upgrade process can be captured and used to improve the upgrade process for their production clusters. Users are encouraged to save their playbooks as historical artifacts for future reference to ensure that with each cycle, the team has a better understanding of the upgrade process and more confidence in swiftly working through cluster upgrades before their Kubernetes version support expires.
 
-### What It Is NOT
+## What It Is NOT
 
 - `eksup` is not a tool that will perform the cluster upgrade. It is assumed that clusters are generally created using an infrastructure as code approach through tools such as Terraform, `eksctl`, or CloudFormation. Therefore, users are encouraged to use those tools to perform the upgrade to avoid any resource definition conflicts.
 - It does not perform any modifications on the resources it identifies as needing, or recommending, changes. Again, following the approach of infrastructure as code, users are encouraged to make these changes through their normal change control process at the appropriate time in the upgrade process.
   - In the future, `eksup` may provide functionality to help in converting a Kubernetes manifest definition from one API version to the next. However, this will occur on the users local filesystem and not against a live cluster. `eksup` will always operate from the perspective of infrastructure as code; any feature requests that support this tenant are encouraged.
+
+## Symbol Table
+
+| Symbol | Description |
+| :----: | :---------- |
+| ℹ️     | Informational - users are encouraged to familiarize themselves with the information but no action is required to upgrade  |
+| ⚠️     | Recommended - users are encouraged to evaluate the recommendation and determine if it is applicable and whether or not to act upon that recommendation. Not remediating the finding does not prevent the upgrade from occurring. |
+| ❌     | Required - users must remediate the finding prior to upgrading to be able to perform the upgrade and avoid downtime or disruption |

docs/process/checks.md → docs/info/checks.md

@@ -5,7 +5,7 @@ If a check fails, it is reported as a finding. Each check will have a remediatio
 - ⚠️ Recommended: A finding that users are encouraged to evaluate the recommendation and determine if it is applicable and whether or not to act upon that recommendation. Not remediating the finding does not prevent the upgrade from occurring.
 - ❌ Required: A finding that requires remediation prior to upgrading to be able to perform the upgrade and avoid downtime or disruption
 
-See the [symbol table](https://clowdhaus.github.io/eksup/process/#symbol-table) for further details on the symbols used throughout the documentation.
+See the [symbol table](https://clowdhaus.github.io/eksup/#symbol-table) for further details on the symbols used throughout the documentation.
 
 ## Amazon
 

docs/info/design.md

@@ -0,0 +1,26 @@
+# Design
+
+## Goals
+
+There is one primary goal for `eksup`:
+
+!!! success "Empower users to routinely upgrade their EKS cluster(s) while avoiding downtime and/or disruption."
+
+To aid in that goal, the following are supporting goals or tenants:
+
+1. Intended for use on Amazon EKS clusters; there are no guarantees that this CLI will or will not work on other Kubernetes clusters at this time. The CLI will focus on EKS to avoid the need to support multiple Kubernetes distributions and their associated cloud controller resources and instead focus on the aspects that are specific to EKS and how it manages the Kubernetes experience for users. The CLI should offer native support for:
+      - Amazon EKS, Amazon EKS on Outposts (local and extended clusters), and [Not yet supported] EKS-A (EKS Anywhere)
+      - Amazon EKS managed node groups, self-managed node groups, and Amazon EKS Fargate profiles
+      - EKS addons
+2. It is designed to produce the least amount of load on the API Server when discovering and analyzing cluster resources. However, this can have some tradeoffs in terms of accuracy and completeness of the information provided to the user
+3. It should provide as much relevant information as possible to the user regarding the state of the cluster prior to upgrading. This includes scoping the information provided to the user to only that which is relevant for upgrading from their current Kubernetes version to the intended target Kubernetes version.
+4. It should support the following use cases:
+      - A one-off analysis to create a report of the cluster state prior to upgrading along with steps to take to upgrade the cluster (i.e. - analyze the cluster and generate an upgrade playbook).
+      - A one-off analysis to report on the state of the cluster for potential issues and/or recommendations prior to upgrading. This is generally a CLI invocation that prints the analysis to the console (stdout) and exits.
+      - Continuous analysis of the cluster state for potential issues and/or recommendations that runs from within the cluster that is being reported on. Results can be sent to stdout where they can be picked up from a log aggregator or sent to a remote location, such as Amazon S3, where they can be analyzed and acted upon. This process supports n-number of clusters across m-number of accounts to better aid in multi-cluster management as well as alerting to ensure enough advance notice is given for users to prepare and schedule the pending upgrade before end of support is reached.
+
+## Architecture
+
+### High Level Diagram
+
+![High level diagram](https://raw.githubusercontent.com/clowdhaus/eksup/main/docs/imgs/checks.png)

docs/process/commands.md → docs/info/usage.md

@@ -1,7 +1,4 @@
-
-## Commands
-
-``` linenums="1"
+```
 A CLI to aid in upgrading Amazon EKS clusters
 
 Usage: eksup <COMMAND>
@@ -20,7 +17,7 @@ Options:
 
 Analyze cluster for any potential issues to remediate prior to upgrade.
 
-``` linenums="1"
+```
 Analyze an Amazon EKS cluster for potential upgrade issues
 
 Usage: eksup analyze [OPTIONS] --cluster <CLUSTER>
@@ -42,9 +39,6 @@ Options:
   -o, --output <OUTPUT>
           Write to file instead of stdout
 
-      --ignore-recommended
-          Exclude recommendations from the output
-
   -h, --help
           Print help (see a summary with '-h')
 
@@ -81,13 +75,15 @@ eksup analyze --cluster <cluster> --region <region> \
 
 Create a playbook with analysis findings to guide users through pre-upgrade, upgrade, and post-upgrade process.
 
+!!! info "See [`examples/test-mixed_v1.24_upgrade.md`](https://github.com/clowdhaus/eksup/blob/main/examples/test-mixed_v1.24_upgrade.md) for an example of a playbook created with `eksup`."
+
 This CLI produces a cluster upgrade playbook that attempts to:
 
 - Educate users on the overall process of upgrading an Amazon EKS cluster (order of operations, which parts AWS manages and which parts are the user's responsibility, etc.)
 - Provide one approach as the basis for upgrading a cluster that users can modify/customize to suit their cluster configuration/architecture and business requirements
 - Provide recommendations on what to check for and precautions to consider before upgrading, how to perform the cluster upgrade, and considerations for configuring your cluster and/or applications to minimize risk and disruption during the upgrade process
 
-``` linenums="1"
+```
 Create a playbook for upgrading an Amazon EKS cluster
 
 Usage: eksup create playbook [OPTIONS] --cluster <CLUSTER>
@@ -96,7 +92,6 @@ Options:
   -c, --cluster <CLUSTER>    The name of the cluster to analyze
   -r, --region <REGION>      The AWS region where the cluster is provisioned
   -f, --filename <FILENAME>  Name of the playbook saved locally
-      --ignore-recommended   Exclude recommendations from the output
   -h, --help                 Print help
   -V, --version              Print version
 ```
@@ -112,5 +107,3 @@ Create playbook and save locally, ignoring recommendations:
 ```sh linenums="1"
 eksup create playbook --cluster <cluster> --region <region> --ignore-recommended
 ```
-
-See [examples](https://github.com/clowdhaus/eksup/tree/main/examples) for examples of the playbook output.