contrib-virtual-workspaces

module
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 11, 2026 License: Apache-2.0

README

contrib-virtual-workspaces

Virtual workspaces for kcp, and the platform built out of two of them.

kcp Platform is tenancy/ and marketplace/ together — tenants, projects and memberships, plus a catalog of offerings to enable in them — served under the *.platform.kcp.io API groups. Its web console lives in kcp hub, which runs these components as one platform. The other three components are standalone virtual workspaces that stand on their own.

Component What it serves Image
access/ SelfClusterAccessReview — "which workspaces can this user access?" in one call ghcr.io/kcp-dev/contrib-virtual-workspaces/access-vw
mcp/ Model Context Protocol as a virtual workspace, scoped to what the caller can see (uses the access VW) ghcr.io/kcp-dev/contrib-virtual-workspaces/mcp-vw
ephemeral/ Non-persisted resources: POST in, a producer webhook answers, nothing reaches etcd ghcr.io/kcp-dev/contrib-virtual-workspaces/ephemeral-vw
tenancy/ Tenants, projects and memberships as kcp workspaces and RBAC, plus SelfTenancyReview — "which tenants am I in?" — and the tenancyctl client ghcr.io/kcp-dev/contrib-virtual-workspaces/tenancy-vw
marketplace/ Producers and offerings: a read-only catalog, where enabling is a plain kcp APIBinding the consumer authors themselves ghcr.io/kcp-dev/contrib-virtual-workspaces/marketplace-vw

Each component's README documents its design, deployment and limits.

Layout

  • One go.mod at the root. The kcp Kubernetes fork replace block lives here once, and hack/verify-fork-pin.sh checks it against virtual-workspace-framework's.
  • One Dockerfile with a shared builder stage and one final stage per component; images are selected with --target access-vw|mcp-vw|ephemeral-vw|tenancy-vw.
  • The root Makefile owns building, testing and verification (make build, make test, make verify, make images, make test-e2e-<component>). Component Makefiles keep only the local development targets that need to run next to their manifests.
  • CI runs one verify job, one build/test job, and one e2e job per component (.github/workflows/ci.yaml); images build as a matrix over the Dockerfile targets (.github/workflows/images.yaml).

Building

make build              # all binaries into bin/
make build-access       # or per component
make images             # all three container images
make image-mcp          # or per component

One CLI

Every component that ships a client exposes it as importable cobra commands, and contribctl (built by make build-cli into bin/) arranges them around what a person does rather than around which component implements it:

contribctl login --issuer https://dex.example.com --url https://kcp.example.com:8443
contribctl use                     # pick a tenant and project
contribctl tenants                 # what you can reach
contribctl offers                  # what you could enable
contribctl enable acme.things      # enable it here
contribctl membership add alice@example.com --role admin

The user-facing commands need no kubeconfig at all — the virtual workspaces authenticate the caller and answer for the identity they hold. contribctl admin is the other side, writing to kcp with a kubeconfig. login --url remembers the server in ~/.kube/contribctl.json, so nothing after it has to be told where kcp is.

The standalone binaries (tenancyctl, scar-to-kubeconfig) remain the same code under their own names.

Building a producer

producer-quickstart/ is a producer ready to copy: a Go type, the schema generated from it, a controller that reconciles it in every workspace that enabled it, the instructions the console shows, a Dockerfile, a deployment manifest and a CI workflow. Copy the directory, rename the group, kind and producer, replace the fake provisioning in the reconciler, and make publish puts it on the catalog. It is its own Go module so the copy builds alone; make verify here builds and tests it so it cannot rot.

Development with Tilt

