feat: add externally managed vs platform managed (#174)

Signed-off-by: Piotr Zaniewski <[email protected]>

platform/understand/externally-vs-platform-deployed.mdx

@@ -0,0 +1,77 @@
+---
+title: Virtual Cluster Lifecycle Ownership
+sidebar_label: Virtual Cluster Lifecycle Ownership
+---
+
+# Virtual Cluster Lifecycle Ownership
+
+There are two main types of virtual clusters based on how they're managed: platform-managed and externally managed. These classifications determine how the clusters are created, updated, and integrated with the platform's features. Understanding the differences between these types is important for effective cluster management and utilization of platform capabilities.
+
+## Platform-Managed Virtual Clusters
+
+These are virtual clusters that are deployed and fully managed through our platform. They benefit from the platform's complete set of management features and automated lifecycle management.
+
+:::info Characteristics
+- Identified by `external: false` in `VirtualClusterInstance` CR
+- Deployment methods:
+    - Platform UI
+    - vCluster CLI (when authenticated to Platform)
+    - `vcluster platform create vcluster` command
+    - `vcluster create <name> --driver platform` command
+- `external: false` is set automatically when using platform deployment methods
+- Full platform lifecycle management and reconciliation
+- Complete access to platform-specific features and tooling
+:::
+
+Platform-managed clusters provide an integrated experience with centralized management and full platform feature utilization.
+
+## Externally-Managed Virtual Clusters
+
+These virtual clusters are initially deployed outside of our platform, using tools like Helm or custom scripts. While they can be imported into the platform for some level of management, they retain their original ownership and have limited platform integration.
+
+:::info Characteristics
+- Deployed using external tools (e.g., ArgoCD, CAPI)
+- Deployed using `vcluster create <name>` command (if driver helm is active)
+- Deployed using `vcluster create <name> --driver helm`
+- Deployed using `helm install vcluster ...`
+- Added to the platform using `vcluster platform add vcluster` command
+- Platform won't manage it (perform reconciliation)
+:::
+
+In this scenario, changes to externally managed virtual clusters should not be performed via the Platform UI. Instead, they should be made using the same tool originally used to deploy the virtual cluster (for example ArgoCD, ClusterAPI, or other tools).
+
+## Understanding the Differences
+
+Virtual clusters are classified based on two key factors: their creation method (via the platform or externally) and their update mechanism (managed by the platform or an external tool). These factors determine whether the platform or an external tool is the lifecycle owner.
+
+:::note
+In short, the key differences are:
+- Creation method: Platform interface vs. external tools
+- Update mechanism: Platform-driven vs. externally controlled
+:::
+
+📝 Current limitations for externally-managed clusters:
+- Sleep mode unavailable
+- Pod and audit logging restricted
+
+Feature parity is in active development. Most functionalities are identical across both cluster types.
+
+Choose based on your preferred cluster lifecycle management approach.
+
+## Choosing Between Platform-Managed and Externally-Managed Clusters
+
+The choice between platform-managed and externally-managed virtual clusters is not a one-size-fits-all decision. It can be made on a per-project or even per-vcluster basis, allowing for a mix-and-match approach that best suits your specific needs.
+
+Consider the following factors when making your decision:
+
+1. **Existing Infrastructure**: If you already have tools in place for lifecycle management of virtual clusters (e.g., ArgoCD, ClusterAPI), you might prefer externally-managed clusters for those specific projects or vclusters.
+2. **Integration Needs**: For projects requiring tight integration with platform features, platform-managed clusters might be more suitable.
+3. **Management Preferences**: Some teams might prefer the centralized management offered by platform-managed clusters, while others might opt for the flexibility of externally-managed clusters.
+
+Remember, you can use both types within the same environment, choosing the most appropriate option for each virtual cluster based on its specific requirements and your team's preferences.
+
+## Next Steps
+
+1. [Create a virtual cluster](/platform/use-platform/virtual-clusters/create/create-no-template) in the platform.
+2. [Add externally managed](/platform/use-platform/virtual-clusters/add-virtual-clusters) virtual clusters to the platform.
+