Merge branch 'master' into update-crossplane-provider

docs/docs-content/architecture/networking-ports.md

@@ -11,8 +11,7 @@ sidebar_position: 20
 
 Depending on what version of Palette you are using, the internal architecture and network communication will be
 different. Before Palette 4.0.0 the management platform communicated with the workload cluster via NATS. Starting with
-Palette 4.0.0, the management platform communicates with the workload cluster via gRPC. Use the tabs below to view the
-network communication and ports for each architecture.
+Palette 4.0.0, the management platform communicates with the workload cluster via gRPC.
 
 ## SaaS Network Communications and Ports
 

docs/docs-content/architecture/orchestration-spectrocloud.md

@@ -1,47 +1,57 @@
 ---
 sidebar_label: "Order of Operations"
 title: "Order of Operations"
-description: "The methods of workload cluster provisioning for K8S clusters with Palette"
+description:
+  "Learn about the order of operations that make up the workload cluster provisioning process in Palette and how Cluster
+  API is used."
 icon: ""
 hide_table_of_contents: false
 sidebar_position: 10
 ---
 
-Spectro Cloud Palette provisions standard, upstream Kubernetes clusters using
-[Cluster API](https://cluster-api.sigs.k8s.io/).
+Palette provisions standard upstream Kubernetes clusters using [Cluster API](https://cluster-api.sigs.k8s.io/). Cluster
+API is a Kubernetes sub-project focused on providing declarative APIs and tooling to simplify provisioning, upgrading,
+and operating multiple Kubernetes clusters.
 
-Cluster API is a Kubernetes sub-project focused on providing declarative APIs and tooling to simplify provisioning,
-upgrading, and operating multiple Kubernetes clusters.
+:::info
+
+Check out the [Cluster API concepts](https://cluster-api.sigs.k8s.io/user/concepts) page for a detailed explanation of
+the components and concepts used in the Cluster API. Cluster API is a Kubernetes sub-project and different from the
+[Kubernetes API](https://kubernetes.io/docs/concepts/overview/kubernetes-api/) that you use to interact with your
+Kubernetes clusters.
 
-Cluster API demonstratively manages the lifecycle of a cluster (creation, scaling, enhancement, and deletion) and helps
-in automating the process of cluster lifecycle management for platform operations. Cluster API also helps in consistent
-and repeated cluster deployment across multiple infrastructure environments.
+:::
 
-<br />
+Cluster API automates cluster lifecycle management for platform operations. It ensures a consistent experience in
+cluster deployment across different infrastructure environments.
 
 ## Workload Cluster Provisioning
 
+The following diagram illustrates the order of operations that make up the workload cluster provisioning process.
+
 ![workload_cluster_provisioning.webp](/architecture_orchestartion-spectrocloud_provision-flow.webp)
 
-1. New K8S cluster request from user submitted to the cluster management system.
+1. A user submits a request to Palette for a new Kubernetes cluster. The request may come from the UI, API, or
+   Infrastructure as Code (IaC) tools such as Terraform or Crossplane.
 
-2. Palette creates the Cluster-API (CAPI) custom-resource specifications for the target cloud, e.g in VMware this would
-   translate to: Cluster, vSphereCluster, KubeadmControlPlane (with replica 1), and VSphereMachineTemplate. These
-   resources are created in the management cluster.
+2. Palette creates Cluster-API (CAPI) custom-resource specifications for the target cloud, such as AWS, GCP, etc. For
+   example, in VMware, this would translate to the following resources getting created: Cluster, vSphereCluster,
+   KubeadmControlPlane, and VSphereMachineTemplate. These resources are created in the Palette internal management
+   plane.
 
-3. Cluster API and corresponding cluster-api provider, e.g: cluster-api-provider-vsphere, provisions the first
-   control-plane node CP-A on the target cloud.
+3. Cluster API and the respective cluster-api provider, specific to the target platform, such as
+   cluster-api-provider-vsphere, provisions the first control-plane node (CP-A) on the target cloud.
 
-4. When CP-A is operational, the management platform will install a Palette agent into the workload cluster and then
-   perform a pivot of the Cluster API resources.
+4. When CP-A is operational, the Palette management platform will install a Palette agent into the workload cluster and
+   then perform a pivot of Cluster API resources. This means that Cluster API resources and their responsibilities are
+   now handled by the workload cluster, not the Palette management plane.
 
-5. CP-A agent will retrieve the latest specifications for the cluster, e.g: 3 control-plane, and 3 workers. CP-A will
-   generate and update the remaining CAPI resources, e.g: update replicas to 3 for KubeadmControlPlane, create the
-   worker's MachineDeployment or VSphereMachineTemplate. Cluster API running in CP-A will provision the remaining
-   control plane and worker nodes.
+5. CP-A agent will retrieve the required specifications for the cluster, such as the number of nodes. CP-A will generate
+   and update the remaining CAPI resources, e.g: update replicas to 3 for KubeadmControlPlane and create the worker's
+   MachineDeployment or VSphereMachineTemplate. The Cluster API active in CP-A will provision the remaining control
+   plane and worker nodes.
 
-6. The Palette agent will install all the additional add-ons as specified by the cluster's cluster profile (e.g:
-   logging, monitoring, security).
+6. The Palette agent will install all the additional add-ons as the cluster profile specifies.
 
 :::info
 
@@ -52,26 +62,28 @@ clusters.
 
 ## Why Palette Pivots?
 
-Palette's decentralized model is based on a "decentralized management - local policy enforcement" scalable architecture.
+Palette's decentralized model is based on a "decentralized management" design with local policy enforcement that allows
+for a scalable architecture.
 
 ![distributed_orchestration.webp](/architecture_orchestartion-spectrocloud_distributed-flow.webp)
 
-As part of the workload K8s cluster provisioning, only the first control-plane node is launched by Cluster API, running
-in the Palette management cluster. Once the control-plane node is operational, Cluster API resources are _pivoted_ from
-the management platform into the target workload cluster.
+As part of the workload for the Kubernetes cluster provisioning, only the first control-plane node is launched by the
+Cluster API active in the Palette management cluster. Once the control plane node is operational, Cluster API resources
+are _pivoted_ from the Palette management platform into the target workload cluster.
 
-The target workload cluster is then responsible for provisioning and maintaining the remaining control-plane and worker
-nodes. All Day-2 operations which result in node changes, including OS/K8s upgrades, scaling, and K8s certificate
-rotation, are triggered by changes to the Cluster API resources in the target workload cluster.
+The target workload cluster is responsible for provisioning and maintaining the remaining control plane and worker
+nodes. All Day-2 operations, which may result in node changes, including the operating system and Kubernetes upgrades,
+node scaling, and Kubernetes SSL certificate rotation, are triggered by changes to Cluster API resources in the target
+workload cluster.
 
-Palette pivots these clusters for several reasons, related to scalability and availability:
+Palette pivots Cluster API resources from the Palette management platform to the workload clusters for reasons such as:
 
-- **Scalability** - The management platform scales to meet the demand of all your workload clusters as the number of
-  tenant clusters and nodes increases in size.
+- **Scalability** - The central management platform, Palette, can scale to meet the demand of all your workload clusters
+  as the number of workload clusters and nodes increase in size. The workload cluster manages its own lifecycle and
+  resources through guidance from the Palette management platform.
 
-- **Resiliency** - Even if the management platform were to experience an outage, the workload clusters would retain
-  their resiliency capabilities, auto-recovery, launching of new nodes on failures, auto-scaling, and other policies
-  still work!
+- **Resiliency** - If the management platform were to experience an outage, the workload clusters would retain their
+  capabilities, such as auto-recovery, launching of new nodes on failures, auto-scaling, and other features.
 
-- **Intermittent network resiliency** - The design supports use cases where the workload clusters can still operate in
+- **Network resiliency** - The decentralized design supports use cases where the workload clusters can still operate in
   intermittent and disconnected network availability situations.