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

* 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,98 @@
+---
+title: Externally Deployed Virtual Clusters
+sidebar_label: Externally Deployed Virtual Clusters
+description: Understanding the lifecycle and management of platform deployed and externally deployed virtual clusters.
+---
+
+# Externally deployed virtual cluster
+
+Virtual clusters can be classified into two main types based on their deployment
+method and management: **platform deployed** and **externally deployed**.
+Understanding the differences between these types is crucial for effective
+virtual cluster management and utilization of platform capabilities.
+
+![externally deployed](/img/external-clusters.png)
+
+## Platform deployed virtual clusters
+
+Platform deployed virtual clusters are deployed and fully managed through the platform. They benefit from the platform's complete set of features and automated lifecycle management.
+
+:::info Characteristics of platform deployed virtual clusters
+- Deployment methods:
+  - Platform UI
+  - `vcluster platform create vcluster <name>` command
+- Full platform lifecycle management and reconciliation
+- Complete access to platform-specific features
+:::
+
+Platform deployed clusters provide an integrated experience with centralized management and full platform feature utilization.
+
+## Externally deployed virtual clusters
+
+Externally deployed virtual clusters are initially deployed outside of the platform, using tools like Helm, Argo, Terraform, or custom scripts. They can be added to the platform for enhanced management and feature access without changing their original deployment method.
+
+:::info Characteristics of externally deployed virtual clusters
+- Deployed using external tools (e.g., Helm, Argo CD, ClusterAPI, Terraform)
+- Added to the platform using `vcluster platform add vcluster [name]` command
+- Platform does not manage lifecycle (no reconciliation)
+- Allows use of certain platform features when connected with an agent
+:::
+
+For externally deployed virtual clusters, lifecycle changes should be performed using the original deployment tool (e.g., Argo CD, ClusterAPI) rather than the platform UI.
+
+### Platform features for externally deployed clusters
+
+When an externally deployed cluster is added to the platform and connected with an agent, certain platform features become available:
+
+- Sleep mode (requires agent and vcluster.yaml configuration)
+- Pro features of vCluster (license key distribution)
+- Administrative overview of virtual cluster fleet
+- UI-based inspection of cluster versions, enabled features, and resources
+- Issue detection (e.g., vCluster errors, outdated Kubernetes versions)
+- Enhanced debugging information and health status monitoring
+- User access management through the platform (useful with SSO)
+- Platform integrations (e.g., Argo CD, Vault secrets)
+
+:::note
+Features in the `platform:` [section of the vcluster.yaml](/vcluster/configure/vcluster-yaml/external/platform) are only available if the agent is installed.
+:::
+
+## Understanding the differences
+
+Virtual clusters are classified based on two key factors:
+1. Creation method: Via the platform or external tools
+2. Management approach: Fully platform-managed or externally managed with optional platform features
+
+:::note Key differences
+- Lifecycle management: Platform-driven vs. externally controlled
+- Feature availability: Full platform features vs. selective feature access (with agent)
+:::
+
+## Choosing the deployment model
+
+The choice between platform deployed and externally deployed virtual clusters can be made on a per-project or per-vcluster basis, allowing for a mix-and-match approach.
+
+Consider the following factors:
+
+1. Existing Infrastructure: If you already use tools like Argo CD for virtual cluster management, you might prefer externally deployed clusters for those specific projects.
+2. Integration Needs: For projects requiring tight integration with all platform features, platform deployed clusters might be more suitable.
+3. Management Preferences: Some teams might prefer the centralized management of platform deployed clusters, while others might opt for the flexibility of externally deployed clusters with selective platform feature usage.
+
+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.
+
+## Adding externally deployed clusters to the platform
+
+To add an existing virtual cluster to the platform without changing its lifecycle management:
+
+1. Ensure the virtual cluster is running vCluster v0.20 or greater.
+2. Run the following command:
+   ```
+   vcluster platform add vcluster [name]
+   ```
+
+This action is non-invasive and easily reversible, allowing you to benefit from platform features while maintaining your existing deployment workflows.
+
+## Next steps
+
+1. [Create a virtual cluster](/platform/use-platform/virtual-clusters/create/create-no-template) in the platform.
+2. [Add externally deployed virtual cluster](/platform/use-platform/virtual-clusters/add-virtual-clusters) virtual clusters to the platform.