diff --git a/_partials/what-is-vcluster-yaml.mdx b/_partials/what-is-vcluster-yaml.mdx new file mode 100644 index 000000000..5ad0d403c --- /dev/null +++ b/_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. + + + +### Updating Existing Virtual Clusters +- Simply update your `vcluster.yaml` file with the new configurations. +- Apply the updates. + + + + +## 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` diff --git a/go.mod b/go.mod index 2fc5bd4b9..96f29ad32 100644 --- a/go.mod +++ b/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 ) diff --git a/go.sum b/go.sum index ed1a1688b..683b2360a 100644 --- a/go.sum +++ b/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= diff --git a/hack/platform/partials/extconfig/config.go b/hack/platform/partials/extconfig/config.go new file mode 100644 index 000000000..0a0961305 --- /dev/null +++ b/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"` +} diff --git a/hack/platform/partials/main.go b/hack/platform/partials/main.go index 510bd2d41..4a635143c 100644 --- a/hack/platform/partials/main.go +++ b/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) + } } diff --git a/hack/platform/util/schema.go b/hack/platform/util/schema.go index 768cc86bb..c3ee5c279 100644 --- a/hack/platform/util/schema.go +++ b/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 { diff --git a/platform/api/_partials/resources/config/external.mdx b/platform/api/_partials/resources/config/external.mdx new file mode 100755 index 000000000..71ff5b54f --- /dev/null +++ b/platform/api/_partials/resources/config/external.mdx @@ -0,0 +1,220 @@ + +
+ + +## `external` required object pro {#external} + +External holds external tool configuration + + + + + + +
+ + +### `platform` required object pro {#external-platform} + +Platform holds configuration for vCluster platform + + + + + + +
+ + +#### `apiKey` required object pro {#external-platform-apiKey} + +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 + + + + + + +
+ + +##### `secretName` required string pro {#external-platform-apiKey-secretName} + +SecretName is the name of the secret where the platform access key is stored. This defaults to vcluster-platform-api-key if undefined. + + + + + +
+ + + +
+ + +##### `namespace` required string pro {#external-platform-apiKey-namespace} + +Namespace defines the namespace where the access key secret should be retrieved from. If this is not equal to the namespace +where the vCluster instance is deployed, you need to make sure vCluster has access to this other namespace. + + + + + +
+ + + +
+ + +##### `createRBAC` required boolean false pro {#external-platform-apiKey-createRBAC} + +CreateRBAC will automatically create the necessary RBAC roles and role bindings to allow vCluster to read the secret specified +in the above namespace, if specified. +This defaults to true. + + + + + +
+ + +
+ + + +
+ + +#### `autoSleep` required object pro {#external-platform-autoSleep} + +AutoSleep holds configuration for automatic sleep and wakeup + + + + + + +
+ + +##### `afterInactivity` required integer pro {#external-platform-autoSleep-afterInactivity} + +AfterInactivity specifies after how many seconds of inactivity the virtual cluster should sleep + + + + + +
+ + + +
+ + +##### `schedule` required string pro {#external-platform-autoSleep-schedule} + +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. + + + + + +
+ + + +
+ + +##### `timezone` required string pro {#external-platform-autoSleep-timezone} + +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". + + + + + +
+ + + +
+ + +##### `autoWakeup` required object pro {#external-platform-autoSleep-autoWakeup} + +AutoSleep holds configuration for automatic wakeup + + + + + + +
+ + +##### `schedule` required string pro {#external-platform-autoSleep-autoWakeup-schedule} + +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 + + + + + +
+ + +
+ + +
+ + + +
+ + +#### `autoDelete` required object pro {#external-platform-autoDelete} + +AutoDelete holds configuration for automatic delete + + + + + + +
+ + +##### `afterInactivity` required integer pro {#external-platform-autoDelete-afterInactivity} + +AfterInactivity specifies after how many seconds of inactivity the virtual cluster be deleted + + + + + +
+ + +
+ + +
+ + +
diff --git a/platform/api/_partials/resources/config/external/platform.mdx b/platform/api/_partials/resources/config/external/platform.mdx new file mode 100755 index 000000000..cc92d3e9a --- /dev/null +++ b/platform/api/_partials/resources/config/external/platform.mdx @@ -0,0 +1,205 @@ + +
+ + +## `platform` required object pro {#platform} + +Platform holds configuration for vCluster platform + + + + + + +
+ + +### `apiKey` required object pro {#platform-apiKey} + +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 + + + + + + +
+ + +#### `secretName` required string pro {#platform-apiKey-secretName} + +SecretName is the name of the secret where the platform access key is stored. This defaults to vcluster-platform-api-key if undefined. + + + + + +
+ + + +
+ + +#### `namespace` required string pro {#platform-apiKey-namespace} + +Namespace defines the namespace where the access key secret should be retrieved from. If this is not equal to the namespace +where the vCluster instance is deployed, you need to make sure vCluster has access to this other namespace. + + + + + +
+ + + +
+ + +#### `createRBAC` required boolean false pro {#platform-apiKey-createRBAC} + +CreateRBAC will automatically create the necessary RBAC roles and role bindings to allow vCluster to read the secret specified +in the above namespace, if specified. +This defaults to true. + + + + + +
+ + +
+ + + +
+ + +### `autoSleep` required object pro {#platform-autoSleep} + +AutoSleep holds configuration for automatic sleep and wakeup + + + + + + +
+ + +#### `afterInactivity` required integer pro {#platform-autoSleep-afterInactivity} + +AfterInactivity specifies after how many seconds of inactivity the virtual cluster should sleep + + + + + +
+ + + +
+ + +#### `schedule` required string pro {#platform-autoSleep-schedule} + +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. + + + + + +
+ + + +
+ + +#### `timezone` required string pro {#platform-autoSleep-timezone} + +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". + + + + + +
+ + + +
+ + +#### `autoWakeup` required object pro {#platform-autoSleep-autoWakeup} + +AutoSleep holds configuration for automatic wakeup + + + + + + +
+ + +##### `schedule` required string pro {#platform-autoSleep-autoWakeup-schedule} + +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 + + + + + +
+ + +
+ + +
+ + + +
+ + +### `autoDelete` required object pro {#platform-autoDelete} + +AutoDelete holds configuration for automatic delete + + + + + + +
+ + +#### `afterInactivity` required integer pro {#platform-autoDelete-afterInactivity} + +AfterInactivity specifies after how many seconds of inactivity the virtual cluster be deleted + + + + + +
+ + +
+ + +
diff --git a/platform/api/_partials/resources/config/external/platform/apiKey.mdx b/platform/api/_partials/resources/config/external/platform/apiKey.mdx new file mode 100755 index 000000000..13ab8e3d4 --- /dev/null +++ b/platform/api/_partials/resources/config/external/platform/apiKey.mdx @@ -0,0 +1,65 @@ + +
+ + +## `apiKey` required object pro {#apiKey} + +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 + + + + + + +
+ + +### `secretName` required string pro {#apiKey-secretName} + +SecretName is the name of the secret where the platform access key is stored. This defaults to vcluster-platform-api-key if undefined. + + + + + +
+ + + +
+ + +### `namespace` required string pro {#apiKey-namespace} + +Namespace defines the namespace where the access key secret should be retrieved from. If this is not equal to the namespace +where the vCluster instance is deployed, you need to make sure vCluster has access to this other namespace. + + + + + +
+ + + +
+ + +### `createRBAC` required boolean false pro {#apiKey-createRBAC} + +CreateRBAC will automatically create the necessary RBAC roles and role bindings to allow vCluster to read the secret specified +in the above namespace, if specified. +This defaults to true. + + + + + +
+ + +
diff --git a/platform/api/_partials/resources/config/external/platform/autoDelete.mdx b/platform/api/_partials/resources/config/external/platform/autoDelete.mdx new file mode 100755 index 000000000..0e585cd11 --- /dev/null +++ b/platform/api/_partials/resources/config/external/platform/autoDelete.mdx @@ -0,0 +1,28 @@ + +
+ + +## `autoDelete` required object pro {#autoDelete} + +AutoDelete holds configuration for automatic delete + + + + + + +
+ + +### `afterInactivity` required integer pro {#autoDelete-afterInactivity} + +AfterInactivity specifies after how many seconds of inactivity the virtual cluster be deleted + + + + + +
+ + +
diff --git a/platform/api/_partials/resources/config/external/platform/autoSleep.mdx b/platform/api/_partials/resources/config/external/platform/autoSleep.mdx new file mode 100755 index 000000000..ebaaf1012 --- /dev/null +++ b/platform/api/_partials/resources/config/external/platform/autoSleep.mdx @@ -0,0 +1,93 @@ + +
+ + +## `autoSleep` required object pro {#autoSleep} + +AutoSleep holds configuration for automatic sleep and wakeup + + + + + + +
+ + +### `afterInactivity` required integer pro {#autoSleep-afterInactivity} + +AfterInactivity specifies after how many seconds of inactivity the virtual cluster should sleep + + + + + +
+ + + +
+ + +### `schedule` required string pro {#autoSleep-schedule} + +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. + + + + + +
+ + + +
+ + +### `timezone` required string pro {#autoSleep-timezone} + +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". + + + + + +
+ + + +
+ + +### `autoWakeup` required object pro {#autoSleep-autoWakeup} + +AutoSleep holds configuration for automatic wakeup + + + + + + +
+ + +#### `schedule` required string pro {#autoSleep-autoWakeup-schedule} + +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 + + + + + +
+ + +
+ + +
diff --git a/platform/install/configure/config.mdx b/platform/install/configure/config.mdx index 3fcdd123e..b27a83c8e 100644 --- a/platform/install/configure/config.mdx +++ b/platform/install/configure/config.mdx @@ -154,8 +154,7 @@ agentValues: enabled: true ``` -Administrators can also provide Agent values for _specific clusters_ by setting the `loft. -sh/agent-values` Annotation of a specific cluster object. These values will always override any +Administrators can also provide Agent values for _specific clusters_ by setting the `loft.sh/agent-values` Annotation of a specific cluster object. These values will always override any values provided in the parent vCluster Platform chart. ## Config reference diff --git a/platform/virtual-clusters/configure/_category_.json b/platform/virtual-clusters/configure/_category_.json new file mode 100644 index 000000000..b2bc999c3 --- /dev/null +++ b/platform/virtual-clusters/configure/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Configure", + "collapsible": false +} + diff --git a/platform/virtual-clusters/configure/vcluster-yaml/README.mdx b/platform/virtual-clusters/configure/vcluster-yaml/README.mdx new file mode 100644 index 000000000..2a0354aa6 --- /dev/null +++ b/platform/virtual-clusters/configure/vcluster-yaml/README.mdx @@ -0,0 +1,19 @@ +--- +title: What is vcluster.yaml (w/Pro)? +sidebar_label: vcluster.yaml +--- + +import External from '@site/platform/api/_partials/resources/config/external.mdx' +import WhatIsVclusterYaml from '@site/_partials/what-is-vcluster-yaml.mdx' + + + +## Pro Features + +All the OSS features are applicable in any `vcluster.yaml`. Below are the Pro features only available on the vCluster Platform. + +### Config reference + + + + diff --git a/platform/virtual-clusters/configure/vcluster-yaml/external/README.mdx b/platform/virtual-clusters/configure/vcluster-yaml/external/README.mdx new file mode 100644 index 000000000..c92e6f36c --- /dev/null +++ b/platform/virtual-clusters/configure/vcluster-yaml/external/README.mdx @@ -0,0 +1,28 @@ +--- +title: External Configuration +sidebar_label: external +--- + +import ProAdmonition from '@site/vcluster/_partials/admonitions/pro-admonition.mdx' +import Platform from '@site/platform/api/_partials/resources/config/external/platform.mdx' + + + +The external section is for configuring tools external to vCluster. + +## Platform + +In the platform section you can configure vCluster Platform features like autoSleep, to clean up unused resources for cost savings. + +### Example + +```yaml +external: + platform: + autoSleep: + afterInactivity: 600 # 10 minutes +``` + +## Config reference + + diff --git a/platform/virtual-clusters/configure/vcluster-yaml/external/platform/api-key.mdx b/platform/virtual-clusters/configure/vcluster-yaml/external/platform/api-key.mdx new file mode 100644 index 000000000..98f2b94ad --- /dev/null +++ b/platform/virtual-clusters/configure/vcluster-yaml/external/platform/api-key.mdx @@ -0,0 +1,8 @@ +--- +title: apiKey +sidebar_label: apiKey +--- + +import ApiKey from '@site/platform/api/_partials/resources/config/external/platform/apiKey.mdx' + + diff --git a/platform/virtual-clusters/configure/vcluster-yaml/external/platform/auto-delete.mdx b/platform/virtual-clusters/configure/vcluster-yaml/external/platform/auto-delete.mdx new file mode 100644 index 000000000..781c83370 --- /dev/null +++ b/platform/virtual-clusters/configure/vcluster-yaml/external/platform/auto-delete.mdx @@ -0,0 +1,8 @@ +--- +title: autoDelete +sidebar_label: autoDelete +--- + +import AutoDelete from '@site/platform/api/_partials/resources/config/external/platform/autoDelete.mdx' + + diff --git a/platform/virtual-clusters/configure/vcluster-yaml/external/platform/auto-sleep.mdx b/platform/virtual-clusters/configure/vcluster-yaml/external/platform/auto-sleep.mdx new file mode 100644 index 000000000..02ab2fe3b --- /dev/null +++ b/platform/virtual-clusters/configure/vcluster-yaml/external/platform/auto-sleep.mdx @@ -0,0 +1,8 @@ +--- +title: autoSleep +sidebar_label: autoSleep +--- + +import AutoSleep from '@site/platform/api/_partials/resources/config/external/platform/autoSleep.mdx' + + diff --git a/platform/virtual-clusters/configure/what-is-vcluster-yaml.mdx b/platform/virtual-clusters/configure/what-is-vcluster-yaml.mdx new file mode 100644 index 000000000..f072b468d --- /dev/null +++ b/platform/virtual-clusters/configure/what-is-vcluster-yaml.mdx @@ -0,0 +1,8 @@ +--- +title: What is vcluster.yaml +sidebar_position: 1 +--- + +import WhatIsVclusterYaml from '@site/vcluster/configure/what-is-vcluster-yaml.mdx'; + + diff --git a/vcluster/configure/vcluster-yaml/README.mdx b/vcluster/configure/vcluster-yaml/README.mdx index d9ee0c6bd..2890e8573 100644 --- a/vcluster/configure/vcluster-yaml/README.mdx +++ b/vcluster/configure/vcluster-yaml/README.mdx @@ -16,6 +16,7 @@ import Plugins from '@site/vcluster/_partials/config/plugins.mdx' import Experimental from '@site/vcluster/_partials/config/experimental.mdx' import Telemetry from '@site/vcluster/_partials/config/telemetry.mdx' import DeployChanges from '@site/vcluster/_partials/deploy/deploy-changes.mdx' +import External from '@site/platform/api/_partials/resources/config/external.mdx' ## Create a virtual cluster with a config file @@ -38,4 +39,5 @@ Configure your vCluster installation in a `vcluster.yaml` configuration file. Th + diff --git a/vcluster/configure/vcluster-yaml/external/README.mdx b/vcluster/configure/vcluster-yaml/external/README.mdx new file mode 100644 index 000000000..c92e6f36c --- /dev/null +++ b/vcluster/configure/vcluster-yaml/external/README.mdx @@ -0,0 +1,28 @@ +--- +title: External Configuration +sidebar_label: external +--- + +import ProAdmonition from '@site/vcluster/_partials/admonitions/pro-admonition.mdx' +import Platform from '@site/platform/api/_partials/resources/config/external/platform.mdx' + + + +The external section is for configuring tools external to vCluster. + +## Platform + +In the platform section you can configure vCluster Platform features like autoSleep, to clean up unused resources for cost savings. + +### Example + +```yaml +external: + platform: + autoSleep: + afterInactivity: 600 # 10 minutes +``` + +## Config reference + + diff --git a/vcluster/configure/vcluster-yaml/external/platform/api-key.mdx b/vcluster/configure/vcluster-yaml/external/platform/api-key.mdx new file mode 100644 index 000000000..bbeaf04a3 --- /dev/null +++ b/vcluster/configure/vcluster-yaml/external/platform/api-key.mdx @@ -0,0 +1,9 @@ +--- +title: apiKey +sidebar_label: apiKey +sidebar_class_name: pro +--- + +import ApiKey from '@site/platform/api/_partials/resources/config/external/platform/apiKey.mdx' + + diff --git a/vcluster/configure/vcluster-yaml/external/platform/auto-delete.mdx b/vcluster/configure/vcluster-yaml/external/platform/auto-delete.mdx new file mode 100644 index 000000000..90eac1cfd --- /dev/null +++ b/vcluster/configure/vcluster-yaml/external/platform/auto-delete.mdx @@ -0,0 +1,9 @@ +--- +title: autoDelete +sidebar_label: autoDelete +sidebar_class_name: pro +--- + +import AutoDelete from '@site/platform/api/_partials/resources/config/external/platform/autoDelete.mdx' + + diff --git a/vcluster/configure/vcluster-yaml/external/platform/auto-sleep.mdx b/vcluster/configure/vcluster-yaml/external/platform/auto-sleep.mdx new file mode 100644 index 000000000..f92df6af9 --- /dev/null +++ b/vcluster/configure/vcluster-yaml/external/platform/auto-sleep.mdx @@ -0,0 +1,9 @@ +--- +title: autoSleep +sidebar_label: autoSleep +sidebar_class_name: pro +--- + +import AutoSleep from '@site/platform/api/_partials/resources/config/external/platform/autoSleep.mdx' + + diff --git a/vcluster/configure/what-is-vcluster-yaml.mdx b/vcluster/configure/what-is-vcluster-yaml.mdx index b6b57754a..6407bfa11 100644 --- a/vcluster/configure/what-is-vcluster-yaml.mdx +++ b/vcluster/configure/what-is-vcluster-yaml.mdx @@ -5,72 +5,6 @@ sidebar_position: 1 description: Intro to the vcluster.yaml configuration file --- -import Deploy from '@site/vcluster/_partials/deploy/deploy-beta.mdx' -import DeployChanges from '@site/vcluster/_partials/deploy/deploy-changes-beta.mdx' +import WhatIsVclusterYaml from '@site/_partials/what-is-vcluster-yaml.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](../configure/vcluster-yaml/control-plane/components/backing-store/), resource syncing behavior [from](../configure/vcluster-yaml/sync/from-host/) and [to](../configure/vcluster-yaml/sync/to-host/) the host cluster, and exporting the virtual cluster's [kubeconfig](../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](../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](../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](../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](../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](../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. - - - -### Updating Existing Virtual Clusters -- Simply update your `vcluster.yaml` file with the new configurations. -- Apply the updates. - - - - -## 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](../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` \ No newline at end of file + diff --git a/vendor/github.com/loft-sh/vcluster-config/config/config.go b/vendor/github.com/loft-sh/vcluster-config/config/config.go index 41eb1ef80..eca52ad7f 100644 --- a/vendor/github.com/loft-sh/vcluster-config/config/config.go +++ b/vendor/github.com/loft-sh/vcluster-config/config/config.go @@ -80,6 +80,37 @@ type Config struct { type Integrations struct { // MetricsServer reuses the metrics server from the host cluster within the vCluster. MetricsServer MetricsServer `json:"metricsServer,omitempty"` + + // KubeVirt reuses a host kubevirt and makes certain CRDs from it available inside the vCluster + KubeVirt KubeVirt `json:"kubeVirt,omitempty"` +} + +// KubeVirt reuses a host kubevirt and makes certain CRDs from it available inside the vCluster +type KubeVirt struct { + // Enabled signals if the integration should be enabled + Enabled bool `json:"enabled,omitempty"` + // APIService holds information about where to find the virt-api service. Defaults to virt-api/kubevirt. + APIService APIService `json:"apiService,omitempty"` + // Webhook holds configuration for enabling the webhook within the vCluster + Webhook EnableSwitch `json:"webhook,omitempty"` + // Sync holds configuration on what resources to sync + Sync KubeVirtSync `json:"sync,omitempty"` +} + +// KubeVirtSync are the crds that are supported by this integration +type KubeVirtSync struct { + // If DataVolumes should get synced + DataVolumes EnableSwitch `json:"dataVolumes,omitempty"` + // If VirtualMachineInstanceMigrations should get synced + VirtualMachineInstanceMigrations EnableSwitch `json:"virtualMachineInstanceMigrations,omitempty"` + // If VirtualMachineInstances should get synced + VirtualMachineInstances EnableSwitch `json:"virtualMachineInstances,omitempty"` + // If VirtualMachines should get synced + VirtualMachines EnableSwitch `json:"virtualMachines,omitempty"` + // If VirtualMachineClones should get synced + VirtualMachineClones EnableSwitch `json:"virtualMachineClones,omitempty"` + // If VirtualMachinePools should get synced + VirtualMachinePools EnableSwitch `json:"virtualMachinePools,omitempty"` } // MetricsServer reuses the metrics server from the host cluster within the vCluster. @@ -87,6 +118,9 @@ type MetricsServer struct { // Enabled signals the metrics server integration should be enabled. Enabled bool `json:"enabled,omitempty"` + // APIService holds information about where to find the metrics-server service. Defaults to metrics-server/kube-system. + APIService APIService `json:"apiService,omitempty"` + // Nodes defines if metrics-server nodes api should get proxied from host to virtual cluster. Nodes bool `json:"nodes,omitempty"` @@ -94,6 +128,24 @@ type MetricsServer struct { Pods bool `json:"pods,omitempty"` } +// APIService holds configuration related to the api server +type APIService struct { + // Service is a reference to the service for the API server. + Service APIServiceService `json:"service,omitempty"` +} + +// APIServiceService holds the service name and namespace of the host apiservice. +type APIServiceService struct { + // Name is the name of the host service of the apiservice. + Name string `json:"name,omitempty"` + + // Namespace is the name of the host service of the apiservice. + Namespace string `json:"namespace,omitempty"` + + // Port is the target port on the host service to connect to. + Port int `json:"port,omitempty"` +} + // ExternalConfig holds external tool configuration type ExternalConfig map[string]interface{} @@ -1199,31 +1251,31 @@ type VolumeClaim struct { // VolumeMount describes a mounting of a Volume within a container. type VolumeMount struct { // This must match the Name of a Volume. - Name string `json:"name" protobuf:"bytes,1,opt,name=name"` + Name string `protobuf:"bytes,1,opt,name=name" json:"name"` // Mounted read-only if true, read-write otherwise (false or unspecified). // Defaults to false. - ReadOnly bool `json:"readOnly,omitempty" protobuf:"varint,2,opt,name=readOnly"` + ReadOnly bool `protobuf:"varint,2,opt,name=readOnly" json:"readOnly,omitempty"` // Path within the container at which the volume should be mounted. Must // not contain ':'. - MountPath string `json:"mountPath" protobuf:"bytes,3,opt,name=mountPath"` + MountPath string `protobuf:"bytes,3,opt,name=mountPath" json:"mountPath"` // Path within the volume from which the container's volume should be mounted. // Defaults to "" (volume's root). - SubPath string `json:"subPath,omitempty" protobuf:"bytes,4,opt,name=subPath"` + SubPath string `protobuf:"bytes,4,opt,name=subPath" json:"subPath,omitempty"` // mountPropagation determines how mounts are propagated from the host // to container and the other way around. // When not set, MountPropagationNone is used. // This field is beta in 1.10. - MountPropagation *string `json:"mountPropagation,omitempty" protobuf:"bytes,5,opt,name=mountPropagation,casttype=MountPropagationMode"` + MountPropagation *string `protobuf:"bytes,5,opt,name=mountPropagation,casttype=MountPropagationMode" json:"mountPropagation,omitempty"` // Expanded path within the volume from which the container's volume should be mounted. // Behaves similarly to SubPath but environment variable references $(VAR_NAME) are expanded using the container's environment. // Defaults to "" (volume's root). // SubPathExpr and SubPath are mutually exclusive. - SubPathExpr string `json:"subPathExpr,omitempty" protobuf:"bytes,6,opt,name=subPathExpr"` + SubPathExpr string `protobuf:"bytes,6,opt,name=subPathExpr" json:"subPathExpr,omitempty"` } type ControlPlaneScheduling struct { @@ -1434,7 +1486,7 @@ type MutatingWebhookConfiguration struct { type MutatingWebhook struct { // reinvocationPolicy indicates whether this webhook should be called multiple times as part of a single admission evaluation. // Allowed values are "Never" and "IfNeeded". - ReinvocationPolicy *string `json:"reinvocationPolicy,omitempty" protobuf:"bytes,10,opt,name=reinvocationPolicy,casttype=ReinvocationPolicyType"` + ReinvocationPolicy *string `protobuf:"bytes,10,opt,name=reinvocationPolicy,casttype=ReinvocationPolicyType" json:"reinvocationPolicy,omitempty"` ValidatingWebhook `json:",inline"` } @@ -1743,7 +1795,6 @@ type ExperimentalDeployHelmChart struct { type PlatformConfig 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 @@ -1758,6 +1809,11 @@ type PlatformAPIKey struct { // Namespace defines the namespace where the access key secret should be retrieved from. If this is not equal to the namespace // where the vCluster instance is deployed, you need to make sure vCluster has access to this other namespace. Namespace string `json:"namespace,omitempty"` + + // CreateRBAC will automatically create the necessary RBAC roles and role bindings to allow vCluster to read the secret specified + // in the above namespace, if specified. + // This defaults to true. + CreateRBAC *bool `json:"createRBAC,omitempty"` } type ExperimentalGenericSync struct { @@ -1936,16 +1992,16 @@ type DenyRule struct { type RuleWithVerbs struct { // APIGroups is the API groups the resources belong to. '*' is all groups. - APIGroups []string `json:"apiGroups,omitempty" protobuf:"bytes,1,rep,name=apiGroups"` + APIGroups []string `protobuf:"bytes,1,rep,name=apiGroups" json:"apiGroups,omitempty"` // APIVersions is the API versions the resources belong to. '*' is all versions. - APIVersions []string `json:"apiVersions,omitempty" protobuf:"bytes,2,rep,name=apiVersions"` + APIVersions []string `protobuf:"bytes,2,rep,name=apiVersions" json:"apiVersions,omitempty"` // Resources is a list of resources this rule applies to. - Resources []string `json:"resources,omitempty" protobuf:"bytes,3,rep,name=resources"` + Resources []string `protobuf:"bytes,3,rep,name=resources" json:"resources,omitempty"` // Scope specifies the scope of this rule. - Scope *string `json:"scope,omitempty" protobuf:"bytes,4,rep,name=scope"` + Scope *string `protobuf:"bytes,4,rep,name=scope" json:"scope,omitempty"` // Verb is the kube verb associated with the request for API requests, not the http verb. This includes things like list and watch. // For non-resource requests, this is the lowercase http verb. diff --git a/vendor/github.com/loft-sh/vcluster-config/config/values.yaml b/vendor/github.com/loft-sh/vcluster-config/config/values.yaml index 29986edd3..fa68ee3c3 100644 --- a/vendor/github.com/loft-sh/vcluster-config/config/values.yaml +++ b/vendor/github.com/loft-sh/vcluster-config/config/values.yaml @@ -69,12 +69,6 @@ sync: all: false labels: {} -integrations: - metricsServer: - enabled: false - nodes: true - pods: true - controlPlane: distro: k8s: @@ -419,6 +413,29 @@ controlPlane: globalMetadata: annotations: {} +integrations: + metricsServer: + enabled: false + nodes: true + pods: true + kubeVirt: + enabled: false + webhook: + enabled: true + sync: + dataVolumes: + enabled: false + virtualMachines: + enabled: true + virtualMachineInstances: + enabled: true + virtualMachinePools: + enabled: true + virtualMachineClones: + enabled: true + virtualMachineInstanceMigrations: + enabled: true + rbac: role: enabled: true diff --git a/vendor/modules.txt b/vendor/modules.txt index d28527980..3b77f466e 100644 --- a/vendor/modules.txt +++ b/vendor/modules.txt @@ -174,7 +174,7 @@ github.com/loft-sh/api/v4/pkg/managerfactory # github.com/loft-sh/apiserver v0.0.0-20240607231110-634aeeab2b36 ## explicit; go 1.22.4 github.com/loft-sh/apiserver/pkg/builders -# github.com/loft-sh/vcluster-config v0.0.0-20240708084328-0260ef98d153 +# github.com/loft-sh/vcluster-config v0.0.0-20240716135058-8f0c5cc020dd ## explicit; go 1.22.0 github.com/loft-sh/vcluster-config/config # github.com/mailru/easyjson v0.7.7