Adds external.platform.(apiKey/autoSleep/autoDelete) docs

_partials/what-is-vcluster-yaml.mdx

@@ -0,0 +1,71 @@
+import Link from "@docusaurus/Link";
+
+import Deploy from '@site/vcluster/_partials/deploy/deploy-beta.mdx'
+import DeployChanges from '@site/vcluster/_partials/deploy/deploy-changes-beta.mdx'
+
+The `vcluster.yaml` file contains all configurations when deploying and upgrading virtual clusters. It's optionally passed to the CLI or as the values file for deployments using Helm. It is also possible to create a vCluster without a vcluster.yaml file which will be created with a set of default values.
+
+Example configurations include the vCluster control plane's [backing store](/vcluster/configure/vcluster-yaml/control-plane/components/backing-store/), resource syncing behavior [from](/vcluster/configure/vcluster-yaml/sync/from-host/) and [to](/vcluster/configure/vcluster-yaml/sync/to-host/) the host cluster, and exporting the virtual cluster's [kubeconfig](/vcluster/configure/vcluster-yaml/export-kube-config) file.
+
+- **Unified Configuration:** All settings for vCluster in one place, simplifying management.
+- **Schema Validation:** Automatically validate the configuration when using the vCluster CLI.
+- **IDE Support:** Integrated schema with popular IDEs for autocompletion and validation.
+
+#### Example `vcluster.yaml` file
+
+```yaml
+controlPlane:
+  backingStore:
+    etcd:
+      embedded:
+        enabled: true
+  ingress:
+    enabled: true
+    host: vcluster-k8s-api.example.com
+sync:
+  toHost:
+    serviceAccounts:
+      enabled: true
+  fromHost:
+    nodes:
+      enabled: true
+      clearImageStatus: true
+exportKubeConfig:
+  context: my-vcluster-context
+  server: https://vcluster-k8s-api.example.com
+  secret:
+    name: my-vcluster-kubeconfig
+```
+
+This example configuration defines:
+1. [Embedded etcd](/vcluster/configure/vcluster-yaml/control-plane/components/backing-store/etcd/embedded) as the vCluster control plane's backing store to reduce management overhead (Pro feature).
+1. Syncing [ServiceAccount](/vcluster/configure/vcluster-yaml/sync/to-host/advanced/service-accounts) resources from the virtual to the host cluster, to support, for example, AWS IRSA.
+1. Deploying an [Ingress](/vcluster/configure/vcluster-yaml/control-plane/deployment/ingress) resource on the host cluster to expose the vCluster control plane's API server at a hostname.
+1. Syncing real [node](/vcluster/configure/vcluster-yaml/sync/from-host/nodes) data, rather than the default "pseudo" nodes, but clears the `ImageStatuses` field within the `NodeStatus` of the synced nodes.
+1. How to export the [kubeconfig](/vcluster/configure/vcluster-yaml/export-kube-config) file to a secret, so you can use it, for example, in your ArgoCD or Terraform pipelines.
+
+## How to Use `vcluster.yaml`
+### Creating a New Virtual Cluster
+- Define your configurations in the `vcluster.yaml` file.
+- Deploy your virtual cluster.
+
+<Deploy/>
+
+### Updating Existing Virtual Clusters
+- Simply update your `vcluster.yaml` file with the new configurations.
+- Apply the updates.
+
+<DeployChanges/>
+
+
+## FAQs
+
+### How do I upgrade my 0.19.x and earlier virtual cluster configurations?
+
+If you have existing 0.19.x virtual clusters, you can convert the old configuration values to the new v0.20 format. [View the guide](/vcluster/reference/migrations/0-20-migration) for more details.
+
+### Is it required to provide a `vcluster.yaml` file?
+No, if a `vcluster.yaml` file isn't provided, the vCluster will be created using a set of default values.
+
+### Can I change the configuration for existing virtual clusters?
+Yes, you can run `vcluster create VCLUSTER_NAME --upgrade -f vcluster.yaml`