make tilt-up (or hack/tilt/up.sh) brings up the whole stack in one place: kcp itself comes from the kcp checkout's own Tilt setup (contrib/tilt — operator, shards, front-proxy behind https://kcp.localhost:8443, observability, dashboard), included unchanged by the repo Tiltfile, and this repo's components run on top as live-reloading local processes.

  • KCP_DIR points at the kcp clone (default ../kcp).
  • Admin kubeconfigs land in .tilt/ (tilt-frontproxy.kubeconfig, per shard), extracted by kcp's own tooling.
  • Each component's virtual workspace is deployed in the cluster by the kcp-operator (a VirtualWorkspace object: Deployment, Service, serving certificate, and the component's own init as an init container) and routed by the front-proxy, so everything answers on one address — https://kcp.localhost:8443, kcp under /clusters/ and each virtual workspace under /services/<name>. The operators run as local processes, which is where the fast iteration is.
  • TENANCY_ENABLED=false / MARKETPLACE_ENABLED=false skip a component.
  • Dex runs in the same kind cluster as the shared OIDC issuer (https://dex.kcp.localhost:8443/dex), trusted by kcp and both virtual workspaces, so a token names the same user everywhere. The environment is seeded with a demo tenant and project, so whoami has something to say right after login. DEX_ENABLED=false / SEED_ENABLED=false turn either off.

hack/tilt/README.md walks the stack end to end: bringing it up, logging in with Dex, and an ordinary user going from a password to a working kubeconfig for exactly the workspaces they were granted.

Testing

An identity provider is shared by every component: hack/dex/ runs Dex and writes the AuthenticationConfiguration that kcp and the virtual workspaces both consume, so a username cannot drift between them. The tenancy e2e uses it by default (DEX=false falls back to client certificates where docker is unavailable).

make test               # unit tests
make verify             # gofmt, vet, fork pin, manifest rendering, tidy -diff
make test-e2e-access    # kind + kcp-operator
make test-e2e-mcp       # kind + kcp-operator + both VWs from this checkout
make test-e2e-ephemeral # local processes against a real kcp
make test-e2e-tenancy   # local processes against a real kcp

History

This repository merges three formerly separate repositories, imported with full history:

Directories

Path Synopsis
access
cmd/access-vw command
cmd/init command
Command access-vw-init installs the kcp-side objects the access virtual workspace needs — the APIResourceSchema, the APIExport, and the APIExportEndpointSlice the RBAC provider follows — and verifies they came up.
Command access-vw-init installs the kcp-side objects the access virtual workspace needs — the APIResourceSchema, the APIExport, and the APIExportEndpointSlice the RBAC provider follows — and verifies they came up.
cmd/scar-to-kubeconfig command
Command scar-to-kubeconfig calls the SCAR endpoint with a bearer token and writes a kubeconfig with one context per authorized cluster.
Command scar-to-kubeconfig calls the SCAR endpoint with a bearer token and writes a kubeconfig with one context per authorized cluster.
config/apiexport
Package apiexport holds the kcp-side assets the access virtual workspace needs in the workspace that hosts its APIExport: the APIResourceSchema for SelfClusterAccessReview, the APIExport itself, the RBAC that makes the export bindable, and the APIExportEndpointSlice the RBAC provider follows.
Package apiexport holds the kcp-side assets the access virtual workspace needs in the workspace that hosts its APIExport: the APIResourceSchema for SelfClusterAccessReview, the APIExport itself, the RBAC that makes the export bindable, and the APIExportEndpointSlice the RBAC provider follows.
config/controller
Package controller holds the identity the access virtual workspace runs as: a ServiceAccount in the workspace that hosts the APIExport, its token, and the RBAC it needs.
Package controller holds the identity the access virtual workspace runs as: a ServiceAccount in the workspace that hosts the APIExport, its token, and the RBAC it needs.
pkg/accessprovider
Package accessprovider defines the AccessProvider interface — the writer-side seam between the access graph and the various sources of authorization data that may populate it.
Package accessprovider defines the AccessProvider interface — the writer-side seam between the access graph and the various sources of authorization data that may populate it.
pkg/bootstrap
Package bootstrap installs the kcp-side objects the access virtual workspace needs and verifies they came up.
Package bootstrap installs the kcp-side objects the access virtual workspace needs and verifies they came up.
pkg/cli
Package cli holds the access component's user-facing commands, shaped so the repo-wide CLI can mount them and the standalone binaries stay thin wrappers.
Package cli holds the access component's user-facing commands, shaped so the repo-wide CLI can mount them and the standalone binaries stay thin wrappers.
pkg/graph
Package graph provides an in-memory RBAC permission map for kcp.
Package graph provides an in-memory RBAC permission map for kcp.
pkg/rbacprovider
Package rbacprovider implements the kcp-native RBAC AccessProvider.
Package rbacprovider implements the kcp-native RBAC AccessProvider.
pkg/server
Package server wires the Access Virtual Workspace binary together: the shared access graph, the RBAC provider that populates it, and a virtual-workspace root apiserver (kcp virtual-workspace-framework) serving the access virtual workspace at /services/access behind kcp's front-proxy.
Package server wires the Access Virtual Workspace binary together: the shared access graph, the RBAC provider that populates it, and a virtual-workspace root apiserver (kcp virtual-workspace-framework) serving the access virtual workspace at /services/access behind kcp's front-proxy.
pkg/virtual
Package virtual provides shared building blocks for the virtual workspaces served by this binary, built on the kcp virtual-workspace-framework.
Package virtual provides shared building blocks for the virtual workspaces served by this binary, built on the kcp virtual-workspace-framework.
pkg/virtual/scar
Package scar implements the SelfClusterAccessReview API of the Access Virtual Workspace.
Package scar implements the SelfClusterAccessReview API of the Access Virtual Workspace.
sdk/apis/access/v1alpha1
Package v1alpha1 holds the API types for the Access Virtual Workspace (group access.contrib.kcp.io).
Package v1alpha1 holds the API types for the Access Virtual Workspace (group access.contrib.kcp.io).
cmd
cli command
contribctl is the repo-wide CLI.
contribctl is the repo-wide CLI.
ephemeral
cmd/endpointslice-controller command
Command endpointslice-controller publishes a virtual workspace's address into the EphemeralResourceEndpointSlices of one workspace.
Command endpointslice-controller publishes a virtual workspace's address into the EphemeralResourceEndpointSlices of one workspace.
cmd/ephemeral-virtual-workspace/command
Package command wires the ephemeral virtual workspace server together.
Package command wires the ephemeral virtual workspace server together.
cmd/ephemeral-virtual-workspace/options
Package options holds the command line surface of the ephemeral virtual workspace server.
Package options holds the command line surface of the ephemeral virtual workspace server.
examples/webhook command
Command example-webhook is a reference implementation of the EphemeralReview contract: a BucketInfo service that answers with live numbers.
Command example-webhook is a reference implementation of the EphemeralReview contract: a BucketInfo service that answers with live numbers.
pkg/apis/ephemeral/v1alpha1
Package v1alpha1 defines the wire contract between the ephemeral virtual workspace and a provider's webhook.
Package v1alpha1 defines the wire contract between the ephemeral virtual workspace and a provider's webhook.
pkg/cacheclient
Package cacheclient builds a rest.Config that talks to a kcp cache server.
Package cacheclient builds a rest.Config that talks to a kcp cache server.
pkg/config
Package config holds the operator-supplied registry of webhook-backed resources.
Package config holds the operator-supplied registry of webhook-backed resources.
pkg/endpointslice
Package endpointslice publishes a virtual workspace's address into the endpoint slices that APIExports reference.
Package endpointslice publishes a virtual workspace's address into the endpoint slices that APIExports reference.
pkg/registry
Package registry implements the REST storage that answers a create by calling a provider webhook.
Package registry implements the REST storage that answers a create by calling a provider webhook.
pkg/virtualworkspace/apidefinitions
Package apidefinitions turns the operator's webhook registry plus the APIExport/APIResourceSchema objects in kcp into the served API surface.
Package apidefinitions turns the operator's webhook registry plus the APIExport/APIResourceSchema objects in kcp into the served API surface.
pkg/virtualworkspace/apidomainkey
Package apidomainkey encodes which APIExport a request is being served for.
Package apidomainkey encodes which APIExport a request is being served for.
pkg/virtualworkspace/authorizer
Package authorizer gates access to the ephemeral virtual workspace.
Package authorizer gates access to the ephemeral virtual workspace.
pkg/virtualworkspace/builder
Package builder assembles the ephemeral virtual workspace.
Package builder assembles the ephemeral virtual workspace.
pkg/webhook
Package webhook implements the client half of the EphemeralReview contract.
Package webhook implements the client half of the EphemeralReview contract.
marketplace-vw is the marketplace component in one binary: `init` installs the kcp-side objects, `operator` materializes producer workspaces, bind grants and enablement bindings, and `virtualworkspace` serves the catalog and the enablements write path.
marketplace-vw is the marketplace component in one binary: `init` installs the kcp-side objects, `operator` materializes producer workspaces, bind grants and enablement bindings, and `virtualworkspace` serves the catalog and the enablements write path.
cmd
Package cmd holds the marketplace binary's subcommands.
Package cmd holds the marketplace binary's subcommands.
config/apiexport
Package apiexport holds the kcp-side assets the marketplace component needs.
Package apiexport holds the kcp-side assets the marketplace component needs.
pkg/bootstrap
Package bootstrap installs the kcp-side objects the marketplace needs: the three APIExports and their endpoint slices, the producer WorkspaceType, and the two hand-bound tiers (catalog and producers parent).
Package bootstrap installs the kcp-side objects the marketplace needs: the three APIExports and their endpoint slices, the producer WorkspaceType, and the two hand-bound tiers (catalog and producers parent).
pkg/cli
Package cli holds the marketplace's user-facing commands: browsing the catalog, and enabling an offering in a workspace.
Package cli holds the marketplace's user-facing commands: browsing the catalog, and enabling an offering in a workspace.
pkg/directory
Package directory is the in-memory index the marketplace virtual workspace answers from: Providers mirrored from the catalog tier, published APIExports mirrored from every producer workspace.
Package directory is the in-memory index the marketplace virtual workspace answers from: Providers mirrored from the catalog tier, published APIExports mirrored from every producer workspace.
pkg/offering
Package offering reads an APIExport as a catalog card.
Package offering reads an APIExport as a catalog card.
pkg/operator
Package operator reconciles the marketplace API into producer workspaces and bind grants.
Package operator reconciles the marketplace API into producer workspaces and bind grants.
pkg/provider
Package provider populates the marketplace directory: Providers from the catalog tier's export, offerings from the APIExports published in each producer workspace — the same multicluster discovery the operator runs, but read-only into the in-memory directory the virtual workspace answers from.
Package provider populates the marketplace directory: Providers from the catalog tier's export, offerings from the APIExports published in each producer workspace — the same multicluster discovery the operator runs, but read-only into the in-memory directory the virtual workspace answers from.
pkg/server
Package server wires the marketplace virtual workspace binary together: the directory, the producer that fills it, and a virtual-workspace root apiserver serving the catalog read-only at /services/marketplace behind kcp's front-proxy.
Package server wires the marketplace virtual workspace binary together: the directory, the producer that fills it, and a virtual-workspace root apiserver serving the catalog read-only at /services/marketplace behind kcp's front-proxy.
pkg/virtual/catalog
Package catalog implements the marketplace virtual workspace: the read-only catalog at /services/marketplace.
Package catalog implements the marketplace virtual workspace: the read-only catalog at /services/marketplace.
sdk/apis/marketplace/v1alpha1
Package v1alpha1 holds the API types for the marketplace component (group marketplace.platform.kcp.io).
Package v1alpha1 holds the API types for the marketplace component (group marketplace.platform.kcp.io).
mcp
cmd
config/apiexport
Package apiexport holds the kcp-side assets the mcp component needs in the workspace hosting its APIExport.
Package apiexport holds the kcp-side assets the mcp component needs in the workspace hosting its APIExport.
internal/access
Package access asks the access virtual workspace which workspaces a caller can see.
Package access asks the access virtual workspace which workspaces a caller can see.
internal/mcp
Package mcp serves the Model Context Protocol as a kcp virtual workspace.
Package mcp serves the Model Context Protocol as a kcp virtual workspace.
pkg/bootstrap
Package bootstrap installs the mcp component's kcp-side objects: the workspace that owns them, the APIExport a consumer enables by binding, and the grant the operator needs to read through it.
Package bootstrap installs the mcp component's kcp-side objects: the workspace that owns them, the APIExport a consumer enables by binding, and the grant the operator needs to read through it.
pkg/operator
Package operator turns a consumer's APIBinding into working MCP.
Package operator turns a consumer's APIBinding into working MCP.
pkg/tools
Package tools is the shared kit for kcp MCP tools: the Scope authorization contract every tool operates within, plus helpers for GVR parsing and unstructured object handling.
Package tools is the shared kit for kcp MCP tools: the Scope authorization contract every tool operates within, plus helpers for GVR parsing and unstructured object handling.
pkg/tools/admin
Package admin provides read tools for kcp operator internals — LogicalClusters, Shards, Partitions and PartitionSets.
Package admin provides read tools for kcp operator internals — LogicalClusters, Shards, Partitions and PartitionSets.
pkg/tools/apis
Package apis provides read tools for the machinery of kcp's API sharing model — APIResourceSchemas and APIConversions.
Package apis provides read tools for the machinery of kcp's API sharing model — APIResourceSchemas and APIConversions.
pkg/tools/core
Package core is the default toolset: navigating the caller's workspaces (workspaces, APIBindings, APIExports, WorkspaceTypes, workspace lifecycle) plus generic read access to any resource by GVR.
Package core is the default toolset: navigating the caller's workspaces (workspaces, APIBindings, APIExports, WorkspaceTypes, workspace lifecycle) plus generic read access to any resource by GVR.
pkg/tools/write
Package write provides generic mutation tools — create, update, patch, delete and scale by GVR.
Package write provides generic mutation tools — create, update, patch, delete and scale by GVR.
pkg/toolsets
Package toolsets names the groups of MCP tools an operator can enable.
Package toolsets names the groups of MCP tools an operator can enable.
sdk/apis/mcp/v1alpha1
Package v1alpha1 holds the API type for the mcp component (group mcp.platform.kcp.io).
Package v1alpha1 holds the API type for the mcp component (group mcp.platform.kcp.io).
tenancy-vw is the tenancy component in one binary: `init` installs the kcp-side objects, `operator` materializes tenants, projects and memberships, and `virtualworkspace` serves SelfTenancyReview.
tenancy-vw is the tenancy component in one binary: `init` installs the kcp-side objects, `operator` materializes tenants, projects and memberships, and `virtualworkspace` serves SelfTenancyReview.
cmd
Package cmd holds the tenancy binary's subcommands.
Package cmd holds the tenancy binary's subcommands.
cmd/tenancyctl command
tenancyctl is the client for the kcp tenancy model: organization workspaces, tenants, projects and access grants for administrators, and "whoami"/"kubeconfig" for the people those grants are about.
tenancyctl is the client for the kcp tenancy model: organization workspaces, tenants, projects and access grants for administrators, and "whoami"/"kubeconfig" for the people those grants are about.
config/apiexport
Package apiexport holds the kcp-side assets the tenancy component needs.
Package apiexport holds the kcp-side assets the tenancy component needs.
pkg/bootstrap
Package bootstrap installs the kcp-side objects the tenancy component needs: the four APIExports and their endpoint slices, the two WorkspaceTypes that bind the capability exports into provisioned workspaces, and the platform tier's own bindings.
Package bootstrap installs the kcp-side objects the tenancy component needs: the four APIExports and their endpoint slices, the two WorkspaceTypes that bind the capability exports into provisioned workspaces, and the platform tier's own bindings.
pkg/cli
Package cli implements tenancyctl, the day-to-day client for the tenancy model: provisioning organization workspaces, creating tenants and projects, granting and revoking access, and asking the virtual workspace what the caller can reach.
Package cli implements tenancyctl, the day-to-day client for the tenancy model: provisioning organization workspaces, creating tenants and projects, granting and revoking access, and asking the virtual workspace what the caller can reach.
pkg/clicontext
Package clicontext holds what the CLI remembers between commands: the server it talks to, and where the user is working.
Package clicontext holds what the CLI remembers between commands: the server it talks to, and where the user is working.
pkg/directory
Package directory keeps the tenancy virtual workspace's in-memory answer state: every Tenant, Project and Membership across all organization workspaces, indexed for the one question the VW answers — "what does this identity belong to?".
Package directory keeps the tenancy virtual workspace's in-memory answer state: every Tenant, Project and Membership across all organization workspaces, indexed for the one question the VW answers — "what does this identity belong to?".
pkg/naming
Package naming turns human display names into kcp workspace names.
Package naming turns human display names into kcp workspace names.
pkg/operator
Package operator reconciles the tenancy API into kcp workspaces and RBAC.
Package operator reconciles the tenancy API into kcp workspaces and RBAC.
pkg/provider
Package provider populates the tenancy directory from the tenant workspaces bound to the tenancy APIExport.
Package provider populates the tenancy directory from the tenant workspaces bound to the tenancy APIExport.
pkg/server
Package server wires the tenancy virtual workspace binary together: the directory, the provider that fills it from tenant workspaces, and a virtual-workspace root apiserver serving SelfTenancyReview at /services/tenancy behind kcp's front-proxy.
Package server wires the tenancy virtual workspace binary together: the directory, the provider that fills it from tenant workspaces, and a virtual-workspace root apiserver serving SelfTenancyReview at /services/tenancy behind kcp's front-proxy.
pkg/virtual/membership
Package membership serves the grants of the tenants a caller administers, so RBAC can be managed without entering the workspace the grants live in.
Package membership serves the grants of the tenants a caller administers, so RBAC can be managed without entering the workspace the grants live in.
pkg/virtual/selfprojectrequest
Package selfprojectrequest implements the one write the tenancy virtual workspace performs on a caller's behalf: creating a project in a tenant the caller administers.
Package selfprojectrequest implements the one write the tenancy virtual workspace performs on a caller's behalf: creating a project in a tenant the caller administers.
pkg/virtual/selftenancyreview
Package selftenancyreview implements the SelfTenancyReview API of the tenancy virtual workspace.
Package selftenancyreview implements the SelfTenancyReview API of the tenancy virtual workspace.
pkg/virtual/selftenantrequest
Package selftenantrequest lets a caller with nothing get their first tenant.
Package selftenantrequest lets a caller with nothing get their first tenant.
sdk/apis/tenancy/v1alpha1
Package v1alpha1 holds the API types for the tenancy component (group tenancy.platform.kcp.io).
Package v1alpha1 holds the API types for the tenancy component (group tenancy.platform.kcp.io).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL