From 167e6e0c8890543e3cddc1be862057f787d24d5e Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 19 Mar 2026 15:57:29 +0000 Subject: [PATCH 1/3] docs: add workflow for working with loft-sh/api types Document the process for making changes to github.com/loft-sh/api/v4 types (in loft-enterprise) and testing them locally in vCluster before merging. This addresses the chicken-and-egg dependency issue where schema changes require coordinated updates across repositories. https://claude.ai/code/session_01L1AZrxEXzRecXFpimzP8gD --- CONTRIBUTING.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ec81972c54..d62f095513 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -15,6 +15,7 @@ Thank you for contributing to vcluster! Here you can find common questions aroun - [Developing without DevSpace](#developing-without-devspace) - [Running vcluster Tests](#running-vcluster-tests) +- [Working with github.com/loft-sh/api Types](#working-with-githubcomloft-shapi-types) - [License](#license) - [Copyright notice](#copyright-notice) @@ -364,6 +365,63 @@ If [Ginkgo](https://github.com/onsi/ginkgo#global-installation) is already insta For running conformance tests, please take a look at [conformance tests](https://github.com/loft-sh/tree/vcluster/main/conformance/v1.21) +# Working with github.com/loft-sh/api Types + +The vCluster Helm chart schema (`chart/values.schema.json`) is generated from Go types defined in both this repository and the `github.com/loft-sh/api/v4` package (maintained in the [loft-enterprise](https://github.com/loft-sh/loft-enterprise) repository). When making changes to types in `github.com/loft-sh/api/v4/pkg/vclusterconfig`, you need to follow a specific workflow to test your changes locally before merging. + +## Why This Matters + +The schema generation (`go run hack/schema/main.go`) reads type definitions from: +- `github.com/loft-sh/vcluster/config` (this repository) +- `vendor/github.com/loft-sh/api/v4/pkg/vclusterconfig` (vendored from loft-enterprise) + +If you add new fields or types in loft-enterprise that affect the vCluster configuration, those changes won't be reflected in the vCluster schema until the dependency is updated. + +## Local Development Workflow + +To test changes to `github.com/loft-sh/api/v4` types locally: + +### 1. Generate Types in loft-enterprise + +In the loft-enterprise repository, run the type generation: + +```bash +just gen-go +``` + +This generates all API types, including those in `staging/src/github.com/loft-sh/api/v4/pkg/vclusterconfig`. + +### 2. Point vCluster to Local loft-enterprise + +In the vCluster repository, add a `replace` directive in `go.mod` to point to your local loft-enterprise repo: + +```go +replace github.com/loft-sh/api/v4 => /path/to/loft-enterprise/staging/src/github.com/loft-sh/api/v4 +``` + +### 3. Update Vendor and Regenerate Schema + +```bash +go mod tidy +go mod vendor +go run hack/schema/main.go +``` + +### 4. Test Your Changes + +Deploy a vCluster with your schema changes and verify the new configuration options work as expected. + +### 5. Merging Changes + +When your changes are ready, merge PRs in the following order: + +1. **Platform first**: Merge your loft-enterprise PR with the API type changes +2. **Release platform version**: A new platform release publishes the updated `github.com/loft-sh/api/v4` version +3. **Bump in vCluster**: Create a PR in vCluster to update the `github.com/loft-sh/api/v4` dependency to the new version +4. **Merge vCluster PR**: Remove any `replace` directives and merge + +This ensures the dependency chain is properly maintained and both repositories stay in sync. + # License This project is licensed under the Apache 2.0 License. From 3082e7ba9d9b52ae1931935af91bc43fba7f93d0 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 31 Mar 2026 07:57:54 +0000 Subject: [PATCH 2/3] docs: expand Step 4 with custom image build and platform testing Address PR review feedback from @nprokopic requesting more detail on how to actually test local vCluster changes from the platform. Added steps for building a custom Docker image and deploying it with a local chart using --local-chart-dir. https://claude.ai/code/session_01L1AZrxEXzRecXFpimzP8gD --- CONTRIBUTING.md | 38 +++++++++++++++++++++++++++++++++++--- 1 file changed, 35 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d62f095513..a72958cdc8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -407,11 +407,43 @@ go mod vendor go run hack/schema/main.go ``` -### 4. Test Your Changes +### 4. Build a Custom vCluster Image -Deploy a vCluster with your schema changes and verify the new configuration options work as expected. +Build a Docker image containing your local changes: -### 5. Merging Changes +```bash +docker build . -t my-vcluster:0.0.1 +``` + +If using Kind, load the image into the cluster: + +```bash +kind load docker-image my-vcluster:0.0.1 +``` + +### 5. Test Your Changes from the Platform + +To test your custom vCluster image when creating a virtual cluster from the platform (loft-enterprise), configure the platform to use your locally built image. Create a `vcluster.yaml` values override: + +```yaml +controlPlane: + statefulSet: + imagePullPolicy: Never + image: + registry: "" + repository: my-vcluster + tag: 0.0.1 +``` + +Then create a virtual cluster using the local chart (which includes the regenerated schema): + +```bash +vcluster create my-vcluster -n my-vcluster -f ./vcluster.yaml --local-chart-dir chart +``` + +This ensures the platform deploys a vCluster using both your updated schema and your locally built syncer image. + +### 6. Merging Changes When your changes are ready, merge PRs in the following order: From f7d85a5e43b9126001732465af85d70b2db71482 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 31 Mar 2026 08:00:03 +0000 Subject: [PATCH 3/3] docs: distinguish Helm vs platform driver testing workflows The previous version incorrectly suggested using --local-chart-dir for platform testing. This flag only works with the Helm driver. When testing schema changes through the platform driver, intermediate pre-releases are required because the platform fetches charts from published releases. Updated docs to clearly separate the two workflows and document the version coupling implications. https://claude.ai/code/session_01L1AZrxEXzRecXFpimzP8gD --- CONTRIBUTING.md | 45 ++++++++++++++++++++++++++++++--------------- 1 file changed, 30 insertions(+), 15 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a72958cdc8..e21098c261 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -407,23 +407,18 @@ go mod vendor go run hack/schema/main.go ``` -### 4. Build a Custom vCluster Image +### 4. Test with the Helm Driver (without the platform) -Build a Docker image containing your local changes: +If you only need to test vCluster schema changes without the platform, you can build a custom image and deploy with the local chart: ```bash docker build . -t my-vcluster:0.0.1 -``` - -If using Kind, load the image into the cluster: -```bash +# For Kind users: kind load docker-image my-vcluster:0.0.1 ``` -### 5. Test Your Changes from the Platform - -To test your custom vCluster image when creating a virtual cluster from the platform (loft-enterprise), configure the platform to use your locally built image. Create a `vcluster.yaml` values override: +Create a `vcluster.yaml` values override: ```yaml controlPlane: @@ -435,24 +430,44 @@ controlPlane: tag: 0.0.1 ``` -Then create a virtual cluster using the local chart (which includes the regenerated schema): +Deploy using the Helm driver with `--local-chart-dir` to use the regenerated schema: ```bash vcluster create my-vcluster -n my-vcluster -f ./vcluster.yaml --local-chart-dir chart ``` -This ensures the platform deploys a vCluster using both your updated schema and your locally built syncer image. +**Note:** `--local-chart-dir` only works with the Helm driver. It is **not** supported when deploying virtual clusters through the platform driver. + +### 5. Test with the Platform Driver + +When you need to test schema changes by creating virtual clusters through the platform, you cannot use a local chart directly. The platform fetches the vCluster Helm chart from a release, so you need to create intermediate releases: + +1. **Create a platform pre-release** with your API type changes in loft-enterprise (e.g. `v4.8.1-next.0`). The platform CI will publish a corresponding `github.com/loft-sh/api/v4` release. + +2. **Bump the API dependency in vCluster** to the newly published version: + ```bash + go get github.com/loft-sh/api/v4@v4.8.1-next.0 + go mod tidy + go mod vendor + go run hack/schema/main.go + ``` + +3. **Create an internal vCluster pre-release** (e.g. `v0.33.1-next.internal.1`) in both the vcluster and vcluster-pro repositories. Wait for the release CI to complete. + +4. **Test from the platform** by creating a virtual cluster that uses the internal vCluster version from step 3. + +This workflow is more involved but is necessary because the platform resolves vCluster charts from published releases, not from local directories. ### 6. Merging Changes -When your changes are ready, merge PRs in the following order: +When your changes are tested and ready, merge PRs in the following order: 1. **Platform first**: Merge your loft-enterprise PR with the API type changes 2. **Release platform version**: A new platform release publishes the updated `github.com/loft-sh/api/v4` version -3. **Bump in vCluster**: Create a PR in vCluster to update the `github.com/loft-sh/api/v4` dependency to the new version -4. **Merge vCluster PR**: Remove any `replace` directives and merge +3. **Bump in vCluster**: Create a PR in vCluster to update the `github.com/loft-sh/api/v4` dependency to the new version, regenerate the schema, and remove any `replace` directives +4. **Merge vCluster PR** -This ensures the dependency chain is properly maintained and both repositories stay in sync. +**Important:** This means that platform changes requiring new schema fields will only work with the vCluster version where the schema was updated. For example, a platform `v4.8.1` release using new config fields would require at least vCluster `v0.33.1` (where the schema includes those fields). # License