go.mod

@@ -8,7 +8,7 @@ require (
 	github.com/invopop/jsonschema v0.12.1-0.20240219232115-a4467074499d
 	github.com/loft-sh/agentapi/v4 v4.0.0-alpha.16
 	github.com/loft-sh/api/v4 v4.0.0-alpha.16
-	github.com/loft-sh/vcluster-config v0.0.0-20240708084328-0260ef98d153
+	github.com/loft-sh/vcluster-config v0.0.0-20240716135058-8f0c5cc020dd
 	k8s.io/apimachinery v0.30.1
 	sigs.k8s.io/controller-runtime v0.18.4
 )

go.sum

@@ -118,8 +118,8 @@ github.com/loft-sh/apiserver v0.0.0-20240607231110-634aeeab2b36 h1:1euJ7mNHMI2MM
 github.com/loft-sh/apiserver v0.0.0-20240607231110-634aeeab2b36/go.mod h1:XxI95azXiqXHiIDRiyDTpZcxdtXQlUqeU5VMMDz8INA=
 github.com/loft-sh/jsonschema v0.0.0-20240411094214-6b88fd9d2a31 h1:fQOxqGdVGSkoaPe2H31eFmEC+0CzCXq7D5TqBJM0eXo=
 github.com/loft-sh/jsonschema v0.0.0-20240411094214-6b88fd9d2a31/go.mod h1:ffZ5Km5SWWRAIN6wbDXItl95euhFz2uON45H2qjYt+0=
-github.com/loft-sh/vcluster-config v0.0.0-20240708084328-0260ef98d153 h1:w6qPVDYEgApfbK1lz5q6gkBnW970Z6yjE5c/XPYUYRA=
-github.com/loft-sh/vcluster-config v0.0.0-20240708084328-0260ef98d153/go.mod h1:WOpmiPADZYvI3lzBd47KL/aTH4jSL8YQvI0kDy4YvFg=
+github.com/loft-sh/vcluster-config v0.0.0-20240716135058-8f0c5cc020dd h1:thFzgY7HZus0sLbbbX9U1CnDq+iCF8/R0/N/387OQVY=
+github.com/loft-sh/vcluster-config v0.0.0-20240716135058-8f0c5cc020dd/go.mod h1:WOpmiPADZYvI3lzBd47KL/aTH4jSL8YQvI0kDy4YvFg=
 github.com/mailru/easyjson v0.7.7 h1:UGYAvKxe3sBsEDzO8ZeWOSlIQfWFlxbzLZe7hwFURr0=
 github.com/mailru/easyjson v0.7.7/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc=
 github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=

hack/platform/partials/extconfig/config.go

@@ -0,0 +1,71 @@
+package extconfig
+
+import "github.com/loft-sh/vcluster-config/config"
+
+// External holds external tool configuration
+type External struct {
+	// Platform holds configuration for vCluster platform
+	Platform Platform `json:"platform"`
+}
+
+// Platform holds configuration for vCluster platform
+type Platform struct {
+	// APIKey defines where to find the platform access key and host. By default, vCluster will search in the following locations in this precedence:
+	// * platform.api.accessKey
+	// * environment variable called LICENSE
+	// * secret specified under external.platform.apiKey.secretName
+	// * secret called "vcluster-platform-api-key" in the vCluster namespace
+	APIKey config.PlatformAPIKey `json:"apiKey,omitempty"`
+
+	// AutoSleep holds configuration for automatic sleep and wakeup
+	// +optional
+	AutoSleep *AutoSleep `json:"autoSleep,omitempty"`
+
+	// AutoDelete holds configuration for automatic delete
+	// +optional
+	AutoDelete *AutoDelete `json:"autoDelete,omitempty"`
+}
+
+// Config represents the external config for vcluster.yaml to generate associated partials
+type Config struct {
+	// External holds external tool configuration
+	External External `json:"external"`
+}
+
+// AutoSleep holds configuration for automatic sleep based on inactivity or a preset schedule
+type AutoSleep struct {
+	// AfterInactivity specifies after how many seconds of inactivity the virtual cluster should sleep
+	// +optional
+	AfterInactivity int64 `json:"afterInactivity,omitempty"`
+
+	// Schedule specifies scheduled virtual cluster sleep in Cron format, see https://en.wikipedia.org/wiki/Cron.
+	// Note: timezone defined in the schedule string will be ignored. Use ".Timezone" field instead.
+	// +optional
+	Schedule string `json:"schedule,omitempty"`
+
+	// Timezone specifies time zone used for scheduled virtual cluster operations. Defaults to UTC.
+	// Accepts the same format as time.LoadLocation() in Go (https://pkg.go.dev/time#LoadLocation).
+	// The value should be a location name corresponding to a file in the IANA Time Zone database, such as "America/New_York".
+	// +optional
+	Timezone string `json:"timezone,omitempty"`
+
+	// AutoSleep holds configuration for automatic wakeup
+	// +optional
+	AutoWakeup *AutoWakeup `json:"autoWakeup,omitempty"`
+}
+
+// AutoWakeup holds configuration for automatic wakeup from sleep based on a preset schedule
+type AutoWakeup struct {
+	// Schedule specifies scheduled wakeup from sleep in Cron format, see https://en.wikipedia.org/wiki/Cron.
+	// Note: timezone defined in the schedule string will be ignored. The timezone for the autoSleep schedule will be
+	// used
+	// +optional
+	Schedule string `json:"schedule,omitempty"`
+}
+
+// AutoDelete holds configuration for automatic deletion of a virtual cluster after inactivity
+type AutoDelete struct {
+	// AfterInactivity specifies after how many seconds of inactivity the virtual cluster be deleted
+	// +optional
+	AfterInactivity int64 `json:"afterInactivity,omitempty"`
+}

hack/platform/partials/main.go

@@ -7,6 +7,7 @@ import (
 	clusterv1 "github.com/loft-sh/agentapi/v4/pkg/apis/loft/cluster/v1"
 	managementv1 "github.com/loft-sh/api/v4/pkg/apis/management/v1"
 	storagev1 "github.com/loft-sh/api/v4/pkg/apis/storage/v1"
+	extconfig "github.com/loft-sh/vcluster-docs/hack/platform/partials/extconfig"
 	"github.com/loft-sh/vcluster-docs/hack/platform/util"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
@@ -893,4 +894,18 @@ spec:
 		},
 		Create: true,
 	})
+
+	util.DefaultRequire = false
+
+	paths := []string{
+		"external/platform/apiKey",
+		"external/platform/autoSleep",
+		"external/platform/autoDelete",
+		"external/platform",
+		"external",
+	}
+
+	for _, p := range paths {
+		util.GenerateFromPath(util.GenerateSchema(&extconfig.Config{}), util.BasePath+"/config", p)
+	}
 }

hack/platform/util/schema.go

@@ -71,6 +71,18 @@ func generateSchema(configInstance interface{}) *jsonschema.Schema {
 	if commentMap == nil {
 		commentMap = map[string]string{}
 
+		runInDir("hack", func() {
+			localCommentsMap := map[string]string{}
+			err := jsonschema.ExtractGoComments("", "platform/partials/extconfig", localCommentsMap)
+			if err != nil {
+				panic(err)
+			}
+
+			for k, v := range localCommentsMap {
+				commentMap["github.com/loft-sh/vcluster-docs/hack/"+k] = v
+			}
+		})
+
 		runInDir("vendor", func() {
 			err := jsonschema.ExtractGoComments("", "github.com/loft-sh/vcluster-config/config", commentMap)
 			if err != nil {