From f716a3e0a8f5031ffe69e1922eadf35648bd5d68 Mon Sep 17 00:00:00 2001 From: olamilekan000 Date: Mon, 2 Nov 2026 04:03:59 +0100 Subject: [PATCH 1/2] tenancy: move to tenancy.platform.kcp.io, add self-service requests and memberships Signed-off-by: olamilekan000 --- access/pkg/server/server.go | 3 +- tenancy/README.md | 58 ++- tenancy/cmd/init.go | 18 +- tenancy/cmd/root.go | 5 + .../config/apiexport/apiexport-platform.yaml | 4 +- .../config/apiexport/apiexport-tenancy.yaml | 8 +- ...a-memberships.tenancy.platform.kcp.io.yaml | 101 +++++ .../apiresourceschema-memberships.yaml | 88 ---- ...hema-projects.tenancy.platform.kcp.io.yaml | 89 ++++ .../apiexport/apiresourceschema-projects.yaml | 72 ---- ...chema-tenants.tenancy.platform.kcp.io.yaml | 100 +++++ .../apiexport/apiresourceschema-tenants.yaml | 67 --- tenancy/config/apiexport/bootstrap.go | 6 +- tenancy/config/apiexport/store-bindings.yaml | 6 +- .../config/apiexport/tenants-bindings.yaml | 6 +- .../config/examples/apibinding-consumer.yaml | 6 +- tenancy/pkg/bootstrap/bootstrap.go | 198 ++++++--- tenancy/pkg/cli/login.go | 60 ++- tenancy/pkg/cli/membership.go | 97 +++-- tenancy/pkg/cli/memberships.go | 214 ++++++++++ tenancy/pkg/cli/org.go | 5 +- tenancy/pkg/cli/review.go | 72 +++- tenancy/pkg/cli/review_test.go | 106 +++++ tenancy/pkg/cli/root.go | 25 +- tenancy/pkg/cli/seed.go | 164 ++++++++ tenancy/pkg/cli/selection.go | 85 ++++ tenancy/pkg/cli/tenant.go | 22 +- tenancy/pkg/cli/user.go | 324 ++++++++++++++ tenancy/pkg/clicontext/context.go | 146 +++++++ tenancy/pkg/directory/directory.go | 32 ++ .../generated/openapi/zz_generated.openapi.go | 395 +++++++++++++++++- tenancy/pkg/naming/naming.go | 24 ++ tenancy/pkg/naming/naming_test.go | 21 + tenancy/pkg/operator/operator.go | 52 --- tenancy/pkg/operator/tenant.go | 79 ++++ tenancy/pkg/operator/workspaces.go | 4 +- tenancy/pkg/provider/clusters.go | 109 +++++ tenancy/pkg/provider/provider.go | 12 +- tenancy/pkg/server/options.go | 41 ++ tenancy/pkg/server/projects.go | 210 ++++++++++ tenancy/pkg/server/server.go | 48 ++- tenancy/pkg/virtual/membership/storage.go | 377 +++++++++++++++++ .../pkg/virtual/membership/storage_test.go | 372 +++++++++++++++++ .../pkg/virtual/selfprojectrequest/storage.go | 219 ++++++++++ .../selfprojectrequest/storage_test.go | 201 +++++++++ .../selftenancyreview/virtualworkspace.go | 59 ++- .../pkg/virtual/selftenantrequest/storage.go | 185 ++++++++ .../virtual/selftenantrequest/storage_test.go | 162 +++++++ tenancy/sdk/apis/tenancy/v1alpha1/doc.go | 4 +- tenancy/sdk/apis/tenancy/v1alpha1/register.go | 6 +- tenancy/sdk/apis/tenancy/v1alpha1/types.go | 157 +++++++ .../tenancy/v1alpha1/zz_generated_deepcopy.go | 118 ++++++ tenancy/test/e2e/fixture_test.go | 2 +- tenancy/test/e2e/scenarios_cli_test.go | 38 +- tenancy/test/e2e/scenarios_test.go | 28 +- 55 files changed, 4600 insertions(+), 510 deletions(-) create mode 100644 tenancy/config/apiexport/apiresourceschema-memberships.tenancy.platform.kcp.io.yaml delete mode 100644 tenancy/config/apiexport/apiresourceschema-memberships.yaml create mode 100644 tenancy/config/apiexport/apiresourceschema-projects.tenancy.platform.kcp.io.yaml delete mode 100644 tenancy/config/apiexport/apiresourceschema-projects.yaml create mode 100644 tenancy/config/apiexport/apiresourceschema-tenants.tenancy.platform.kcp.io.yaml delete mode 100644 tenancy/config/apiexport/apiresourceschema-tenants.yaml create mode 100644 tenancy/pkg/cli/memberships.go create mode 100644 tenancy/pkg/cli/review_test.go create mode 100644 tenancy/pkg/cli/seed.go create mode 100644 tenancy/pkg/cli/selection.go create mode 100644 tenancy/pkg/cli/user.go create mode 100644 tenancy/pkg/clicontext/context.go create mode 100644 tenancy/pkg/provider/clusters.go create mode 100644 tenancy/pkg/server/projects.go create mode 100644 tenancy/pkg/virtual/membership/storage.go create mode 100644 tenancy/pkg/virtual/membership/storage_test.go create mode 100644 tenancy/pkg/virtual/selfprojectrequest/storage.go create mode 100644 tenancy/pkg/virtual/selfprojectrequest/storage_test.go create mode 100644 tenancy/pkg/virtual/selftenantrequest/storage.go create mode 100644 tenancy/pkg/virtual/selftenantrequest/storage_test.go diff --git a/access/pkg/server/server.go b/access/pkg/server/server.go index 018468a..7923b77 100644 --- a/access/pkg/server/server.go +++ b/access/pkg/server/server.go @@ -176,8 +176,7 @@ func Run(ctx context.Context, o *Options) error { if err != nil && !errors.Is(err, context.Canceled) { return fmt.Errorf("rbac provider failed: %w", err) } - <-serveErr - return nil + return <-serveErr case err := <-serveErr: return err } diff --git a/tenancy/README.md b/tenancy/README.md index 1407748..e25e17e 100644 --- a/tenancy/README.md +++ b/tenancy/README.md @@ -47,7 +47,7 @@ root │ │ │ ├── web ................... WorkspaceType: project │ │ APIBinding tenancy-access ... from the WorkspaceType - │ │ ClusterRole tenancy.contrib.kcp.io:role:admin + │ │ ClusterRole tenancy.platform.kcp.io:role:admin │ │ ClusterRoleBinding ...:membership:alice-admin │ │ Namespace "default" ... created by the operator │ │ @@ -203,6 +203,14 @@ run it twice and the second run is a no-op. Quote `"$KUBECONFIG"` — unset and unquoted, the shell drops the argument and `--kubeconfig` swallows the next flag, giving the baffling `load kubeconfig: stat --workspace-path`. +Platform administrators — whoever creates and deletes Tenants — are named +here too: `--platform-admin-user` and `--platform-admin-group` (both +repeatable) bind them to `tenancy.platform.kcp.io:platform-admin` in the +store, a role that may enter it and manage Tenants and nothing else. The +binding holds exactly the identities of the latest run, so dropping one +from the flags revokes it. In production, name a group your identity +provider asserts rather than individual users. + ### 5. Run the operator ```sh @@ -304,7 +312,7 @@ Workspace names are DNS labels; display names are arbitrary UTF-8. The - `slug` (default): lowercase the display name, collapse everything else to dashes ("Acme Corp" → `acme-corp`). On collision with a workspace owned by a different object, fall back to the slug plus a hash of the object's UID. - Ownership is tracked with a `tenancy.contrib.kcp.io/owner-uid` label, so + Ownership is tracked with a `tenancy.kcp.hub/owner-uid` label, so reconciles converge without storing decisions anywhere. - `uid`: always name by UID hash. Opaque, but immune to display-name games. @@ -317,7 +325,7 @@ always proposes the same candidates. front-proxy: ``` -POST /services/tenancy/apis/tenancy.contrib.kcp.io/v1alpha1/selftenancyreviews +POST /services/tenancy/apis/tenancy.platform.kcp.io/v1alpha1/selftenancyreviews ``` The caller POSTs an empty object; the answer lists their tenants with @@ -410,8 +418,12 @@ is for a self-signed local serving certificate; in a deployment pass `--certificate-authority` instead. `kubeconfig` is the other half of a login: it asks the virtual workspace -what the caller can reach and writes one context per tenant and per -project, each pointing at that workspace's own URL. There is still no user +what the caller can reach and writes one context per **project**, each +pointing at that workspace's own URL. Projects only, because a tenant +workspace is where this system keeps its own records — a Membership +materializes RBAC in that tenant's projects, never in the tenant itself, +so no member can enter it and a context for it would only ever answer +`Forbidden`. There is still no user registry to enrol into — `login` obtains a credential, it does not create an identity. Issuing identities belongs to your provider, and a `Membership` only records what one may do. @@ -471,8 +483,8 @@ PKI=$PWD/pki # or tenancy/.e2e/pki # ask who you are: curl -ks --cert "$PKI/alice.crt" --key "$PKI/alice.key" \ -X POST -H 'Content-Type: application/json' \ - -d '{"apiVersion":"tenancy.contrib.kcp.io/v1alpha1","kind":"SelfTenancyReview"}' \ - https://localhost:9445/services/tenancy/apis/tenancy.contrib.kcp.io/v1alpha1/selftenancyreviews + -d '{"apiVersion":"tenancy.platform.kcp.io/v1alpha1","kind":"SelfTenancyReview"}' \ + https://localhost:9445/services/tenancy/apis/tenancy.platform.kcp.io/v1alpha1/selftenancyreviews # ...and whether the directory is being fed at all: curl -ks --cert "$PKI/alice.crt" --key "$PKI/alice.key" \ @@ -490,6 +502,15 @@ Reading the answers: - `403 ... authentication required` means no certificate was presented at all; the review is only served to an authenticated caller. +## Regenerating the schemas + +The `apiresourceschema-*.yaml` assets are generated from the Go types by +`make generate` (controller-gen + kcp's `apigen`; see +[../hack/update-apiresourceschemas.sh](../hack/update-apiresourceschemas.sh)). +After changing anything under `sdk/apis/`, run it and commit the result — +and if a schema's name changed, update `ExportsOrder` in +[config/apiexport/bootstrap.go](config/apiexport/bootstrap.go). + ## Testing From the repository root: @@ -541,14 +562,21 @@ SelfTenancyReview scenarios authenticate with. identity exists because your IdP issued it a credential, and a `Membership` names it verbatim. A typo in a subject name is not an error, it is a grant nobody holds. -6. **There is no tenant self-service.** The virtual workspace serves - `SelfTenancyReview` and nothing else, so Projects and Memberships are - written straight to kcp by someone holding an admin kubeconfig — - `tenancyctl` included. A tenant cannot manage their own projects, - because the tier those objects live in names no tenant identity. The - intended shape is for those writes to arrive through the virtual - workspace, which would hold the only credential into that tier and - could enforce guards a direct write bypasses. +6. **Self-service is narrow, and mediated.** Besides `SelfTenancyReview`, + the virtual workspace accepts exactly three writes, each performed with + its own credential into the tenant tier rather than a grant to the + caller: + - `SelfTenantRequest` gives a caller their first tenant, with the + caller as its admin. It is off unless the deployment passes + `--self-service-tenants`, and `--self-service-tenant-groups` limits it + to groups the identity provider asserts. + - `SelfProjectRequest` creates a project in a tenant the caller + administers. The caller names the project and nothing else. + - `memberships` lists, grants and revokes access in tenants the caller + administers. + + Anything else — deleting a tenant or project, renaming one — is still + written straight to kcp by someone holding an admin kubeconfig. 7. **The operator is not an administrator, and that is load-bearing.** It holds no admin client; every write goes through one of the four exports, so its reach is exactly their claims. The flip side is that a workspace diff --git a/tenancy/cmd/init.go b/tenancy/cmd/init.go index dad63a7..ea25182 100644 --- a/tenancy/cmd/init.go +++ b/tenancy/cmd/init.go @@ -41,6 +41,8 @@ func newInitCommand() *cobra.Command { workspaceType string serverUsers []string serverGroups []string + adminUsers []string + adminGroups []string timeout time.Duration ) @@ -109,10 +111,17 @@ root down. Idempotent: safe to run on every pod start and every upgrade.`, if err != nil { return fmt.Errorf("resolve workspace path %s: %w", storePath, err) } - if err := bootstrap.BindStore(ctx, storeCfg, result); err != nil { + if err := bootstrap.BindStore(ctx, storeCfg, result, bootstrap.Options{ + ServerUsers: serverUsers, + ServerGroups: serverGroups, + }); err != nil { return fmt.Errorf("bind the Tenant API into %s: %w", storePath, err) } - logger.Info("tenant store ready", "workspace", storePath) + if err := bootstrap.GrantPlatformAdmins(ctx, storeCfg, adminUsers, adminGroups); err != nil { + return fmt.Errorf("grant platform admins in %s: %w", storePath, err) + } + logger.Info("tenant store ready", "workspace", storePath, + "platformAdminUsers", adminUsers, "platformAdminGroups", adminGroups) } if tenantsWorkspace != "" { tenantsPath, err = accessbootstrap.JoinWorkspacePath(workspacePrefix, tenantsWorkspace) @@ -187,6 +196,11 @@ root down. Idempotent: safe to run on every pod start and every upgrade.`, "or the virtual workspace does not run as this bootstrap's own credential.") cmd.Flags().StringSliceVar(&serverGroups, "server-group", nil, "Additional Group to grant the server role to, repeatable.") + cmd.Flags().StringSliceVar(&adminUsers, "platform-admin-user", nil, + "User who may manage Tenants in the store workspace, repeatable. Bound to a role "+ + "that allows exactly that; anyone left off the list on a later run loses it.") + cmd.Flags().StringSliceVar(&adminGroups, "platform-admin-group", nil, + "Group, as the identity provider asserts it, whose members may manage Tenants, repeatable.") cmd.Flags().DurationVar(&timeout, "timeout", 3*time.Minute, "Overall time budget for installing and verifying.") diff --git a/tenancy/cmd/root.go b/tenancy/cmd/root.go index ff98c90..85d8f36 100644 --- a/tenancy/cmd/root.go +++ b/tenancy/cmd/root.go @@ -25,6 +25,8 @@ import ( ctrllog "sigs.k8s.io/controller-runtime/pkg/log" "k8s.io/klog/v2" + + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/pkg/cli" ) // Execute runs the tenancy binary. @@ -45,6 +47,9 @@ func Execute() error { root.AddCommand(newInitCommand()) root.AddCommand(newOperatorCommand()) root.AddCommand(newVirtualWorkspaceCommand()) + // seed is shared with the CLI: one idempotent command any environment + // (Tilt, demos, CI) uses to converge on baseline tenancy data. + root.AddCommand(cli.NewSeedCommand()) return root.Execute() } diff --git a/tenancy/config/apiexport/apiexport-platform.yaml b/tenancy/config/apiexport/apiexport-platform.yaml index 8ab64bf..cbad10f 100644 --- a/tenancy/config/apiexport/apiexport-platform.yaml +++ b/tenancy/config/apiexport/apiexport-platform.yaml @@ -10,7 +10,7 @@ metadata: spec: resources: - name: tenants - group: tenancy.contrib.kcp.io - schema: v1alpha1.tenants.tenancy.contrib.kcp.io + group: tenancy.platform.kcp.io + schema: v260926-3d181e5.tenants.tenancy.platform.kcp.io storage: crd: {} diff --git a/tenancy/config/apiexport/apiexport-tenancy.yaml b/tenancy/config/apiexport/apiexport-tenancy.yaml index 47219ae..1989d8c 100644 --- a/tenancy/config/apiexport/apiexport-tenancy.yaml +++ b/tenancy/config/apiexport/apiexport-tenancy.yaml @@ -10,12 +10,12 @@ metadata: spec: resources: - name: projects - group: tenancy.contrib.kcp.io - schema: v1alpha1.projects.tenancy.contrib.kcp.io + group: tenancy.platform.kcp.io + schema: v260924-7813b03.projects.tenancy.platform.kcp.io storage: crd: {} - name: memberships - group: tenancy.contrib.kcp.io - schema: v1alpha1.memberships.tenancy.contrib.kcp.io + group: tenancy.platform.kcp.io + schema: v260924-7813b03.memberships.tenancy.platform.kcp.io storage: crd: {} diff --git a/tenancy/config/apiexport/apiresourceschema-memberships.tenancy.platform.kcp.io.yaml b/tenancy/config/apiexport/apiresourceschema-memberships.tenancy.platform.kcp.io.yaml new file mode 100644 index 0000000..970eff6 --- /dev/null +++ b/tenancy/config/apiexport/apiresourceschema-memberships.tenancy.platform.kcp.io.yaml @@ -0,0 +1,101 @@ +apiVersion: apis.kcp.io/v1alpha1 +kind: APIResourceSchema +metadata: + name: v260924-7813b03.memberships.tenancy.platform.kcp.io +spec: + group: tenancy.platform.kcp.io + names: + kind: Membership + listKind: MembershipList + plural: memberships + singular: membership + scope: Cluster + versions: + - name: v1alpha1 + schema: + description: |- + Membership grants one subject one role in one tenant, or in one project + of that tenant. The operator materializes it as RBAC in the target + workspace; deleting the Membership removes that RBAC again. + properties: + apiVersion: + description: |- + APIVersion defines the versioned schema of this representation of an object. + Servers should convert recognized schemas to the latest internal value, and + may reject unrecognized values. + More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + type: string + kind: + description: |- + Kind is a string value representing the REST resource this object represents. + Servers may infer this from the endpoint the client submits requests to. + Cannot be updated. + In CamelCase. + More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + type: string + metadata: + type: object + spec: + description: MembershipSpec is the desired state of a Membership. + properties: + project: + description: |- + Project optionally narrows the grant to one project of the tenant. + Empty means the grant applies to the tenant's workspace, which every + project workspace nests under. + type: string + role: + description: 'Role is the access level granted: view, edit or admin.' + enum: + - view + - edit + - admin + type: string + subject: + description: Subject is who the grant is for. + properties: + kind: + description: Kind is User or Group. + enum: + - User + - Group + type: string + name: + description: |- + Name is the username or group name, compared verbatim against the + identity kcp authenticates. No issuer prefixes are added or stripped + here; the deployment's authentication configuration must agree with + kcp's. + type: string + required: + - kind + - name + type: object + tenant: + description: Tenant names the Tenant (in the same workspace) the grant + applies to. + type: string + required: + - role + - subject + - tenant + type: object + status: + description: MembershipStatus is the observed state of a Membership. + properties: + message: + type: string + phase: + description: |- + Phase describes where a tenancy object is in its lifecycle. It is a + coarse, human-first signal; Message carries the detail when a phase is + not Ready. + type: string + type: object + required: + - spec + type: object + served: true + storage: true + subresources: + status: {} diff --git a/tenancy/config/apiexport/apiresourceschema-memberships.yaml b/tenancy/config/apiexport/apiresourceschema-memberships.yaml deleted file mode 100644 index 973e396..0000000 --- a/tenancy/config/apiexport/apiresourceschema-memberships.yaml +++ /dev/null @@ -1,88 +0,0 @@ -apiVersion: apis.kcp.io/v1alpha1 -kind: APIResourceSchema -metadata: - name: v1alpha1.memberships.tenancy.contrib.kcp.io -spec: - group: tenancy.contrib.kcp.io - names: - kind: Membership - listKind: MembershipList - plural: memberships - singular: membership - scope: Cluster - versions: - - name: v1alpha1 - served: true - storage: true - subresources: - status: {} - schema: - description: | - Membership grants one subject one role in one tenant, or in one - project of that tenant. The operator materializes it as RBAC in - the target workspace; deleting the Membership removes that RBAC - again. - type: object - properties: - apiVersion: - type: string - kind: - type: string - metadata: - type: object - spec: - type: object - required: - - subject - - role - - tenant - properties: - subject: - description: Who the grant is for. - type: object - required: - - kind - - name - properties: - kind: - description: User or Group. - type: string - enum: - - User - - Group - name: - description: | - Username or group name, compared verbatim against - the identity kcp authenticates. - type: string - minLength: 1 - role: - description: Access level granted. - type: string - enum: - - view - - edit - - admin - tenant: - description: | - Name of the Tenant (in the same workspace) the grant - applies to. - type: string - minLength: 1 - project: - description: | - Optionally narrows the grant to one project of the - tenant. Empty means the grant applies to the tenant's - workspace, which every project workspace nests under. - type: string - status: - type: object - properties: - phase: - description: Pending, Ready or Error. - type: string - message: - description: Detail when phase is not Ready. - type: string - required: - - spec diff --git a/tenancy/config/apiexport/apiresourceschema-projects.tenancy.platform.kcp.io.yaml b/tenancy/config/apiexport/apiresourceschema-projects.tenancy.platform.kcp.io.yaml new file mode 100644 index 0000000..8b3caf6 --- /dev/null +++ b/tenancy/config/apiexport/apiresourceschema-projects.tenancy.platform.kcp.io.yaml @@ -0,0 +1,89 @@ +apiVersion: apis.kcp.io/v1alpha1 +kind: APIResourceSchema +metadata: + name: v260924-7813b03.projects.tenancy.platform.kcp.io +spec: + group: tenancy.platform.kcp.io + names: + kind: Project + listKind: ProjectList + plural: projects + singular: project + scope: Cluster + versions: + - name: v1alpha1 + schema: + description: |- + Project asks for a workspace nested under a tenant's workspace. Projects + are the unit teams actually work in; tenant-wide Memberships reach every + project, project Memberships reach one. + properties: + apiVersion: + description: |- + APIVersion defines the versioned schema of this representation of an object. + Servers should convert recognized schemas to the latest internal value, and + may reject unrecognized values. + More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + type: string + kind: + description: |- + Kind is a string value representing the REST resource this object represents. + Servers may infer this from the endpoint the client submits requests to. + Cannot be updated. + In CamelCase. + More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + type: string + metadata: + type: object + spec: + description: ProjectSpec is the desired state of a Project. + properties: + description: + description: Description is free text for humans. + type: string + displayName: + description: |- + DisplayName is the human name of the project; it seeds the workspace + name the same way a tenant's does. + type: string + tenant: + description: |- + Tenant names the Tenant (in the same workspace) this project belongs + to. The project's workspace is created under that tenant's workspace. + type: string + required: + - displayName + - tenant + type: object + status: + description: ProjectStatus is the observed state of a Project. + properties: + message: + type: string + phase: + description: |- + Phase describes where a tenancy object is in its lifecycle. It is a + coarse, human-first signal; Message carries the detail when a phase is + not Ready. + type: string + url: + description: URL is the direct address of the provisioned workspace. + type: string + workspace: + description: |- + Workspace is the name of the provisioned Workspace object, inside the + tenant's workspace. + type: string + workspaceCluster: + description: |- + WorkspaceCluster is the logical cluster name backing the provisioned + workspace. + type: string + type: object + required: + - spec + type: object + served: true + storage: true + subresources: + status: {} diff --git a/tenancy/config/apiexport/apiresourceschema-projects.yaml b/tenancy/config/apiexport/apiresourceschema-projects.yaml deleted file mode 100644 index ae7f499..0000000 --- a/tenancy/config/apiexport/apiresourceschema-projects.yaml +++ /dev/null @@ -1,72 +0,0 @@ -apiVersion: apis.kcp.io/v1alpha1 -kind: APIResourceSchema -metadata: - name: v1alpha1.projects.tenancy.contrib.kcp.io -spec: - group: tenancy.contrib.kcp.io - names: - kind: Project - listKind: ProjectList - plural: projects - singular: project - scope: Cluster - versions: - - name: v1alpha1 - served: true - storage: true - subresources: - status: {} - schema: - description: | - Project asks for a workspace nested under a tenant's workspace. - Projects are the unit teams actually work in; tenant-wide - Memberships reach every project, project Memberships reach one. - type: object - properties: - apiVersion: - type: string - kind: - type: string - metadata: - type: object - spec: - type: object - required: - - tenant - - displayName - properties: - tenant: - description: | - Name of the Tenant (in the same workspace) this project - belongs to. - type: string - minLength: 1 - displayName: - description: | - Human name of the project; seeds the workspace name the - same way a tenant's does. - type: string - minLength: 1 - description: - description: Free text for humans. - type: string - status: - type: object - properties: - phase: - description: Pending, Ready or Error. - type: string - message: - description: Detail when phase is not Ready. - type: string - workspace: - description: Name of the provisioned Workspace object. - type: string - workspaceCluster: - description: Logical cluster backing the provisioned workspace. - type: string - url: - description: Direct address of the provisioned workspace. - type: string - required: - - spec diff --git a/tenancy/config/apiexport/apiresourceschema-tenants.tenancy.platform.kcp.io.yaml b/tenancy/config/apiexport/apiresourceschema-tenants.tenancy.platform.kcp.io.yaml new file mode 100644 index 0000000..2033b61 --- /dev/null +++ b/tenancy/config/apiexport/apiresourceschema-tenants.tenancy.platform.kcp.io.yaml @@ -0,0 +1,100 @@ +apiVersion: apis.kcp.io/v1alpha1 +kind: APIResourceSchema +metadata: + name: v260926-3d181e5.tenants.tenancy.platform.kcp.io +spec: + group: tenancy.platform.kcp.io + names: + kind: Tenant + listKind: TenantList + plural: tenants + singular: tenant + scope: Cluster + versions: + - name: v1alpha1 + schema: + description: |- + Tenant asks for an isolated kcp workspace for one organizational unit. + The operator provisions a workspace under the organization workspace the + Tenant object lives in and reports it in Status. + properties: + apiVersion: + description: |- + APIVersion defines the versioned schema of this representation of an object. + Servers should convert recognized schemas to the latest internal value, and + may reject unrecognized values. + More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + type: string + kind: + description: |- + Kind is a string value representing the REST resource this object represents. + Servers may infer this from the endpoint the client submits requests to. + Cannot be updated. + In CamelCase. + More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + type: string + metadata: + type: object + spec: + description: TenantSpec is the desired state of a Tenant. + properties: + description: + description: Description is free text for humans. + type: string + displayName: + description: |- + DisplayName is the human name of the tenant. It seeds the workspace + name (subject to the operator's naming strategy) and is returned in + SelfTenancyReview answers. It is not required to be unique. + type: string + firstAdmin: + description: |- + FirstAdmin is an identity granted the admin role on this tenant once + its workspace is ready, as a Membership the operator creates. + + It exists because a tenant nobody administers is unusable, and the + two writes cannot be one: the Membership lives in the tenant's own + workspace, which does not exist when the Tenant is created. Naming + the admin here lets whoever creates the tenant hand it over without + waiting, and is what makes self-service possible — the virtual + workspace sets it to the caller, so a caller cannot make someone + else the admin of a tenant they asked for. + + Empty means nobody is seeded, which is the right answer when an + administrator intends to grant access separately. + type: string + required: + - displayName + type: object + status: + description: TenantStatus is the observed state of a Tenant. + properties: + message: + type: string + phase: + description: |- + Phase describes where a tenancy object is in its lifecycle. It is a + coarse, human-first signal; Message carries the detail when a phase is + not Ready. + type: string + url: + description: URL is the direct address of the provisioned workspace. + type: string + workspace: + description: |- + Workspace is the name of the provisioned Workspace object, in the + same workspace the Tenant lives in. + type: string + workspaceCluster: + description: |- + WorkspaceCluster is the logical cluster name backing the provisioned + workspace. It is the stable address of the tenant's workspace. + type: string + type: object + required: + - spec + type: object + served: true + storage: true + subresources: + status: {} diff --git a/tenancy/config/apiexport/apiresourceschema-tenants.yaml b/tenancy/config/apiexport/apiresourceschema-tenants.yaml deleted file mode 100644 index 694414b..0000000 --- a/tenancy/config/apiexport/apiresourceschema-tenants.yaml +++ /dev/null @@ -1,67 +0,0 @@ -apiVersion: apis.kcp.io/v1alpha1 -kind: APIResourceSchema -metadata: - name: v1alpha1.tenants.tenancy.contrib.kcp.io -spec: - group: tenancy.contrib.kcp.io - names: - kind: Tenant - listKind: TenantList - plural: tenants - singular: tenant - scope: Cluster - versions: - - name: v1alpha1 - served: true - storage: true - subresources: - status: {} - schema: - description: | - Tenant asks for an isolated kcp workspace for one organizational - unit. The tenancy operator provisions a workspace under the - organization workspace this object lives in and reports it in - status. - type: object - properties: - apiVersion: - type: string - kind: - type: string - metadata: - type: object - spec: - type: object - required: - - displayName - properties: - displayName: - description: | - Human name of the tenant. Seeds the workspace name, - subject to the operator's naming strategy. Not required - to be unique. - type: string - minLength: 1 - description: - description: Free text for humans. - type: string - status: - type: object - properties: - phase: - description: Pending, Ready or Error. - type: string - message: - description: Detail when phase is not Ready. - type: string - workspace: - description: Name of the provisioned Workspace object. - type: string - workspaceCluster: - description: Logical cluster backing the provisioned workspace. - type: string - url: - description: Direct address of the provisioned workspace. - type: string - required: - - spec diff --git a/tenancy/config/apiexport/bootstrap.go b/tenancy/config/apiexport/bootstrap.go index 314340f..392e42e 100644 --- a/tenancy/config/apiexport/bootstrap.go +++ b/tenancy/config/apiexport/bootstrap.go @@ -66,9 +66,9 @@ const ( // - the workspace types after the exports they default-bind, so the // references resolve. var ExportsOrder = []string{ - "apiresourceschema-tenants.yaml", - "apiresourceschema-projects.yaml", - "apiresourceschema-memberships.yaml", + "apiresourceschema-tenants.tenancy.platform.kcp.io.yaml", + "apiresourceschema-projects.tenancy.platform.kcp.io.yaml", + "apiresourceschema-memberships.tenancy.platform.kcp.io.yaml", "apiexport-platform.yaml", "apiexport-tenancy.yaml", "apiexport-provisioner.yaml", diff --git a/tenancy/config/apiexport/store-bindings.yaml b/tenancy/config/apiexport/store-bindings.yaml index b7d4cd8..71f671d 100644 --- a/tenancy/config/apiexport/store-bindings.yaml +++ b/tenancy/config/apiexport/store-bindings.yaml @@ -11,5 +11,9 @@ metadata: spec: reference: export: - path: __EXPORTS_PATH__ + # The logical cluster id, not the pretty path: an APIBinding reference + # resolves ids locally on the shard, while pretty paths need the cache + # server's path index — which multi-shard deployments have broken + # before. The WorkspaceTypes reference exports the same way. + path: __EXPORTS_REF__ name: tenancy-platform diff --git a/tenancy/config/apiexport/tenants-bindings.yaml b/tenancy/config/apiexport/tenants-bindings.yaml index fbb561a..c7ed075 100644 --- a/tenancy/config/apiexport/tenants-bindings.yaml +++ b/tenancy/config/apiexport/tenants-bindings.yaml @@ -12,7 +12,11 @@ metadata: spec: reference: export: - path: __EXPORTS_PATH__ + # The logical cluster id, not the pretty path: an APIBinding reference + # resolves ids locally on the shard, while pretty paths need the cache + # server's path index — which multi-shard deployments have broken + # before. The WorkspaceTypes reference exports the same way. + path: __EXPORTS_REF__ name: tenancy-provisioner permissionClaims: - group: tenancy.kcp.io diff --git a/tenancy/config/examples/apibinding-consumer.yaml b/tenancy/config/examples/apibinding-consumer.yaml index 88e64ea..5725087 100644 --- a/tenancy/config/examples/apibinding-consumer.yaml +++ b/tenancy/config/examples/apibinding-consumer.yaml @@ -10,17 +10,17 @@ # hash from the claim on the installed APIExport (init discovered and # injected it there): # -# kubectl get apiexport tenancy.contrib.kcp.io \ +# kubectl get apiexport tenancy.platform.kcp.io \ # -o jsonpath='{.spec.permissionClaims[0].identityHash}' apiVersion: apis.kcp.io/v1alpha2 kind: APIBinding metadata: - name: tenancy.contrib.kcp.io + name: tenancy.platform.kcp.io spec: reference: export: path: root:tenancy:controllers - name: tenancy.contrib.kcp.io + name: tenancy.platform.kcp.io permissionClaims: - group: tenancy.kcp.io resource: workspaces diff --git a/tenancy/pkg/bootstrap/bootstrap.go b/tenancy/pkg/bootstrap/bootstrap.go index 740bb24..a9ed29c 100644 --- a/tenancy/pkg/bootstrap/bootstrap.go +++ b/tenancy/pkg/bootstrap/bootstrap.go @@ -35,7 +35,6 @@ import ( metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" "k8s.io/apimachinery/pkg/apis/meta/v1/unstructured" "k8s.io/apimachinery/pkg/runtime/schema" - "k8s.io/apimachinery/pkg/types" "k8s.io/apimachinery/pkg/util/wait" "k8s.io/apimachinery/pkg/util/yaml" "k8s.io/client-go/discovery" @@ -44,6 +43,7 @@ import ( "k8s.io/client-go/kubernetes" "k8s.io/client-go/rest" "k8s.io/client-go/restmapper" + "k8s.io/client-go/util/retry" "k8s.io/klog/v2" "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/config/apiexport" @@ -87,12 +87,6 @@ const ( DefaultTenantsWorkspace = "tenants" ) -// NudgeAnnotation is bumped on an endpoint slice to make kcp recompute its -// URLs. kcp's URLs controller runs when the slice object is reconciled, and -// a consumer binding the export is not a slice event, so a slice created -// before its first consumer would otherwise stay URL-less indefinitely. -const NudgeAnnotation = tenancyv1alpha1.GroupName + "/nudged-at" - // Options configures Bootstrap. type Options struct { // ServerUsers and ServerGroups are additional identities granted the @@ -174,11 +168,27 @@ func Bootstrap(ctx context.Context, cfg *rest.Config, exportsPath string, opts O // BindStore makes the workspace cfg points at the tenant registry: it // binds tenancy-platform, then waits until Tenants are actually servable. -func BindStore(ctx context.Context, cfg *rest.Config, result *Result) error { +func BindStore(ctx context.Context, cfg *rest.Config, result *Result, opts Options) error { if err := applyTier(ctx, cfg, result, apiexport.StoreOrder); err != nil { return err } + // The virtual workspace writes a requested tenant here, through the + // platform export — which needs no standing in this workspace. What it + // does need is to know which logical cluster this is, because an + // export's virtual workspace addresses clusters and not paths. That is + // the whole grant: enter, and read the one object that says where you + // are. + if len(opts.ServerUsers)+len(opts.ServerGroups) > 0 { + kube, err := kubernetes.NewForConfig(cfg) + if err != nil { + return fmt.Errorf("build kubernetes client: %w", err) + } + if err := applyStoreLocator(ctx, kube, opts.ServerUsers, opts.ServerGroups); err != nil { + return fmt.Errorf("grant the server identities the store locator role: %w", err) + } + } + dyn, err := dynamic.NewForConfig(cfg) if err != nil { return fmt.Errorf("build dynamic client: %w", err) @@ -335,15 +345,42 @@ func applyManifests(ctx context.Context, dyn dynamic.Interface, mapper *restmapp client := dyn.Resource(mapping.Resource) if _, err := client.Create(ctx, &obj, metav1.CreateOptions{}); err != nil { + // A hand-bound tier can land on a different shard than the + // exports, and the `bind` RBAC applied moments ago reaches that + // shard through cache replication — so a Forbidden here is + // usually a propagation lag, not a verdict. Retry it briefly. + if apierrors.IsForbidden(err) && gvk.Kind == "APIBinding" { + retryErr := wait.PollUntilContextTimeout(ctx, 3*time.Second, 2*time.Minute, false, func(ctx context.Context) (bool, error) { + _, err := client.Create(ctx, &obj, metav1.CreateOptions{}) + if err == nil || apierrors.IsAlreadyExists(err) { + return true, nil + } + if apierrors.IsForbidden(err) { + return false, nil + } + return false, err + }) + if retryErr != nil { + return fmt.Errorf("create %s %s (after retrying propagation of the bind grant): %w", gvk.Kind, obj.GetName(), retryErr) + } + continue + } if !apierrors.IsAlreadyExists(err) { return fmt.Errorf("create %s %s: %w", gvk.Kind, obj.GetName(), err) } - existing, err := client.Get(ctx, obj.GetName(), metav1.GetOptions{}) + // kcp reconciles some of these objects concurrently (it creates + // and keeps updating a default APIExportEndpointSlice per + // export), so a single get+update can 409. Re-read and retry. + err := retry.RetryOnConflict(retry.DefaultRetry, func() error { + existing, err := client.Get(ctx, obj.GetName(), metav1.GetOptions{}) + if err != nil { + return err + } + obj.SetResourceVersion(existing.GetResourceVersion()) + _, err = client.Update(ctx, &obj, metav1.UpdateOptions{}) + return err + }) if err != nil { - return fmt.Errorf("get existing %s %s: %w", gvk.Kind, obj.GetName(), err) - } - obj.SetResourceVersion(existing.GetResourceVersion()) - if _, err := client.Update(ctx, &obj, metav1.UpdateOptions{}); err != nil { // Some kcp objects reject spec updates (APIResourceSchemas // are immutable); existing is as good as applied. if apierrors.IsInvalid(err) || apierrors.IsForbidden(err) { @@ -355,77 +392,132 @@ func applyManifests(ctx context.Context, dyn dynamic.Interface, mapper *restmapp } } -// applyServerIdentity grants the server role to the given identities. -func applyServerIdentity(ctx context.Context, kube kubernetes.Interface, users, groups []string) error { +// applyStoreLocator grants the least a server needs to find out which +// logical cluster the store workspace is: kcp's workspace gate, and a read +// of the LogicalCluster that names it. Deliberately not the Tenant API — +// tenants are written through the platform export, not through here. +func applyStoreLocator(ctx context.Context, kube kubernetes.Interface, users, groups []string) error { role := &rbacv1.ClusterRole{ - ObjectMeta: metav1.ObjectMeta{Name: tenancyv1alpha1.GroupName + ":server"}, + ObjectMeta: metav1.ObjectMeta{Name: tenancyv1alpha1.GroupName + ":store-locator"}, Rules: []rbacv1.PolicyRule{ { Verbs: []string{"access"}, NonResourceURLs: []string{"/"}, }, { - APIGroups: []string{"apis.kcp.io"}, - Resources: []string{"apiexports", "apiexportendpointslices", "apibindings"}, - Verbs: []string{"get", "list", "watch"}, + APIGroups: []string{"core.kcp.io"}, + Resources: []string{"logicalclusters"}, + Verbs: []string{"get"}, }, + }, + } + return applyRoleAndBinding(ctx, kube, role, users, groups) +} + +// GrantPlatformAdmins makes the given identities administrators of the +// tenant registry cfg points at: they may enter it and manage Tenants, +// and nothing else. It is applied even with no identities, so that +// dropping someone from the list revokes them. +func GrantPlatformAdmins(ctx context.Context, cfg *rest.Config, users, groups []string) error { + kube, err := kubernetes.NewForConfig(cfg) + if err != nil { + return fmt.Errorf("build kubernetes client: %w", err) + } + role := &rbacv1.ClusterRole{ + ObjectMeta: metav1.ObjectMeta{Name: tenancyv1alpha1.GroupName + ":platform-admin"}, + Rules: []rbacv1.PolicyRule{ { - // The operator nudges a URL-less endpoint slice to work - // around kcp not reconciling slices on new bindings. - APIGroups: []string{"apis.kcp.io"}, - Resources: []string{"apiexportendpointslices"}, - Verbs: []string{"patch"}, + Verbs: []string{"access"}, + NonResourceURLs: []string{"/"}, }, { - APIGroups: []string{"apis.kcp.io"}, - Resources: []string{"apiexports/content"}, - Verbs: []string{"*"}, + APIGroups: []string{tenancyv1alpha1.GroupName}, + Resources: []string{"tenants"}, + Verbs: []string{"get", "list", "watch", "create", "update", "patch", "delete"}, }, }, } + return applyRoleAndBinding(ctx, kube, role, users, groups) +} + +// applyRoleAndBinding creates or updates a ClusterRole and a binding of the +// same name holding exactly the given subjects. Updates change only rules, +// subjects and roleRef on the stored object: kcp annotates these objects +// itself, and writing back a copy without its internal.kcp.io annotations +// is rejected as modifying reserved metadata. +func applyRoleAndBinding(ctx context.Context, kube kubernetes.Interface, role *rbacv1.ClusterRole, users, groups []string) error { if _, err := kube.RbacV1().ClusterRoles().Create(ctx, role, metav1.CreateOptions{}); err != nil { if !apierrors.IsAlreadyExists(err) { return err } - if _, err := kube.RbacV1().ClusterRoles().Update(ctx, role, metav1.UpdateOptions{}); err != nil { + if err := retry.RetryOnConflict(retry.DefaultRetry, func() error { + existing, err := kube.RbacV1().ClusterRoles().Get(ctx, role.Name, metav1.GetOptions{}) + if err != nil { + return err + } + existing.Rules = role.Rules + _, err = kube.RbacV1().ClusterRoles().Update(ctx, existing, metav1.UpdateOptions{}) + return err + }); err != nil { return err } } - binding := &rbacv1.ClusterRoleBinding{ - ObjectMeta: metav1.ObjectMeta{Name: tenancyv1alpha1.GroupName + ":server"}, - RoleRef: rbacv1.RoleRef{ - APIGroup: rbacv1.GroupName, - Kind: "ClusterRole", - Name: role.Name, - }, - } + subjects := make([]rbacv1.Subject, 0, len(users)+len(groups)) for _, u := range users { - binding.Subjects = append(binding.Subjects, rbacv1.Subject{ - APIGroup: rbacv1.GroupName, Kind: "User", Name: u, - }) + subjects = append(subjects, rbacv1.Subject{Kind: rbacv1.UserKind, APIGroup: rbacv1.GroupName, Name: u}) } for _, g := range groups { - binding.Subjects = append(binding.Subjects, rbacv1.Subject{ - APIGroup: rbacv1.GroupName, Kind: "Group", Name: g, - }) + subjects = append(subjects, rbacv1.Subject{Kind: rbacv1.GroupKind, APIGroup: rbacv1.GroupName, Name: g}) + } + + binding := &rbacv1.ClusterRoleBinding{ + ObjectMeta: metav1.ObjectMeta{Name: role.Name}, + RoleRef: rbacv1.RoleRef{APIGroup: rbacv1.GroupName, Kind: "ClusterRole", Name: role.Name}, + Subjects: subjects, } if _, err := kube.RbacV1().ClusterRoleBindings().Create(ctx, binding, metav1.CreateOptions{}); err != nil { if !apierrors.IsAlreadyExists(err) { return err } - existing, err := kube.RbacV1().ClusterRoleBindings().Get(ctx, binding.Name, metav1.GetOptions{}) - if err != nil { - return err - } - binding.ResourceVersion = existing.ResourceVersion - if _, err := kube.RbacV1().ClusterRoleBindings().Update(ctx, binding, metav1.UpdateOptions{}); err != nil { + return retry.RetryOnConflict(retry.DefaultRetry, func() error { + existing, err := kube.RbacV1().ClusterRoleBindings().Get(ctx, binding.Name, metav1.GetOptions{}) + if err != nil { + return err + } + existing.Subjects = subjects + existing.RoleRef = binding.RoleRef + _, err = kube.RbacV1().ClusterRoleBindings().Update(ctx, existing, metav1.UpdateOptions{}) return err - } + }) } return nil } +// applyServerIdentity grants the server role to the given identities. +func applyServerIdentity(ctx context.Context, kube kubernetes.Interface, users, groups []string) error { + role := &rbacv1.ClusterRole{ + ObjectMeta: metav1.ObjectMeta{Name: tenancyv1alpha1.GroupName + ":server"}, + Rules: []rbacv1.PolicyRule{ + { + Verbs: []string{"access"}, + NonResourceURLs: []string{"/"}, + }, + { + APIGroups: []string{"apis.kcp.io"}, + Resources: []string{"apiexports", "apiexportendpointslices", "apibindings"}, + Verbs: []string{"get", "list", "watch"}, + }, + { + APIGroups: []string{"apis.kcp.io"}, + Resources: []string{"apiexports/content"}, + Verbs: []string{"*"}, + }, + }, + } + return applyRoleAndBinding(ctx, kube, role, users, groups) +} + // WaitForEndpointSliceURLs reports the virtual workspace URLs one endpoint // slice has published. kcp fills a slice only once a workspace binds the // export, so this is worth calling after binding, not before. An empty @@ -445,14 +537,6 @@ func waitForEndpointSlice(ctx context.Context, dyn dynamic.Interface, sliceName ctx, cancel := context.WithTimeout(ctx, 30*time.Second) defer cancel() - // See NudgeAnnotation: without a write to the slice, the URLs for a - // freshly bound export never appear and this wait is 30 seconds of - // nothing. - patch := fmt.Sprintf(`{"metadata":{"annotations":{%q:%q}}}`, NudgeAnnotation, time.Now().UTC().Format(time.RFC3339)) - if _, err := dyn.Resource(endpointSliceGVR).Patch(ctx, sliceName, types.MergePatchType, []byte(patch), metav1.PatchOptions{}); err != nil { - logger.V(2).Info("could not nudge the endpoint slice", "slice", sliceName, "error", err.Error()) - } - var urls []string err := wait.PollUntilContextCancel(ctx, 2*time.Second, true, func(ctx context.Context) (bool, error) { slice, err := dyn.Resource(endpointSliceGVR).Get(ctx, sliceName, metav1.GetOptions{}) diff --git a/tenancy/pkg/cli/login.go b/tenancy/pkg/cli/login.go index 24e3032..7c3ebb4 100644 --- a/tenancy/pkg/cli/login.go +++ b/tenancy/pkg/cli/login.go @@ -37,6 +37,8 @@ import ( "github.com/spf13/cobra" "golang.org/x/oauth2" + + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/pkg/clicontext" ) // Login obtains an ID token — the JWT every other command presents — and @@ -140,6 +142,13 @@ func anyCachedToken(path string) (string, bool) { return found, found != "" } +// CachedToken returns the token `login` cached in the default location, or +// "" when there is none, it expired, or more than one provider is cached. +func CachedToken() string { + token, _ := anyCachedToken(defaultTokenCachePath()) + return token +} + // oidcEndpoints is the slice of the discovery document this needs. type oidcEndpoints struct { Issuer string `json:"issuer"` @@ -197,17 +206,20 @@ func httpClientFor(caFile string, insecure bool) (*http.Client, error) { func newLoginCommand() *cobra.Command { var ( - issuer string - clientID string - clientSecret string - scopes []string - username string - passwordStdin bool - password string - listen string - caFile string - insecure bool - cachePath string + issuer string + clientID string + clientSecret string + scopes []string + username string + passwordStdin bool + password string + listen string + caFile string + insecure bool + cachePath string + server string + serverCAFile string + serverInsecure bool ) cmd := &cobra.Command{ @@ -305,6 +317,24 @@ a Membership has to name.`, if !token.Expiry.IsZero() { fmt.Printf("expires %s\n", token.Expiry.Local().Format(time.RFC1123)) } + + // Remember the server, so nothing after this has to be told + // where kcp is. Every virtual workspace hangs off it under + // /services/, so one address covers them all. + if server != "" { + if err := clicontext.Update(func(c *clicontext.Context) { + c.Server = strings.TrimSuffix(server, "/") + c.CertificateAuthority = serverCAFile + c.Insecure = serverInsecure + }); err != nil { + return err + } + fmt.Printf("server %s saved in %s\n", strings.TrimSuffix(server, "/"), clicontext.Where()) + } else if clicontext.Load().Server == "" { + fmt.Fprintf(os.Stderr, + "\nno server known yet: pass --url https://:8443 to store one, "+ + "or give each command --url\n") + } return nil }, } @@ -329,6 +359,14 @@ a Membership has to name.`, "Do not verify the issuer's certificate. For a local provider only.") cmd.Flags().StringVar(&cachePath, "token-cache", defaultTokenCachePath(), "File the token is cached in.") + cmd.Flags().StringVar(&server, "url", "", + "Base URL of the kcp front-proxy, e.g. https://kcp.example.com:8443. Remembered in "+ + clicontext.Where()+" so later commands need no --url: every virtual workspace "+ + "answers on it under /services/.") + cmd.Flags().StringVar(&serverCAFile, "server-certificate-authority", "", + "CA bundle that verifies the server's certificate. Remembered with --url.") + cmd.Flags().BoolVar(&serverInsecure, "server-insecure-skip-tls-verify", false, + "Do not verify the server's certificate. For local testing only. Remembered with --url.") return cmd } diff --git a/tenancy/pkg/cli/membership.go b/tenancy/pkg/cli/membership.go index 34e55ea..650dc6f 100644 --- a/tenancy/pkg/cli/membership.go +++ b/tenancy/pkg/cli/membership.go @@ -17,6 +17,7 @@ limitations under the License. package cli import ( + "context" "fmt" "github.com/spf13/cobra" @@ -69,50 +70,7 @@ identity provider's job, and this only records what that identity may do.`, if asGroup { kind = tenancyv1alpha1.SubjectKindGroup } - subject := args[0] - name := membershipName(subject, tenant, project) - - membership := &tenancyv1alpha1.Membership{ - ObjectMeta: metav1.ObjectMeta{Name: name}, - Spec: tenancyv1alpha1.MembershipSpec{ - Subject: tenancyv1alpha1.Subject{Kind: kind, Name: subject}, - Role: tenancyv1alpha1.Role(role), - Tenant: tenant, - Project: project, - }, - } - - err = c.Create(cmd.Context(), membership) - if apierrors.IsAlreadyExists(err) { - // The name is derived from (subject, tenant, project), so - // an existing object is the same grant: re-granting is a - // role change, not a duplicate. - var existing tenancyv1alpha1.Membership - if err := c.Get(cmd.Context(), client.ObjectKey{Name: name}, &existing); err != nil { - return fmt.Errorf("get existing membership: %w", err) - } - if existing.Spec.Role == tenancyv1alpha1.Role(role) { - fmt.Printf("membership/%s already grants %s\n", name, role) - return nil - } - previous := existing.Spec.Role - existing.Spec.Role = tenancyv1alpha1.Role(role) - if err := c.Update(cmd.Context(), &existing); err != nil { - return fmt.Errorf("update membership: %w", err) - } - fmt.Printf("membership/%s changed from %s to %s\n", name, previous, role) - return nil - } - if err != nil { - return fmt.Errorf("create membership: %w", err) - } - - scope := "every project of tenant " + tenant - if project != "" { - scope = "project " + project + " of tenant " + tenant - } - fmt.Printf("membership/%s created: %s %q is %s in %s\n", name, kind, subject, role, scope) - return nil + return upsertMembership(cmd.Context(), c, kind, args[0], tenancyv1alpha1.Role(role), tenant, project) }, } o.addFlags(cmd) @@ -132,6 +90,7 @@ func newRevokeCommand() *cobra.Command { tenant string project string list bool + asGroup bool ) cmd := &cobra.Command{ @@ -172,7 +131,7 @@ With --list it prints every grant instead of removing one.`, return nil } - name := membershipName(args[0], tenant, project) + name := membershipName(subjectKind(asGroup), args[0], tenant, project) membership := &tenancyv1alpha1.Membership{ObjectMeta: metav1.ObjectMeta{Name: name}} if err := c.Delete(cmd.Context(), membership); err != nil { if apierrors.IsNotFound(err) { @@ -188,6 +147,54 @@ With --list it prints every grant instead of removing one.`, cmd.Flags().StringVar(&tenant, "tenant", "", "Tenant whose grants to list or revoke (required).") cmd.Flags().StringVar(&project, "project", "", "Project of the grant, if it was project-scoped.") cmd.Flags().BoolVar(&list, "list", false, "List grants instead of revoking one.") + cmd.Flags().BoolVar(&asGroup, "group", false, "Treat SUBJECT as a group rather than a username.") return cmd } + +// upsertMembership creates a grant, or — because the name is derived from +// (kind, subject, tenant, project), so an existing object IS the same grant — +// updates its role in place. Re-granting is a role change, never a +// duplicate, which is what makes grant and seed idempotent. +func upsertMembership(ctx context.Context, c client.Client, kind tenancyv1alpha1.SubjectKind, subject string, role tenancyv1alpha1.Role, tenant, project string) error { + name := membershipName(kind, subject, tenant, project) + + membership := &tenancyv1alpha1.Membership{ + ObjectMeta: metav1.ObjectMeta{Name: name}, + Spec: tenancyv1alpha1.MembershipSpec{ + Subject: tenancyv1alpha1.Subject{Kind: kind, Name: subject}, + Role: role, + Tenant: tenant, + Project: project, + }, + } + + err := c.Create(ctx, membership) + if apierrors.IsAlreadyExists(err) { + var existing tenancyv1alpha1.Membership + if err := c.Get(ctx, client.ObjectKey{Name: name}, &existing); err != nil { + return fmt.Errorf("get existing membership: %w", err) + } + if existing.Spec.Role == role { + fmt.Printf("membership/%s already grants %s\n", name, role) + return nil + } + previous := existing.Spec.Role + existing.Spec.Role = role + if err := c.Update(ctx, &existing); err != nil { + return fmt.Errorf("update membership: %w", err) + } + fmt.Printf("membership/%s changed from %s to %s\n", name, previous, role) + return nil + } + if err != nil { + return fmt.Errorf("create membership: %w", err) + } + + scope := "every project of tenant " + tenant + if project != "" { + scope = "project " + project + " of tenant " + tenant + } + fmt.Printf("membership/%s created: %s %q is %s in %s\n", name, kind, subject, role, scope) + return nil +} diff --git a/tenancy/pkg/cli/memberships.go b/tenancy/pkg/cli/memberships.go new file mode 100644 index 0000000..156a7f7 --- /dev/null +++ b/tenancy/pkg/cli/memberships.go @@ -0,0 +1,214 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package cli + +import ( + "fmt" + + "github.com/spf13/cobra" + + apierrors "k8s.io/apimachinery/pkg/api/errors" + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + + tenancyv1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1" +) + +// NewMembershipCommand groups the grant lifecycle under one noun: +// `membership` lists, `membership add` grants, `membership remove` +// revokes. +// +// Unlike the user-facing commands, these need a kubeconfig for kcp: a +// Membership lives in its tenant's workspace, which is the record store +// no member can enter, so managing access is an administrator's job by +// construction rather than by a check. +func NewMembershipCommand() *cobra.Command { + cmd := &cobra.Command{ + Use: "membership", + Aliases: []string{"memberships"}, + Short: "List, grant and revoke access to a tenant or project", + Long: `A Membership records what an identity may do, and the operator +materializes it as RBAC in the tenant's project workspaces. + +There is no user registry to enrol anyone into: issuing credentials is +the identity provider's job, and a Membership only names the identity it +already issues. + +Run without a subcommand it lists the grants in the tenant.`, + Args: cobra.NoArgs, + RunE: func(cmd *cobra.Command, _ []string) error { + return cmd.Help() + }, + } + + cmd.AddCommand( + newMembershipListCommand(), + newMembershipAddCommand(), + newMembershipRemoveCommand(), + ) + return cmd +} + +// tenantFlag adds --tenant, defaulting to whatever `use` selected, so the +// admin commands compose with the user-facing ones. +func tenantFlag(cmd *cobra.Command, tenant *string) { + cmd.Flags().StringVar(tenant, "tenant", "", + "Tenant to act on. Defaults to the one `use` selected.") +} + +func newMembershipListCommand() *cobra.Command { + o := &adminOptions{} + var tenant string + + cmd := &cobra.Command{ + Use: "list", + Aliases: []string{"ls"}, + Short: "List the grants in a tenant", + Args: cobra.NoArgs, + RunE: func(cmd *cobra.Command, _ []string) error { + selected, err := selectionFor(tenant, "") + if err != nil { + return err + } + c, err := o.tenantClient(cmd.Context(), selected.Tenant) + if err != nil { + return err + } + var memberships tenancyv1alpha1.MembershipList + if err := c.List(cmd.Context(), &memberships); err != nil { + return fmt.Errorf("list memberships: %w", err) + } + if len(memberships.Items) == 0 { + fmt.Printf("No grants in tenant %s.\n", selected.Tenant) + return nil + } + rows := make([][]string, 0, len(memberships.Items)) + for _, m := range memberships.Items { + rows = append(rows, []string{ + m.Name, string(m.Spec.Subject.Kind), m.Spec.Subject.Name, + string(m.Spec.Role), dash(m.Spec.Project), + string(dashPhase(m.Status.Phase)), + }) + } + table([]string{"NAME", "KIND", "SUBJECT", "ROLE", "PROJECT", "PHASE"}, rows) + return nil + }, + } + o.addFlags(cmd) + tenantFlag(cmd, &tenant) + return cmd +} + +func newMembershipAddCommand() *cobra.Command { + o := &adminOptions{} + var ( + role string + tenant string + project string + asGroup bool + ) + + cmd := &cobra.Command{ + Use: "add SUBJECT", + Aliases: []string{"grant"}, + Short: "Grant a user or group a role", + Long: `Grant access by creating a Membership. + +SUBJECT is matched verbatim against the identity kcp authenticates: the +CommonName of a client certificate, or the username an OIDC token maps +to. With --group it is matched against the caller's groups instead. + +Without --project the grant is tenant-wide and reaches every project, +including ones created later. Re-running with a different --role changes +the grant in place rather than adding a second one.`, + Args: cobra.ExactArgs(1), + RunE: func(cmd *cobra.Command, args []string) error { + switch tenancyv1alpha1.Role(role) { + case tenancyv1alpha1.RoleView, tenancyv1alpha1.RoleEdit, tenancyv1alpha1.RoleAdmin: + default: + return fmt.Errorf("--role must be one of view, edit, admin (got %q)", role) + } + selected, err := selectionFor(tenant, project) + if err != nil { + return err + } + c, err := o.tenantClient(cmd.Context(), selected.Tenant) + if err != nil { + return err + } + kind := tenancyv1alpha1.SubjectKindUser + if asGroup { + kind = tenancyv1alpha1.SubjectKindGroup + } + return upsertMembership(cmd.Context(), c, kind, args[0], + tenancyv1alpha1.Role(role), selected.Tenant, selected.Project) + }, + } + o.addFlags(cmd) + tenantFlag(cmd, &tenant) + cmd.Flags().StringVar(&role, "role", string(tenancyv1alpha1.RoleView), "view, edit or admin.") + cmd.Flags().StringVar(&project, "project", "", + "Narrow the grant to one project. Defaults to the one `use` selected; "+ + "pass --project= to grant tenant-wide.") + cmd.Flags().BoolVar(&asGroup, "group", false, "Treat SUBJECT as a group rather than a username.") + return cmd +} + +func newMembershipRemoveCommand() *cobra.Command { + o := &adminOptions{} + var ( + tenant string + project string + asGroup bool + ) + + cmd := &cobra.Command{ + Use: "remove SUBJECT", + Aliases: []string{"revoke", "rm"}, + Short: "Revoke a grant", + Long: `Delete the Membership, and with it the RBAC the operator +materialized in the target workspaces. + +--project has to match how the grant was made: a tenant-wide grant and a +project-scoped one are different objects.`, + Args: cobra.ExactArgs(1), + RunE: func(cmd *cobra.Command, args []string) error { + selected, err := selectionFor(tenant, project) + if err != nil { + return err + } + c, err := o.tenantClient(cmd.Context(), selected.Tenant) + if err != nil { + return err + } + name := membershipName(subjectKind(asGroup), args[0], selected.Tenant, selected.Project) + membership := &tenancyv1alpha1.Membership{ObjectMeta: metav1.ObjectMeta{Name: name}} + if err := c.Delete(cmd.Context(), membership); err != nil { + if apierrors.IsNotFound(err) { + return fmt.Errorf("no such grant: %s (try `membership list`)", name) + } + return fmt.Errorf("delete membership: %w", err) + } + fmt.Printf("membership/%s revoked\n", name) + return nil + }, + } + o.addFlags(cmd) + tenantFlag(cmd, &tenant) + cmd.Flags().StringVar(&project, "project", "", "Project of the grant, if it was project-scoped.") + cmd.Flags().BoolVar(&asGroup, "group", false, "Treat SUBJECT as a group rather than a username.") + return cmd +} diff --git a/tenancy/pkg/cli/org.go b/tenancy/pkg/cli/org.go index 088b712..045f1af 100644 --- a/tenancy/pkg/cli/org.go +++ b/tenancy/pkg/cli/org.go @@ -99,7 +99,10 @@ them.`, if err != nil { return fmt.Errorf("resolve workspace path %s: %w", orgPath, err) } - if err := bootstrap.BindStore(cmd.Context(), orgCfg, result); err != nil { + // No server identities here: `org bootstrap` makes an additional + // platform workspace, and which servers may locate it is init's + // business rather than this command's. + if err := bootstrap.BindStore(cmd.Context(), orgCfg, result, bootstrap.Options{}); err != nil { return fmt.Errorf("bind the Tenant API into %s: %w", orgPath, err) } diff --git a/tenancy/pkg/cli/review.go b/tenancy/pkg/cli/review.go index a80a868..321fd3f 100644 --- a/tenancy/pkg/cli/review.go +++ b/tenancy/pkg/cli/review.go @@ -53,15 +53,19 @@ type userOptions struct { } func (o *userOptions) addFlags(cmd *cobra.Command) { - cmd.Flags().StringVar(&o.url, "url", os.Getenv("TENANCY_VW_URL"), - "Base URL of the tenancy virtual workspace, e.g. https://kcp.example.com. "+ - "Defaults to $TENANCY_VW_URL.") + // The address is learned once, by `login --url`, and kept in the + // shared context; $TENANCY_VW_URL still wins for a one-off, and an + // explicit flag wins over both. + cmd.Flags().StringVar(&o.url, "url", envOr("TENANCY_VW_URL", storedServiceURL("tenancy")), + "Base URL of the tenancy virtual workspace. Defaults to the server `login --url` "+ + "stored, or $TENANCY_VW_URL.") cmd.Flags().StringVar(&o.certFile, "client-cert", "", "Client certificate to authenticate with.") cmd.Flags().StringVar(&o.keyFile, "client-key", "", "Key for --client-cert.") cmd.Flags().StringVar(&o.tokenFile, "token-file", "", "File holding a bearer token to authenticate with.") - cmd.Flags().StringVar(&o.caFile, "certificate-authority", "", + storedCA, storedInsecure := storedTLS() + cmd.Flags().StringVar(&o.caFile, "certificate-authority", storedCA, "CA bundle used to verify the virtual workspace's serving certificate.") - cmd.Flags().BoolVar(&o.insecure, "insecure-skip-tls-verify", false, + cmd.Flags().BoolVar(&o.insecure, "insecure-skip-tls-verify", storedInsecure, "Do not verify the virtual workspace's serving certificate. For local testing only.") cmd.Flags().StringVar(&o.kubeconfig, "kubeconfig", "", "Take credentials from this kubeconfig's current context instead of --client-cert/--token-file.") @@ -219,13 +223,19 @@ func newKubeconfigCommand() *cobra.Command { cmd := &cobra.Command{ Use: "kubeconfig", - Short: "Write a kubeconfig with a context per tenant and project you can reach", + Short: "Write a kubeconfig with a context per project you can reach", Long: `Ask the virtual workspace what you can reach and turn the answer -into a kubeconfig: one context per tenant and per project, each pointing at -that workspace's own URL, all sharing your credential. +into a kubeconfig: one context per project, each pointing at that +workspace's own URL, all sharing your credential. + +Projects only, because those are the workspaces a member can work in. A +tenant workspace is the record store the tenancy system keeps its own +objects in — a Membership materializes RBAC in that tenant's projects and +never in the tenant itself — so no member can enter it, and a context for +it would only ever answer Forbidden. This is the closest thing to a login: after running it, "kubectl ---context=" talks to that tenant's workspace directly.`, +--context=-" talks to that project's workspace directly.`, Args: cobra.NoArgs, RunE: func(cmd *cobra.Command, _ []string) error { review, err := o.review(cmd.Context()) @@ -271,15 +281,16 @@ This is the closest thing to a login: after running it, "kubectl kubeconfig.Contexts[name] = ctx } + // Projects only: the tenant workspace is a record store no + // member can enter, so a context for it would be a trap. for _, t := range review.Status.Tenants { - add(t.Name, t.Endpoint) for _, p := range t.Projects { add(t.Name+"-"+p.Name, p.Endpoint) } } if len(kubeconfig.Contexts) == 0 { - return fmt.Errorf("no workspace in the answer carried an endpoint URL; " + - "is the virtual workspace started with --endpoint-base?") + return fmt.Errorf("you are a member of no project yet, so there is nothing to write "+ + "(`%s whoami` shows what you can reach)", cmd.Root().Name()) } if context_ != "" { @@ -288,7 +299,7 @@ This is the closest thing to a login: after running it, "kubectl } kubeconfig.CurrentContext = context_ } else { - kubeconfig.CurrentContext = review.Status.Tenants[0].Name + kubeconfig.CurrentContext = defaultContext(review.Status.Tenants, kubeconfig.Contexts) } if output == "" || output == "-" { @@ -302,8 +313,12 @@ This is the closest thing to a login: after running it, "kubectl if err := clientcmd.WriteToFile(*kubeconfig, output); err != nil { return fmt.Errorf("write %s: %w", output, err) } - fmt.Printf("wrote %s with %d contexts (current: %s)\n", - output, len(kubeconfig.Contexts), kubeconfig.CurrentContext) + plural := "s" + if len(kubeconfig.Contexts) == 1 { + plural = "" + } + fmt.Printf("wrote %s with %d project context%s (current: %s)\n", + output, len(kubeconfig.Contexts), plural, kubeconfig.CurrentContext) return nil }, } @@ -336,3 +351,30 @@ func hint(err error) string { return "" } } + +// defaultContext picks which project context a freshly written kubeconfig +// starts in: the first one the caller actually holds a role in. +// +// A project can be listed with no roles of its own — a tenant-wide grant +// is reported on the tenant, not repeated on every project — so "no +// roles" is not "no access" and such a context is still worth keeping. +// Preferring one with roles just makes the default the least surprising. +func defaultContext(tenants []tenancyv1alpha1.TenantClaim, contexts map[string]*clientcmdapi.Context) string { + var fallback string + + for _, t := range tenants { + for _, p := range t.Projects { + name := t.Name + "-" + p.Name + if _, ok := contexts[name]; !ok { + continue // no endpoint, so no context was written for it + } + if len(p.Roles) > 0 { + return name + } + if fallback == "" { + fallback = name + } + } + } + return fallback +} diff --git a/tenancy/pkg/cli/review_test.go b/tenancy/pkg/cli/review_test.go new file mode 100644 index 0000000..e0fb97d --- /dev/null +++ b/tenancy/pkg/cli/review_test.go @@ -0,0 +1,106 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package cli + +import ( + "testing" + + clientcmdapi "k8s.io/client-go/tools/clientcmd/api" + + tenancyv1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1" +) + +func TestDefaultContext(t *testing.T) { + // Only projects get contexts at all — a tenant workspace is a record + // store no member can enter — so this only ever chooses between + // projects, preferring one the caller holds a role in. + cases := map[string]struct { + tenants []tenancyv1alpha1.TenantClaim + contexts []string + want string + }{ + "the only project is the default": { + tenants: []tenancyv1alpha1.TenantClaim{{ + Name: "acme", + Roles: []string{"admin"}, + Projects: []tenancyv1alpha1.ProjectClaim{ + {Name: "web", Roles: []string{"admin"}}, + }, + }}, + contexts: []string{"acme-web"}, + want: "acme-web", + }, + "a project with roles wins over one without": { + tenants: []tenancyv1alpha1.TenantClaim{{ + Name: "acme", + Projects: []tenancyv1alpha1.ProjectClaim{ + {Name: "attic"}, + {Name: "web", Roles: []string{"edit"}}, + }, + }}, + contexts: []string{"acme-attic", "acme-web"}, + want: "acme-web", + }, + "a project reached only by a tenant-wide grant still counts": { + tenants: []tenancyv1alpha1.TenantClaim{{ + Name: "acme", + Roles: []string{"admin"}, // fans out; not repeated per project + Projects: []tenancyv1alpha1.ProjectClaim{ + {Name: "web"}, + }, + }}, + contexts: []string{"acme-web"}, + want: "acme-web", + }, + "a project whose workspace has no endpoint is skipped": { + tenants: []tenancyv1alpha1.TenantClaim{{ + Name: "acme", + Projects: []tenancyv1alpha1.ProjectClaim{ + {Name: "pending", Roles: []string{"admin"}}, + {Name: "web", Roles: []string{"view"}}, + }, + }}, + // "pending" is still provisioning, so no context was written. + contexts: []string{"acme-web"}, + want: "acme-web", + }, + "the first project of the first tenant, across tenants": { + tenants: []tenancyv1alpha1.TenantClaim{ + {Name: "acme", Projects: []tenancyv1alpha1.ProjectClaim{ + {Name: "web", Roles: []string{"view"}}, + }}, + {Name: "globex", Projects: []tenancyv1alpha1.ProjectClaim{ + {Name: "api", Roles: []string{"admin"}}, + }}, + }, + contexts: []string{"acme-web", "globex-api"}, + want: "acme-web", + }, + } + + for name, tc := range cases { + t.Run(name, func(t *testing.T) { + contexts := map[string]*clientcmdapi.Context{} + for _, c := range tc.contexts { + contexts[c] = clientcmdapi.NewContext() + } + if got := defaultContext(tc.tenants, contexts); got != tc.want { + t.Errorf("defaultContext = %q, want %q", got, tc.want) + } + }) + } +} diff --git a/tenancy/pkg/cli/root.go b/tenancy/pkg/cli/root.go index 176ff10..8d13675 100644 --- a/tenancy/pkg/cli/root.go +++ b/tenancy/pkg/cli/root.go @@ -54,10 +54,13 @@ func init() { utilruntime.Must(tenancyv1alpha1.AddToScheme(scheme)) } -// Execute runs tenancyctl. -func Execute() error { +// New builds the tenancy CLI command tree under the given name — +// "tenancyctl" for the standalone binary, "tenancy" when mounted as a +// subcommand of the repo-wide CLI. It registers no logging flags; the +// binary that owns the process does that once, at its own root. +func New(use string) *cobra.Command { root := &cobra.Command{ - Use: "tenancyctl", + Use: use, Short: "Manage kcp tenants, projects and access", Long: `tenancyctl is the client for the kcp tenancy model. @@ -70,10 +73,6 @@ with no kubeconfig for kcp itself and no credential flags.`, SilenceUsage: true, } - klogFlags := goflag.NewFlagSet("klog", goflag.ContinueOnError) - klog.InitFlags(klogFlags) - root.PersistentFlags().AddGoFlagSet(klogFlags) - root.AddCommand( newLoginCommand(), newLogoutCommand(), @@ -84,8 +83,20 @@ with no kubeconfig for kcp itself and no credential flags.`, newWhoAmICommand(), newKubeconfigCommand(), newOrgCommand(), + newSeedCommand(), ) + return root +} + +// Execute runs the standalone tenancyctl binary. +func Execute() error { + root := New("tenancyctl") + + klogFlags := goflag.NewFlagSet("klog", goflag.ContinueOnError) + klog.InitFlags(klogFlags) + root.PersistentFlags().AddGoFlagSet(klogFlags) + return root.Execute() } diff --git a/tenancy/pkg/cli/seed.go b/tenancy/pkg/cli/seed.go new file mode 100644 index 0000000..d68544a --- /dev/null +++ b/tenancy/pkg/cli/seed.go @@ -0,0 +1,164 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package cli + +import ( + "fmt" + + "github.com/spf13/cobra" + + apierrors "k8s.io/apimachinery/pkg/api/errors" + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + + tenancyv1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1" +) + +// NewSeedCommand exposes seed for the tenancy binary, so a development +// environment (Tilt, a demo) can converge on baseline data with the +// component's own tooling and nothing else. +func NewSeedCommand() *cobra.Command { return newSeedCommand() } + +// newSeedCommand builds `seed`: one idempotent call that converges on a +// tenant, optionally a project, and a set of grants. Everything it does +// is if-not-present or an in-place role change, so calling it again — on +// every environment start, say — is always safe. The identities are +// arguments, not defaults: which users exist is the environment's +// business, not the component's. +func newSeedCommand() *cobra.Command { + o := &adminOptions{} + var ( + tenant string + displayName string + project string + admins []string + views []string + wait_ bool + ) + + cmd := &cobra.Command{ + Use: "seed", + Short: "Idempotently converge on a tenant, a project and grants", + Long: `Seed baseline tenancy data for an environment, idempotently. + +Creates the tenant and project when missing (and waits for their +workspaces), then upserts the grants: --admin subjects become tenant-wide +admins, --view subjects get view on the project (tenant-wide when no +project is given). Safe to run on every environment start.`, + Args: cobra.NoArgs, + RunE: func(cmd *cobra.Command, _ []string) error { + if tenant == "" { + return fmt.Errorf("--tenant is required") + } + ctx := cmd.Context() + + platform, err := o.client() + if err != nil { + return err + } + if displayName == "" { + displayName = tenant + } + t := &tenancyv1alpha1.Tenant{ + ObjectMeta: metav1.ObjectMeta{Name: tenant}, + Spec: tenancyv1alpha1.TenantSpec{ + DisplayName: displayName, + // The first --admin also seeds the tenant, so the + // grant exists the moment the workspace does rather + // than after the projects below it. + FirstAdmin: firstOf(admins), + }, + } + switch err := platform.Create(ctx, t); { + case err == nil: + fmt.Printf("tenant/%s created in %s\n", tenant, o.workspace) + case apierrors.IsAlreadyExists(err): + fmt.Printf("tenant/%s already exists in %s\n", tenant, o.workspace) + default: + return fmt.Errorf("create tenant: %w", err) + } + if wait_ { + if err := waitForTenant(ctx, platform, tenant); err != nil { + return err + } + } + + tc, err := o.tenantClient(ctx, tenant) + if err != nil { + return err + } + + if project != "" { + p := &tenancyv1alpha1.Project{ + ObjectMeta: metav1.ObjectMeta{Name: project}, + Spec: tenancyv1alpha1.ProjectSpec{ + Tenant: tenant, + DisplayName: project, + }, + } + switch err := tc.Create(ctx, p); { + case err == nil: + fmt.Printf("project/%s created in tenant %s\n", project, tenant) + case apierrors.IsAlreadyExists(err): + fmt.Printf("project/%s already exists in tenant %s\n", project, tenant) + default: + return fmt.Errorf("create project: %w", err) + } + if wait_ { + if err := waitForProject(ctx, tc, project); err != nil { + return err + } + } + } + + for _, subject := range admins { + if err := upsertMembership(ctx, tc, tenancyv1alpha1.SubjectKindUser, subject, + tenancyv1alpha1.RoleAdmin, tenant, ""); err != nil { + return err + } + } + for _, subject := range views { + if err := upsertMembership(ctx, tc, tenancyv1alpha1.SubjectKindUser, subject, + tenancyv1alpha1.RoleView, tenant, project); err != nil { + return err + } + } + + fmt.Printf("seeded tenant %s\n", tenant) + return nil + }, + } + o.addFlags(cmd) + cmd.Flags().StringVar(&tenant, "tenant", "", "Tenant to converge on (required).") + cmd.Flags().StringVar(&displayName, "display-name", "", + "Human name of the tenant; seeds the workspace name. Defaults to the tenant name.") + cmd.Flags().StringVar(&project, "project", "", "Project to converge on inside the tenant.") + cmd.Flags().StringArrayVar(&admins, "admin", nil, + "Subject to grant tenant-wide admin (repeatable).") + cmd.Flags().StringArrayVar(&views, "view", nil, + "Subject to grant view on the project, or tenant-wide without --project (repeatable).") + cmd.Flags().BoolVar(&wait_, "wait", true, "Wait until the workspaces are ready.") + + return cmd +} + +// firstOf returns the first element, or "". +func firstOf(ss []string) string { + if len(ss) == 0 { + return "" + } + return ss[0] +} diff --git a/tenancy/pkg/cli/selection.go b/tenancy/pkg/cli/selection.go new file mode 100644 index 0000000..19a86ad --- /dev/null +++ b/tenancy/pkg/cli/selection.go @@ -0,0 +1,85 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package cli + +import ( + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/pkg/clicontext" +) + +// Selection is the tenant and project the user is currently working in: +// what `use` picks, and what every command that needs a workspace falls +// back to when no flag names one. +// +// It is a view onto the shared CLI context in ~/.kube, which also holds +// the server `login` learned — one file, so a command never has to be +// told twice where anything is. +type Selection struct { + Tenant string + Project string + // URL is the project's workspace, as the virtual workspace reported + // it, so commands that only need somewhere to talk to do not have to + // ask again. + URL string +} + +// String renders the selection the way the CLI prints it. +func (s Selection) String() string { + if s.Project == "" { + return s.Tenant + } + return s.Tenant + "/" + s.Project +} + +// Empty reports whether nothing has been selected yet. +func (s Selection) Empty() bool { return s.Tenant == "" } + +// CurrentSelection reads the selection from the shared context. +func CurrentSelection() Selection { + c := clicontext.Load() + return Selection{Tenant: c.Tenant, Project: c.Project, URL: c.WorkspaceURL} +} + +// WriteSelection stores the selection, leaving the rest of the context — +// the server, the TLS settings — as it was. +func WriteSelection(s Selection) error { + return clicontext.Update(func(c *clicontext.Context) { + c.Tenant, c.Project, c.WorkspaceURL = s.Tenant, s.Project, s.URL + }) +} + +// ClearSelection forgets where the user was working, but keeps them +// logged in and keeps the server: they chose a project, not a cluster. +func ClearSelection() error { + return clicontext.Update(func(c *clicontext.Context) { + c.Tenant, c.Project, c.WorkspaceURL = "", "", "" + }) +} + +// storedServiceURL is where a virtual workspace answers on the server +// `login --url` stored, or "" when no server is known yet — in which case +// the flag is required and says so. +func storedServiceURL(name string) string { + return clicontext.Load().ServiceURL(name) +} + +// storedTLS reports the TLS settings saved with the server, so a +// development setup does not need --insecure-skip-tls-verify on every +// command. +func storedTLS() (caFile string, insecure bool) { + c := clicontext.Load() + return c.CertificateAuthority, c.Insecure +} diff --git a/tenancy/pkg/cli/tenant.go b/tenancy/pkg/cli/tenant.go index 79e00a8..df164fd 100644 --- a/tenancy/pkg/cli/tenant.go +++ b/tenancy/pkg/cli/tenant.go @@ -44,6 +44,7 @@ func newTenantCommand() *cobra.Command { var ( displayName string description string + firstAdmin string wait_ bool ) @@ -66,6 +67,7 @@ func newTenantCommand() *cobra.Command { Spec: tenancyv1alpha1.TenantSpec{ DisplayName: displayName, Description: description, + FirstAdmin: firstAdmin, }, } if err := c.Create(cmd.Context(), tenant); err != nil { @@ -85,6 +87,9 @@ func newTenantCommand() *cobra.Command { create.Flags().StringVar(&displayName, "display-name", "", "Human name of the tenant; seeds the workspace name. Defaults to NAME.") create.Flags().StringVar(&description, "description", "", "Free text for humans.") + create.Flags().StringVar(&firstAdmin, "first-admin", "", + "Identity to grant admin on this tenant once its workspace exists. Saves a second "+ + "`membership add`, and is what makes the tenant usable by anyone but you.") create.Flags().BoolVar(&wait_, "wait", true, "Wait until the tenant's workspace is ready.") list := &cobra.Command{ @@ -178,11 +183,16 @@ func dashPhase(p tenancyv1alpha1.Phase) tenancyv1alpha1.Phase { } // membershipName derives a deterministic object name for a grant, so that -// granting the same access twice is a no-op rather than a duplicate. -func membershipName(subject, tenant, project string) string { - parts := naming.Slugify(subject) + "-" + naming.Slugify(tenant) - if project != "" { - parts += "-" + naming.Slugify(project) +// granting the same access twice is a no-op rather than a duplicate. The +// virtual workspace derives the same name for grants made through it, so +// the two paths cannot produce competing objects for one grant. +func membershipName(kind tenancyv1alpha1.SubjectKind, subject, tenant, project string) string { + return naming.MembershipName(string(kind), subject, tenant, project) +} + +func subjectKind(asGroup bool) tenancyv1alpha1.SubjectKind { + if asGroup { + return tenancyv1alpha1.SubjectKindGroup } - return parts + return tenancyv1alpha1.SubjectKindUser } diff --git a/tenancy/pkg/cli/user.go b/tenancy/pkg/cli/user.go new file mode 100644 index 0000000..1beb4aa --- /dev/null +++ b/tenancy/pkg/cli/user.go @@ -0,0 +1,324 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package cli + +import ( + "bufio" + "fmt" + "os" + "strconv" + "strings" + + "github.com/spf13/cobra" + + tenancyv1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1" +) + +// The user-facing half of the CLI: everything here answers from the +// caller's own credential through the virtual workspace, with no +// kubeconfig for kcp and no administrative rights. These are the +// commands mounted at the root of the repo-wide CLI. + +// NewLoginCommand obtains a token from the identity provider and caches it. +func NewLoginCommand() *cobra.Command { return newLoginCommand() } + +// NewLogoutCommand forgets the cached token. +func NewLogoutCommand() *cobra.Command { return newLogoutCommand() } + +// NewWhoAmICommand shows the tenants and projects the caller can reach. +func NewWhoAmICommand() *cobra.Command { return newWhoAmICommand() } + +// NewKubeconfigCommand writes a kubeconfig for the caller's projects. +func NewKubeconfigCommand() *cobra.Command { return newKubeconfigCommand() } + +// NewAdminCommand groups everything that writes to kcp with a kubeconfig +// rather than answering from the caller's own credential: creating +// tenants and projects, bootstrapping an organization, seeding an +// environment. Whoever runs the platform uses these; a tenant does not. +func NewAdminCommand() *cobra.Command { + cmd := &cobra.Command{ + Use: "admin", + Short: "Create tenants and projects, bootstrap and seed (needs a kubeconfig)", + Long: `The platform side of the tenancy model. + +These commands write to kcp directly — they need a kubeconfig with rights +in the workspace they touch, which is exactly what a tenant does not +have. The user-facing commands at the root need no kubeconfig at all.`, + Args: cobra.NoArgs, + RunE: func(cmd *cobra.Command, _ []string) error { return cmd.Help() }, + } + cmd.AddCommand( + newTenantCommand(), + newProjectCommand(), + newOrgCommand(), + newSeedCommand(), + ) + return cmd +} + +// NewTenantsCommand lists the tenants the caller is a member of. +func NewTenantsCommand() *cobra.Command { + o := &userOptions{} + cmd := &cobra.Command{ + Use: "tenants", + Aliases: []string{"tenant"}, + Short: "List the tenants you can reach", + Long: `List the tenants the calling identity is a member of, as the +tenancy virtual workspace reports them. + +This is the user's view: it needs no kubeconfig for kcp, only your own +credential. To create a tenant, which is an administrator's job, see +"admin tenant create".`, + Args: cobra.NoArgs, + RunE: func(cmd *cobra.Command, _ []string) error { + review, err := o.review(cmd.Context()) + if err != nil { + return err + } + if len(review.Status.Tenants) == 0 { + fmt.Println("You are not a member of any tenant.") + return nil + } + current := CurrentSelection() + rows := make([][]string, 0, len(review.Status.Tenants)) + for _, t := range review.Status.Tenants { + rows = append(rows, []string{ + marker(current.Tenant == t.Name), t.Name, dash(t.DisplayName), + dash(strings.Join(t.Roles, ",")), strconv.Itoa(len(t.Projects)), + }) + } + table([]string{"", "TENANT", "DISPLAY NAME", "ROLES", "PROJECTS"}, rows) + return nil + }, + } + o.addFlags(cmd) + return cmd +} + +// NewProjectsCommand lists the projects the caller can reach. +func NewProjectsCommand() *cobra.Command { + o := &userOptions{} + var tenant string + + cmd := &cobra.Command{ + Use: "projects", + Aliases: []string{"project"}, + Short: "List the projects you can reach", + Long: `List the projects the calling identity can reach, across every +tenant, or only within one with --tenant. + +A project is where work happens: it is the workspace your kubeconfig +context points at.`, + Args: cobra.NoArgs, + RunE: func(cmd *cobra.Command, _ []string) error { + review, err := o.review(cmd.Context()) + if err != nil { + return err + } + current := CurrentSelection() + rows := [][]string{} + for _, t := range review.Status.Tenants { + if tenant != "" && t.Name != tenant { + continue + } + for _, p := range t.Projects { + selected := current.Tenant == t.Name && current.Project == p.Name + rows = append(rows, []string{ + marker(selected), t.Name, p.Name, dash(p.DisplayName), + dash(strings.Join(rolesFor(t, p), ",")), dash(p.Endpoint), + }) + } + } + if len(rows) == 0 { + if tenant != "" { + fmt.Printf("No projects you can reach in tenant %q.\n", tenant) + } else { + fmt.Println("You can reach no projects.") + } + return nil + } + table([]string{"", "TENANT", "PROJECT", "DISPLAY NAME", "ROLES", "ENDPOINT"}, rows) + return nil + }, + } + o.addFlags(cmd) + cmd.Flags().StringVar(&tenant, "tenant", "", "Only show projects of this tenant.") + return cmd +} + +// NewUseCommand selects the tenant and project later commands default to. +func NewUseCommand() *cobra.Command { + o := &userOptions{} + var clear bool + + cmd := &cobra.Command{ + Use: "use [TENANT[/PROJECT]]", + Short: "Choose the tenant and project to work in", + Long: `Pick the project later commands act on, so they do not each need +--tenant and --project. + +Given no argument it lists what you can reach and asks; given +TENANT/PROJECT it selects that directly. The choice is remembered in +` + "`" + `current.json` + "`" + ` next to the token cache, and "whoami" or "projects" shows +it marked with *. + +Selecting nothing authorizes nothing: it is a convenience, and kcp still +decides what you may do in the workspace.`, + Args: cobra.MaximumNArgs(1), + RunE: func(cmd *cobra.Command, args []string) error { + if clear { + if err := ClearSelection(); err != nil { + return err + } + fmt.Println("Selection cleared.") + return nil + } + + review, err := o.review(cmd.Context()) + if err != nil { + return err + } + choices := flatten(review) + if len(choices) == 0 { + return fmt.Errorf("you can reach no project yet; `whoami` shows what you are a member of") + } + + var chosen Selection + if len(args) == 1 { + chosen, err = matchChoice(choices, args[0]) + } else { + chosen, err = promptForChoice(choices) + } + if err != nil { + return err + } + + if err := WriteSelection(chosen); err != nil { + return err + } + fmt.Printf("Now using %s\n", chosen) + if chosen.URL != "" { + fmt.Printf(" %s\n", chosen.URL) + } + return nil + }, + } + o.addFlags(cmd) + cmd.Flags().BoolVar(&clear, "clear", false, "Forget the current selection instead of choosing one.") + return cmd +} + +// flatten turns a review into the list of things that can be selected: +// every project, since a tenant workspace is a record store no member can +// enter (see defaultContext). +func flatten(review *tenancyv1alpha1.SelfTenancyReview) []Selection { + out := []Selection{} + for _, t := range review.Status.Tenants { + for _, p := range t.Projects { + out = append(out, Selection{Tenant: t.Name, Project: p.Name, URL: p.Endpoint}) + } + } + return out +} + +// matchChoice resolves "tenant/project", or a bare tenant when it has +// exactly one project. +func matchChoice(choices []Selection, arg string) (Selection, error) { + tenant, project, hasProject := strings.Cut(arg, "/") + + matches := []Selection{} + for _, c := range choices { + if c.Tenant != tenant { + continue + } + if hasProject && c.Project != project { + continue + } + matches = append(matches, c) + } + + switch len(matches) { + case 0: + return Selection{}, fmt.Errorf("no project %q you can reach (try `projects`)", arg) + case 1: + return matches[0], nil + default: + names := make([]string, 0, len(matches)) + for _, m := range matches { + names = append(names, m.String()) + } + return Selection{}, fmt.Errorf("tenant %q has several projects, say which: %s", + tenant, strings.Join(names, ", ")) + } +} + +// promptForChoice lists the options and reads a number. Deliberately a +// plain numbered list read from stdin: it works over ssh, in a pipe with +// `echo 2 |`, and without a terminal library. +func promptForChoice(choices []Selection) (Selection, error) { + current := CurrentSelection() + fmt.Fprintln(os.Stderr, "Projects you can reach:") + for i, c := range choices { + fmt.Fprintf(os.Stderr, " %s%2d) %s\n", marker(c.Tenant == current.Tenant && c.Project == current.Project), i+1, c) + } + fmt.Fprintf(os.Stderr, "Select [1-%d]: ", len(choices)) + + line, err := bufio.NewReader(os.Stdin).ReadString('\n') + if err != nil && strings.TrimSpace(line) == "" { + return Selection{}, fmt.Errorf("nothing selected") + } + n, err := strconv.Atoi(strings.TrimSpace(line)) + if err != nil || n < 1 || n > len(choices) { + return Selection{}, fmt.Errorf("not a choice between 1 and %d: %q", len(choices), strings.TrimSpace(line)) + } + return choices[n-1], nil +} + +// rolesFor reports the roles that reach a project: its own, plus the +// tenant-wide ones, which fan out to every project and are reported on +// the tenant rather than repeated on each. +func rolesFor(t tenancyv1alpha1.TenantClaim, p tenancyv1alpha1.ProjectClaim) []string { + if len(p.Roles) > 0 { + return p.Roles + } + return t.Roles +} + +// marker flags the current selection in a listing. +func marker(selected bool) string { + if selected { + return "*" + } + return "" +} + +// selectionFor resolves which tenant and project a command should act on: +// the flags when given, otherwise whatever `use` selected. +func selectionFor(tenant, project string) (Selection, error) { + if tenant != "" { + return Selection{Tenant: tenant, Project: project}, nil + } + current := CurrentSelection() + if current.Empty() { + return Selection{}, fmt.Errorf("no tenant selected: pass --tenant, or run `use` to choose one") + } + if project != "" { + current.Project = project + current.URL = "" + } + return current, nil +} diff --git a/tenancy/pkg/clicontext/context.go b/tenancy/pkg/clicontext/context.go new file mode 100644 index 0000000..fe9b119 --- /dev/null +++ b/tenancy/pkg/clicontext/context.go @@ -0,0 +1,146 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// Package clicontext holds what the CLI remembers between commands: the +// server it talks to, and where the user is working. +// +// It lives beside the kubeconfig, in ~/.kube, because it is the same kind +// of thing — the local note about which cluster you mean — and because +// anyone debugging a CLI looks there first. +// +// It belongs to the tenancy CLI because that is where it is written: +// `login` learns the server, `use` picks the project. Other components' +// commands are handed what they need from it by whichever binary composes +// them (contribctl), the way the marketplace's `enable` is handed a +// workspace resolver — so the components still never import each other, +// and a component's CLI on its own needs nothing but its flags. +// +// Nothing here authorizes anything. It is a convenience that saves +// repeating flags — kcp decides what the caller may do. +package clicontext + +import ( + "encoding/json" + "fmt" + "os" + "path/filepath" + "strings" +) + +// EnvPath overrides where the context is stored. +const EnvPath = "CONTRIBCTL_CONTEXT" + +// Context is the CLI's memory between invocations. +type Context struct { + // Server is the front-proxy's base URL, e.g. + // https://kcp.example.com:8443. Every virtual workspace hangs off it + // under /services/, so one address is all a client needs. + Server string `json:"server,omitempty"` + // Tenant and Project are what `use` selected. + Tenant string `json:"tenant,omitempty"` + Project string `json:"project,omitempty"` + // WorkspaceURL is the selected project's own workspace, as the + // tenancy virtual workspace reported it. + WorkspaceURL string `json:"workspaceURL,omitempty"` + // Insecure records that the servers' certificates are not verified, + // so a development setup does not need the flag on every command. + Insecure bool `json:"insecureSkipTLSVerify,omitempty"` + // CertificateAuthority is the CA bundle that verifies them, when they + // are verified. + CertificateAuthority string `json:"certificateAuthority,omitempty"` +} + +// Where returns the path the context is read from and written to. +func Where() string { + if p := os.Getenv(EnvPath); p != "" { + return p + } + home, err := os.UserHomeDir() + if err != nil { + return "" + } + return filepath.Join(home, ".kube", "contribctl.json") +} + +// Load reads the stored context. A missing or unreadable file is an empty +// context, not an error: every caller has to cope with "nothing chosen +// yet" anyway, and a corrupt file should not make the CLI unusable. +func Load() Context { + path := Where() + if path == "" { + return Context{} + } + raw, err := os.ReadFile(path) + if err != nil { + return Context{} + } + var c Context + if err := json.Unmarshal(raw, &c); err != nil { + return Context{} + } + return c +} + +// Save writes the context, creating ~/.kube if it is not there yet. +func Save(c Context) error { + path := Where() + if path == "" { + return fmt.Errorf("no home directory could be determined; set %s", EnvPath) + } + if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil { + return fmt.Errorf("create %s: %w", filepath.Dir(path), err) + } + raw, err := json.MarshalIndent(c, "", " ") + if err != nil { + return fmt.Errorf("serialize the context: %w", err) + } + if err := os.WriteFile(path, append(raw, '\n'), 0o600); err != nil { + return fmt.Errorf("write %s: %w", path, err) + } + return nil +} + +// Update reads the context, applies mutate, and writes it back, so a +// command changes only the field it owns. +func Update(mutate func(*Context)) error { + c := Load() + mutate(&c) + return Save(c) +} + +// ServiceURL is where a virtual workspace answers on the stored server: +// the front-proxy routes /services/ to it. +// +// Empty when no server is known, which is the caller's cue to ask for +// one — the CLI cannot guess an address. +func (c Context) ServiceURL(name string) string { + if c.Server == "" { + return "" + } + return strings.TrimSuffix(c.Server, "/") + "/services/" + name +} + +// Selection renders where the user is working, for messages. +func (c Context) Selection() string { + switch { + case c.Tenant == "": + return "" + case c.Project == "": + return c.Tenant + default: + return c.Tenant + "/" + c.Project + } +} diff --git a/tenancy/pkg/directory/directory.go b/tenancy/pkg/directory/directory.go index 2197d0f..ef9d3dc 100644 --- a/tenancy/pkg/directory/directory.go +++ b/tenancy/pkg/directory/directory.go @@ -166,6 +166,38 @@ func (d *Directory) RemoveMembership(k Key) { delete(d.memberships, k) } +// NamedMembership is a membership together with the name of the object it +// was mirrored from, which is what a caller needs to delete it again. +type NamedMembership struct { + Name string + Membership +} + +// MembershipsIn lists every grant recorded in one tenant workspace, +// sorted by name so the answer is stable. +// +// Unlike ReviewFor this is not filtered to one identity: it reports who +// else holds what, which only an administrator of that tenant may see. +// Callers are responsible for having established that first. +func (d *Directory) MembershipsIn(cluster string) []NamedMembership { + if cluster == "" { + return nil + } + + d.mu.RLock() + defer d.mu.RUnlock() + + out := make([]NamedMembership, 0, len(d.memberships)) + for k, m := range d.memberships { + if k.Cluster != cluster { + continue + } + out = append(out, NamedMembership{Name: k.Name, Membership: m}) + } + sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name }) + return out +} + // ForgetCluster drops everything recorded for one organization workspace, // for when a cluster leaves the fleet. func (d *Directory) ForgetCluster(cluster string) { diff --git a/tenancy/pkg/generated/openapi/zz_generated.openapi.go b/tenancy/pkg/generated/openapi/zz_generated.openapi.go index 68bbfce..b1a0694 100644 --- a/tenancy/pkg/generated/openapi/zz_generated.openapi.go +++ b/tenancy/pkg/generated/openapi/zz_generated.openapi.go @@ -1,10 +1,6 @@ //go:build !ignore_autogenerated // +build !ignore_autogenerated -/* -Copyright 2026 The kcp Authors. -*/ - // Code generated by openapi-gen. DO NOT EDIT. package openapi @@ -19,24 +15,32 @@ import ( func GetOpenAPIDefinitions(ref common.ReferenceCallback) map[string]common.OpenAPIDefinition { return map[string]common.OpenAPIDefinition{ - "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.Membership": schema_sdk_apis_tenancy_v1alpha1_Membership(ref), - "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.MembershipList": schema_sdk_apis_tenancy_v1alpha1_MembershipList(ref), - "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.MembershipSpec": schema_sdk_apis_tenancy_v1alpha1_MembershipSpec(ref), - "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.MembershipStatus": schema_sdk_apis_tenancy_v1alpha1_MembershipStatus(ref), - "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.Project": schema_sdk_apis_tenancy_v1alpha1_Project(ref), - "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.ProjectClaim": schema_sdk_apis_tenancy_v1alpha1_ProjectClaim(ref), - "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.ProjectList": schema_sdk_apis_tenancy_v1alpha1_ProjectList(ref), - "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.ProjectSpec": schema_sdk_apis_tenancy_v1alpha1_ProjectSpec(ref), - "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.ProjectStatus": schema_sdk_apis_tenancy_v1alpha1_ProjectStatus(ref), - "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.SelfTenancyReview": schema_sdk_apis_tenancy_v1alpha1_SelfTenancyReview(ref), - "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.SelfTenancyReviewList": schema_sdk_apis_tenancy_v1alpha1_SelfTenancyReviewList(ref), - "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.SelfTenancyReviewStatus": schema_sdk_apis_tenancy_v1alpha1_SelfTenancyReviewStatus(ref), - "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.Subject": schema_sdk_apis_tenancy_v1alpha1_Subject(ref), - "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.Tenant": schema_sdk_apis_tenancy_v1alpha1_Tenant(ref), - "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.TenantClaim": schema_sdk_apis_tenancy_v1alpha1_TenantClaim(ref), - "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.TenantList": schema_sdk_apis_tenancy_v1alpha1_TenantList(ref), - "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.TenantSpec": schema_sdk_apis_tenancy_v1alpha1_TenantSpec(ref), - "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.TenantStatus": schema_sdk_apis_tenancy_v1alpha1_TenantStatus(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.Membership": schema_sdk_apis_tenancy_v1alpha1_Membership(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.MembershipList": schema_sdk_apis_tenancy_v1alpha1_MembershipList(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.MembershipSpec": schema_sdk_apis_tenancy_v1alpha1_MembershipSpec(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.MembershipStatus": schema_sdk_apis_tenancy_v1alpha1_MembershipStatus(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.Project": schema_sdk_apis_tenancy_v1alpha1_Project(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.ProjectClaim": schema_sdk_apis_tenancy_v1alpha1_ProjectClaim(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.ProjectList": schema_sdk_apis_tenancy_v1alpha1_ProjectList(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.ProjectSpec": schema_sdk_apis_tenancy_v1alpha1_ProjectSpec(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.ProjectStatus": schema_sdk_apis_tenancy_v1alpha1_ProjectStatus(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.SelfProjectRequest": schema_sdk_apis_tenancy_v1alpha1_SelfProjectRequest(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.SelfProjectRequestList": schema_sdk_apis_tenancy_v1alpha1_SelfProjectRequestList(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.SelfProjectRequestSpec": schema_sdk_apis_tenancy_v1alpha1_SelfProjectRequestSpec(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.SelfProjectRequestStatus": schema_sdk_apis_tenancy_v1alpha1_SelfProjectRequestStatus(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.SelfTenancyReview": schema_sdk_apis_tenancy_v1alpha1_SelfTenancyReview(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.SelfTenancyReviewList": schema_sdk_apis_tenancy_v1alpha1_SelfTenancyReviewList(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.SelfTenancyReviewStatus": schema_sdk_apis_tenancy_v1alpha1_SelfTenancyReviewStatus(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.SelfTenantRequest": schema_sdk_apis_tenancy_v1alpha1_SelfTenantRequest(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.SelfTenantRequestList": schema_sdk_apis_tenancy_v1alpha1_SelfTenantRequestList(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.SelfTenantRequestSpec": schema_sdk_apis_tenancy_v1alpha1_SelfTenantRequestSpec(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.SelfTenantRequestStatus": schema_sdk_apis_tenancy_v1alpha1_SelfTenantRequestStatus(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.Subject": schema_sdk_apis_tenancy_v1alpha1_Subject(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.Tenant": schema_sdk_apis_tenancy_v1alpha1_Tenant(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.TenantClaim": schema_sdk_apis_tenancy_v1alpha1_TenantClaim(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.TenantList": schema_sdk_apis_tenancy_v1alpha1_TenantList(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.TenantSpec": schema_sdk_apis_tenancy_v1alpha1_TenantSpec(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.TenantStatus": schema_sdk_apis_tenancy_v1alpha1_TenantStatus(ref), v1.APIGroup{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_APIGroup(ref), v1.APIGroupList{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_APIGroupList(ref), v1.APIResource{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_APIResource(ref), @@ -497,6 +501,180 @@ func schema_sdk_apis_tenancy_v1alpha1_ProjectStatus(ref common.ReferenceCallback } } +func schema_sdk_apis_tenancy_v1alpha1_SelfProjectRequest(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "SelfProjectRequest asks for a project in a tenant the caller administers. It is the one write the tenancy virtual workspace does on a caller's behalf, and it exists because the alternative is worse: Projects live in the tenant's own workspace, which is the record store that decides who may reach what, so letting a tenant admin write there directly would hand them the Memberships governing themselves.\n\nThe virtual workspace therefore holds the only credential into that tier. It authorizes the request against the caller's own Membership — admin on that tenant — and creates the Project itself. Nothing is relayed and no privilege is lent: a caller who is not an admin of the named tenant is refused, and one who is gets exactly one object created.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "kind": { + SchemaProps: spec.SchemaProps{ + Description: "Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", + Type: []string{"string"}, + Format: "", + }, + }, + "apiVersion": { + SchemaProps: spec.SchemaProps{ + Description: "APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources", + Type: []string{"string"}, + Format: "", + }, + }, + "metadata": { + SchemaProps: spec.SchemaProps{ + Default: map[string]interface{}{}, + Ref: ref(v1.ObjectMeta{}.OpenAPIModelName()), + }, + }, + "spec": { + SchemaProps: spec.SchemaProps{ + Default: map[string]interface{}{}, + Ref: ref("github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.SelfProjectRequestSpec"), + }, + }, + "status": { + SchemaProps: spec.SchemaProps{ + Default: map[string]interface{}{}, + Ref: ref("github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.SelfProjectRequestStatus"), + }, + }, + }, + Required: []string{"spec"}, + }, + }, + Dependencies: []string{ + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.SelfProjectRequestSpec", "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.SelfProjectRequestStatus", v1.ObjectMeta{}.OpenAPIModelName()}, + } +} + +func schema_sdk_apis_tenancy_v1alpha1_SelfProjectRequestList(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "SelfProjectRequestList is the list form, which exists because the API machinery requires it; the resource is create-only.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "kind": { + SchemaProps: spec.SchemaProps{ + Description: "Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", + Type: []string{"string"}, + Format: "", + }, + }, + "apiVersion": { + SchemaProps: spec.SchemaProps{ + Description: "APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources", + Type: []string{"string"}, + Format: "", + }, + }, + "metadata": { + SchemaProps: spec.SchemaProps{ + Default: map[string]interface{}{}, + Ref: ref(v1.ListMeta{}.OpenAPIModelName()), + }, + }, + "items": { + SchemaProps: spec.SchemaProps{ + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Ref: ref("github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.SelfProjectRequest"), + }, + }, + }, + }, + }, + }, + Required: []string{"items"}, + }, + }, + Dependencies: []string{ + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.SelfProjectRequest", v1.ListMeta{}.OpenAPIModelName()}, + } +} + +func schema_sdk_apis_tenancy_v1alpha1_SelfProjectRequestSpec(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "SelfProjectRequestSpec names the project to create.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "tenant": { + SchemaProps: spec.SchemaProps{ + Description: "Tenant is the tenant to create the project in. The caller must hold the admin role there.", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "name": { + SchemaProps: spec.SchemaProps{ + Description: "Name is the project's object name, which also seeds its workspace name.", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "displayName": { + SchemaProps: spec.SchemaProps{ + Description: "DisplayName is the project's human name. Defaults to Name.", + Type: []string{"string"}, + Format: "", + }, + }, + "description": { + SchemaProps: spec.SchemaProps{ + Description: "Description is free text for humans.", + Type: []string{"string"}, + Format: "", + }, + }, + }, + Required: []string{"tenant", "name"}, + }, + }, + } +} + +func schema_sdk_apis_tenancy_v1alpha1_SelfProjectRequestStatus(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "SelfProjectRequestStatus reports what the request produced.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "created": { + SchemaProps: spec.SchemaProps{ + Description: "Created is true when the Project was created by this request, and false when it already existed — the request is idempotent, so asking twice is not an error.", + Type: []string{"boolean"}, + Format: "", + }, + }, + "project": { + SchemaProps: spec.SchemaProps{ + Description: "Project is the created object's name.", + Type: []string{"string"}, + Format: "", + }, + }, + "message": { + SchemaProps: spec.SchemaProps{ + Description: "Message explains the outcome in a sentence.", + Type: []string{"string"}, + Format: "", + }, + }, + }, + }, + }, + } +} + func schema_sdk_apis_tenancy_v1alpha1_SelfTenancyReview(ref common.ReferenceCallback) common.OpenAPIDefinition { return common.OpenAPIDefinition{ Schema: spec.Schema{ @@ -613,6 +791,172 @@ func schema_sdk_apis_tenancy_v1alpha1_SelfTenancyReviewStatus(ref common.Referen } } +func schema_sdk_apis_tenancy_v1alpha1_SelfTenantRequest(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "SelfTenantRequest asks for a tenant, with the caller as its first admin. It is how someone who is a member of nothing gets started.\n\nUnlike every other self-service path here, there is no Membership to authorize against — that is the point — so the gate is the deployment's: self-service is off unless enabled, and may be limited to groups the identity provider asserts.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "kind": { + SchemaProps: spec.SchemaProps{ + Description: "Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", + Type: []string{"string"}, + Format: "", + }, + }, + "apiVersion": { + SchemaProps: spec.SchemaProps{ + Description: "APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources", + Type: []string{"string"}, + Format: "", + }, + }, + "metadata": { + SchemaProps: spec.SchemaProps{ + Default: map[string]interface{}{}, + Ref: ref(v1.ObjectMeta{}.OpenAPIModelName()), + }, + }, + "spec": { + SchemaProps: spec.SchemaProps{ + Default: map[string]interface{}{}, + Ref: ref("github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.SelfTenantRequestSpec"), + }, + }, + "status": { + SchemaProps: spec.SchemaProps{ + Default: map[string]interface{}{}, + Ref: ref("github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.SelfTenantRequestStatus"), + }, + }, + }, + Required: []string{"spec"}, + }, + }, + Dependencies: []string{ + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.SelfTenantRequestSpec", "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.SelfTenantRequestStatus", v1.ObjectMeta{}.OpenAPIModelName()}, + } +} + +func schema_sdk_apis_tenancy_v1alpha1_SelfTenantRequestList(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "SelfTenantRequestList is the list form, which the API machinery requires; the resource is create-only.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "kind": { + SchemaProps: spec.SchemaProps{ + Description: "Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", + Type: []string{"string"}, + Format: "", + }, + }, + "apiVersion": { + SchemaProps: spec.SchemaProps{ + Description: "APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources", + Type: []string{"string"}, + Format: "", + }, + }, + "metadata": { + SchemaProps: spec.SchemaProps{ + Default: map[string]interface{}{}, + Ref: ref(v1.ListMeta{}.OpenAPIModelName()), + }, + }, + "items": { + SchemaProps: spec.SchemaProps{ + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Ref: ref("github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.SelfTenantRequest"), + }, + }, + }, + }, + }, + }, + Required: []string{"items"}, + }, + }, + Dependencies: []string{ + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1.SelfTenantRequest", v1.ListMeta{}.OpenAPIModelName()}, + } +} + +func schema_sdk_apis_tenancy_v1alpha1_SelfTenantRequestSpec(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "SelfTenantRequestSpec names the tenant to create. The first admin is not here: it is the caller, and the server sets it.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "name": { + SchemaProps: spec.SchemaProps{ + Description: "Name is the tenant's object name, which also seeds its workspace name.", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "displayName": { + SchemaProps: spec.SchemaProps{ + Description: "DisplayName is the tenant's human name. Defaults to Name.", + Type: []string{"string"}, + Format: "", + }, + }, + "description": { + SchemaProps: spec.SchemaProps{ + Description: "Description is free text for humans.", + Type: []string{"string"}, + Format: "", + }, + }, + }, + Required: []string{"name"}, + }, + }, + } +} + +func schema_sdk_apis_tenancy_v1alpha1_SelfTenantRequestStatus(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "SelfTenantRequestStatus reports what the request produced.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "created": { + SchemaProps: spec.SchemaProps{ + Description: "Created is true when this request created the tenant, and false when one of that name already existed — which does not mean the caller can reach it.", + Type: []string{"boolean"}, + Format: "", + }, + }, + "tenant": { + SchemaProps: spec.SchemaProps{ + Description: "Tenant is the tenant's name.", + Type: []string{"string"}, + Format: "", + }, + }, + "message": { + SchemaProps: spec.SchemaProps{ + Description: "Message explains the outcome in a sentence.", + Type: []string{"string"}, + Format: "", + }, + }, + }, + }, + }, + } +} + func schema_sdk_apis_tenancy_v1alpha1_Subject(ref common.ReferenceCallback) common.OpenAPIDefinition { return common.OpenAPIDefinition{ Schema: spec.Schema{ @@ -833,6 +1177,13 @@ func schema_sdk_apis_tenancy_v1alpha1_TenantSpec(ref common.ReferenceCallback) c Format: "", }, }, + "firstAdmin": { + SchemaProps: spec.SchemaProps{ + Description: "FirstAdmin is an identity granted the admin role on this tenant once its workspace is ready, as a Membership the operator creates.\n\nIt exists because a tenant nobody administers is unusable, and the two writes cannot be one: the Membership lives in the tenant's own workspace, which does not exist when the Tenant is created. Naming the admin here lets whoever creates the tenant hand it over without waiting, and is what makes self-service possible — the virtual workspace sets it to the caller, so a caller cannot make someone else the admin of a tenant they asked for.\n\nEmpty means nobody is seeded, which is the right answer when an administrator intends to grant access separately.", + Type: []string{"string"}, + Format: "", + }, + }, }, Required: []string{"displayName"}, }, diff --git a/tenancy/pkg/naming/naming.go b/tenancy/pkg/naming/naming.go index f2fdf9d..2074de1 100644 --- a/tenancy/pkg/naming/naming.go +++ b/tenancy/pkg/naming/naming.go @@ -39,6 +39,10 @@ const maxNameLength = 54 // fallback appends. const suffixLength = 8 +// subjectHashLength is how many hex characters of the subject hash a +// membership name carries. +const subjectHashLength = 6 + // A Strategy proposes workspace names for an object. Propose returns // candidates in preference order; the caller tries each until one is free // or already owned by the same object. The last candidate embeds the @@ -128,6 +132,26 @@ func Slugify(displayName string) string { return truncate(b.String(), maxNameLength) } +// MembershipName derives the object name of a grant from what it grants +// to whom. It is deterministic so that granting the same access twice is +// an update in place rather than a second object saying the same thing — +// which is what lets a role be changed by re-granting it, and what makes +// seeding safe to repeat. +// +// Subject, tenant and project are slugified because they become part of an +// object name: a subject is usually an email address, which is not a DNS +// label. Different subjects can end up with the same slug (alice@x.com, +// ALICE@X.COM and a group called alice.x.com all become alice-x-com), so a +// short hash of the kind and subject is added to tell them apart. +func MembershipName(kind, subject, tenant, project string) string { + sum := sha256.Sum256([]byte(kind + "\x00" + subject)) + name := Slugify(subject) + "-" + hex.EncodeToString(sum[:])[:subjectHashLength] + "-" + Slugify(tenant) + if project != "" { + name += "-" + Slugify(project) + } + return name +} + // truncate shortens s to at most n bytes without leaving a trailing dash. func truncate(s string, n int) string { if len(s) > n { diff --git a/tenancy/pkg/naming/naming_test.go b/tenancy/pkg/naming/naming_test.go index becabc0..bd0c2d9 100644 --- a/tenancy/pkg/naming/naming_test.go +++ b/tenancy/pkg/naming/naming_test.go @@ -104,6 +104,27 @@ func TestCollidingDisplayNamesDivergeOnFallback(t *testing.T) { } } +func TestMembershipNamesKeepSubjectsApart(t *testing.T) { + // All three slugify to alice-x-com. + names := map[string]string{ + "user alice@x.com": MembershipName("User", "alice@x.com", "acme", ""), + "user ALICE@X.COM": MembershipName("User", "ALICE@X.COM", "acme", ""), + "group alice.x.com": MembershipName("Group", "alice.x.com", "acme", ""), + "group alice@x.com": MembershipName("Group", "alice@x.com", "acme", ""), + "project-scoped one": MembershipName("User", "alice@x.com", "acme", "web"), + } + seen := map[string]string{} + for who, name := range names { + if other, ok := seen[name]; ok { + t.Errorf("%s and %s share the name %q", who, other, name) + } + seen[name] = who + } + if a, b := MembershipName("User", "alice", "acme", ""), MembershipName("User", "alice", "acme", ""); a != b { + t.Errorf("MembershipName is not deterministic: %q vs %q", a, b) + } +} + func TestUnknownStrategyIsAnError(t *testing.T) { if _, err := ForName("cute-animals"); err == nil { t.Error("expected an error for an unknown strategy") diff --git a/tenancy/pkg/operator/operator.go b/tenancy/pkg/operator/operator.go index bc79e9b..c8e419e 100644 --- a/tenancy/pkg/operator/operator.go +++ b/tenancy/pkg/operator/operator.go @@ -52,10 +52,8 @@ import ( mcreconcile "sigs.k8s.io/multicluster-runtime/pkg/reconcile" metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" - "k8s.io/apimachinery/pkg/apis/meta/v1/unstructured" "k8s.io/apimachinery/pkg/runtime" "k8s.io/apimachinery/pkg/runtime/schema" - "k8s.io/apimachinery/pkg/types" utilruntime "k8s.io/apimachinery/pkg/util/runtime" "k8s.io/client-go/dynamic" "k8s.io/client-go/kubernetes/scheme" @@ -196,17 +194,6 @@ func Run(ctx context.Context, opts Options) error { return fmt.Errorf("build membership controller: %w", err) } - // Every slice needs the same nudge: kcp computes a slice's URLs when - // the slice object is reconciled, and a consumer binding the export is - // not a slice event. - for _, slice := range []string{opts.PlatformSlice, opts.TenancySlice, opts.ProvisionerSlice, opts.AccessSlice} { - if err := m.platform.GetLocalManager().Add(manager.RunnableFunc(func(ctx context.Context) error { - return nudgeEndpointSlice(ctx, opts.RestConfig, slice, logger) - })); err != nil { - return fmt.Errorf("register endpoint slice nudger for %s: %w", slice, err) - } - } - logger.Info("tenancy operator running", "tenantStore", "(the clusters bound to "+opts.PlatformSlice+")", "provisioningParent", opts.TenantsPath+" ("+tenantsCluster+")", @@ -319,42 +306,3 @@ func requeueAfterStatus(err error) (ctrl.Result, error) { } return requeue() } - -var endpointSliceGVR = schema.GroupVersionResource{ - Group: "apis.kcp.io", Version: "v1alpha1", Resource: "apiexportendpointslices", -} - -func nudgeEndpointSlice(ctx context.Context, cfg *rest.Config, sliceName string, logger logr.Logger) error { - dyn, err := dynamic.NewForConfig(cfg) - if err != nil { - return fmt.Errorf("build dynamic client: %w", err) - } - - ticker := time.NewTicker(20 * time.Second) - defer ticker.Stop() - - for { - select { - case <-ctx.Done(): - return nil - case <-ticker.C: - } - - slice, err := dyn.Resource(endpointSliceGVR).Get(ctx, sliceName, metav1.GetOptions{}) - if err != nil { - logger.V(2).Info("endpoint slice nudge: get failed", "slice", sliceName, "error", err.Error()) - continue - } - endpoints, _, _ := unstructured.NestedSlice(slice.Object, "status", "endpoints") - if len(endpoints) > 0 { - continue - } - - patch := fmt.Sprintf(`{"metadata":{"annotations":{%q:%q}}}`, bootstrap.NudgeAnnotation, time.Now().UTC().Format(time.RFC3339)) - if _, err := dyn.Resource(endpointSliceGVR).Patch(ctx, sliceName, types.MergePatchType, []byte(patch), metav1.PatchOptions{}); err != nil { - logger.V(2).Info("endpoint slice nudge: patch failed", "slice", sliceName, "error", err.Error()) - continue - } - logger.V(2).Info("nudged URL-less endpoint slice", "slice", sliceName) - } -} diff --git a/tenancy/pkg/operator/tenant.go b/tenancy/pkg/operator/tenant.go index b1b2748..96e0f88 100644 --- a/tenancy/pkg/operator/tenant.go +++ b/tenancy/pkg/operator/tenant.go @@ -18,6 +18,7 @@ package operator import ( "context" + "fmt" ctrl "sigs.k8s.io/controller-runtime" "sigs.k8s.io/controller-runtime/pkg/client" @@ -26,8 +27,11 @@ import ( mcreconcile "sigs.k8s.io/multicluster-runtime/pkg/reconcile" apierrors "k8s.io/apimachinery/pkg/api/errors" + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + "sigs.k8s.io/multicluster-runtime/pkg/multicluster" "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/pkg/bootstrap" + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/pkg/naming" tenancyv1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1" ) @@ -111,10 +115,85 @@ func (r *reconcilers) reconcileTenant(ctx context.Context, req mcreconcile.Reque if !ws.Ready { return requeue() } + + // The tenant's workspace exists now, so the first admin can finally be + // granted. This is the second half of a write that could not be one: + // the Membership lives in a workspace that did not exist when the + // Tenant was created. + if err := r.seedFirstAdmin(ctx, c, &tenant, ws.Cluster); err != nil { + return ctrl.Result{}, err + } + logger.V(2).Info("tenant ready", "workspace", ws.Name, "workspaceCluster", ws.Cluster) return ctrl.Result{}, nil } +// firstAdminSeededAnnotation is set on a Tenant once its first admin has +// been granted, so the grant is made only once. +const firstAdminSeededAnnotation = "tenancy.platform.kcp.io/first-admin-seeded" + +// seedFirstAdmin grants spec.firstAdmin the admin role on the tenant, once. +// +// This seeds the first admin, it does not keep them. Whoever holds the +// tenant afterwards may revoke it like any other grant, and it must not +// come back, so the Tenant is marked once the grant is made. +func (r *reconcilers) seedFirstAdmin(ctx context.Context, platform client.Client, tenant *tenancyv1alpha1.Tenant, cluster string) error { + if tenant.Spec.FirstAdmin == "" || tenant.Annotations[firstAdminSeededAnnotation] == "true" { + return nil + } + + c, err := clientFor(ctx, r.m.tenancy, multicluster.ClusterName(cluster)) + if err != nil { + // The tenant tier is served by the tenancy export, which the new + // workspace binds through its WorkspaceType. A moment after the + // workspace is ready that binding may still be settling. + return err + } + + // Same shape as the CLI's grant naming, so a seeded grant and a + // hand-made one for the same subject are the same object rather than + // two that fight. + name := naming.MembershipName(string(tenancyv1alpha1.SubjectKindUser), tenant.Spec.FirstAdmin, tenant.Name, "") + membership := &tenancyv1alpha1.Membership{ + ObjectMeta: metav1.ObjectMeta{Name: name}, + Spec: tenancyv1alpha1.MembershipSpec{ + Subject: tenancyv1alpha1.Subject{ + Kind: tenancyv1alpha1.SubjectKindUser, + Name: tenant.Spec.FirstAdmin, + }, + Role: tenancyv1alpha1.RoleAdmin, + Tenant: tenant.Name, + }, + } + err = c.Create(ctx, membership) + if apierrors.IsAlreadyExists(err) { + // The same user already has a grant on the tenant, maybe with a + // lower role. Make it admin, or the tenant could end up with none. + var existing tenancyv1alpha1.Membership + if err := c.Get(ctx, client.ObjectKey{Name: name}, &existing); err != nil { + return fmt.Errorf("get the existing grant of tenant %q's first admin: %w", tenant.Name, err) + } + if existing.Spec.Role != tenancyv1alpha1.RoleAdmin { + existing.Spec.Role = tenancyv1alpha1.RoleAdmin + if err := c.Update(ctx, &existing); err != nil { + return fmt.Errorf("make tenant %q's first admin an admin: %w", tenant.Name, err) + } + } + } else if err != nil { + return fmt.Errorf("seed the first admin of tenant %q: %w", tenant.Name, err) + } + + patch := client.MergeFrom(tenant.DeepCopy()) + if tenant.Annotations == nil { + tenant.Annotations = map[string]string{} + } + tenant.Annotations[firstAdminSeededAnnotation] = "true" + if err := platform.Patch(ctx, tenant, patch); err != nil { + return fmt.Errorf("mark tenant %q's first admin as seeded: %w", tenant.Name, err) + } + return nil +} + func updateTenantStatus(ctx context.Context, c client.Client, tenant *tenancyv1alpha1.Tenant, status tenancyv1alpha1.TenantStatus) error { if tenant.Status == status { return nil diff --git a/tenancy/pkg/operator/workspaces.go b/tenancy/pkg/operator/workspaces.go index f3d0fa2..c310282 100644 --- a/tenancy/pkg/operator/workspaces.go +++ b/tenancy/pkg/operator/workspaces.go @@ -27,15 +27,13 @@ import ( corev1alpha1 "github.com/kcp-dev/sdk/apis/core/v1alpha1" kcptenancyv1alpha1 "github.com/kcp-dev/sdk/apis/tenancy/v1alpha1" - - tenancyv1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1" ) // ownerUIDLabel ties a provisioned Workspace to the Tenant or Project that // asked for it. It is how a reconcile recognizes its own workspace among // naming candidates, and how a collision with someone else's workspace is // told apart from an earlier run of the same reconcile. -const ownerUIDLabel = tenancyv1alpha1.GroupName + "/owner-uid" +const ownerUIDLabel = "tenancy.kcp.hub/owner-uid" // provisioned describes the workspace a tenant or project ended up with. type provisioned struct { diff --git a/tenancy/pkg/provider/clusters.go b/tenancy/pkg/provider/clusters.go new file mode 100644 index 0000000..9345766 --- /dev/null +++ b/tenancy/pkg/provider/clusters.go @@ -0,0 +1,109 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package provider + +import ( + "context" + "fmt" + + apierrors "k8s.io/apimachinery/pkg/api/errors" + "sigs.k8s.io/controller-runtime/pkg/client" + mcmanager "sigs.k8s.io/multicluster-runtime/pkg/manager" + "sigs.k8s.io/multicluster-runtime/pkg/multicluster" +) + +// Clusters hands out a client for one logical cluster in the fleet. +// +// An APIExport's virtual workspace runs per shard: the endpoint slice +// lists one URL for each shard serving the export, and each of those URLs +// serves only the clusters that live on that shard. So there is no single +// URL a write can be addressed to. Asking a shard about a cluster it does +// not host is refused as a plain Forbidden — that shard has no APIBinding +// for the cluster, and the virtual workspace's authorizer anonymizes the +// reason, so the answer is indistinguishable from the caller having no +// standing at all. +// +// The read side already solves this: the provider watches every URL the +// slice publishes and knows which endpoint each cluster was discovered +// through. Clusters exposes that, so a write goes to the shard that +// actually holds the workspace rather than to whichever URL happened to +// be listed first. +type Clusters struct { + // ready is closed once Run has built the managers. Everything below is + // written before the close and only read after it, which is what makes + // the handoff to request handlers safe without a lock. + ready chan struct{} + platform mcmanager.Manager + tenancy mcmanager.Manager +} + +// NewClusters returns a Clusters that Run fills in. +func NewClusters() *Clusters { + return &Clusters{ready: make(chan struct{})} +} + +func (c *Clusters) set(platform, tenancy mcmanager.Manager) { + c.platform, c.tenancy = platform, tenancy + close(c.ready) +} + +// Tenancy returns a client for a tenant workspace, which is where Projects +// and Memberships live. +func (c *Clusters) Tenancy(ctx context.Context, cluster string) (client.Client, error) { + if err := c.wait(ctx); err != nil { + return nil, err + } + return clientFor(ctx, c.tenancy, cluster) +} + +// Platform returns a client for a workspace in the platform tier, which is +// where Tenant records live. +func (c *Clusters) Platform(ctx context.Context, cluster string) (client.Client, error) { + if err := c.wait(ctx); err != nil { + return nil, err + } + return clientFor(ctx, c.platform, cluster) +} + +// wait blocks until the managers exist. In practice they always do by the +// time a write is attempted: every write is authorized against the +// directory first, and the directory is not ready until both managers have +// synced. +func (c *Clusters) wait(ctx context.Context) error { + select { + case <-c.ready: + return nil + case <-ctx.Done(): + return apierrors.NewServiceUnavailable("the tenancy directory is still starting") + } +} + +func clientFor(ctx context.Context, mgr mcmanager.Manager, cluster string) (client.Client, error) { + if cluster == "" { + return nil, fmt.Errorf("no logical cluster given") + } + cl, err := mgr.GetCluster(ctx, multicluster.ClusterName(cluster)) + if err != nil { + // A cluster the provider has not discovered is one no shard has + // reported binding the export — usually a workspace that is still + // initializing, which is worth retrying rather than reporting as a + // refusal. + return nil, apierrors.NewServiceUnavailable(fmt.Sprintf( + "workspace %s has not joined the fleet yet: %v", cluster, err)) + } + return cl.GetClient(), nil +} diff --git a/tenancy/pkg/provider/provider.go b/tenancy/pkg/provider/provider.go index 395a63a..3f937fe 100644 --- a/tenancy/pkg/provider/provider.go +++ b/tenancy/pkg/provider/provider.go @@ -14,7 +14,7 @@ See the License for the specific language governing permissions and limitations under the License. */ -// Package provider populates the tenancy directory from the organization +// Package provider populates the tenancy directory from the tenant // workspaces bound to the tenancy APIExport. It is the read side of the // operator: the same discovery (multicluster-runtime over the apiexport // endpoint slice), but instead of materializing workspaces it only mirrors @@ -63,6 +63,10 @@ type Options struct { // different tiers, so the directory is fed by two managers. PlatformSlice string TenancySlice string + // Clusters, when non-nil, is filled with a handle on the two managers, + // so the caller can address a write to the shard that hosts a given + // workspace. See the type for why that is not a free choice. + Clusters *Clusters } // Run fills dir until ctx is cancelled. It marks the directory ready once @@ -112,6 +116,10 @@ func Run(ctx context.Context, opts Options, dir *directory.Directory) error { return err } + if opts.Clusters != nil { + opts.Clusters.set(platform, tenancy) + } + if err := registerTenantMirror(platform, dir); err != nil { return err } @@ -161,7 +169,7 @@ func (c clusterLifecycle) OnDelete(obj client.Object) { if cluster == "" { return } - c.logger.Info("organization workspace left the fleet, dropping from directory", "cluster", cluster) + c.logger.Info("workspace left the fleet, dropping from directory", "cluster", cluster) c.dir.ForgetCluster(cluster) } diff --git a/tenancy/pkg/server/options.go b/tenancy/pkg/server/options.go index 744abd3..f32bcd6 100644 --- a/tenancy/pkg/server/options.go +++ b/tenancy/pkg/server/options.go @@ -55,6 +55,14 @@ type Options struct { // workspace endpoints in review answers. EndpointBase string + // SelfServiceTenants lets a caller with no membership request a tenant + // and become its admin. SelfServiceTenantGroups narrows who may. + SelfServiceTenants bool + SelfServiceTenantGroups []string + // StoreWorkspace is where Tenant records live; a requested tenant is + // created there. + StoreWorkspace string + // PlatformSlice and TenancySlice are the endpoint slices the directory // is fed from: Tenants come from the platform tier, Projects and // Memberships from inside each tenant's workspace. @@ -91,6 +99,18 @@ func (o *Options) AddFlags(fs *pflag.FlagSet) { fs.StringVar(&o.EndpointBase, "endpoint-base", "https://kcp.example.com/clusters/", "FrontProxy URL prefix for workspace endpoints returned in review answers.") + // Self-service tenants: how someone with no membership gets started. + // Off by default, because handing out tenants is a decision a + // deployment makes rather than one this server makes for it. + fs.BoolVar(&o.SelfServiceTenants, "self-service-tenants", false, + "Let any authenticated caller request a tenant, becoming its admin. "+ + "Off means tenants are an administrator's job.") + fs.StringSliceVar(&o.SelfServiceTenantGroups, "self-service-tenant-groups", nil, + "Restrict --self-service-tenants to callers in one of these groups, as kcp sees them. "+ + "Empty means any authenticated caller.") + fs.StringVar(&o.StoreWorkspace, "store-workspace", bootstrap.DefaultWorkspacePrefix+":"+bootstrap.DefaultStoreWorkspace, + "Path of the workspace Tenant records live in, written to when a tenant is requested.") + fs.StringVar(&o.PlatformSlice, "platform-endpointslice", bootstrap.ExportPlatform, "APIExportEndpointSlice serving Tenants.") fs.StringVar(&o.TenancySlice, "tenancy-endpointslice", bootstrap.ExportTenancy, @@ -102,6 +122,27 @@ func (o *Options) AddFlags(fs *pflag.FlagSet) { if fs.Lookup("kubeconfig") == nil { fs.StringVar(&o.Kubeconfig, "kubeconfig", "", "Path to the kubeconfig for the target kcp (required).") } + + addIgnoredOperatorFlags(fs) +} + +// addIgnoredOperatorFlags accepts, and ignores, flags the kcp-operator +// puts on every VirtualWorkspace deployment. +// +// --shard-external-url is one of kcp's own virtual-workspace server's +// flags and means nothing here, but the operator appends it +// unconditionally (internal/resources/compiledvirtualworkspace: +// "TODO(ntnn): We need a way to shut this off if it isn't required"), +// even though the API type documents spec.command as suppressing it +// "because a custom server would reject the unknown flags and refuse to +// start". An apiserver built on pflag exits on a flag it does not know, +// so accepting it is what lets this server be deployed by the operator +// at all. Remove once the operator stops sending it. +func addIgnoredOperatorFlags(fs *pflag.FlagSet) { + var ignored string + fs.StringVar(&ignored, "shard-external-url", "", + "Ignored. Accepted only because the kcp-operator passes it to every virtual workspace.") + _ = fs.MarkHidden("shard-external-url") } // Complete fills in derived defaults. diff --git a/tenancy/pkg/server/projects.go b/tenancy/pkg/server/projects.go new file mode 100644 index 0000000..cef54c6 --- /dev/null +++ b/tenancy/pkg/server/projects.go @@ -0,0 +1,210 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package server + +import ( + "context" + "fmt" + "strings" + + apierrors "k8s.io/apimachinery/pkg/api/errors" + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + "k8s.io/apimachinery/pkg/runtime/schema" + "k8s.io/client-go/dynamic" + "k8s.io/client-go/rest" + "k8s.io/client-go/util/retry" + "sigs.k8s.io/controller-runtime/pkg/client" + + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/pkg/provider" + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/pkg/virtual/membership" + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/pkg/virtual/selfprojectrequest" + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/pkg/virtual/selftenantrequest" + tenancyv1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1" +) + +// projectWriter creates Projects in tenant workspaces through the tenancy +// APIExport's virtual workspace — the same export the directory reads, so +// the server needs no reach it does not already have. +// +// This is the credential a tenant admin deliberately does not hold. What +// keeps that honest is the narrowness of what it is used for: the storage +// authorizes the caller first, and then exactly one object is created +// from fields the caller controls. Nothing here can name a workspace, +// choose a cluster, or touch a Membership. +type projectWriter struct { + clusters *provider.Clusters +} + +func newProjectWriter(clusters *provider.Clusters) *projectWriter { + return &projectWriter{clusters: clusters} +} + +// CreateProject satisfies selfprojectrequest.CreateProjectFunc. +func (w *projectWriter) CreateProject(ctx context.Context, cluster string, project *tenancyv1alpha1.Project) (bool, error) { + c, err := w.clusters.Tenancy(ctx, cluster) + if err != nil { + return false, err + } + + if err := c.Create(ctx, project); err != nil { + // Asking twice is not an error: the request says what should + // exist, and it does. + if apierrors.IsAlreadyExists(err) { + return false, nil + } + return false, fmt.Errorf("create project %q in tenant workspace %s: %w", project.Name, cluster, err) + } + return true, nil +} + +var _ selfprojectrequest.CreateProjectFunc = (*projectWriter)(nil).CreateProject + +// membershipWriter changes grants inside tenant workspaces, through the +// same export the directory reads them from. +// +// This is the credential a tenant admin cannot hold: the grants governing +// their own access live beside the projects. What keeps it honest is that +// the storage authorizes the caller as an admin of that very tenant first, +// and derives both the cluster and the object name itself — nothing the +// caller sends chooses where a write lands. +type membershipWriter struct { + clusters *provider.Clusters +} + +func newMembershipWriter(clusters *provider.Clusters) *membershipWriter { + return &membershipWriter{clusters: clusters} +} + +// Create satisfies membership.CreateFunc. Re-granting the same access is +// an update in place rather than a conflict, because the request states +// what should be true and the name is derived from that. +func (w *membershipWriter) Create(ctx context.Context, cluster string, m *tenancyv1alpha1.Membership) (bool, error) { + c, err := w.clusters.Tenancy(ctx, cluster) + if err != nil { + return false, err + } + + if err := c.Create(ctx, m); err == nil { + return true, nil + } else if !apierrors.IsAlreadyExists(err) { + return false, fmt.Errorf("grant %q in tenant workspace %s: %w", m.Name, cluster, err) + } + + // Already there: bring the role (and anything else in the spec) to what + // was asked for, retrying the read-modify-write on a conflicting update. + spec := m.Spec + err = retry.RetryOnConflict(retry.DefaultRetry, func() error { + var existing tenancyv1alpha1.Membership + if err := c.Get(ctx, client.ObjectKey{Name: m.Name}, &existing); err != nil { + return err + } + if existing.Spec == spec { + return nil + } + existing.Spec = spec + return c.Update(ctx, &existing) + }) + if err != nil { + return false, fmt.Errorf("update grant %q in tenant workspace %s: %w", m.Name, cluster, err) + } + return false, nil +} + +// Delete satisfies membership.DeleteFunc. +func (w *membershipWriter) Delete(ctx context.Context, cluster, name string) error { + c, err := w.clusters.Tenancy(ctx, cluster) + if err != nil { + return err + } + m := &tenancyv1alpha1.Membership{ObjectMeta: metav1.ObjectMeta{Name: name}} + if err := c.Delete(ctx, m); err != nil { + // Gone is the state that was asked for. + if apierrors.IsNotFound(err) { + return nil + } + return fmt.Errorf("revoke %q in tenant workspace %s: %w", name, cluster, err) + } + return nil +} + +var ( + _ membership.CreateFunc = (*membershipWriter)(nil).Create + _ membership.DeleteFunc = (*membershipWriter)(nil).Delete +) + +// tenantWriter creates Tenants in the store workspace through the platform +// APIExport — the same export the directory reads Tenants from. +// +// Only one operation is offered through it, and the Tenant it writes names +// its first admin, so the credential cannot be used to grant anything to +// anyone the caller is not. +type tenantWriter struct { + clusters *provider.Clusters + store string +} + +func newTenantWriter(clusters *provider.Clusters, store string) *tenantWriter { + return &tenantWriter{clusters: clusters, store: store} +} + +// CreateTenant satisfies selftenantrequest.CreateTenantFunc. +func (w *tenantWriter) CreateTenant(ctx context.Context, tenant *tenancyv1alpha1.Tenant) (bool, error) { + c, err := w.clusters.Platform(ctx, w.store) + if err != nil { + return false, err + } + + if err := c.Create(ctx, tenant); err != nil { + if apierrors.IsAlreadyExists(err) { + return false, nil + } + return false, fmt.Errorf("create tenant %q: %w", tenant.Name, err) + } + return true, nil +} + +var _ selftenantrequest.CreateTenantFunc = (*tenantWriter)(nil).CreateTenant + +// resolveCluster reads the logical cluster name of a workspace path. +// +// The writers address workspaces by cluster rather than by path, because +// an APIExport's virtual workspace serves clusters: it has no view of the +// tree the path walks. +func resolveCluster(cfg *rest.Config, path string) (string, error) { + scoped := rest.CopyConfig(cfg) + host := scoped.Host + if i := strings.Index(host, "/clusters/"); i >= 0 { + host = host[:i] + } + scoped.Host = strings.TrimSuffix(host, "/") + "/clusters/" + path + + dyn, err := dynamic.NewForConfig(scoped) + if err != nil { + return "", fmt.Errorf("build dynamic client: %w", err) + } + lc, err := dyn.Resource(schema.GroupVersionResource{ + Group: "core.kcp.io", Version: "v1alpha1", Resource: "logicalclusters", + }).Get(context.Background(), "cluster", metav1.GetOptions{}) + if err != nil { + return "", err + } + name := lc.GetAnnotations()["kcp.io/cluster"] + if name == "" { + return "", fmt.Errorf("the LogicalCluster of %s carries no kcp.io/cluster annotation", path) + } + return name, nil +} diff --git a/tenancy/pkg/server/server.go b/tenancy/pkg/server/server.go index 685d5e0..1a06c68 100644 --- a/tenancy/pkg/server/server.go +++ b/tenancy/pkg/server/server.go @@ -15,7 +15,7 @@ limitations under the License. */ // Package server wires the tenancy virtual workspace binary together: the -// directory, the provider that fills it from organization workspaces, and +// 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 @@ -46,7 +46,9 @@ import ( "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/pkg/directory" generatedopenapi "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/pkg/generated/openapi" "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/pkg/provider" + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/pkg/virtual/membership" "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/pkg/virtual/selftenancyreview" + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/pkg/virtual/selftenantrequest" tenancyv1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1" ) @@ -90,12 +92,18 @@ func Run(ctx context.Context, o *Options) error { dir := directory.New() + // The writes below go through the same discovery that fills the + // directory, which is what makes them land on the shard that actually + // hosts the workspace. + clusters := provider.NewClusters() + providerErr := make(chan error, 1) go func() { providerErr <- provider.Run(ctx, provider.Options{ RestConfig: restConfig, PlatformSlice: o.PlatformSlice, TenancySlice: o.TenancySlice, + Clusters: clusters, }, dir) }() @@ -103,12 +111,41 @@ func Run(ctx context.Context, o *Options) error { "platformSlice", o.PlatformSlice, "tenancySlice", o.TenancySlice, "kubeconfig", o.Kubeconfig, "host", restConfig.Host) + scheme := runtime.NewScheme() + utilruntime.Must(tenancyv1alpha1.AddToScheme(scheme)) + + // The writes this server performs on a caller's behalf, all through + // the tenancy export, because the tenant tier is closed to its own + // members by design: a project in a tenant they administer, and the + // grants deciding who else may reach it. + writer := newProjectWriter(clusters) + grants := newMembershipWriter(clusters) + + // And the one that starts someone off with nothing: a tenant, with + // themselves as its admin. Off unless the deployment enabled it. + storeCluster, err := resolveCluster(restConfig, o.StoreWorkspace) + if err != nil && o.SelfServiceTenants { + return fmt.Errorf("resolve the tenant store %s: %w", o.StoreWorkspace, err) + } + tenants := newTenantWriter(clusters, storeCluster) + vws := []rootapiserver.NamedVirtualWorkspace{ - selftenancyreview.NewVirtualWorkspace(dir, endpointFor(o.EndpointBase)), + selftenancyreview.NewVirtualWorkspace(selftenancyreview.Config{ + Directory: dir, + EndpointFor: endpointFor(o.EndpointBase), + CreateProject: writer.CreateProject, + Tenants: selftenantrequest.Options{ + Enabled: o.SelfServiceTenants, + Groups: o.SelfServiceTenantGroups, + }, + CreateTenant: tenants.CreateTenant, + Memberships: membership.Options{ + Create: grants.Create, + Delete: grants.Delete, + }, + }), } - scheme := runtime.NewScheme() - utilruntime.Must(tenancyv1alpha1.AddToScheme(scheme)) codecs := serializer.NewCodecFactory(scheme) recommended := genericapiserver.NewRecommendedConfig(codecs) @@ -189,8 +226,7 @@ func Run(ctx context.Context, o *Options) error { if err != nil && !errors.Is(err, context.Canceled) { return fmt.Errorf("directory provider failed: %w", err) } - <-serveErr - return nil + return <-serveErr case err := <-serveErr: return err } diff --git a/tenancy/pkg/virtual/membership/storage.go b/tenancy/pkg/virtual/membership/storage.go new file mode 100644 index 0000000..4c81a40 --- /dev/null +++ b/tenancy/pkg/virtual/membership/storage.go @@ -0,0 +1,377 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// Package membership serves the grants of the tenants a caller +// administers, so RBAC can be managed without entering the workspace the +// grants live in. +// +// Memberships live inside their tenant's workspace, which is closed to the +// tenant's own members — including its admins — precisely because it holds +// the records that decide their access. That makes it the one part of the +// model a tenant admin cannot administer directly, which is not a gap to +// leave open: someone has to be able to add a colleague. +// +// So this is mediated the same way project creation is. The caller's own +// admin Membership, as the directory already reports it, is the +// authorization; the server's credential performs the write; and what is +// offered through it is only ever a Membership in a tenant the caller +// already administers. A caller cannot name a workspace or a cluster, and +// cannot reach a tenant they do not administer — not even to discover that +// it exists. +// +// Listing here is deliberately wider than a self-review: it reports what +// OTHER people hold, which is the point of administering access, and is +// why every path checks for admin rather than for mere membership. +package membership + +import ( + "context" + "fmt" + "slices" + "sort" + + apierrors "k8s.io/apimachinery/pkg/api/errors" + metainternalversion "k8s.io/apimachinery/pkg/apis/meta/internalversion" + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + "k8s.io/apimachinery/pkg/runtime" + "k8s.io/apimachinery/pkg/util/validation/field" + "k8s.io/apiserver/pkg/authentication/user" + genericapirequest "k8s.io/apiserver/pkg/endpoints/request" + "k8s.io/apiserver/pkg/registry/rest" + "k8s.io/klog/v2" + + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/pkg/directory" + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/pkg/naming" + tenancyv1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1" +) + +// CreateFunc upserts a Membership in one tenant's workspace. The server +// supplies it, because how the virtual workspace reaches that workspace is +// a detail of the deployment rather than of the API. +type CreateFunc func(ctx context.Context, cluster string, m *tenancyv1alpha1.Membership) (created bool, err error) + +// DeleteFunc removes a Membership from one tenant's workspace. +type DeleteFunc func(ctx context.Context, cluster, name string) error + +// Options carries the write side. Both funcs may be nil, in which case the +// resource stays readable and says plainly that changing grants is not +// configured rather than appearing to work. +type Options struct { + Create CreateFunc + Delete DeleteFunc +} + +// REST serves memberships for the tenants the caller administers. +type REST struct { + directory *directory.Directory + opts Options +} + +var ( + _ rest.Storage = &REST{} + _ rest.Lister = &REST{} + _ rest.Getter = &REST{} + _ rest.Creater = &REST{} + _ rest.GracefulDeleter = &REST{} + _ rest.Scoper = &REST{} + _ rest.SingularNameProvider = &REST{} +) + +// NewREST returns the storage. +func NewREST(d *directory.Directory, opts Options) *REST { + return &REST{directory: d, opts: opts} +} + +func (r *REST) New() runtime.Object { return &tenancyv1alpha1.Membership{} } + +func (r *REST) NewList() runtime.Object { return &tenancyv1alpha1.MembershipList{} } + +func (r *REST) Destroy() {} + +func (r *REST) NamespaceScoped() bool { return false } + +func (r *REST) GetSingularName() string { return "membership" } + +func (r *REST) ConvertToTable(ctx context.Context, object runtime.Object, tableOptions runtime.Object) (*metav1.Table, error) { + return rest.NewDefaultTableConvertor(tenancyv1alpha1.Resource("memberships")). + ConvertToTable(ctx, object, tableOptions) +} + +// List returns every grant in every tenant the caller administers. +// +// There is no scoping parameter: the answer is the caller's whole +// administrative surface, and a client that cares about one tenant filters +// on spec.tenant. That keeps the authorization rule here a single +// sentence, which is worth more than saving the client a loop. +func (r *REST) List(ctx context.Context, _ *metainternalversion.ListOptions) (runtime.Object, error) { + admin, err := r.adminTenants(ctx) + if err != nil { + return nil, err + } + + list := &tenancyv1alpha1.MembershipList{} + for _, claim := range admin { + for _, m := range r.directory.MembershipsIn(claim.Cluster) { + list.Items = append(list.Items, membershipObject(m)) + } + } + // Stable across calls: by tenant, then by name. + sort.Slice(list.Items, func(i, j int) bool { + if list.Items[i].Spec.Tenant != list.Items[j].Spec.Tenant { + return list.Items[i].Spec.Tenant < list.Items[j].Spec.Tenant + } + return list.Items[i].Name < list.Items[j].Name + }) + return list, nil +} + +// Get returns one grant, if it is in a tenant the caller administers. +func (r *REST) Get(ctx context.Context, name string, _ *metav1.GetOptions) (runtime.Object, error) { + admin, err := r.adminTenants(ctx) + if err != nil { + return nil, err + } + for _, claim := range admin { + for _, m := range r.directory.MembershipsIn(claim.Cluster) { + if m.Name == name { + out := membershipObject(m) + return &out, nil + } + } + } + return nil, apierrors.NewNotFound(tenancyv1alpha1.Resource("memberships"), name) +} + +// Create grants access in a tenant the caller administers. +// +// The object's name is derived from what is being granted to whom, not +// taken from the request: two requests saying the same thing are the same +// grant, so re-granting changes the role in place instead of leaving two +// objects disagreeing about it. +func (r *REST) Create(ctx context.Context, obj runtime.Object, _ rest.ValidateObjectFunc, _ *metav1.CreateOptions) (runtime.Object, error) { + m, ok := obj.(*tenancyv1alpha1.Membership) + if !ok { + return nil, apierrors.NewBadRequest(fmt.Sprintf("not a Membership: %T", obj)) + } + if r.opts.Create == nil { + return nil, apierrors.NewServiceUnavailable( + "this virtual workspace was started without membership management; grants are read-only here") + } + + if errs := validateSpec(&m.Spec); len(errs) > 0 { + return nil, apierrors.NewInvalid( + tenancyv1alpha1.SchemeGroupVersion.WithKind("Membership").GroupKind(), m.Name, errs) + } + + claim, err := r.adminOn(ctx, m.Spec.Tenant) + if err != nil { + return nil, err + } + // A grant naming a project that does not exist would be a grant that + // never applies to anything — worth refusing while the caller is still + // looking at it. + if m.Spec.Project != "" && !slices.ContainsFunc(claim.Projects, + func(p tenancyv1alpha1.ProjectClaim) bool { return p.Name == m.Spec.Project }) { + return nil, apierrors.NewInvalid( + tenancyv1alpha1.SchemeGroupVersion.WithKind("Membership").GroupKind(), m.Name, + field.ErrorList{field.NotFound( + field.NewPath("spec", "project"), m.Spec.Project)}) + } + + grant := &tenancyv1alpha1.Membership{ + ObjectMeta: metav1.ObjectMeta{ + Name: naming.MembershipName(string(m.Spec.Subject.Kind), m.Spec.Subject.Name, m.Spec.Tenant, m.Spec.Project), + }, + Spec: m.Spec, + } + + // Granting again changes the role of the existing grant. Do not let that + // turn the last tenant admin into a non-admin, same as Delete. + grants := r.directory.MembershipsIn(claim.Cluster) + if idx := slices.IndexFunc(grants, func(g directory.NamedMembership) bool { return g.Name == grant.Name }); idx >= 0 { + existing := grants[idx] + if existing.Role == string(tenancyv1alpha1.RoleAdmin) && existing.Project == "" && + m.Spec.Role != tenancyv1alpha1.RoleAdmin && lastTenantAdmin(grants, m.Spec.Tenant) { + return nil, apierrors.NewForbidden( + tenancyv1alpha1.Resource("memberships"), grant.Name, + fmt.Errorf("this is the last admin of tenant %q; grant admin to someone else first", m.Spec.Tenant)) + } + } + + created, err := r.opts.Create(ctx, claim.Cluster, grant) + if err != nil { + return nil, err + } + + user, _ := genericapirequest.UserFrom(ctx) + klog.FromContext(ctx).V(2).Info("granted membership", + "by", userName(user), "subject", m.Spec.Subject.Name, "role", m.Spec.Role, + "tenant", m.Spec.Tenant, "project", m.Spec.Project, + "cluster", claim.Cluster, "created", created) + + return grant, nil +} + +// Delete revokes a grant in a tenant the caller administers. +func (r *REST) Delete(ctx context.Context, name string, _ rest.ValidateObjectFunc, _ *metav1.DeleteOptions) (runtime.Object, bool, error) { + if r.opts.Delete == nil { + return nil, false, apierrors.NewServiceUnavailable( + "this virtual workspace was started without membership management; grants are read-only here") + } + + admin, err := r.adminTenants(ctx) + if err != nil { + return nil, false, err + } + + for _, claim := range admin { + grants := r.directory.MembershipsIn(claim.Cluster) + idx := slices.IndexFunc(grants, func(m directory.NamedMembership) bool { return m.Name == name }) + if idx < 0 { + continue + } + found := grants[idx] + + // Refuse the one deletion that cannot be undone through this API: + // removing the last tenant-wide admin leaves nobody who may grant + // anything, including the grant that would fix it. + if found.Role == string(tenancyv1alpha1.RoleAdmin) && found.Project == "" && + lastTenantAdmin(grants, found.Tenant) { + return nil, false, apierrors.NewForbidden( + tenancyv1alpha1.Resource("memberships"), name, + fmt.Errorf("this is the last admin of tenant %q; grant admin to someone else first, "+ + "or nobody will be able to", found.Tenant)) + } + + if err := r.opts.Delete(ctx, claim.Cluster, name); err != nil { + return nil, false, err + } + + user, _ := genericapirequest.UserFrom(ctx) + klog.FromContext(ctx).V(2).Info("revoked membership", + "by", userName(user), "name", name, "tenant", found.Tenant, "cluster", claim.Cluster) + + out := membershipObject(found) + return &out, true, nil + } + + return nil, false, apierrors.NewNotFound(tenancyv1alpha1.Resource("memberships"), name) +} + +// adminTenants returns the caller's claims on the tenants they administer +// and whose workspace exists. +func (r *REST) adminTenants(ctx context.Context) ([]tenancyv1alpha1.TenantClaim, error) { + if !r.directory.Ready() { + return nil, apierrors.NewServiceUnavailable("tenancy directory is not ready; try again shortly") + } + user, ok := genericapirequest.UserFrom(ctx) + if !ok { + return nil, apierrors.NewUnauthorized("no user present in request context") + } + + // noEndpoints: this path needs roles and clusters, not URLs. + var admin []tenancyv1alpha1.TenantClaim + for _, claim := range r.directory.ReviewFor(user.GetName(), user.GetGroups(), noEndpoints) { + if slices.Contains(claim.Roles, string(tenancyv1alpha1.RoleAdmin)) && claim.Cluster != "" { + admin = append(admin, claim) + } + } + return admin, nil +} + +// adminOn resolves one tenant the caller administers, or explains the +// refusal without revealing whether the tenant exists. +func (r *REST) adminOn(ctx context.Context, tenant string) (tenancyv1alpha1.TenantClaim, error) { + admin, err := r.adminTenants(ctx) + if err != nil { + return tenancyv1alpha1.TenantClaim{}, err + } + for _, claim := range admin { + if claim.Name == tenant { + return claim, nil + } + } + return tenancyv1alpha1.TenantClaim{}, apierrors.NewForbidden( + tenancyv1alpha1.Resource("memberships"), "", + fmt.Errorf("you are not an admin of tenant %q", tenant)) +} + +// lastTenantAdmin reports whether exactly one tenant-wide admin grant +// covers the tenant. +func lastTenantAdmin(grants []directory.NamedMembership, tenant string) bool { + count := 0 + for _, g := range grants { + if g.Tenant == tenant && g.Project == "" && g.Role == string(tenancyv1alpha1.RoleAdmin) { + count++ + } + } + return count <= 1 +} + +// membershipObject renders the directory's projection back as the API +// object it was mirrored from. +func membershipObject(m directory.NamedMembership) tenancyv1alpha1.Membership { + return tenancyv1alpha1.Membership{ + ObjectMeta: metav1.ObjectMeta{Name: m.Name}, + Spec: tenancyv1alpha1.MembershipSpec{ + Subject: m.Subject, + Role: tenancyv1alpha1.Role(m.Role), + Tenant: m.Tenant, + Project: m.Project, + }, + } +} + +func userName(u user.Info) string { + if u == nil { + return "" + } + return u.GetName() +} + +// noEndpoints renders no URL, for the paths that do not need one. +func noEndpoints(string) string { return "" } + +// validateSpec checks what the caller controls. +func validateSpec(spec *tenancyv1alpha1.MembershipSpec) field.ErrorList { + var errs field.ErrorList + path := field.NewPath("spec") + + switch spec.Subject.Kind { + case tenancyv1alpha1.SubjectKindUser, tenancyv1alpha1.SubjectKindGroup: + default: + errs = append(errs, field.NotSupported(path.Child("subject", "kind"), spec.Subject.Kind, + []string{string(tenancyv1alpha1.SubjectKindUser), string(tenancyv1alpha1.SubjectKindGroup)})) + } + if spec.Subject.Name == "" { + errs = append(errs, field.Required(path.Child("subject", "name"), "who the grant is for")) + } else if naming.Slugify(spec.Subject.Name) == "" { + // The subject becomes part of an object name, so something of it has + // to survive slugification. + errs = append(errs, field.Invalid(path.Child("subject", "name"), spec.Subject.Name, + "must contain at least one letter or digit")) + } + switch spec.Role { + case tenancyv1alpha1.RoleView, tenancyv1alpha1.RoleEdit, tenancyv1alpha1.RoleAdmin: + default: + errs = append(errs, field.NotSupported(path.Child("role"), spec.Role, + []string{string(tenancyv1alpha1.RoleView), string(tenancyv1alpha1.RoleEdit), string(tenancyv1alpha1.RoleAdmin)})) + } + if spec.Tenant == "" { + errs = append(errs, field.Required(path.Child("tenant"), "which tenant the grant applies to")) + } + return errs +} diff --git a/tenancy/pkg/virtual/membership/storage_test.go b/tenancy/pkg/virtual/membership/storage_test.go new file mode 100644 index 0000000..b8a9a82 --- /dev/null +++ b/tenancy/pkg/virtual/membership/storage_test.go @@ -0,0 +1,372 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package membership + +import ( + "context" + "testing" + + apierrors "k8s.io/apimachinery/pkg/api/errors" + "k8s.io/apiserver/pkg/authentication/user" + genericapirequest "k8s.io/apiserver/pkg/endpoints/request" + + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/pkg/directory" + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/pkg/naming" + tenancyv1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1" +) + +// This storage decides who may see and change other people's access, so +// what it refuses is the interesting part. + +// readyDirectory: alice administers acme, carol administers other, bob +// only views one of acme's projects, and mallory is a member of nothing. +func readyDirectory() *directory.Directory { + d := directory.New() + d.UpsertTenant(directory.Key{Cluster: "platform", Name: "acme"}, + directory.Tenant{DisplayName: "Acme", WorkspaceCluster: "ws1"}) + d.UpsertTenant(directory.Key{Cluster: "platform", Name: "other"}, + directory.Tenant{DisplayName: "Other", WorkspaceCluster: "ws2"}) + d.UpsertProject(directory.Key{Cluster: "ws1", Name: "web"}, + directory.Project{Tenant: "acme", WorkspaceCluster: "ws-web"}) + + d.UpsertMembership(directory.Key{Cluster: "ws1", Name: nameOf("alice", "acme", "")}, + directory.Membership{ + Subject: tenancyv1alpha1.Subject{Kind: tenancyv1alpha1.SubjectKindUser, Name: "alice"}, + Role: "admin", Tenant: "acme", + }) + // A second admin, so revoking one is not revoking the last. + d.UpsertMembership(directory.Key{Cluster: "ws1", Name: nameOf("dave", "acme", "")}, + directory.Membership{ + Subject: tenancyv1alpha1.Subject{Kind: tenancyv1alpha1.SubjectKindUser, Name: "dave"}, + Role: "admin", Tenant: "acme", + }) + d.UpsertMembership(directory.Key{Cluster: "ws1", Name: nameOf("bob", "acme", "web")}, + directory.Membership{ + Subject: tenancyv1alpha1.Subject{Kind: tenancyv1alpha1.SubjectKindUser, Name: "bob"}, + Role: "view", Tenant: "acme", Project: "web", + }) + d.UpsertMembership(directory.Key{Cluster: "ws2", Name: nameOf("carol", "other", "")}, + directory.Membership{ + Subject: tenancyv1alpha1.Subject{Kind: tenancyv1alpha1.SubjectKindUser, Name: "carol"}, + Role: "admin", Tenant: "other", + }) + d.SetReady() + return d +} + +// nameOf is the name the storage gives a user's grant. +func nameOf(subject, tenant, project string) string { + return naming.MembershipName(string(tenancyv1alpha1.SubjectKindUser), subject, tenant, project) +} + +func ctxWithUser(name string) context.Context { + return genericapirequest.WithUser(context.Background(), &user.DefaultInfo{Name: name}) +} + +// recorder captures what the storage asked to have written. +type recorder struct { + cluster string + grant *tenancyv1alpha1.Membership + created bool + creates int + deleted string + delCluster string + deletes int +} + +func (r *recorder) create(_ context.Context, cluster string, m *tenancyv1alpha1.Membership) (bool, error) { + r.creates++ + r.cluster, r.grant = cluster, m + return r.created, nil +} + +func (r *recorder) delete(_ context.Context, cluster, name string) error { + r.deletes++ + r.delCluster, r.deleted = cluster, name + return nil +} + +func (r *recorder) options() Options { return Options{Create: r.create, Delete: r.delete} } + +func grantFor(tenant, project, subject string, role tenancyv1alpha1.Role) *tenancyv1alpha1.Membership { + return &tenancyv1alpha1.Membership{ + Spec: tenancyv1alpha1.MembershipSpec{ + Subject: tenancyv1alpha1.Subject{Kind: tenancyv1alpha1.SubjectKindUser, Name: subject}, + Role: role, Tenant: tenant, Project: project, + }, + } +} + +func listFor(t *testing.T, r *REST, username string) *tenancyv1alpha1.MembershipList { + t.Helper() + obj, err := r.List(ctxWithUser(username), nil) + if err != nil { + t.Fatalf("List as %s: %v", username, err) + } + list, ok := obj.(*tenancyv1alpha1.MembershipList) + if !ok { + t.Fatalf("List returned %T", obj) + } + return list +} + +func TestAdminSeesEveryGrantInTheirTenant(t *testing.T) { + rec := &recorder{} + r := NewREST(readyDirectory(), rec.options()) + + list := listFor(t, r, "alice") + if len(list.Items) != 3 { + t.Fatalf("alice sees %d grants, want acme's 3: %+v", len(list.Items), list.Items) + } + // Including grants that are not her own — that is the point of + // administering access. + var subjects []string + for _, m := range list.Items { + subjects = append(subjects, m.Spec.Subject.Name) + if m.Spec.Tenant != "acme" { + t.Errorf("alice sees a grant on tenant %q", m.Spec.Tenant) + } + } + t.Logf("alice sees grants for %v", subjects) +} + +func TestNonAdminsSeeNothing(t *testing.T) { + rec := &recorder{} + r := NewREST(readyDirectory(), rec.options()) + + for _, who := range []string{"bob", "mallory"} { + list := listFor(t, r, who) + if len(list.Items) != 0 { + t.Errorf("%s sees %d grants, want none: %+v", who, len(list.Items), list.Items) + } + } +} + +func TestListIsScopedToTheTenantsYouAdminister(t *testing.T) { + rec := &recorder{} + r := NewREST(readyDirectory(), rec.options()) + + list := listFor(t, r, "carol") + if len(list.Items) != 1 || list.Items[0].Spec.Tenant != "other" { + t.Fatalf("carol sees %+v, want only her own tenant's grant", list.Items) + } +} + +func TestAdminGrantsInTheTenantWorkspace(t *testing.T) { + rec := &recorder{created: true} + r := NewREST(readyDirectory(), rec.options()) + + obj, err := r.Create(ctxWithUser("alice"), grantFor("acme", "", "erin@example.com", tenancyv1alpha1.RoleEdit), nil, nil) + if err != nil { + t.Fatalf("Create: %v", err) + } + + // The cluster comes from the directory, never from the request. + if rec.cluster != "ws1" { + t.Errorf("wrote to cluster %q, want the tenant's own ws1", rec.cluster) + } + // The name is derived, so granting the same access twice is one object. + if rec.grant.Name != nameOf("erin@example.com", "acme", "") { + t.Errorf("derived name %q", rec.grant.Name) + } + if got := obj.(*tenancyv1alpha1.Membership).Name; got != rec.grant.Name { + t.Errorf("returned name %q, want %q", got, rec.grant.Name) + } +} + +func TestCallerCannotChooseTheObjectName(t *testing.T) { + rec := &recorder{created: true} + r := NewREST(readyDirectory(), rec.options()) + + grant := grantFor("acme", "", "erin@example.com", tenancyv1alpha1.RoleView) + grant.Name = "something-else" + if _, err := r.Create(ctxWithUser("alice"), grant, nil, nil); err != nil { + t.Fatalf("Create: %v", err) + } + if rec.grant.Name != nameOf("erin@example.com", "acme", "") { + t.Errorf("name %q followed the request instead of the grant", rec.grant.Name) + } +} + +func TestNonAdminCannotGrant(t *testing.T) { + for _, who := range []string{"bob", "mallory"} { + rec := &recorder{} + r := NewREST(readyDirectory(), rec.options()) + + _, err := r.Create(ctxWithUser(who), grantFor("acme", "", "erin", tenancyv1alpha1.RoleAdmin), nil, nil) + if !apierrors.IsForbidden(err) { + t.Errorf("%s granting: %v, want Forbidden", who, err) + } + if rec.creates != 0 { + t.Errorf("%s reached the writer", who) + } + } +} + +func TestAdminOfOneTenantCannotGrantInAnother(t *testing.T) { + rec := &recorder{} + r := NewREST(readyDirectory(), rec.options()) + + // carol administers "other", and must not be able to reach "acme" — + // nor learn from the refusal whether it exists. + _, err := r.Create(ctxWithUser("carol"), grantFor("acme", "", "carol", tenancyv1alpha1.RoleAdmin), nil, nil) + if !apierrors.IsForbidden(err) { + t.Fatalf("cross-tenant grant: %v, want Forbidden", err) + } + if rec.creates != 0 { + t.Error("cross-tenant grant reached the writer") + } +} + +func TestGrantOnAnUnknownProjectIsRefused(t *testing.T) { + rec := &recorder{} + r := NewREST(readyDirectory(), rec.options()) + + _, err := r.Create(ctxWithUser("alice"), grantFor("acme", "nope", "erin", tenancyv1alpha1.RoleView), nil, nil) + if !apierrors.IsInvalid(err) { + t.Fatalf("grant on a missing project: %v, want Invalid", err) + } + if rec.creates != 0 { + t.Error("it reached the writer anyway") + } +} + +func TestInvalidGrantsAreRefusedBeforeTheWrite(t *testing.T) { + cases := map[string]*tenancyv1alpha1.Membership{ + "no subject": grantFor("acme", "", "", tenancyv1alpha1.RoleView), + "unsluggable subject": grantFor("acme", "", "!!!", tenancyv1alpha1.RoleView), + "unknown role": grantFor("acme", "", "erin", tenancyv1alpha1.Role("root")), + "no tenant": grantFor("", "", "erin", tenancyv1alpha1.RoleView), + } + for name, grant := range cases { + rec := &recorder{} + r := NewREST(readyDirectory(), rec.options()) + + _, err := r.Create(ctxWithUser("alice"), grant, nil, nil) + if !apierrors.IsInvalid(err) { + t.Errorf("%s: %v, want Invalid", name, err) + } + if rec.creates != 0 { + t.Errorf("%s: reached the writer", name) + } + } +} + +func TestAdminRevokesAGrant(t *testing.T) { + rec := &recorder{} + r := NewREST(readyDirectory(), rec.options()) + + _, deleted, err := r.Delete(ctxWithUser("alice"), nameOf("bob", "acme", "web"), nil, nil) + if err != nil { + t.Fatalf("Delete: %v", err) + } + if !deleted { + t.Error("Delete reported nothing removed") + } + if rec.delCluster != "ws1" || rec.deleted != nameOf("bob", "acme", "web") { + t.Errorf("deleted %q in %q", rec.deleted, rec.delCluster) + } +} + +func TestTheLastAdminCannotBeRevoked(t *testing.T) { + d := readyDirectory() + // Leave acme with a single admin. + d.RemoveMembership(directory.Key{Cluster: "ws1", Name: nameOf("dave", "acme", "")}) + + rec := &recorder{} + r := NewREST(d, rec.options()) + + _, _, err := r.Delete(ctxWithUser("alice"), nameOf("alice", "acme", ""), nil, nil) + if !apierrors.IsForbidden(err) { + t.Fatalf("revoking the last admin: %v, want Forbidden", err) + } + if rec.deletes != 0 { + t.Error("it reached the writer, leaving the tenant unadministerable") + } +} + +func TestTheLastAdminCannotBeDemoted(t *testing.T) { + d := readyDirectory() + d.RemoveMembership(directory.Key{Cluster: "ws1", Name: nameOf("dave", "acme", "")}) + + rec := &recorder{} + r := NewREST(d, rec.options()) + + _, err := r.Create(ctxWithUser("alice"), grantFor("acme", "", "alice", tenancyv1alpha1.RoleView), nil, nil) + if !apierrors.IsForbidden(err) { + t.Fatalf("demoting the last admin: %v, want Forbidden", err) + } + if rec.creates != 0 { + t.Error("it reached the writer, leaving the tenant without an admin") + } +} + +func TestAnAdminCanBeDemotedWhenAnotherRemains(t *testing.T) { + rec := &recorder{} + r := NewREST(readyDirectory(), rec.options()) + + if _, err := r.Create(ctxWithUser("alice"), grantFor("acme", "", "dave", tenancyv1alpha1.RoleView), nil, nil); err != nil { + t.Fatalf("demoting dave while alice is still admin: %v", err) + } +} + +func TestRevokingSomethingYouDoNotAdministerIsNotFound(t *testing.T) { + rec := &recorder{} + r := NewREST(readyDirectory(), rec.options()) + + // carol administers another tenant: acme's grants are not hers to see, + // so they are reported as absent rather than refused. + _, _, err := r.Delete(ctxWithUser("carol"), nameOf("bob", "acme", "web"), nil, nil) + if !apierrors.IsNotFound(err) { + t.Fatalf("cross-tenant revoke: %v, want NotFound", err) + } + if rec.deletes != 0 { + t.Error("cross-tenant revoke reached the writer") + } +} + +func TestReadOnlyDeploymentRefusesWrites(t *testing.T) { + r := NewREST(readyDirectory(), Options{}) + + if _, err := r.Create(ctxWithUser("alice"), grantFor("acme", "", "erin", tenancyv1alpha1.RoleView), nil, nil); !apierrors.IsServiceUnavailable(err) { + t.Errorf("Create without a writer: %v, want ServiceUnavailable", err) + } + if _, _, err := r.Delete(ctxWithUser("alice"), nameOf("bob", "acme", "web"), nil, nil); !apierrors.IsServiceUnavailable(err) { + t.Errorf("Delete without a writer: %v, want ServiceUnavailable", err) + } +} + +func TestAnUnsyncedDirectoryAnswersNothing(t *testing.T) { + rec := &recorder{} + r := NewREST(directory.New(), rec.options()) + + if _, err := r.List(ctxWithUser("alice"), nil); !apierrors.IsServiceUnavailable(err) { + t.Errorf("List before sync: %v, want ServiceUnavailable", err) + } +} + +func TestGetOnlyReachesYourOwnTenants(t *testing.T) { + rec := &recorder{} + r := NewREST(readyDirectory(), rec.options()) + + if _, err := r.Get(ctxWithUser("alice"), nameOf("bob", "acme", "web"), nil); err != nil { + t.Fatalf("alice getting a grant in acme: %v", err) + } + if _, err := r.Get(ctxWithUser("carol"), nameOf("bob", "acme", "web"), nil); !apierrors.IsNotFound(err) { + t.Errorf("carol getting a grant in acme: %v, want NotFound", err) + } +} diff --git a/tenancy/pkg/virtual/selfprojectrequest/storage.go b/tenancy/pkg/virtual/selfprojectrequest/storage.go new file mode 100644 index 0000000..1b6d88d --- /dev/null +++ b/tenancy/pkg/virtual/selfprojectrequest/storage.go @@ -0,0 +1,219 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// 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. +// +// Everything else this component serves is a read of the caller's own +// state. This is a write, so it is worth being explicit about why it is +// mediated rather than delegated: +// +// Projects live in their tenant's workspace, which is also where the +// Memberships that decide who may reach what live. Granting a tenant +// admin RBAC there to create projects would hand them the records +// governing their own access. The virtual workspace therefore holds the +// only credential into that tier, and offers exactly one operation +// through it — create a project — gated on the caller's own admin +// Membership as the directory already reports it. +// +// The mediation is narrow on purpose: one verb, one kind, one field the +// caller controls. A caller cannot name a workspace, choose a cluster, or +// touch anything else in the tenant tier. +package selfprojectrequest + +import ( + "context" + "fmt" + "slices" + + apierrors "k8s.io/apimachinery/pkg/api/errors" + "k8s.io/apimachinery/pkg/api/validation" + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + "k8s.io/apimachinery/pkg/runtime" + "k8s.io/apimachinery/pkg/util/validation/field" + genericapirequest "k8s.io/apiserver/pkg/endpoints/request" + "k8s.io/apiserver/pkg/registry/rest" + "k8s.io/klog/v2" + + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/pkg/directory" + tenancyv1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1" +) + +// CreateProjectFunc creates a Project in one tenant's workspace. The +// server supplies it, because how the virtual workspace reaches that +// workspace — through the tenancy export — is a detail of the deployment +// rather than of the API. +type CreateProjectFunc func(ctx context.Context, cluster string, project *tenancyv1alpha1.Project) (created bool, err error) + +// REST answers SelfProjectRequest creates. +type REST struct { + directory *directory.Directory + create CreateProjectFunc +} + +var ( + _ rest.Storage = &REST{} + _ rest.Creater = &REST{} + _ rest.Scoper = &REST{} + _ rest.SingularNameProvider = &REST{} +) + +// NewREST returns the storage. create may be nil, in which case the +// resource reports that project creation is not configured rather than +// pretending to work. +func NewREST(d *directory.Directory, create CreateProjectFunc) *REST { + return &REST{directory: d, create: create} +} + +func (r *REST) New() runtime.Object { return &tenancyv1alpha1.SelfProjectRequest{} } + +func (r *REST) Destroy() {} + +func (r *REST) NamespaceScoped() bool { return false } + +func (r *REST) GetSingularName() string { return "selfprojectrequest" } + +// Create authorizes the request against the caller's own membership and, +// if it holds, creates the project. +func (r *REST) Create(ctx context.Context, obj runtime.Object, _ rest.ValidateObjectFunc, _ *metav1.CreateOptions) (runtime.Object, error) { + req, ok := obj.(*tenancyv1alpha1.SelfProjectRequest) + if !ok { + return nil, apierrors.NewBadRequest(fmt.Sprintf("not a SelfProjectRequest: %T", obj)) + } + if r.create == nil { + return nil, apierrors.NewServiceUnavailable( + "this virtual workspace was started without project creation; it can only answer reviews") + } + if !r.directory.Ready() { + return nil, apierrors.NewServiceUnavailable("tenancy directory is not ready; try again shortly") + } + + user, ok := genericapirequest.UserFrom(ctx) + if !ok { + return nil, apierrors.NewUnauthorized("no user present in request context") + } + + if errs := validateSpec(&req.Spec); len(errs) > 0 { + return nil, apierrors.NewInvalid( + tenancyv1alpha1.SchemeGroupVersion.WithKind("SelfProjectRequest").GroupKind(), + req.Name, errs) + } + + // The caller's own answer decides: admin on that tenant, or nothing. + // Deliberately the same view `whoami` returns, so what a person is + // told they can do and what they can do cannot drift apart. + // noEndpoints: this path needs the caller's roles and the tenant's + // cluster, not URLs, and ReviewFor calls the renderer for every + // workspace it reports. + claim, ok := tenantFor( + r.directory.ReviewFor(user.GetName(), user.GetGroups(), noEndpoints), + req.Spec.Tenant, + ) + if !ok { + // Not revealing whether the tenant exists: to a non-member the two + // cases are the same, and saying which would leak the tenant list. + return nil, apierrors.NewForbidden( + tenancyv1alpha1.Resource("selfprojectrequests"), req.Spec.Name, + fmt.Errorf("you are not an admin of tenant %q", req.Spec.Tenant)) + } + if !slices.Contains(claim.Roles, string(tenancyv1alpha1.RoleAdmin)) { + return nil, apierrors.NewForbidden( + tenancyv1alpha1.Resource("selfprojectrequests"), req.Spec.Name, + fmt.Errorf("creating a project in tenant %q needs the admin role; you hold %v", + req.Spec.Tenant, claim.Roles)) + } + if claim.Cluster == "" { + return nil, apierrors.NewServiceUnavailable( + fmt.Sprintf("tenant %q has no workspace yet; try again once it is ready", req.Spec.Tenant)) + } + + displayName := req.Spec.DisplayName + if displayName == "" { + displayName = req.Spec.Name + } + + project := &tenancyv1alpha1.Project{ + ObjectMeta: metav1.ObjectMeta{Name: req.Spec.Name}, + Spec: tenancyv1alpha1.ProjectSpec{ + Tenant: req.Spec.Tenant, + DisplayName: displayName, + Description: req.Spec.Description, + }, + } + + created, err := r.create(ctx, claim.Cluster, project) + if err != nil { + return nil, err + } + + logger := klog.FromContext(ctx) + logger.V(2).Info("answered SelfProjectRequest", + "username", user.GetName(), + "tenant", req.Spec.Tenant, + "project", req.Spec.Name, + "cluster", claim.Cluster, + "created", created, + ) + + out := req.DeepCopy() + out.Status = tenancyv1alpha1.SelfProjectRequestStatus{ + Created: created, + Project: req.Spec.Name, + Message: message(created, req.Spec.Name, req.Spec.Tenant), + } + return out, nil +} + +func message(created bool, project, tenant string) string { + if created { + return fmt.Sprintf("project %q created in tenant %q", project, tenant) + } + return fmt.Sprintf("project %q already exists in tenant %q", project, tenant) +} + +// noEndpoints renders no URL, for the paths that do not need one. +func noEndpoints(string) string { return "" } + +// tenantFor finds the caller's claim on one tenant. +func tenantFor(claims []tenancyv1alpha1.TenantClaim, name string) (tenancyv1alpha1.TenantClaim, bool) { + for _, c := range claims { + if c.Name == name { + return c, true + } + } + return tenancyv1alpha1.TenantClaim{}, false +} + +// validateSpec checks what the caller controls. The name becomes an +// object name and seeds a workspace name, so it has to be a DNS label +// rather than whatever was typed. +func validateSpec(spec *tenancyv1alpha1.SelfProjectRequestSpec) field.ErrorList { + var errs field.ErrorList + path := field.NewPath("spec") + + if spec.Tenant == "" { + errs = append(errs, field.Required(path.Child("tenant"), "which tenant to create the project in")) + } + if spec.Name == "" { + errs = append(errs, field.Required(path.Child("name"), "the project's name")) + } else { + for _, msg := range validation.NameIsDNSLabel(spec.Name, false) { + errs = append(errs, field.Invalid(path.Child("name"), spec.Name, msg)) + } + } + return errs +} diff --git a/tenancy/pkg/virtual/selfprojectrequest/storage_test.go b/tenancy/pkg/virtual/selfprojectrequest/storage_test.go new file mode 100644 index 0000000..97665b3 --- /dev/null +++ b/tenancy/pkg/virtual/selfprojectrequest/storage_test.go @@ -0,0 +1,201 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package selfprojectrequest + +import ( + "context" + "testing" + + apierrors "k8s.io/apimachinery/pkg/api/errors" + "k8s.io/apiserver/pkg/authentication/user" + genericapirequest "k8s.io/apiserver/pkg/endpoints/request" + + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/pkg/directory" + tenancyv1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1" +) + +// This storage holds a credential its callers do not, so what it refuses +// matters more than what it allows. The tests are mostly refusals. + +// readyDirectory: alice administers acme, bob only views one of its +// projects, and mallory is a member of nothing. +func readyDirectory() *directory.Directory { + d := directory.New() + d.UpsertTenant(directory.Key{Cluster: "platform", Name: "acme"}, + directory.Tenant{DisplayName: "Acme", WorkspaceCluster: "ws1"}) + d.UpsertProject(directory.Key{Cluster: "ws1", Name: "web"}, + directory.Project{Tenant: "acme", WorkspaceCluster: "ws-web"}) + d.UpsertMembership(directory.Key{Cluster: "ws1", Name: "m-alice"}, + directory.Membership{ + Subject: tenancyv1alpha1.Subject{Kind: tenancyv1alpha1.SubjectKindUser, Name: "alice"}, + Role: "admin", Tenant: "acme", + }) + d.UpsertMembership(directory.Key{Cluster: "ws1", Name: "m-bob"}, + directory.Membership{ + Subject: tenancyv1alpha1.Subject{Kind: tenancyv1alpha1.SubjectKindUser, Name: "bob"}, + Role: "view", Tenant: "acme", Project: "web", + }) + d.SetReady() + return d +} + +func ctxWithUser(name string) context.Context { + return genericapirequest.WithUser(context.Background(), &user.DefaultInfo{Name: name}) +} + +// recorder captures what the storage asked to have created. +type recorder struct { + cluster string + project *tenancyv1alpha1.Project + created bool + calls int +} + +func (r *recorder) create(_ context.Context, cluster string, p *tenancyv1alpha1.Project) (bool, error) { + r.calls++ + r.cluster, r.project = cluster, p + return r.created, nil +} + +func request(tenant, name string) *tenancyv1alpha1.SelfProjectRequest { + return &tenancyv1alpha1.SelfProjectRequest{ + Spec: tenancyv1alpha1.SelfProjectRequestSpec{Tenant: tenant, Name: name}, + } +} + +func TestAdminCreatesInTheTenantWorkspace(t *testing.T) { + rec := &recorder{created: true} + r := NewREST(readyDirectory(), rec.create) + + obj, err := r.Create(ctxWithUser("alice"), request("acme", "analytics"), nil, nil) + if err != nil { + t.Fatalf("Create: %v", err) + } + + // The cluster comes from the directory, never from the request: a + // caller cannot aim this credential at a workspace of their choosing. + if rec.cluster != "ws1" { + t.Errorf("created in cluster %q, want the tenant's own ws1", rec.cluster) + } + if rec.project.Name != "analytics" || rec.project.Spec.Tenant != "acme" { + t.Errorf("created %+v", rec.project) + } + // An unset display name should not reach the object empty. + if rec.project.Spec.DisplayName != "analytics" { + t.Errorf("displayName = %q, want it defaulted to the name", rec.project.Spec.DisplayName) + } + + out := obj.(*tenancyv1alpha1.SelfProjectRequest) + if !out.Status.Created || out.Status.Project != "analytics" { + t.Errorf("status = %+v", out.Status) + } +} + +func TestExistingProjectIsNotAnError(t *testing.T) { + // Asking for what already exists is the same request, answered. + rec := &recorder{created: false} + r := NewREST(readyDirectory(), rec.create) + + obj, err := r.Create(ctxWithUser("alice"), request("acme", "web"), nil, nil) + if err != nil { + t.Fatalf("Create: %v", err) + } + if out := obj.(*tenancyv1alpha1.SelfProjectRequest); out.Status.Created { + t.Errorf("status says created, want created=false for an existing project") + } +} + +func TestNonAdminMemberIsRefused(t *testing.T) { + rec := &recorder{} + r := NewREST(readyDirectory(), rec.create) + + _, err := r.Create(ctxWithUser("bob"), request("acme", "analytics"), nil, nil) + if !apierrors.IsForbidden(err) { + t.Fatalf("err = %v, want Forbidden", err) + } + if rec.calls != 0 { + t.Errorf("the credential was used %d times for a refused request", rec.calls) + } +} + +func TestStrangerIsRefused(t *testing.T) { + rec := &recorder{} + r := NewREST(readyDirectory(), rec.create) + + _, err := r.Create(ctxWithUser("mallory"), request("acme", "analytics"), nil, nil) + if !apierrors.IsForbidden(err) { + t.Fatalf("err = %v, want Forbidden", err) + } + // The refusal must not say whether the tenant exists: to a + // non-member, "no such tenant" and "not your tenant" are the same. + if got := err.Error(); !contains(got, "not an admin") { + t.Errorf("message %q reveals more than membership", got) + } + if rec.calls != 0 { + t.Errorf("the credential was used for a stranger's request") + } +} + +func TestUnknownTenantLooksLikeNonMembership(t *testing.T) { + rec := &recorder{} + r := NewREST(readyDirectory(), rec.create) + + _, err := r.Create(ctxWithUser("alice"), request("no-such-tenant", "x"), nil, nil) + if !apierrors.IsForbidden(err) { + t.Fatalf("err = %v, want Forbidden rather than NotFound", err) + } +} + +func TestNameMustBeAWorkspaceName(t *testing.T) { + rec := &recorder{} + r := NewREST(readyDirectory(), rec.create) + + // The name seeds a workspace name, so it has to be a DNS label. + _, err := r.Create(ctxWithUser("alice"), request("acme", "Not A Label"), nil, nil) + if !apierrors.IsInvalid(err) { + t.Fatalf("err = %v, want Invalid", err) + } + if rec.calls != 0 { + t.Errorf("an invalid request reached the credential") + } +} + +func TestUnconfiguredCreationIsHonest(t *testing.T) { + // A server without the writer should say so rather than refuse as if + // it were an authorization decision. + r := NewREST(readyDirectory(), nil) + + _, err := r.Create(ctxWithUser("alice"), request("acme", "analytics"), nil, nil) + if !apierrors.IsServiceUnavailable(err) { + t.Fatalf("err = %v, want ServiceUnavailable", err) + } +} + +func contains(haystack, needle string) bool { + return len(haystack) >= len(needle) && (haystack == needle || + len(needle) == 0 || + indexOf(haystack, needle) >= 0) +} + +func indexOf(haystack, needle string) int { + for i := 0; i+len(needle) <= len(haystack); i++ { + if haystack[i:i+len(needle)] == needle { + return i + } + } + return -1 +} diff --git a/tenancy/pkg/virtual/selftenancyreview/virtualworkspace.go b/tenancy/pkg/virtual/selftenancyreview/virtualworkspace.go index 0f2cdb2..21e09e6 100644 --- a/tenancy/pkg/virtual/selftenancyreview/virtualworkspace.go +++ b/tenancy/pkg/virtual/selftenancyreview/virtualworkspace.go @@ -30,23 +30,45 @@ import ( "github.com/kcp-dev/contrib-virtual-workspaces/access/pkg/virtual" "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/pkg/directory" + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/pkg/virtual/membership" + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/pkg/virtual/selfprojectrequest" + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/pkg/virtual/selftenantrequest" tenancyv1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1" ) const VirtualWorkspaceName = "tenancy" // RootPath is the URL prefix the front-proxy routes to this VW. The review -// is served at RootPath + /apis/tenancy.contrib.kcp.io/v1alpha1/selftenancyreviews. +// is served at RootPath + /apis/tenancy.platform.kcp.io/v1alpha1/selftenancyreviews. const RootPath = "/services/" + VirtualWorkspaceName +// Config is what the server supplies: the shared directory every answer +// is read from, how to render a workspace's URL, and the write paths — +// each one a function, because how this server reaches another workspace +// is a property of the deployment rather than of the API. +type Config struct { + Directory *directory.Directory + EndpointFor func(cluster string) string + + CreateProject selfprojectrequest.CreateProjectFunc + + Tenants selftenantrequest.Options + CreateTenant selftenantrequest.CreateTenantFunc + + Memberships membership.Options +} + // NewVirtualWorkspace builds the tenancy VW: a fixed-group-version -// delegated apiserver serving tenancy.contrib.kcp.io/v1alpha1 with the -// selftenancyreviews REST storage, answered from the shared directory. +// delegated apiserver serving tenancy.platform.kcp.io/v1alpha1, answered +// from the shared directory. // -// The authorizer only requires an authenticated caller: the review is a -// self-review, so the directory — not the authorizer — decides what the -// answer contains. -func NewVirtualWorkspace(d *directory.Directory, endpointFor func(cluster string) string) rootapiserver.NamedVirtualWorkspace { +// The authorizer only requires an authenticated caller. That is not a gap: +// every resource here decides for itself what the caller may see or do, +// from the caller's own Memberships as the directory reports them. A +// coarser authorizer would have to be told about tenants, which is exactly +// the knowledge the directory already holds. +func NewVirtualWorkspace(cfg Config) rootapiserver.NamedVirtualWorkspace { + d := cfg.Directory vw := &fixedgvs.FixedGroupVersionsVirtualWorkspace{ RootPathResolver: framework.RootPathResolverFunc(func(urlPath string, ctx context.Context) (bool, string, context.Context) { if urlPath != RootPath && !strings.HasPrefix(urlPath, RootPath+"/") { @@ -68,7 +90,28 @@ func NewVirtualWorkspace(d *directory.Directory, endpointFor func(cluster string BootstrapRestResources: func(_ genericapiserver.CompletedConfig) (map[string]fixedgvs.RestStorageBuilder, error) { return map[string]fixedgvs.RestStorageBuilder{ "selftenancyreviews": func(_ genericapiserver.CompletedConfig) (restStorage.Storage, error) { - return NewREST(d, endpointFor), nil + return NewREST(d, cfg.EndpointFor), nil + }, + // Creating a project in a tenant the caller + // administers. Authorized against the caller's own + // Membership, performed with this server's + // credential, because the tenant tier is + // deliberately closed to its own members. + "selfprojectrequests": func(_ genericapiserver.CompletedConfig) (restStorage.Storage, error) { + return selfprojectrequest.NewREST(d, cfg.CreateProject), nil + }, + // How someone with no membership at all gets + // started: there is nothing to authorize against, + // so the deployment decides whether this is + // offered. + "selftenantrequests": func(_ genericapiserver.CompletedConfig) (restStorage.Storage, error) { + return selftenantrequest.NewREST(cfg.Tenants, cfg.CreateTenant), nil + }, + // Managing who else may reach what. Mediated for + // the same reason projects are: the grants live in + // the workspace their holders may not enter. + "memberships": func(_ genericapiserver.CompletedConfig) (restStorage.Storage, error) { + return membership.NewREST(d, cfg.Memberships), nil }, }, nil }, diff --git a/tenancy/pkg/virtual/selftenantrequest/storage.go b/tenancy/pkg/virtual/selftenantrequest/storage.go new file mode 100644 index 0000000..db1bde1 --- /dev/null +++ b/tenancy/pkg/virtual/selftenantrequest/storage.go @@ -0,0 +1,185 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// Package selftenantrequest lets a caller with nothing get their first +// tenant. +// +// It closes the one gap that made the model unusable for a new person: +// every other self-service path here is authorized against a Membership, +// and someone who has just signed in has none. There is no login hook to +// hang this on either — the OIDC redirect goes from the browser to the +// identity provider and back, and this server only ever sees the +// resulting token on ordinary requests — so a new user has to ask for a +// tenant explicitly. That is deliberate rather than a limitation: +// provisioning as a side effect of a read would make listing tenants a +// write, and a monitoring probe would materialize workspaces. +// +// Because there is no Membership to check, the gate is configuration: +// self-service is off unless the deployment turns it on, and can be +// restricted to groups the identity provider asserts. A deployment that +// leaves it off is not broken — it has decided that handing out tenants +// is an administrator's job. +// +// The caller names the tenant and nothing else. The first admin is the +// caller, set here rather than read from the request, so nobody can ask +// for a tenant administered by someone else. +package selftenantrequest + +import ( + "context" + "fmt" + "slices" + + apierrors "k8s.io/apimachinery/pkg/api/errors" + "k8s.io/apimachinery/pkg/api/validation" + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + "k8s.io/apimachinery/pkg/runtime" + "k8s.io/apimachinery/pkg/util/validation/field" + genericapirequest "k8s.io/apiserver/pkg/endpoints/request" + "k8s.io/apiserver/pkg/registry/rest" + "k8s.io/klog/v2" + + tenancyv1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1" +) + +// CreateTenantFunc creates a Tenant in the store workspace. The server +// supplies it, because where the records live is a deployment detail. +type CreateTenantFunc func(ctx context.Context, tenant *tenancyv1alpha1.Tenant) (created bool, err error) + +// Options configures who may ask. +type Options struct { + // Enabled turns self-service on. Off means the resource answers that + // it is not offered here, which is a decision rather than a failure. + Enabled bool + // Groups, when set, restricts self-service to callers in at least one + // of them — the groups the identity provider asserts, as kcp sees + // them. Empty means any authenticated caller. + Groups []string +} + +// REST answers SelfTenantRequest creates. +type REST struct { + opts Options + create CreateTenantFunc +} + +var ( + _ rest.Storage = &REST{} + _ rest.Creater = &REST{} + _ rest.Scoper = &REST{} + _ rest.SingularNameProvider = &REST{} +) + +func NewREST(opts Options, create CreateTenantFunc) *REST { + return &REST{opts: opts, create: create} +} + +func (r *REST) New() runtime.Object { return &tenancyv1alpha1.SelfTenantRequest{} } + +func (r *REST) Destroy() {} + +func (r *REST) NamespaceScoped() bool { return false } + +func (r *REST) GetSingularName() string { return "selftenantrequest" } + +// Create makes the tenant, with the caller as its first admin. +func (r *REST) Create(ctx context.Context, obj runtime.Object, _ rest.ValidateObjectFunc, _ *metav1.CreateOptions) (runtime.Object, error) { + req, ok := obj.(*tenancyv1alpha1.SelfTenantRequest) + if !ok { + return nil, apierrors.NewBadRequest(fmt.Sprintf("not a SelfTenantRequest: %T", obj)) + } + if r.create == nil || !r.opts.Enabled { + return nil, apierrors.NewServiceUnavailable( + "self-service tenants are not enabled here; an administrator creates tenants") + } + + user, ok := genericapirequest.UserFrom(ctx) + if !ok { + return nil, apierrors.NewUnauthorized("no user present in request context") + } + + if len(r.opts.Groups) > 0 && !slices.ContainsFunc(user.GetGroups(), func(g string) bool { + return slices.Contains(r.opts.Groups, g) + }) { + return nil, apierrors.NewForbidden( + tenancyv1alpha1.Resource("selftenantrequests"), req.Spec.Name, + fmt.Errorf("self-service tenants are limited to %v", r.opts.Groups)) + } + + if errs := validateSpec(&req.Spec); len(errs) > 0 { + return nil, apierrors.NewInvalid( + tenancyv1alpha1.SchemeGroupVersion.WithKind("SelfTenantRequest").GroupKind(), + req.Spec.Name, errs) + } + + displayName := req.Spec.DisplayName + if displayName == "" { + displayName = req.Spec.Name + } + + tenant := &tenancyv1alpha1.Tenant{ + ObjectMeta: metav1.ObjectMeta{Name: req.Spec.Name}, + Spec: tenancyv1alpha1.TenantSpec{ + DisplayName: displayName, + Description: req.Spec.Description, + // The caller, never what the request asked for: a tenant you + // requested is a tenant you administer, and not one you can + // hand to somebody else on the way in. + FirstAdmin: user.GetName(), + }, + } + + created, err := r.create(ctx, tenant) + if err != nil { + return nil, err + } + + klog.FromContext(ctx).V(2).Info("answered SelfTenantRequest", + "username", user.GetName(), "tenant", req.Spec.Name, "created", created) + + out := req.DeepCopy() + out.Status = tenancyv1alpha1.SelfTenantRequestStatus{ + Created: created, + Tenant: req.Spec.Name, + Message: message(created, req.Spec.Name, user.GetName()), + } + return out, nil +} + +func message(created bool, tenant, admin string) string { + if created { + return fmt.Sprintf("tenant %q created; %s is its admin once the workspace is ready", tenant, admin) + } + // Someone else may hold it. Saying so is better than implying it is + // theirs, and the review will show whether they can reach it. + return fmt.Sprintf("tenant %q already exists", tenant) +} + +// validateSpec checks what the caller controls. The name becomes an +// object name and seeds a workspace name, so it has to be a DNS label. +func validateSpec(spec *tenancyv1alpha1.SelfTenantRequestSpec) field.ErrorList { + var errs field.ErrorList + path := field.NewPath("spec") + + if spec.Name == "" { + errs = append(errs, field.Required(path.Child("name"), "the tenant's name")) + return errs + } + for _, msg := range validation.NameIsDNSLabel(spec.Name, false) { + errs = append(errs, field.Invalid(path.Child("name"), spec.Name, msg)) + } + return errs +} diff --git a/tenancy/pkg/virtual/selftenantrequest/storage_test.go b/tenancy/pkg/virtual/selftenantrequest/storage_test.go new file mode 100644 index 0000000..7bef402 --- /dev/null +++ b/tenancy/pkg/virtual/selftenantrequest/storage_test.go @@ -0,0 +1,162 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package selftenantrequest + +import ( + "context" + "testing" + + apierrors "k8s.io/apimachinery/pkg/api/errors" + "k8s.io/apiserver/pkg/authentication/user" + genericapirequest "k8s.io/apiserver/pkg/endpoints/request" + + tenancyv1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1" +) + +// This is the one endpoint with no Membership to authorize against, so +// the tests are about the gate and about what the caller cannot choose. + +type recorder struct { + tenant *tenancyv1alpha1.Tenant + created bool + calls int +} + +func (r *recorder) create(_ context.Context, t *tenancyv1alpha1.Tenant) (bool, error) { + r.calls++ + r.tenant = t + return r.created, nil +} + +func ctxWithUser(name string, groups ...string) context.Context { + return genericapirequest.WithUser(context.Background(), &user.DefaultInfo{Name: name, Groups: groups}) +} + +func request(name string) *tenancyv1alpha1.SelfTenantRequest { + return &tenancyv1alpha1.SelfTenantRequest{ + Spec: tenancyv1alpha1.SelfTenantRequestSpec{Name: name}, + } +} + +func TestDisabledByDefault(t *testing.T) { + rec := &recorder{} + r := NewREST(Options{}, rec.create) + + _, err := r.Create(ctxWithUser("alice@example.com"), request("acme"), nil, nil) + if !apierrors.IsServiceUnavailable(err) { + t.Fatalf("err = %v, want ServiceUnavailable", err) + } + if rec.calls != 0 { + t.Errorf("a tenant was created while self-service was off") + } +} + +func TestEnabledCallerBecomesFirstAdmin(t *testing.T) { + rec := &recorder{created: true} + r := NewREST(Options{Enabled: true}, rec.create) + + obj, err := r.Create(ctxWithUser("alice@example.com"), request("acme"), nil, nil) + if err != nil { + t.Fatalf("Create: %v", err) + } + // A tenant nobody administers is unusable, so the caller must come out + // of this as its admin. + if rec.tenant.Spec.FirstAdmin != "alice@example.com" { + t.Errorf("firstAdmin = %q, want the caller", rec.tenant.Spec.FirstAdmin) + } + if rec.tenant.Spec.DisplayName != "acme" { + t.Errorf("displayName = %q, want it defaulted to the name", rec.tenant.Spec.DisplayName) + } + if out := obj.(*tenancyv1alpha1.SelfTenantRequest); !out.Status.Created { + t.Errorf("status = %+v", out.Status) + } +} + +func TestCallerCannotNameSomeoneElseAsAdmin(t *testing.T) { + rec := &recorder{created: true} + r := NewREST(Options{Enabled: true}, rec.create) + + // There is no field for it, so the only way to try is to smuggle one + // in — and the server overwrites whatever arrived. + req := request("acme") + _, err := r.Create(ctxWithUser("mallory@example.com"), req, nil, nil) + if err != nil { + t.Fatalf("Create: %v", err) + } + if rec.tenant.Spec.FirstAdmin != "mallory@example.com" { + t.Errorf("firstAdmin = %q, want the authenticated caller", rec.tenant.Spec.FirstAdmin) + } +} + +func TestGroupRestriction(t *testing.T) { + rec := &recorder{created: true} + r := NewREST(Options{Enabled: true, Groups: []string{"staff"}}, rec.create) + + if _, err := r.Create(ctxWithUser("alice@example.com", "staff"), request("acme"), nil, nil); err != nil { + t.Fatalf("a caller in the group was refused: %v", err) + } + + _, err := r.Create(ctxWithUser("mallory@example.com", "others"), request("evil"), nil, nil) + if !apierrors.IsForbidden(err) { + t.Fatalf("err = %v, want Forbidden for a caller outside the groups", err) + } + if rec.calls != 1 { + t.Errorf("calls = %d, want only the permitted one", rec.calls) + } +} + +func TestExistingTenantIsNotClaimed(t *testing.T) { + // Someone else may already hold that name. The answer must not imply + // the caller now administers it. + rec := &recorder{created: false} + r := NewREST(Options{Enabled: true}, rec.create) + + obj, err := r.Create(ctxWithUser("mallory@example.com"), request("acme"), nil, nil) + if err != nil { + t.Fatalf("Create: %v", err) + } + out := obj.(*tenancyv1alpha1.SelfTenantRequest) + if out.Status.Created { + t.Errorf("status claims creation of an existing tenant") + } + if got := out.Status.Message; got != `tenant "acme" already exists` { + t.Errorf("message = %q, should not promise admin of someone else's tenant", got) + } +} + +func TestNameMustBeAWorkspaceName(t *testing.T) { + rec := &recorder{} + r := NewREST(Options{Enabled: true}, rec.create) + + _, err := r.Create(ctxWithUser("alice@example.com"), request("Not A Label"), nil, nil) + if !apierrors.IsInvalid(err) { + t.Fatalf("err = %v, want Invalid", err) + } + if rec.calls != 0 { + t.Errorf("an invalid request reached the credential") + } +} + +func TestUnauthenticatedIsRefused(t *testing.T) { + rec := &recorder{} + r := NewREST(Options{Enabled: true}, rec.create) + + _, err := r.Create(context.Background(), request("acme"), nil, nil) + if !apierrors.IsUnauthorized(err) { + t.Fatalf("err = %v, want Unauthorized", err) + } +} diff --git a/tenancy/sdk/apis/tenancy/v1alpha1/doc.go b/tenancy/sdk/apis/tenancy/v1alpha1/doc.go index cbca894..f38314b 100644 --- a/tenancy/sdk/apis/tenancy/v1alpha1/doc.go +++ b/tenancy/sdk/apis/tenancy/v1alpha1/doc.go @@ -15,7 +15,7 @@ limitations under the License. */ // Package v1alpha1 holds the API types for the tenancy component (group -// tenancy.contrib.kcp.io). +// tenancy.platform.kcp.io). // // Three persisted, cluster-scoped kinds — Tenant, Project and Membership — // are exported through an APIExport and bound into an organization @@ -25,5 +25,5 @@ limitations under the License. // identity a member of, and as what role?". // // +k8s:openapi-gen=true -// +groupName=tenancy.contrib.kcp.io +// +groupName=tenancy.platform.kcp.io package v1alpha1 diff --git a/tenancy/sdk/apis/tenancy/v1alpha1/register.go b/tenancy/sdk/apis/tenancy/v1alpha1/register.go index d9e8ee1..e7b83b2 100644 --- a/tenancy/sdk/apis/tenancy/v1alpha1/register.go +++ b/tenancy/sdk/apis/tenancy/v1alpha1/register.go @@ -22,7 +22,7 @@ import ( "k8s.io/apimachinery/pkg/runtime/schema" ) -const GroupName = "tenancy.contrib.kcp.io" +const GroupName = "tenancy.platform.kcp.io" var ( SchemeBuilder = runtime.NewSchemeBuilder(addKnownTypes) @@ -48,6 +48,10 @@ func addKnownTypes(scheme *runtime.Scheme) error { &MembershipList{}, &SelfTenancyReview{}, &SelfTenancyReviewList{}, + &SelfProjectRequest{}, + &SelfProjectRequestList{}, + &SelfTenantRequest{}, + &SelfTenantRequestList{}, ) metav1.AddToGroupVersion(scheme, SchemeGroupVersion) return nil diff --git a/tenancy/sdk/apis/tenancy/v1alpha1/types.go b/tenancy/sdk/apis/tenancy/v1alpha1/types.go index b69c7cc..e6943d9 100644 --- a/tenancy/sdk/apis/tenancy/v1alpha1/types.go +++ b/tenancy/sdk/apis/tenancy/v1alpha1/types.go @@ -64,6 +64,7 @@ const ( // Subject identifies who a Membership is for. type Subject struct { // Kind is User or Group. + // +kubebuilder:validation:Enum=User;Group Kind SubjectKind `json:"kind"` // Name is the username or group name, compared verbatim against the // identity kcp authenticates. No issuer prefixes are added or stripped @@ -77,6 +78,9 @@ type Subject struct { // Tenant object lives in and reports it in Status. // // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object +// +kubebuilder:object:root=true +// +kubebuilder:resource:scope=Cluster +// +kubebuilder:subresource:status type Tenant struct { metav1.TypeMeta `json:",inline"` // +optional @@ -96,6 +100,21 @@ type TenantSpec struct { // Description is free text for humans. // +optional Description string `json:"description,omitempty"` + // FirstAdmin is an identity granted the admin role on this tenant once + // its workspace is ready, as a Membership the operator creates. + // + // It exists because a tenant nobody administers is unusable, and the + // two writes cannot be one: the Membership lives in the tenant's own + // workspace, which does not exist when the Tenant is created. Naming + // the admin here lets whoever creates the tenant hand it over without + // waiting, and is what makes self-service possible — the virtual + // workspace sets it to the caller, so a caller cannot make someone + // else the admin of a tenant they asked for. + // + // Empty means nobody is seeded, which is the right answer when an + // administrator intends to grant access separately. + // +optional + FirstAdmin string `json:"firstAdmin,omitempty"` } // TenantStatus is the observed state of a Tenant. @@ -120,6 +139,7 @@ type TenantStatus struct { // TenantList is the list form of Tenant. // // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object +// +kubebuilder:object:root=true type TenantList struct { metav1.TypeMeta `json:",inline"` metav1.ListMeta `json:"metadata,omitempty"` @@ -132,6 +152,9 @@ type TenantList struct { // project, project Memberships reach one. // // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object +// +kubebuilder:object:root=true +// +kubebuilder:resource:scope=Cluster +// +kubebuilder:subresource:status type Project struct { metav1.TypeMeta `json:",inline"` // +optional @@ -177,6 +200,7 @@ type ProjectStatus struct { // ProjectList is the list form of Project. // // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object +// +kubebuilder:object:root=true type ProjectList struct { metav1.TypeMeta `json:",inline"` metav1.ListMeta `json:"metadata,omitempty"` @@ -189,6 +213,9 @@ type ProjectList struct { // workspace; deleting the Membership removes that RBAC again. // // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object +// +kubebuilder:object:root=true +// +kubebuilder:resource:scope=Cluster +// +kubebuilder:subresource:status type Membership struct { metav1.TypeMeta `json:",inline"` // +optional @@ -204,6 +231,7 @@ type MembershipSpec struct { // Subject is who the grant is for. Subject Subject `json:"subject"` // Role is the access level granted: view, edit or admin. + // +kubebuilder:validation:Enum=view;edit;admin Role Role `json:"role"` // Tenant names the Tenant (in the same workspace) the grant applies to. Tenant string `json:"tenant"` @@ -225,6 +253,7 @@ type MembershipStatus struct { // MembershipList is the list form of Membership. // // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object +// +kubebuilder:object:root=true type MembershipList struct { metav1.TypeMeta `json:",inline"` metav1.ListMeta `json:"metadata,omitempty"` @@ -309,3 +338,131 @@ type SelfTenancyReviewList struct { Items []SelfTenancyReview `json:"items"` } + +// SelfProjectRequest asks for a project in a tenant the caller +// administers. It is the one write the tenancy virtual workspace does on +// a caller's behalf, and it exists because the alternative is worse: +// Projects live in the tenant's own workspace, which is the record store +// that decides who may reach what, so letting a tenant admin write there +// directly would hand them the Memberships governing themselves. +// +// The virtual workspace therefore holds the only credential into that +// tier. It authorizes the request against the caller's own Membership — +// admin on that tenant — and creates the Project itself. Nothing is +// relayed and no privilege is lent: a caller who is not an admin of the +// named tenant is refused, and one who is gets exactly one object +// created. +// +// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object +// +kubebuilder:object:root=true +type SelfProjectRequest struct { + metav1.TypeMeta `json:",inline"` + // +optional + metav1.ObjectMeta `json:"metadata,omitempty"` + + Spec SelfProjectRequestSpec `json:"spec"` + // +optional + Status SelfProjectRequestStatus `json:"status,omitempty"` +} + +// SelfProjectRequestSpec names the project to create. +type SelfProjectRequestSpec struct { + // Tenant is the tenant to create the project in. The caller must hold + // the admin role there. + Tenant string `json:"tenant"` + // Name is the project's object name, which also seeds its workspace + // name. + Name string `json:"name"` + // DisplayName is the project's human name. Defaults to Name. + // +optional + DisplayName string `json:"displayName,omitempty"` + // Description is free text for humans. + // +optional + Description string `json:"description,omitempty"` +} + +// SelfProjectRequestStatus reports what the request produced. +type SelfProjectRequestStatus struct { + // Created is true when the Project was created by this request, and + // false when it already existed — the request is idempotent, so + // asking twice is not an error. + // +optional + Created bool `json:"created,omitempty"` + // Project is the created object's name. + // +optional + Project string `json:"project,omitempty"` + // Message explains the outcome in a sentence. + // +optional + Message string `json:"message,omitempty"` +} + +// SelfProjectRequestList is the list form, which exists because the API +// machinery requires it; the resource is create-only. +// +// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object +// +kubebuilder:object:root=true +type SelfProjectRequestList struct { + metav1.TypeMeta `json:",inline"` + metav1.ListMeta `json:"metadata,omitempty"` + Items []SelfProjectRequest `json:"items"` +} + +// SelfTenantRequest asks for a tenant, with the caller as its first +// admin. It is how someone who is a member of nothing gets started. +// +// Unlike every other self-service path here, there is no Membership to +// authorize against — that is the point — so the gate is the +// deployment's: self-service is off unless enabled, and may be limited +// to groups the identity provider asserts. +// +// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object +// +kubebuilder:object:root=true +type SelfTenantRequest struct { + metav1.TypeMeta `json:",inline"` + // +optional + metav1.ObjectMeta `json:"metadata,omitempty"` + + Spec SelfTenantRequestSpec `json:"spec"` + // +optional + Status SelfTenantRequestStatus `json:"status,omitempty"` +} + +// SelfTenantRequestSpec names the tenant to create. The first admin is +// not here: it is the caller, and the server sets it. +type SelfTenantRequestSpec struct { + // Name is the tenant's object name, which also seeds its workspace + // name. + Name string `json:"name"` + // DisplayName is the tenant's human name. Defaults to Name. + // +optional + DisplayName string `json:"displayName,omitempty"` + // Description is free text for humans. + // +optional + Description string `json:"description,omitempty"` +} + +// SelfTenantRequestStatus reports what the request produced. +type SelfTenantRequestStatus struct { + // Created is true when this request created the tenant, and false + // when one of that name already existed — which does not mean the + // caller can reach it. + // +optional + Created bool `json:"created,omitempty"` + // Tenant is the tenant's name. + // +optional + Tenant string `json:"tenant,omitempty"` + // Message explains the outcome in a sentence. + // +optional + Message string `json:"message,omitempty"` +} + +// SelfTenantRequestList is the list form, which the API machinery +// requires; the resource is create-only. +// +// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object +// +kubebuilder:object:root=true +type SelfTenantRequestList struct { + metav1.TypeMeta `json:",inline"` + metav1.ListMeta `json:"metadata,omitempty"` + Items []SelfTenantRequest `json:"items"` +} diff --git a/tenancy/sdk/apis/tenancy/v1alpha1/zz_generated_deepcopy.go b/tenancy/sdk/apis/tenancy/v1alpha1/zz_generated_deepcopy.go index cd3370a..f0ab004 100644 --- a/tenancy/sdk/apis/tenancy/v1alpha1/zz_generated_deepcopy.go +++ b/tenancy/sdk/apis/tenancy/v1alpha1/zz_generated_deepcopy.go @@ -325,3 +325,121 @@ func (in *SelfTenancyReviewList) DeepCopyObject() runtime.Object { } return nil } + +// DeepCopyInto is a deepcopy function, copying the receiver, writing into out. in must be non-nil. +func (in *SelfProjectRequest) DeepCopyInto(out *SelfProjectRequest) { + *out = *in + out.TypeMeta = in.TypeMeta + in.ObjectMeta.DeepCopyInto(&out.ObjectMeta) + out.Spec = in.Spec + out.Status = in.Status +} + +// DeepCopy is a deepcopy function, copying the receiver, creating a new SelfProjectRequest. +func (in *SelfProjectRequest) DeepCopy() *SelfProjectRequest { + if in == nil { + return nil + } + out := new(SelfProjectRequest) + in.DeepCopyInto(out) + return out +} + +// DeepCopyObject is a deepcopy function, copying the receiver, creating a new runtime.Object. +func (in *SelfProjectRequest) DeepCopyObject() runtime.Object { + if c := in.DeepCopy(); c != nil { + return c + } + return nil +} + +// DeepCopyInto is a deepcopy function, copying the receiver, writing into out. in must be non-nil. +func (in *SelfProjectRequestList) DeepCopyInto(out *SelfProjectRequestList) { + *out = *in + out.TypeMeta = in.TypeMeta + in.ListMeta.DeepCopyInto(&out.ListMeta) + if in.Items != nil { + l := make([]SelfProjectRequest, len(in.Items)) + for i := range in.Items { + in.Items[i].DeepCopyInto(&l[i]) + } + out.Items = l + } +} + +// DeepCopy is a deepcopy function, copying the receiver, creating a new SelfProjectRequestList. +func (in *SelfProjectRequestList) DeepCopy() *SelfProjectRequestList { + if in == nil { + return nil + } + out := new(SelfProjectRequestList) + in.DeepCopyInto(out) + return out +} + +// DeepCopyObject is a deepcopy function, copying the receiver, creating a new runtime.Object. +func (in *SelfProjectRequestList) DeepCopyObject() runtime.Object { + if c := in.DeepCopy(); c != nil { + return c + } + return nil +} + +// DeepCopyInto is a deepcopy function, copying the receiver, writing into out. in must be non-nil. +func (in *SelfTenantRequest) DeepCopyInto(out *SelfTenantRequest) { + *out = *in + out.TypeMeta = in.TypeMeta + in.ObjectMeta.DeepCopyInto(&out.ObjectMeta) + out.Spec = in.Spec + out.Status = in.Status +} + +// DeepCopy is a deepcopy function, copying the receiver, creating a new SelfTenantRequest. +func (in *SelfTenantRequest) DeepCopy() *SelfTenantRequest { + if in == nil { + return nil + } + out := new(SelfTenantRequest) + in.DeepCopyInto(out) + return out +} + +// DeepCopyObject is a deepcopy function, copying the receiver, creating a new runtime.Object. +func (in *SelfTenantRequest) DeepCopyObject() runtime.Object { + if c := in.DeepCopy(); c != nil { + return c + } + return nil +} + +// DeepCopyInto is a deepcopy function, copying the receiver, writing into out. in must be non-nil. +func (in *SelfTenantRequestList) DeepCopyInto(out *SelfTenantRequestList) { + *out = *in + out.TypeMeta = in.TypeMeta + in.ListMeta.DeepCopyInto(&out.ListMeta) + if in.Items != nil { + l := make([]SelfTenantRequest, len(in.Items)) + for i := range in.Items { + in.Items[i].DeepCopyInto(&l[i]) + } + out.Items = l + } +} + +// DeepCopy is a deepcopy function, copying the receiver, creating a new SelfTenantRequestList. +func (in *SelfTenantRequestList) DeepCopy() *SelfTenantRequestList { + if in == nil { + return nil + } + out := new(SelfTenantRequestList) + in.DeepCopyInto(out) + return out +} + +// DeepCopyObject is a deepcopy function, copying the receiver, creating a new runtime.Object. +func (in *SelfTenantRequestList) DeepCopyObject() runtime.Object { + if c := in.DeepCopy(); c != nil { + return c + } + return nil +} diff --git a/tenancy/test/e2e/fixture_test.go b/tenancy/test/e2e/fixture_test.go index 2cdb19d..95ac4ae 100644 --- a/tenancy/test/e2e/fixture_test.go +++ b/tenancy/test/e2e/fixture_test.go @@ -349,7 +349,7 @@ func testContext(t *testing.T) context.Context { // bindingName mirrors the operator's deterministic binding naming. func bindingName(membershipName string) string { - return fmt.Sprintf("tenancy.contrib.kcp.io:membership:%s", membershipName) + return fmt.Sprintf("tenancy.platform.kcp.io:membership:%s", membershipName) } // getBinding fetches the materialized ClusterRoleBinding for a membership diff --git a/tenancy/test/e2e/scenarios_cli_test.go b/tenancy/test/e2e/scenarios_cli_test.go index e914c84..a402cdb 100644 --- a/tenancy/test/e2e/scenarios_cli_test.go +++ b/tenancy/test/e2e/scenarios_cli_test.go @@ -23,12 +23,16 @@ import ( "os" "os/exec" "path/filepath" + "sort" "strings" "testing" "time" + "k8s.io/client-go/tools/clientcmd" + clientcmdapi "k8s.io/client-go/tools/clientcmd/api" "sigs.k8s.io/controller-runtime/pkg/client" + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/pkg/naming" tenancyv1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/sdk/apis/tenancy/v1alpha1" ) @@ -141,7 +145,7 @@ func TestScenarioTenancyctlDrivesTheModel(t *testing.T) { projectWS := workspaceClient(t, projectObj.Status.URL) waitFor(t, ctx, "the CLI's grant to reach the project workspace", func(ctx context.Context) (bool, error) { - crb, err := getBinding(ctx, projectWS, "alice-"+tenant) + crb, err := getBinding(ctx, projectWS, naming.MembershipName(string(tenancyv1alpha1.SubjectKindUser), "alice", tenant, "")) if err != nil { return false, nil } @@ -151,7 +155,7 @@ func TestScenarioTenancyctlDrivesTheModel(t *testing.T) { // Revoking removes it again. tenancyctl(t, ctx, "revoke", "alice", "--tenant", tenant) waitFor(t, ctx, "the CLI's revoke to remove the binding", func(ctx context.Context) (bool, error) { - _, err := getBinding(ctx, projectWS, "alice-"+tenant) + _, err := getBinding(ctx, projectWS, naming.MembershipName(string(tenancyv1alpha1.SubjectKindUser), "alice", tenant, "")) return err != nil, nil }) } @@ -215,4 +219,34 @@ func TestScenarioTenancyctlWhoamiAndKubeconfig(t *testing.T) { t.Errorf("generated kubeconfig has no %q:\n%s", want, raw) } } + + // Projects only. The tenant workspace is this system's own record + // store: a Membership materializes RBAC in the tenant's projects and + // never in the tenant itself, so a context for it could only answer + // Forbidden and must not be written. + written, err := clientcmd.Load(raw) + if err != nil { + t.Fatalf("parse generated kubeconfig: %v", err) + } + if _, found := written.Contexts[tenant]; found { + t.Errorf("generated kubeconfig has a context for the tenant workspace %q, which no member can enter", tenant) + } + project := "web-" + suffix + if _, found := written.Contexts[tenant+"-"+project]; !found { + t.Errorf("generated kubeconfig has no context for project %q; got %v", + tenant+"-"+project, contextNames(written)) + } + if written.CurrentContext != tenant+"-"+project { + t.Errorf("current context is %q, want the project context %q", + written.CurrentContext, tenant+"-"+project) + } +} + +func contextNames(cfg *clientcmdapi.Config) []string { + names := make([]string, 0, len(cfg.Contexts)) + for name := range cfg.Contexts { + names = append(names, name) + } + sort.Strings(names) + return names } diff --git a/tenancy/test/e2e/scenarios_test.go b/tenancy/test/e2e/scenarios_test.go index 4a7e404..2524ac5 100644 --- a/tenancy/test/e2e/scenarios_test.go +++ b/tenancy/test/e2e/scenarios_test.go @@ -72,13 +72,23 @@ func TestScenarioInstallIsIdempotent(t *testing.T) { } } - for _, name := range []string{ - "v1alpha1.tenants.tenancy.contrib.kcp.io", - "v1alpha1.projects.tenancy.contrib.kcp.io", - "v1alpha1.memberships.tenancy.contrib.kcp.io", - } { - if _, err := dyn.Resource(apiResourceSchemaGVR).Get(ctx, name, metav1.GetOptions{}); err != nil { - t.Errorf("APIResourceSchema %s missing: %v", name, err) + // Schema names are generated (content-addressed by `make generate`), + // so assert what the exports actually reference rather than a spelling. + for _, exportName := range []string{exportPlatform, exportTenancy} { + export, err := dyn.Resource(apiExportGVR).Get(ctx, exportName, metav1.GetOptions{}) + if err != nil { + t.Fatalf("get %s: %v", exportName, err) + } + resources, _, _ := unstructured.NestedSlice(export.Object, "spec", "resources") + if len(resources) == 0 { + t.Errorf("APIExport %s serves no resources", exportName) + } + for _, r := range resources { + m, _ := r.(map[string]any) + schemaName, _ := m["schema"].(string) + if _, err := dyn.Resource(apiResourceSchemaGVR).Get(ctx, schemaName, metav1.GetOptions{}); err != nil { + t.Errorf("APIResourceSchema %s referenced by %s missing: %v", schemaName, exportName, err) + } } } @@ -280,7 +290,7 @@ func TestScenarioMembershipMaterializesInProjectsOnly(t *testing.T) { if err != nil { return false, nil } - return crb.RoleRef.Name == "tenancy.contrib.kcp.io:role:admin", nil + return crb.RoleRef.Name == "tenancy.platform.kcp.io:role:admin", nil }) } @@ -362,7 +372,7 @@ func TestScenarioChangingTheRoleReplacesTheBinding(t *testing.T) { if err != nil { return false, nil } - return crb.RoleRef.Name == "tenancy.contrib.kcp.io:role:edit", nil + return crb.RoleRef.Name == "tenancy.platform.kcp.io:role:edit", nil }) } From d896436b7c03ce756e3754d90f507162ff68ae4d Mon Sep 17 00:00:00 2001 From: olamilekan000 Date: Mon, 2 Nov 2026 04:11:56 +0100 Subject: [PATCH 2/2] marketplace: add the marketplace VW, producer quickstart, mcp offering and shared tilt Signed-off-by: olamilekan000 --- .github/workflows/ci.yaml | 4 +- .github/workflows/images.yaml | 2 + .gitignore | 5 + Dockerfile | 11 + Makefile | 42 +- README.md | 81 +- Tiltfile | 676 ++++ access/cmd/scar-to-kubeconfig/main.go | 133 +- access/pkg/cli/scar.go | 173 + cmd/cli/main.go | 150 + go.mod | 4 + go.sum | 10 + hack/tilt/README.md | 595 +++ hack/tilt/dex-pki.sh | 86 + hack/tilt/dex.yaml | 175 + hack/tilt/ingress-forward.sh | 53 + hack/tilt/mcp-offering.sh | 127 + hack/tilt/pki.sh | 48 + hack/tilt/up.sh | 43 + hack/tools/tools.go | 27 + hack/update-apiresourceschemas.sh | 118 + marketplace/README.md | 628 ++++ marketplace/cmd/init.go | 201 + marketplace/cmd/operator.go | 90 + marketplace/cmd/root.go | 59 + marketplace/cmd/virtualworkspace.go | 43 + .../config/apiexport/apiexport-catalog.yaml | 16 + .../apiexport/apiexport-provisioner.yaml | 16 + .../config/apiexport/apiexport-publish.yaml | 51 + .../apiexport/apiexportendpointslices.yaml | 25 + ...producers.marketplace.platform.kcp.io.yaml | 106 + marketplace/config/apiexport/bootstrap.go | 94 + .../config/apiexport/catalog-bindings.yaml | 16 + .../config/apiexport/producers-bindings.yaml | 29 + marketplace/config/apiexport/rbac-bind.yaml | 63 + .../config/apiexport/workspacetypes.yaml | 27 + marketplace/config/examples/README.md | 65 + marketplace/config/examples/apply.sh | 94 + marketplace/config/examples/producer.yaml | 15 + .../config/examples/things-instructions.yaml | 49 + marketplace/config/examples/things.yaml | 70 + marketplace/config/examples/widgets.yaml | 61 + marketplace/hack/ci/run-e2e-tests.sh | 283 ++ marketplace/hack/ci/run-spike.sh | 95 + marketplace/main.go | 35 + marketplace/pkg/bootstrap/bootstrap.go | 528 +++ marketplace/pkg/cli/offers.go | 456 +++ marketplace/pkg/directory/directory.go | 301 ++ marketplace/pkg/directory/directory_test.go | 66 + .../generated/openapi/zz_generated.openapi.go | 3264 +++++++++++++++++ marketplace/pkg/offering/offering.go | 159 + marketplace/pkg/offering/offering_test.go | 178 + marketplace/pkg/operator/operator.go | 308 ++ marketplace/pkg/operator/provider.go | 161 + marketplace/pkg/operator/publish.go | 210 ++ marketplace/pkg/operator/workspaces.go | 113 + marketplace/pkg/provider/provider.go | 299 ++ marketplace/pkg/server/options.go | 149 + marketplace/pkg/server/server.go | 192 + marketplace/pkg/virtual/catalog/offerings.go | 105 + .../pkg/virtual/catalog/virtualworkspace.go | 87 + .../sdk/apis/marketplace/v1alpha1/doc.go | 34 + .../sdk/apis/marketplace/v1alpha1/register.go | 50 + .../sdk/apis/marketplace/v1alpha1/types.go | 302 ++ .../v1alpha1/zz_generated_deepcopy.go | 227 ++ marketplace/test/e2e/fixture_test.go | 480 +++ marketplace/test/e2e/scenarios_test.go | 332 ++ marketplace/test/e2e/scenarios_vw_test.go | 211 ++ mcp/README.md | 143 +- mcp/cmd/init.go | 93 + mcp/cmd/operator.go | 102 + mcp/cmd/root.go | 2 + mcp/config/apiexport/apiexport-mcp.yaml | 51 + .../apiexport/apiexportendpointslice.yaml | 12 + ...hema-mcpendpoints.mcp.platform.kcp.io.yaml | 81 + mcp/config/apiexport/bootstrap.go | 50 + mcp/config/apiexport/instructions.yaml | 244 ++ mcp/config/apiexport/rbac-bind.yaml | 29 + mcp/pkg/bootstrap/bootstrap.go | 377 ++ mcp/pkg/operator/operator.go | 295 ++ mcp/sdk/apis/mcp/v1alpha1/doc.go | 28 + mcp/sdk/apis/mcp/v1alpha1/register.go | 58 + mcp/sdk/apis/mcp/v1alpha1/types.go | 87 + .../mcp/v1alpha1/zz_generated_deepcopy.go | 103 + producer-quickstart/.github/workflows/ci.yaml | 37 + producer-quickstart/.gitignore | 3 + producer-quickstart/Dockerfile | 19 + producer-quickstart/Makefile | 46 + producer-quickstart/README.md | 140 + .../apis/v1alpha1/database_types.go | 114 + producer-quickstart/apis/v1alpha1/doc.go | 27 + .../apis/v1alpha1/groupversion_info.go | 37 + .../apis/v1alpha1/zz_generated.deepcopy.go | 106 + producer-quickstart/cmd/producer/main.go | 122 + producer-quickstart/config/apiexport.yaml | 33 + .../config/apiexportendpointslice.yaml | 15 + ...rceschema-databases.dbaas.example.com.yaml | 174 + .../config/deploy/deployment.yaml | 51 + producer-quickstart/config/instructions.yaml | 56 + producer-quickstart/config/producer.yaml | 16 + producer-quickstart/go.mod | 120 + producer-quickstart/go.sum | 343 ++ producer-quickstart/hack/publish.sh | 65 + producer-quickstart/hack/tools/tools.go | 25 + producer-quickstart/hack/update-codegen.sh | 50 + .../controller/database_controller.go | 170 + .../controller/database_controller_test.go | 97 + 107 files changed, 16490 insertions(+), 137 deletions(-) create mode 100644 Tiltfile create mode 100644 access/pkg/cli/scar.go create mode 100644 cmd/cli/main.go create mode 100644 hack/tilt/README.md create mode 100755 hack/tilt/dex-pki.sh create mode 100644 hack/tilt/dex.yaml create mode 100755 hack/tilt/ingress-forward.sh create mode 100755 hack/tilt/mcp-offering.sh create mode 100755 hack/tilt/pki.sh create mode 100755 hack/tilt/up.sh create mode 100644 hack/tools/tools.go create mode 100755 hack/update-apiresourceschemas.sh create mode 100644 marketplace/README.md create mode 100644 marketplace/cmd/init.go create mode 100644 marketplace/cmd/operator.go create mode 100644 marketplace/cmd/root.go create mode 100644 marketplace/cmd/virtualworkspace.go create mode 100644 marketplace/config/apiexport/apiexport-catalog.yaml create mode 100644 marketplace/config/apiexport/apiexport-provisioner.yaml create mode 100644 marketplace/config/apiexport/apiexport-publish.yaml create mode 100644 marketplace/config/apiexport/apiexportendpointslices.yaml create mode 100644 marketplace/config/apiexport/apiresourceschema-producers.marketplace.platform.kcp.io.yaml create mode 100644 marketplace/config/apiexport/bootstrap.go create mode 100644 marketplace/config/apiexport/catalog-bindings.yaml create mode 100644 marketplace/config/apiexport/producers-bindings.yaml create mode 100644 marketplace/config/apiexport/rbac-bind.yaml create mode 100644 marketplace/config/apiexport/workspacetypes.yaml create mode 100644 marketplace/config/examples/README.md create mode 100755 marketplace/config/examples/apply.sh create mode 100644 marketplace/config/examples/producer.yaml create mode 100644 marketplace/config/examples/things-instructions.yaml create mode 100644 marketplace/config/examples/things.yaml create mode 100644 marketplace/config/examples/widgets.yaml create mode 100755 marketplace/hack/ci/run-e2e-tests.sh create mode 100755 marketplace/hack/ci/run-spike.sh create mode 100644 marketplace/main.go create mode 100644 marketplace/pkg/bootstrap/bootstrap.go create mode 100644 marketplace/pkg/cli/offers.go create mode 100644 marketplace/pkg/directory/directory.go create mode 100644 marketplace/pkg/directory/directory_test.go create mode 100644 marketplace/pkg/generated/openapi/zz_generated.openapi.go create mode 100644 marketplace/pkg/offering/offering.go create mode 100644 marketplace/pkg/offering/offering_test.go create mode 100644 marketplace/pkg/operator/operator.go create mode 100644 marketplace/pkg/operator/provider.go create mode 100644 marketplace/pkg/operator/publish.go create mode 100644 marketplace/pkg/operator/workspaces.go create mode 100644 marketplace/pkg/provider/provider.go create mode 100644 marketplace/pkg/server/options.go create mode 100644 marketplace/pkg/server/server.go create mode 100644 marketplace/pkg/virtual/catalog/offerings.go create mode 100644 marketplace/pkg/virtual/catalog/virtualworkspace.go create mode 100644 marketplace/sdk/apis/marketplace/v1alpha1/doc.go create mode 100644 marketplace/sdk/apis/marketplace/v1alpha1/register.go create mode 100644 marketplace/sdk/apis/marketplace/v1alpha1/types.go create mode 100644 marketplace/sdk/apis/marketplace/v1alpha1/zz_generated_deepcopy.go create mode 100644 marketplace/test/e2e/fixture_test.go create mode 100644 marketplace/test/e2e/scenarios_test.go create mode 100644 marketplace/test/e2e/scenarios_vw_test.go create mode 100644 mcp/cmd/init.go create mode 100644 mcp/cmd/operator.go create mode 100644 mcp/config/apiexport/apiexport-mcp.yaml create mode 100644 mcp/config/apiexport/apiexportendpointslice.yaml create mode 100644 mcp/config/apiexport/apiresourceschema-mcpendpoints.mcp.platform.kcp.io.yaml create mode 100644 mcp/config/apiexport/bootstrap.go create mode 100644 mcp/config/apiexport/instructions.yaml create mode 100644 mcp/config/apiexport/rbac-bind.yaml create mode 100644 mcp/pkg/bootstrap/bootstrap.go create mode 100644 mcp/pkg/operator/operator.go create mode 100644 mcp/sdk/apis/mcp/v1alpha1/doc.go create mode 100644 mcp/sdk/apis/mcp/v1alpha1/register.go create mode 100644 mcp/sdk/apis/mcp/v1alpha1/types.go create mode 100644 mcp/sdk/apis/mcp/v1alpha1/zz_generated_deepcopy.go create mode 100644 producer-quickstart/.github/workflows/ci.yaml create mode 100644 producer-quickstart/.gitignore create mode 100644 producer-quickstart/Dockerfile create mode 100644 producer-quickstart/Makefile create mode 100644 producer-quickstart/README.md create mode 100644 producer-quickstart/apis/v1alpha1/database_types.go create mode 100644 producer-quickstart/apis/v1alpha1/doc.go create mode 100644 producer-quickstart/apis/v1alpha1/groupversion_info.go create mode 100644 producer-quickstart/apis/v1alpha1/zz_generated.deepcopy.go create mode 100644 producer-quickstart/cmd/producer/main.go create mode 100644 producer-quickstart/config/apiexport.yaml create mode 100644 producer-quickstart/config/apiexportendpointslice.yaml create mode 100644 producer-quickstart/config/apiresourceschema-databases.dbaas.example.com.yaml create mode 100644 producer-quickstart/config/deploy/deployment.yaml create mode 100644 producer-quickstart/config/instructions.yaml create mode 100644 producer-quickstart/config/producer.yaml create mode 100644 producer-quickstart/go.mod create mode 100644 producer-quickstart/go.sum create mode 100755 producer-quickstart/hack/publish.sh create mode 100644 producer-quickstart/hack/tools/tools.go create mode 100755 producer-quickstart/hack/update-codegen.sh create mode 100644 producer-quickstart/internal/controller/database_controller.go create mode 100644 producer-quickstart/internal/controller/database_controller_test.go diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index a910619..72904a7 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -82,7 +82,7 @@ jobs: strategy: fail-fast: false matrix: - component: [access, mcp, ephemeral, tenancy] + component: [access, mcp, ephemeral, tenancy, marketplace] steps: - name: Checkout uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # tag=v7.0.1 @@ -97,7 +97,7 @@ jobs: - name: Run e2e tests run: make test-e2e-${{ matrix.component }} env: - # Only the ephemeral and tenancy harnesses read this. Set the KCP_IMAGE + # Only the ephemeral, tenancy and marketplace harnesses read this. Set the KCP_IMAGE # repository variable to pin a tag when kcp main is broken and the # noise is not useful. KCP_IMAGE: ${{ vars.KCP_IMAGE || 'ghcr.io/kcp-dev/kcp:main' }} diff --git a/.github/workflows/images.yaml b/.github/workflows/images.yaml index 6364d9e..a6ac76a 100644 --- a/.github/workflows/images.yaml +++ b/.github/workflows/images.yaml @@ -35,6 +35,8 @@ jobs: description: kcp ephemeral resources virtual workspace (ephemeral-virtual-workspace, endpointslice-controller, example-webhook) - component: tenancy-vw description: kcp tenancy component (tenancy-vw server with init, operator and virtualworkspace subcommands, plus the tenancyctl client) + - component: marketplace-vw + description: kcp marketplace component (marketplace-vw server with init, operator and virtualworkspace subcommands) steps: - name: Checkout uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # tag=v7.0.1 diff --git a/.gitignore b/.gitignore index 5ebf941..888634b 100644 --- a/.gitignore +++ b/.gitignore @@ -11,10 +11,14 @@ cover.out .local/ pki/ .dex/ +.tilt/ # Kubeconfigs the README walkthrough writes (`tenancyctl kubeconfig -o ...`). *.kubeconfig +# Serial files `openssl x509 -CAcreateserial` leaves beside wherever it ran. +*.srl + # Binaries built into component roots by `go build ./cmd/...`. They shadow # bin/ on tab-completion and go stale silently; use `make build`. /ephemeral/ephemeral-virtual-workspace @@ -26,3 +30,4 @@ pki/ # Self-signed serving certs a VW generates when none are supplied. apiserver.local.config/ +/marketplace/bin/ diff --git a/Dockerfile b/Dockerfile index cf00734..ad536c2 100644 --- a/Dockerfile +++ b/Dockerfile @@ -91,3 +91,14 @@ FROM gcr.io/distroless/static:nonroot AS tenancy-vw COPY --from=build-tenancy /out/ / USER 65532:65532 ENTRYPOINT ["/tenancy-vw"] + +# ── marketplace ────────────────────────────────────────────────────── +FROM builder AS build-marketplace +RUN --mount=type=cache,target=/go/pkg/mod \ + --mount=type=cache,target=/root/.cache/go-build \ + go build -o /out/marketplace-vw ./marketplace/ + +FROM gcr.io/distroless/static:nonroot AS marketplace-vw +COPY --from=build-marketplace /out/ / +USER 65532:65532 +ENTRYPOINT ["/marketplace-vw"] diff --git a/Makefile b/Makefile index 898592a..7694300 100644 --- a/Makefile +++ b/Makefile @@ -28,7 +28,7 @@ help: ## Show available targets # ── Build ──────────────────────────────────────────────────────────── .PHONY: build -build: build-access build-mcp build-ephemeral build-tenancy ## Build every binary into bin/ +build: build-access build-mcp build-ephemeral build-tenancy build-marketplace build-cli ## Build every binary into bin/ .PHONY: build-access build-access: ## Build the access virtual workspace binaries @@ -68,16 +68,20 @@ lint: ## Run golangci-lint (configuration in .golangci.yml) .PHONY: vet vet: ## Run go vet, including the e2e build tag so the tests cannot rot $(GO) vet ./... - $(GO) vet -tags e2e ./test/... ./access/test/... ./mcp/test/... ./ephemeral/test/... ./tenancy/test/... + $(GO) vet -tags e2e ./test/... ./access/test/... ./mcp/test/... ./ephemeral/test/... ./tenancy/test/... ./marketplace/test/... .PHONY: tidy tidy: ## Sync go.mod / go.sum $(GO) mod tidy .PHONY: verify -verify: verify-gofmt vet verify-fork-pin verify-e2e-manifests ## Run every verification check +verify: verify-gofmt vet verify-fork-pin verify-e2e-manifests verify-producer-quickstart ## Run every verification check $(GO) mod tidy -diff +.PHONY: verify-producer-quickstart +verify-producer-quickstart: ## Build and test the producer-quickstart template, which is a Go module of its own + cd producer-quickstart && $(GO) mod tidy -diff && $(GO) vet ./... && $(GO) build ./... && $(GO) test ./... + .PHONY: verify-gofmt verify-gofmt: ## Check gofmt -s cleanliness @out=$$(gofmt -l -s $$(find . -name '*.go' -not -path './$(BIN_DIR)/*')); \ @@ -95,7 +99,7 @@ verify-fork-pin: ## Check the kcp Kubernetes fork pin matches virtual-workspace- # Each component owns its e2e harness; these are the entry points CI uses. .PHONY: test-e2e -test-e2e: test-e2e-access test-e2e-mcp test-e2e-ephemeral test-e2e-tenancy ## Run every component's e2e tests in sequence +test-e2e: test-e2e-access test-e2e-mcp test-e2e-ephemeral test-e2e-tenancy test-e2e-marketplace ## Run every component's e2e tests in sequence .PHONY: test-e2e-access test-e2e-access: ## Run the access VW e2e tests (throwaway kind cluster via kcp-operator) @@ -113,6 +117,26 @@ test-e2e-ephemeral: ## Run the ephemeral VW e2e tests (local processes against a test-e2e-tenancy: ## Run the tenancy e2e tests (local processes against a real kcp) cd tenancy && ./hack/ci/run-e2e-tests.sh +.PHONY: generate +generate: ## Regenerate the APIResourceSchemas from the sdk Go types (controller-gen + kcp apigen) + ./hack/update-apiresourceschemas.sh + +.PHONY: build-cli +build-cli: ## Build contribctl, the repo-wide CLI bundling every component's client + $(GO) build -o $(BIN_DIR)/contribctl ./cmd/cli + +.PHONY: build-marketplace +build-marketplace: ## Build the marketplace server binary + $(GO) build -o $(BIN_DIR)/marketplace-vw ./marketplace + +.PHONY: test-spike-marketplace +test-spike-marketplace: ## Prove the marketplace design's binder composition against a real kcp + ./marketplace/hack/ci/run-spike.sh + +.PHONY: test-e2e-marketplace +test-e2e-marketplace: ## Run the marketplace e2e tests (local processes against a real kcp) + cd marketplace && ./hack/ci/run-e2e-tests.sh + # ── Images ─────────────────────────────────────────────────────────── # One Dockerfile, one shared builder stage, three image targets. @@ -120,7 +144,7 @@ IMAGE_PREFIX ?= ghcr.io/kcp-dev/contrib-virtual-workspaces IMAGE_TAG ?= latest .PHONY: images -images: image-access image-mcp image-ephemeral image-tenancy ## Build every container image +images: image-access image-mcp image-ephemeral image-tenancy image-marketplace ## Build every container image .PHONY: image-access image-access: ## Build the access-vw container image @@ -138,6 +162,14 @@ image-ephemeral: ## Build the ephemeral-vw container image image-tenancy: ## Build the tenancy-vw container image docker build --target tenancy-vw -t $(IMAGE_PREFIX)/tenancy-vw:$(IMAGE_TAG) . +.PHONY: image-marketplace +image-marketplace: ## Build the marketplace-vw container image + docker build --target marketplace-vw -t $(IMAGE_PREFIX)/marketplace-vw:$(IMAGE_TAG) . + +.PHONY: tilt-up +tilt-up: ## Bring up kcp (from $(KCP_DIR), default ../kcp) plus this repo's components under Tilt + ./hack/tilt/up.sh + .PHONY: clean clean: ## Remove build artifacts rm -rf $(BIN_DIR) diff --git a/README.md b/README.md index 65d5164..9d4c9c3 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,22 @@ # contrib-virtual-workspaces -Contrib virtual workspaces for [kcp](https://github.com/kcp-dev/kcp). +Virtual workspaces for [kcp](https://github.com/kcp-dev/kcp), and the +platform built out of two of them. + +**kcp Platform** is [tenancy/](tenancy/) and [marketplace/](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](https://github.com/olamilekan000/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/](access/) | **SelfClusterAccessReview** — "which workspaces can this user access?" in one call | `ghcr.io/kcp-dev/contrib-virtual-workspaces/access-vw` | | [mcp/](mcp/) | [Model Context Protocol](https://modelcontextprotocol.io) 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/](ephemeral/) | Non-persisted resources: `POST` in, a provider webhook answers, nothing reaches etcd | `ghcr.io/kcp-dev/contrib-virtual-workspaces/ephemeral-vw` | +| [ephemeral/](ephemeral/) | Non-persisted resources: `POST` in, a producer webhook answers, nothing reaches etcd | `ghcr.io/kcp-dev/contrib-virtual-workspaces/ephemeral-vw` | | [tenancy/](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/](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. @@ -35,6 +44,74 @@ 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: + +```sh +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/](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](https://github.com/kcp-dev/kcp/tree/main/contrib/tilt) — +operator, shards, front-proxy behind https://kcp.localhost:8443, +observability, dashboard), included unchanged by the repo +[Tiltfile](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/`. 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](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/](hack/dex/) diff --git a/Tiltfile b/Tiltfile new file mode 100644 index 0000000..8b15171 --- /dev/null +++ b/Tiltfile @@ -0,0 +1,676 @@ +# Tilt for the contrib virtual workspaces: kcp itself comes from the kcp +# repo's own Tilt setup (included below, unchanged), and this repo's +# components run on top as live-reloading local processes against it. +# +# hack/tilt/up.sh create the kind cluster and start tilt +# KCP_DIR=/path/to/kcp where the kcp checkout lives (default ../kcp) +# KCP_STATIC=false build kcp from the checkout's sources instead +# of running the published, version-matched +# images (the default is static: this repo +# develops AGAINST kcp, not kcp itself; pin +# with KCP_IMAGE_REPO/KCP_IMAGE_TAG) +# TENANCY_ENABLED=false skip a component (also MARKETPLACE_ENABLED) +# +# What you get: +# - everything kcp's contrib/tilt deploys (operator, shards, front-proxy +# behind an envoy gateway on https://kcp.localhost:8443, observability, +# optionally the dashboard), +# - admin kubeconfigs extracted into .tilt/ (tilt-frontproxy.kubeconfig, +# tilt-root.kubeconfig, tilt-theseus.kubeconfig), +# - per component: a build resource (rebuilds on source changes), an +# init resource (re-applies the exports — they are embedded in the +# binary, so a rebuilt binary re-runs init), and operator + virtual +# workspace processes that restart when the binary changes. + +KCP_DIR = os.getenv('KCP_DIR', '../kcp') +if not os.path.exists(KCP_DIR + '/contrib/tilt/Tiltfile'): + fail('no kcp checkout at %s — set KCP_DIR to your github.com/kcp-dev/kcp clone' % KCP_DIR) + +# kcp's extract-kubeconfig.bash honors this: the admin kubeconfigs land in +# OUR .tilt/ instead of the kcp repo root. +TILT_DIR = os.getcwd() + '/.tilt' +os.putenv('KCP_KUBECONFIG_DIR', TILT_DIR) + +# Static mode: the operator's default image tag (a release, v0.33.x) lags +# what these Tiltfiles and this repo are developed against. Track kcp main +# unless the caller pinned something else with KCP_IMAGE_REPO/KCP_IMAGE_TAG. +if os.getenv('KCP_IMAGE_TAG') == None: + os.putenv('KCP_IMAGE_TAG', 'main') + +# The dashboard lives in yet another sibling checkout; only keep kcp's +# default-on behavior when it is actually there. +if os.getenv('KCP_PORTAL_ENABLED') == None and not os.path.exists(KCP_DIR + '/../contrib-dashboard/Dockerfile'): + os.putenv('KCP_PORTAL_ENABLED', 'false') + +# Dex: an in-cluster OIDC issuer shared by kcp and the virtual workspaces, +# so `contribctl login` works against this environment. One +# issuer URL serves both sides: the host reaches it through the :8443 +# ingress port-forward, the kcp pods through their gateway hostAliases. +# Disable with DEX_ENABLED=false. +DEX_ENABLED = os.getenv('DEX_ENABLED', 'true').lower() not in ('false', '0', 'no', 'off') +DEX_ISSUER = 'https://dex.kcp.localhost:8443/dex' +DEX_HOSTNAME = 'dex.kcp.localhost' + +# ── kcp itself ─────────────────────────────────────────────────────── +# kcp's contrib/tilt ships two entry points: Tiltfile.static (published +# images, operator CRs generated by kcp_static.Tiltfile's deploy_kcp) and +# Tiltfile (built from source, hand-written CRs). Neither knows about an +# OIDC issuer, and an include() cannot be parameterized — so for the static +# path this file repeats the entry point's dozen lines and calls deploy_kcp +# itself, with dex as the issuer and dex's hostname among the hostAliases. +# Everything path-like is addressed through KCP_DIR so it tracks the kcp +# checkout rather than copying it. +# +# This replaced an earlier hand-off through KCP_OIDC_* environment variables +# that kcp's Tiltfile never actually read: with them, every kcp pod came up +# without an OIDC authenticator, and every dex token was "invalid bearer +# token" at the front-proxy. If kcp's entry point grows an oidc parameter, +# this block can shrink back to an include(). +KCP_TILT = KCP_DIR + '/contrib/tilt' +KCP_STATIC = os.getenv('KCP_STATIC', 'true').lower() not in ('false', '0', 'no', 'off') + +load('ext://helm_remote', 'helm_remote') +load('ext://namespace', 'namespace_create') +load('ext://cert_manager', 'deploy_cert_manager') +# load() is top-level only and takes only a string literal, and KCP_DIR is +# neither; a symlink under .tilt gives it a fixed path to a movable target. +local('mkdir -p "%s" && ln -sfn "%s" "%s/kcp"' % (TILT_DIR, os.path.abspath(KCP_DIR), TILT_DIR), quiet=True) +load('./.tilt/kcp/contrib/tilt/kcp_static.Tiltfile', 'deploy_kcp') + +if KCP_STATIC: + k8s_yaml(KCP_TILT + '/kernel-limits-job.yaml') + deploy_cert_manager(version='v1.19.2') + k8s_yaml(KCP_TILT + '/issuer.yaml') + + namespace_create('envoy-gateway-system') + helm_remote( + 'gateway-helm', + repo_url='oci://registry-1.docker.io/envoyproxy', + repo_name='gateway-helm', + release_name='envoy', + namespace='envoy-gateway-system', + version='v1.7.0', + values=[], + set=[], + ) + k8s_yaml(KCP_TILT + '/gateway.yaml') + # kcp's own `ingress` port-forward is left out: ingress-forward below does + # the same job with a readiness probe. + + if os.getenv('KCP_OBSERVABILITY_ENABLED', 'true').lower() not in ('false', '0', 'no', 'off'): + include(KCP_TILT + '/observability/Tiltfile') + else: + print('Observability stack disabled (KCP_OBSERVABILITY_ENABLED=false)') + + k8s_yaml(kustomize(KCP_TILT + '/etcd')) + k8s_yaml(kustomize(KCP_TILT + '/kcp-operator')) + + kcp_overrides = { + 'image_repo': os.getenv('KCP_IMAGE_REPO', ''), + 'image_tag': os.getenv('KCP_IMAGE_TAG', ''), + 'token_auth_secret': os.getenv('KCP_TOKEN_AUTH_SECRET', None) or None, + 'token_auth_key': os.getenv('KCP_TOKEN_AUTH_KEY', None) or None, + 'kubeconfig_dir': TILT_DIR, + } + if DEX_ENABLED: + # The same block the production chart takes. caFileRef is the dex-tls + # secret this file creates below — kcp reads dex's CA from it, which + # is why the secret is the source of truth for dex's certificate. + kcp_overrides['oidc'] = { + 'issuerURL': DEX_ISSUER, + 'clientID': 'kcp', + 'usernameClaim': 'email', + 'groupsClaim': 'groups', + 'caFileRef': {'name': 'dex-tls', 'key': 'ca.crt'}, + } + # deploy_kcp derives the kcp hostnames from the base domain; dex's + # has to be added so the pods resolve the issuer through the gateway. + kcp_overrides['hostnames'] = [ + 'kcp.localhost', 'root.kcp.localhost', 'theseus.kcp.localhost', DEX_HOSTNAME, + ] + deploy_kcp(base_domain='kcp.localhost', extra_shards=['theseus'], **kcp_overrides) + + if os.getenv('KCP_PORTAL_ENABLED', 'true').lower() not in ('false', '0', 'no', 'off'): + DASHBOARD_DIR = os.getenv('KCP_PORTAL_DIR', KCP_DIR + '/../contrib-dashboard') + manifest = DASHBOARD_DIR + '/deploy/deployment.yaml' + if not os.path.exists(manifest): + fail('contrib-dashboard not found at %s — set KCP_PORTAL_DIR to your checkout ' % DASHBOARD_DIR + + 'or disable the portal with KCP_PORTAL_ENABLED=false') + portal_image = os.getenv('KCP_PORTAL_IMAGE', 'ghcr.io/kcp-dev/contrib-dashboard:main') + dashboard_yaml = str(read_file(manifest)).replace('image: kcp-dashboard', 'image: ' + portal_image) + k8s_yaml(blob(dashboard_yaml)) + k8s_resource('kcp-dashboard', + port_forwards=['8080:8080'], + resource_deps=['kcp-admin extract'], + labels='dashboard', + ) + print('kcp portal → http://localhost:8080 (no-oidc, static image %s)' % portal_image) +else: + # Built from source: kcp's hand-written CRs, which carry no OIDC block. + # Rather than let the stack come up with an issuer nobody can sign in + # with, say so. + if DEX_ENABLED: + fail('KCP_STATIC=false runs kcp from the hand-written CRs in the checkout, which have no OIDC issuer; ' + + 'run with DEX_ENABLED=false, or use the default KCP_STATIC=true.') + include(KCP_TILT + '/Tiltfile') + +# ── this repo's components ─────────────────────────────────────────── + +# The components get their own credential rather than borrowing kcp's +# admin kubeconfig, because the group it carries matters: +# +# kcp's workspace admission records the creator as the workspace owner +# (LogicalCluster.spec.createdBy) only for identities that are NOT +# system-privileged, and the apibinder initializer impersonates that owner +# to bind a new workspace's defaultAPIBindings. A workspace created by a +# system:masters client therefore has no owner and sticks in Initializing +# on system:apibindings forever. +# +# kcp's own tilt mints its admin kubeconfigs with system:masters, and the +# front-proxy hides the problem by dropping that group on ingress — but +# our operators also talk to shard-direct APIExport URLs, where it is not +# dropped. So we mint system:kcp:admin without it: admin everywhere +# through RBAC, recorded as an owner, and not dependent on how the kcp +# checkout happens to be configured. +k8s_yaml(blob(""" +apiVersion: operator.kcp.io/v1alpha1 +kind: Kubeconfig +metadata: + name: contrib + namespace: default +spec: + username: contrib-admin + groups: ["system:kcp:admin"] + validity: 8766h + secretRef: + name: kcp-contrib-kubeconfig + target: + frontProxyRef: + name: frontproxy +""")) +local_resource('contrib-kubeconfig', + cmd='kubectl wait kubeconfig/contrib --for=create --timeout=5m && ' + + 'kubectl wait secret/kcp-contrib-kubeconfig --for=create --timeout=5m && ' + + "kubectl get secret/kcp-contrib-kubeconfig -o jsonpath='{.data.kubeconfig}' | base64 -d > " + + TILT_DIR + '/tilt-contrib.kubeconfig', + resource_deps=['kcp-admin extract'], + labels=['contrib'], +) + +# Everything in this stack is addressed through one port on the host, so +# keeping it up is not a detail: lose it and every kubeconfig, the UI and +# the CLI all fail at once, which looks like the components being broken +# rather than the address being gone. Tilt restarts a serve_cmd, and the +# script re-resolves the gateway Service each time round. +local_resource('ingress-forward', + serve_cmd='hack/tilt/ingress-forward.sh', + deps=['hack/tilt/ingress-forward.sh'], + readiness_probe=probe( + period_secs=5, + exec=exec_action(command=['sh', '-c', + 'curl -sk -o /dev/null --max-time 3 https://kcp.localhost:8443/readyz']), + ), + labels=['contrib'], +) + +KUBECONFIG = TILT_DIR + '/tilt-contrib.kubeconfig' +FRONT_PROXY_URL = os.getenv('KCP_FRONT_PROXY_URL', 'https://kcp.localhost:8443') + +# A throwaway client CA + alice/bob, so the virtual workspaces can +# authenticate direct callers during development. With dex enabled the +# same resource also mints dex's serving cert, whose CA every consumer +# (kcp via the dex-tls secret, the VWs and login via the file) trusts. +PKI_CMD = 'hack/tilt/pki.sh ' + TILT_DIR + '/pki' +if DEX_ENABLED: + PKI_CMD += ' && hack/tilt/dex-pki.sh ' + TILT_DIR + '/dex' +local_resource('dev-pki', + cmd=PKI_CMD, + labels=['contrib'], + allow_parallel=True, +) + +if DEX_ENABLED: + # The one secret both dex (tls.crt/tls.key) and the kcp shards + # (caFileRef -> ca.crt) mount. + local_resource('dex-secret', + cmd='kubectl create secret generic dex-tls' + + ' --from-file=tls.crt=' + TILT_DIR + '/dex/tls.crt' + + ' --from-file=tls.key=' + TILT_DIR + '/dex/tls.key' + + ' --from-file=ca.crt=' + TILT_DIR + '/dex/ca.crt' + + ' --dry-run=client -o yaml | kubectl apply -f -', + deps=[TILT_DIR + '/dex/tls.crt'], + resource_deps=['dev-pki'], + labels=['auth'], + allow_parallel=True, + ) + # Stamp the serving cert's fingerprint onto the pod template. + # + # dex reads its certificate once, at boot. Depending on dex-secret only + # orders startup — replacing a Secret does not roll a Deployment — so a + # regenerated cert left dex serving one that nothing trusted any more, + # and every OIDC validator answered 401 because it could not even fetch + # the discovery document. Making the cert part of the pod spec is what + # ties the two together: a new cert is a new Deployment, and Tilt rolls + # it. watch_file is what re-evaluates this when the cert changes. + watch_file(TILT_DIR + '/dex/tls.crt') + dex_cert_stamp = str(local( + 'shasum -a 256 %s/dex/tls.crt 2>/dev/null | cut -c1-16 || echo bootstrap' % TILT_DIR, + quiet=True, echo_off=True)).strip() + + dex_objects = read_yaml_stream('hack/tilt/dex.yaml') + for obj in dex_objects: + if obj['kind'] == 'Deployment' and obj['metadata']['name'] == 'dex': + template = obj['spec']['template'] + template.setdefault('metadata', {}).setdefault('annotations', {}) + template['metadata']['annotations']['kcp.localhost/serving-cert'] = dex_cert_stamp + k8s_yaml(encode_yaml_stream(dex_objects)) + k8s_resource('dex', resource_deps=['dex-secret'], labels=['auth']) + + # The issuer URL must resolve on the host too (the pods get it via + # hostAliases). Warn early instead of failing a login later. + if str(local('grep -qs dex.kcp.localhost /etc/hosts && echo yes || echo no', quiet=True)).strip() == 'no': + print('WARNING: dex.kcp.localhost missing from /etc/hosts — add it to the 127.0.0.1 line for login to work') + + print('dex → %s (alice@team-a.example.com / bob@team-b.example.com / mallory@strangers.example.com / admin@platform.example.com, password "password")' % DEX_ISSUER) + print('login: bin/contribctl login --issuer %s --certificate-authority %s/dex/ca.crt' % (DEX_ISSUER, TILT_DIR)) + print('walkthrough: hack/tilt/README.md') + print('JWT usernames arrive as the plain email, e.g. alice@team-a.example.com') + +# The flags every virtual workspace shares when dex is on, mirroring the +# shard-side mapping exactly (usernameClaim email, no prefix — the +# operator's documented "oidc:" default is not actually rendered) so a +# JWT names the same user at kcp and at a VW. The issuer's CA comes from +# the same dex-tls secret the shards mount, since these now run in the +# cluster rather than on the host. +OIDC_VW_ARGS_LIST = [] +if DEX_ENABLED: + OIDC_VW_ARGS_LIST = [ + '--oidc-issuer-url=' + DEX_ISSUER, + '--oidc-client-id=kcp', + '--oidc-username-claim=email', + '--oidc-groups-claim=groups', + '--oidc-ca-file=/etc/dex/ca.crt', + ] + +DEX_VW_VOLUMES = '' +if DEX_ENABLED: + DEX_VW_VOLUMES = """ extraVolumes: + - name: dex-ca + secret: + secretName: dex-tls + items: + - key: ca.crt + path: ca.crt + extraVolumeMounts: + - name: dex-ca + mountPath: /etc/dex + readOnly: true""" + +def enabled(name): + return os.getenv(name + '_ENABLED', 'true').lower() not in ('false', '0', 'no', 'off') + +# Every virtual workspace answers on the front-proxy, at the path it +# owns — so a client needs exactly one address for all of kcp. The +# operator does the wiring: it deploys each virtual workspace from a +# VirtualWorkspace object (Deployment + Service on :6443), issues its +# serving certificate from the shard CA and mounts the requestheader +# client CA, and the front-proxy mappings below forward the caller's +# identity to it in X-Remote-* headers over its own client certificate. +# +# Mappings are collected here and applied to the FrontProxy at the end, +# because one patch has to carry them all. +VW_PATH_MAPPINGS = [] + +# The kind cluster images are side-loaded into; matches hack/tilt/up.sh. +KIND_CLUSTER = os.getenv('CLUSTER_NAME', 'kcp-tilt') + +def yaml_list(items): + """Render a list of strings as a YAML flow sequence.""" + return '[' + ', '.join(['"%s"' % i for i in items]) + ']' + + +def virtual_workspace(name, image_target, service, init_args, vw_args, + server_cmd=None, init_cmd=None): + """Deploy one component's virtual workspace through the operator. + + server_cmd and init_cmd are the container commands. They default to + the single-binary-with-subcommands shape tenancy and marketplace use; + access ships separate binaries, and mcp has nothing to bootstrap at + all, so both are overridable. init_cmd=[] means this component + installs nothing and gets no bootstrap credential. + """ + if server_cmd == None: + server_cmd = ['/' + image_target, 'virtualworkspace'] + if init_cmd == None: + init_cmd = ['/' + image_target, 'init'] + + # Built and side-loaded by hand rather than with docker_build: the + # operator composes the image as ":", so there is no + # single field for Tilt to inject a ref into. A fixed tag plus an + # explicit rollout restart gets the new image running. + local_resource('%s-image' % name, + cmd=('docker build --target %s -t %s:dev . && ' % (image_target, image_target) + + 'kind load docker-image %s:dev --name %s && ' % (image_target, KIND_CLUSTER) + + 'kubectl rollout restart deploy/%s-virtual-workspace 2>/dev/null || true' % name), + deps=['go.mod', 'go.sum', 'Dockerfile'] + [ + p for p in [name + '/main.go', name + '/cmd', name + '/pkg', + name + '/internal', name + '/config', name + '/sdk'] + if os.path.exists(p) + ], + ignore=['**/*_test.go'], + labels=[name], + allow_parallel=True, + ) + + # Two credentials, because bootstrapping and serving want different + # ones: init walks the workspace tree and installs exports (admin), + # while the server only reads what its exports give it — init grants + # that identity the server role with --server-user. + bootstrap_kubeconfig = "" + if init_cmd: + bootstrap_kubeconfig = """apiVersion: operator.kcp.io/v1alpha1 +kind: Kubeconfig +metadata: + name: %(name)s-vw-bootstrap + namespace: default +spec: + username: kcp-admin + groups: ["system:kcp:admin"] + validity: 8766h + secretRef: + name: %(name)s-vw-bootstrap-kubeconfig + target: + frontProxyRef: + name: frontproxy +--- +""" % {'name': name} + + init_containers = "" + if init_cmd: + init_containers = """ initContainers: + - name: init + kubeconfigSecretRef: + name: %(name)s-vw-bootstrap-kubeconfig + command: %(init_cmd)s + args: + - --kubeconfig=/etc/kcp/init-kubeconfig/kubeconfig + - --server-user=%(name)s-vw +%(init_args)s""" % { + 'name': name, + 'init_cmd': yaml_list(init_cmd), + 'init_args': init_args, + } + + k8s_yaml(blob("""%(bootstrap_kubeconfig)sapiVersion: operator.kcp.io/v1alpha1 +kind: Kubeconfig +metadata: + name: %(name)s-vw-server + namespace: default +spec: + username: %(name)s-vw + validity: 8766h + targetWorkspace: root:%(name)s:controllers + secretRef: + name: %(name)s-vw-server-kubeconfig + target: + frontProxyRef: + name: frontproxy +--- +apiVersion: operator.kcp.io/v1alpha1 +kind: VirtualWorkspace +metadata: + name: %(name)s + namespace: default +spec: + target: + rootShardRef: + name: root + external: + hostname: kcp.localhost + port: 8443 + image: + repository: %(image)s + tag: dev + # One replica, small: this is a one-node development cluster. The + # operator's default is two replicas requesting a whole CPU each, which + # for four virtual workspaces is eight CPUs before anything else runs — + # and a rollout adds a surge pod on top, which then cannot schedule and + # leaves the old image serving while the new one sits Pending forever. + replicas: 1 + resources: + requests: + cpu: 200m + memory: 256Mi + command: %(server_cmd)s + kubeconfigSecretRef: + name: %(name)s-vw-server-kubeconfig +%(init_containers)s + extraArgs: +%(vw_args)s +%(dex_volumes)s + deploymentTemplate: + spec: + template: + spec: + # The kubeconfigs address the front-proxy by its external + # hostname, so it has to resolve in here too. + hostAliases: + - ip: 10.96.2.2 + hostnames: ["kcp.localhost", "root.kcp.localhost", "theseus.kcp.localhost", "dex.kcp.localhost"] +""" % { + 'name': name, + 'image': image_target, + 'server_cmd': yaml_list(server_cmd), + 'bootstrap_kubeconfig': bootstrap_kubeconfig, + 'init_containers': init_containers, + 'vw_args': vw_args, + 'dex_volumes': DEX_VW_VOLUMES, + })) + + # The VirtualWorkspace is not a workload Tilt recognises — the + # Deployment and Service behind it are the operator's doing — so it + # gets no resource of its own unless one is assembled from the object. + # + # Deliberately NOT waiting on the two Kubeconfig resources: they have + # no pods, so their runtime status never leaves "pending" and a + # dependent would wait forever. The pod just stays in + # ContainerCreating until the operator has minted their secrets. + k8s_resource( + new_name='%s-vw' % name, + objects=['%s:VirtualWorkspace' % name], + resource_deps=['%s-image' % name, 'contrib-kubeconfig'], + labels=[name], + ) + kubeconfigs = ['%s-vw-server' % name] + if init_cmd: + kubeconfigs.append('%s-vw-bootstrap' % name) + for kubeconfig in kubeconfigs: + k8s_resource(kubeconfig, labels=[name]) + + VW_PATH_MAPPINGS.append({ + 'path': '/services/' + service, + 'backend': 'https://%s-virtual-workspace.default.svc.cluster.local:6443' % name, + # The serving certificate chains up to the root CA the front-proxy + # already mounts, and the requestheader client certificate is how + # the virtual workspace knows to trust the forwarded identity. + # This is the path the operator's own default mappings use; the + # /etc/kcp-front-proxy/tls/ca/tls.crt in its docs does not exist + # in the deployment, and the front-proxy exits on a CA it cannot + # read rather than serving without it. + 'backend_server_ca': '/etc/kcp/tls/ca/tls.crt', + 'proxy_client_cert': '/etc/kcp-front-proxy/requestheader-client/tls.crt', + 'proxy_client_key': '/etc/kcp-front-proxy/requestheader-client/tls.key', + }) + + +def component(name, binary, operator_args): + """The component's operator, which runs as a local process: it serves + no path, so nothing about it needs the front-proxy's routing — only + its client credential, which is the same one everything else uses. + """ + bin_path = 'bin/' + binary + + local_resource('%s-build' % name, + cmd='make --no-print-directory build-%s' % name, + deps=[p for p in [name + '/main.go', name + '/cmd', name + '/pkg', + name + '/internal', name + '/config', name + '/sdk'] + if os.path.exists(p)], + ignore=['**/*_test.go'], + labels=[name], + allow_parallel=True, + ) + + local_resource('%s-operator' % name, + serve_cmd='%s operator --kubeconfig %s %s --v=4' % (bin_path, KUBECONFIG, operator_args), + deps=[bin_path], + # The exports it reconciles are installed by the virtual + # workspace's init container. ingress-forward is only ready once + # kcp answers on the host, and the operator exits if it cannot + # reach kcp at startup. + resource_deps=['%s-build' % name, '%s-vw' % name, 'contrib-kubeconfig', 'ingress-forward'], + labels=[name], + ) + +# access — SelfClusterAccessReview: "which workspaces can this identity +# reach?" in one call. It ships separate binaries rather than one with +# subcommands, so the commands are spelled out. +if enabled('ACCESS'): + virtual_workspace('access', 'access-vw', 'access', + # The server kubeconfig already targets root:access:controllers, so + # the slice is looked up there without a --workspace-path. + init_args='', + # Deliberately NOT --apiexport-endpointslice: that restricts access + # to workspaces which bind its own export, which would make enabling + # MCP two bindings rather than one. Here it indexes everything its + # kubeconfig can see, and a caller's RBAC is what narrows the answer. + vw_args=' - --endpoint-base=%s/clusters/\n' % FRONT_PROXY_URL + + ''.join([' - %s\n' % a for a in OIDC_VW_ARGS_LIST]), + server_cmd=['/access-vw'], + init_cmd=['/access-vw-init'], + ) + print('access VW → %s/services/access' % FRONT_PROXY_URL) + +# mcp — the Model Context Protocol over whatever the caller can reach, +# which it learns from the access VW above. +# +# It is also a marketplace offering, which is the interesting part. MCP is +# not an API, so there is nothing for a consumer to bind in order to "get" +# it; what they actually have to do is let the server act as them in their +# workspace. Its APIExport claims exactly the RBAC for that, so binding IS +# the consent, and the operator below spends those claims on the one grant. +if enabled('MCP'): + virtual_workspace('mcp', 'mcp-vw', 'mcp', + init_args='', + # It reaches the access VW through the front-proxy like any other + # client, trusting the root CA the operator mounts into every + # virtual workspace pod. + vw_args=' - --access-url=%s/services/access\n' % FRONT_PROXY_URL + + ' - --access-ca-file=/etc/kcp/tls/ca/root/tls.crt\n' + + ''.join([' - %s\n' % a for a in OIDC_VW_ARGS_LIST]), + server_cmd=['/mcp-virtual-workspace', 'serve'], + init_cmd=['/mcp-virtual-workspace', 'init'], + ) + component('mcp', 'mcp-virtual-workspace', + operator_args='--workspace-path root:mcp:controllers ' + + '--apiexport-endpointslice=mcp ' + + '--server-url=%s/services/mcp ' % FRONT_PROXY_URL + + # The identity the operator mints for this VW's server + # kubeconfig, and so the subject the grant names. + '--impersonate-user=mcp-vw', + ) + + # Register the mcp workspace as a marketplace provider, so its export + # shows up in the catalog as something to enable. Ad-hoc: it only makes + # sense once both components are up, and publishing grants `bind` to + # every authenticated user in this stack. + local_resource('mcp-offering', + cmd='hack/tilt/mcp-offering.sh', + env={'KUBECONFIG': KUBECONFIG, 'KCP_FRONT_PROXY_URL': FRONT_PROXY_URL}, + deps=['hack/tilt/mcp-offering.sh'], + resource_deps=['mcp-operator', 'marketplace-operator'], + trigger_mode=TRIGGER_MODE_MANUAL, + auto_init=False, + labels=['mcp'], + ) + print('mcp VW → %s/services/mcp' % FRONT_PROXY_URL) + print(' publish it to the catalog: tilt trigger mcp-offering') + +# The dex user who runs the platform: init binds it to the platform-admin +# role in the tenancy store and the marketplace catalog, and nothing else. +PLATFORM_ADMIN = 'admin@platform.example.com' +PLATFORM_ADMIN_INIT_ARGS = ' - --platform-admin-user=%s\n' % PLATFORM_ADMIN + +if enabled('TENANCY'): + virtual_workspace('tenancy', 'tenancy-vw', 'tenancy', + init_args=PLATFORM_ADMIN_INIT_ARGS, + # No --workspace-path: the server kubeconfig is already scoped to + # root:tenancy:controllers by targetWorkspace, and retargeting it + # would append a second /clusters/ segment. + # Self-service tenants are off by default in the component; a dev + # stack wants them on, so a fresh identity can get started without + # an administrator. + vw_args=' - --endpoint-base=%s/clusters/\n' % FRONT_PROXY_URL + + ' - --self-service-tenants\n' + + ''.join([' - %s\n' % a for a in OIDC_VW_ARGS_LIST]), + ) + component('tenancy', 'tenancy-vw', + operator_args='--workspace-path root:tenancy:controllers ' + + '--tenants-workspace root:tenancy:tenants', + ) + # Demo data, so a fresh environment answers whoami with something: + # the component's own `admin seed` command converges on tenant acme + # + project web, alice admin / bob view — each granted under both + # identities (dex email and dev-cert CN). Idempotent; re-run anytime + # with `tilt trigger tenancy-seed`. SEED_ENABLED=false skips it. + if os.getenv('SEED_ENABLED', 'true').lower() not in ('false', '0', 'no', 'off'): + local_resource('tenancy-seed', + cmd='make --no-print-directory build-cli && ' + + 'bin/contribctl admin seed --kubeconfig ' + KUBECONFIG + + ' --tenant acme --display-name "Acme Corp" --project web' + + ' --admin alice@team-a.example.com --admin alice' + + ' --view bob@team-b.example.com --view bob', + resource_deps=['tenancy-operator'], + labels=['tenancy'], + ) + print('tenancy VW → %s/services/tenancy' % FRONT_PROXY_URL) + +if enabled('MARKETPLACE'): + virtual_workspace('marketplace', 'marketplace-vw', 'marketplace', + init_args=PLATFORM_ADMIN_INIT_ARGS, + vw_args=''.join([' - %s\n' % a for a in OIDC_VW_ARGS_LIST]), + ) + component('marketplace', 'marketplace-vw', + operator_args='--workspace-path root:marketplace:controllers ' + + '--catalog-workspace root:marketplace:catalog ' + + '--producers-workspace root:marketplace:producers', + ) + # Example offerings, on demand: `tilt trigger marketplace-examples`. + # + # Ad-hoc rather than automatic because an empty catalog is a legitimate + # state to develop against — and because publishing grants `bind` to + # every authenticated user in this stack, which should be something + # someone asked for. auto_init=False keeps it out of `tilt up`; + # TRIGGER_MODE_MANUAL keeps editing the examples from re-running it + # behind your back. + local_resource('marketplace-examples', + cmd='KUBECONFIG=%s KCP_FRONT_PROXY_URL=%s marketplace/config/examples/apply.sh' + % (KUBECONFIG, FRONT_PROXY_URL), + deps=['marketplace/config/examples'], + resource_deps=['marketplace-operator'], + trigger_mode=TRIGGER_MODE_MANUAL, + auto_init=False, + labels=['marketplace'], + ) + print('marketplace VW → %s/services/marketplace' % FRONT_PROXY_URL) + print(' example offerings: tilt trigger marketplace-examples') + +# One patch carries every mapping: the front-proxy matches the longest +# prefix, so these win over the default /services/ route to the shards. +if VW_PATH_MAPPINGS: + local_resource('frontproxy-path-mappings', + cmd="kubectl patch frontproxy frontproxy --type=merge -p '%s'" % encode_json( + {'spec': {'additionalPathMappings': VW_PATH_MAPPINGS}}), + resource_deps=['frontproxy'], + labels=['contrib'], + ) + print('front-proxy routes: %s' % ', '.join([m['path'] for m in VW_PATH_MAPPINGS])) diff --git a/access/cmd/scar-to-kubeconfig/main.go b/access/cmd/scar-to-kubeconfig/main.go index 6ea165e..1c0a707 100644 --- a/access/cmd/scar-to-kubeconfig/main.go +++ b/access/cmd/scar-to-kubeconfig/main.go @@ -14,139 +14,20 @@ See the License for the specific language governing permissions and limitations under the License. */ -// 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. The +// same command is mounted in the repo-wide CLI (cmd/cli) as +// `contribctl scar-to-kubeconfig`. package main import ( - "context" - "crypto/tls" - "encoding/json" - "flag" - "fmt" - "io" - "log" - "net/http" "os" - "strings" - "time" - "k8s.io/client-go/tools/clientcmd" - clientcmdapi "k8s.io/client-go/tools/clientcmd/api" + "github.com/kcp-dev/contrib-virtual-workspaces/access/pkg/cli" ) -type scarResponse struct { - Status struct { - Clusters []struct { - ClusterName string `json:"clusterName"` - Endpoint string `json:"endpoint"` - } `json:"clusters"` - } `json:"status"` -} - func main() { - scarURL := flag.String("scar-url", "https://localhost:9443/services/access/apis/access.contrib.kcp.io/v1alpha1/selfclusteraccessreviews", "SCAR endpoint URL") - token := flag.String("token", "", "Bearer token (required)") - output := flag.String("output", "scar.kubeconfig", "Output kubeconfig path") - insecure := flag.Bool("insecure", false, "Skip TLS verification for cluster endpoints") - flag.Parse() - - if *token == "" { - log.Fatal("error: -token is required") - } - - clusters, err := callSCAR(context.Background(), *scarURL, *token, *insecure) - if err != nil { - log.Fatalf("SCAR call failed: %v", err) - } - if len(clusters) == 0 { - log.Fatal("SCAR returned no clusters for this identity (check RBAC bindings)") - } - - kubeconfig := buildKubeconfig(clusters, *token, *insecure) - - data, err := clientcmd.Write(*kubeconfig) - if err != nil { - log.Fatalf("serialize kubeconfig: %v", err) - } - - if err := os.WriteFile(*output, data, 0600); err != nil { - log.Fatalf("write %s: %v", *output, err) - } - - fmt.Fprintf(os.Stderr, "wrote %s with %d cluster context(s)\n", *output, len(clusters)) - fmt.Fprintf(os.Stderr, "next: kubernetes-mcp-server --kubeconfig=%s --cluster-provider=kcp\n", *output) -} - -func callSCAR(ctx context.Context, scarURL, token string, insecure bool) ([]scarCluster, error) { - client := &http.Client{Timeout: 10 * time.Second} - if insecure { - client.Transport = &http.Transport{ - TLSClientConfig: &tls.Config{InsecureSkipVerify: true}, - } - } - - req, err := http.NewRequestWithContext(ctx, http.MethodPost, scarURL, strings.NewReader("{}")) - if err != nil { - return nil, fmt.Errorf("create request: %w", err) - } - req.Header.Set("Authorization", "Bearer "+token) - req.Header.Set("Content-Type", "application/json") - - resp, err := client.Do(req) - if err != nil { - return nil, fmt.Errorf("POST %s: %w", scarURL, err) + if err := cli.NewSCARToKubeconfigCommand().Execute(); err != nil { + os.Exit(1) } - defer func() { _ = resp.Body.Close() }() - - body, err := io.ReadAll(resp.Body) - if err != nil { - return nil, fmt.Errorf("read response: %w", err) - } - - if resp.StatusCode != http.StatusOK && resp.StatusCode != http.StatusCreated { - return nil, fmt.Errorf("SCAR returned %d: %s", resp.StatusCode, string(body)) - } - - var scar scarResponse - if err := json.Unmarshal(body, &scar); err != nil { - return nil, fmt.Errorf("decode SCAR response: %w", err) - } - - out := make([]scarCluster, len(scar.Status.Clusters)) - for i, c := range scar.Status.Clusters { - out[i] = scarCluster{Name: c.ClusterName, Endpoint: c.Endpoint} - } - return out, nil -} - -type scarCluster struct { - Name string - Endpoint string -} - -func buildKubeconfig(clusters []scarCluster, token string, insecure bool) *clientcmdapi.Config { - config := clientcmdapi.NewConfig() - - for _, c := range clusters { - cluster := clientcmdapi.NewCluster() - cluster.Server = c.Endpoint - if insecure { - cluster.InsecureSkipTLSVerify = true - } - config.Clusters[c.Name] = cluster - - ctx := clientcmdapi.NewContext() - ctx.Cluster = c.Name - ctx.AuthInfo = "scar-user" - config.Contexts[c.Name] = ctx - } - - user := clientcmdapi.NewAuthInfo() - user.Token = token - config.AuthInfos["scar-user"] = user - - config.CurrentContext = clusters[0].Name - - return config } diff --git a/access/pkg/cli/scar.go b/access/pkg/cli/scar.go new file mode 100644 index 0000000..a9cad21 --- /dev/null +++ b/access/pkg/cli/scar.go @@ -0,0 +1,173 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// 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 + +import ( + "context" + "crypto/tls" + "encoding/json" + "fmt" + "io" + "net/http" + "os" + "strings" + "time" + + "github.com/spf13/cobra" + + "k8s.io/client-go/tools/clientcmd" + clientcmdapi "k8s.io/client-go/tools/clientcmd/api" +) + +// NewSCARToKubeconfigCommand builds the scar-to-kubeconfig command: it +// calls the access virtual workspace's SelfClusterAccessReview endpoint +// with a bearer token and writes a kubeconfig with one context per +// authorized cluster. +func NewSCARToKubeconfigCommand() *cobra.Command { + var ( + scarURL string + token string + output string + insecure bool + ) + + cmd := &cobra.Command{ + Use: "scar-to-kubeconfig", + Short: "Turn a SelfClusterAccessReview answer into a kubeconfig", + Args: cobra.NoArgs, + RunE: func(cmd *cobra.Command, _ []string) error { + if token == "" { + return fmt.Errorf("--token is required") + } + + clusters, err := callSCAR(cmd.Context(), scarURL, token, insecure) + if err != nil { + return fmt.Errorf("SCAR call failed: %w", err) + } + if len(clusters) == 0 { + return fmt.Errorf("SCAR returned no clusters for this identity (check RBAC bindings)") + } + + kubeconfig := buildKubeconfig(clusters, token, insecure) + data, err := clientcmd.Write(*kubeconfig) + if err != nil { + return fmt.Errorf("serialize kubeconfig: %w", err) + } + if err := os.WriteFile(output, data, 0o600); err != nil { + return fmt.Errorf("write %s: %w", output, err) + } + + fmt.Fprintf(os.Stderr, "wrote %s with %d cluster context(s)\n", output, len(clusters)) + fmt.Fprintf(os.Stderr, "next: kubernetes-mcp-server --kubeconfig=%s --cluster-provider=kcp\n", output) + return nil + }, + } + + cmd.Flags().StringVar(&scarURL, "scar-url", + "https://localhost:9443/services/access/apis/access.contrib.kcp.io/v1alpha1/selfclusteraccessreviews", + "SCAR endpoint URL") + cmd.Flags().StringVar(&token, "token", "", "Bearer token (required)") + cmd.Flags().StringVar(&output, "output", "scar.kubeconfig", "Output kubeconfig path") + cmd.Flags().BoolVar(&insecure, "insecure", false, "Skip TLS verification for cluster endpoints") + + return cmd +} + +type scarResponse struct { + Status struct { + Clusters []struct { + ClusterName string `json:"clusterName"` + Endpoint string `json:"endpoint"` + } `json:"clusters"` + } `json:"status"` +} + +type scarCluster struct { + Name string + Endpoint string +} + +func callSCAR(ctx context.Context, scarURL, token string, insecure bool) ([]scarCluster, error) { + client := &http.Client{Timeout: 10 * time.Second} + if insecure { + client.Transport = &http.Transport{ + TLSClientConfig: &tls.Config{InsecureSkipVerify: true}, //nolint:gosec // opt-in, for a local server + } + } + + req, err := http.NewRequestWithContext(ctx, http.MethodPost, scarURL, strings.NewReader("{}")) + if err != nil { + return nil, fmt.Errorf("create request: %w", err) + } + req.Header.Set("Authorization", "Bearer "+token) + req.Header.Set("Content-Type", "application/json") + + resp, err := client.Do(req) + if err != nil { + return nil, fmt.Errorf("POST %s: %w", scarURL, err) + } + defer func() { _ = resp.Body.Close() }() + + body, err := io.ReadAll(resp.Body) + if err != nil { + return nil, fmt.Errorf("read response: %w", err) + } + + if resp.StatusCode != http.StatusOK && resp.StatusCode != http.StatusCreated { + return nil, fmt.Errorf("SCAR returned %d: %s", resp.StatusCode, string(body)) + } + + var scar scarResponse + if err := json.Unmarshal(body, &scar); err != nil { + return nil, fmt.Errorf("decode SCAR response: %w", err) + } + + out := make([]scarCluster, len(scar.Status.Clusters)) + for i, c := range scar.Status.Clusters { + out[i] = scarCluster{Name: c.ClusterName, Endpoint: c.Endpoint} + } + return out, nil +} + +func buildKubeconfig(clusters []scarCluster, token string, insecure bool) *clientcmdapi.Config { + config := clientcmdapi.NewConfig() + + for _, c := range clusters { + cluster := clientcmdapi.NewCluster() + cluster.Server = c.Endpoint + if insecure { + cluster.InsecureSkipTLSVerify = true + } + config.Clusters[c.Name] = cluster + + ctx := clientcmdapi.NewContext() + ctx.Cluster = c.Name + ctx.AuthInfo = "scar-user" + config.Contexts[c.Name] = ctx + } + + user := clientcmdapi.NewAuthInfo() + user.Token = token + config.AuthInfos["scar-user"] = user + + config.CurrentContext = clusters[0].Name + + return config +} diff --git a/cmd/cli/main.go b/cmd/cli/main.go new file mode 100644 index 0000000..a64a364 --- /dev/null +++ b/cmd/cli/main.go @@ -0,0 +1,150 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// contribctl is the repo-wide CLI. +// +// It is organised around what a person does rather than around which +// component implements it: you log in, choose where you are working, look +// at what you can reach, and enable things there. Which virtual workspace +// answers any given command is an implementation detail the user should +// not have to know. +// +// The commands themselves belong to the components — every component that +// ships a client exposes it as importable cobra commands, and this binary +// only arranges them. The glue is two small hand-overs to the marketplace: +// the server tenancy's login stored, and a workspace resolver that turns +// "here" into a URL using the tenancy selection. The two components still +// never name each other. +package main + +import ( + goflag "flag" + "os" + + "github.com/spf13/cobra" + + "k8s.io/klog/v2" + + accesscli "github.com/kcp-dev/contrib-virtual-workspaces/access/pkg/cli" + marketplacecli "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/pkg/cli" + tenancycli "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/pkg/cli" + "github.com/kcp-dev/contrib-virtual-workspaces/tenancy/pkg/clicontext" +) + +func main() { + root := &cobra.Command{ + Use: "contribctl", + Short: "Work with kcp tenants, projects and the marketplace", + Long: `contribctl is the client for kcp Platform. + +Start by logging in and choosing where you are working: + + contribctl login --issuer https://dex.example.com + 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 + +Everything above needs only your own credential: the virtual workspaces +authenticate you and answer for the identity you actually hold. The +commands under "admin" are the other side — they write to kcp with a +kubeconfig and are for whoever runs the platform.`, + SilenceUsage: true, + } + + // klog's flags stay available — they are how you debug a command that + // misbehaves — but hidden, because two dozen logging knobs in front of + // someone looking for "how do I list my tenants" is not help. + klogFlags := goflag.NewFlagSet("klog", goflag.ContinueOnError) + klog.InitFlags(klogFlags) + root.PersistentFlags().AddGoFlagSet(klogFlags) + klogFlags.VisitAll(func(f *goflag.Flag) { + if f.Name != "v" { + _ = root.PersistentFlags().MarkHidden(f.Name) + } + }) + + // Cobra prints commands in these groups, in this order, so the help + // reads as the order you would do things in. + const ( + groupAuth = "auth" + groupWork = "work" + groupAdmin = "admin" + ) + root.AddGroup( + &cobra.Group{ID: groupAuth, Title: "Getting in:"}, + &cobra.Group{ID: groupWork, Title: "Working:"}, + &cobra.Group{ID: groupAdmin, Title: "Running the platform:"}, + ) + + add := func(group string, cmds ...*cobra.Command) { + for _, c := range cmds { + c.GroupID = group + root.AddCommand(c) + } + } + + add(groupAuth, + tenancycli.NewLoginCommand(), + tenancycli.NewLogoutCommand(), + tenancycli.NewWhoAmICommand(), + ) + + add(groupWork, + tenancycli.NewUseCommand(), + tenancycli.NewTenantsCommand(), + tenancycli.NewProjectsCommand(), + tenancycli.NewKubeconfigCommand(), + marketplacecli.NewOffersCommand(marketplaceDefaults()), + marketplacecli.NewEnableCommand(marketplaceDefaults(), currentWorkspace), + ) + + add(groupAdmin, + tenancycli.NewMembershipCommand(), + tenancycli.NewAdminCommand(), + accesscli.NewSCARToKubeconfigCommand(), + ) + + if err := root.Execute(); err != nil { + os.Exit(1) + } +} + +// marketplaceDefaults is the other piece of glue: the server `login --url` +// stored, how to verify it, and the token `login` cached, handed to the +// marketplace commands as their flag defaults. The marketplace never reads +// the context file or the token cache; it only knows what it was told. +func marketplaceDefaults() marketplacecli.ServerDefaults { + stored := clicontext.Load() + return marketplacecli.ServerDefaults{ + URL: stored.ServiceURL("marketplace"), + CertificateAuthority: stored.CertificateAuthority, + Insecure: stored.Insecure, + Token: tenancycli.CachedToken(), + } +} + +// currentWorkspace is the glue between the two components: the +// marketplace asks "where am I?", and the answer is whatever `use` +// selected. The marketplace never learns that the answer came from a +// tenancy project. +func currentWorkspace() (string, string, error) { + selection := tenancycli.CurrentSelection() + if selection.Empty() { + return "", "", nil + } + return selection.URL, selection.String(), nil +} diff --git a/go.mod b/go.mod index 5115d1e..6a7bcc0 100644 --- a/go.mod +++ b/go.mod @@ -23,17 +23,21 @@ require ( ) require ( + github.com/bombsimon/logrusr/v3 v3.1.0 // indirect github.com/google/jsonschema-go v0.4.3 // indirect github.com/gorilla/websocket v1.5.4-0.20250319132907-e064f32e3674 // indirect github.com/moby/spdystream v0.5.1 // indirect github.com/mxk/go-flowrate v0.0.0-20140419014527-cca7078d478f // indirect github.com/segmentio/asm v1.1.3 // indirect github.com/segmentio/encoding v0.5.4 // indirect + github.com/sirupsen/logrus v1.9.3 // indirect github.com/yosida95/uritemplate/v3 v3.0.2 // indirect + golang.org/x/mod v0.35.0 // indirect gopkg.in/yaml.v3 v3.0.1 // indirect k8s.io/cloud-provider v0.0.0 // indirect k8s.io/endpointslice v0.0.0 // indirect k8s.io/externaljwt v0.0.0 // indirect + k8s.io/gengo/v2 v2.0.0-20250922181213-ec3ebc5fd46b // indirect k8s.io/kube-aggregator v0.0.0 // indirect k8s.io/kube-controller-manager v0.0.0 // indirect k8s.io/kube-proxy v0.0.0 // indirect diff --git a/go.sum b/go.sum index 2f4d016..5d4d8a6 100644 --- a/go.sum +++ b/go.sum @@ -16,6 +16,8 @@ github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM= github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw= github.com/blang/semver/v4 v4.0.0 h1:1PFHFE6yCCTv8C1TeyNNarDzntLi7wMI5i/pzqYIsAM= github.com/blang/semver/v4 v4.0.0/go.mod h1:IbckMUScFkM3pff0VJDNKRiT6TG/YpiHIM2yvyW5YoQ= +github.com/bombsimon/logrusr/v3 v3.1.0 h1:zORbLM943D+hDMGgyjMhSAz/iDz86ZV72qaak/CA0zQ= +github.com/bombsimon/logrusr/v3 v3.1.0/go.mod h1:PksPPgSFEL2I52pla2glgCyyd2OqOHAnFF5E+g8Ixco= github.com/cenkalti/backoff/v5 v5.0.3 h1:ZN+IMa753KfX5hd8vVaMixjnqRZ3y8CuJKRKj1xcsSM= github.com/cenkalti/backoff/v5 v5.0.3/go.mod h1:rkhZdG3JZukswDf7f0cwqPNk4K0sa+F97BxZthm/crw= github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs= @@ -269,6 +271,7 @@ github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY= github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA= github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI= github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg= +github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg= github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U= github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U= github.com/tmc/grpc-websocket-proxy v0.0.0-20220101234140-673ab2c3ae75 h1:6fotK7otjonDflCTK0BCfls4SPy3NcCVb5dqqmbRknE= @@ -354,6 +357,7 @@ golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0= golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY= golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= golang.org/x/sys v0.0.0-20200930185726-fdedc70b468f/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= +golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= golang.org/x/sys v0.43.0 h1:Rlag2XtaFTxp19wS8MXlJwTvoh8ArU6ezoyFsMyCTNI= golang.org/x/sys v0.43.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw= golang.org/x/term v0.42.0 h1:UiKe+zDFmJobeJ5ggPwOshJIVt6/Ft0rcfrXZDLWAWY= @@ -370,6 +374,10 @@ golang.org/x/tools v0.0.0-20200619180055-7c47624df98f/go.mod h1:EkVYQZoAsY45+roY golang.org/x/tools v0.0.0-20210106214847-113979e3529a/go.mod h1:emZCQorbCU4vsT4fOWvOPXz4eW1wZW4PmDk9uLelYpA= golang.org/x/tools v0.44.0 h1:UP4ajHPIcuMjT1GqzDWRlalUEoY+uzoZKnhOjbIPD2c= golang.org/x/tools v0.44.0/go.mod h1:KA0AfVErSdxRZIsOVipbv3rQhVXTnlU6UhKxHd1seDI= +golang.org/x/tools/go/expect v0.1.1-deprecated h1:jpBZDwmgPhXsKZC6WhL20P4b/wmnpsEAGHaNy0n/rJM= +golang.org/x/tools/go/expect v0.1.1-deprecated/go.mod h1:eihoPOH+FgIqa3FpoTwguz/bVUSGBlGQU67vpBeOrBY= +golang.org/x/tools/go/packages/packagestest v0.1.1-deprecated h1:1h2MnaIAIXISqTFKdENegdpAgUXz6NrPEsbIeWaBRvM= +golang.org/x/tools/go/packages/packagestest v0.1.1-deprecated/go.mod h1:RVAQXBGNv1ib0J382/DPCRS/BPnsGebyM1Gj5VSDpG8= golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= @@ -400,6 +408,8 @@ gopkg.in/natefinch/lumberjack.v2 v2.2.1/go.mod h1:YD8tP3GAjkrDg1eZH7EGmyESg/lsYs gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= +k8s.io/gengo/v2 v2.0.0-20250922181213-ec3ebc5fd46b h1:gMplByicHV/TJBizHd9aVEsTYoJBnnUAT5MHlTkbjhQ= +k8s.io/gengo/v2 v2.0.0-20250922181213-ec3ebc5fd46b/go.mod h1:CgujABENc3KuTrcsdpGmrrASjtQsWCT7R99mEV4U/fM= k8s.io/klog/v2 v2.140.0 h1:Tf+J3AH7xnUzZyVVXhTgGhEKnFqye14aadWv7bzXdzc= k8s.io/klog/v2 v2.140.0/go.mod h1:o+/RWfJ6PwpnFn7OyAG3QnO47BFsymfEfrz6XyYSSp0= k8s.io/kube-openapi v0.0.0-20260721132016-d427ff9ee9ad h1:oXImqH8mQNk7PmvzKhmN3ddJoY6OnyM225MXwGHPm0A= diff --git a/hack/tilt/README.md b/hack/tilt/README.md new file mode 100644 index 0000000..59ee54a --- /dev/null +++ b/hack/tilt/README.md @@ -0,0 +1,595 @@ +# The all-in-one development stack + +One command brings up kcp, an OIDC issuer, and every component in this +repo, wired together: `make tilt-up`. + +What you get, and what this document walks through: + +| | | +|---|---| +| **kcp** | operator-deployed, two shards (`root`, `theseus`) behind a front-proxy at `https://kcp.localhost:8443` | +| **Dex** | in-cluster OIDC issuer at `https://dex.kcp.localhost:8443/dex`, trusted by kcp *and* both virtual workspaces | +| **tenancy** | virtual workspace at `/services/tenancy`, a local operator, seeded with a demo tenant and project | +| **marketplace** | virtual workspace at `/services/marketplace`, a local operator | +| **observability** | Grafana, Prometheus, Loki | + +The point of the setup is what the later sections show: an ordinary user, +holding nothing but a password, ends up with a working kubeconfig for +exactly the workspaces they were granted — and can enable a marketplace +offering in one of them, with no admin credential anywhere in their path. + +Every command below was executed against this stack. + +--- + +## 1. Bring the stack up + +You need a kcp checkout next to this one (`../kcp`, or set `KCP_DIR`) and +Docker. Add the hostnames the stack serves on to `/etc/hosts`: + +``` +127.0.0.1 kcp.localhost root.kcp.localhost theseus.kcp.localhost dex.kcp.localhost +``` + +Then: + +```sh +make tilt-up # creates the kind cluster and runs tilt up +``` + +Tilt's UI is at http://localhost:10350. Resources come up in dependency +order: kcp (operator, shards, front-proxy) → `kcp-admin extract` → `dex` → +per component `build` → `init` → `operator` + `vw` → `tenancy-seed`. + +Everything is reached through one port on the host, `8443`, which the +`ingress-forward` resource keeps pointed at the gateway. It is a +`serve_cmd` so Tilt restarts it, and it re-resolves the gateway Service on +each attempt — the Service name carries a hash that changes when the +Gateway is recreated. Worth knowing because losing that forward makes +every kubeconfig, the UI and the CLI fail at once, which looks like the +components being broken rather than the address being gone. + +### How kcp learns about dex + +kcp's own `contrib/tilt` entry points know nothing about an OIDC issuer, and +a Tilt `include()` cannot be parameterized. So instead of including +`Tiltfile.static`, the Tiltfile here repeats its dozen lines (cert-manager, +the envoy gateway, etcd, the operator — all addressed through `KCP_DIR`) +and calls kcp's `deploy_kcp()` itself (loaded through a `.tilt/kcp` symlink +to `KCP_DIR`, because Starlark's `load()` only takes a literal path), passing +the `oidc` block (`issuerURL`, +`clientID: kcp`, `usernameClaim: email`, `caFileRef: dex-tls/ca.crt`) and +`dex.kcp.localhost` among the pods' hostAliases. That is what puts an OIDC +authenticator on the shards and the front-proxy; without it every dex token +is `invalid bearer token` at `:8443`. If kcp's entry point grows an `oidc` +parameter, this collapses back to an include. + +### The dex certificate, and why it matters + +dex serves a self-signed certificate, and *changing* it is expensive in two +directions that are easy to mistake for component failures: + +- a browser will not talk to a self-signed issuer until someone has visited + it once and accepted the warning, and that acceptance is **per + certificate** — so a new one makes signing in from a browser fail until + the issuer has been visited and accepted again; +- dex reads its certificate once, at **boot**, so a new one in the secret + leaves dex serving the old one while every OIDC validator has mounted the + new CA. They then cannot fetch dex's discovery document at all, their + authenticator never initialises, and **every** token gets a 401 — + including a freshly minted one, which is the tell. + +Both are handled now. `dex-pki.sh` treats the cluster's `dex-tls` secret as +the source of truth and `.tilt/dex` as a cache of it, so wiping `.tilt` no +longer changes the certificate — only losing the cluster does. And the +certificate's fingerprint is an annotation on the dex pod template, so a +certificate that really is new rolls dex with it. + +Knobs, all optional: + +| Variable | Effect | +|---|---| +| `KCP_DIR` | where the kcp checkout lives (default `../kcp`) | +| `KCP_STATIC=false` | build kcp from that checkout instead of running published images. kcp's source-build CRs carry no OIDC issuer, so this needs `DEX_ENABLED=false` too — the Tiltfile refuses the combination rather than bring up a console nobody can sign in to | +| `TENANCY_ENABLED=false`, `MARKETPLACE_ENABLED=false`, `ACCESS_ENABLED=false`, `MCP_ENABLED=false` | skip a component | +| `DEX_ENABLED=false` | skip the identity provider | +| `PKI_VALID_DAYS` | development certificate lifetime (default 365) | +| `SEED_ENABLED=false` | skip the demo tenancy data | +| `MCP_WORKSPACE` | where mcp's export lives (default `root:mcp:controllers`) | + + +### The modules + +Four virtual workspaces come up the same way — an image, a `VirtualWorkspace` +object the operator turns into a Deployment and Service, and a front-proxy +path mapping — and differ only in what they need to start: + +| Module | Path | Bootstraps | Notes | +|---|---|---|---| +| `tenancy` | `/services/tenancy` | four APIExports, three tiers | plus a local operator | +| `marketplace` | `/services/marketplace` | three APIExports | plus a local operator | +| `access` | `/services/access` | one APIExport + endpoint slice | separate `access-vw` / `access-vw-init` binaries | +| `mcp` | `/services/mcp` | one APIExport | reads the access VW; **is a marketplace offering** | + +**mcp is the interesting one, because enabling it is a marketplace +offering.** It is also the case that shows what an offering can be when it +is not an API. + +Behind the front-proxy a caller's bearer token is consumed by the proxy and +replaced with identity headers, so there is no token left for mcp to +replay: it acts by *impersonating* the caller, and kcp authorizes every +request as them. That needs `impersonate` — and deliberately nothing else, +since everything mcp can do it does as somebody else. kcp's RBAC is per +logical cluster and does not inherit down the tree, so that grant has to +exist in each workspace that wants MCP. + +Which is exactly an enablement. So mcp's APIExport serves one small report +kind and *claims* `clusterroles` and `clusterrolebindings`: binding it is +the consent, `mcp operator` spends those claims on the single impersonation +grant, and deleting the binding revokes the claims and with them the +operator's reach into that workspace. Consent and capability are the same +fact. + +Publish it to the catalog once both components are up: + +```sh +tilt trigger mcp-offering # registers root:mcp:controllers as a producer +``` + +Then it is an ordinary offering — enable it in a project from the UI's +Service Catalog, or: + +```sh +bin/contribctl offers +bin/contribctl enable mcp.mcp + +# where to point a client, reported back in your own workspace +kubectl --server https://kcp.localhost:8443/clusters/ get mcpendpoints +# NAME URL PHASE AGE +# mcp https://kcp.localhost:8443/services/mcp Ready 30s +``` + +The consent form is worth reading before you click Enable: the catalog +entry says this offering wants `clusterroles` and `clusterrolebindings` in +your project, which is the truth about what enabling MCP means. + +Note that `access` runs **without** `--apiexport-endpointslice` here. That +flag restricts it to workspaces which bind its own export, which would make +enabling MCP two bindings instead of one; unrestricted, it indexes whatever +its kubeconfig sees and a caller's own RBAC is what narrows the answer. + +### Check it + +Everything answers on the front-proxy, at `https://kcp.localhost:8443` — +kcp's own API under `/clusters/`, each virtual workspace under the path it +owns. There is no second address to know: + +```sh +KC=.tilt/tilt-frontproxy.kubeconfig + +kubectl --kubeconfig $KC get --raw \ + /services/tenancy/apis/tenancy.platform.kcp.io/v1alpha1 +# {"kind":"APIResourceList",...,"resources":[{"name":"selftenancyreviews",...}]} + +kubectl --kubeconfig $KC get --raw \ + /services/marketplace/apis/marketplace.platform.kcp.io/v1alpha1/offerings +# {"kind":"CatalogOfferingList",...,"items":[]} +``` + +The virtual workspaces run **in the cluster**, deployed by the kcp-operator +from a `VirtualWorkspace` object: it gives each one a Deployment and a +Service on `:6443`, issues its serving certificate from the shard CA, and +runs the component's own `init` as an init container so the APIExports +exist before the server that serves them starts. The front-proxy reaches +them through `additionalPathMappings` and forwards the caller's identity +in `X-Remote-*` headers over its own client certificate — which is why a +token works the same at kcp and at a virtual workspace. + +The operators stay local processes (`tilt trigger -operator` to +restart): they serve no path, so nothing about them needs the routing, +and that is where the reconcile loop you iterate on lives. + +The tenancy numbers come from the seed (`contribctl tenancy seed`, run by +the `tenancy-seed` resource): tenant `acme` with project `web`, alice +admin, bob view. Re-run it any time with `tilt trigger tenancy-seed` — it +is idempotent. + +The marketplace starts empty — [step 5](#5-the-marketplace-publish-an-api-enable-it-as-a-user) +fills it. + +--- + +## 2. Log in with Dex + +Dex is the one identity provider kcp and both virtual workspaces trust, so +a token names the same user everywhere. Four users, all with the password +`password`: + +| Login | Identity everywhere | +|---|---| +| `alice@team-a.example.com` | `alice@team-a.example.com` | +| `bob@team-b.example.com` | `bob@team-b.example.com` | +| `mallory@strangers.example.com` | `mallory@strangers.example.com` | +| `admin@platform.example.com` | `admin@platform.example.com` | + +`admin` is the platform administrator: the tenancy and marketplace init +steps run with `--platform-admin-user=admin@platform.example.com`, which +binds it to a role that may manage Tenants in `root:tenancy:store` and +Producers in `root:marketplace:catalog`, and nothing else. + +The identity is the **plain email, with no groups**: the kcp-operator only +speaks the legacy `--oidc-*` claim mapping, so the CEL claim mapping used +by [hack/dex](../dex/) (which would produce `alice` in group `team-a`) is +not available here. Grants under Tilt therefore name the full email — and +the login form wants that email too, not the `username` in Dex's config, +which is only a display name. + +Dex keeps its signing keys in the cluster (`storage: type: kubernetes`), +not in memory, so restarting it is a non-event. With memory storage it +mints new keys on every start, which invalidates every issued token *and* +leaves the front-proxy, both shards and both virtual workspaces holding a +JWKS that verifies nothing — every login then fails with `401` until each +of them is restarted too. + +```sh +echo password | bin/contribctl tenancy login \ + --issuer https://dex.kcp.localhost:8443/dex \ + --certificate-authority .tilt/dex/ca.crt \ + --username alice@team-a.example.com --password-stdin +``` +``` +logged in to https://dex.kcp.localhost:8443/dex as alice@team-a.example.com +token cached in ~/.config/tenancyctl/tokens.json +expires Sat, 26 Sep 2026 13:01:17 EEST +``` + +Dropping `--username --password-stdin` opens a browser instead +(authorization code + PKCE on `localhost:8000`); the password grant is +here because scripts have no browser. + +The ID token is the credential, and it is cached — nothing below passes a +credential flag again. + +--- + +## 3. Find your tenants and projects + +A new user knows nothing: not which workspaces exist, not their paths, not +even whether they have any. `whoami` asks the tenancy virtual workspace, +which authenticates the token itself and answers with the Memberships that +name the caller: + +```sh +bin/contribctl tenancy whoami \ + --url https://kcp.localhost:8443/services/tenancy --insecure-skip-tls-verify +``` +``` +TENANT PROJECT DISPLAY NAME ROLES ENDPOINT +acme - Acme Corp admin https://kcp.localhost:8443/clusters/2p56nya1pwo7fk5z +acme web web admin https://kcp.localhost:8443/clusters/fasvvoj7giral9qt +``` + +No kubeconfig for kcp was involved, and no admin credential: the only +input was the cached token. Alice is admin of the tenant, and a +tenant-wide grant reaches every project, hence `admin` on `web` too. + +**How does it know which user this is?** No flag says so, and the request +body carries no username. Two halves: + +- the CLI passes no credential, so it falls back to what `login` cached — + the entry for `--issuer`, or the single unexpired token when only one + issuer is cached (with two it refuses and asks which, rather than + guessing); +- the virtual workspace validates that JWT itself. It runs with the same + issuer, client id and `--oidc-username-claim email` as kcp, so the + username it derives is `alice@team-a.example.com`, and the review + answers from the *authenticated* identity on the request — never from + anything the caller asserts. + +Which is why the mapping in [step 2](#2-log-in-with-dex) matters: the +username the virtual workspace derives has to be the exact string a +Membership names, so under Tilt grants use the full email. + +The same command as bob (`--token-cache /tmp/bob-tokens.json` after +logging in as him) shows the narrower grant: + +``` +TENANT PROJECT DISPLAY NAME ROLES ENDPOINT +acme - Acme Corp - https://kcp.localhost:8443/clusters/2p56nya1pwo7fk5z +acme web web view https://kcp.localhost:8443/clusters/fasvvoj7giral9qt +``` + +Bob has no role at the tenant level and `view` on the project — the +listing shows a tenant he can see through, not one he can use. + +`--insecure-skip-tls-verify` is here only because the virtual workspace +serves a development certificate; pass +`--certificate-authority .tilt/pki/ca.crt` instead to verify it properly. + +--- + +## 4. Use the kubeconfig + +`kubeconfig` turns that same answer into contexts — one per **project** +the caller can reach: + +```sh +bin/contribctl tenancy kubeconfig \ + --url https://kcp.localhost:8443/services/tenancy --insecure-skip-tls-verify \ + -o /tmp/alice.kubeconfig +# wrote /tmp/alice.kubeconfig with 1 project context (current: acme-web) + +kubectl --kubeconfig /tmp/alice.kubeconfig config get-contexts +``` +``` +CURRENT NAME CLUSTER AUTHINFO NAMESPACE +* acme-web acme-web tenancy +``` + +Projects only, and no context for the tenant — a tenant workspace is the +record store the tenancy system keeps Tenants, Projects and Memberships +in. A Membership materializes RBAC in that tenant's *projects* and never +in the tenant itself, so no member can enter it however senior: alice's +tenant-wide `admin` means admin in every project. A context for it could +only ever answer `Forbidden`, so it is not written. + +These contexts point at **kcp itself**, not at the virtual workspace, and +they carry alice's own token. kcp authenticates her against Dex and +authorizes her against the RBAC the tenancy operator materialized from her +Membership: + +```sh +kubectl --kubeconfig /tmp/alice.kubeconfig --context acme-web auth whoami +``` +``` +ATTRIBUTE VALUE +Username alice@team-a.example.com +Groups [system:authenticated] +``` + +Note the groups: nothing privileged. Everything she can do comes from her +Membership, and she can work in her project: + +```sh +kubectl --kubeconfig /tmp/alice.kubeconfig --context acme-web get namespaces +# NAME STATUS AGE +# default Active 2m31s + +kubectl --kubeconfig /tmp/alice.kubeconfig --context acme-web \ + create configmap hello --from-literal=who=alice +# configmap/hello created +``` + +Bob's kubeconfig, built exactly the same way, is `view` on that project — +he reads alice's object and is refused a write, by kcp, on his own +identity: + +```sh +kubectl --kubeconfig /tmp/bob.kubeconfig --context acme-web get configmap hello +# NAME DATA AGE +# hello 1 6s + +kubectl --kubeconfig /tmp/bob.kubeconfig --context acme-web \ + create configmap nope --from-literal=x=y +# error: failed to create configmap: configmaps is forbidden: +# User "bob@team-b.example.com" cannot create resource "configmaps" +# in API group "" in the namespace "default": access denied +``` + +That is the whole model working end to end: a password became a token, +the token became a list of workspaces, the list became a kubeconfig, and +kcp enforced the role — with no privileged credential anywhere along the +way. + +--- + +## 5. The marketplace: publish an API, enable it as a user + +The marketplace is the other half of the stack, and it composes with +tenancy without either component naming the other: a producer publishes an +API, and a consumer — *any* workspace, including the project alice just +got a kubeconfig for — enables it by creating an ordinary kcp APIBinding. + +### Register a producer + +A `Producer` record in the catalog makes the operator provision a +workspace with the `producer` WorkspaceType, which carries the +`marketplace-publish` binding: + +```sh +KC=.tilt/tilt-frontproxy.kubeconfig +CATALOG=https://kcp.localhost:8443/clusters/root:marketplace:catalog + +kubectl --kubeconfig $KC --server $CATALOG apply -f - <<'EOF' +apiVersion: marketplace.platform.kcp.io/v1alpha1 +kind: Producer +metadata: + name: acme +spec: + displayName: Acme Producer + mode: provisioned +EOF + +kubectl --kubeconfig $KC --server $CATALOG \ + get producers acme -o jsonpath='{.status.phase} {.status.workspacePath}' +# Ready root:marketplace:producers:acme +``` + +### Publish an offering + +Everything in this section is also available as a one-liner — +`tilt trigger marketplace-examples` applies +[the examples](../../marketplace/config/examples/), which publish the same +`things` export plus a second one that claims nothing. It is an ad-hoc job: +it never runs on its own, because publishing grants `bind` to every +authenticated user in this stack. Doing it by hand, once, is worth it the +first time: + +Now act as the producer, inside that workspace. The producer brings their +own APIExport — the marketplace never defines what a producer serves, only +how it is offered: + +```sh +PROVIDER=https://kcp.localhost:8443/clusters/root:marketplace:producers:acme + +kubectl --kubeconfig $KC --server $PROVIDER apply -f - <<'EOF' +apiVersion: apis.kcp.io/v1alpha1 +kind: APIResourceSchema +metadata: + name: v1alpha1.things.acme.example +spec: + group: acme.example + names: {kind: Thing, listKind: ThingList, plural: things, singular: thing} + scope: Cluster + versions: + - name: v1alpha1 + served: true + storage: true + schema: + type: object + properties: + apiVersion: {type: string} + kind: {type: string} + metadata: {type: object} + spec: + type: object + properties: + message: {type: string} +--- +apiVersion: apis.kcp.io/v1alpha2 +kind: APIExport +metadata: + name: things.acme.example + # The offering is the export: these annotations publish it, and its own + # permissionClaims (none here) are the consent form. + annotations: + marketplace.kcp.hub/publish: "true" + marketplace.kcp.hub/display-name: "Things as a service" + marketplace.kcp.hub/description: "One Thing per workspace, batteries included." +spec: + resources: + - name: things + group: acme.example + schema: v1alpha1.things.acme.example + storage: + crd: {} +EOF +``` + +Publishing is what grants `bind`, and nothing else does. Once the operator +sees the annotation it materializes exactly one grant next to the export: + +```sh +kubectl --kubeconfig $KC --server $PROVIDER get clusterroles,clusterrolebindings \ + | grep marketplace:bind +``` +``` +clusterrole.rbac.../marketplace:bind:things.acme.example +clusterrolebinding.rbac.../marketplace:bind:things.acme.example:consumers +``` + +### Browse the catalog + +The marketplace virtual workspace serves the catalog read-only to any +authenticated caller. Each entry carries the coordinates of the binding +you would write, so browsing it is reading both the consent form and the +APIBinding: + +```sh +kubectl --kubeconfig .tilt/tilt-frontproxy.kubeconfig get --raw \ + /services/marketplace/apis/marketplace.platform.kcp.io/v1alpha1/offerings +``` +```json +{ + "kind": "CatalogOfferingList", + "items": [ + { + "metadata": {"name": "acme.things"}, + "producer": "acme", + "offering": "things", + "displayName": "Things as a service", + "export": "things.acme.example", + "workspacePath": "root:marketplace:producers:acme", + "revision": "", + "ready": true + } + ] +} +``` + +### Enable it as an ordinary user + +Here the two components meet. Alice uses **the kubeconfig from +[step 4](#4-use-the-kubeconfig)** — her own Dex token, her own project — +and enables the offering herself. Enabling *is* the APIBinding; there is +no marketplace API to call, and no privileged component involved: + +```sh +kubectl --kubeconfig /tmp/alice.kubeconfig apply -f - <<'EOF' +apiVersion: apis.kcp.io/v1alpha2 +kind: APIBinding +metadata: + name: things +spec: + reference: + export: + path: root:marketplace:producers:acme + name: things.acme.example +EOF +# apibinding.apis.kcp.io/things created + +kubectl --kubeconfig /tmp/alice.kubeconfig get apibinding things -o jsonpath='{.status.phase}' +# Bound +``` + +kcp allowed this because two independent things were true: alice may +create APIBindings in that workspace (her tenancy `admin` Membership), and +the export's workspace grants `bind` (the offering is published). Remove +either and it fails. + +The API is then hers to use, in her own project: + +```sh +kubectl --kubeconfig /tmp/alice.kubeconfig apply -f - <<'EOF' +apiVersion: acme.example/v1alpha1 +kind: Thing +metadata: + name: hello +spec: + message: "from alice's project" +EOF +# thing.acme.example/hello created + +kubectl --kubeconfig /tmp/alice.kubeconfig get things +# NAME AGE +# hello 1s +``` + +Bob, `view` on the same project, cannot enable anything — the tenancy role +decides, and kcp enforces it: + +```sh +kubectl --kubeconfig /tmp/bob.kubeconfig apply -f - <<'EOF' +apiVersion: apis.kcp.io/v1alpha2 +kind: APIBinding +metadata: + name: things-by-bob +spec: + reference: + export: + path: root:marketplace:producers:acme + name: things.acme.example +EOF +# Error from server (Forbidden): apibindings.apis.kcp.io is forbidden: +# User "bob@team-b.example.com" cannot create resource "apibindings" +# in API group "apis.kcp.io" at the cluster scope: access denied + +kubectl --kubeconfig /tmp/bob.kubeconfig get things +# NAME AGE ← but he reads what alice enabled, as `view` should +# hello 11s +``` + +Note what never happened: no component wrote into alice's project, no +marketplace API or WorkspaceType exists there, and nobody relayed her +identity. "Who may enable what, where" was answered entirely by kcp, from +her Membership's RBAC and the producer's `bind` grant. diff --git a/hack/tilt/dex-pki.sh b/hack/tilt/dex-pki.sh new file mode 100755 index 0000000..b21ad3d --- /dev/null +++ b/hack/tilt/dex-pki.sh @@ -0,0 +1,86 @@ +#!/usr/bin/env bash + +# Copyright 2026 The kcp Authors. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Mints the Dex serving certificate for the Tilt setup: a single +# self-signed cert for dex.kcp.localhost, minted on the host so the same +# CA file both goes into the cluster (secret dex-tls, which kcp's +# spec.auth.oidc.caFileRef mounts) and stays on disk for the virtual +# workspaces' --oidc-ca-file and `contribctl tenancy login --ca-file`. +# Reused across runs, and recovered from the cluster when this directory is +# gone, because a CHANGED certificate is expensive here in a way a missing +# one is not: +# +# - a browser will not talk to a self-signed issuer until someone has +# visited it once and accepted the warning, and that acceptance is per +# certificate — so a new one silently breaks signing in from a browser; +# - dex reads its certificate once at boot, so a new one means every OIDC +# validator has to be rolled with it or they answer 401 to everything. +# +# So the cluster's secret is the source of truth and this directory is a +# cache of it. Wiping .tilt no longer changes the certificate; only losing +# the cluster does. + +set -euo pipefail + +DEX_DIR="${1:?usage: dex-pki.sh }" +VALID_DAYS="${PKI_VALID_DAYS:-365}" +DEX_HOST="${DEX_HOST:-dex.kcp.localhost}" +SECRET="${DEX_TLS_SECRET:-dex-tls}" + +mkdir -p "${DEX_DIR}" +if openssl x509 -in "${DEX_DIR}/tls.crt" -checkend 3600 >/dev/null 2>&1; then + echo "dex serving cert in ${DEX_DIR} is current" + exit 0 +fi + +# Nothing usable on disk. Before minting a new one — which invalidates +# every browser exception and requires rolling the validators — see whether +# the cluster already has one. +recover() { + local key crt + key="$(kubectl get secret "${SECRET}" -o jsonpath='{.data.tls\.key}' 2>/dev/null || true)" + crt="$(kubectl get secret "${SECRET}" -o jsonpath='{.data.tls\.crt}' 2>/dev/null || true)" + [ -n "${key}" ] && [ -n "${crt}" ] || return 1 + + printf '%s' "${crt}" | base64 -d > "${DEX_DIR}/tls.crt.try" 2>/dev/null || return 1 + printf '%s' "${key}" | base64 -d > "${DEX_DIR}/tls.key.try" 2>/dev/null || return 1 + openssl x509 -in "${DEX_DIR}/tls.crt.try" -checkend 3600 >/dev/null 2>&1 || return 1 + + mv "${DEX_DIR}/tls.crt.try" "${DEX_DIR}/tls.crt" + mv "${DEX_DIR}/tls.key.try" "${DEX_DIR}/tls.key" + chmod 600 "${DEX_DIR}/tls.key" + cp "${DEX_DIR}/tls.crt" "${DEX_DIR}/ca.crt" + return 0 +} + +if recover; then + echo "recovered the dex serving cert from secret/${SECRET}; nothing to re-accept" + exit 0 +fi +rm -f "${DEX_DIR}"/tls.crt.try "${DEX_DIR}"/tls.key.try + +echo "generating dex serving cert in ${DEX_DIR} (valid ${VALID_DAYS} days)" +echo "NOTE: a new certificate — accept it once in the browser, and the" +echo " validators roll with it automatically." +rm -f "${DEX_DIR}"/tls.crt "${DEX_DIR}"/tls.key "${DEX_DIR}"/ca.crt + +openssl req -x509 -newkey rsa:2048 -nodes -days "${VALID_DAYS}" \ + -keyout "${DEX_DIR}/tls.key" -out "${DEX_DIR}/tls.crt" \ + -subj "/CN=${DEX_HOST}" \ + -addext "subjectAltName=DNS:${DEX_HOST}" + +# Self-signed: the leaf is its own trust anchor. +cp "${DEX_DIR}/tls.crt" "${DEX_DIR}/ca.crt" diff --git a/hack/tilt/dex.yaml b/hack/tilt/dex.yaml new file mode 100644 index 0000000..dc372d5 --- /dev/null +++ b/hack/tilt/dex.yaml @@ -0,0 +1,175 @@ +# Dex for the Tilt setup: the OIDC issuer kcp and the virtual workspaces +# share. It runs in the same kind cluster, terminates its own TLS (secret +# dex-tls, minted by dex-pki.sh) and is reachable as +# https://dex.kcp.localhost:8443/dex both from the host (the ingress +# port-forward) and from the kcp pods (hostAliases -> the envoy gateway). +# +# The identities mirror hack/dex/dex.sh: alice/bob/mallory, plus admin, +# the platform administrator the Tiltfile grants the platform-admin role +# to. One shared password ("password"), a public client "kcp" for PKCE and the password +# grant. With kcp's operator-side claim mapping (usernameClaim: email, no +# prefix) the resulting kcp username is the plain email, +# e.g. alice@team-a.example.com. +apiVersion: v1 +kind: ServiceAccount +metadata: + name: dex + namespace: default +--- +# Kubernetes storage means dex creates its own CRDs on first start and +# then reads and writes them — including the signing keys whose survival +# across restarts is the whole point. +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: dex +rules: + - apiGroups: ["dex.coreos.com"] + resources: ["*"] + verbs: ["*"] + - apiGroups: ["apiextensions.k8s.io"] + resources: ["customresourcedefinitions"] + verbs: ["create", "get", "list", "watch"] +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: dex +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: dex +subjects: + - kind: ServiceAccount + name: dex + namespace: default +--- +apiVersion: v1 +kind: ConfigMap +metadata: + name: dex + namespace: default +data: + config.yaml: | + issuer: https://dex.kcp.localhost:8443/dex + # Kubernetes storage, not memory, because dex mints its signing keys + # on first start and keeps them in storage. With memory storage every + # restart produces new keys, which invalidates every token already + # issued AND leaves the front-proxy, both shards and both virtual + # workspaces holding a JWKS that no longer verifies anything — the + # whole stack rejects logins until each of them is restarted too. + # Persisting the keys in the cluster makes a dex restart a non-event. + storage: + type: kubernetes + config: + inCluster: true + web: + https: 0.0.0.0:5556 + tlsCert: /etc/dex/tls/tls.crt + tlsKey: /etc/dex/tls/tls.key + oauth2: + # The password grant needs a nominated connector and a public + # client; PKCE (contribctl tenancy login without --username) works + # with the same client. + passwordConnector: local + skipApprovalScreen: true + staticClients: + - id: kcp + public: true + name: kcp + # The CLI's loopback listener: a public client doing + # authorization-code + PKCE, with no secret to keep, which is what + # PKCE is for. + redirectURIs: + - 'http://localhost:8000/callback' + enablePasswordDB: true + # All hashes are bcrypt("password"). + staticPasswords: + - email: alice@team-a.example.com + hash: "$2a$10$2b2cU8CPhOTaGrs1HRQuAueS7JTT5ZHsHSzYiFPm1leZck7Mc8T4W" + username: alice + userID: "1" + - email: bob@team-b.example.com + hash: "$2a$10$2b2cU8CPhOTaGrs1HRQuAueS7JTT5ZHsHSzYiFPm1leZck7Mc8T4W" + username: bob + userID: "2" + - email: mallory@strangers.example.com + hash: "$2a$10$2b2cU8CPhOTaGrs1HRQuAueS7JTT5ZHsHSzYiFPm1leZck7Mc8T4W" + username: mallory + userID: "3" + - email: admin@platform.example.com + hash: "$2a$10$2b2cU8CPhOTaGrs1HRQuAueS7JTT5ZHsHSzYiFPm1leZck7Mc8T4W" + username: admin + userID: "4" +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: dex + namespace: default + labels: + app: dex +spec: + replicas: 1 + selector: + matchLabels: + app: dex + template: + metadata: + labels: + app: dex + spec: + serviceAccountName: dex + containers: + - name: dex + image: ghcr.io/dexidp/dex:v2.44.0 + command: ["/usr/local/bin/dex", "serve", "/etc/dex/cfg/config.yaml"] + ports: + - containerPort: 5556 + volumeMounts: + - name: config + mountPath: /etc/dex/cfg + readOnly: true + - name: tls + mountPath: /etc/dex/tls + readOnly: true + readinessProbe: + tcpSocket: + port: 5556 + volumes: + - name: config + configMap: + name: dex + - name: tls + secret: + secretName: dex-tls +--- +apiVersion: v1 +kind: Service +metadata: + name: dex + namespace: default +spec: + selector: + app: dex + ports: + - port: 5556 + targetPort: 5556 +--- +# SNI-routed through the same envoy gateway and 8443 port-forward as the +# kcp shards; dex terminates the TLS itself (mode Passthrough upstream). +apiVersion: gateway.networking.k8s.io/v1alpha3 +kind: TLSRoute +metadata: + name: dex + namespace: default +spec: + parentRefs: + - name: eg + namespace: envoy-gateway-system + hostnames: + - dex.kcp.localhost + rules: + - backendRefs: + - name: dex + port: 5556 diff --git a/hack/tilt/ingress-forward.sh b/hack/tilt/ingress-forward.sh new file mode 100755 index 0000000..4249c0f --- /dev/null +++ b/hack/tilt/ingress-forward.sh @@ -0,0 +1,53 @@ +#!/usr/bin/env bash + +# Copyright 2026 The kcp Authors. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Keeps https://kcp.localhost:8443 reachable from the host. +# +# The gateway's Service is a LoadBalancer whose external IP is only routable +# inside the cluster, so the host reaches it through a port-forward. That +# forward used to be something you started by hand, which meant it died with +# the gateway pod and took the whole stack's address with it — every +# kubeconfig, the UI, and the CLI all point at this one port, so losing it +# looks like everything being broken at once. +# +# Run as a Tilt serve_cmd it is restarted automatically, and this loop +# re-resolves the Service each time: its name carries a hash that changes +# when the Gateway is recreated, so hard-coding it would break on exactly +# the rebuild this is meant to survive. + +set -uo pipefail + +NAMESPACE="${GATEWAY_NAMESPACE:-envoy-gateway-system}" +SELECTOR="${GATEWAY_SELECTOR:-gateway.envoyproxy.io/owning-gateway-name=eg}" +PORT="${INGRESS_PORT:-8443}" + +while :; do + svc="$(kubectl -n "$NAMESPACE" get svc -l "$SELECTOR" \ + -o jsonpath='{.items[0].metadata.name}' 2>/dev/null || true)" + + if [ -z "$svc" ]; then + echo "waiting for the gateway Service in $NAMESPACE ($SELECTOR)" + sleep 5 + continue + fi + + echo "forwarding localhost:$PORT -> $NAMESPACE/$svc:$PORT" + # Exits when the pod behind the Service goes away; the loop re-resolves + # and reconnects rather than leaving the port dead. + kubectl -n "$NAMESPACE" port-forward "svc/$svc" "$PORT:$PORT" || true + echo "forward dropped, reconnecting" + sleep 2 +done diff --git a/hack/tilt/mcp-offering.sh b/hack/tilt/mcp-offering.sh new file mode 100755 index 0000000..dee8468 --- /dev/null +++ b/hack/tilt/mcp-offering.sh @@ -0,0 +1,127 @@ +#!/usr/bin/env bash + +# Copyright 2026 The kcp Authors. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Publishes MCP to the marketplace catalog. +# +# MCP is its own producer: `mcp init` already installed its APIExport in +# root:mcp:controllers, annotated for the catalog. Two things are still +# missing before the marketplace will list it, and neither belongs to mcp: +# +# 1. a Producer record naming that workspace, because the marketplace +# refuses to publish from a workspace no record names — otherwise any +# workspace could put itself on the catalog by annotating its own +# export; +# 2. a marketplace-publish binding in that workspace, which is what lets +# the marketplace operator see the annotation and materialize the +# `bind` grant. Binding it IS the registration consent. +# +# That makes mcp an external ("bring your own") producer in marketplace +# terms, which is the honest description: it is a component in this repo, +# but to the marketplace it is just a workspace that asked to publish. + +set -euo pipefail + +KUBECONFIG_FILE="${KUBECONFIG:?KUBECONFIG must point at a kcp admin kubeconfig}" +SERVER="${KCP_FRONT_PROXY_URL:-https://kcp.localhost:8443}" +CATALOG="${MARKETPLACE_CATALOG_WORKSPACE:-root:marketplace:catalog}" +EXPORTS="${MARKETPLACE_EXPORTS_WORKSPACE:-root:marketplace:controllers}" +MCP_WS="${MCP_WORKSPACE:-root:mcp:controllers}" +TIMEOUT="${TIMEOUT_SECONDS:-120}" + +kube() { kubectl --kubeconfig "$KUBECONFIG_FILE" --server "$1" "${@:2}"; } + +echo "==> registering $MCP_WS as a marketplace producer" +kube "$SERVER/clusters/$CATALOG" apply -f - < binding marketplace-publish in $MCP_WS (the registration consent)" +kube "$SERVER/clusters/$MCP_WS" apply -f - < waiting for the bind grant" +deadline=$((SECONDS + TIMEOUT)) +until kube "$SERVER/clusters/$MCP_WS" get clusterrole marketplace:bind:mcp >/dev/null 2>&1; do + if [ "$SECONDS" -ge "$deadline" ]; then + echo "no bind grant for the mcp export after ${TIMEOUT}s." >&2 + echo "Is marketplace-operator running, and did the Producer record resolve?" >&2 + exit 1 + fi + sleep 2 +done + +echo +echo "MCP is on the catalog. Enable it in a project:" +echo " bin/contribctl offers" +echo " bin/contribctl enable mcp.mcp" +echo +echo "Then read back where to point a client:" +echo " kubectl --server $SERVER/clusters/ get mcpendpoints" diff --git a/hack/tilt/pki.sh b/hack/tilt/pki.sh new file mode 100755 index 0000000..8c259a8 --- /dev/null +++ b/hack/tilt/pki.sh @@ -0,0 +1,48 @@ +#!/usr/bin/env bash + +# Copyright 2026 The kcp Authors. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Mints the development client CA and user certificates the virtual +# workspaces authenticate direct callers with under Tilt: CN becomes the +# username, O the groups. Reused across runs; regenerated when missing or +# close to expiry. + +set -euo pipefail + +PKI_DIR="${1:?usage: pki.sh }" +VALID_DAYS="${PKI_VALID_DAYS:-30}" + +mkdir -p "${PKI_DIR}" +if [[ -f "${PKI_DIR}/alice.crt" ]] && openssl x509 -in "${PKI_DIR}/ca.crt" -checkend 3600 >/dev/null 2>&1; then + echo "dev PKI in ${PKI_DIR} is current" + exit 0 +fi + +echo "generating dev PKI in ${PKI_DIR} (valid ${VALID_DAYS} days)" +rm -f "${PKI_DIR}"/*.crt "${PKI_DIR}"/*.key "${PKI_DIR}"/*.csr "${PKI_DIR}"/*.srl + +openssl req -x509 -newkey rsa:2048 -nodes -days "${VALID_DAYS}" \ + -keyout "${PKI_DIR}/ca.key" -out "${PKI_DIR}/ca.crt" \ + -subj "/CN=contrib-tilt-dev-ca" + +for spec in "alice:team-a" "bob:team-b"; do + user="${spec%%:*}"; group="${spec#*:}" + openssl req -newkey rsa:2048 -nodes \ + -keyout "${PKI_DIR}/${user}.key" -out "${PKI_DIR}/${user}.csr" \ + -subj "/CN=${user}/O=${group}" + openssl x509 -req -in "${PKI_DIR}/${user}.csr" \ + -CA "${PKI_DIR}/ca.crt" -CAkey "${PKI_DIR}/ca.key" -CAcreateserial \ + -days "${VALID_DAYS}" -out "${PKI_DIR}/${user}.crt" +done diff --git a/hack/tilt/up.sh b/hack/tilt/up.sh new file mode 100755 index 0000000..ac7ff62 --- /dev/null +++ b/hack/tilt/up.sh @@ -0,0 +1,43 @@ +#!/usr/bin/env bash + +# Copyright 2026 The kcp Authors. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Brings up the whole development stack: a kind cluster (the same name +# kcp's own tilt setup uses, so either entry point works on it), then Tilt +# with the repo Tiltfile — kcp from the kcp checkout, this repo's +# components on top. +# +# hack/tilt/up.sh +# KCP_DIR=/path/to/kcp hack/tilt/up.sh + +set -euo pipefail + +REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" +cd "${REPO_ROOT}" + +for tool in tilt kind helm kubectl docker; do + command -v "${tool}" >/dev/null 2>&1 || { echo "ERR: ${tool} is required"; exit 1; } +done + +KCP_DIR="${KCP_DIR:-${REPO_ROOT}/../kcp}" +[[ -f "${KCP_DIR}/contrib/tilt/Tiltfile" ]] || { echo "ERR: no kcp checkout at ${KCP_DIR}; set KCP_DIR"; exit 1; } + +CLUSTER_NAME="${CLUSTER_NAME:-kcp-tilt}" +if ! kind get clusters 2>/dev/null | grep -w -q "${CLUSTER_NAME}"; then + kind create cluster --name "${CLUSTER_NAME}" +fi +kubectl config use-context "kind-${CLUSTER_NAME}" + +KCP_DIR="${KCP_DIR}" exec tilt up "$@" diff --git a/hack/tools/tools.go b/hack/tools/tools.go new file mode 100644 index 0000000..0f3ff47 --- /dev/null +++ b/hack/tools/tools.go @@ -0,0 +1,27 @@ +//go:build tools + +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// Package tools pins the code generators `make generate` runs with `go +// run`, so `go mod tidy` keeps their modules resolvable. Nothing imports +// this package; the build tag keeps it out of every build. +package tools + +import ( + _ "github.com/kcp-dev/sdk/cmd/apigen" + _ "k8s.io/kube-openapi/cmd/openapi-gen" +) diff --git a/hack/update-apiresourceschemas.sh b/hack/update-apiresourceschemas.sh new file mode 100755 index 0000000..80c59bd --- /dev/null +++ b/hack/update-apiresourceschemas.sh @@ -0,0 +1,118 @@ +#!/usr/bin/env bash + +# Copyright 2026 The kcp Authors. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Regenerates every APIResourceSchema from the Go types, the way kcp does +# it: controller-gen renders CRDs from the kubebuilder markers, kcp's +# apigen converts them into APIResourceSchemas — content-addressed names +# (v-..), reusing the committed schema when +# nothing changed, because APIResourceSchemas are immutable and a changed +# schema MUST be a new object — and this script then rewrites the schema +# references inside each component's own APIExport manifests. +# +# apigen also wants to own one APIExport per group, which this repo +# deliberately does not do (a group's resources are split across exports +# so that capabilities are granted separately). Its export output is +# discarded; only the schemas and their names are taken. +# +# Run `make generate` after changing any sdk/apis type. + +set -euo pipefail + +REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +cd "${REPO_ROOT}" + +CONTROLLER_GEN_VERSION="${CONTROLLER_GEN_VERSION:-v0.19.0}" + +log() { printf '\033[1;32m==>\033[0m %s\n' "$*"; } + +# component +generate() { + local name=$1 pkg=$2 assets=$3 + shift 3 + local stage + stage="$(mktemp -d)" + mkdir -p "${stage}/crds" "${stage}/out" + + log "${name}: rendering CRDs from ${pkg}" + go run "sigs.k8s.io/controller-tools/cmd/controller-gen@${CONTROLLER_GEN_VERSION}" \ + crd paths="${pkg}" output:crd:dir="${stage}/crds" + + # Virtual kinds are served by the virtual workspace, never stored in + # kcp, so they get no APIResourceSchema. + local virtual + for virtual in "$@"; do + rm -f "${stage}/crds/"*_"${virtual}.yaml" + done + + # Seed the stage with the committed GENERATED schemas so apigen can keep + # their names when the shape did not change. (Only files following its + # apiresourceschema-..yaml naming; hand-written ones from + # before generation cannot seed it and are simply replaced.) + cp "${assets}"/apiresourceschema-*.*.*.yaml "${stage}/out/" 2>/dev/null || true + + log "${name}: converting CRDs to APIResourceSchemas" + go run github.com/kcp-dev/sdk/cmd/apigen \ + --input-dir "${stage}/crds" --output-dir "${stage}/out" + + # Take the schemas, drop apigen's per-group APIExport, prune what it no + # longer generates, and rewrite our exports' schema references. + python3 - "$name" "$assets" "$stage/out" <<'PY' +import glob, os, re, sys + +name, assets, out = sys.argv[1], sys.argv[2], sys.argv[3] + +generated = {} # (group, plural) -> (schema name, file basename) +for path in sorted(glob.glob(os.path.join(out, "apiresourceschema-*.yaml"))): + text = open(path).read() + schema_name = re.search(r"^ name: (\S+)$", text, re.M).group(1) + group = re.search(r"^ group: (\S+)$", text, re.M).group(1) + plural = re.search(r"^ plural: (\S+)$", text, re.M).group(1) + generated[(group, plural)] = (schema_name, os.path.basename(path)) + +for old in glob.glob(os.path.join(assets, "apiresourceschema-*.yaml")): + os.remove(old) +for (_, _), (schema_name, base) in generated.items(): + src = os.path.join(out, base) + dst = os.path.join(assets, base) + open(dst, "w").write(open(src).read()) + +# Rewrite `schema: ` lines in OUR APIExport manifests: any name +# ending in .. becomes the freshly generated one. +for path in glob.glob(os.path.join(assets, "apiexport-*.yaml")): + text = open(path).read() + for (group, plural), (schema_name, _) in generated.items(): + text = re.sub( + r"(schema: )\S*\.%s\.%s\b" % (re.escape(plural), re.escape(group)), + r"\g<1>" + schema_name, text) + open(path, "w").write(text) + +names = ", ".join(sorted(v[1] for v in generated.values())) +print(f"{name}: {len(generated)} schemas -> {names}") +PY + + rm -rf "${stage}" +} + +generate marketplace ./marketplace/sdk/apis/marketplace/v1alpha1 marketplace/config/apiexport catalogofferings +generate mcp ./mcp/sdk/apis/mcp/v1alpha1 mcp/config/apiexport +# The self-* kinds are the virtual workspace's own request surface: they +# are answered in memory and never stored, so they need no schema and must +# not appear in the export. +generate tenancy ./tenancy/sdk/apis/tenancy/v1alpha1 tenancy/config/apiexport \ + selftenancyreviews selfprojectrequests selftenantrequests + +log "done; if schema file names changed, update the ExportsOrder lists in" +log " marketplace/config/apiexport/bootstrap.go and tenancy/config/apiexport/bootstrap.go" diff --git a/marketplace/README.md b/marketplace/README.md new file mode 100644 index 0000000..6a7ae7e --- /dev/null +++ b/marketplace/README.md @@ -0,0 +1,628 @@ +# Marketplace + +A producer/offering marketplace for [kcp](https://github.com/kcp-dev/kcp): +**one** cluster-scoped resource — **Producer** — that an operator turns +into producer workspaces, plus per-export `bind` grants, plus a virtual +workspace that serves the catalog read-only. + +An offering has no resource of its own. A producer publishes by annotating +their **APIExport**, so the offering *is* the export. And enabling one is +**kcp itself**: the consumer creates a plain `APIBinding` in their own +workspace, kcp checks the `bind` grant publishing materialized, and the +marketplace has no footprint in consumer workspaces at all. + +Why each piece is shaped this way is explained where it is enforced: the +tiers in [config/apiexport/](config/apiexport/), the publish flow in +[pkg/operator/publish.go](pkg/operator/publish.go), and what an annotated +export means in [pkg/offering/](pkg/offering/). This file is how to use +it. + +## The model + +`marketplace-vw init` creates three workspaces. Everything below them is +bound by a `WorkspaceType` or by the owner's own consent — never by hand +and never by an admin; the operator holds no admin client at all. + +``` +root +└── marketplace + ├── controllers ..................... what init installs, bound by nobody + │ APIExport marketplace-catalog ....... exports Producers + │ APIExport marketplace-publish ....... NO resources; claims RBAC, + │ apiexports (read), logicalclusters + │ APIExport marketplace-provisioner ... NO resources; claims workspaces + │ WorkspaceType producer .............. no tenancy, no topology + │ + ├── catalog ........................ the registry (--catalog-workspace) + │ Producer "acme" .................... the record, and only the record + │ + └── producers ...................... provisioning parent (--producers-workspace) + │ + └── acme ...................... WorkspaceType: producer + APIBinding marketplace-publish ... from the WorkspaceType + APIExport things.acme.example ..... the producer's OWN export, + annotated: it IS the offering + ClusterRole/CRB: bind on the export → consumers + +any workspace at all (a tenancy project, a plain workspace — no type needed) + APIBinding things.acme.example ........... created by the CONSUMER: + enabling IS this object +``` + +| Object | Lives in | Written by | Reached through | +|---|---|---|---| +| `Producer` | the catalog | an admin | `marketplace-catalog` | +| the offering (annotations on an `APIExport`) | the producer's workspace | the producer | `marketplace-publish` claims | +| bind ClusterRole/CRB | the producer's workspace | the operator | `marketplace-publish` claims | +| the offering's `APIBinding` | the consumer's workspace | **the consumer**, natively | kcp, no marketplace involved | + +Three facts carry the security model: + +- **Registration is a `bind` grant.** Publishing materializes `bind` on + that one export in the producer's workspace, to the configured consumers + (default: any authenticated user; `--bind-user`/`--bind-group` restrict + it). kcp checks that verb on every APIBinding — removing the annotation + revokes it, and being admin of one's own workspace grants nothing on the + producer's side. A workspace no `Producer` record names gets no grant at + all, so annotating your own export is not a way onto the catalog. +- **The offering cannot misdescribe the export.** It is the export: the + claim surface the catalog advertises is the export's own + `spec.permissionClaims`, read straight off it. There is no second + declaration to validate, to intersect, or to drift. +- **Consent is the consumer's own object.** Those claims are accepted on + the APIBinding the consumer authors, which nothing in the marketplace can + write. A producer changing their claims changes the catalog's revision; + existing bindings are structurally untouchable. +- **Who may enable is the workspace's RBAC, natively.** Creating an + APIBinding needs the consumer's own rights in their own workspace — + which is exactly what a [tenancy](../tenancy/) `admin` Membership + materializes. The two components compose through kcp alone, with no + knowledge of each other. + +## Run it locally + +Nine steps, from nothing to a user enabling an offering through the +virtual workspace with only their own certificate. Run them from the +**repository root**, each long-running one in its own shell. + +If you would rather have it done for you, `make test-e2e-marketplace` +performs exactly these steps and then runs the suite against them — +[hack/ci/run-e2e-tests.sh](hack/ci/run-e2e-tests.sh) is the executable +version of this section, and it leaves a working `.e2e/` behind to poke +at. + +### 1. Build + +```sh +make build-marketplace # bin/marketplace-vw +``` + +One binary, three subcommands (`init`, `operator`, `virtualworkspace`), +one image (`ghcr.io/kcp-dev/contrib-virtual-workspaces/marketplace-vw`). + +### 2. Generate certificates + +The virtual workspace authenticates callers itself, and `kcp start` mints +no client CA, so you make one. A certificate's **CommonName becomes the +username** — the string SubjectAccessReviews carry and RBAC matches. + +```sh +mkdir -p pki && (cd pki + +openssl req -x509 -newkey rsa:2048 -nodes -days 30 \ + -keyout ca.key -out ca.crt -subj "/CN=marketplace-dev-ca" + +for spec in "alice:team-a" "bob:team-b"; do + user="${spec%%:*}"; group="${spec#*:}" + openssl req -newkey rsa:2048 -nodes \ + -keyout "$user.key" -out "$user.csr" -subj "/CN=$user/O=$group" + openssl x509 -req -in "$user.csr" -CA ca.crt -CAkey ca.key \ + -CAcreateserial -days 30 -out "$user.crt" +done) +``` + +### 3. Run kcp + +From a kcp checkout (`make build` there, or `go build ./cmd/kcp`): + +```sh +kcp start --root-directory .kcp --secure-port 6443 --client-ca-file pki/ca.crt +``` + +`--client-ca-file` matters for step 9: an enabled API is served by *kcp*, +so a user reaching it with a certificate kcp was not told to trust arrives +as `system:anonymous`. If something already listens on 6443 — Docker +Desktop and OrbStack both do — pick another port here and match it below. + +Then, in every other shell: + +```sh +export KUBECONFIG=$PWD/.kcp/admin.kubeconfig +``` + +### 4. Install the exports + +```sh +bin/marketplace-vw init --kubeconfig "$KUBECONFIG" +``` + +This creates the three workspaces from [the model](#the-model) and nothing +below them. Idempotent: run it twice and the second run is a no-op. + +`--platform-admin-user` and `--platform-admin-group` (both repeatable) name +who may register Producers: they are bound to +`marketplace.platform.kcp.io:platform-admin` in the catalog, a role that +may enter it and manage Producers and nothing else. The binding holds +exactly the identities of the latest run, so dropping one from the flags +revokes it. + +### 5. Run the operator + +```sh +bin/marketplace-vw operator --kubeconfig "$KUBECONFIG" \ + --workspace-path root:marketplace:controllers \ + --catalog-workspace root:marketplace:catalog \ + --producers-workspace root:marketplace:producers +``` + +The per-offering `bind` grants it materializes name `system:authenticated` +by default — any authenticated user may enable, in a workspace their own +RBAC lets them bind in. `--bind-user`/`--bind-group` restrict who. + +### 6. Run the virtual workspace + +```sh +bin/marketplace-vw virtualworkspace --kubeconfig "$KUBECONFIG" \ + --workspace-path root:marketplace:controllers \ + --secure-port 9446 \ + --client-ca-file pki/ca.crt +``` + +### 7. Register a producer and publish an offering + +> Ready-made versions of everything in this step live in +> [config/examples/](config/examples/), with a script that applies them to +> the right workspaces: `marketplace/config/examples/apply.sh`, or +> `tilt trigger marketplace-examples` under Tilt. The walkthrough below is +> the same thing spelled out. + +As the administrator: a `Producer` record in the catalog makes the +operator provision `root:marketplace:producers:acme` with the `producer` +WorkspaceType, which carries the `marketplace-publish` binding — the +producer's whole surface. + +```sh +kubectl --server "https://localhost:6443/clusters/root:marketplace:catalog" \ + apply -f - <<'EOF' +apiVersion: marketplace.platform.kcp.io/v1alpha1 +kind: Producer +metadata: + name: acme +spec: + displayName: Acme + mode: provisioned +EOF +``` + +Wait for `PHASE: Ready`, then act as the producer inside that workspace. +A producer brings their own APIExport — the marketplace never defines what +a producer serves, only how it is offered: + +```sh +PRODUCER="https://localhost:6443/clusters/root:marketplace:producers:acme" + +kubectl --server "$PRODUCER" apply -f - <<'EOF' +apiVersion: apis.kcp.io/v1alpha1 +kind: APIResourceSchema +metadata: + name: v1alpha1.things.acme.example +spec: + group: acme.example + names: + kind: Thing + listKind: ThingList + plural: things + singular: thing + scope: Cluster + versions: + - name: v1alpha1 + served: true + storage: true + schema: + type: object + properties: + apiVersion: {type: string} + kind: {type: string} + metadata: {type: object} + spec: + type: object + properties: + message: {type: string} +--- +apiVersion: apis.kcp.io/v1alpha2 +kind: APIExport +metadata: + name: things.acme.example + # These three annotations are the offering. There is no other object. + annotations: + marketplace.kcp.hub/publish: "true" + marketplace.kcp.hub/display-name: "Things as a service" + marketplace.kcp.hub/description: "One Thing per workspace, batteries included." +spec: + resources: + - name: things + group: acme.example + schema: v1alpha1.things.acme.example + storage: + crd: {} + # And these are the consent form: what the catalog advertises and what a + # consumer accepts are this list, not a copy of it. + permissionClaims: + - group: "" + resource: configmaps + verbs: [get, list, watch] +EOF + +kubectl --server "$PRODUCER" get clusterrole marketplace:bind:things.acme.example +``` + +That ClusterRole appearing is the operator having seen the annotation: +publishing materializes `bind` on this one export, and nothing else. There +is no status to wait for, because there is no object to carry one — the +catalog derives everything it shows from the export itself. + +Only the exact value `"true"` publishes. A typo leaves the export off the +catalog rather than on it, which is the safe direction: being on it is what +hands `bind` to strangers. + +To take it off the catalog again, remove the annotation — the grant goes +with it, and the export and everyone already bound to it are untouched: + +```sh +kubectl --server "$PRODUCER" annotate apiexport things.acme.example \ + marketplace.kcp.hub/publish- +``` + +### 8. Create a consumer workspace and enable + +A consumer workspace is **any workspace** — no marketplace type, no +marketplace bindings. Enabling is creating the APIBinding yourself: the +reference comes from the catalog entry (workspace path + export), the +claims are the entry's `claims`, accepted on **your** object — that +acceptance is the consent, first-class in kcp. + +```sh +kubectl --server "https://localhost:6443/clusters/root" apply -f - <<'EOF' +apiVersion: tenancy.kcp.io/v1alpha1 +kind: Workspace +metadata: + name: team-a +EOF + +CONSUMER="https://localhost:6443/clusters/root:team-a" + +kubectl --server "$CONSUMER" apply -f - <<'EOF' +apiVersion: apis.kcp.io/v1alpha2 +kind: APIBinding +metadata: + name: things +spec: + reference: + export: + path: root:marketplace:producers:acme + name: things.acme.example + permissionClaims: + - group: "" + resource: configmaps + verbs: [get, list, watch] + state: Accepted + selector: + matchAll: true +EOF + +kubectl --server "$CONSUMER" get apibindings +``` + +When it reports `Ready`, the producer's API serves here — kcp checked the +`bind` grant in acme's workspace on the way, the one publishing +materialized: + +```sh +kubectl --server "$CONSUMER" apply -f - <<'EOF' +apiVersion: acme.example/v1alpha1 +kind: Thing +metadata: + name: first +spec: + message: enabled through a plain kcp bind +EOF +``` + +Disabling is deleting the binding. If acme later changes the export's +claims, the catalog shows a different `revision` — and your binding keeps +exactly the claims you accepted, because they live on your object and +nothing in the marketplace can write it. + +### 9. Be a user + +Users don't hold the admin kubeconfig. They browse the catalog through the +virtual workspace with their own credential, and enable by binding in a +workspace their own RBAC allows — which is what a tenancy `admin` +Membership materializes. Grant alice by hand here, standing in for +tenancy: + +```sh +kubectl --server "$CONSUMER" apply -f - <<'EOF' +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: team-a-admin +rules: + - apiGroups: ["*"] + resources: ["*"] + verbs: ["*"] + - nonResourceURLs: ["/"] + verbs: ["access"] +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: team-a-admin-alice +subjects: + - kind: User + name: alice + apiGroup: rbac.authorization.k8s.io +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: team-a-admin +EOF +``` + +Now alice, with nothing but her certificate. `--kubeconfig /dev/null` +matters on every one of these: with `$KUBECONFIG` exported, kubectl would +merge the admin bearer token in and it silently wins over the certificate +— you would be admin wearing an alice suit. + +Browse the catalog — every entry carries the bind coordinates and the +claims: + +```sh +kubectl --kubeconfig /dev/null \ + --server "https://localhost:9446/services/marketplace" \ + --client-certificate pki/alice.crt --client-key pki/alice.key \ + --insecure-skip-tls-verify \ + get offerings +``` + +Unbind and re-bind, as alice, natively against kcp: + +```sh +kubectl --kubeconfig /dev/null --server "$CONSUMER" \ + --client-certificate pki/alice.crt --client-key pki/alice.key \ + --insecure-skip-tls-verify \ + delete apibinding things + +kubectl --kubeconfig /dev/null --server "$CONSUMER" \ + --client-certificate pki/alice.crt --client-key pki/alice.key \ + --insecure-skip-tls-verify \ + apply -f - <<'EOF' +apiVersion: apis.kcp.io/v1alpha2 +kind: APIBinding +metadata: + name: things +spec: + reference: + export: + path: root:marketplace:producers:acme + name: things.acme.example + permissionClaims: + - group: "" + resource: configmaps + verbs: [get, list, watch] + state: Accepted + selector: + matchAll: true +EOF + +kubectl --kubeconfig /dev/null --server "$CONSUMER" \ + --client-certificate pki/alice.crt --client-key pki/alice.key \ + --insecure-skip-tls-verify \ + get apibindings +``` + +Run the same commands with `pki/bob.crt` and `pki/bob.key` and every call +is refused — bob holds nothing in `team-a`, and it is the workspace +refusing, not the marketplace: there is no marketplace in this path at +all. Delete alice's ClusterRoleBinding and her next call fails the same +way; under tenancy, that revocation is `tenancyctl revoke`. + +### BYO: a producer without provisioning + +Any workspace becomes a producer workspace by binding +`marketplace-publish` itself — the binding is the consent, and deleting it +revokes every claim it carried. Register the record with `mode: external` +and the workspace's canonical path: + +```sh +kubectl --server "https://localhost:6443/clusters/root:marketplace:catalog" \ + apply -f - <<'EOF' +apiVersion: marketplace.platform.kcp.io/v1alpha1 +kind: Producer +metadata: + name: byo +spec: + displayName: Bring-your-own + mode: external + workspacePath: root:my-services +EOF +``` + +Then, in `root:my-services`, bind the export (accepting its claims — see +[test/e2e/scenarios_vw_test.go](test/e2e/scenarios_vw_test.go) for the +full APIBinding shape) and annotate your APIExports exactly as in step 7. +The operator learns the workspace's cluster from the first published +export there, matched against the record's path — a workspace no record +names publishes into the void, and gets no `bind` grant for trying. + +## Instructions: how a producer says "here is how to use this" + +An offering can ship setup instructions — per client, per scenario — as +text a consumer sees in the console after enabling it. Two annotations on +the APIExport: + +```yaml +metadata: + annotations: + marketplace.kcp.hub/instructions: things-instructions # a ConfigMap, same workspace + marketplace.kcp.hub/docs-url: https://docs.example/things +``` + +The ConfigMap's keys are sections, shown as tabs; a leading `NN-` orders +them and is dropped from the label, so `10-claude-code.md` reads as +*Claude Code*. The content is a small markdown subset — headings, +paragraphs, lists, fenced code, `inline code`, `[links](https://…)` — and +is rendered as elements rather than HTML, so a producer can write a code +block but not a script, and only `http(s)` links become links. + +Inside the text, `{{variables}}` are filled in for whoever is reading, so a +snippet is copy-and-run rather than copy-and-edit: + +| Variable | Value | +|---|---| +| `{{server}}` | the front-proxy, e.g. `https://kcp.localhost:8443` | +| `{{workspace}}` | the reader's project workspace URL | +| `{{cluster}}` | its logical cluster id | +| `{{tenant}}`, `{{project}}` | where they are working | +| `{{user}}` | who they are, as the servers see them | +| `{{export}}`, `{{producerWorkspace}}` | the offering's bind coordinates | +| `{{binding}}` | the APIBinding that enabled it | +| `{{issuer}}`, `{{clientId}}` | the OIDC issuer the console signs in with, and its OAuth client id — for instructions that point another program at the platform | + +An unknown variable is left as written, so a typo shows on screen instead +of vanishing. + +The ConfigMap is found by name, in any namespace of the producer's +workspace — but the namespace has to exist, and a workspace the operator +provisioned has none to start with (only `kcp-system`). The example ships +its own `Namespace` for that reason; a producer that already has one uses +it. Two ConfigMaps of the same name in different namespaces would collide +on the name, so keep it unique in the workspace. + +One operational note, learned adding this: the `configmaps` claim was added +to `marketplace-publish` after producer workspaces already existed, and +**kcp does not add a new claim to a binding that already exists** — a +provisioned producer's binding keeps the claims it accepted at creation. +A fresh `init` is unaffected; an upgraded stack needs each existing publish +binding to accept the new claim (or be recreated) before that producer's +instructions become readable. A ConfigMap rather than more annotations because setup +instructions for several clients are paragraphs and code blocks, not a +line; it is read through the publish export's `configmaps` claim, +read-only, and nothing but its data is read. The mcp component is the +full example — see [mcp/config/apiexport/instructions.yaml](../mcp/config/apiexport/instructions.yaml). + +## The virtual workspace + +`marketplace-vw virtualworkspace` serves, behind kcp's front-proxy or +standalone: + +``` +GET /services/marketplace/apis/marketplace.platform.kcp.io/v1alpha1/offerings +GET /debug/directory +``` + +Any authenticated caller may read the catalog; it answers 503 until both +its feeds (Producers from the catalog export, published APIExports through +the publish export) have synced, rather than answering partially. Each +entry carries the bind coordinates — `workspacePath`, `export` — and the +claims, so browsing the catalog is reading both the consent form and the +APIBinding you would author. `revision` is a digest of those claims: the +same claims always give the same revision, so a consumer who kept theirs +can tell whether the form moved. The VW writes nothing, +anywhere: enabling is between the consumer and kcp. + +Authentication mirrors the other components — client certificates, +OIDC/JWT via `--authentication-config` (hand it the same file kcp gets; +[../hack/dex/](../hack/dex/) writes one), or forwarded request-header +identity behind the front-proxy. + +Probing by hand: + +```sh +curl -ks --cert pki/alice.crt --key pki/alice.key \ + https://localhost:9446/services/marketplace/apis/marketplace.platform.kcp.io/v1alpha1/offerings + +curl -ks --cert pki/alice.crt --key pki/alice.key \ + https://localhost:9446/debug/directory +``` + +`{"ready":true,"producers":N,"offerings":M}` says the directory is being +fed; `ready:false` plus 503s on the catalog means one of the two exports +has no consumers yet or the sync has not finished. + +## Regenerating the schemas + +The `apiresourceschema-*.yaml` assets are generated, not written: `make +generate` renders CRDs from the Go types' kubebuilder markers +(controller-gen) and converts them with kcp's own `apigen` — which gives +each schema a content-addressed name (`v-..`) +and keeps the committed name when nothing changed, because +APIResourceSchemas are immutable and a changed schema must be a new +object. The script also rewrites the `schema:` references inside this +component's APIExport manifests. After changing anything under +`sdk/apis/`, run it and commit the result; if a schema's *name* changed, +update `ExportsOrder` in [config/apiexport/bootstrap.go](config/apiexport/bootstrap.go) +to the new file name. + +## Testing + +From the repository root: + +```sh +make test-spike-marketplace # the keystone alone: the binder composition + # against a real kcp, no component involved +make test-e2e-marketplace # full stack: real kcp + operator + VW as + # local processes, 10 scenarios +``` + +The suite asserts placement and absence, because — as with tenancy — the +absence of a binding *is* the security model: which tiers carry which +bindings, that a producer workspace serves neither tenancy.kcp.io nor +topology.kcp.io, that `bind` follows the publish annotation and is revoked +when it is removed (a workspace admin cannot bind an unpublished export), +that a claim change changes the revision while the consumer's binding keeps +exactly what they accepted, that a user with workspace RBAC binds natively with their +own credential while one without cannot, and that a BYO producer is a +first-class one. + +The harness ([hack/ci/run-e2e-tests.sh](hack/ci/run-e2e-tests.sh)) builds +kcp from a sibling checkout (`KCP_DIR`, default `../../kcp`) or extracts it +from `KCP_IMAGE` in CI, runs `init` twice for idempotency, and mints a +throwaway client CA (`alice`, `bob`) for the virtual workspace scenarios. + +## Limits, stated plainly + +1. **Enabling means authoring an APIBinding.** `contribctl offers` and + `contribctl enable` (in [pkg/cli/](pkg/cli/)) do it for you from a + catalog entry; by hand, the claims must be copied from that entry — + identity hashes included — into the binding. Either way the acceptance + is the consent, on the consumer's own object, which is the point. +2. **The catalog revision is advisory.** A claim change changes it so + consumers can notice, but nothing tracks who is on which revision: + bindings belong to consumers, and the marketplace does not read their + workspaces. +3. **The catalog is visible to every authenticated caller.** There is no + per-tenant catalog scoping; a deployment wanting it would filter in + the directory. +4. **`bind` defaults to everyone authenticated.** Publishing grants + `bind` to `system:authenticated` unless the operator is started with + `--bind-user`/`--bind-group`. Enabling still requires rights in a + workspace of one's own — the grant only opens the export side. +5. **Producers police their own maximal surface.** The catalog advertises + whatever the export declares — it is the producer's own object, so + there is nothing to check it against. Setting a + `MaximalPermissionPolicy` on the export — the hard cap kcp itself + enforces — is the producer's job and is recommended, not automated. +6. **Unbinding removes the API, not the producer's leftovers.** Objects a + producer's controllers created through their claims are theirs to + garbage-collect when the cluster leaves their endpoint slice. diff --git a/marketplace/cmd/init.go b/marketplace/cmd/init.go new file mode 100644 index 0000000..fce5d7a --- /dev/null +++ b/marketplace/cmd/init.go @@ -0,0 +1,201 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package cmd + +import ( + "context" + "fmt" + "os" + "time" + + "github.com/spf13/cobra" + + "k8s.io/client-go/tools/clientcmd" + "k8s.io/klog/v2" + + accessbootstrap "github.com/kcp-dev/contrib-virtual-workspaces/access/pkg/bootstrap" + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/pkg/bootstrap" +) + +func newInitCommand() *cobra.Command { + var ( + kubeconfig string + workspacePrefix string + controllersWorkspace string + catalogWorkspace string + producersWorkspace string + workspaceType string + serverUsers []string + serverGroups []string + adminUsers []string + adminGroups []string + timeout time.Duration + ) + + cmd := &cobra.Command{ + Use: "init", + Short: "Install the marketplace APIExports, schemas and endpoint slices into kcp", + Long: `Install the kcp-side objects the marketplace needs — the schemas, the +three APIExports, the bind RBAC, the producer WorkspaceType and the +endpoint slices — and bind the two hand-bound tiers: the catalog +(Provider records) and the producers parent (where provisioned producer +workspaces are created). + +The objects land in :, default +root:marketplace:controllers. Any missing workspace along that path is +created. Idempotent: safe to run on every pod start and every upgrade.`, + RunE: func(cmd *cobra.Command, _ []string) error { + ctx, cancel := context.WithTimeout(cmd.Context(), timeout) + defer cancel() + logger := klog.FromContext(ctx) + + if kubeconfig == "" { + kubeconfig = os.Getenv("KUBECONFIG") + } + if kubeconfig == "" { + return fmt.Errorf("--kubeconfig is required, or set KUBECONFIG") + } + + cfg, err := clientcmd.BuildConfigFromFlags("", kubeconfig) + if err != nil { + return fmt.Errorf("load kubeconfig: %w", err) + } + + workspacePath, err := accessbootstrap.JoinWorkspacePath(workspacePrefix, controllersWorkspace) + if err != nil { + return err + } + + target, err := accessbootstrap.CreateWorkspacePath(ctx, cfg, workspacePath, workspaceType) + if err != nil { + return fmt.Errorf("resolve workspace path %s: %w", workspacePath, err) + } + + result, err := bootstrap.Bootstrap(ctx, target, workspacePath, bootstrap.Options{ + ServerUsers: serverUsers, + ServerGroups: serverGroups, + }) + if err != nil { + return err + } + + // The two hand-bound tiers every install gets for free. They are + // separate on purpose: the catalog holds the records, the + // producers workspace is the parent producer workspaces are + // created under, and neither can do the other's job. + var catalogPath, producersPath string + if catalogWorkspace != "" { + catalogPath, err = accessbootstrap.JoinWorkspacePath(workspacePrefix, catalogWorkspace) + if err != nil { + return err + } + logger.Info("creating the catalog", "workspace", catalogPath) + catalogCfg, err := accessbootstrap.CreateWorkspacePath(ctx, cfg, catalogPath, workspaceType) + if err != nil { + return fmt.Errorf("resolve workspace path %s: %w", catalogPath, err) + } + if err := bootstrap.BindCatalog(ctx, catalogCfg, result); err != nil { + return fmt.Errorf("bind the Provider API into %s: %w", catalogPath, err) + } + if err := bootstrap.GrantPlatformAdmins(ctx, catalogCfg, adminUsers, adminGroups); err != nil { + return fmt.Errorf("grant platform admins in %s: %w", catalogPath, err) + } + logger.Info("catalog ready", "workspace", catalogPath, + "platformAdminUsers", adminUsers, "platformAdminGroups", adminGroups) + } + if producersWorkspace != "" { + producersPath, err = accessbootstrap.JoinWorkspacePath(workspacePrefix, producersWorkspace) + if err != nil { + return err + } + logger.Info("creating the producers parent", "workspace", producersPath) + providersCfg, err := accessbootstrap.CreateWorkspacePath(ctx, cfg, producersPath, workspaceType) + if err != nil { + return fmt.Errorf("resolve workspace path %s: %w", producersPath, err) + } + if err := bootstrap.BindProvidersParent(ctx, providersCfg, result); err != nil { + return fmt.Errorf("bind the provisioner claim into %s: %w", producersPath, err) + } + logger.Info("producers parent ready", "workspace", producersPath) + } + + // Only now is there a consumer, so only now can a slice have + // URLs to report. Informational: the servers follow the slices + // themselves and pick them up whenever they appear. + sliceURLs := map[string][]string{} + for _, slice := range []string{ + bootstrap.ExportCatalog, bootstrap.ExportPublish, bootstrap.ExportProvisioner, + } { + urls, err := bootstrap.WaitForEndpointSliceURLs(ctx, target, slice) + if err != nil { + return err + } + sliceURLs[slice] = urls + } + + logger.Info("bootstrap complete", + "workspace", workspacePath, + "exportsCluster", result.ExportsCluster, + "catalogUrls", sliceURLs[bootstrap.ExportCatalog], + "publishUrls", sliceURLs[bootstrap.ExportPublish], + "provisionerUrls", sliceURLs[bootstrap.ExportProvisioner], + ) + if catalogPath != "" { + logger.Info("register Providers here; a producer publishes by annotating an APIExport in its own workspace", + "catalog", catalogPath, "provisionedUnder", producersPath, + ) + } + logger.Info("producer workspaces get marketplace-publish through the `producer` type, or bind "+ + "it by hand to register BYO; consumers need nothing bound - enabling an offering is a "+ + "plain kcp APIBinding they create themselves", + "exportsPath", workspacePath, + "workspaceTypes", []string{bootstrap.WorkspaceTypeProvider}, + ) + return nil + }, + } + + cmd.Flags().StringVar(&kubeconfig, "kubeconfig", "", + "Path to the kubeconfig for the target kcp. Defaults to $KUBECONFIG.") + cmd.Flags().StringVar(&workspacePrefix, "workspace-prefix", bootstrap.DefaultWorkspacePrefix, + "Parent path the controllers workspace is created under.") + cmd.Flags().StringVar(&controllersWorkspace, "controllers-workspace", bootstrap.DefaultControllersWorkspace, + "Name of the workspace this component owns, created under --workspace-prefix. "+ + "Holds the APIExports, the WorkspaceTypes and the endpoint slices.") + cmd.Flags().StringVar(&catalogWorkspace, "catalog-workspace", bootstrap.DefaultCatalogWorkspace, + "Name of the workspace Provider records live in, created under --workspace-prefix "+ + "and bound to the Provider API. Empty skips creating it.") + cmd.Flags().StringVar(&producersWorkspace, "producers-workspace", bootstrap.DefaultProducersWorkspace, + "Name of the workspace provisioned producer workspaces are created under, bound to "+ + "the provisioner claim. Holds no marketplace objects. Empty skips creating it.") + cmd.Flags().StringVar(&workspaceType, "workspace-type", accessbootstrap.DefaultWorkspaceType, + "WorkspaceType for any workspace this creates.") + cmd.Flags().StringSliceVar(&serverUsers, "server-user", nil, + "Additional User to grant the server role to, repeatable. Needed when the operator "+ + "or the virtual workspace does not run as this bootstrap's own credential.") + cmd.Flags().StringSliceVar(&serverGroups, "server-group", nil, + "Additional Group to grant the server role to, repeatable.") + cmd.Flags().StringSliceVar(&adminUsers, "platform-admin-user", nil, + "User who may manage Producers in the catalog workspace, repeatable. Bound to a role "+ + "that allows exactly that; anyone left off the list on a later run loses it.") + cmd.Flags().StringSliceVar(&adminGroups, "platform-admin-group", nil, + "Group, as the identity provider asserts it, whose members may manage Producers, repeatable.") + cmd.Flags().DurationVar(&timeout, "timeout", 3*time.Minute, + "Overall time budget for installing and verifying.") + + return cmd +} diff --git a/marketplace/cmd/operator.go b/marketplace/cmd/operator.go new file mode 100644 index 0000000..a1a5e8e --- /dev/null +++ b/marketplace/cmd/operator.go @@ -0,0 +1,90 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package cmd + +import ( + "fmt" + + "github.com/spf13/cobra" + + genericapiserver "k8s.io/apiserver/pkg/server" + "k8s.io/client-go/tools/clientcmd" + + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/pkg/bootstrap" + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/pkg/operator" +) + +func newOperatorCommand() *cobra.Command { + var ( + kubeconfig string + workspacePath string + catalogPath string + producersPath string + bindUsers []string + bindGroups []string + ) + + cmd := &cobra.Command{ + Use: "operator", + Short: "Reconcile Providers into workspaces, and published APIExports into bind grants", + RunE: func(cmd *cobra.Command, _ []string) error { + if kubeconfig == "" { + return fmt.Errorf("--kubeconfig is required") + } + + cfg, err := clientcmd.BuildConfigFromFlags("", kubeconfig) + if err != nil { + return fmt.Errorf("load kubeconfig: %w", err) + } + if workspacePath == "" { + return fmt.Errorf("--workspace-path is required: it is where the exports and WorkspaceTypes live") + } + cfg.Host = retargetHost(cfg.Host, workspacePath) + + ctx := genericapiserver.SetupSignalContext() + return operator.Run(ctx, operator.Options{ + RestConfig: cfg, + ExportsPath: workspacePath, + CatalogPath: catalogPath, + ProducersPath: producersPath, + BindUsers: bindUsers, + BindGroups: bindGroups, + }) + }, + } + + cmd.Flags().StringVar(&kubeconfig, "kubeconfig", "", "Path to the kubeconfig for the target kcp (required).") + cmd.Flags().StringVar(&workspacePath, "workspace-path", + bootstrap.DefaultWorkspacePrefix+":"+bootstrap.DefaultControllersWorkspace, + "Workspace holding the marketplace APIExports, their endpoint slices and the "+ + "producer/consumer WorkspaceTypes.") + cmd.Flags().StringVar(&catalogPath, "catalog-workspace", + bootstrap.DefaultWorkspacePrefix+":"+bootstrap.DefaultCatalogWorkspace, + "Workspace Provider records live in.") + cmd.Flags().StringVar(&producersPath, "producers-workspace", + bootstrap.DefaultWorkspacePrefix+":"+bootstrap.DefaultProducersWorkspace, + "Workspace provisioned producer workspaces are created under. Deliberately not "+ + "the workspace Provider records live in.") + cmd.Flags().StringSliceVar(&bindUsers, "bind-user", nil, + "User the per-offering `bind` grants name: who may enable a published offering. Repeatable.") + cmd.Flags().StringSliceVar(&bindGroups, "bind-group", nil, + "Group the per-offering `bind` grants name. Repeatable. Both flags empty means "+ + "system:authenticated — any authenticated user may enable in a workspace their "+ + "own RBAC lets them bind in.") + + return cmd +} diff --git a/marketplace/cmd/root.go b/marketplace/cmd/root.go new file mode 100644 index 0000000..35c27db --- /dev/null +++ b/marketplace/cmd/root.go @@ -0,0 +1,59 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// Package cmd holds the marketplace binary's subcommands. +package cmd + +import ( + goflag "flag" + "strings" + + "github.com/spf13/cobra" + ctrllog "sigs.k8s.io/controller-runtime/pkg/log" + + "k8s.io/klog/v2" +) + +// Execute runs the marketplace binary. +func Execute() error { + ctrllog.SetLogger(klog.NewKlogr()) + + root := &cobra.Command{ + Use: "marketplace-vw", + Short: "A marketplace for kcp: producers, offerings and enablements as exports and bindings", + SilenceUsage: true, + SilenceErrors: false, + } + + klogFlags := goflag.NewFlagSet("klog", goflag.ContinueOnError) + klog.InitFlags(klogFlags) + root.PersistentFlags().AddGoFlagSet(klogFlags) + + root.AddCommand(newInitCommand()) + root.AddCommand(newOperatorCommand()) + root.AddCommand(newVirtualWorkspaceCommand()) + + return root.Execute() +} + +// retargetHost swaps the workspace path of a kcp cluster URL, keeping the +// scheme and host. +func retargetHost(host, workspacePath string) string { + if i := strings.Index(host, "/clusters/"); i >= 0 { + host = host[:i] + } + return strings.TrimSuffix(host, "/") + "/clusters/" + workspacePath +} diff --git a/marketplace/cmd/virtualworkspace.go b/marketplace/cmd/virtualworkspace.go new file mode 100644 index 0000000..14000da --- /dev/null +++ b/marketplace/cmd/virtualworkspace.go @@ -0,0 +1,43 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package cmd + +import ( + "github.com/spf13/cobra" + + genericapiserver "k8s.io/apiserver/pkg/server" + + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/pkg/server" +) + +func newVirtualWorkspaceCommand() *cobra.Command { + opts := server.NewOptions() + + cmd := &cobra.Command{ + Use: "virtualworkspace", + Aliases: []string{"vw"}, + Short: "Serve the catalog and enablements at /services/marketplace behind kcp's front-proxy", + RunE: func(cmd *cobra.Command, _ []string) error { + ctx := genericapiserver.SetupSignalContext() + return server.Run(ctx, opts) + }, + } + + opts.AddFlags(cmd.Flags()) + + return cmd +} diff --git a/marketplace/config/apiexport/apiexport-catalog.yaml b/marketplace/config/apiexport/apiexport-catalog.yaml new file mode 100644 index 0000000..1f1841f --- /dev/null +++ b/marketplace/config/apiexport/apiexport-catalog.yaml @@ -0,0 +1,16 @@ +# marketplace-catalog - the registry of Producer records. +# +# Bound by hand into the catalog workspace and nowhere else. It carries no +# claims: a Producer record is data, and the tier holding the records that +# say who may publish cannot reach into any workspace. +apiVersion: apis.kcp.io/v1alpha2 +kind: APIExport +metadata: + name: marketplace-catalog +spec: + resources: + - name: producers + group: marketplace.platform.kcp.io + schema: v261001-fbafaea.producers.marketplace.platform.kcp.io + storage: + crd: {} diff --git a/marketplace/config/apiexport/apiexport-provisioner.yaml b/marketplace/config/apiexport/apiexport-provisioner.yaml new file mode 100644 index 0000000..229bcd5 --- /dev/null +++ b/marketplace/config/apiexport/apiexport-provisioner.yaml @@ -0,0 +1,16 @@ +# marketplace-provisioner - the capability to CREATE PROVIDER WORKSPACES. +# +# Declares no resources; bound by hand into the producers parent and +# nowhere else. The identityHash names kcp's own tenancy.kcp.io export, +# discovered at install time - a claim on kcp's exported types without it +# is a different claim that never applies. +apiVersion: apis.kcp.io/v1alpha2 +kind: APIExport +metadata: + name: marketplace-provisioner +spec: + permissionClaims: + - group: tenancy.kcp.io + resource: workspaces + verbs: [get, list, watch, create, delete] + identityHash: __TENANCY_KCP_IO_IDENTITY_HASH__ diff --git a/marketplace/config/apiexport/apiexport-publish.yaml b/marketplace/config/apiexport/apiexport-publish.yaml new file mode 100644 index 0000000..0573e76 --- /dev/null +++ b/marketplace/config/apiexport/apiexport-publish.yaml @@ -0,0 +1,51 @@ +# marketplace-publish - the producer-side export. +# +# It serves NO resources: publishing is annotating an APIExport, so there +# is no marketplace object in a producer workspace and nothing to serve. +# What this export carries is the reach the publish flow needs inside one: +# +# - read apiexports, because an annotated export IS an offering: this is +# how one is noticed, read, and noticed again when un-annotated; +# - read their endpoint slices, to follow the exports that are published; +# - read apiresourceschemas, so the catalog can show what an offering +# serves - the schema a consumer gets by enabling it - before they do; +# - read the LogicalCluster, so the workspace's canonical path can be +# matched against the Producer record that names it (that match is how +# an external producer's workspace is recognized); +# - read ConfigMaps, which is how a producer ships "how to use this": an +# annotated export names one, and the catalog shows its sections to +# whoever enables it. Read-only, and the only thing read from it is +# the data a producer put there to be read; +# - write ClusterRoles and ClusterRoleBindings, to materialize the ONE +# grant publishing means: `bind` on the annotated export. Delete is +# load-bearing - removing the annotation revokes it. +# +# Binding this export IS a producer's consent: kcp auto-accepts these +# claims on binding, and deleting the binding revokes every one of them. +apiVersion: apis.kcp.io/v1alpha2 +kind: APIExport +metadata: + name: marketplace-publish +spec: + permissionClaims: + - group: apis.kcp.io + resource: apiexports + verbs: [get, list, watch] + - group: apis.kcp.io + resource: apiexportendpointslices + verbs: [get, list, watch] + - group: apis.kcp.io + resource: apiresourceschemas + verbs: [get, list, watch] + - group: core.kcp.io + resource: logicalclusters + verbs: [get, list, watch] + - group: "" + resource: configmaps + verbs: [get, list, watch] + - group: rbac.authorization.k8s.io + resource: clusterroles + verbs: [get, list, watch, create, update, delete] + - group: rbac.authorization.k8s.io + resource: clusterrolebindings + verbs: [get, list, watch, create, update, delete] diff --git a/marketplace/config/apiexport/apiexportendpointslices.yaml b/marketplace/config/apiexport/apiexportendpointslices.yaml new file mode 100644 index 0000000..38b404d --- /dev/null +++ b/marketplace/config/apiexport/apiexportendpointslices.yaml @@ -0,0 +1,25 @@ +# One slice per export. Each is a separate virtual workspace, and the +# operator runs one manager (or holds one client) per slice. +apiVersion: apis.kcp.io/v1alpha1 +kind: APIExportEndpointSlice +metadata: + name: marketplace-catalog +spec: + export: + name: marketplace-catalog +--- +apiVersion: apis.kcp.io/v1alpha1 +kind: APIExportEndpointSlice +metadata: + name: marketplace-publish +spec: + export: + name: marketplace-publish +--- +apiVersion: apis.kcp.io/v1alpha1 +kind: APIExportEndpointSlice +metadata: + name: marketplace-provisioner +spec: + export: + name: marketplace-provisioner diff --git a/marketplace/config/apiexport/apiresourceschema-producers.marketplace.platform.kcp.io.yaml b/marketplace/config/apiexport/apiresourceschema-producers.marketplace.platform.kcp.io.yaml new file mode 100644 index 0000000..3ccef5a --- /dev/null +++ b/marketplace/config/apiexport/apiresourceschema-producers.marketplace.platform.kcp.io.yaml @@ -0,0 +1,106 @@ +apiVersion: apis.kcp.io/v1alpha1 +kind: APIResourceSchema +metadata: + name: v261001-fbafaea.producers.marketplace.platform.kcp.io +spec: + group: marketplace.platform.kcp.io + names: + kind: Producer + listKind: ProducerList + plural: producers + singular: producer + scope: Cluster + versions: + - name: v1alpha1 + schema: + description: |- + Producer is the registration record: it says which workspace is allowed + to publish offerings under this name. It lives in the catalog workspace + and grants nothing by existing — the reach into a producer workspace + comes from the marketplace-publish binding there, never from this + record. + properties: + apiVersion: + description: |- + APIVersion defines the versioned schema of this representation of an object. + Servers should convert recognized schemas to the latest internal value, and + may reject unrecognized values. + More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + type: string + kind: + description: |- + Kind is a string value representing the REST resource this object represents. + Servers may infer this from the endpoint the client submits requests to. + Cannot be updated. + In CamelCase. + More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + type: string + metadata: + type: object + spec: + description: ProducerSpec is the desired state of a Producer. + properties: + description: + description: Description is free text for humans. + type: string + displayName: + description: DisplayName is the human name of the producer, shown in + the catalog. + minLength: 1 + type: string + mode: + description: Mode is provisioned or external. + enum: + - provisioned + - external + type: string + workspacePath: + description: |- + WorkspacePath is the canonical path of the producer's own workspace, + for mode external. Ignored for mode provisioned, where the operator + computes it. + type: string + required: + - displayName + - mode + type: object + status: + description: ProducerStatus is the observed state of a Producer. + properties: + message: + type: string + phase: + description: |- + Phase describes where a marketplace object is in its lifecycle. It is a + coarse, human-first signal; Message carries the detail when a phase is + not Ready. + type: string + url: + description: URL is the direct address of the producer's workspace, + when known. + type: string + workspace: + description: |- + Workspace is the name of the provisioned Workspace object, for mode + provisioned. + type: string + workspaceCluster: + description: |- + WorkspaceCluster is the logical cluster backing the producer's + workspace. For external producers it is learned when the first + Offering is published from that workspace. + type: string + workspacePath: + description: |- + WorkspacePath is the canonical path of the producer's workspace — + computed for provisioned, copied from spec for external. Offerings + bind against it. + type: string + type: object + required: + - spec + type: object + served: true + storage: true + subresources: + status: {} diff --git a/marketplace/config/apiexport/bootstrap.go b/marketplace/config/apiexport/bootstrap.go new file mode 100644 index 0000000..4a72f3e --- /dev/null +++ b/marketplace/config/apiexport/bootstrap.go @@ -0,0 +1,94 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// Package apiexport holds the kcp-side assets the marketplace component +// needs. +// +// The model is three APIExports across three tiers, one of which declares +// no resources at all — an export with no schemas is the "grant a +// capability, add no API" primitive: +// +// - marketplace-catalog Producers. Bound into the catalog workspace. +// - marketplace-publish no resources; the claims the publish flow +// needs in a producer workspace. Binding it IS a producer's consent. +// - marketplace-provisioner no resources; the claim to create producer +// workspaces. Bound into the producers parent only. +// +// Enabling an offering involves NO marketplace machinery in the consumer +// workspace: publishing materializes a `bind` grant on the producer's own +// export, and a consumer enables by creating a plain kcp APIBinding there +// themselves — governed by their workspace's RBAC and kcp's bind check, +// nothing else. +package apiexport + +import "embed" + +//go:embed *.yaml +var FS embed.FS + +// Placeholders substituted at apply time. None of them can be committed: +// the identity hash is per kcp install, and the export references depend on +// where the operator chose to install. +const ( + // IdentityHashPlaceholder is replaced with the identity of kcp's own + // tenancy.kcp.io APIExport, which a claim on `workspaces` must name. + IdentityHashPlaceholder = "__TENANCY_KCP_IO_IDENTITY_HASH__" + // ExportsRefPlaceholder is replaced with the logical cluster of the + // workspace holding these exports; WorkspaceType references resolve + // against it. + ExportsRefPlaceholder = "__EXPORTS_REF__" + // ExportsPathPlaceholder is replaced with that workspace's canonical + // path; APIBinding references and limitAllowedParents want paths. + ExportsPathPlaceholder = "__EXPORTS_PATH__" +) + +// ExportsOrder is the sequence the exports workspace's assets are applied +// in. It is load-bearing: +// +// - schemas before the exports that name them, or the export is rejected +// (the files are generated — `make generate` — and their kcp-style +// content-addressed names are what the export manifests reference); +// - the bind RBAC before the endpoint slices, because kcp gates slice +// creation on a `bind` verb the creator does not otherwise hold; +// - the workspace types after the exports they default-bind, so the +// references resolve. +var ExportsOrder = []string{ + "apiresourceschema-producers.marketplace.platform.kcp.io.yaml", + "apiexport-catalog.yaml", + "apiexport-publish.yaml", + "apiexport-provisioner.yaml", + "rbac-bind.yaml", + "workspacetypes.yaml", + "apiexportendpointslices.yaml", +} + +// CatalogOrder is applied into the catalog workspace: the registry of +// Producer records. It binds the Producer API and nothing else. +var CatalogOrder = []string{ + "catalog-bindings.yaml", +} + +// ProducersOrder is applied into the workspace provisioned producer +// workspaces are created under. It binds the capability to create them and +// nothing else. +// +// These two are the only tiers bound by hand, because nothing provisions +// them. Keeping them apart means a bug in the provisioning path cannot +// rewrite the records that drive it, and the record tier cannot create a +// workspace. +var ProducersOrder = []string{ + "producers-bindings.yaml", +} diff --git a/marketplace/config/apiexport/catalog-bindings.yaml b/marketplace/config/apiexport/catalog-bindings.yaml new file mode 100644 index 0000000..e61f686 --- /dev/null +++ b/marketplace/config/apiexport/catalog-bindings.yaml @@ -0,0 +1,16 @@ +# Applied into the CATALOG workspace: the registry of Producer records. +# It binds the Producer API and nothing else - the record tier cannot +# provision a workspace and cannot reach into anyone's. +apiVersion: apis.kcp.io/v1alpha2 +kind: APIBinding +metadata: + name: marketplace-catalog +spec: + reference: + export: + # The logical cluster id, not the pretty path: an APIBinding reference + # resolves ids locally on the shard, while pretty paths need the cache + # server's path index — which multi-shard deployments have broken + # before. The WorkspaceTypes reference exports the same way. + path: __EXPORTS_REF__ + name: marketplace-catalog diff --git a/marketplace/config/apiexport/producers-bindings.yaml b/marketplace/config/apiexport/producers-bindings.yaml new file mode 100644 index 0000000..c666431 --- /dev/null +++ b/marketplace/config/apiexport/producers-bindings.yaml @@ -0,0 +1,29 @@ +# Applied into the PROVIDERS workspace: the parent provisioned producer +# workspaces are created under. It binds only the capability to create +# them - no marketplace API is servable here, so a bug in provisioning +# cannot reach the records that drive it. +apiVersion: apis.kcp.io/v1alpha2 +kind: APIBinding +metadata: + name: marketplace-provisioner +spec: + reference: + export: + # The logical cluster id, not the pretty path: an APIBinding reference + # resolves ids locally on the shard, while pretty paths need the cache + # server's path index — which multi-shard deployments have broken + # before. The WorkspaceTypes reference exports the same way. + path: __EXPORTS_REF__ + name: marketplace-provisioner + permissionClaims: + - group: tenancy.kcp.io + resource: workspaces + verbs: [get, list, watch, create, delete] + # MUST match the identityHash on the export's claim; kcp compares + # claims by (group, resource, identityHash), and a mismatch leaves + # the claim exported-but-never-applied while the binding still + # reports Bound. + identityHash: __TENANCY_KCP_IO_IDENTITY_HASH__ + state: Accepted + selector: + matchAll: true diff --git a/marketplace/config/apiexport/rbac-bind.yaml b/marketplace/config/apiexport/rbac-bind.yaml new file mode 100644 index 0000000..98a1448 --- /dev/null +++ b/marketplace/config/apiexport/rbac-bind.yaml @@ -0,0 +1,63 @@ +# Who may BIND these exports. Applied into the workspace that hosts them. +# +# kcp gates APIBinding and APIExportEndpointSlice creation on a `bind` verb +# against the APIExport, evaluated in the EXPORT's own workspace, and +# cluster-admin does not satisfy it. Open to system:authenticated because a +# claim only takes effect once the consumer accepts it; a deployment +# wanting the exports restricted replaces the subject. +# +# The PROVIDER exports a consumer actually enables are not listed here: +# `bind` on those is materialized per published export, in the producer's +# own workspace, by the publish reconciler — and revoked when the publish +# annotation is removed. +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: system:kcp:apiexport:marketplace:bind +rules: + - apiGroups: ["apis.kcp.io"] + resources: ["apiexports"] + resourceNames: + - marketplace-catalog + - marketplace-publish + - marketplace-provisioner + verbs: ["bind"] +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: system:kcp:authenticated:apiexport:marketplace:bind +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: system:kcp:apiexport:marketplace:bind +subjects: + - apiGroup: rbac.authorization.k8s.io + kind: Group + name: system:authenticated +--- +# The `producer` WorkspaceType is referenced from Workspace objects created +# in other logical clusters; kcp gates that on a `use` verb against the +# type, in the type's own workspace. +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: system:kcp:workspacetype:marketplace:use +rules: + - apiGroups: ["tenancy.kcp.io"] + resources: ["workspacetypes"] + resourceNames: ["producer"] + verbs: ["use"] +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: system:kcp:authenticated:workspacetype:marketplace:use +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: system:kcp:workspacetype:marketplace:use +subjects: + - apiGroup: rbac.authorization.k8s.io + kind: Group + name: system:authenticated diff --git a/marketplace/config/apiexport/workspacetypes.yaml b/marketplace/config/apiexport/workspacetypes.yaml new file mode 100644 index 0000000..a76bf1d --- /dev/null +++ b/marketplace/config/apiexport/workspacetypes.yaml @@ -0,0 +1,27 @@ +# The one workspace shape the marketplace provisions. Its +# defaultAPIBindings are what make the system claim-based: kcp's +# default-apibinding controller copies every claim off the referenced +# export into the binding it creates, already Accepted with matchAll. +apiVersion: tenancy.kcp.io/v1alpha1 +kind: WorkspaceType +metadata: + name: producer +spec: + # DELIBERATELY no `extend: root:universal`: universal would pull + # tenancy.kcp.io (Workspace, WorkspaceType) and topology.kcp.io into the + # producer's API surface, letting a producer spawn arbitrary child + # workspaces and inspect cluster topology. Both are platform surfaces. A + # producer's business is apis.kcp.io — schemas, its own APIExport — and + # that group is a kcp system API, served in every logical cluster + # without any binding. + # + # marketplace-publish is the registration consent: annotated APIExports become + # publishable here, and the operator gains exactly the claims that + # export declares — nothing else is bound into a producer workspace. + # + # There is no `consumer` type: enabling an offering is a plain kcp + # APIBinding a consumer creates in their own workspace, so the + # marketplace has NO footprint there at all. + defaultAPIBindings: + - export: marketplace-publish + path: __EXPORTS_REF__ diff --git a/marketplace/config/examples/README.md b/marketplace/config/examples/README.md new file mode 100644 index 0000000..192c9c2 --- /dev/null +++ b/marketplace/config/examples/README.md @@ -0,0 +1,65 @@ +# Example offerings + +A producer and two offerings, for a development stack. Applying them is +the shortest path from an empty catalog to something you can browse and +enable. + +| File | Applied to | What it is | +|---|---|---| +| `producer.yaml` | the catalog workspace | the `Producer` record — registration, and nothing else | +| `things.yaml` | the producer's workspace | a schema and a published export, with a claim on configmaps | +| `things-instructions.yaml` | the producer's workspace | the "how to use this" the console shows after enabling `things` | +| `widgets.yaml` | the producer's workspace | the same, claiming nothing | + +The two exports are the two shapes worth seeing. `things` carries a +`permissionClaim`, so its catalog entry has a consent form and a revision +identifying it. `widgets` carries none, so enabling it asks for nothing in +the consumer's workspace and its entry has neither. + +Note that neither file contains an offering object, because there is no +such kind. The annotations on the `APIExport` are the offering: + +```yaml +metadata: + annotations: + marketplace.kcp.hub/publish: "true" + marketplace.kcp.hub/display-name: Things as a service + marketplace.kcp.hub/description: One Thing per workspace, batteries included. +``` + +Only the exact string `"true"` publishes; anything else leaves the export +off the catalog. Removing the annotation takes it off again and revokes +the `bind` grant, without touching the export or anyone already bound. + +## Applying them + +Under Tilt, on demand: + +```sh +tilt trigger marketplace-examples +``` + +Or directly, against any running marketplace: + +```sh +KUBECONFIG=.tilt/tilt-contrib.kubeconfig marketplace/config/examples/apply.sh +``` + +`apply.sh` is idempotent, so editing an example and re-triggering is the +development loop. It is a script rather than one `kubectl apply -f` +because the two halves go to different workspaces, and the producer's +workspace does not exist until the operator has read the record. + +Then: + +```sh +bin/contribctl offers +bin/contribctl enable acme.things.acme.example +``` + +Both schemas declare `additionalPrinterColumns`, which is what makes them +presentable to any client that asks for a Table — `kubectl get things` +shows MESSAGE and AGE, and so does the web console, from the same +declaration. `widgets` also carries a `priority: 1` column, so it appears +only under `-o wide` (and behind the console's "wide" toggle): the two +examples between them cover both cases. diff --git a/marketplace/config/examples/apply.sh b/marketplace/config/examples/apply.sh new file mode 100755 index 0000000..b8fa984 --- /dev/null +++ b/marketplace/config/examples/apply.sh @@ -0,0 +1,94 @@ +#!/usr/bin/env bash + +# Copyright 2026 The kcp Authors. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Publishes the example offerings into a running marketplace. +# +# Two workspaces are involved and they are not interchangeable, which is +# why this is a script rather than one `kubectl apply -f`: the Producer +# record is registration and belongs to the catalog, while the exports are +# the offerings themselves and belong to the producer's own workspace — +# which does not exist until the operator has read the record. +# +# Idempotent: re-running re-applies, so editing an example and triggering +# it again is the development loop. + +set -euo pipefail + +KUBECONFIG_FILE="${KUBECONFIG:?KUBECONFIG must point at a kcp admin kubeconfig}" +SERVER="${KCP_FRONT_PROXY_URL:-https://kcp.localhost:8443}" +CATALOG="${MARKETPLACE_CATALOG_WORKSPACE:-root:marketplace:catalog}" +TIMEOUT="${TIMEOUT_SECONDS:-120}" +HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + +kube() { kubectl --kubeconfig "$KUBECONFIG_FILE" --server "$1" "${@:2}"; } + +echo "==> registering producer acme in $CATALOG" +kube "$SERVER/clusters/$CATALOG" apply -f "$HERE/producer.yaml" + +# The operator provisions the workspace and reports its path back on the +# record. Waiting for the path rather than for a phase is deliberate: the +# path is the thing the next step actually needs. +echo "==> waiting for the operator to provision acme's workspace" +deadline=$((SECONDS + TIMEOUT)) +while :; do + path="$(kube "$SERVER/clusters/$CATALOG" get producer acme \ + -o jsonpath='{.status.workspacePath}' 2>/dev/null || true)" + phase="$(kube "$SERVER/clusters/$CATALOG" get producer acme \ + -o jsonpath='{.status.phase}' 2>/dev/null || true)" + [ -n "$path" ] && break + if [ "$SECONDS" -ge "$deadline" ]; then + echo "producer acme has no workspace after ${TIMEOUT}s (phase: ${phase:-none})." >&2 + echo "Is marketplace-operator running?" >&2 + exit 1 + fi + sleep 2 +done +echo " $path" + +PROVIDER_WS="$SERVER/clusters/$path" + +# The APIExport references a schema by name, so the schema has to land +# first; both files carry both, in that order. +for example in things things-instructions widgets; do + echo "==> publishing $example into $path" + kube "$PROVIDER_WS" apply -f "$HERE/$example.yaml" +done + +# Publishing materializes exactly one thing, and it is the only observable +# effect there is to wait for: `bind` on that export. No annotation, no +# grant; no grant, nobody can enable it. +echo "==> waiting for the bind grants" +deadline=$((SECONDS + TIMEOUT)) +for export_name in things.acme.example widgets.acme.example; do + while ! kube "$PROVIDER_WS" get clusterrole "marketplace:bind:$export_name" >/dev/null 2>&1; do + if [ "$SECONDS" -ge "$deadline" ]; then + echo "no bind grant for $export_name after ${TIMEOUT}s." >&2 + echo "The operator only grants it for a workspace a Producer record names." >&2 + exit 1 + fi + sleep 2 + done + echo " marketplace:bind:$export_name" +done + +echo +echo "published. browse the catalog with:" +echo " kubectl --kubeconfig $KUBECONFIG_FILE get --raw \\" +echo " $SERVER/services/marketplace/apis/marketplace.platform.kcp.io/v1alpha1/offerings" +echo +echo "or enable one as yourself:" +echo " bin/contribctl offers" +echo " bin/contribctl enable acme.things.acme.example" diff --git a/marketplace/config/examples/producer.yaml b/marketplace/config/examples/producer.yaml new file mode 100644 index 0000000..3ff612b --- /dev/null +++ b/marketplace/config/examples/producer.yaml @@ -0,0 +1,15 @@ +# The registration record, applied to the CATALOG workspace. +# +# It grants nothing by existing. What it does is say which workspace may +# publish under the name "acme" — and for mode: provisioned, ask the +# operator to create that workspace with the `producer` WorkspaceType, +# which carries the marketplace-publish binding that is the producer's +# whole surface. +apiVersion: marketplace.platform.kcp.io/v1alpha1 +kind: Producer +metadata: + name: acme +spec: + displayName: Acme + description: Example producer, published by the marketplace-examples job. + mode: provisioned diff --git a/marketplace/config/examples/things-instructions.yaml b/marketplace/config/examples/things-instructions.yaml new file mode 100644 index 0000000..abf7227 --- /dev/null +++ b/marketplace/config/examples/things-instructions.yaml @@ -0,0 +1,49 @@ +# The example's "how to use this", applied to the PRODUCER's workspace +# next to the export that names it. Short on purpose: the point of the +# example is to show the shape, not to document Things. +# +# The namespace is part of the example because a provisioned producer +# workspace starts without one: the operator creates the workspace and +# nothing else, and a ConfigMap cannot be created into a namespace that +# is not there. The marketplace reads the ConfigMap by name whatever its +# namespace, so which one is the producer's choice. +apiVersion: v1 +kind: Namespace +metadata: + name: default +--- +apiVersion: v1 +kind: ConfigMap +metadata: + name: things-instructions + namespace: default +data: + 00-overview.md: | + # Things + + Enabling binds `things.acme.example` into `{{tenant}}/{{project}}`, + where it is an ordinary API. One Thing is one object with a message. + + 10-kubectl.md: | + # kubectl + + Point a kubeconfig at the project and create one: + + ```sh + kubectl --server {{workspace}} apply -f - <\033[0m %s\n' "$*"; } +die() { printf '\033[1;31mERR\033[0m %s\n' "$*" >&2; exit 1; } + +### diagnostics and teardown ################################################## + +dump_diagnostics() { + echo + echo "===== e2e diagnostics =====" + for name in kcp init operator vw; do + if [[ -f "${LOG_DIR}/${name}.log" ]]; then + echo "----- ${name} (last 80 lines) -----" + tail -n 80 "${LOG_DIR}/${name}.log" || true + fi + done + echo "===== end diagnostics =====" + echo +} + +stop_all() { + [[ -d "${RUN_DIR}" ]] || return 0 + for pidfile in "${RUN_DIR}"/*.pid; do + [[ -f "${pidfile}" ]] || continue + local name pid + name="$(basename "${pidfile}" .pid)" + pid="$(cat "${pidfile}")" + if kill -0 "${pid}" 2>/dev/null; then + log "stopping ${name} (pid ${pid})" + kill "${pid}" 2>/dev/null || true + # These pids may be from an earlier invocation, so poll rather than + # `wait`, and make sure ports are really free. + for _ in $(seq 1 30); do + kill -0 "${pid}" 2>/dev/null || break + sleep 1 + done + if kill -0 "${pid}" 2>/dev/null; then + log "killing ${name} (pid ${pid}) forcefully" + kill -9 "${pid}" 2>/dev/null || true + sleep 1 + fi + fi + rm -f "${pidfile}" + done +} + +teardown() { + local code=$? + if [[ ${code} -ne 0 ]]; then + dump_diagnostics + fi + if [[ "${NO_TEARDOWN}" == "true" ]]; then + log "NO_TEARDOWN is set, leaving everything running (KUBECONFIG=${KCP_ROOT_DIR}/admin.kubeconfig)" + return + fi + stop_all +} + +start_bg() { # name, then command + local name=$1; shift + mkdir -p "${LOG_DIR}" "${RUN_DIR}" + "$@" >"${LOG_DIR}/${name}.log" 2>&1 & + echo $! >"${RUN_DIR}/${name}.pid" + log "started ${name} (pid $(cat "${RUN_DIR}/${name}.pid")), logging to ${LOG_DIR}/${name}.log" +} + +require_alive() { # name + local pidfile="${RUN_DIR}/$1.pid" + [[ -f "${pidfile}" ]] || die "$1 was never started" + kill -0 "$(cat "${pidfile}")" 2>/dev/null || die "$1 died, see ${LOG_DIR}/$1.log" +} + +### preflight ################################################################# + +for tool in go curl openssl kubectl; do + command -v "${tool}" >/dev/null 2>&1 || die "${tool} is required but not installed" +done + +mkdir -p "${WORK_DIR}" "${LOG_DIR}" "${RUN_DIR}" "${PKI_DIR}" +stop_all +# Every run gets a fresh kcp: a leftover root directory makes kcp replay +# the previous teardown before becoming ready. The PKI is reusable. +rm -rf "${KCP_ROOT_DIR}" +trap teardown EXIT + +for port_and_name in "${KCP_PORT}:kcp" "${VW_PORT}:virtual workspace" \ + "${ETCD_CLIENT_PORT}:etcd client" "${ETCD_PEER_PORT}:etcd peer"; do + port=${port_and_name%%:*} + if lsof -nP -iTCP:"${port}" -sTCP:LISTEN >/dev/null 2>&1; then + lsof -nP -iTCP:"${port}" -sTCP:LISTEN 2>/dev/null | tail -n +2 >&2 + die "port ${port} (${port_and_name#*:}) is already in use" + fi +done + +if [[ "${SKIP_BUILD}" != "true" ]]; then + log "building the marketplace binary" + make --no-print-directory -C "${MONOREPO_ROOT}" build-marketplace BIN_DIR="${REPO_ROOT}/bin" + + if [[ ! -x "${KCP_BIN}" ]]; then + if [[ -n "${KCP_IMAGE}" ]]; then + [[ "$(uname -s)" == "Linux" ]] || die "KCP_IMAGE only works on Linux; use KCP_DIR to build from a checkout." + command -v docker >/dev/null 2>&1 || die "docker is required to extract kcp from ${KCP_IMAGE}" + log "extracting kcp from ${KCP_IMAGE}" + docker pull --quiet "${KCP_IMAGE}" >/dev/null + container="$(docker create "${KCP_IMAGE}")" + mkdir -p "$(dirname "${KCP_BIN}")" + docker cp "${container}:/kcp" "${KCP_BIN}" >/dev/null + docker rm --force "${container}" >/dev/null + chmod +x "${KCP_BIN}" + else + [[ -d "${KCP_DIR}" ]] || die "no kcp checkout at ${KCP_DIR}; set KCP_DIR=/path/to/kcp, or KCP_IMAGE on Linux" + log "building kcp from ${KCP_DIR}" + go build -C "${KCP_DIR}" -o "${KCP_BIN}" ./cmd/kcp + fi + fi +fi + +[[ -x "${KCP_BIN}" ]] || die "no kcp binary at ${KCP_BIN}" +MARKETPLACE_BIN="${REPO_ROOT}/bin/marketplace-vw" +[[ -x "${MARKETPLACE_BIN}" ]] || die "no marketplace binary at ${MARKETPLACE_BIN}" + +### PKI ####################################################################### + +# The virtual workspace authenticates callers by client certificate against +# this throwaway CA: CN becomes the username, O the groups. The PKI is +# reused between runs, so expiry is checked rather than only existence. +PKI_VALID_DAYS="${PKI_VALID_DAYS:-30}" +if [[ ! -f "${PKI_DIR}/alice.crt" ]] || ! openssl x509 -in "${PKI_DIR}/ca.crt" -checkend 3600 >/dev/null 2>&1; then + log "generating a client CA and user certificates (valid ${PKI_VALID_DAYS} days)" + rm -f "${PKI_DIR}"/*.crt "${PKI_DIR}"/*.key "${PKI_DIR}"/*.csr "${PKI_DIR}"/*.srl + + openssl req -x509 -newkey rsa:2048 -nodes -days "${PKI_VALID_DAYS}" \ + -keyout "${PKI_DIR}/ca.key" -out "${PKI_DIR}/ca.crt" \ + -subj "/CN=marketplace-e2e-ca" >>"${LOG_DIR}/pki.log" 2>&1 + + for spec in "alice:team-a" "bob:team-b"; do + user="${spec%%:*}"; group="${spec#*:}" + openssl req -newkey rsa:2048 -nodes \ + -keyout "${PKI_DIR}/${user}.key" -out "${PKI_DIR}/${user}.csr" \ + -subj "/CN=${user}/O=${group}" >>"${LOG_DIR}/pki.log" 2>&1 + openssl x509 -req -in "${PKI_DIR}/${user}.csr" \ + -CA "${PKI_DIR}/ca.crt" -CAkey "${PKI_DIR}/ca.key" -CAcreateserial \ + -days "${PKI_VALID_DAYS}" -out "${PKI_DIR}/${user}.crt" >>"${LOG_DIR}/pki.log" 2>&1 + done +fi + +### kcp ####################################################################### + +log "starting kcp on :${KCP_PORT}" +start_bg kcp "${KCP_BIN}" start \ + --root-directory="${KCP_ROOT_DIR}" \ + --secure-port="${KCP_PORT}" \ + --embedded-etcd-client-port="${ETCD_CLIENT_PORT}" \ + --embedded-etcd-peer-port="${ETCD_PEER_PORT}" \ + --client-ca-file="${PKI_DIR}/ca.crt" \ + --v="${KCP_V:-2}" + +KUBECONFIG_PATH="${KCP_ROOT_DIR}/admin.kubeconfig" + +log "waiting for kcp to be ready" +ready=false +for _ in $(seq 1 180); do + require_alive kcp + if [[ -f "${KUBECONFIG_PATH}" ]] && \ + kubectl --kubeconfig "${KUBECONFIG_PATH}" get --raw /readyz >/dev/null 2>&1; then + ready=true + break + fi + sleep 1 +done +[[ "${ready}" == "true" ]] || die "kcp did not become ready, see ${LOG_DIR}/kcp.log" + +### init (twice: the second run is the idempotency check) ##################### + +log "installing the marketplace APIExports (twice, for idempotency)" +"${MARKETPLACE_BIN}" init --kubeconfig "${KUBECONFIG_PATH}" >"${LOG_DIR}/init.log" 2>&1 \ + || { cat "${LOG_DIR}/init.log" >&2; die "init failed"; } +"${MARKETPLACE_BIN}" init --kubeconfig "${KUBECONFIG_PATH}" >>"${LOG_DIR}/init.log" 2>&1 \ + || { cat "${LOG_DIR}/init.log" >&2; die "second init failed; it must be idempotent"; } + +### operator and virtual workspace ############################################ + +log "starting the marketplace operator" +start_bg operator "${MARKETPLACE_BIN}" operator \ + --kubeconfig "${KUBECONFIG_PATH}" \ + --workspace-path root:marketplace:controllers \ + --catalog-workspace root:marketplace:catalog \ + --producers-workspace root:marketplace:producers \ + --v=4 + +log "starting the marketplace virtual workspace on :${VW_PORT}" +start_bg vw "${MARKETPLACE_BIN}" virtualworkspace \ + --kubeconfig "${KUBECONFIG_PATH}" \ + --workspace-path root:marketplace:controllers \ + --secure-port "${VW_PORT}" \ + --client-ca-file "${PKI_DIR}/ca.crt" \ + --requestheader-client-ca-file "${PKI_DIR}/ca.crt" \ + `# Same CA on both flags, so the server insists on knowing which cert` \ + `# names may set identity headers. No minted cert carries this name.` \ + --requestheader-allowed-names marketplace-front-proxy \ + --v=4 + +log "waiting for the virtual workspace to serve" +vw_ready=false +for _ in $(seq 1 60); do + require_alive vw + if curl -ks "https://localhost:${VW_PORT}/readyz" | grep -q ok; then + vw_ready=true + break + fi + sleep 1 +done +[[ "${vw_ready}" == "true" ]] || die "virtual workspace did not become ready, see ${LOG_DIR}/vw.log" + +### tests ##################################################################### + +require_alive kcp +require_alive operator +require_alive vw + +export KUBECONFIG="${KUBECONFIG_PATH}" +export MARKETPLACE_VW_URL="https://localhost:${VW_PORT}" +export MARKETPLACE_PKI_DIR="${PKI_DIR}" +export NO_TEARDOWN + +WHAT="${WHAT:-./test/e2e/...}" +TEST_ARGS="${TEST_ARGS:--timeout 20m -v}" + +log "running e2e tests: ${WHAT}" +# shellcheck disable=SC2086 +go test -tags e2e -count=1 ${TEST_ARGS} ${WHAT} + +log "e2e tests passed" diff --git a/marketplace/hack/ci/run-spike.sh b/marketplace/hack/ci/run-spike.sh new file mode 100755 index 0000000..039967c --- /dev/null +++ b/marketplace/hack/ci/run-spike.sh @@ -0,0 +1,95 @@ +#!/usr/bin/env bash + +# Spike #1 from ../DESIGN.md: prove the binder composition against a real +# kcp — an identity holding only the apibindings claim in a consumer +# workspace and a granted `bind` in one provider workspace can enable that +# provider's export there, and only that one. +# +# Nothing is built; there is no component binary yet. This starts kcp, +# mints the operator identity as a client certificate, and runs the test. +# +# Environment: +# KCP_BIN kcp binary (default: ../../kcp/bin/kcp relative to repo root) +# KCP_PORT default 7643; etcd on 7639/7640 + +set -euo pipefail + +REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)" +KCP_BIN="${KCP_BIN:-${REPO_ROOT}/../kcp/bin/kcp}" +KCP_PORT="${KCP_PORT:-7643}" +ETCD_CLIENT_PORT="${ETCD_CLIENT_PORT:-7639}" +ETCD_PEER_PORT="${ETCD_PEER_PORT:-7640}" + +WORK="${REPO_ROOT}/marketplace/.e2e-spike" +LOG_DIR="${WORK}/logs" +PKI_DIR="${WORK}/pki" +KCP_ROOT_DIR="${WORK}/.kcp" + +log() { echo -e "\033[1;32m==>\033[0m $*"; } +die() { echo -e "\033[1;31mERROR:\033[0m $*" >&2; exit 1; } + +[[ -x "${KCP_BIN}" ]] || die "no kcp binary at ${KCP_BIN}; set KCP_BIN or build ../kcp" + +rm -rf "${WORK}" +mkdir -p "${LOG_DIR}" "${PKI_DIR}" + +pids=() +stop_all() { + for pid in "${pids[@]:-}"; do kill "${pid}" 2>/dev/null || true; done + for _ in $(seq 1 20); do + local alive=false + for pid in "${pids[@]:-}"; do kill -0 "${pid}" 2>/dev/null && alive=true; done + [[ "${alive}" == "false" ]] && return + sleep 0.5 + done + for pid in "${pids[@]:-}"; do kill -9 "${pid}" 2>/dev/null || true; done +} +trap stop_all EXIT + +log "minting the operator identity (CN=mkt-operator)" +openssl req -x509 -newkey rsa:2048 -nodes -days 7 \ + -keyout "${PKI_DIR}/ca.key" -out "${PKI_DIR}/ca.crt" \ + -subj "/CN=marketplace-spike-ca" >"${LOG_DIR}/pki.log" 2>&1 +openssl req -newkey rsa:2048 -nodes \ + -keyout "${PKI_DIR}/mkt-operator.key" -out "${PKI_DIR}/mkt-operator.csr" \ + -subj "/CN=mkt-operator" >>"${LOG_DIR}/pki.log" 2>&1 +openssl x509 -req -in "${PKI_DIR}/mkt-operator.csr" \ + -CA "${PKI_DIR}/ca.crt" -CAkey "${PKI_DIR}/ca.key" -CAcreateserial \ + -days 7 -out "${PKI_DIR}/mkt-operator.crt" >>"${LOG_DIR}/pki.log" 2>&1 + +log "starting kcp on :${KCP_PORT}" +"${KCP_BIN}" start \ + --root-directory="${KCP_ROOT_DIR}" \ + --secure-port="${KCP_PORT}" \ + --embedded-etcd-client-port="${ETCD_CLIENT_PORT}" \ + --embedded-etcd-peer-port="${ETCD_PEER_PORT}" \ + --client-ca-file="${PKI_DIR}/ca.crt" \ + --v=2 >"${LOG_DIR}/kcp.log" 2>&1 & +pids+=($!) + +KUBECONFIG_PATH="${KCP_ROOT_DIR}/admin.kubeconfig" +log "waiting for kcp to be ready" +ready=false +for _ in $(seq 1 180); do + kill -0 "${pids[0]}" 2>/dev/null || die "kcp exited, see ${LOG_DIR}/kcp.log" + if [[ -f "${KUBECONFIG_PATH}" ]] && \ + kubectl --kubeconfig "${KUBECONFIG_PATH}" get --raw /readyz >/dev/null 2>&1; then + ready=true + break + fi + sleep 1 +done +[[ "${ready}" == "true" ]] || die "kcp did not become ready, see ${LOG_DIR}/kcp.log" + +log "running the spike" +export KUBECONFIG="${KUBECONFIG_PATH}" +export MKT_PKI_DIR="${PKI_DIR}" +cd "${REPO_ROOT}" +go test -tags e2e -count=1 -timeout 10m -v ./marketplace/test/spike/... 2>&1 | tee "${LOG_DIR}/test.log" +result=${PIPESTATUS[0]} + +if [[ "${result}" == "0" ]]; then + log "spike PASSED" +else + die "spike failed, logs in ${LOG_DIR}" +fi diff --git a/marketplace/main.go b/marketplace/main.go new file mode 100644 index 0000000..57e04c9 --- /dev/null +++ b/marketplace/main.go @@ -0,0 +1,35 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// 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. One binary so a +// deployment's init container and both long-running processes share a +// single image. +package main + +import ( + "os" + + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/cmd" +) + +func main() { + if err := cmd.Execute(); err != nil { + os.Exit(1) + } +} diff --git a/marketplace/pkg/bootstrap/bootstrap.go b/marketplace/pkg/bootstrap/bootstrap.go new file mode 100644 index 0000000..691ee77 --- /dev/null +++ b/marketplace/pkg/bootstrap/bootstrap.go @@ -0,0 +1,528 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// 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). +// +// Workspace-path plumbing is shared with the access component +// (access/pkg/bootstrap); this package only owns the marketplace assets. +package bootstrap + +import ( + "bytes" + "context" + "fmt" + "strings" + "time" + + rbacv1 "k8s.io/api/rbac/v1" + apierrors "k8s.io/apimachinery/pkg/api/errors" + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + "k8s.io/apimachinery/pkg/apis/meta/v1/unstructured" + "k8s.io/apimachinery/pkg/runtime/schema" + "k8s.io/apimachinery/pkg/util/wait" + "k8s.io/apimachinery/pkg/util/yaml" + "k8s.io/client-go/discovery" + "k8s.io/client-go/discovery/cached/memory" + "k8s.io/client-go/dynamic" + "k8s.io/client-go/kubernetes" + "k8s.io/client-go/rest" + "k8s.io/client-go/restmapper" + "k8s.io/client-go/util/retry" + "k8s.io/klog/v2" + + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/config/apiexport" + marketplacev1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1" +) + +// The three exports. Each has an endpoint slice of the same name, and the +// operator runs one manager (or holds one client) per slice. Nothing is +// exported into consumer workspaces: enabling is a plain kcp APIBinding +// the consumer creates, so the marketplace has no footprint there. +const ( + // ExportCatalog serves Producers in the catalog workspace. + ExportCatalog = "marketplace-catalog" + // ExportPublish serves no resources; it carries the claims the publish + // flow needs in producer workspaces, with the + // publish-side claims. + ExportPublish = "marketplace-publish" + // ExportProvisioner grants the claim to create producer workspaces. + ExportProvisioner = "marketplace-provisioner" +) + +// The workspace type the operator provisions producer workspaces with. It +// deliberately does not extend root:universal, so a producer workspace +// serves apis.kcp.io and the kcp built-ins but neither tenancy.kcp.io nor +// topology.kcp.io. +const ( + WorkspaceTypeProvider = "producer" +) + +// Defaults for where things are installed. +const ( + DefaultWorkspacePrefix = "root:marketplace" + DefaultControllersWorkspace = "controllers" + + // DefaultCatalogWorkspace is the registry: the workspace Producer + // records live in. Deliberately not the workspace producers are + // provisioned under. + DefaultCatalogWorkspace = "catalog" + + // DefaultProducersWorkspace is the provisioning parent: every + // provisioned producer workspace is created as its child. It holds no + // marketplace objects at all. + DefaultProducersWorkspace = "producers" +) + +// Options configures Bootstrap. +type Options struct { + // ServerUsers and ServerGroups are additional identities granted the + // server role in the exports workspace — the identities the operator + // and the virtual workspace authenticate as when they are not this + // bootstrap's own credential. + ServerUsers []string + ServerGroups []string +} + +// Result reports what Bootstrap installed. +type Result struct { + // ExportsPath is the canonical path of the workspace holding the + // exports, and ExportsCluster its logical cluster name. + ExportsPath string + ExportsCluster string + // WorkspacesIdentityHash is the identity of kcp's tenancy.kcp.io + // export, which every claim on `workspaces` must repeat. + WorkspacesIdentityHash string +} + +// Bootstrap applies the exports workspace's assets into the workspace cfg +// points at. Idempotent: safe to run on every pod start and every upgrade. +func Bootstrap(ctx context.Context, cfg *rest.Config, exportsPath string, opts Options) (*Result, error) { + logger := klog.FromContext(ctx) + + dyn, err := dynamic.NewForConfig(cfg) + if err != nil { + return nil, fmt.Errorf("build dynamic client: %w", err) + } + disc, err := discovery.NewDiscoveryClientForConfig(cfg) + if err != nil { + return nil, fmt.Errorf("build discovery client: %w", err) + } + cache := memory.NewMemCacheClient(disc) + mapper := restmapper.NewDeferredDiscoveryRESTMapper(cache) + + // A claim on kcp's own exported types must name that export's identity, + // and the hash is per install, so it is discovered rather than + // committed. + hash, err := exportIdentityHash(ctx, cfg, "root", "tenancy.kcp.io") + if err != nil { + return nil, fmt.Errorf("discover the identity hash of kcp's tenancy.kcp.io export: %w", err) + } + + cluster, err := logicalClusterName(ctx, dyn) + if err != nil { + return nil, fmt.Errorf("resolve the logical cluster of %s: %w", exportsPath, err) + } + + subs := map[string]string{ + apiexport.IdentityHashPlaceholder: hash, + apiexport.ExportsRefPlaceholder: cluster, + apiexport.ExportsPathPlaceholder: exportsPath, + } + + logger.Info("installing the marketplace APIExports", + "assets", len(apiexport.ExportsOrder), "workspace", exportsPath) + if err := applyAll(ctx, dyn, mapper, cache, apiexport.ExportsOrder, subs); err != nil { + return nil, err + } + + if len(opts.ServerUsers)+len(opts.ServerGroups) > 0 { + kube, err := kubernetes.NewForConfig(cfg) + if err != nil { + return nil, fmt.Errorf("build kubernetes client: %w", err) + } + if err := applyServerIdentity(ctx, kube, opts.ServerUsers, opts.ServerGroups); err != nil { + return nil, fmt.Errorf("grant server identities: %w", err) + } + } + + return &Result{ + ExportsPath: exportsPath, + ExportsCluster: cluster, + WorkspacesIdentityHash: hash, + }, nil +} + +// BindCatalog makes the workspace cfg points at the Producer registry: it +// binds marketplace-catalog, then waits until Producers are servable. +func BindCatalog(ctx context.Context, cfg *rest.Config, result *Result) error { + if err := applyTier(ctx, cfg, result, apiexport.CatalogOrder); err != nil { + return err + } + + dyn, err := dynamic.NewForConfig(cfg) + if err != nil { + return fmt.Errorf("build dynamic client: %w", err) + } + klog.FromContext(ctx).Info("waiting for the Producer API to become servable in the catalog workspace") + providersGVR := schema.GroupVersionResource{ + Group: marketplacev1alpha1.GroupName, Version: "v1alpha1", Resource: "producers", + } + if err := wait.PollUntilContextTimeout(ctx, 2*time.Second, time.Minute, true, func(ctx context.Context) (bool, error) { + if _, err := dyn.Resource(providersGVR).List(ctx, metav1.ListOptions{Limit: 1}); err != nil { + return false, nil + } + return true, nil + }); err != nil { + return fmt.Errorf("the Producer API did not become usable after binding: %w", err) + } + return nil +} + +// BindProvidersParent makes the workspace cfg points at the provisioning +// parent: it binds marketplace-provisioner, so producer workspaces can be +// created as its children. Nothing to wait for — the claim adds reach, not +// a servable API. +func BindProvidersParent(ctx context.Context, cfg *rest.Config, result *Result) error { + return applyTier(ctx, cfg, result, apiexport.ProducersOrder) +} + +// applyTier applies one hand-bound tier's assets. These two tiers are the +// only ones bound this way; every workspace below them is bound by its +// WorkspaceType or by its owner's own consent. +func applyTier(ctx context.Context, cfg *rest.Config, result *Result, order []string) error { + dyn, err := dynamic.NewForConfig(cfg) + if err != nil { + return fmt.Errorf("build dynamic client: %w", err) + } + disc, err := discovery.NewDiscoveryClientForConfig(cfg) + if err != nil { + return fmt.Errorf("build discovery client: %w", err) + } + cache := memory.NewMemCacheClient(disc) + mapper := restmapper.NewDeferredDiscoveryRESTMapper(cache) + + subs := map[string]string{ + apiexport.IdentityHashPlaceholder: result.WorkspacesIdentityHash, + apiexport.ExportsRefPlaceholder: result.ExportsCluster, + apiexport.ExportsPathPlaceholder: result.ExportsPath, + } + return applyAll(ctx, dyn, mapper, cache, order, subs) +} + +func applyAll(ctx context.Context, dyn dynamic.Interface, mapper *restmapper.DeferredDiscoveryRESTMapper, cache discovery.CachedDiscoveryInterface, order []string, subs map[string]string) error { + logger := klog.FromContext(ctx) + for _, filename := range order { + raw, err := apiexport.FS.ReadFile(filename) + if err != nil { + return fmt.Errorf("read embedded asset %s: %w", filename, err) + } + for placeholder, value := range subs { + raw = bytes.ReplaceAll(raw, []byte(placeholder), []byte(value)) + } + if err := applyManifests(ctx, dyn, mapper, cache, raw); err != nil { + return fmt.Errorf("apply %s: %w", filename, err) + } + logger.V(2).Info("applied", "asset", filename) + } + return nil +} + +var ( + endpointSliceGVR = schema.GroupVersionResource{ + Group: "apis.kcp.io", Version: "v1alpha1", Resource: "apiexportendpointslices", + } + apiExportGVR = schema.GroupVersionResource{ + Group: "apis.kcp.io", Version: "v1alpha2", Resource: "apiexports", + } + logicalClusterGVR = schema.GroupVersionResource{ + Group: "core.kcp.io", Version: "v1alpha1", Resource: "logicalclusters", + } +) + +// logicalClusterName reads the logical cluster of the workspace the client +// is pointed at. +func logicalClusterName(ctx context.Context, dyn dynamic.Interface) (string, error) { + lc, err := dyn.Resource(logicalClusterGVR).Get(ctx, "cluster", metav1.GetOptions{}) + if err != nil { + return "", err + } + if name := lc.GetAnnotations()["kcp.io/cluster"]; name != "" { + return name, nil + } + return "", fmt.Errorf("the LogicalCluster carries no kcp.io/cluster annotation") +} + +// exportIdentityHash reads status.identityHash of an APIExport in the given +// workspace, reached by retargeting cfg's host. +func exportIdentityHash(ctx context.Context, cfg *rest.Config, workspacePath, exportName string) (string, error) { + scoped := rest.CopyConfig(cfg) + host := scoped.Host + if i := strings.Index(host, "/clusters/"); i >= 0 { + host = host[:i] + } + scoped.Host = strings.TrimSuffix(host, "/") + "/clusters/" + workspacePath + + dyn, err := dynamic.NewForConfig(scoped) + if err != nil { + return "", fmt.Errorf("build dynamic client for %s: %w", workspacePath, err) + } + + var hash string + err = wait.PollUntilContextTimeout(ctx, 2*time.Second, time.Minute, true, func(ctx context.Context) (bool, error) { + export, err := dyn.Resource(apiExportGVR).Get(ctx, exportName, metav1.GetOptions{}) + if err != nil { + return false, err + } + hash, _, _ = unstructured.NestedString(export.Object, "status", "identityHash") + return hash != "", nil + }) + if err != nil { + return "", fmt.Errorf("APIExport %s in %s has no identity hash: %w", exportName, workspacePath, err) + } + return hash, nil +} + +// applyManifests applies every YAML document in raw, create-or-update. +func applyManifests(ctx context.Context, dyn dynamic.Interface, mapper *restmapper.DeferredDiscoveryRESTMapper, cache discovery.CachedDiscoveryInterface, raw []byte) error { + decoder := yaml.NewYAMLOrJSONDecoder(bytes.NewReader(raw), 4096) + for { + var obj unstructured.Unstructured + if err := decoder.Decode(&obj); err != nil { + if err.Error() == "EOF" { + return nil + } + return fmt.Errorf("decode manifest: %w", err) + } + if len(obj.Object) == 0 { + continue + } + + gvk := obj.GroupVersionKind() + mapping, err := mapper.RESTMapping(gvk.GroupKind(), gvk.Version) + if err != nil { + // A kind this bootstrap just installed may not be in the cached + // discovery yet; refresh once and retry. + cache.Invalidate() + mapper.Reset() + mapping, err = mapper.RESTMapping(gvk.GroupKind(), gvk.Version) + if err != nil { + return fmt.Errorf("map %s: %w", gvk, err) + } + } + + client := dyn.Resource(mapping.Resource) + if _, err := client.Create(ctx, &obj, metav1.CreateOptions{}); err != nil { + // A hand-bound tier can land on a different shard than the + // exports, and the `bind` RBAC applied moments ago reaches that + // shard through cache replication — so a Forbidden here is + // usually a propagation lag, not a verdict. Retry it briefly. + if apierrors.IsForbidden(err) && gvk.Kind == "APIBinding" { + retryErr := wait.PollUntilContextTimeout(ctx, 3*time.Second, 2*time.Minute, false, func(ctx context.Context) (bool, error) { + _, err := client.Create(ctx, &obj, metav1.CreateOptions{}) + if err == nil || apierrors.IsAlreadyExists(err) { + return true, nil + } + if apierrors.IsForbidden(err) { + return false, nil + } + return false, err + }) + if retryErr != nil { + return fmt.Errorf("create %s %s (after retrying propagation of the bind grant): %w", gvk.Kind, obj.GetName(), retryErr) + } + continue + } + if !apierrors.IsAlreadyExists(err) { + return fmt.Errorf("create %s %s: %w", gvk.Kind, obj.GetName(), err) + } + err := retry.RetryOnConflict(retry.DefaultRetry, func() error { + existing, err := client.Get(ctx, obj.GetName(), metav1.GetOptions{}) + if err != nil { + return err + } + obj.SetResourceVersion(existing.GetResourceVersion()) + _, err = client.Update(ctx, &obj, metav1.UpdateOptions{}) + return err + }) + if err != nil { + // Some kcp objects reject spec updates (APIResourceSchemas + // are immutable); existing is as good as applied. + if apierrors.IsInvalid(err) || apierrors.IsForbidden(err) { + continue + } + return fmt.Errorf("update %s %s: %w", gvk.Kind, obj.GetName(), err) + } + } + } +} + +// GrantPlatformAdmins makes the given identities administrators of the +// Producer registry cfg points at: they may enter it and manage Producers, +// and nothing else. It is applied even with no identities, so that +// dropping someone from the list revokes them. +func GrantPlatformAdmins(ctx context.Context, cfg *rest.Config, users, groups []string) error { + kube, err := kubernetes.NewForConfig(cfg) + if err != nil { + return fmt.Errorf("build kubernetes client: %w", err) + } + role := &rbacv1.ClusterRole{ + ObjectMeta: metav1.ObjectMeta{Name: marketplacev1alpha1.GroupName + ":platform-admin"}, + Rules: []rbacv1.PolicyRule{ + { + Verbs: []string{"access"}, + NonResourceURLs: []string{"/"}, + }, + { + APIGroups: []string{marketplacev1alpha1.GroupName}, + Resources: []string{"producers"}, + Verbs: []string{"get", "list", "watch", "create", "update", "patch", "delete"}, + }, + }, + } + return applyRoleAndBinding(ctx, kube, role, users, groups) +} + +// applyRoleAndBinding creates or updates a ClusterRole and a binding of the +// same name holding exactly the given subjects. Updates change only rules, +// subjects and roleRef on the stored object: kcp annotates these objects +// itself, and writing back a copy without its internal.kcp.io annotations +// is rejected as modifying reserved metadata. +func applyRoleAndBinding(ctx context.Context, kube kubernetes.Interface, role *rbacv1.ClusterRole, users, groups []string) error { + if _, err := kube.RbacV1().ClusterRoles().Create(ctx, role, metav1.CreateOptions{}); err != nil { + if !apierrors.IsAlreadyExists(err) { + return err + } + if err := retry.RetryOnConflict(retry.DefaultRetry, func() error { + existing, err := kube.RbacV1().ClusterRoles().Get(ctx, role.Name, metav1.GetOptions{}) + if err != nil { + return err + } + existing.Rules = role.Rules + _, err = kube.RbacV1().ClusterRoles().Update(ctx, existing, metav1.UpdateOptions{}) + return err + }); err != nil { + return err + } + } + + subjects := make([]rbacv1.Subject, 0, len(users)+len(groups)) + for _, u := range users { + subjects = append(subjects, rbacv1.Subject{Kind: rbacv1.UserKind, APIGroup: rbacv1.GroupName, Name: u}) + } + for _, g := range groups { + subjects = append(subjects, rbacv1.Subject{Kind: rbacv1.GroupKind, APIGroup: rbacv1.GroupName, Name: g}) + } + binding := &rbacv1.ClusterRoleBinding{ + ObjectMeta: metav1.ObjectMeta{Name: role.Name}, + RoleRef: rbacv1.RoleRef{APIGroup: rbacv1.GroupName, Kind: "ClusterRole", Name: role.Name}, + Subjects: subjects, + } + if _, err := kube.RbacV1().ClusterRoleBindings().Create(ctx, binding, metav1.CreateOptions{}); err != nil { + if !apierrors.IsAlreadyExists(err) { + return err + } + return retry.RetryOnConflict(retry.DefaultRetry, func() error { + existing, err := kube.RbacV1().ClusterRoleBindings().Get(ctx, binding.Name, metav1.GetOptions{}) + if err != nil { + return err + } + existing.Subjects = subjects + existing.RoleRef = binding.RoleRef + _, err = kube.RbacV1().ClusterRoleBindings().Update(ctx, existing, metav1.UpdateOptions{}) + return err + }) + } + return nil +} + +// applyServerIdentity grants the server role to the given identities: what +// the operator and the virtual workspace need in the exports workspace to +// use the exports' virtual workspaces when they do not run as the +// bootstrap credential. The nonResourceURL access rule is load-bearing — +// RBAC in a workspace means nothing to a subject that cannot enter it. +func applyServerIdentity(ctx context.Context, kube kubernetes.Interface, users, groups []string) error { + role := &rbacv1.ClusterRole{ + ObjectMeta: metav1.ObjectMeta{Name: marketplacev1alpha1.GroupName + ":server"}, + Rules: []rbacv1.PolicyRule{ + { + Verbs: []string{"access"}, + NonResourceURLs: []string{"/"}, + }, + { + APIGroups: []string{"apis.kcp.io"}, + Resources: []string{"apiexports", "apiexportendpointslices", "apibindings"}, + Verbs: []string{"get", "list", "watch"}, + }, + { + APIGroups: []string{"apis.kcp.io"}, + Resources: []string{"apiexports/content"}, + Verbs: []string{"*"}, + }, + }, + } + return applyRoleAndBinding(ctx, kube, role, users, groups) +} + +// WaitForEndpointSliceURLs reports the virtual workspace URLs one endpoint +// slice has published, nudging first. An empty answer is informational, +// never fatal. +func WaitForEndpointSliceURLs(ctx context.Context, cfg *rest.Config, sliceName string) ([]string, error) { + dyn, err := dynamic.NewForConfig(cfg) + if err != nil { + return nil, fmt.Errorf("build dynamic client: %w", err) + } + return waitForEndpointSlice(ctx, dyn, sliceName), nil +} + +func waitForEndpointSlice(ctx context.Context, dyn dynamic.Interface, sliceName string) []string { + logger := klog.FromContext(ctx) + + ctx, cancel := context.WithTimeout(ctx, 30*time.Second) + defer cancel() + + var urls []string + err := wait.PollUntilContextCancel(ctx, 2*time.Second, true, func(ctx context.Context) (bool, error) { + slice, err := dyn.Resource(endpointSliceGVR).Get(ctx, sliceName, metav1.GetOptions{}) + if err != nil { + if apierrors.IsNotFound(err) { + return false, nil + } + return false, err + } + endpoints, _, err := unstructured.NestedSlice(slice.Object, "status", "endpoints") + if err != nil || len(endpoints) == 0 { + return false, nil + } + urls = urls[:0] + for _, e := range endpoints { + if m, ok := e.(map[string]any); ok { + if u, ok := m["url"].(string); ok && u != "" { + urls = append(urls, u) + } + } + } + return len(urls) > 0, nil + }) + if err != nil { + logger.Info("endpoint slice has no virtual workspace endpoints yet; "+ + "the servers pick them up as they appear", "slice", sliceName) + return nil + } + return urls +} diff --git a/marketplace/pkg/cli/offers.go b/marketplace/pkg/cli/offers.go new file mode 100644 index 0000000..ced66ab --- /dev/null +++ b/marketplace/pkg/cli/offers.go @@ -0,0 +1,456 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// Package cli holds the marketplace's user-facing commands: browsing the +// catalog, and enabling an offering in a workspace. +// +// Enabling is a plain kcp APIBinding the caller creates with their own +// credential, so these commands are sugar over surfaces that already +// exist — there is no marketplace API to call and nothing privileged in +// the path. +package cli + +import ( + "fmt" + "os" + "strings" + "text/tabwriter" + + "github.com/spf13/cobra" + + apierrors "k8s.io/apimachinery/pkg/api/errors" + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + "k8s.io/apimachinery/pkg/runtime" + utilruntime "k8s.io/apimachinery/pkg/util/runtime" + "k8s.io/client-go/rest" + "k8s.io/client-go/tools/clientcmd" + "sigs.k8s.io/controller-runtime/pkg/client" + + apisv1alpha2 "github.com/kcp-dev/sdk/apis/apis/v1alpha2" + + marketplacev1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1" +) + +// WorkspaceResolver reports the workspace URL a command should act on +// when no flag names one. +// +// It is a function rather than an import because the marketplace does not +// know what a tenant is: whoever assembles the CLI decides where "here" +// is — under the repo-wide CLI that is whatever `use` selected, and the +// two components still never name each other. +type WorkspaceResolver func() (url string, describe string, err error) + +var scheme = runtime.NewScheme() + +func init() { + utilruntime.Must(marketplacev1alpha1.AddToScheme(scheme)) + utilruntime.Must(apisv1alpha2.AddToScheme(scheme)) +} + +// ServerDefaults is what a composing binary already knows about where the +// platform is — learned by its own login, remembered in its own way — and +// hands over so the catalog commands need no address on every call. This +// package does not read it from anywhere itself: what counts as "the +// stored server" is the composer's business, not the marketplace's. +// +// The zero value means "nothing known", and the flags are then required. +type ServerDefaults struct { + // URL is the marketplace virtual workspace's base URL. + URL string + // CertificateAuthority verifies its serving certificate; Insecure + // skips that, for local testing. + CertificateAuthority string + Insecure bool + // Token is the bearer token the composer's login obtained, used when + // no credential is given explicitly. + Token string +} + +// catalogOptions are the flags for reaching the marketplace virtual +// workspace, which any authenticated caller may read. +type catalogOptions struct { + defaults ServerDefaults + url string + kubeconfig string + certFile string + keyFile string + tokenFile string + caFile string + insecure bool +} + +func (o *catalogOptions) addFlags(cmd *cobra.Command) { + // Defaulted from what the composing binary learned at login, so + // browsing the catalog needs no address of its own. + cmd.Flags().StringVar(&o.url, "url", envOr("MARKETPLACE_VW_URL", o.defaults.URL), + "Base URL of the marketplace virtual workspace. Defaults to the server "+ + "`login --url` stored, or $MARKETPLACE_VW_URL.") + cmd.Flags().StringVar(&o.kubeconfig, "kubeconfig", os.Getenv("KUBECONFIG"), + "Kubeconfig whose credential to use. Defaults to $KUBECONFIG.") + cmd.Flags().StringVar(&o.certFile, "client-cert", "", "Client certificate to authenticate with.") + cmd.Flags().StringVar(&o.keyFile, "client-key", "", "Key for --client-cert.") + cmd.Flags().StringVar(&o.tokenFile, "token-file", "", "File holding a bearer token to authenticate with.") + cmd.Flags().StringVar(&o.caFile, "certificate-authority", o.defaults.CertificateAuthority, + "CA bundle used to verify the virtual workspace's serving certificate.") + cmd.Flags().BoolVar(&o.insecure, "insecure-skip-tls-verify", o.defaults.Insecure, + "Do not verify the serving certificate. For local testing only.") +} + +func (o *catalogOptions) client() (client.Client, error) { + if o.url == "" && o.kubeconfig == "" { + return nil, fmt.Errorf("--url is required, or set MARKETPLACE_VW_URL") + } + + cfg := &rest.Config{} + if o.kubeconfig != "" { + loaded, err := clientcmd.BuildConfigFromFlags("", o.kubeconfig) + if err != nil { + return nil, fmt.Errorf("load kubeconfig: %w", err) + } + cfg = loaded + if i := strings.Index(cfg.Host, "/clusters/"); i >= 0 { + cfg.Host = cfg.Host[:i] + } + cfg.Host = strings.TrimSuffix(cfg.Host, "/") + rootPath + } + if o.url != "" { + cfg.Host = strings.TrimSuffix(o.url, "/") + if !strings.HasSuffix(cfg.Host, rootPath) { + cfg.Host += rootPath + } + } + + if o.certFile != "" || o.keyFile != "" { + if o.certFile == "" || o.keyFile == "" { + return nil, fmt.Errorf("--client-cert and --client-key must be given together") + } + cfg.CertFile, cfg.KeyFile = o.certFile, o.keyFile + } + if o.tokenFile != "" { + raw, err := os.ReadFile(o.tokenFile) + if err != nil { + return nil, fmt.Errorf("read token file: %w", err) + } + cfg.BearerToken = strings.TrimSpace(string(raw)) + } + if cfg.CertFile == "" && cfg.BearerToken == "" && o.kubeconfig == "" { + cfg.BearerToken = o.defaults.Token + } + if o.caFile != "" { + cfg.CAFile, cfg.CAData = o.caFile, nil + } + if o.insecure { + cfg.Insecure, cfg.CAFile, cfg.CAData = true, "", nil + } + + c, err := client.New(cfg, client.Options{Scheme: scheme}) + if err != nil { + return nil, fmt.Errorf("build client for %s: %w", cfg.Host, err) + } + return c, nil +} + +// rootPath is where the catalog virtual workspace answers. Kept as a +// literal so this package does not drag the server in. +const rootPath = "/services/marketplace" + +// NewOffersCommand lists the catalog. +func NewOffersCommand(defaults ServerDefaults) *cobra.Command { + o := &catalogOptions{defaults: defaults} + var wide bool + + cmd := &cobra.Command{ + Use: "offers", + Aliases: []string{"offer", "catalog"}, + Short: "List the offerings you could enable", + Long: `Browse the marketplace catalog. + +Every entry carries the coordinates of the APIBinding that enabling it +would create — the producer's workspace and APIExport — so reading the +catalog is reading both the consent form and the binding. Any +authenticated caller may read it.`, + Args: cobra.NoArgs, + RunE: func(cmd *cobra.Command, _ []string) error { + c, err := o.client() + if err != nil { + return err + } + var offerings marketplacev1alpha1.CatalogOfferingList + if err := c.List(cmd.Context(), &offerings); err != nil { + return fmt.Errorf("list offerings: %w", err) + } + if len(offerings.Items) == 0 { + fmt.Println("The catalog is empty.") + return nil + } + + header := []string{"OFFER", "DISPLAY NAME", "READY"} + if wide { + header = append(header, "EXPORT", "PROVIDER WORKSPACE", "REV", "CLAIMS") + } + rows := make([][]string, 0, len(offerings.Items)) + for _, off := range offerings.Items { + row := []string{off.Name, dash(off.DisplayName), yesNo(off.Ready)} + if wide { + row = append(row, dash(off.Export), dash(off.WorkspacePath), + dash(off.Revision), claimSummary(off.Claims)) + } + rows = append(rows, row) + } + table(header, rows) + return nil + }, + } + o.addFlags(cmd) + cmd.Flags().BoolVarP(&wide, "wide", "o", false, "Also show the bind coordinates and claims.") + return cmd +} + +// NewEnableCommand enables an offering in a workspace by creating the +// APIBinding, as the caller. +func NewEnableCommand(defaults ServerDefaults, resolve WorkspaceResolver) *cobra.Command { + o := &catalogOptions{defaults: defaults} + var ( + workspace string + kubeconfig string + name string + ) + + cmd := &cobra.Command{ + Use: "enable OFFER", + Short: "Enable an offering in your workspace", + Long: `Enable an offering: read its coordinates from the catalog and +create the APIBinding that enabling consists of. + +The binding is created with your own credential, so kcp decides whether +it happens — you must be allowed to create APIBindings in the workspace, +and the producer must have published the offering, which is what grants +the bind permission. Nothing privileged is involved, and this command +does nothing the catalog did not already tell you.`, + Args: cobra.ExactArgs(1), + RunE: func(cmd *cobra.Command, args []string) error { + c, err := o.client() + if err != nil { + return err + } + var offering marketplacev1alpha1.CatalogOffering + if err := c.Get(cmd.Context(), client.ObjectKey{Name: args[0]}, &offering); err != nil { + if apierrors.IsNotFound(err) { + return fmt.Errorf("no offering %q in the catalog (try `offers`)", args[0]) + } + return fmt.Errorf("get offering %q: %w", args[0], err) + } + if offering.Export == "" || offering.WorkspacePath == "" { + return fmt.Errorf("offering %q carries no bind coordinates yet; is it Ready?", args[0]) + } + + target, describe, err := targetWorkspace(workspace, resolve) + if err != nil { + return err + } + binding, err := bindingClient(target, kubeconfig, o) + if err != nil { + return err + } + + if name == "" { + name = offering.Offering + } + // Accepting the catalog's claims is the consent, and it happens + // on the object being created here — so say what is being + // accepted rather than doing it quietly. + claims := acceptClaims(offering.Claims) + for _, c := range offering.Claims { + fmt.Printf(" accepting %s: %s\n", claimName(c), strings.Join(c.Verbs, ",")) + } + obj := &apisv1alpha2.APIBinding{ + ObjectMeta: metav1.ObjectMeta{Name: name}, + Spec: apisv1alpha2.APIBindingSpec{ + Reference: apisv1alpha2.BindingReference{ + Export: &apisv1alpha2.ExportBindingReference{ + Path: offering.WorkspacePath, + Name: offering.Export, + }, + }, + PermissionClaims: claims, + }, + } + if err := binding.Create(cmd.Context(), obj); err != nil { + if apierrors.IsAlreadyExists(err) { + return fmt.Errorf("%q is already enabled in %s (binding %q)", args[0], describe, name) + } + return fmt.Errorf("create the binding in %s: %w%s", describe, err, enableHint(err)) + } + fmt.Printf("enabled %s in %s\n", args[0], describe) + fmt.Printf(" apibinding/%s → %s|%s\n", name, offering.WorkspacePath, offering.Export) + return nil + }, + } + o.addFlags(cmd) + cmd.Flags().StringVar(&workspace, "workspace", "", + "URL of the workspace to enable in. Defaults to the one currently selected.") + cmd.Flags().StringVar(&kubeconfig, "workspace-kubeconfig", "", + "Kubeconfig whose credential to use against the workspace. Defaults to --kubeconfig.") + cmd.Flags().StringVar(&name, "name", "", "Name for the APIBinding. Defaults to the offering's name.") + return cmd +} + +// targetWorkspace picks the workspace to write the binding into. +func targetWorkspace(flag string, resolve WorkspaceResolver) (string, string, error) { + if flag != "" { + return flag, flag, nil + } + if resolve == nil { + return "", "", fmt.Errorf("--workspace is required") + } + url, describe, err := resolve() + if err != nil { + return "", "", err + } + if url == "" { + return "", "", fmt.Errorf("no workspace selected: pass --workspace, or run `use` to choose one") + } + return url, describe, nil +} + +// bindingClient talks to the workspace itself rather than to the virtual +// workspace: the binding is an ordinary object in the consumer's own +// cluster. +func bindingClient(url, kubeconfig string, o *catalogOptions) (client.Client, error) { + cfg := &rest.Config{} + if kubeconfig == "" { + kubeconfig = o.kubeconfig + } + if kubeconfig != "" { + loaded, err := clientcmd.BuildConfigFromFlags("", kubeconfig) + if err != nil { + return nil, fmt.Errorf("load kubeconfig: %w", err) + } + cfg = loaded + } + cfg.Host = url + + if o.certFile != "" && o.keyFile != "" { + cfg.CertFile, cfg.KeyFile = o.certFile, o.keyFile + } + if o.tokenFile != "" { + raw, err := os.ReadFile(o.tokenFile) + if err != nil { + return nil, fmt.Errorf("read token file: %w", err) + } + cfg.BearerToken = strings.TrimSpace(string(raw)) + } + if cfg.CertFile == "" && cfg.BearerToken == "" && kubeconfig == "" { + cfg.BearerToken = o.defaults.Token + } + if o.insecure { + cfg.Insecure, cfg.CAFile, cfg.CAData = true, "", nil + } + + c, err := client.New(cfg, client.Options{Scheme: scheme}) + if err != nil { + return nil, fmt.Errorf("build client for %s: %w", url, err) + } + return c, nil +} + +func enableHint(err error) string { + if apierrors.IsForbidden(err) { + return "\n\nkcp refused this: either you may not create APIBindings in that workspace " + + "(an admin Membership is what grants it), or the offering is not published." + } + return "" +} + +// acceptClaims turns the catalog's claim surface into the acceptance the +// APIBinding carries. Verbs and identity come from the catalog entry +// verbatim; the selector is the producer's suggested scope, or every +// object, which is what a binding means by default. +func acceptClaims(claims []marketplacev1alpha1.OfferingClaim) []apisv1alpha2.AcceptablePermissionClaim { + var out []apisv1alpha2.AcceptablePermissionClaim + for _, c := range claims { + selector := apisv1alpha2.PermissionClaimSelector{MatchAll: true} + if len(c.MatchLabels) > 0 { + selector = apisv1alpha2.PermissionClaimSelector{ + LabelSelector: metav1.LabelSelector{MatchLabels: c.MatchLabels}, + } + } + out = append(out, apisv1alpha2.AcceptablePermissionClaim{ + ScopedPermissionClaim: apisv1alpha2.ScopedPermissionClaim{ + PermissionClaim: apisv1alpha2.PermissionClaim{ + GroupResource: apisv1alpha2.GroupResource{Group: c.Group, Resource: c.Resource}, + Verbs: c.Verbs, + IdentityHash: c.IdentityHash, + }, + Selector: selector, + }, + State: apisv1alpha2.ClaimAccepted, + }) + } + return out +} + +// claimName renders a claim the way kcp names one: resource.group, with +// the core group left implicit. +func claimName(c marketplacev1alpha1.OfferingClaim) string { + if c.Group == "" { + return c.Resource + } + return c.Resource + "." + c.Group +} + +func claimSummary(claims []marketplacev1alpha1.OfferingClaim) string { + if len(claims) == 0 { + return "-" + } + parts := make([]string, 0, len(claims)) + for _, c := range claims { + parts = append(parts, c.Resource) + } + return strings.Join(parts, ",") +} + +// envOr is the usual precedence: an environment override, else whatever +// was stored at login. +func envOr(key, fallback string) string { + if v := os.Getenv(key); v != "" { + return v + } + return fallback +} + +func yesNo(b bool) string { + if b { + return "yes" + } + return "no" +} + +func dash(s string) string { + if s == "" { + return "-" + } + return s +} + +func table(header []string, rows [][]string) { + w := tabwriter.NewWriter(os.Stdout, 0, 0, 3, ' ', 0) + _, _ = fmt.Fprintln(w, strings.Join(header, "\t")) + for _, row := range rows { + _, _ = fmt.Fprintln(w, strings.Join(row, "\t")) + } + _ = w.Flush() +} diff --git a/marketplace/pkg/directory/directory.go b/marketplace/pkg/directory/directory.go new file mode 100644 index 0000000..61c4ef1 --- /dev/null +++ b/marketplace/pkg/directory/directory.go @@ -0,0 +1,301 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// 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. It is read-heavy, +// written only by the mirroring controllers, and guarded by one mutex — +// the catalog is small and a browse must never block a sync. +package directory + +import ( + "sort" + "sync" + + marketplacev1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1" +) + +// Key identifies a mirrored object by the logical cluster it lives in and +// its name there. +type Key struct { + Cluster string + Name string +} + +// Producer is the directory's view of a catalog record. +type Producer struct { + DisplayName string + Description string + WorkspacePath string + WorkspaceCluster string + Ready bool +} + +// Offering is the directory's view of a published APIExport. +// +// There is no Producer field: which producer an offering belongs to is not +// something the offering records, it is which workspace the export lives +// in. Catalog resolves it by matching the export's logical cluster against +// the Producer records, so a producer cannot be misattributed by anything +// written in the producer's own workspace. +type Offering struct { + DisplayName string + Description string + Export string + Revision string + Claims []marketplacev1alpha1.OfferingClaim + Ready bool + IdentityHash string + DocsURL string + // InstructionsRef names a ConfigMap in the offering's own cluster; the + // content is mirrored separately and joined at read time, so an edit + // to the instructions never has to re-reconcile the export. + InstructionsRef string + // Resources are the export's spec.resources. Like instructions, the + // schemas they name are mirrored separately and joined at read time. + Resources []ResourceRef +} + +// ResourceRef is one resource an export serves and the APIResourceSchema, +// in the export's own cluster, that defines it. +type ResourceRef struct { + Group string + Resource string + Schema string +} + +// Schema is the directory's view of an APIResourceSchema: what the catalog +// shows of it. +type Schema struct { + Kind string + Scope string + Versions []marketplacev1alpha1.OfferingResourceVersion +} + +// Directory is safe for concurrent use. +type Directory struct { + mu sync.RWMutex + ready bool + producers map[Key]Producer + offerings map[Key]Offering + // instructions holds the content of ConfigMaps offerings point at, + // keyed like everything else by the cluster they live in. + instructions map[Key]map[string]string + // schemas holds the APIResourceSchemas offerings reference. + schemas map[Key]Schema +} + +// New returns an empty directory. +func New() *Directory { + return &Directory{ + producers: map[Key]Producer{}, + offerings: map[Key]Offering{}, + instructions: map[Key]map[string]string{}, + schemas: map[Key]Schema{}, + } +} + +// SetReady marks the initial sync complete; Ready reports it. +func (d *Directory) SetReady() { + d.mu.Lock() + defer d.mu.Unlock() + d.ready = true +} + +func (d *Directory) Ready() bool { + d.mu.RLock() + defer d.mu.RUnlock() + return d.ready +} + +// Counts reports how many objects the directory holds, for debugging. +func (d *Directory) Counts() (producers, offerings int) { + d.mu.RLock() + defer d.mu.RUnlock() + return len(d.producers), len(d.offerings) +} + +func (d *Directory) UpsertProducer(key Key, p Producer) { + d.mu.Lock() + defer d.mu.Unlock() + d.producers[key] = p +} + +func (d *Directory) RemoveProducer(key Key) { + d.mu.Lock() + defer d.mu.Unlock() + delete(d.producers, key) +} + +func (d *Directory) UpsertOffering(key Key, o Offering) { + d.mu.Lock() + defer d.mu.Unlock() + d.offerings[key] = o +} + +func (d *Directory) RemoveOffering(key Key) { + d.mu.Lock() + defer d.mu.Unlock() + delete(d.offerings, key) +} + +// UpsertInstructions records the content of one instructions ConfigMap. +// Which offerings use it is decided at read time by name, so the two +// mirrors never have to know about each other. +func (d *Directory) UpsertInstructions(key Key, sections map[string]string) { + d.mu.Lock() + defer d.mu.Unlock() + copied := make(map[string]string, len(sections)) + for k, v := range sections { + copied[k] = v + } + d.instructions[key] = copied +} + +func (d *Directory) RemoveInstructions(key Key) { + d.mu.Lock() + defer d.mu.Unlock() + delete(d.instructions, key) +} + +// UpsertSchema records one APIResourceSchema. As with instructions, which +// offerings use it is decided at read time by name. +func (d *Directory) UpsertSchema(key Key, s Schema) { + d.mu.Lock() + defer d.mu.Unlock() + d.schemas[key] = s +} + +func (d *Directory) RemoveSchema(key Key) { + d.mu.Lock() + defer d.mu.Unlock() + delete(d.schemas, key) +} + +// ForgetCluster drops everything mirrored from one logical cluster — a +// workspace that unbound its export leaves nothing behind. +func (d *Directory) ForgetCluster(cluster string) { + d.mu.Lock() + defer d.mu.Unlock() + for key := range d.producers { + if key.Cluster == cluster { + delete(d.producers, key) + } + } + for key := range d.offerings { + if key.Cluster == cluster { + delete(d.offerings, key) + } + } + for key := range d.instructions { + if key.Cluster == cluster { + delete(d.instructions, key) + } + } + for key := range d.schemas { + if key.Cluster == cluster { + delete(d.schemas, key) + } + } +} + +// Entry is one catalog listing: a published export joined with the +// Producer record that owns its workspace. +type Entry struct { + Producer string + Offering string + // WorkspacePath is the canonical path of the producer's workspace — + // what the APIBinding a consumer authors references as + // spec.reference.export.path. + WorkspacePath string + Detail Offering + // Instructions is the referenced ConfigMap's content, or nil if the + // offering names none or it has not been seen. + Instructions map[string]string + // Resources are the offering's resources joined with their schemas; + // one whose schema has not been seen carries no versions. + Resources []marketplacev1alpha1.OfferingResource +} + +// Name is the entry's stable listing name, ".". +func (e Entry) Name() string { + return e.Producer + "." + e.Offering +} + +// Catalog lists every offering whose workspace a Producer record names, +// sorted by name for stable output. An offering published from a workspace +// no record names is invisible — publishing into the void is not +// publishing, and it is also the case an unregistered workspace would use +// to put itself on the catalog by annotating its own export. +func (d *Directory) Catalog() []Entry { + d.mu.RLock() + defer d.mu.RUnlock() + + // The join is workspace → producer: the record says which logical + // cluster it owns, and the offering is in one. + producerByCluster := map[string]struct { + name string + record Producer + }{} + for key, p := range d.producers { + if p.WorkspaceCluster == "" { + continue + } + producerByCluster[p.WorkspaceCluster] = struct { + name string + record Producer + }{key.Name, p} + } + + var out []Entry + for key, offering := range d.offerings { + owner, known := producerByCluster[key.Cluster] + if !known { + continue + } + entry := Entry{ + Producer: owner.name, + Offering: key.Name, + WorkspacePath: owner.record.WorkspacePath, + Detail: offering, + } + // Instructions live next to the export, in the same cluster. + if offering.InstructionsRef != "" { + entry.Instructions = d.instructions[Key{Cluster: key.Cluster, Name: offering.InstructionsRef}] + } + // So do the schemas. + for _, ref := range offering.Resources { + r := marketplacev1alpha1.OfferingResource{Group: ref.Group, Resource: ref.Resource, Schema: ref.Schema} + if s, seen := d.schemas[Key{Cluster: key.Cluster, Name: ref.Schema}]; seen { + r.Kind, r.Scope, r.Versions = s.Kind, s.Scope, s.Versions + } + entry.Resources = append(entry.Resources, r) + } + out = append(out, entry) + } + sort.Slice(out, func(i, j int) bool { return out[i].Name() < out[j].Name() }) + return out +} + +// Lookup returns one catalog entry by its listing name. +func (d *Directory) Lookup(name string) (Entry, bool) { + for _, e := range d.Catalog() { + if e.Name() == name { + return e, true + } + } + return Entry{}, false +} diff --git a/marketplace/pkg/directory/directory_test.go b/marketplace/pkg/directory/directory_test.go new file mode 100644 index 0000000..2f7365c --- /dev/null +++ b/marketplace/pkg/directory/directory_test.go @@ -0,0 +1,66 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package directory + +import ( + "testing" + + "k8s.io/apimachinery/pkg/runtime" + + marketplacev1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1" +) + +func TestCatalogJoinsSchemasFromTheOfferingsOwnCluster(t *testing.T) { + d := New() + d.UpsertProducer(Key{Cluster: "catalog", Name: "acme"}, Producer{WorkspacePath: "root:acme", WorkspaceCluster: "c-acme"}) + d.UpsertOffering(Key{Cluster: "c-acme", Name: "widgets.acme.example"}, Offering{ + Export: "widgets.acme.example", + Resources: []ResourceRef{ + {Group: "acme.example", Resource: "widgets", Schema: "v1.widgets.acme.example"}, + {Group: "acme.example", Resource: "gizmos", Schema: "v1.gizmos.acme.example"}, + }, + }) + schema := runtime.RawExtension{Raw: []byte(`{"type":"object"}`)} + d.UpsertSchema(Key{Cluster: "c-acme", Name: "v1.widgets.acme.example"}, Schema{ + Kind: "Widget", + Scope: "Namespaced", + Versions: []marketplacev1alpha1.OfferingResourceVersion{{Name: "v1", Served: true, Storage: true, Schema: schema}}, + }) + // A schema of the same name in another workspace is not this offering's. + d.UpsertSchema(Key{Cluster: "c-other", Name: "v1.gizmos.acme.example"}, Schema{Kind: "Gizmo"}) + + entries := d.Catalog() + if len(entries) != 1 { + t.Fatalf("catalog = %+v, want one entry", entries) + } + got := entries[0].Resources + if len(got) != 2 { + t.Fatalf("resources = %+v, want both the export serves", got) + } + if got[0].Kind != "Widget" || got[0].Scope != "Namespaced" || len(got[0].Versions) != 1 || + string(got[0].Versions[0].Schema.Raw) != `{"type":"object"}` { + t.Errorf("widgets = %+v, want its schema joined in", got[0]) + } + if got[1].Resource != "gizmos" || got[1].Kind != "" || got[1].Versions != nil { + t.Errorf("gizmos = %+v, want it listed without a schema it has not seen", got[1]) + } + + d.RemoveSchema(Key{Cluster: "c-acme", Name: "v1.widgets.acme.example"}) + if r := d.Catalog()[0].Resources[0]; r.Versions != nil { + t.Errorf("widgets = %+v after its schema went away, want no versions", r) + } +} diff --git a/marketplace/pkg/generated/openapi/zz_generated.openapi.go b/marketplace/pkg/generated/openapi/zz_generated.openapi.go new file mode 100644 index 0000000..c5edde4 --- /dev/null +++ b/marketplace/pkg/generated/openapi/zz_generated.openapi.go @@ -0,0 +1,3264 @@ +//go:build !ignore_autogenerated +// +build !ignore_autogenerated + +/* +Copyright 2026 The kcp Authors. +*/ + +// Code generated by openapi-gen. DO NOT EDIT. + +package openapi + +import ( + v1 "k8s.io/apimachinery/pkg/apis/meta/v1" + runtime "k8s.io/apimachinery/pkg/runtime" + version "k8s.io/apimachinery/pkg/version" + common "k8s.io/kube-openapi/pkg/common" + spec "k8s.io/kube-openapi/pkg/validation/spec" +) + +func GetOpenAPIDefinitions(ref common.ReferenceCallback) map[string]common.OpenAPIDefinition { + return map[string]common.OpenAPIDefinition{ + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1.CatalogOffering": schema_sdk_apis_marketplace_v1alpha1_CatalogOffering(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1.CatalogOfferingList": schema_sdk_apis_marketplace_v1alpha1_CatalogOfferingList(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1.OfferingClaim": schema_sdk_apis_marketplace_v1alpha1_OfferingClaim(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1.OfferingResource": schema_sdk_apis_marketplace_v1alpha1_OfferingResource(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1.OfferingResourceVersion": schema_sdk_apis_marketplace_v1alpha1_OfferingResourceVersion(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1.Producer": schema_sdk_apis_marketplace_v1alpha1_Producer(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1.ProducerList": schema_sdk_apis_marketplace_v1alpha1_ProducerList(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1.ProducerSpec": schema_sdk_apis_marketplace_v1alpha1_ProducerSpec(ref), + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1.ProducerStatus": schema_sdk_apis_marketplace_v1alpha1_ProducerStatus(ref), + v1.APIGroup{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_APIGroup(ref), + v1.APIGroupList{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_APIGroupList(ref), + v1.APIResource{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_APIResource(ref), + v1.APIResourceList{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_APIResourceList(ref), + v1.APIVersions{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_APIVersions(ref), + v1.ApplyOptions{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_ApplyOptions(ref), + v1.Condition{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_Condition(ref), + v1.CreateOptions{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_CreateOptions(ref), + v1.DeleteOptions{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_DeleteOptions(ref), + v1.Duration{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_Duration(ref), + v1.FieldSelectorRequirement{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_FieldSelectorRequirement(ref), + v1.FieldsV1{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_FieldsV1(ref), + v1.GetOptions{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_GetOptions(ref), + v1.GroupKind{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_GroupKind(ref), + v1.GroupResource{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_GroupResource(ref), + v1.GroupVersion{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_GroupVersion(ref), + v1.GroupVersionForDiscovery{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_GroupVersionForDiscovery(ref), + v1.GroupVersionKind{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_GroupVersionKind(ref), + v1.GroupVersionResource{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_GroupVersionResource(ref), + v1.InternalEvent{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_InternalEvent(ref), + v1.LabelSelector{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_LabelSelector(ref), + v1.LabelSelectorRequirement{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_LabelSelectorRequirement(ref), + v1.List{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_List(ref), + v1.ListMeta{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_ListMeta(ref), + v1.ListOptions{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_ListOptions(ref), + v1.ManagedFieldsEntry{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_ManagedFieldsEntry(ref), + v1.MicroTime{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_MicroTime(ref), + v1.ObjectMeta{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_ObjectMeta(ref), + v1.OwnerReference{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_OwnerReference(ref), + v1.PartialObjectMetadata{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_PartialObjectMetadata(ref), + v1.PartialObjectMetadataList{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_PartialObjectMetadataList(ref), + v1.Patch{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_Patch(ref), + v1.PatchOptions{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_PatchOptions(ref), + v1.Preconditions{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_Preconditions(ref), + v1.RootPaths{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_RootPaths(ref), + v1.ServerAddressByClientCIDR{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_ServerAddressByClientCIDR(ref), + v1.ShardInfo{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_ShardInfo(ref), + v1.Status{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_Status(ref), + v1.StatusCause{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_StatusCause(ref), + v1.StatusDetails{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_StatusDetails(ref), + v1.Table{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_Table(ref), + v1.TableColumnDefinition{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_TableColumnDefinition(ref), + v1.TableOptions{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_TableOptions(ref), + v1.TableRow{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_TableRow(ref), + v1.TableRowCondition{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_TableRowCondition(ref), + v1.Time{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_Time(ref), + v1.Timestamp{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_Timestamp(ref), + v1.TypeMeta{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_TypeMeta(ref), + v1.UpdateOptions{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_UpdateOptions(ref), + v1.WatchEvent{}.OpenAPIModelName(): schema_pkg_apis_meta_v1_WatchEvent(ref), + runtime.RawExtension{}.OpenAPIModelName(): schema_k8sio_apimachinery_pkg_runtime_RawExtension(ref), + runtime.TypeMeta{}.OpenAPIModelName(): schema_k8sio_apimachinery_pkg_runtime_TypeMeta(ref), + runtime.Unknown{}.OpenAPIModelName(): schema_k8sio_apimachinery_pkg_runtime_Unknown(ref), + version.Info{}.OpenAPIModelName(): schema_k8sio_apimachinery_pkg_version_Info(ref), + } +} + +func schema_sdk_apis_marketplace_v1alpha1_CatalogOffering(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "CatalogOffering is the virtual, read-only view of one offering as the marketplace virtual workspace serves it: a published APIExport joined with the Producer record whose workspace it lives in, named \".\". It carries everything needed to author the APIBinding that enabling means — the export, the workspace path it lives at, and its claims, identity hashes included. Reading the catalog is reading the consent form.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "kind": { + SchemaProps: spec.SchemaProps{ + Description: "Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", + Type: []string{"string"}, + Format: "", + }, + }, + "apiVersion": { + SchemaProps: spec.SchemaProps{ + Description: "APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources", + Type: []string{"string"}, + Format: "", + }, + }, + "metadata": { + SchemaProps: spec.SchemaProps{ + Default: map[string]interface{}{}, + Ref: ref(v1.ObjectMeta{}.OpenAPIModelName()), + }, + }, + "producer": { + SchemaProps: spec.SchemaProps{ + Description: "Producer is the catalog Producer record's name.", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "offering": { + SchemaProps: spec.SchemaProps{ + Description: "Offering is the name of the published APIExport in the producer's workspace — the offering and the export are the same object.", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "displayName": { + SchemaProps: spec.SchemaProps{ + Description: "DisplayName and Description mirror the offering's card.", + Type: []string{"string"}, + Format: "", + }, + }, + "description": { + SchemaProps: spec.SchemaProps{ + Type: []string{"string"}, + Format: "", + }, + }, + "export": { + SchemaProps: spec.SchemaProps{ + Description: "Export is the APIExport enabling binds, and WorkspacePath is the canonical path of the workspace that owns it — together the spec.reference.export of the APIBinding a consumer creates.", + Type: []string{"string"}, + Format: "", + }, + }, + "workspacePath": { + SchemaProps: spec.SchemaProps{ + Type: []string{"string"}, + Format: "", + }, + }, + "revision": { + SchemaProps: spec.SchemaProps{ + Description: "Revision identifies the claim surface below: it is a digest of Claims, so the same claims always produce the same revision and any change produces a different one.\n\nIt is derived rather than counted because there is no longer an object to keep a counter on — which turns out to be the better property anyway. A consumer who recorded the revision they accepted can compare it with this one to see whether the consent form has changed since, and the answer does not depend on how many times a controller happened to observe it.", + Type: []string{"string"}, + Format: "", + }, + }, + "claims": { + SchemaProps: spec.SchemaProps{ + Description: "Claims is the claim surface a consumer accepts by enabling: the export's own permission claims, projected.", + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Ref: ref("github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1.OfferingClaim"), + }, + }, + }, + }, + }, + "ready": { + SchemaProps: spec.SchemaProps{ + Description: "Ready reports whether enabling can currently succeed.", + Default: false, + Type: []string{"boolean"}, + Format: "", + }, + }, + "docsURL": { + SchemaProps: spec.SchemaProps{ + Description: "DocsURL links to the producer's own documentation, if they gave one.", + Type: []string{"string"}, + Format: "", + }, + }, + "instructions": { + SchemaProps: spec.SchemaProps{ + Description: "Instructions is the producer's \"how to use this\", keyed by section. Static text with {{variables}} the console fills in; see AnnotationInstructions.", + Type: []string{"object"}, + AdditionalProperties: &spec.SchemaOrBool{ + Allows: true, + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Type: []string{"string"}, + Format: "", + }, + }, + }, + }, + }, + "resources": { + SchemaProps: spec.SchemaProps{ + Description: "Resources is the API enabling adds: each resource the export serves, with the schema its APIResourceSchema declares, so a consumer can read what they would get before enabling it. A resource whose schema has not been seen is listed without versions.", + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Ref: ref("github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1.OfferingResource"), + }, + }, + }, + }, + }, + }, + Required: []string{"producer", "offering", "ready"}, + }, + }, + Dependencies: []string{ + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1.OfferingClaim", "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1.OfferingResource", v1.ObjectMeta{}.OpenAPIModelName()}, + } +} + +func schema_sdk_apis_marketplace_v1alpha1_CatalogOfferingList(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "CatalogOfferingList is the list form of CatalogOffering.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "kind": { + SchemaProps: spec.SchemaProps{ + Description: "Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", + Type: []string{"string"}, + Format: "", + }, + }, + "apiVersion": { + SchemaProps: spec.SchemaProps{ + Description: "APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources", + Type: []string{"string"}, + Format: "", + }, + }, + "metadata": { + SchemaProps: spec.SchemaProps{ + Default: map[string]interface{}{}, + Ref: ref(v1.ListMeta{}.OpenAPIModelName()), + }, + }, + "items": { + SchemaProps: spec.SchemaProps{ + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Ref: ref("github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1.CatalogOffering"), + }, + }, + }, + }, + }, + }, + Required: []string{"items"}, + }, + }, + Dependencies: []string{ + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1.CatalogOffering", v1.ListMeta{}.OpenAPIModelName()}, + } +} + +func schema_sdk_apis_marketplace_v1alpha1_OfferingClaim(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "OfferingClaim is one permission claim as the catalog shows it: what a consumer accepts when they enable the offering.\n\nIt is a projection of the APIExport's own spec.permissionClaims, never a separate declaration — so what the catalog advertises and what the binding will carry cannot drift apart.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "group": { + SchemaProps: spec.SchemaProps{ + Description: "Group and Resource name what is claimed, as kcp permission claims do.", + Type: []string{"string"}, + Format: "", + }, + }, + "resource": { + SchemaProps: spec.SchemaProps{ + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "verbs": { + SchemaProps: spec.SchemaProps{ + Description: "Verbs are the verbs claimed, as the export declares them.", + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Type: []string{"string"}, + Format: "", + }, + }, + }, + }, + }, + "identityHash": { + SchemaProps: spec.SchemaProps{ + Description: "IdentityHash is set when the claimed resource is itself served by an APIExport, copied from the claim.", + Type: []string{"string"}, + Format: "", + }, + }, + "matchLabels": { + SchemaProps: spec.SchemaProps{ + Description: "MatchLabels is the scope the producer suggests for this claim, from the claim's defaultSelector. Empty means the claim covers every object of that resource, which is what a consumer accepts by default.", + Type: []string{"object"}, + AdditionalProperties: &spec.SchemaOrBool{ + Allows: true, + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Type: []string{"string"}, + Format: "", + }, + }, + }, + }, + }, + }, + Required: []string{"resource", "verbs"}, + }, + }, + } +} + +func schema_sdk_apis_marketplace_v1alpha1_OfferingResource(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "OfferingResource is one resource an offering serves, projected from the APIResourceSchema the export references.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "group": { + SchemaProps: spec.SchemaProps{ + Description: "Group and Resource name it as the export does.", + Type: []string{"string"}, + Format: "", + }, + }, + "resource": { + SchemaProps: spec.SchemaProps{ + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "schema": { + SchemaProps: spec.SchemaProps{ + Description: "Schema is the APIResourceSchema's name in the producer's workspace.", + Type: []string{"string"}, + Format: "", + }, + }, + "kind": { + SchemaProps: spec.SchemaProps{ + Description: "Kind and Scope are the schema's.", + Type: []string{"string"}, + Format: "", + }, + }, + "scope": { + SchemaProps: spec.SchemaProps{ + Type: []string{"string"}, + Format: "", + }, + }, + "versions": { + SchemaProps: spec.SchemaProps{ + Description: "Versions are the schema's versions, in its order.", + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Ref: ref("github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1.OfferingResourceVersion"), + }, + }, + }, + }, + }, + }, + Required: []string{"resource"}, + }, + }, + Dependencies: []string{ + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1.OfferingResourceVersion"}, + } +} + +func schema_sdk_apis_marketplace_v1alpha1_OfferingResourceVersion(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "OfferingResourceVersion is one version of an offered resource.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "name": { + SchemaProps: spec.SchemaProps{ + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "served": { + SchemaProps: spec.SchemaProps{ + Default: false, + Type: []string{"boolean"}, + Format: "", + }, + }, + "storage": { + SchemaProps: spec.SchemaProps{ + Default: false, + Type: []string{"boolean"}, + Format: "", + }, + }, + "schema": { + SchemaProps: spec.SchemaProps{ + Description: "Schema is the version's OpenAPI v3 schema, verbatim.", + Ref: ref(runtime.RawExtension{}.OpenAPIModelName()), + }, + }, + }, + Required: []string{"name", "served", "storage"}, + }, + }, + Dependencies: []string{ + runtime.RawExtension{}.OpenAPIModelName()}, + } +} + +func schema_sdk_apis_marketplace_v1alpha1_Producer(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "Producer is the registration record: it says which workspace is allowed to publish offerings under this name. It lives in the catalog workspace and grants nothing by existing — the reach into a producer workspace comes from the marketplace-publish binding there, never from this record.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "kind": { + SchemaProps: spec.SchemaProps{ + Description: "Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", + Type: []string{"string"}, + Format: "", + }, + }, + "apiVersion": { + SchemaProps: spec.SchemaProps{ + Description: "APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources", + Type: []string{"string"}, + Format: "", + }, + }, + "metadata": { + SchemaProps: spec.SchemaProps{ + Default: map[string]interface{}{}, + Ref: ref(v1.ObjectMeta{}.OpenAPIModelName()), + }, + }, + "spec": { + SchemaProps: spec.SchemaProps{ + Default: map[string]interface{}{}, + Ref: ref("github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1.ProducerSpec"), + }, + }, + "status": { + SchemaProps: spec.SchemaProps{ + Default: map[string]interface{}{}, + Ref: ref("github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1.ProducerStatus"), + }, + }, + }, + Required: []string{"spec"}, + }, + }, + Dependencies: []string{ + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1.ProducerSpec", "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1.ProducerStatus", v1.ObjectMeta{}.OpenAPIModelName()}, + } +} + +func schema_sdk_apis_marketplace_v1alpha1_ProducerList(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "ProducerList is the list form of Producer.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "kind": { + SchemaProps: spec.SchemaProps{ + Description: "Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", + Type: []string{"string"}, + Format: "", + }, + }, + "apiVersion": { + SchemaProps: spec.SchemaProps{ + Description: "APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources", + Type: []string{"string"}, + Format: "", + }, + }, + "metadata": { + SchemaProps: spec.SchemaProps{ + Default: map[string]interface{}{}, + Ref: ref(v1.ListMeta{}.OpenAPIModelName()), + }, + }, + "items": { + SchemaProps: spec.SchemaProps{ + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Ref: ref("github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1.Producer"), + }, + }, + }, + }, + }, + }, + Required: []string{"items"}, + }, + }, + Dependencies: []string{ + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1.Producer", v1.ListMeta{}.OpenAPIModelName()}, + } +} + +func schema_sdk_apis_marketplace_v1alpha1_ProducerSpec(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "ProducerSpec is the desired state of a Producer.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "displayName": { + SchemaProps: spec.SchemaProps{ + Description: "DisplayName is the human name of the producer, shown in the catalog.", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "description": { + SchemaProps: spec.SchemaProps{ + Description: "Description is free text for humans.", + Type: []string{"string"}, + Format: "", + }, + }, + "mode": { + SchemaProps: spec.SchemaProps{ + Description: "Mode is provisioned or external.", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "workspacePath": { + SchemaProps: spec.SchemaProps{ + Description: "WorkspacePath is the canonical path of the producer's own workspace, for mode external. Ignored for mode provisioned, where the operator computes it.", + Type: []string{"string"}, + Format: "", + }, + }, + }, + Required: []string{"displayName", "mode"}, + }, + }, + } +} + +func schema_sdk_apis_marketplace_v1alpha1_ProducerStatus(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "ProducerStatus is the observed state of a Producer.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "phase": { + SchemaProps: spec.SchemaProps{ + Type: []string{"string"}, + Format: "", + }, + }, + "message": { + SchemaProps: spec.SchemaProps{ + Type: []string{"string"}, + Format: "", + }, + }, + "workspace": { + SchemaProps: spec.SchemaProps{ + Description: "Workspace is the name of the provisioned Workspace object, for mode provisioned.", + Type: []string{"string"}, + Format: "", + }, + }, + "workspacePath": { + SchemaProps: spec.SchemaProps{ + Description: "WorkspacePath is the canonical path of the producer's workspace — computed for provisioned, copied from spec for external. Offerings bind against it.", + Type: []string{"string"}, + Format: "", + }, + }, + "workspaceCluster": { + SchemaProps: spec.SchemaProps{ + Description: "WorkspaceCluster is the logical cluster backing the producer's workspace. For external producers it is learned when the first Offering is published from that workspace.", + Type: []string{"string"}, + Format: "", + }, + }, + "url": { + SchemaProps: spec.SchemaProps{ + Description: "URL is the direct address of the producer's workspace, when known.", + Type: []string{"string"}, + Format: "", + }, + }, + }, + }, + }, + } +} + +func schema_pkg_apis_meta_v1_APIGroup(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "APIGroup contains the name, the supported versions, and the preferred version of a group.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "kind": { + SchemaProps: spec.SchemaProps{ + Description: "Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", + Type: []string{"string"}, + Format: "", + }, + }, + "apiVersion": { + SchemaProps: spec.SchemaProps{ + Description: "APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources", + Type: []string{"string"}, + Format: "", + }, + }, + "name": { + SchemaProps: spec.SchemaProps{ + Description: "name is the name of the group.", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "versions": { + VendorExtensible: spec.VendorExtensible{ + Extensions: spec.Extensions{ + "x-kubernetes-list-type": "atomic", + }, + }, + SchemaProps: spec.SchemaProps{ + Description: "versions are the versions supported in this group.", + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Ref: ref(v1.GroupVersionForDiscovery{}.OpenAPIModelName()), + }, + }, + }, + }, + }, + "preferredVersion": { + SchemaProps: spec.SchemaProps{ + Description: "preferredVersion is the version preferred by the API server, which probably is the storage version.", + Default: map[string]interface{}{}, + Ref: ref(v1.GroupVersionForDiscovery{}.OpenAPIModelName()), + }, + }, + "serverAddressByClientCIDRs": { + VendorExtensible: spec.VendorExtensible{ + Extensions: spec.Extensions{ + "x-kubernetes-list-type": "atomic", + }, + }, + SchemaProps: spec.SchemaProps{ + Description: "a map of client CIDR to server address that is serving this group. This is to help clients reach servers in the most network-efficient way possible. Clients can use the appropriate server address as per the CIDR that they match. In case of multiple matches, clients should use the longest matching CIDR. The server returns only those CIDRs that it thinks that the client can match. For example: the master will return an internal IP CIDR only, if the client reaches the server using an internal IP. Server looks at X-Forwarded-For header or X-Real-Ip header or request.RemoteAddr (in that order) to get the client IP.", + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Ref: ref(v1.ServerAddressByClientCIDR{}.OpenAPIModelName()), + }, + }, + }, + }, + }, + }, + Required: []string{"name", "versions"}, + }, + }, + Dependencies: []string{ + v1.GroupVersionForDiscovery{}.OpenAPIModelName(), v1.ServerAddressByClientCIDR{}.OpenAPIModelName()}, + } +} + +func schema_pkg_apis_meta_v1_APIGroupList(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "APIGroupList is a list of APIGroup, to allow clients to discover the API at /apis.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "kind": { + SchemaProps: spec.SchemaProps{ + Description: "Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", + Type: []string{"string"}, + Format: "", + }, + }, + "apiVersion": { + SchemaProps: spec.SchemaProps{ + Description: "APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources", + Type: []string{"string"}, + Format: "", + }, + }, + "groups": { + VendorExtensible: spec.VendorExtensible{ + Extensions: spec.Extensions{ + "x-kubernetes-list-type": "atomic", + }, + }, + SchemaProps: spec.SchemaProps{ + Description: "groups is a list of APIGroup.", + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Ref: ref(v1.APIGroup{}.OpenAPIModelName()), + }, + }, + }, + }, + }, + }, + Required: []string{"groups"}, + }, + }, + Dependencies: []string{ + v1.APIGroup{}.OpenAPIModelName()}, + } +} + +func schema_pkg_apis_meta_v1_APIResource(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "APIResource specifies the name of a resource and whether it is namespaced.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "name": { + SchemaProps: spec.SchemaProps{ + Description: "name is the plural name of the resource.", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "singularName": { + SchemaProps: spec.SchemaProps{ + Description: "singularName is the singular name of the resource. This allows clients to handle plural and singular opaquely. The singularName is more correct for reporting status on a single item and both singular and plural are allowed from the kubectl CLI interface.", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "namespaced": { + SchemaProps: spec.SchemaProps{ + Description: "namespaced indicates if a resource is namespaced or not.", + Default: false, + Type: []string{"boolean"}, + Format: "", + }, + }, + "group": { + SchemaProps: spec.SchemaProps{ + Description: "group is the preferred group of the resource. Empty implies the group of the containing resource list. For subresources, this may have a different value, for example: Scale\".", + Type: []string{"string"}, + Format: "", + }, + }, + "version": { + SchemaProps: spec.SchemaProps{ + Description: "version is the preferred version of the resource. Empty implies the version of the containing resource list For subresources, this may have a different value, for example: v1 (while inside a v1beta1 version of the core resource's group)\".", + Type: []string{"string"}, + Format: "", + }, + }, + "kind": { + SchemaProps: spec.SchemaProps{ + Description: "kind is the kind for the resource (e.g. 'Foo' is the kind for a resource 'foo')", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "verbs": { + SchemaProps: spec.SchemaProps{ + Description: "verbs is a list of supported kube verbs (this includes get, list, watch, create, update, patch, delete, deletecollection, and proxy)", + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Type: []string{"string"}, + Format: "", + }, + }, + }, + }, + }, + "shortNames": { + VendorExtensible: spec.VendorExtensible{ + Extensions: spec.Extensions{ + "x-kubernetes-list-type": "atomic", + }, + }, + SchemaProps: spec.SchemaProps{ + Description: "shortNames is a list of suggested short names of the resource.", + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Type: []string{"string"}, + Format: "", + }, + }, + }, + }, + }, + "categories": { + VendorExtensible: spec.VendorExtensible{ + Extensions: spec.Extensions{ + "x-kubernetes-list-type": "atomic", + }, + }, + SchemaProps: spec.SchemaProps{ + Description: "categories is a list of the grouped resources this resource belongs to (e.g. 'all')", + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Type: []string{"string"}, + Format: "", + }, + }, + }, + }, + }, + "storageVersionHash": { + SchemaProps: spec.SchemaProps{ + Description: "The hash value of the storage version, the version this resource is converted to when written to the data store. Value must be treated as opaque by clients. Only equality comparison on the value is valid. This is an alpha feature and may change or be removed in the future. The field is populated by the apiserver only if the StorageVersionHash feature gate is enabled. This field will remain optional even if it graduates.", + Type: []string{"string"}, + Format: "", + }, + }, + }, + Required: []string{"name", "singularName", "namespaced", "kind", "verbs"}, + }, + }, + } +} + +func schema_pkg_apis_meta_v1_APIResourceList(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "APIResourceList is a list of APIResource, it is used to expose the name of the resources supported in a specific group and version, and if the resource is namespaced.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "kind": { + SchemaProps: spec.SchemaProps{ + Description: "Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", + Type: []string{"string"}, + Format: "", + }, + }, + "apiVersion": { + SchemaProps: spec.SchemaProps{ + Description: "APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources", + Type: []string{"string"}, + Format: "", + }, + }, + "groupVersion": { + SchemaProps: spec.SchemaProps{ + Description: "groupVersion is the group and version this APIResourceList is for.", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "resources": { + VendorExtensible: spec.VendorExtensible{ + Extensions: spec.Extensions{ + "x-kubernetes-list-type": "atomic", + }, + }, + SchemaProps: spec.SchemaProps{ + Description: "resources contains the name of the resources and if they are namespaced.", + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Ref: ref(v1.APIResource{}.OpenAPIModelName()), + }, + }, + }, + }, + }, + }, + Required: []string{"groupVersion", "resources"}, + }, + }, + Dependencies: []string{ + v1.APIResource{}.OpenAPIModelName()}, + } +} + +func schema_pkg_apis_meta_v1_APIVersions(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "APIVersions lists the versions that are available, to allow clients to discover the API at /api, which is the root path of the legacy v1 API.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "kind": { + SchemaProps: spec.SchemaProps{ + Description: "Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", + Type: []string{"string"}, + Format: "", + }, + }, + "apiVersion": { + SchemaProps: spec.SchemaProps{ + Description: "APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources", + Type: []string{"string"}, + Format: "", + }, + }, + "versions": { + VendorExtensible: spec.VendorExtensible{ + Extensions: spec.Extensions{ + "x-kubernetes-list-type": "atomic", + }, + }, + SchemaProps: spec.SchemaProps{ + Description: "versions are the api versions that are available.", + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Type: []string{"string"}, + Format: "", + }, + }, + }, + }, + }, + "serverAddressByClientCIDRs": { + VendorExtensible: spec.VendorExtensible{ + Extensions: spec.Extensions{ + "x-kubernetes-list-type": "atomic", + }, + }, + SchemaProps: spec.SchemaProps{ + Description: "a map of client CIDR to server address that is serving this group. This is to help clients reach servers in the most network-efficient way possible. Clients can use the appropriate server address as per the CIDR that they match. In case of multiple matches, clients should use the longest matching CIDR. The server returns only those CIDRs that it thinks that the client can match. For example: the master will return an internal IP CIDR only, if the client reaches the server using an internal IP. Server looks at X-Forwarded-For header or X-Real-Ip header or request.RemoteAddr (in that order) to get the client IP.", + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Ref: ref(v1.ServerAddressByClientCIDR{}.OpenAPIModelName()), + }, + }, + }, + }, + }, + }, + Required: []string{"versions", "serverAddressByClientCIDRs"}, + }, + }, + Dependencies: []string{ + v1.ServerAddressByClientCIDR{}.OpenAPIModelName()}, + } +} + +func schema_pkg_apis_meta_v1_ApplyOptions(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "ApplyOptions may be provided when applying an API object. FieldManager is required for apply requests. ApplyOptions is equivalent to PatchOptions. It is provided as a convenience with documentation that speaks specifically to how the options fields relate to apply.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "kind": { + SchemaProps: spec.SchemaProps{ + Description: "Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", + Type: []string{"string"}, + Format: "", + }, + }, + "apiVersion": { + SchemaProps: spec.SchemaProps{ + Description: "APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources", + Type: []string{"string"}, + Format: "", + }, + }, + "dryRun": { + VendorExtensible: spec.VendorExtensible{ + Extensions: spec.Extensions{ + "x-kubernetes-list-type": "atomic", + }, + }, + SchemaProps: spec.SchemaProps{ + Description: "When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed", + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Type: []string{"string"}, + Format: "", + }, + }, + }, + }, + }, + "force": { + SchemaProps: spec.SchemaProps{ + Description: "Force is going to \"force\" Apply requests. It means user will re-acquire conflicting fields owned by other people.", + Default: false, + Type: []string{"boolean"}, + Format: "", + }, + }, + "fieldManager": { + SchemaProps: spec.SchemaProps{ + Description: "fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required.", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + }, + Required: []string{"force", "fieldManager"}, + }, + }, + } +} + +func schema_pkg_apis_meta_v1_Condition(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "Condition contains details for one aspect of the current state of this API Resource.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "type": { + SchemaProps: spec.SchemaProps{ + Description: "type of condition in CamelCase or in foo.example.com/CamelCase.", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "status": { + SchemaProps: spec.SchemaProps{ + Description: "status of the condition, one of True, False, Unknown.", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "observedGeneration": { + SchemaProps: spec.SchemaProps{ + Description: "observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance.", + Type: []string{"integer"}, + Format: "int64", + }, + }, + "lastTransitionTime": { + SchemaProps: spec.SchemaProps{ + Description: "lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.", + Ref: ref(v1.Time{}.OpenAPIModelName()), + }, + }, + "reason": { + SchemaProps: spec.SchemaProps{ + Description: "reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty.", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "message": { + SchemaProps: spec.SchemaProps{ + Description: "message is a human readable message indicating details about the transition. This may be an empty string.", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + }, + Required: []string{"type", "status", "lastTransitionTime", "reason", "message"}, + }, + }, + Dependencies: []string{ + v1.Time{}.OpenAPIModelName()}, + } +} + +func schema_pkg_apis_meta_v1_CreateOptions(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "CreateOptions may be provided when creating an API object.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "kind": { + SchemaProps: spec.SchemaProps{ + Description: "Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", + Type: []string{"string"}, + Format: "", + }, + }, + "apiVersion": { + SchemaProps: spec.SchemaProps{ + Description: "APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources", + Type: []string{"string"}, + Format: "", + }, + }, + "dryRun": { + VendorExtensible: spec.VendorExtensible{ + Extensions: spec.Extensions{ + "x-kubernetes-list-type": "atomic", + }, + }, + SchemaProps: spec.SchemaProps{ + Description: "When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed", + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Type: []string{"string"}, + Format: "", + }, + }, + }, + }, + }, + "fieldManager": { + SchemaProps: spec.SchemaProps{ + Description: "fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.", + Type: []string{"string"}, + Format: "", + }, + }, + "fieldValidation": { + SchemaProps: spec.SchemaProps{ + Description: "fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered.", + Type: []string{"string"}, + Format: "", + }, + }, + }, + }, + }, + } +} + +func schema_pkg_apis_meta_v1_DeleteOptions(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "DeleteOptions may be provided when deleting an API object.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "kind": { + SchemaProps: spec.SchemaProps{ + Description: "Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", + Type: []string{"string"}, + Format: "", + }, + }, + "apiVersion": { + SchemaProps: spec.SchemaProps{ + Description: "APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources", + Type: []string{"string"}, + Format: "", + }, + }, + "gracePeriodSeconds": { + SchemaProps: spec.SchemaProps{ + Description: "The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately.", + Type: []string{"integer"}, + Format: "int64", + }, + }, + "preconditions": { + SchemaProps: spec.SchemaProps{ + Description: "Must be fulfilled before a deletion is carried out. If not possible, a 409 Conflict status will be returned.", + Ref: ref(v1.Preconditions{}.OpenAPIModelName()), + }, + }, + "orphanDependents": { + SchemaProps: spec.SchemaProps{ + Description: "Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the \"orphan\" finalizer will be added to/removed from the object's finalizers list. Either this field or PropagationPolicy may be set, but not both.", + Type: []string{"boolean"}, + Format: "", + }, + }, + "propagationPolicy": { + SchemaProps: spec.SchemaProps{ + Description: "Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: 'Orphan' - orphan the dependents; 'Background' - allow the garbage collector to delete the dependents in the background; 'Foreground' - a cascading policy that deletes all dependents in the foreground.", + Type: []string{"string"}, + Format: "", + }, + }, + "dryRun": { + VendorExtensible: spec.VendorExtensible{ + Extensions: spec.Extensions{ + "x-kubernetes-list-type": "atomic", + }, + }, + SchemaProps: spec.SchemaProps{ + Description: "When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed", + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Type: []string{"string"}, + Format: "", + }, + }, + }, + }, + }, + "ignoreStoreReadErrorWithClusterBreakingPotential": { + SchemaProps: spec.SchemaProps{ + Description: "if set to true, it will trigger an unsafe deletion of the resource in case the normal deletion flow fails with a corrupt object error. A resource is considered corrupt if it can not be retrieved from the underlying storage successfully because of a) its data can not be transformed e.g. decryption failure, or b) it fails to decode into an object. NOTE: unsafe deletion ignores finalizer constraints, skips precondition checks, and removes the object from the storage. WARNING: This may potentially break the cluster if the workload associated with the resource being unsafe-deleted relies on normal deletion flow. Use only if you REALLY know what you are doing. The default value is false, and the user must opt in to enable it", + Type: []string{"boolean"}, + Format: "", + }, + }, + }, + }, + }, + Dependencies: []string{ + v1.Preconditions{}.OpenAPIModelName()}, + } +} + +func schema_pkg_apis_meta_v1_Duration(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "Duration is a wrapper around time.Duration which supports correct marshaling to YAML and JSON. In particular, it marshals into strings, which can be used as map keys in json.", + Type: v1.Duration{}.OpenAPISchemaType(), + Format: v1.Duration{}.OpenAPISchemaFormat(), + }, + }, + } +} + +func schema_pkg_apis_meta_v1_FieldSelectorRequirement(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "FieldSelectorRequirement is a selector that contains values, a key, and an operator that relates the key and values.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "key": { + SchemaProps: spec.SchemaProps{ + Description: "key is the field selector key that the requirement applies to.", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "operator": { + SchemaProps: spec.SchemaProps{ + Description: "operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists, DoesNotExist. The list of operators may grow in the future.", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "values": { + VendorExtensible: spec.VendorExtensible{ + Extensions: spec.Extensions{ + "x-kubernetes-list-type": "atomic", + }, + }, + SchemaProps: spec.SchemaProps{ + Description: "values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty.", + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Type: []string{"string"}, + Format: "", + }, + }, + }, + }, + }, + }, + Required: []string{"key", "operator"}, + }, + }, + } +} + +func schema_pkg_apis_meta_v1_FieldsV1(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "FieldsV1 stores a set of fields in a data structure like a Trie, in JSON format.\n\nEach key is either a '.' representing the field itself, and will always map to an empty set, or a string representing a sub-field or item. The string will follow one of these four formats: 'f:', where is the name of a field in a struct, or key in a map 'v:', where is the exact json formatted value of a list item 'i:', where is position of a item in a list 'k:', where is a map of a list item's key fields to their unique values If a key maps to an empty Fields value, the field that key represents is part of the set.\n\nThe exact format is defined in sigs.k8s.io/structured-merge-diff", + Type: []string{"object"}, + }, + }, + } +} + +func schema_pkg_apis_meta_v1_GetOptions(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "GetOptions is the standard query options to the standard REST get call.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "kind": { + SchemaProps: spec.SchemaProps{ + Description: "Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", + Type: []string{"string"}, + Format: "", + }, + }, + "apiVersion": { + SchemaProps: spec.SchemaProps{ + Description: "APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources", + Type: []string{"string"}, + Format: "", + }, + }, + "resourceVersion": { + SchemaProps: spec.SchemaProps{ + Description: "resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.\n\nDefaults to unset", + Type: []string{"string"}, + Format: "", + }, + }, + }, + }, + }, + } +} + +func schema_pkg_apis_meta_v1_GroupKind(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "GroupKind specifies a Group and a Kind, but does not force a version. This is useful for identifying concepts during lookup stages without having partially valid types", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "group": { + SchemaProps: spec.SchemaProps{ + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "kind": { + SchemaProps: spec.SchemaProps{ + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + }, + Required: []string{"group", "kind"}, + }, + }, + } +} + +func schema_pkg_apis_meta_v1_GroupResource(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "GroupResource specifies a Group and a Resource, but does not force a version. This is useful for identifying concepts during lookup stages without having partially valid types", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "group": { + SchemaProps: spec.SchemaProps{ + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "resource": { + SchemaProps: spec.SchemaProps{ + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + }, + Required: []string{"group", "resource"}, + }, + }, + } +} + +func schema_pkg_apis_meta_v1_GroupVersion(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "GroupVersion contains the \"group\" and the \"version\", which uniquely identifies the API.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "group": { + SchemaProps: spec.SchemaProps{ + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "version": { + SchemaProps: spec.SchemaProps{ + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + }, + Required: []string{"group", "version"}, + }, + }, + } +} + +func schema_pkg_apis_meta_v1_GroupVersionForDiscovery(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "GroupVersion contains the \"group/version\" and \"version\" string of a version. It is made a struct to keep extensibility.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "groupVersion": { + SchemaProps: spec.SchemaProps{ + Description: "groupVersion specifies the API group and version in the form \"group/version\"", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "version": { + SchemaProps: spec.SchemaProps{ + Description: "version specifies the version in the form of \"version\". This is to save the clients the trouble of splitting the GroupVersion.", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + }, + Required: []string{"groupVersion", "version"}, + }, + }, + } +} + +func schema_pkg_apis_meta_v1_GroupVersionKind(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "GroupVersionKind unambiguously identifies a kind. It doesn't anonymously include GroupVersion to avoid automatic coercion. It doesn't use a GroupVersion to avoid custom marshalling", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "group": { + SchemaProps: spec.SchemaProps{ + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "version": { + SchemaProps: spec.SchemaProps{ + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "kind": { + SchemaProps: spec.SchemaProps{ + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + }, + Required: []string{"group", "version", "kind"}, + }, + }, + } +} + +func schema_pkg_apis_meta_v1_GroupVersionResource(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "GroupVersionResource unambiguously identifies a resource. It doesn't anonymously include GroupVersion to avoid automatic coercion. It doesn't use a GroupVersion to avoid custom marshalling", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "group": { + SchemaProps: spec.SchemaProps{ + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "version": { + SchemaProps: spec.SchemaProps{ + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "resource": { + SchemaProps: spec.SchemaProps{ + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + }, + Required: []string{"group", "version", "resource"}, + }, + }, + } +} + +func schema_pkg_apis_meta_v1_InternalEvent(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "InternalEvent makes watch.Event versioned", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "Type": { + SchemaProps: spec.SchemaProps{ + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "Object": { + SchemaProps: spec.SchemaProps{ + Description: "Object is:\n * If Type is Added or Modified: the new state of the object.\n * If Type is Deleted: the state of the object immediately before deletion.\n * If Type is Bookmark: the object (instance of a type being watched) where\n only ResourceVersion field is set. On successful restart of watch from a\n bookmark resourceVersion, client is guaranteed to not get repeat event\n nor miss any events.\n * If Type is Error: *api.Status is recommended; other types may make sense\n depending on context.", + }, + }, + }, + Required: []string{"Type", "Object"}, + }, + }, + } +} + +func schema_pkg_apis_meta_v1_LabelSelector(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "A label selector is a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. An empty label selector matches all objects. A null label selector matches no objects.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "matchLabels": { + SchemaProps: spec.SchemaProps{ + Description: "matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is \"key\", the operator is \"In\", and the values array contains only \"value\". The requirements are ANDed.", + Type: []string{"object"}, + AdditionalProperties: &spec.SchemaOrBool{ + Allows: true, + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Type: []string{"string"}, + Format: "", + }, + }, + }, + }, + }, + "matchExpressions": { + VendorExtensible: spec.VendorExtensible{ + Extensions: spec.Extensions{ + "x-kubernetes-list-type": "atomic", + }, + }, + SchemaProps: spec.SchemaProps{ + Description: "matchExpressions is a list of label selector requirements. The requirements are ANDed.", + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Ref: ref(v1.LabelSelectorRequirement{}.OpenAPIModelName()), + }, + }, + }, + }, + }, + }, + }, + VendorExtensible: spec.VendorExtensible{ + Extensions: spec.Extensions{ + "x-kubernetes-map-type": "atomic", + }, + }, + }, + Dependencies: []string{ + v1.LabelSelectorRequirement{}.OpenAPIModelName()}, + } +} + +func schema_pkg_apis_meta_v1_LabelSelectorRequirement(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "key": { + SchemaProps: spec.SchemaProps{ + Description: "key is the label key that the selector applies to.", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "operator": { + SchemaProps: spec.SchemaProps{ + Description: "operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist.", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "values": { + VendorExtensible: spec.VendorExtensible{ + Extensions: spec.Extensions{ + "x-kubernetes-list-type": "atomic", + }, + }, + SchemaProps: spec.SchemaProps{ + Description: "values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch.", + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Type: []string{"string"}, + Format: "", + }, + }, + }, + }, + }, + }, + Required: []string{"key", "operator"}, + }, + }, + } +} + +func schema_pkg_apis_meta_v1_List(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "List holds a list of objects, which may not be known by the server.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "kind": { + SchemaProps: spec.SchemaProps{ + Description: "Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", + Type: []string{"string"}, + Format: "", + }, + }, + "apiVersion": { + SchemaProps: spec.SchemaProps{ + Description: "APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources", + Type: []string{"string"}, + Format: "", + }, + }, + "metadata": { + SchemaProps: spec.SchemaProps{ + Description: "Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", + Default: map[string]interface{}{}, + Ref: ref(v1.ListMeta{}.OpenAPIModelName()), + }, + }, + "items": { + SchemaProps: spec.SchemaProps{ + Description: "List of objects", + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Ref: ref(runtime.RawExtension{}.OpenAPIModelName()), + }, + }, + }, + }, + }, + }, + Required: []string{"items"}, + }, + }, + Dependencies: []string{ + v1.ListMeta{}.OpenAPIModelName(), runtime.RawExtension{}.OpenAPIModelName()}, + } +} + +func schema_pkg_apis_meta_v1_ListMeta(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "ListMeta describes metadata that synthetic resources must have, including lists and various status objects. A resource may have only one of {ObjectMeta, ListMeta}.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "selfLink": { + SchemaProps: spec.SchemaProps{ + Description: "Deprecated: selfLink is a legacy read-only field that is no longer populated by the system.", + Type: []string{"string"}, + Format: "", + }, + }, + "resourceVersion": { + SchemaProps: spec.SchemaProps{ + Description: "String that identifies the server's internal version of this object that can be used by clients to determine when objects have changed. Value must be treated as opaque by clients and passed unmodified back to the server. Populated by the system. Read-only. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#concurrency-control-and-consistency", + Type: []string{"string"}, + Format: "", + }, + }, + "continue": { + SchemaProps: spec.SchemaProps{ + Description: "continue may be set if the user set a limit on the number of items returned, and indicates that the server has more data available. The value is opaque and may be used to issue another request to the endpoint that served this list to retrieve the next set of available objects. Continuing a consistent list may not be possible if the server configuration has changed or more than a few minutes have passed. The resourceVersion field returned when using this continue value will be identical to the value in the first response, unless you have received this token from an error message.", + Type: []string{"string"}, + Format: "", + }, + }, + "remainingItemCount": { + SchemaProps: spec.SchemaProps{ + Description: "remainingItemCount is the number of subsequent items in the list which are not included in this list response. If the list request contained label or field selectors, then the number of remaining items is unknown and the field will be left unset and omitted during serialization. If the list is complete (either because it is not chunking or because this is the last chunk), then there are no more remaining items and this field will be left unset and omitted during serialization. Servers older than v1.15 do not set this field. The intended use of the remainingItemCount is *estimating* the size of a collection. Clients should not rely on the remainingItemCount to be set or to be exact.", + Type: []string{"integer"}, + Format: "int64", + }, + }, + "shardInfo": { + SchemaProps: spec.SchemaProps{ + Description: "shardInfo is set when the list is a filtered subset of the full collection, as selected by a shard selector on the request. It echoes back the selector so clients can verify which shard they received and merge sharded responses. Clients should not cache sharded list responses as a full representation of the collection.\n\nThis is an alpha field and requires enabling the ShardedListAndWatch feature gate.", + Ref: ref(v1.ShardInfo{}.OpenAPIModelName()), + }, + }, + }, + }, + }, + Dependencies: []string{ + v1.ShardInfo{}.OpenAPIModelName()}, + } +} + +func schema_pkg_apis_meta_v1_ListOptions(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "ListOptions is the query options to a standard REST list call.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "kind": { + SchemaProps: spec.SchemaProps{ + Description: "Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", + Type: []string{"string"}, + Format: "", + }, + }, + "apiVersion": { + SchemaProps: spec.SchemaProps{ + Description: "APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources", + Type: []string{"string"}, + Format: "", + }, + }, + "labelSelector": { + SchemaProps: spec.SchemaProps{ + Description: "A selector to restrict the list of returned objects by their labels. Defaults to everything.", + Type: []string{"string"}, + Format: "", + }, + }, + "fieldSelector": { + SchemaProps: spec.SchemaProps{ + Description: "A selector to restrict the list of returned objects by their fields. Defaults to everything.", + Type: []string{"string"}, + Format: "", + }, + }, + "watch": { + SchemaProps: spec.SchemaProps{ + Description: "Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion.", + Type: []string{"boolean"}, + Format: "", + }, + }, + "allowWatchBookmarks": { + SchemaProps: spec.SchemaProps{ + Description: "allowWatchBookmarks requests watch events with type \"BOOKMARK\". Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server's discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored.", + Type: []string{"boolean"}, + Format: "", + }, + }, + "resourceVersion": { + SchemaProps: spec.SchemaProps{ + Description: "resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.\n\nDefaults to unset", + Type: []string{"string"}, + Format: "", + }, + }, + "resourceVersionMatch": { + SchemaProps: spec.SchemaProps{ + Description: "resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.\n\nDefaults to unset", + Type: []string{"string"}, + Format: "", + }, + }, + "timeoutSeconds": { + SchemaProps: spec.SchemaProps{ + Description: "Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity.", + Type: []string{"integer"}, + Format: "int64", + }, + }, + "limit": { + SchemaProps: spec.SchemaProps{ + Description: "limit is a maximum number of responses to return for a list call. If more items exist, the server will set the `continue` field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true.\n\nThe server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned.", + Type: []string{"integer"}, + Format: "int64", + }, + }, + "continue": { + SchemaProps: spec.SchemaProps{ + Description: "The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the \"next key\".\n\nThis field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications.", + Type: []string{"string"}, + Format: "", + }, + }, + "sendInitialEvents": { + SchemaProps: spec.SchemaProps{ + Description: "`sendInitialEvents=true` may be set together with `watch=true`. In that case, the watch stream will begin with synthetic events to produce the current state of objects in the collection. Once all such events have been sent, a synthetic \"Bookmark\" event will be sent. The bookmark will report the ResourceVersion (RV) corresponding to the set of objects, and be marked with `\"k8s.io/initial-events-end\": \"true\"` annotation. Afterwards, the watch stream will proceed as usual, sending watch events corresponding to changes (subsequent to the RV) to objects watched.\n\nWhen `sendInitialEvents` option is set, we require `resourceVersionMatch` option to also be set. The semantic of the watch request is as following: - `resourceVersionMatch` = NotOlderThan\n is interpreted as \"data at least as new as the provided `resourceVersion`\"\n and the bookmark event is send when the state is synced\n to a `resourceVersion` at least as fresh as the one provided by the ListOptions.\n If `resourceVersion` is unset, this is interpreted as \"consistent read\" and the\n bookmark event is send when the state is synced at least to the moment\n when request started being processed.\n- `resourceVersionMatch` set to any other value or unset\n Invalid error is returned.\n\nDefaults to true if `resourceVersion=\"\"` or `resourceVersion=\"0\"` (for backward compatibility reasons) and to false otherwise.", + Type: []string{"boolean"}, + Format: "", + }, + }, + "shardSelector": { + SchemaProps: spec.SchemaProps{ + Description: "shardSelector restricts the list of returned objects using a CEL-based shard selector expression. The format uses the shardRange() function combined with || (logical OR) to specify one or more hash ranges:\n\n shardRange(object.metadata.uid, '0x0', '0x8000000000000000')\n shardRange(object.metadata.uid, '0x0', '0x8000000000000000') || shardRange(object.metadata.uid, '0x8000000000000000', '0x10000000000000000')\n\nField paths use CEL-style object-rooted syntax (e.g. \"object.metadata.uid\"), NOT the fieldSelector format (\"metadata.uid\"). Currently supported paths:\n - object.metadata.uid\n - object.metadata.namespace\n\nhexStart and hexEnd are single-quoted CEL string literals with a '0x' prefix, defining the inclusive lower and exclusive upper bounds over the 64-bit FNV-1a hash space. The full range is [0x0, 0x10000000000000000), where the exclusive upper bound equals 2^64.\n\nExamples:\n 2-shard split:\n shard 0: shardRange(object.metadata.uid, '0x0000000000000000', '0x8000000000000000')\n shard 1: shardRange(object.metadata.uid, '0x8000000000000000', '0x10000000000000000')\n 4-shard split:\n shard 0: shardRange(object.metadata.uid, '0x0000000000000000', '0x4000000000000000')\n shard 1: shardRange(object.metadata.uid, '0x4000000000000000', '0x8000000000000000')\n shard 2: shardRange(object.metadata.uid, '0x8000000000000000', '0xc000000000000000')\n shard 3: shardRange(object.metadata.uid, '0xc000000000000000', '0x10000000000000000')\n\nThis is an alpha field and requires enabling the ShardedListAndWatch feature gate.", + Type: []string{"string"}, + Format: "", + }, + }, + }, + }, + }, + } +} + +func schema_pkg_apis_meta_v1_ManagedFieldsEntry(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "ManagedFieldsEntry is a workflow-id, a FieldSet and the group version of the resource that the fieldset applies to.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "manager": { + SchemaProps: spec.SchemaProps{ + Description: "Manager is an identifier of the workflow managing these fields.", + Type: []string{"string"}, + Format: "", + }, + }, + "operation": { + SchemaProps: spec.SchemaProps{ + Description: "Operation is the type of operation which lead to this ManagedFieldsEntry being created. The only valid values for this field are 'Apply' and 'Update'.", + Type: []string{"string"}, + Format: "", + }, + }, + "apiVersion": { + SchemaProps: spec.SchemaProps{ + Description: "APIVersion defines the version of this resource that this field set applies to. The format is \"group/version\" just like the top-level APIVersion field. It is necessary to track the version of a field set because it cannot be automatically converted.", + Type: []string{"string"}, + Format: "", + }, + }, + "time": { + SchemaProps: spec.SchemaProps{ + Description: "Time is the timestamp of when the ManagedFields entry was added. The timestamp will also be updated if a field is added, the manager changes any of the owned fields value or removes a field. The timestamp does not update when a field is removed from the entry because another manager took it over.", + Ref: ref(v1.Time{}.OpenAPIModelName()), + }, + }, + "fieldsType": { + SchemaProps: spec.SchemaProps{ + Description: "FieldsType is the discriminator for the different fields format and version. There is currently only one possible value: \"FieldsV1\"", + Type: []string{"string"}, + Format: "", + }, + }, + "fieldsV1": { + SchemaProps: spec.SchemaProps{ + Description: "FieldsV1 holds the first JSON version format as described in the \"FieldsV1\" type.", + Ref: ref(v1.FieldsV1{}.OpenAPIModelName()), + }, + }, + "subresource": { + SchemaProps: spec.SchemaProps{ + Description: "Subresource is the name of the subresource used to update that object, or empty string if the object was updated through the main resource. The value of this field is used to distinguish between managers, even if they share the same name. For example, a status update will be distinct from a regular update using the same manager name. Note that the APIVersion field is not related to the Subresource field and it always corresponds to the version of the main resource.", + Type: []string{"string"}, + Format: "", + }, + }, + }, + }, + }, + Dependencies: []string{ + v1.FieldsV1{}.OpenAPIModelName(), v1.Time{}.OpenAPIModelName()}, + } +} + +func schema_pkg_apis_meta_v1_MicroTime(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "MicroTime is version of Time with microsecond level precision.", + Type: v1.MicroTime{}.OpenAPISchemaType(), + Format: v1.MicroTime{}.OpenAPISchemaFormat(), + }, + }, + } +} + +func schema_pkg_apis_meta_v1_ObjectMeta(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "name": { + SchemaProps: spec.SchemaProps{ + Description: "Name must be unique within a namespace. Is required when creating resources, although some resources may allow a client to request the generation of an appropriate name automatically. Name is primarily intended for creation idempotence and configuration definition. Cannot be updated. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names#names", + Type: []string{"string"}, + Format: "", + }, + }, + "generateName": { + SchemaProps: spec.SchemaProps{ + Description: "GenerateName is an optional prefix, used by the server, to generate a unique name ONLY IF the Name field has not been provided. If this field is used, the name returned to the client will be different than the name passed. This value will also be combined with a unique suffix. The provided value has the same validation rules as the Name field, and may be truncated by the length of the suffix required to make the value unique on the server.\n\nIf this field is specified and the generated name exists, the server will return a 409.\n\nApplied only if Name is not specified. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#idempotency", + Type: []string{"string"}, + Format: "", + }, + }, + "namespace": { + SchemaProps: spec.SchemaProps{ + Description: "Namespace defines the space within which each name must be unique. An empty namespace is equivalent to the \"default\" namespace, but \"default\" is the canonical representation. Not all objects are required to be scoped to a namespace - the value of this field for those objects will be empty.\n\nMust be a DNS_LABEL. Cannot be updated. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces", + Type: []string{"string"}, + Format: "", + }, + }, + "selfLink": { + SchemaProps: spec.SchemaProps{ + Description: "Deprecated: selfLink is a legacy read-only field that is no longer populated by the system.", + Type: []string{"string"}, + Format: "", + }, + }, + "uid": { + SchemaProps: spec.SchemaProps{ + Description: "UID is the unique in time and space value for this object. It is typically generated by the server on successful creation of a resource and is not allowed to change on PUT operations.\n\nPopulated by the system. Read-only. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names#uids", + Type: []string{"string"}, + Format: "", + }, + }, + "resourceVersion": { + SchemaProps: spec.SchemaProps{ + Description: "An opaque value that represents the internal version of this object that can be used by clients to determine when objects have changed. May be used for optimistic concurrency, change detection, and the watch operation on a resource or set of resources. Clients must treat these values as opaque and passed unmodified back to the server. They may only be valid for a particular resource or set of resources.\n\nPopulated by the system. Read-only. Value must be treated as opaque by clients and . More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#concurrency-control-and-consistency", + Type: []string{"string"}, + Format: "", + }, + }, + "generation": { + SchemaProps: spec.SchemaProps{ + Description: "A sequence number representing a specific generation of the desired state. Populated by the system. Read-only.", + Type: []string{"integer"}, + Format: "int64", + }, + }, + "creationTimestamp": { + SchemaProps: spec.SchemaProps{ + Description: "CreationTimestamp is a timestamp representing the server time when this object was created. It is not guaranteed to be set in happens-before order across separate operations. Clients may not set this value. It is represented in RFC3339 form and is in UTC.\n\nPopulated by the system. Read-only. Null for lists. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata", + Ref: ref(v1.Time{}.OpenAPIModelName()), + }, + }, + "deletionTimestamp": { + SchemaProps: spec.SchemaProps{ + Description: "DeletionTimestamp is RFC 3339 date and time at which this resource will be deleted. This field is set by the server when a graceful deletion is requested by the user, and is not directly settable by a client. The resource is expected to be deleted (no longer visible from resource lists, and not reachable by name) after the time in this field, once the finalizers list is empty. As long as the finalizers list contains items, deletion is blocked. Once the deletionTimestamp is set, this value may not be unset or be set further into the future, although it may be shortened or the resource may be deleted prior to this time. For example, a user may request that a pod is deleted in 30 seconds. The Kubelet will react by sending a graceful termination signal to the containers in the pod. After that 30 seconds, the Kubelet will send a hard termination signal (SIGKILL) to the container and after cleanup, remove the pod from the API. In the presence of network partitions, this object may still exist after this timestamp, until an administrator or automated process can determine the resource is fully terminated. If not set, graceful deletion of the object has not been requested.\n\nPopulated by the system when a graceful deletion is requested. Read-only. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata", + Ref: ref(v1.Time{}.OpenAPIModelName()), + }, + }, + "deletionGracePeriodSeconds": { + SchemaProps: spec.SchemaProps{ + Description: "Number of seconds allowed for this object to gracefully terminate before it will be removed from the system. Only set when deletionTimestamp is also set. May only be shortened. Read-only.", + Type: []string{"integer"}, + Format: "int64", + }, + }, + "labels": { + SchemaProps: spec.SchemaProps{ + Description: "Map of string keys and values that can be used to organize and categorize (scope and select) objects. May match selectors of replication controllers and services. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels", + Type: []string{"object"}, + AdditionalProperties: &spec.SchemaOrBool{ + Allows: true, + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Type: []string{"string"}, + Format: "", + }, + }, + }, + }, + }, + "annotations": { + SchemaProps: spec.SchemaProps{ + Description: "Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations", + Type: []string{"object"}, + AdditionalProperties: &spec.SchemaOrBool{ + Allows: true, + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Type: []string{"string"}, + Format: "", + }, + }, + }, + }, + }, + "ownerReferences": { + VendorExtensible: spec.VendorExtensible{ + Extensions: spec.Extensions{ + "x-kubernetes-list-map-keys": []interface{}{ + "uid", + }, + "x-kubernetes-list-type": "map", + "x-kubernetes-patch-merge-key": "uid", + "x-kubernetes-patch-strategy": "merge", + }, + }, + SchemaProps: spec.SchemaProps{ + Description: "List of objects depended by this object. If ALL objects in the list have been deleted, this object will be garbage collected. If this object is managed by a controller, then an entry in this list will point to this controller, with the controller field set to true. There cannot be more than one managing controller.", + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Ref: ref(v1.OwnerReference{}.OpenAPIModelName()), + }, + }, + }, + }, + }, + "finalizers": { + VendorExtensible: spec.VendorExtensible{ + Extensions: spec.Extensions{ + "x-kubernetes-list-type": "set", + "x-kubernetes-patch-strategy": "merge", + }, + }, + SchemaProps: spec.SchemaProps{ + Description: "Must be empty before the object is deleted from the registry. Each entry is an identifier for the responsible component that will remove the entry from the list. If the deletionTimestamp of the object is non-nil, entries in this list can only be removed. Finalizers may be processed and removed in any order. Order is NOT enforced because it introduces significant risk of stuck finalizers. finalizers is a shared field, any actor with permission can reorder it. If the finalizer list is processed in order, then this can lead to a situation in which the component responsible for the first finalizer in the list is waiting for a signal (field value, external system, or other) produced by a component responsible for a finalizer later in the list, resulting in a deadlock. Without enforced ordering finalizers are free to order amongst themselves and are not vulnerable to ordering changes in the list.", + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Type: []string{"string"}, + Format: "", + }, + }, + }, + }, + }, + "managedFields": { + VendorExtensible: spec.VendorExtensible{ + Extensions: spec.Extensions{ + "x-kubernetes-list-type": "atomic", + }, + }, + SchemaProps: spec.SchemaProps{ + Description: "ManagedFields maps workflow-id and version to the set of fields that are managed by that workflow. This is mostly for internal housekeeping, and users typically shouldn't need to set or understand this field. A workflow can be the user's name, a controller's name, or the name of a specific apply path like \"ci-cd\". The set of fields is always in the version that the workflow used when modifying the object.", + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Ref: ref(v1.ManagedFieldsEntry{}.OpenAPIModelName()), + }, + }, + }, + }, + }, + }, + }, + }, + Dependencies: []string{ + v1.ManagedFieldsEntry{}.OpenAPIModelName(), v1.OwnerReference{}.OpenAPIModelName(), v1.Time{}.OpenAPIModelName()}, + } +} + +func schema_pkg_apis_meta_v1_OwnerReference(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "OwnerReference contains enough information to let you identify an owning object. An owning object must be in the same namespace as the dependent, or be cluster-scoped, so there is no namespace field.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "apiVersion": { + SchemaProps: spec.SchemaProps{ + Description: "API version of the referent.", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "kind": { + SchemaProps: spec.SchemaProps{ + Description: "Kind of the referent. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "name": { + SchemaProps: spec.SchemaProps{ + Description: "Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names#names", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "uid": { + SchemaProps: spec.SchemaProps{ + Description: "UID of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names#uids", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "controller": { + SchemaProps: spec.SchemaProps{ + Description: "If true, this reference points to the managing controller.", + Type: []string{"boolean"}, + Format: "", + }, + }, + "blockOwnerDeletion": { + SchemaProps: spec.SchemaProps{ + Description: "If true, AND if the owner has the \"foregroundDeletion\" finalizer, then the owner cannot be deleted from the key-value store until this reference is removed. See https://kubernetes.io/docs/concepts/architecture/garbage-collection/#foreground-deletion for how the garbage collector interacts with this field and enforces the foreground deletion. Defaults to false. To set this field, a user needs \"delete\" permission of the owner, otherwise 422 (Unprocessable Entity) will be returned.", + Type: []string{"boolean"}, + Format: "", + }, + }, + }, + Required: []string{"apiVersion", "kind", "name", "uid"}, + }, + VendorExtensible: spec.VendorExtensible{ + Extensions: spec.Extensions{ + "x-kubernetes-map-type": "atomic", + }, + }, + }, + } +} + +func schema_pkg_apis_meta_v1_PartialObjectMetadata(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "PartialObjectMetadata is a generic representation of any object with ObjectMeta. It allows clients to get access to a particular ObjectMeta schema without knowing the details of the version.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "kind": { + SchemaProps: spec.SchemaProps{ + Description: "Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", + Type: []string{"string"}, + Format: "", + }, + }, + "apiVersion": { + SchemaProps: spec.SchemaProps{ + Description: "APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources", + Type: []string{"string"}, + Format: "", + }, + }, + "metadata": { + SchemaProps: spec.SchemaProps{ + Description: "Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata", + Default: map[string]interface{}{}, + Ref: ref(v1.ObjectMeta{}.OpenAPIModelName()), + }, + }, + }, + }, + }, + Dependencies: []string{ + v1.ObjectMeta{}.OpenAPIModelName()}, + } +} + +func schema_pkg_apis_meta_v1_PartialObjectMetadataList(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "PartialObjectMetadataList contains a list of objects containing only their metadata", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "kind": { + SchemaProps: spec.SchemaProps{ + Description: "Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", + Type: []string{"string"}, + Format: "", + }, + }, + "apiVersion": { + SchemaProps: spec.SchemaProps{ + Description: "APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources", + Type: []string{"string"}, + Format: "", + }, + }, + "metadata": { + SchemaProps: spec.SchemaProps{ + Description: "Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", + Default: map[string]interface{}{}, + Ref: ref(v1.ListMeta{}.OpenAPIModelName()), + }, + }, + "items": { + SchemaProps: spec.SchemaProps{ + Description: "items contains each of the included items.", + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Ref: ref(v1.PartialObjectMetadata{}.OpenAPIModelName()), + }, + }, + }, + }, + }, + }, + Required: []string{"items"}, + }, + }, + Dependencies: []string{ + v1.ListMeta{}.OpenAPIModelName(), v1.PartialObjectMetadata{}.OpenAPIModelName()}, + } +} + +func schema_pkg_apis_meta_v1_Patch(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "Patch is provided to give a concrete name and type to the Kubernetes PATCH request body.", + Type: []string{"object"}, + }, + }, + } +} + +func schema_pkg_apis_meta_v1_PatchOptions(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "PatchOptions may be provided when patching an API object. PatchOptions is meant to be a superset of UpdateOptions.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "kind": { + SchemaProps: spec.SchemaProps{ + Description: "Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", + Type: []string{"string"}, + Format: "", + }, + }, + "apiVersion": { + SchemaProps: spec.SchemaProps{ + Description: "APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources", + Type: []string{"string"}, + Format: "", + }, + }, + "dryRun": { + VendorExtensible: spec.VendorExtensible{ + Extensions: spec.Extensions{ + "x-kubernetes-list-type": "atomic", + }, + }, + SchemaProps: spec.SchemaProps{ + Description: "When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed", + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Type: []string{"string"}, + Format: "", + }, + }, + }, + }, + }, + "force": { + SchemaProps: spec.SchemaProps{ + Description: "Force is going to \"force\" Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests.", + Type: []string{"boolean"}, + Format: "", + }, + }, + "fieldManager": { + SchemaProps: spec.SchemaProps{ + Description: "fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch).", + Type: []string{"string"}, + Format: "", + }, + }, + "fieldValidation": { + SchemaProps: spec.SchemaProps{ + Description: "fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered.", + Type: []string{"string"}, + Format: "", + }, + }, + }, + }, + }, + } +} + +func schema_pkg_apis_meta_v1_Preconditions(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "Preconditions must be fulfilled before an operation (update, delete, etc.) is carried out.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "uid": { + SchemaProps: spec.SchemaProps{ + Description: "Specifies the target UID.", + Type: []string{"string"}, + Format: "", + }, + }, + "resourceVersion": { + SchemaProps: spec.SchemaProps{ + Description: "Specifies the target ResourceVersion", + Type: []string{"string"}, + Format: "", + }, + }, + }, + }, + }, + } +} + +func schema_pkg_apis_meta_v1_RootPaths(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "RootPaths lists the paths available at root. For example: \"/healthz\", \"/apis\".", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "paths": { + VendorExtensible: spec.VendorExtensible{ + Extensions: spec.Extensions{ + "x-kubernetes-list-type": "atomic", + }, + }, + SchemaProps: spec.SchemaProps{ + Description: "paths are the paths available at root.", + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Type: []string{"string"}, + Format: "", + }, + }, + }, + }, + }, + }, + Required: []string{"paths"}, + }, + }, + } +} + +func schema_pkg_apis_meta_v1_ServerAddressByClientCIDR(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "ServerAddressByClientCIDR helps the client to determine the server address that they should use, depending on the clientCIDR that they match.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "clientCIDR": { + SchemaProps: spec.SchemaProps{ + Description: "The CIDR with which clients can match their IP to figure out the server address that they should use.", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "serverAddress": { + SchemaProps: spec.SchemaProps{ + Description: "Address of this server, suitable for a client that matches the above CIDR. This can be a hostname, hostname:port, IP or IP:port.", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + }, + Required: []string{"clientCIDR", "serverAddress"}, + }, + }, + } +} + +func schema_pkg_apis_meta_v1_ShardInfo(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "ShardInfo describes the shard selector that was applied to produce a list response. Its presence on a list response indicates the list is a filtered subset.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "selector": { + SchemaProps: spec.SchemaProps{ + Description: "selector is the shard selector string from the request, echoed back so clients can verify which shard they received and merge responses from multiple shards.", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + }, + Required: []string{"selector"}, + }, + }, + } +} + +func schema_pkg_apis_meta_v1_Status(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "Status is a return value for calls that don't return other objects.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "kind": { + SchemaProps: spec.SchemaProps{ + Description: "Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", + Type: []string{"string"}, + Format: "", + }, + }, + "apiVersion": { + SchemaProps: spec.SchemaProps{ + Description: "APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources", + Type: []string{"string"}, + Format: "", + }, + }, + "metadata": { + SchemaProps: spec.SchemaProps{ + Description: "Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", + Default: map[string]interface{}{}, + Ref: ref(v1.ListMeta{}.OpenAPIModelName()), + }, + }, + "status": { + SchemaProps: spec.SchemaProps{ + Description: "Status of the operation. One of: \"Success\" or \"Failure\". More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status", + Type: []string{"string"}, + Format: "", + }, + }, + "message": { + SchemaProps: spec.SchemaProps{ + Description: "A human-readable description of the status of this operation.", + Type: []string{"string"}, + Format: "", + }, + }, + "reason": { + SchemaProps: spec.SchemaProps{ + Description: "A machine-readable description of why this operation is in the \"Failure\" status. If this value is empty there is no information available. A Reason clarifies an HTTP status code but does not override it.", + Type: []string{"string"}, + Format: "", + }, + }, + "details": { + SchemaProps: spec.SchemaProps{ + Description: "Extended data associated with the reason. Each reason may define its own extended details. This field is optional and the data returned is not guaranteed to conform to any schema except that defined by the reason type.", + Ref: ref(v1.StatusDetails{}.OpenAPIModelName()), + }, + }, + "code": { + SchemaProps: spec.SchemaProps{ + Description: "Suggested HTTP return code for this status, 0 if not set.", + Type: []string{"integer"}, + Format: "int32", + }, + }, + }, + }, + }, + Dependencies: []string{ + v1.ListMeta{}.OpenAPIModelName(), v1.StatusDetails{}.OpenAPIModelName()}, + } +} + +func schema_pkg_apis_meta_v1_StatusCause(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "StatusCause provides more information about an api.Status failure, including cases when multiple errors are encountered.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "reason": { + SchemaProps: spec.SchemaProps{ + Description: "A machine-readable description of the cause of the error. If this value is empty there is no information available.", + Type: []string{"string"}, + Format: "", + }, + }, + "message": { + SchemaProps: spec.SchemaProps{ + Description: "A human-readable description of the cause of the error. This field may be presented as-is to a reader.", + Type: []string{"string"}, + Format: "", + }, + }, + "field": { + SchemaProps: spec.SchemaProps{ + Description: "The field of the resource that has caused this error, as named by its JSON serialization. May include dot and postfix notation for nested attributes. Arrays are zero-indexed. Fields may appear more than once in an array of causes due to fields having multiple errors. Optional.\n\nExamples:\n \"name\" - the field \"name\" on the current resource\n \"items[0].name\" - the field \"name\" on the first array entry in \"items\"", + Type: []string{"string"}, + Format: "", + }, + }, + }, + }, + }, + } +} + +func schema_pkg_apis_meta_v1_StatusDetails(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "StatusDetails is a set of additional properties that MAY be set by the server to provide additional information about a response. The Reason field of a Status object defines what attributes will be set. Clients must ignore fields that do not match the defined type of each attribute, and should assume that any attribute may be empty, invalid, or under defined.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "name": { + SchemaProps: spec.SchemaProps{ + Description: "The name attribute of the resource associated with the status StatusReason (when there is a single name which can be described).", + Type: []string{"string"}, + Format: "", + }, + }, + "group": { + SchemaProps: spec.SchemaProps{ + Description: "The group attribute of the resource associated with the status StatusReason.", + Type: []string{"string"}, + Format: "", + }, + }, + "kind": { + SchemaProps: spec.SchemaProps{ + Description: "The kind attribute of the resource associated with the status StatusReason. On some operations may differ from the requested resource Kind. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", + Type: []string{"string"}, + Format: "", + }, + }, + "uid": { + SchemaProps: spec.SchemaProps{ + Description: "UID of the resource. (when there is a single resource which can be described). More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names#uids", + Type: []string{"string"}, + Format: "", + }, + }, + "causes": { + VendorExtensible: spec.VendorExtensible{ + Extensions: spec.Extensions{ + "x-kubernetes-list-type": "atomic", + }, + }, + SchemaProps: spec.SchemaProps{ + Description: "The Causes array includes more details associated with the StatusReason failure. Not all StatusReasons may provide detailed causes.", + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Ref: ref(v1.StatusCause{}.OpenAPIModelName()), + }, + }, + }, + }, + }, + "retryAfterSeconds": { + SchemaProps: spec.SchemaProps{ + Description: "If specified, the time in seconds before the operation should be retried. Some errors may indicate the client must take an alternate action - for those errors this field may indicate how long to wait before taking the alternate action.", + Type: []string{"integer"}, + Format: "int32", + }, + }, + }, + }, + }, + Dependencies: []string{ + v1.StatusCause{}.OpenAPIModelName()}, + } +} + +func schema_pkg_apis_meta_v1_Table(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "Table is a tabular representation of a set of API resources. The server transforms the object into a set of preferred columns for quickly reviewing the objects.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "kind": { + SchemaProps: spec.SchemaProps{ + Description: "Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", + Type: []string{"string"}, + Format: "", + }, + }, + "apiVersion": { + SchemaProps: spec.SchemaProps{ + Description: "APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources", + Type: []string{"string"}, + Format: "", + }, + }, + "metadata": { + SchemaProps: spec.SchemaProps{ + Description: "Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", + Default: map[string]interface{}{}, + Ref: ref(v1.ListMeta{}.OpenAPIModelName()), + }, + }, + "columnDefinitions": { + VendorExtensible: spec.VendorExtensible{ + Extensions: spec.Extensions{ + "x-kubernetes-list-type": "atomic", + }, + }, + SchemaProps: spec.SchemaProps{ + Description: "columnDefinitions describes each column in the returned items array. The number of cells per row will always match the number of column definitions.", + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Ref: ref(v1.TableColumnDefinition{}.OpenAPIModelName()), + }, + }, + }, + }, + }, + "rows": { + VendorExtensible: spec.VendorExtensible{ + Extensions: spec.Extensions{ + "x-kubernetes-list-type": "atomic", + }, + }, + SchemaProps: spec.SchemaProps{ + Description: "rows is the list of items in the table.", + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Ref: ref(v1.TableRow{}.OpenAPIModelName()), + }, + }, + }, + }, + }, + }, + Required: []string{"columnDefinitions", "rows"}, + }, + }, + Dependencies: []string{ + v1.ListMeta{}.OpenAPIModelName(), v1.TableColumnDefinition{}.OpenAPIModelName(), v1.TableRow{}.OpenAPIModelName()}, + } +} + +func schema_pkg_apis_meta_v1_TableColumnDefinition(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "TableColumnDefinition contains information about a column returned in the Table.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "name": { + SchemaProps: spec.SchemaProps{ + Description: "name is a human readable name for the column.", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "type": { + SchemaProps: spec.SchemaProps{ + Description: "type is an OpenAPI type definition for this column, such as number, integer, string, or array. See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types for more.", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "format": { + SchemaProps: spec.SchemaProps{ + Description: "format is an optional OpenAPI type modifier for this column. A format modifies the type and imposes additional rules, like date or time formatting for a string. The 'name' format is applied to the primary identifier column which has type 'string' to assist in clients identifying column is the resource name. See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types for more.", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "description": { + SchemaProps: spec.SchemaProps{ + Description: "description is a human readable description of this column.", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "priority": { + SchemaProps: spec.SchemaProps{ + Description: "priority is an integer defining the relative importance of this column compared to others. Lower numbers are considered higher priority. Columns that may be omitted in limited space scenarios should be given a higher priority.", + Default: 0, + Type: []string{"integer"}, + Format: "int32", + }, + }, + }, + Required: []string{"name", "type", "format", "description", "priority"}, + }, + }, + } +} + +func schema_pkg_apis_meta_v1_TableOptions(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "TableOptions are used when a Table is requested by the caller.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "kind": { + SchemaProps: spec.SchemaProps{ + Description: "Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", + Type: []string{"string"}, + Format: "", + }, + }, + "apiVersion": { + SchemaProps: spec.SchemaProps{ + Description: "APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources", + Type: []string{"string"}, + Format: "", + }, + }, + "includeObject": { + SchemaProps: spec.SchemaProps{ + Description: "includeObject decides whether to include each object along with its columnar information. Specifying \"None\" will return no object, specifying \"Object\" will return the full object contents, and specifying \"Metadata\" (the default) will return the object's metadata in the PartialObjectMetadata kind in version v1beta1 of the meta.k8s.io API group.", + Type: []string{"string"}, + Format: "", + }, + }, + }, + }, + }, + } +} + +func schema_pkg_apis_meta_v1_TableRow(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "TableRow is an individual row in a table.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "cells": { + VendorExtensible: spec.VendorExtensible{ + Extensions: spec.Extensions{ + "x-kubernetes-list-type": "atomic", + }, + }, + SchemaProps: spec.SchemaProps{ + Description: "cells will be as wide as the column definitions array and may contain strings, numbers (float64 or int64), booleans, simple maps, lists, or null. See the type field of the column definition for a more detailed description.", + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Type: []string{"object"}, + Format: "", + }, + }, + }, + }, + }, + "conditions": { + VendorExtensible: spec.VendorExtensible{ + Extensions: spec.Extensions{ + "x-kubernetes-list-type": "atomic", + }, + }, + SchemaProps: spec.SchemaProps{ + Description: "conditions describe additional status of a row that are relevant for a human user. These conditions apply to the row, not to the object, and will be specific to table output. The only defined condition type is 'Completed', for a row that indicates a resource that has run to completion and can be given less visual priority.", + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Ref: ref(v1.TableRowCondition{}.OpenAPIModelName()), + }, + }, + }, + }, + }, + "object": { + SchemaProps: spec.SchemaProps{ + Description: "This field contains the requested additional information about each object based on the includeObject policy when requesting the Table. If \"None\", this field is empty, if \"Object\" this will be the default serialization of the object for the current API version, and if \"Metadata\" (the default) will contain the object metadata. Check the returned kind and apiVersion of the object before parsing. The media type of the object will always match the enclosing list - if this as a JSON table, these will be JSON encoded objects.", + Ref: ref(runtime.RawExtension{}.OpenAPIModelName()), + }, + }, + }, + Required: []string{"cells"}, + }, + }, + Dependencies: []string{ + v1.TableRowCondition{}.OpenAPIModelName(), runtime.RawExtension{}.OpenAPIModelName()}, + } +} + +func schema_pkg_apis_meta_v1_TableRowCondition(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "TableRowCondition allows a row to be marked with additional information.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "type": { + SchemaProps: spec.SchemaProps{ + Description: "Type of row condition. The only defined value is 'Completed' indicating that the object this row represents has reached a completed state and may be given less visual priority than other rows. Clients are not required to honor any conditions but should be consistent where possible about handling the conditions.", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "status": { + SchemaProps: spec.SchemaProps{ + Description: "Status of the condition, one of True, False, Unknown.", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "reason": { + SchemaProps: spec.SchemaProps{ + Description: "(brief) machine readable reason for the condition's last transition.", + Type: []string{"string"}, + Format: "", + }, + }, + "message": { + SchemaProps: spec.SchemaProps{ + Description: "Human readable message indicating details about last transition.", + Type: []string{"string"}, + Format: "", + }, + }, + }, + Required: []string{"type", "status"}, + }, + }, + } +} + +func schema_pkg_apis_meta_v1_Time(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "Time is a wrapper around time.Time which supports correct marshaling to YAML and JSON. Wrappers are provided for many of the factory methods that the time package offers.", + Type: v1.Time{}.OpenAPISchemaType(), + Format: v1.Time{}.OpenAPISchemaFormat(), + }, + }, + } +} + +func schema_pkg_apis_meta_v1_Timestamp(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "Timestamp is a struct that is equivalent to Time, but intended for protobuf marshalling/unmarshalling. It is generated into a serialization that matches Time. Do not use in Go structs.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "seconds": { + SchemaProps: spec.SchemaProps{ + Description: "Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive.", + Default: 0, + Type: []string{"integer"}, + Format: "int64", + }, + }, + "nanos": { + SchemaProps: spec.SchemaProps{ + Description: "Non-negative fractions of a second at nanosecond resolution. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be from 0 to 999,999,999 inclusive. This field may be limited in precision depending on context.", + Default: 0, + Type: []string{"integer"}, + Format: "int32", + }, + }, + }, + Required: []string{"seconds", "nanos"}, + }, + }, + } +} + +func schema_pkg_apis_meta_v1_TypeMeta(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "TypeMeta describes an individual object in an API response or request with strings representing the type of the object and its API schema version. Structures that are versioned or persisted should inline TypeMeta.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "kind": { + SchemaProps: spec.SchemaProps{ + Description: "Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", + Type: []string{"string"}, + Format: "", + }, + }, + "apiVersion": { + SchemaProps: spec.SchemaProps{ + Description: "APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources", + Type: []string{"string"}, + Format: "", + }, + }, + }, + }, + }, + } +} + +func schema_pkg_apis_meta_v1_UpdateOptions(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "UpdateOptions may be provided when updating an API object. All fields in UpdateOptions should also be present in PatchOptions.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "kind": { + SchemaProps: spec.SchemaProps{ + Description: "Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", + Type: []string{"string"}, + Format: "", + }, + }, + "apiVersion": { + SchemaProps: spec.SchemaProps{ + Description: "APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources", + Type: []string{"string"}, + Format: "", + }, + }, + "dryRun": { + VendorExtensible: spec.VendorExtensible{ + Extensions: spec.Extensions{ + "x-kubernetes-list-type": "atomic", + }, + }, + SchemaProps: spec.SchemaProps{ + Description: "When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed", + Type: []string{"array"}, + Items: &spec.SchemaOrArray{ + Schema: &spec.Schema{ + SchemaProps: spec.SchemaProps{ + Type: []string{"string"}, + Format: "", + }, + }, + }, + }, + }, + "fieldManager": { + SchemaProps: spec.SchemaProps{ + Description: "fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.", + Type: []string{"string"}, + Format: "", + }, + }, + "fieldValidation": { + SchemaProps: spec.SchemaProps{ + Description: "fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered.", + Type: []string{"string"}, + Format: "", + }, + }, + }, + }, + }, + } +} + +func schema_pkg_apis_meta_v1_WatchEvent(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "Event represents a single event to a watched resource.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "type": { + SchemaProps: spec.SchemaProps{ + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "object": { + SchemaProps: spec.SchemaProps{ + Description: "Object is:\n * If Type is Added or Modified: the new state of the object.\n * If Type is Deleted: the state of the object immediately before deletion.\n * If Type is Error: *Status is recommended; other types may make sense\n depending on context.", + Ref: ref(runtime.RawExtension{}.OpenAPIModelName()), + }, + }, + }, + Required: []string{"type", "object"}, + }, + }, + Dependencies: []string{ + runtime.RawExtension{}.OpenAPIModelName()}, + } +} + +func schema_k8sio_apimachinery_pkg_runtime_RawExtension(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "RawExtension is used to hold extensions in external versions.\n\nTo use this, make a field which has RawExtension as its type in your external, versioned struct, and Object in your internal struct. You also need to register your various plugin types.\n\n// Internal package:\n\n\ttype MyAPIObject struct {\n\t\truntime.TypeMeta `json:\",inline\"`\n\t\tMyPlugin runtime.Object `json:\"myPlugin\"`\n\t}\n\n\ttype PluginA struct {\n\t\tAOption string `json:\"aOption\"`\n\t}\n\n// External package:\n\n\ttype MyAPIObject struct {\n\t\truntime.TypeMeta `json:\",inline\"`\n\t\tMyPlugin runtime.RawExtension `json:\"myPlugin\"`\n\t}\n\n\ttype PluginA struct {\n\t\tAOption string `json:\"aOption\"`\n\t}\n\n// On the wire, the JSON will look something like this:\n\n\t{\n\t\t\"kind\":\"MyAPIObject\",\n\t\t\"apiVersion\":\"v1\",\n\t\t\"myPlugin\": {\n\t\t\t\"kind\":\"PluginA\",\n\t\t\t\"aOption\":\"foo\",\n\t\t},\n\t}\n\nSo what happens? Decode first uses json or yaml to unmarshal the serialized data into your external MyAPIObject. That causes the raw JSON to be stored, but not unpacked. The next step is to copy (using pkg/conversion) into the internal struct. The runtime package's DefaultScheme has conversion functions installed which will unpack the JSON stored in RawExtension, turning it into the correct object type, and storing it in the Object. (TODO: In the case where the object is of an unknown type, a runtime.Unknown object will be created and stored.)", + Type: []string{"object"}, + }, + }, + } +} + +func schema_k8sio_apimachinery_pkg_runtime_TypeMeta(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "TypeMeta is shared by all top level objects. The proper way to use it is to inline it in your type, like this:\n\n\ttype MyAwesomeAPIObject struct {\n\t runtime.TypeMeta `json:\",inline\"`\n\t ... // other fields\n\t}\n\nfunc (obj *MyAwesomeAPIObject) SetGroupVersionKind(gvk *metav1.GroupVersionKind) { metav1.UpdateTypeMeta(obj,gvk) }; GroupVersionKind() *GroupVersionKind\n\nTypeMeta is provided here for convenience. You may use it directly from this package or define your own with the same fields.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "apiVersion": { + SchemaProps: spec.SchemaProps{ + Type: []string{"string"}, + Format: "", + }, + }, + "kind": { + SchemaProps: spec.SchemaProps{ + Type: []string{"string"}, + Format: "", + }, + }, + }, + }, + }, + } +} + +func schema_k8sio_apimachinery_pkg_runtime_Unknown(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "Unknown allows api objects with unknown types to be passed-through. This can be used to deal with the API objects from a plug-in. Unknown objects still have functioning TypeMeta features-- kind, version, etc. metadata and field mutatation.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "apiVersion": { + SchemaProps: spec.SchemaProps{ + Type: []string{"string"}, + Format: "", + }, + }, + "kind": { + SchemaProps: spec.SchemaProps{ + Type: []string{"string"}, + Format: "", + }, + }, + "ContentEncoding": { + SchemaProps: spec.SchemaProps{ + Description: "ContentEncoding is encoding used to encode 'Raw' data. Unspecified means no encoding.", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "ContentType": { + SchemaProps: spec.SchemaProps{ + Description: "ContentType is serialization method used to serialize 'Raw'. Unspecified means ContentTypeJSON.", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + }, + Required: []string{"ContentEncoding", "ContentType"}, + }, + }, + } +} + +func schema_k8sio_apimachinery_pkg_version_Info(ref common.ReferenceCallback) common.OpenAPIDefinition { + return common.OpenAPIDefinition{ + Schema: spec.Schema{ + SchemaProps: spec.SchemaProps{ + Description: "Info contains versioning information. how we'll want to distribute that information.", + Type: []string{"object"}, + Properties: map[string]spec.Schema{ + "major": { + SchemaProps: spec.SchemaProps{ + Description: "Major is the major version of the binary version", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "minor": { + SchemaProps: spec.SchemaProps{ + Description: "Minor is the minor version of the binary version", + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "emulationMajor": { + SchemaProps: spec.SchemaProps{ + Description: "EmulationMajor is the major version of the emulation version", + Type: []string{"string"}, + Format: "", + }, + }, + "emulationMinor": { + SchemaProps: spec.SchemaProps{ + Description: "EmulationMinor is the minor version of the emulation version", + Type: []string{"string"}, + Format: "", + }, + }, + "minCompatibilityMajor": { + SchemaProps: spec.SchemaProps{ + Description: "MinCompatibilityMajor is the major version of the minimum compatibility version", + Type: []string{"string"}, + Format: "", + }, + }, + "minCompatibilityMinor": { + SchemaProps: spec.SchemaProps{ + Description: "MinCompatibilityMinor is the minor version of the minimum compatibility version", + Type: []string{"string"}, + Format: "", + }, + }, + "gitVersion": { + SchemaProps: spec.SchemaProps{ + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "gitCommit": { + SchemaProps: spec.SchemaProps{ + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "gitTreeState": { + SchemaProps: spec.SchemaProps{ + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "buildDate": { + SchemaProps: spec.SchemaProps{ + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "goVersion": { + SchemaProps: spec.SchemaProps{ + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "compiler": { + SchemaProps: spec.SchemaProps{ + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + "platform": { + SchemaProps: spec.SchemaProps{ + Default: "", + Type: []string{"string"}, + Format: "", + }, + }, + }, + Required: []string{"major", "minor", "gitVersion", "gitCommit", "gitTreeState", "buildDate", "goVersion", "compiler", "platform"}, + }, + }, + } +} diff --git a/marketplace/pkg/offering/offering.go b/marketplace/pkg/offering/offering.go new file mode 100644 index 0000000..4bec3c0 --- /dev/null +++ b/marketplace/pkg/offering/offering.go @@ -0,0 +1,159 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// Package offering reads an APIExport as a catalog card. +// +// An offering has no object of its own: a producer publishes by annotating +// their APIExport, and the export's own permission claims are the claim +// surface a consumer accepts. This package is the single place that knows +// how to read that, so the operator (which grants `bind`) and the +// directory (which serves the catalog) cannot disagree about what is +// published or about what enabling would accept. +package offering + +import ( + "crypto/sha256" + "encoding/hex" + "fmt" + "sort" + "strings" + + apisv1alpha2 "github.com/kcp-dev/sdk/apis/apis/v1alpha2" + + marketplacev1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1" +) + +// Card is one offering, as read off the APIExport that is it. +type Card struct { + // DisplayName falls back to the export's own name. + DisplayName string + Description string + // IdentityHash is the export's identity, from its status. It is empty + // until kcp has reconciled the export, which is one of the two reasons + // an offering is not yet Ready. + IdentityHash string + // Claims is the export's permission claims, projected. + Claims []marketplacev1alpha1.OfferingClaim + // Revision is a digest of Claims. + Revision string + // DocsURL is the producer's documentation link, if any. + DocsURL string + // InstructionsRef names the ConfigMap holding the producer's "how to + // use this", in the export's own workspace. Empty means none. + InstructionsRef string +} + +// Published reports whether an export opts into the catalog. +// +// Only the exact string "true" publishes. An annotation present with any +// other value is not "sort of published": a typo should leave an export +// off the catalog rather than on it, because being on it is what grants +// `bind` to strangers. +func Published(export *apisv1alpha2.APIExport) bool { + if export == nil { + return false + } + return export.Annotations[marketplacev1alpha1.AnnotationPublish] == "true" +} + +// From reads the card off a published export. +func From(export *apisv1alpha2.APIExport) Card { + card := Card{ + DisplayName: export.Annotations[marketplacev1alpha1.AnnotationDisplayName], + Description: export.Annotations[marketplacev1alpha1.AnnotationDescription], + IdentityHash: export.Status.IdentityHash, + Claims: Claims(export.Spec.PermissionClaims), + DocsURL: export.Annotations[marketplacev1alpha1.AnnotationDocsURL], + InstructionsRef: export.Annotations[marketplacev1alpha1.AnnotationInstructions], + } + if card.DisplayName == "" { + card.DisplayName = export.Name + } + card.Revision = Revision(card.Claims) + return card +} + +// Claims projects an export's permission claims into the catalog's view of +// them. Nothing is validated, because there is nothing to validate against: +// the export declaring a claim is the claim existing. +func Claims(declared []apisv1alpha2.PermissionClaim) []marketplacev1alpha1.OfferingClaim { + if len(declared) == 0 { + return nil + } + out := make([]marketplacev1alpha1.OfferingClaim, 0, len(declared)) + for _, claim := range declared { + verbs := append([]string(nil), claim.Verbs...) + sort.Strings(verbs) + projected := marketplacev1alpha1.OfferingClaim{ + Group: claim.Group, + Resource: claim.Resource, + Verbs: verbs, + IdentityHash: claim.IdentityHash, + } + // The producer's suggested scope for this claim. Only matchLabels + // is carried: it is what a consumer can act on when authoring the + // binding, and an unset selector already means "every object", + // which is the default a binding takes anyway. + if sel := claim.DefaultSelector; sel != nil && len(sel.MatchLabels) > 0 { + projected.MatchLabels = make(map[string]string, len(sel.MatchLabels)) + for k, v := range sel.MatchLabels { + projected.MatchLabels[k] = v + } + } + out = append(out, projected) + } + // Sorted so that reordering claims on the export is not a change of + // consent — only the content is. + sort.Slice(out, func(i, j int) bool { + if out[i].Group != out[j].Group { + return out[i].Group < out[j].Group + } + return out[i].Resource < out[j].Resource + }) + return out +} + +// Revision is a digest of the claim surface: the same claims always give +// the same revision, and any change gives a different one. +// +// This is what a consumer compares against the revision they accepted, to +// see whether the consent form moved under them. A digest rather than a +// counter because there is no object left to keep a counter on — and +// because a counter would restart at a different number every time a +// controller lost its memory of it, which is precisely when a consumer +// most wants the comparison to still mean something. +func Revision(claims []marketplacev1alpha1.OfferingClaim) string { + if len(claims) == 0 { + return "" + } + var b strings.Builder + for _, c := range claims { + fmt.Fprintf(&b, "%s/%s#%s:%s", c.Group, c.Resource, c.IdentityHash, strings.Join(c.Verbs, ",")) + if len(c.MatchLabels) > 0 { + keys := make([]string, 0, len(c.MatchLabels)) + for k := range c.MatchLabels { + keys = append(keys, k) + } + sort.Strings(keys) + for _, k := range keys { + fmt.Fprintf(&b, "|%s=%s", k, c.MatchLabels[k]) + } + } + b.WriteByte(';') + } + sum := sha256.Sum256([]byte(b.String())) + return hex.EncodeToString(sum[:])[:12] +} diff --git a/marketplace/pkg/offering/offering_test.go b/marketplace/pkg/offering/offering_test.go new file mode 100644 index 0000000..e30396b --- /dev/null +++ b/marketplace/pkg/offering/offering_test.go @@ -0,0 +1,178 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package offering + +import ( + "reflect" + "testing" + + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + + apisv1alpha2 "github.com/kcp-dev/sdk/apis/apis/v1alpha2" + + marketplacev1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1" +) + +func exportWith(annotations map[string]string, claims ...apisv1alpha2.PermissionClaim) *apisv1alpha2.APIExport { + return &apisv1alpha2.APIExport{ + ObjectMeta: metav1.ObjectMeta{Name: "wildwest", Annotations: annotations}, + Spec: apisv1alpha2.APIExportSpec{PermissionClaims: claims}, + Status: apisv1alpha2.APIExportStatus{IdentityHash: "abc123"}, + } +} + +func claim(group, resource string, verbs ...string) apisv1alpha2.PermissionClaim { + return apisv1alpha2.PermissionClaim{ + GroupResource: apisv1alpha2.GroupResource{Group: group, Resource: resource}, + Verbs: verbs, + } +} + +func TestOnlyTruePublishes(t *testing.T) { + cases := map[string]bool{ + "true": true, + "True": false, + "yes": false, + "1": false, + "false": false, + "": false, + } + for value, want := range cases { + got := Published(exportWith(map[string]string{marketplacev1alpha1.AnnotationPublish: value})) + if got != want { + t.Errorf("publish=%q published=%v, want %v", value, got, want) + } + } + // A typo must leave an export off the catalog, because being on it is + // what hands `bind` to strangers. + if Published(exportWith(nil)) { + t.Error("an export with no annotations is published") + } + if Published(nil) { + t.Error("a nil export is published") + } +} + +func TestDisplayNameFallsBackToTheExportName(t *testing.T) { + card := From(exportWith(map[string]string{marketplacev1alpha1.AnnotationPublish: "true"})) + if card.DisplayName != "wildwest" { + t.Errorf("display name %q, want the export's own name", card.DisplayName) + } + + card = From(exportWith(map[string]string{ + marketplacev1alpha1.AnnotationPublish: "true", + marketplacev1alpha1.AnnotationDisplayName: "Wild West", + marketplacev1alpha1.AnnotationDescription: "cowboys", + })) + if card.DisplayName != "Wild West" || card.Description != "cowboys" { + t.Errorf("card = %+v", card) + } +} + +func TestClaimsAreTheExportsOwn(t *testing.T) { + export := exportWith(map[string]string{marketplacev1alpha1.AnnotationPublish: "true"}, + claim("", "secrets", "get", "list"), + claim("wildwest.dev", "sheriffs", "*"), + ) + export.Spec.PermissionClaims[0].IdentityHash = "core" + + card := From(export) + if len(card.Claims) != 2 { + t.Fatalf("claims = %+v", card.Claims) + } + // Sorted by group then resource: the core-group claim comes first. + if card.Claims[0].Resource != "secrets" || card.Claims[0].IdentityHash != "core" { + t.Errorf("first claim = %+v", card.Claims[0]) + } + if !reflect.DeepEqual(card.Claims[0].Verbs, []string{"get", "list"}) { + t.Errorf("verbs = %v", card.Claims[0].Verbs) + } + if card.IdentityHash != "abc123" { + t.Errorf("identity hash = %q", card.IdentityHash) + } +} + +func TestSuggestedScopeComesFromTheDefaultSelector(t *testing.T) { + export := exportWith(map[string]string{marketplacev1alpha1.AnnotationPublish: "true"}, + claim("", "secrets", "get")) + export.Spec.PermissionClaims[0].DefaultSelector = &apisv1alpha2.PermissionClaimSelector{ + LabelSelector: metav1.LabelSelector{MatchLabels: map[string]string{"owner": "wildwest"}}, + } + + card := From(export) + if got := card.Claims[0].MatchLabels["owner"]; got != "wildwest" { + t.Errorf("match labels = %v", card.Claims[0].MatchLabels) + } + + // An unset selector is not a narrower scope: it is every object, which + // is what a binding defaults to anyway. + export.Spec.PermissionClaims[0].DefaultSelector = nil + if labels := From(export).Claims[0].MatchLabels; labels != nil { + t.Errorf("match labels = %v, want none", labels) + } +} + +func TestRevisionFollowsContentNotOrder(t *testing.T) { + published := map[string]string{marketplacev1alpha1.AnnotationPublish: "true"} + a := From(exportWith(published, + claim("wildwest.dev", "sheriffs", "get"), + claim("", "secrets", "get"), + )) + b := From(exportWith(published, + claim("", "secrets", "get"), + claim("wildwest.dev", "sheriffs", "get"), + )) + if a.Revision != b.Revision { + t.Errorf("reordering the claims changed the revision: %q vs %q", a.Revision, b.Revision) + } + if a.Revision == "" { + t.Fatal("no revision for a claim surface that has claims") + } + + // Verb order is not a change either; a new verb is. + same := From(exportWith(published, claim("", "secrets", "list", "get"))) + also := From(exportWith(published, claim("", "secrets", "get", "list"))) + if same.Revision != also.Revision { + t.Errorf("verb order changed the revision: %q vs %q", same.Revision, also.Revision) + } + wider := From(exportWith(published, claim("", "secrets", "get", "list", "create"))) + if wider.Revision == same.Revision { + t.Error("widening the verbs did not change the revision") + } +} + +func TestScopeChangesTheRevision(t *testing.T) { + published := map[string]string{marketplacev1alpha1.AnnotationPublish: "true"} + unscoped := exportWith(published, claim("", "secrets", "get")) + scoped := exportWith(published, claim("", "secrets", "get")) + scoped.Spec.PermissionClaims[0].DefaultSelector = &apisv1alpha2.PermissionClaimSelector{ + LabelSelector: metav1.LabelSelector{MatchLabels: map[string]string{"owner": "wildwest"}}, + } + if From(unscoped).Revision == From(scoped).Revision { + t.Error("narrowing a claim to a label scope did not change the revision") + } +} + +func TestNoClaimsMeansNoRevision(t *testing.T) { + card := From(exportWith(map[string]string{marketplacev1alpha1.AnnotationPublish: "true"})) + if card.Claims != nil { + t.Errorf("claims = %+v, want none", card.Claims) + } + if card.Revision != "" { + t.Errorf("revision = %q, want empty for an offering that claims nothing", card.Revision) + } +} diff --git a/marketplace/pkg/operator/operator.go b/marketplace/pkg/operator/operator.go new file mode 100644 index 0000000..67bd39e --- /dev/null +++ b/marketplace/pkg/operator/operator.go @@ -0,0 +1,308 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// Package operator reconciles the marketplace API into producer +// workspaces and bind grants. +// +// It runs one manager per APIExport with schemas, and holds one client for +// the provisioner capability — and that is the whole security design: each +// write happens through exactly one claim someone accepted. +// +// catalog Providers, in the catalog workspace. +// publish APIExports, in each producer workspace; materializes the +// per-export `bind` grant that publishing means. It reads +// those exports through a claim and never writes to them — +// an offering is a producer's own object, annotated. +// provisioner (client only) creates producer workspaces under the +// producers parent. +// +// The operator never touches a consumer workspace: enabling an offering is +// a plain kcp APIBinding the consumer creates themselves, authorized by +// their own RBAC and by the `bind` grant publishing materialized. +package operator + +import ( + "context" + "fmt" + "strings" + "time" + + "github.com/go-logr/logr" + ctrl "sigs.k8s.io/controller-runtime" + "sigs.k8s.io/controller-runtime/pkg/client" + "sigs.k8s.io/controller-runtime/pkg/log" + "sigs.k8s.io/controller-runtime/pkg/manager" + metricsserver "sigs.k8s.io/controller-runtime/pkg/metrics/server" + mcbuilder "sigs.k8s.io/multicluster-runtime/pkg/builder" + mcmanager "sigs.k8s.io/multicluster-runtime/pkg/manager" + "sigs.k8s.io/multicluster-runtime/pkg/multicluster" + mcreconcile "sigs.k8s.io/multicluster-runtime/pkg/reconcile" + + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + "k8s.io/apimachinery/pkg/runtime" + "k8s.io/apimachinery/pkg/runtime/schema" + utilruntime "k8s.io/apimachinery/pkg/util/runtime" + "k8s.io/client-go/dynamic" + "k8s.io/client-go/kubernetes/scheme" + "k8s.io/client-go/rest" + + "github.com/kcp-dev/multicluster-provider/apiexport" + apisv1alpha1 "github.com/kcp-dev/sdk/apis/apis/v1alpha1" + apisv1alpha2 "github.com/kcp-dev/sdk/apis/apis/v1alpha2" + corev1alpha1 "github.com/kcp-dev/sdk/apis/core/v1alpha1" + kcptenancyv1alpha1 "github.com/kcp-dev/sdk/apis/tenancy/v1alpha1" + + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/pkg/bootstrap" + marketplacev1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1" +) + +// requeueWhilePending is how long the operator waits between looks at +// something that has not become ready yet. +const requeueWhilePending = 3 * time.Second + +// finalizer marks objects whose materialized side effects must be removed +// before the object may go. It is used only on Provider records, which the +// marketplace owns — never on a producer's own APIExport. +const finalizer = marketplacev1alpha1.GroupName + "/cleanup" + +// requeueWhileUnregistered is the slower beat for a published export whose +// workspace no Provider record names. Registering one happens in another +// workspace, so no event here will report it — but it is a human action, +// not a controller's, so looking every few seconds would be noise. +const requeueWhileUnregistered = 30 * time.Second + +// Options configures the operator. +type Options struct { + // RestConfig reaches the kcp shard hosting the marketplace APIExports. + RestConfig *rest.Config + // Slice names, one per export. Defaults match what init installs. + CatalogSlice string + PublishSlice string + ProvisionerSlice string + // ExportsPath is where the WorkspaceTypes live; Workspace objects + // reference their type by path. + ExportsPath string + // CatalogPath is the workspace Provider records live in. + CatalogPath string + // ProducersPath is the workspace provisioned producer workspaces are + // created under. + ProducersPath string + // BindUsers and BindGroups are the subjects the per-offering `bind` + // grants name: who may enable a published offering. Both empty means + // the system:authenticated group — mirroring this repo's bind-RBAC + // stance that a claim only takes effect once the consumer accepts it, + // and matching what kcp does for its own root exports. + BindUsers []string + BindGroups []string +} + +func (o *Options) defaults() { + if o.CatalogSlice == "" { + o.CatalogSlice = bootstrap.ExportCatalog + } + if o.PublishSlice == "" { + o.PublishSlice = bootstrap.ExportPublish + } + if o.ProvisionerSlice == "" { + o.ProvisionerSlice = bootstrap.ExportProvisioner + } +} + +// managers is the set this operator runs. provisioner has no controllers — +// it exists to hand out per-cluster clients scoped to its claim. +type managers struct { + catalog mcmanager.Manager + publish mcmanager.Manager + provisioner mcmanager.Manager +} + +// Run starts the operator and blocks until ctx is cancelled. +func Run(ctx context.Context, opts Options) error { + if opts.RestConfig == nil { + return fmt.Errorf("rest config is required") + } + if opts.ExportsPath == "" { + return fmt.Errorf("exports path is required; Workspace objects name their type by path") + } + if opts.CatalogPath == "" { + return fmt.Errorf("catalog path is required; it is the workspace Provider records live in") + } + if opts.ProducersPath == "" { + return fmt.Errorf("producers path is required; it is the workspace producer workspaces are created under") + } + opts.defaults() + + catalogCluster, err := resolveCluster(opts.RestConfig, opts.CatalogPath) + if err != nil { + return fmt.Errorf("resolve the logical cluster of %s (has `marketplace-vw init` run?): %w", opts.CatalogPath, err) + } + producersCluster, err := resolveCluster(opts.RestConfig, opts.ProducersPath) + if err != nil { + return fmt.Errorf("resolve the logical cluster of %s (has `marketplace-vw init` run?): %w", opts.ProducersPath, err) + } + + bindUsers, bindGroups := opts.BindUsers, opts.BindGroups + if len(bindUsers)+len(bindGroups) == 0 { + bindGroups = []string{"system:authenticated"} + } + + logger := log.FromContext(ctx).WithName("marketplace-operator") + sch := buildScheme() + + m := &managers{} + if m.catalog, err = newManager(opts.RestConfig, opts.CatalogSlice, sch, logger); err != nil { + return err + } + if m.publish, err = newManager(opts.RestConfig, opts.PublishSlice, sch, logger); err != nil { + return err + } + if m.provisioner, err = newManager(opts.RestConfig, opts.ProvisionerSlice, sch, logger); err != nil { + return err + } + + r := &reconcilers{ + m: m, + exportsPath: opts.ExportsPath, + producersPath: opts.ProducersPath, + catalogCluster: multicluster.ClusterName(catalogCluster), + producersCluster: multicluster.ClusterName(producersCluster), + bindUsers: bindUsers, + bindGroups: bindGroups, + logger: logger, + } + + if err := mcbuilder.ControllerManagedBy(m.catalog). + Named("marketplace-producer"). + For(&marketplacev1alpha1.Producer{}). + Complete(mcreconcile.Func(r.reconcileProducer)); err != nil { + return fmt.Errorf("build producer controller: %w", err) + } + // Every APIExport in every producer workspace comes through here, + // because the annotation that publishes one is on the export itself: + // there is no narrower thing to watch, and watching the exports is how + // un-publishing is noticed at all. + if err := mcbuilder.ControllerManagedBy(m.publish). + Named("marketplace-publish"). + For(&apisv1alpha2.APIExport{}). + Complete(mcreconcile.Func(r.reconcileAPIExport)); err != nil { + return fmt.Errorf("build publish controller: %w", err) + } + logger.Info("marketplace operator running", + "catalog", opts.CatalogPath+" ("+catalogCluster+")", + "providersParent", opts.ProducersPath+" ("+producersCluster+")", + "bindUsers", bindUsers, "bindGroups", bindGroups) + + errs := make(chan error, 3) + for _, mgr := range []mcmanager.Manager{m.provisioner, m.publish, m.catalog} { + go func(mgr mcmanager.Manager) { errs <- mgr.Start(ctx) }(mgr) + } + select { + case err := <-errs: + return err + case <-ctx.Done(): + return nil + } +} + +func buildScheme() *runtime.Scheme { + sch := runtime.NewScheme() + utilruntime.Must(scheme.AddToScheme(sch)) + utilruntime.Must(corev1alpha1.AddToScheme(sch)) + utilruntime.Must(kcptenancyv1alpha1.AddToScheme(sch)) + utilruntime.Must(apisv1alpha1.AddToScheme(sch)) + utilruntime.Must(apisv1alpha2.AddToScheme(sch)) + utilruntime.Must(marketplacev1alpha1.AddToScheme(sch)) + return sch +} + +// newManager builds a multicluster manager over one APIExport's virtual +// workspace. The export is the boundary: this manager sees exactly the +// clusters that bound it, with exactly the verbs it claims. +func newManager(cfg *rest.Config, slice string, sch *runtime.Scheme, logger logr.Logger) (mcmanager.Manager, error) { + provider, err := apiexport.New(cfg, slice, apiexport.Options{Scheme: sch, Log: &logger}) + if err != nil { + return nil, fmt.Errorf("construct provider for %q: %w", slice, err) + } + mgr, err := mcmanager.New(cfg, provider, manager.Options{ + Scheme: sch, + Metrics: metricsserver.Options{BindAddress: "0"}, + }) + if err != nil { + return nil, fmt.Errorf("construct manager for %q: %w", slice, err) + } + return mgr, nil +} + +// reconcilers carries what every reconcile needs. +type reconcilers struct { + m *managers + exportsPath string + producersPath string + // catalogCluster is where Provider records live; producersCluster is + // where provisioned producer workspaces are created. + catalogCluster multicluster.ClusterName + producersCluster multicluster.ClusterName + // bindUsers/bindGroups are the subjects the per-offering bind grants + // name: who may enable a published offering. + bindUsers []string + bindGroups []string + logger logr.Logger +} + +// resolveCluster turns a workspace path into its logical cluster name. +func resolveCluster(cfg *rest.Config, path string) (string, error) { + scoped := rest.CopyConfig(cfg) + host := scoped.Host + if i := strings.Index(host, "/clusters/"); i >= 0 { + host = host[:i] + } + scoped.Host = strings.TrimSuffix(host, "/") + "/clusters/" + path + + dyn, err := dynamic.NewForConfig(scoped) + if err != nil { + return "", fmt.Errorf("build dynamic client: %w", err) + } + lc, err := dyn.Resource(schema.GroupVersionResource{ + Group: "core.kcp.io", Version: "v1alpha1", Resource: "logicalclusters", + }).Get(context.Background(), "cluster", metav1.GetOptions{}) + if err != nil { + return "", err + } + name := lc.GetAnnotations()["kcp.io/cluster"] + if name == "" { + return "", fmt.Errorf("the LogicalCluster of %s carries no kcp.io/cluster annotation", path) + } + return name, nil +} + +// clientFor returns a client for one cluster through one export's virtual +// workspace. Which manager is passed decides what the call is allowed to +// do, which is why every caller names one explicitly. +func clientFor(ctx context.Context, mgr mcmanager.Manager, cluster multicluster.ClusterName) (client.Client, error) { + if mgr == nil { + return nil, fmt.Errorf("no manager for cluster %q: the export it reads through is not wired", cluster) + } + cl, err := mgr.GetCluster(ctx, cluster) + if err != nil { + return nil, fmt.Errorf("get cluster %q: %w", cluster, err) + } + return cl.GetClient(), nil +} + +// requeue is the poll-again result used while things come up. +func requeue() (ctrl.Result, error) { + return ctrl.Result{RequeueAfter: requeueWhilePending}, nil +} diff --git a/marketplace/pkg/operator/provider.go b/marketplace/pkg/operator/provider.go new file mode 100644 index 0000000..b342dd1 --- /dev/null +++ b/marketplace/pkg/operator/provider.go @@ -0,0 +1,161 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package operator + +import ( + "context" + + ctrl "sigs.k8s.io/controller-runtime" + "sigs.k8s.io/controller-runtime/pkg/client" + "sigs.k8s.io/controller-runtime/pkg/controller/controllerutil" + "sigs.k8s.io/controller-runtime/pkg/log" + mcreconcile "sigs.k8s.io/multicluster-runtime/pkg/reconcile" + + apierrors "k8s.io/apimachinery/pkg/api/errors" + + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/pkg/bootstrap" + marketplacev1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1" +) + +// reconcileProducer turns a Provider record into a workspace (for mode +// provisioned) or records the workspace the producer brought (for mode +// external). Either way the record grants nothing: reach into a producer +// workspace comes from the marketplace-publish binding there, which for +// provisioned workspaces the `producer` WorkspaceType carries and for +// external ones the producer creates themselves — that binding, not this +// object, is the consent. +func (r *reconcilers) reconcileProducer(ctx context.Context, req mcreconcile.Request) (ctrl.Result, error) { + logger := log.FromContext(ctx).WithValues("cluster", req.ClusterName, "producer", req.Name) + + c, err := clientFor(ctx, r.m.catalog, req.ClusterName) + if err != nil { + return ctrl.Result{}, err + } + + var producer marketplacev1alpha1.Producer + if err := c.Get(ctx, req.NamespacedName, &producer); err != nil { + return ctrl.Result{}, client.IgnoreNotFound(err) + } + + if !producer.DeletionTimestamp.IsZero() { + if producer.Spec.Mode == marketplacev1alpha1.ProducerModeProvisioned { + prov, err := clientFor(ctx, r.m.provisioner, r.producersCluster) + if err != nil { + return ctrl.Result{}, err + } + done, err := deleteWorkspace(ctx, prov, producer.Status.Workspace, string(producer.UID)) + if err != nil { + return ctrl.Result{}, err + } + if !done { + return requeue() + } + } + if controllerutil.RemoveFinalizer(&producer, finalizer) { + if err := c.Update(ctx, &producer); err != nil { + return ctrl.Result{}, client.IgnoreNotFound(err) + } + logger.Info("producer cleaned up") + } + return ctrl.Result{}, nil + } + + if controllerutil.AddFinalizer(&producer, finalizer) { + if err := c.Update(ctx, &producer); err != nil { + if apierrors.IsConflict(err) { + return requeue() + } + return ctrl.Result{}, err + } + } + + switch producer.Spec.Mode { + case marketplacev1alpha1.ProducerModeProvisioned: + prov, err := clientFor(ctx, r.m.provisioner, r.producersCluster) + if err != nil { + return ctrl.Result{}, err + } + ws, err := ensureWorkspace(ctx, prov, producer.Name, string(producer.UID), + bootstrap.WorkspaceTypeProvider, r.exportsPath) + if err != nil { + return ctrl.Result{}, updateProviderStatus(ctx, c, &producer, marketplacev1alpha1.ProducerStatus{ + Phase: marketplacev1alpha1.PhaseError, Message: err.Error(), + }) + } + status := marketplacev1alpha1.ProducerStatus{ + Phase: marketplacev1alpha1.PhasePending, + Message: "waiting for the workspace to become ready", + Workspace: ws.Name, + WorkspacePath: r.producersPath + ":" + ws.Name, + WorkspaceCluster: ws.Cluster, + URL: ws.URL, + } + if ws.Ready { + status.Phase = marketplacev1alpha1.PhaseReady + status.Message = "" + } + if err := updateProviderStatus(ctx, c, &producer, status); err != nil { + return ctrl.Result{}, err + } + if !ws.Ready { + return requeue() + } + logger.V(2).Info("producer workspace ready", "workspace", ws.Name, "workspaceCluster", ws.Cluster) + return ctrl.Result{}, nil + + case marketplacev1alpha1.ProducerModeExternal: + if producer.Spec.WorkspacePath == "" { + return ctrl.Result{}, updateProviderStatus(ctx, c, &producer, marketplacev1alpha1.ProducerStatus{ + Phase: marketplacev1alpha1.PhaseError, + Message: "mode external requires spec.workspacePath: the canonical path of the producer's own workspace", + }) + } + // The workspace's logical cluster cannot be resolved from here — + // the operator has no standing in an external workspace until its + // owner binds marketplace-publish. The offering reconciler learns + // the cluster when the first Offering arrives from a workspace + // whose path matches, and fills it in. + status := marketplacev1alpha1.ProducerStatus{ + WorkspacePath: producer.Spec.WorkspacePath, + WorkspaceCluster: producer.Status.WorkspaceCluster, // preserved, learned at publish + } + if status.WorkspaceCluster != "" { + status.Phase = marketplacev1alpha1.PhaseReady + } else { + status.Phase = marketplacev1alpha1.PhasePending + status.Message = "waiting for the workspace to bind marketplace-publish and publish an Offering" + } + return ctrl.Result{}, updateProviderStatus(ctx, c, &producer, status) + + default: + return ctrl.Result{}, updateProviderStatus(ctx, c, &producer, marketplacev1alpha1.ProducerStatus{ + Phase: marketplacev1alpha1.PhaseError, + Message: "spec.mode must be provisioned or external", + }) + } +} + +func updateProviderStatus(ctx context.Context, c client.Client, producer *marketplacev1alpha1.Producer, status marketplacev1alpha1.ProducerStatus) error { + if producer.Status == status { + return nil + } + producer.Status = status + if err := c.Status().Update(ctx, producer); err != nil && !apierrors.IsConflict(err) { + return err + } + return nil +} diff --git a/marketplace/pkg/operator/publish.go b/marketplace/pkg/operator/publish.go new file mode 100644 index 0000000..6276044 --- /dev/null +++ b/marketplace/pkg/operator/publish.go @@ -0,0 +1,210 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package operator + +import ( + "context" + "fmt" + + ctrl "sigs.k8s.io/controller-runtime" + "sigs.k8s.io/controller-runtime/pkg/client" + "sigs.k8s.io/controller-runtime/pkg/log" + mcreconcile "sigs.k8s.io/multicluster-runtime/pkg/reconcile" + + rbacv1 "k8s.io/api/rbac/v1" + apierrors "k8s.io/apimachinery/pkg/api/errors" + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + "k8s.io/apimachinery/pkg/types" + + apisv1alpha2 "github.com/kcp-dev/sdk/apis/apis/v1alpha2" + corev1alpha1 "github.com/kcp-dev/sdk/apis/core/v1alpha1" + + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/pkg/offering" + marketplacev1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1" +) + +// bindRoleName is the per-offering grant: `bind` on exactly one export. +// Publishing creates it, un-publishing revokes it — an offering off the +// catalog is an offering nobody new can enable. +func bindRoleName(export string) string { + return "marketplace:bind:" + export +} + +// reconcileAPIExport is the whole publish flow: an APIExport annotated for +// the catalog gets the `bind` grant that makes it enableable, and one that +// is not — never annotated, un-annotated, or deleted — does not. +// +// Nothing is written back to the export. It belongs to the producer, and +// the operator only reads it: there is no status to maintain (the catalog +// derives what it shows) and no finalizer to add, which matters because a +// finalizer of ours on someone else's object would let a wedged marketplace +// operator block a producer from deleting their own export. +func (r *reconcilers) reconcileAPIExport(ctx context.Context, req mcreconcile.Request) (ctrl.Result, error) { + logger := log.FromContext(ctx).WithValues("cluster", req.ClusterName, "export", req.Name) + + c, err := clientFor(ctx, r.m.publish, req.ClusterName) + if err != nil { + return ctrl.Result{}, err + } + + var export apisv1alpha2.APIExport + switch err := c.Get(ctx, req.NamespacedName, &export); { + case apierrors.IsNotFound(err): + // Deleted. The grant names the export, so it can be revoked + // without having seen what it pointed at. + return ctrl.Result{}, r.removeBindGrant(ctx, c, req.Name) + case err != nil: + return ctrl.Result{}, err + } + + if !offering.Published(&export) || !export.DeletionTimestamp.IsZero() { + // Either never published, or the annotation is gone, or it is on + // its way out. All three mean the same thing: not on the catalog. + if err := r.removeBindGrant(ctx, c, export.Name); err != nil { + return ctrl.Result{}, err + } + return ctrl.Result{}, nil + } + + // Which Provider record does this workspace publish under? The join is + // the workspace's canonical path — read from its LogicalCluster, never + // from anything the workspace's owner could claim — matched against + // the record. A workspace no record names publishes into the void, and + // gets no grant: an unregistered workspace must not be able to hand + // `bind` to the world by annotating its own export. + producerName, err := r.resolveProducerFor(ctx, c, string(req.ClusterName)) + if err != nil { + logger.V(2).Info("published export has no Provider record yet; not granting bind", "reason", err.Error()) + return ctrl.Result{RequeueAfter: requeueWhileUnregistered}, nil + } + + if err := r.ensureBindGrant(ctx, c, export.Name); err != nil { + return ctrl.Result{}, fmt.Errorf("materialize the bind grant: %w", err) + } + + card := offering.From(&export) + logger.V(2).Info("offering published", "producer", producerName, + "revision", card.Revision, "claims", len(card.Claims)) + return ctrl.Result{}, nil +} + +// resolveProducerFor matches the publishing workspace's canonical path +// against the Provider records, and teaches an external Provider its +// logical cluster on first contact. +func (r *reconcilers) resolveProducerFor(ctx context.Context, publishClient client.Client, cluster string) (string, error) { + var lc corev1alpha1.LogicalCluster + if err := publishClient.Get(ctx, types.NamespacedName{Name: "cluster"}, &lc); err != nil { + return "", fmt.Errorf("read this workspace's LogicalCluster: %w", err) + } + path := lc.Annotations["kcp.io/path"] + if path == "" { + return "", fmt.Errorf("this workspace's LogicalCluster carries no kcp.io/path annotation") + } + + catalog, err := clientFor(ctx, r.m.catalog, r.catalogCluster) + if err != nil { + return "", err + } + var producers marketplacev1alpha1.ProducerList + if err := catalog.List(ctx, &producers); err != nil { + return "", fmt.Errorf("list Provider records: %w", err) + } + for i := range producers.Items { + p := &producers.Items[i] + if p.Status.WorkspacePath != path { + continue + } + if p.Status.WorkspaceCluster == "" { + p.Status.WorkspaceCluster = cluster + p.Status.Phase = marketplacev1alpha1.PhaseReady + p.Status.Message = "" + if err := catalog.Status().Update(ctx, p); err != nil && !apierrors.IsConflict(err) { + return "", fmt.Errorf("record the producer's logical cluster: %w", err) + } + } else if p.Status.WorkspaceCluster != cluster { + return "", fmt.Errorf("producer %q maps %s to cluster %s, but this export is in %s", + p.Name, path, p.Status.WorkspaceCluster, cluster) + } + return p.Name, nil + } + return "", fmt.Errorf("no Provider record names this workspace (%s); register one in the catalog", path) +} + +// ensureBindGrant materializes `bind` on one export, to the configured +// consumers (default: any authenticated user). This grant IS what makes an +// offering enableable — a consumer creates the APIBinding themselves, and +// kcp checks this verb in this workspace on the way. +func (r *reconcilers) ensureBindGrant(ctx context.Context, c client.Client, export string) error { + role := &rbacv1.ClusterRole{ + ObjectMeta: metav1.ObjectMeta{Name: bindRoleName(export)}, + Rules: []rbacv1.PolicyRule{{ + APIGroups: []string{"apis.kcp.io"}, + Resources: []string{"apiexports"}, + ResourceNames: []string{export}, + Verbs: []string{"bind"}, + }}, + } + binding := &rbacv1.ClusterRoleBinding{ + ObjectMeta: metav1.ObjectMeta{Name: bindRoleName(export) + ":consumers"}, + RoleRef: rbacv1.RoleRef{APIGroup: rbacv1.GroupName, Kind: "ClusterRole", Name: role.Name}, + } + for _, u := range r.bindUsers { + binding.Subjects = append(binding.Subjects, rbacv1.Subject{ + APIGroup: rbacv1.GroupName, Kind: "User", Name: u, + }) + } + for _, g := range r.bindGroups { + binding.Subjects = append(binding.Subjects, rbacv1.Subject{ + APIGroup: rbacv1.GroupName, Kind: "Group", Name: g, + }) + } + for _, obj := range []client.Object{role, binding} { + if err := c.Create(ctx, obj); err != nil { + if !apierrors.IsAlreadyExists(err) { + return err + } + } + } + return nil +} + +// removeBindGrant revokes `bind` on one export. +// +// Every APIExport in every producer workspace reaches this reconciler, so +// the common case by far is an export that never had a grant. It checks +// before deleting to keep that case to one read. +func (r *reconcilers) removeBindGrant(ctx context.Context, c client.Client, export string) error { + if export == "" { + return nil + } + var existing rbacv1.ClusterRole + if err := c.Get(ctx, types.NamespacedName{Name: bindRoleName(export)}, &existing); err != nil { + if apierrors.IsNotFound(err) { + return nil + } + return err + } + for _, obj := range []client.Object{ + &rbacv1.ClusterRoleBinding{ObjectMeta: metav1.ObjectMeta{Name: bindRoleName(export) + ":consumers"}}, + &rbacv1.ClusterRole{ObjectMeta: metav1.ObjectMeta{Name: bindRoleName(export)}}, + } { + if err := c.Delete(ctx, obj); err != nil && !apierrors.IsNotFound(err) { + return err + } + } + return nil +} diff --git a/marketplace/pkg/operator/workspaces.go b/marketplace/pkg/operator/workspaces.go new file mode 100644 index 0000000..d309546 --- /dev/null +++ b/marketplace/pkg/operator/workspaces.go @@ -0,0 +1,113 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package operator + +import ( + "context" + "fmt" + + apierrors "k8s.io/apimachinery/pkg/api/errors" + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + "k8s.io/apimachinery/pkg/types" + "sigs.k8s.io/controller-runtime/pkg/client" + + corev1alpha1 "github.com/kcp-dev/sdk/apis/core/v1alpha1" + kcptenancyv1alpha1 "github.com/kcp-dev/sdk/apis/tenancy/v1alpha1" + + marketplacev1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1" +) + +// ownerUIDLabel ties a provisioned Workspace to the Provider that asked +// for it, so a reconcile recognizes its own workspace and a name collision +// with someone else's is told apart from an earlier run. +const ownerUIDLabel = marketplacev1alpha1.MetadataDomain + "/owner-uid" + +// provisioned describes the workspace a producer ended up with. +type provisioned struct { + Name string + Ready bool + Cluster string + URL string +} + +// ensureWorkspace makes sure a workspace named name exists under the +// parent addressed by c, owned by ownerUID, with the given type. A +// Producer's name is already a DNS label, so unlike tenancy there is no +// naming strategy: the workspace is named after the record, and a name +// held by a workspace with a different owner is an error, not a retry. +func ensureWorkspace(ctx context.Context, c client.Client, name, ownerUID, wsType, typePath string) (provisioned, error) { + var ws kcptenancyv1alpha1.Workspace + err := c.Get(ctx, types.NamespacedName{Name: name}, &ws) + switch { + case apierrors.IsNotFound(err): + create := kcptenancyv1alpha1.Workspace{ + ObjectMeta: metav1.ObjectMeta{ + Name: name, + Labels: map[string]string{ownerUIDLabel: ownerUID}, + }, + Spec: kcptenancyv1alpha1.WorkspaceSpec{ + Type: &kcptenancyv1alpha1.WorkspaceTypeReference{ + Name: kcptenancyv1alpha1.WorkspaceTypeName(wsType), + Path: typePath, + }, + }, + } + if err := c.Create(ctx, &create); err != nil && !apierrors.IsAlreadyExists(err) { + return provisioned{}, fmt.Errorf("create workspace %q: %w", name, err) + } + return provisioned{Name: name}, nil + + case err != nil: + return provisioned{}, fmt.Errorf("get workspace %q: %w", name, err) + + case ws.Labels[ownerUIDLabel] == ownerUID: + return provisioned{ + Name: ws.Name, + Ready: ws.Status.Phase == corev1alpha1.LogicalClusterPhaseReady && ws.Spec.Cluster != "", + Cluster: ws.Spec.Cluster, + URL: ws.Spec.URL, + }, nil + + default: + return provisioned{}, fmt.Errorf("workspace %q exists but belongs to something else", name) + } +} + +// deleteWorkspace removes the owner's workspace if it still exists and is +// still the owner's. Returns true once nothing is left to wait for. +func deleteWorkspace(ctx context.Context, c client.Client, name, ownerUID string) (bool, error) { + if name == "" { + return true, nil + } + var ws kcptenancyv1alpha1.Workspace + err := c.Get(ctx, types.NamespacedName{Name: name}, &ws) + if apierrors.IsNotFound(err) { + return true, nil + } + if err != nil { + return false, fmt.Errorf("get workspace %q: %w", name, err) + } + if ws.Labels[ownerUIDLabel] != ownerUID { + return true, nil + } + if ws.DeletionTimestamp == nil { + if err := c.Delete(ctx, &ws); err != nil && !apierrors.IsNotFound(err) { + return false, fmt.Errorf("delete workspace %q: %w", name, err) + } + } + return false, nil +} diff --git a/marketplace/pkg/provider/provider.go b/marketplace/pkg/provider/provider.go new file mode 100644 index 0000000..fdcc845 --- /dev/null +++ b/marketplace/pkg/provider/provider.go @@ -0,0 +1,299 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// 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 + +import ( + "context" + "fmt" + + "github.com/go-logr/logr" + ctrl "sigs.k8s.io/controller-runtime" + "sigs.k8s.io/controller-runtime/pkg/client" + "sigs.k8s.io/controller-runtime/pkg/log" + "sigs.k8s.io/controller-runtime/pkg/manager" + metricsserver "sigs.k8s.io/controller-runtime/pkg/metrics/server" + mcbuilder "sigs.k8s.io/multicluster-runtime/pkg/builder" + mcmanager "sigs.k8s.io/multicluster-runtime/pkg/manager" + mcreconcile "sigs.k8s.io/multicluster-runtime/pkg/reconcile" + + corev1 "k8s.io/api/core/v1" + apierrors "k8s.io/apimachinery/pkg/api/errors" + "k8s.io/apimachinery/pkg/runtime" + utilruntime "k8s.io/apimachinery/pkg/util/runtime" + "k8s.io/client-go/kubernetes/scheme" + "k8s.io/client-go/rest" + + "github.com/kcp-dev/logicalcluster/v3" + "github.com/kcp-dev/multicluster-provider/apiexport" + "github.com/kcp-dev/multicluster-provider/pkg/handlers" + apisv1alpha1 "github.com/kcp-dev/sdk/apis/apis/v1alpha1" + apisv1alpha2 "github.com/kcp-dev/sdk/apis/apis/v1alpha2" + corev1alpha1 "github.com/kcp-dev/sdk/apis/core/v1alpha1" + + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/pkg/bootstrap" + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/pkg/directory" + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/pkg/offering" + marketplacev1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1" +) + +// Options configures the directory producer. +type Options struct { + // RestConfig reaches the kcp shard hosting the marketplace APIExports. + RestConfig *rest.Config + // CatalogSlice serves Providers; PublishSlice reaches the APIExports + // in producer workspaces. + CatalogSlice string + PublishSlice string +} + +// Run fills dir until ctx is cancelled, marking it ready only once both +// discoveries have synced — a partial catalog that looks authoritative is +// worse than a 503. +func Run(ctx context.Context, opts Options, dir *directory.Directory) error { + if opts.RestConfig == nil { + return fmt.Errorf("rest config is required") + } + if opts.CatalogSlice == "" { + opts.CatalogSlice = bootstrap.ExportCatalog + } + if opts.PublishSlice == "" { + opts.PublishSlice = bootstrap.ExportPublish + } + + logger := log.FromContext(ctx).WithName("marketplace-directory") + + sch := runtime.NewScheme() + utilruntime.Must(scheme.AddToScheme(sch)) + utilruntime.Must(corev1alpha1.AddToScheme(sch)) + utilruntime.Must(apisv1alpha1.AddToScheme(sch)) + utilruntime.Must(apisv1alpha2.AddToScheme(sch)) + utilruntime.Must(marketplacev1alpha1.AddToScheme(sch)) + + newMgr := func(slice string) (mcmanager.Manager, error) { + provider, err := apiexport.New(opts.RestConfig, slice, apiexport.Options{ + Scheme: sch, + Log: &logger, + Handlers: handlers.Handlers{clusterLifecycle{dir: dir, logger: logger}}, + }) + if err != nil { + return nil, fmt.Errorf("construct provider for %q: %w", slice, err) + } + return mcmanager.New(opts.RestConfig, provider, manager.Options{ + Scheme: sch, + Metrics: metricsserver.Options{BindAddress: "0"}, // the VW has its own HTTP server + }) + } + + catalog, err := newMgr(opts.CatalogSlice) + if err != nil { + return err + } + publish, err := newMgr(opts.PublishSlice) + if err != nil { + return err + } + + if err := mcbuilder.ControllerManagedBy(catalog). + Named("marketplace-vw-producer"). + For(&marketplacev1alpha1.Producer{}). + Complete(mcreconcile.Func(func(ctx context.Context, req mcreconcile.Request) (ctrl.Result, error) { + key := directory.Key{Cluster: string(req.ClusterName), Name: req.Name} + var p marketplacev1alpha1.Producer + if err := getFrom(ctx, catalog, req, &p); err != nil { + if apierrors.IsNotFound(err) { + dir.RemoveProducer(key) + return ctrl.Result{}, nil + } + return ctrl.Result{}, err + } + dir.UpsertProducer(key, directory.Producer{ + DisplayName: p.Spec.DisplayName, + Description: p.Spec.Description, + WorkspacePath: p.Status.WorkspacePath, + WorkspaceCluster: p.Status.WorkspaceCluster, + Ready: p.Status.Phase == marketplacev1alpha1.PhaseReady, + }) + return ctrl.Result{}, nil + })); err != nil { + return fmt.Errorf("build producer mirror: %w", err) + } + + // An offering is an APIExport that says it is one. Every export in + // every producer workspace is mirrored or dropped by that annotation + // alone, so un-publishing takes an entry off the catalog exactly as + // deleting the export does. + if err := mcbuilder.ControllerManagedBy(publish). + Named("marketplace-vw-offering"). + For(&apisv1alpha2.APIExport{}). + Complete(mcreconcile.Func(func(ctx context.Context, req mcreconcile.Request) (ctrl.Result, error) { + key := directory.Key{Cluster: string(req.ClusterName), Name: req.Name} + var export apisv1alpha2.APIExport + if err := getFrom(ctx, publish, req, &export); err != nil { + if apierrors.IsNotFound(err) { + dir.RemoveOffering(key) + return ctrl.Result{}, nil + } + return ctrl.Result{}, err + } + if !offering.Published(&export) { + dir.RemoveOffering(key) + return ctrl.Result{}, nil + } + card := offering.From(&export) + dir.UpsertOffering(key, directory.Offering{ + DisplayName: card.DisplayName, + Description: card.Description, + Export: export.Name, + Revision: card.Revision, + Claims: card.Claims, + IdentityHash: card.IdentityHash, + DocsURL: card.DocsURL, + InstructionsRef: card.InstructionsRef, + Resources: resourceRefs(&export), + // Ready means a consumer can act on this entry: kcp has + // given the export its identity. Whether a Provider record + // names this workspace is the other half, and the + // directory decides that when it joins the two. + Ready: card.IdentityHash != "", + }) + return ctrl.Result{}, nil + })); err != nil { + return fmt.Errorf("build offering mirror: %w", err) + } + + // Instructions: ConfigMaps in producer workspaces, mirrored whole. Every + // ConfigMap the export's claim can see comes through here, and the + // directory keeps all of them keyed by name — cheap, and it means a + // producer editing their instructions needs no re-reconcile of the + // export that points at them. + if err := mcbuilder.ControllerManagedBy(publish). + Named("marketplace-vw-instructions"). + For(&corev1.ConfigMap{}). + Complete(mcreconcile.Func(func(ctx context.Context, req mcreconcile.Request) (ctrl.Result, error) { + key := directory.Key{Cluster: string(req.ClusterName), Name: req.Name} + var cm corev1.ConfigMap + if err := getFrom(ctx, publish, req, &cm); err != nil { + if apierrors.IsNotFound(err) { + dir.RemoveInstructions(key) + return ctrl.Result{}, nil + } + return ctrl.Result{}, err + } + dir.UpsertInstructions(key, cm.Data) + return ctrl.Result{}, nil + })); err != nil { + return fmt.Errorf("build instructions mirror: %w", err) + } + + // Schemas: the APIResourceSchemas exports reference, mirrored the same + // way and for the same reason — joined by name at read time, so the + // catalog shows what enabling an offering adds before anyone does. + if err := mcbuilder.ControllerManagedBy(publish). + Named("marketplace-vw-schemas"). + For(&apisv1alpha1.APIResourceSchema{}). + Complete(mcreconcile.Func(func(ctx context.Context, req mcreconcile.Request) (ctrl.Result, error) { + key := directory.Key{Cluster: string(req.ClusterName), Name: req.Name} + var s apisv1alpha1.APIResourceSchema + if err := getFrom(ctx, publish, req, &s); err != nil { + if apierrors.IsNotFound(err) { + dir.RemoveSchema(key) + return ctrl.Result{}, nil + } + return ctrl.Result{}, err + } + dir.UpsertSchema(key, schemaOf(&s)) + return ctrl.Result{}, nil + })); err != nil { + return fmt.Errorf("build schema mirror: %w", err) + } + + if err := catalog.GetLocalManager().Add(manager.RunnableFunc(func(ctx context.Context) error { + if !catalog.GetLocalManager().GetCache().WaitForCacheSync(ctx) { + return fmt.Errorf("catalog discovery cache did not sync") + } + if !publish.GetLocalManager().GetCache().WaitForCacheSync(ctx) { + return fmt.Errorf("publish discovery cache did not sync") + } + dir.SetReady() + logger.Info("marketplace directory ready") + <-ctx.Done() + return nil + })); err != nil { + return fmt.Errorf("register readiness runnable: %w", err) + } + + errs := make(chan error, 2) + go func() { errs <- catalog.Start(ctx) }() + go func() { errs <- publish.Start(ctx) }() + select { + case err := <-errs: + return err + case <-ctx.Done(): + return nil + } +} + +type clusterLifecycle struct { + dir *directory.Directory + logger logr.Logger +} + +func (c clusterLifecycle) OnAdd(client.Object) {} +func (c clusterLifecycle) OnUpdate(client.Object, client.Object) {} + +func (c clusterLifecycle) OnDelete(obj client.Object) { + cluster := logicalcluster.From(obj).String() + if cluster == "" { + return + } + c.logger.Info("workspace left the fleet, dropping from directory", "cluster", cluster) + c.dir.ForgetCluster(cluster) +} + +func resourceRefs(export *apisv1alpha2.APIExport) []directory.ResourceRef { + var refs []directory.ResourceRef + for _, r := range export.Spec.Resources { + refs = append(refs, directory.ResourceRef{Group: r.Group, Resource: r.Name, Schema: r.Schema}) + } + return refs +} + +func schemaOf(s *apisv1alpha1.APIResourceSchema) directory.Schema { + out := directory.Schema{Kind: s.Spec.Names.Kind, Scope: string(s.Spec.Scope)} + for _, v := range s.Spec.Versions { + out.Versions = append(out.Versions, marketplacev1alpha1.OfferingResourceVersion{ + Name: v.Name, + Served: v.Served, + Storage: v.Storage, + Schema: *v.Schema.DeepCopy(), + }) + } + return out +} + +func getFrom(ctx context.Context, mgr mcmanager.Manager, req mcreconcile.Request, obj client.Object) error { + cl, err := mgr.GetCluster(ctx, req.ClusterName) + if err != nil { + return fmt.Errorf("get cluster %q: %w", req.ClusterName, err) + } + return cl.GetClient().Get(ctx, req.NamespacedName, obj) +} diff --git a/marketplace/pkg/server/options.go b/marketplace/pkg/server/options.go new file mode 100644 index 0000000..2fd7297 --- /dev/null +++ b/marketplace/pkg/server/options.go @@ -0,0 +1,149 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package server + +import ( + "errors" + "fmt" + + "github.com/spf13/pflag" + + genericoptions "k8s.io/apiserver/pkg/server/options" + + "github.com/kcp-dev/logicalcluster/v3" + vwoptions "github.com/kcp-dev/virtual-workspace-framework/pkg/options" + + accessserver "github.com/kcp-dev/contrib-virtual-workspaces/access/pkg/server" + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/pkg/bootstrap" +) + +// Options configures the marketplace virtual workspace server. +type Options struct { + // SecureServing configures TLS serving. + SecureServing *genericoptions.SecureServingOptions + + // Authentication identifies callers the same way the other virtual + // workspaces do — JWT, forwarded request-header identity, client + // certificates. + Authentication *accessserver.Authentication + + // Authorization is the virtual-workspace-framework authorizer setup. + Authorization *vwoptions.Authorization + + // Kubeconfig is the path to the kubeconfig for the target kcp. + Kubeconfig string + + // CatalogSlice and PublishSlice feed the directory. + CatalogSlice string + PublishSlice string + + // WorkspacePath retargets the kubeconfig to the workspace holding the + // endpoint slices. Empty means use the kubeconfig as-is. + WorkspacePath string +} + +// NewOptions returns options with defaults suitable for running behind +// kcp's front-proxy. +func NewOptions() *Options { + o := &Options{ + SecureServing: genericoptions.NewSecureServingOptions(), + Authentication: accessserver.NewAuthentication(), + Authorization: vwoptions.NewAuthorization(), + } + + o.SecureServing.BindPort = 9446 + o.SecureServing.ServerCert.PairName = "marketplace-vw" + + return o +} + +// AddFlags registers all flags on the given flag set. +func (o *Options) AddFlags(fs *pflag.FlagSet) { + o.SecureServing.AddFlags(fs) + o.Authentication.AddFlags(fs) + o.Authorization.AddFlags(fs) + + fs.StringVar(&o.CatalogSlice, "catalog-endpointslice", bootstrap.ExportCatalog, + "APIExportEndpointSlice serving Providers.") + fs.StringVar(&o.PublishSlice, "publish-endpointslice", bootstrap.ExportPublish, + "APIExportEndpointSlice reaching the APIExports in producer workspaces.") + fs.StringVar(&o.WorkspacePath, "workspace-path", "", + "Workspace path the kubeconfig is retargeted to, e.g. root:marketplace:controllers. "+ + "Must be the workspace containing the APIExportEndpointSlices. "+ + "Empty means the kubeconfig's own cluster URL is used unchanged.") + if fs.Lookup("kubeconfig") == nil { + fs.StringVar(&o.Kubeconfig, "kubeconfig", "", "Path to the kubeconfig for the target kcp (required).") + } + + addIgnoredOperatorFlags(fs) +} + +// addIgnoredOperatorFlags accepts, and ignores, flags the kcp-operator +// puts on every VirtualWorkspace deployment. +// +// --shard-external-url is one of kcp's own virtual-workspace server's +// flags and means nothing here, but the operator appends it +// unconditionally (internal/resources/compiledvirtualworkspace: +// "TODO(ntnn): We need a way to shut this off if it isn't required"), +// even though the API type documents spec.command as suppressing it +// "because a custom server would reject the unknown flags and refuse to +// start". An apiserver built on pflag exits on a flag it does not know, +// so accepting it is what lets this server be deployed by the operator +// at all. Remove once the operator stops sending it. +func addIgnoredOperatorFlags(fs *pflag.FlagSet) { + var ignored string + fs.StringVar(&ignored, "shard-external-url", "", + "Ignored. Accepted only because the kcp-operator passes it to every virtual workspace.") + _ = fs.MarkHidden("shard-external-url") +} + +// Complete fills in derived defaults. +func (o *Options) Complete() error { + if o.Kubeconfig == "" { + return fmt.Errorf("--kubeconfig is required") + } + + if !o.Authentication.OIDCEnabled() && !o.Authentication.RequestHeaderEnabled() && !o.Authentication.ClientCertEnabled() { + return fmt.Errorf("no authentication method configured: set --client-ca-file or " + + "--authentication-config / --oidc-issuer-url for direct callers, and/or " + + "--requestheader-client-ca-file when running behind kcp's front-proxy") + } + + return nil +} + +// Validate checks flag consistency, reporting every problem it finds. +func (o *Options) Validate() error { + errs := []error{} + errs = append(errs, o.SecureServing.Validate()...) + errs = append(errs, o.Authentication.Validate()...) + errs = append(errs, o.Authorization.Validate()...) + + if o.CatalogSlice == "" { + errs = append(errs, fmt.Errorf("--catalog-endpointslice must not be empty")) + } + if o.PublishSlice == "" { + errs = append(errs, fmt.Errorf("--publish-endpointslice must not be empty")) + } + if o.WorkspacePath != "" { + if p := logicalcluster.NewPath(o.WorkspacePath); !p.IsValid() { + errs = append(errs, fmt.Errorf("--workspace-path %q is not a valid workspace path", o.WorkspacePath)) + } + } + + return errors.Join(errs...) +} diff --git a/marketplace/pkg/server/server.go b/marketplace/pkg/server/server.go new file mode 100644 index 0000000..eee4c06 --- /dev/null +++ b/marketplace/pkg/server/server.go @@ -0,0 +1,192 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// 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 + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "net" + "net/http" + "strings" + + "k8s.io/apimachinery/pkg/runtime" + "k8s.io/apimachinery/pkg/runtime/serializer" + utilruntime "k8s.io/apimachinery/pkg/util/runtime" + "k8s.io/apiserver/pkg/authorization/authorizer" + "k8s.io/apiserver/pkg/authorization/union" + openapinamer "k8s.io/apiserver/pkg/endpoints/openapi" + genericapiserver "k8s.io/apiserver/pkg/server" + "k8s.io/client-go/tools/clientcmd" + "k8s.io/klog/v2" + netutils "k8s.io/utils/net" + + "github.com/kcp-dev/virtual-workspace-framework/pkg/rootapiserver" + + "github.com/kcp-dev/contrib-virtual-workspaces/access/pkg/virtual" + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/pkg/directory" + generatedopenapi "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/pkg/generated/openapi" + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/pkg/provider" + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/pkg/virtual/catalog" + marketplacev1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1" +) + +const debugDirectoryPath = "/debug/directory" + +func retargetHost(host, workspacePath string) string { + if i := strings.Index(host, "/clusters/"); i >= 0 { + host = host[:i] + } + return strings.TrimSuffix(host, "/") + "/clusters/" + workspacePath +} + +// Run starts the directory producer and serves the marketplace virtual +// workspace until ctx is cancelled. +func Run(ctx context.Context, o *Options) error { + if err := o.Complete(); err != nil { + return err + } + if err := o.Validate(); err != nil { + return err + } + + restConfig, err := clientcmd.BuildConfigFromFlags("", o.Kubeconfig) + if err != nil { + return fmt.Errorf("load kubeconfig: %w", err) + } + if o.WorkspacePath != "" { + restConfig.Host = retargetHost(restConfig.Host, o.WorkspacePath) + } + + dir := directory.New() + + providerErr := make(chan error, 1) + go func() { + providerErr <- provider.Run(ctx, provider.Options{ + RestConfig: restConfig, + CatalogSlice: o.CatalogSlice, + PublishSlice: o.PublishSlice, + }, dir) + }() + + klog.InfoS("marketplace directory producer running", + "catalogSlice", o.CatalogSlice, "publishSlice", o.PublishSlice, + "kubeconfig", o.Kubeconfig, "host", restConfig.Host) + + vws := []rootapiserver.NamedVirtualWorkspace{ + catalog.NewVirtualWorkspace(dir), + } + + scheme := runtime.NewScheme() + utilruntime.Must(marketplacev1alpha1.AddToScheme(scheme)) + codecs := serializer.NewCodecFactory(scheme) + + recommended := genericapiserver.NewRecommendedConfig(codecs) + + namer := openapinamer.NewDefinitionNamer(scheme) + recommended.OpenAPIConfig = genericapiserver.DefaultOpenAPIConfig(generatedopenapi.GetOpenAPIDefinitions, namer) + recommended.OpenAPIConfig.Info.Title = "kcp-marketplace-vw" + recommended.OpenAPIV3Config = genericapiserver.DefaultOpenAPIV3Config(generatedopenapi.GetOpenAPIDefinitions, namer) + recommended.OpenAPIV3Config.Info.Title = "kcp-marketplace-vw" + + rootCfg, err := rootapiserver.NewConfig(recommended) + if err != nil { + return fmt.Errorf("create root apiserver config: %w", err) + } + rootCfg.Extra.VirtualWorkspaces = vws + + if err := o.SecureServing.MaybeDefaultWithSelfSignedCerts("localhost", nil, []net.IP{netutils.ParseIPSloppy("127.0.0.1")}); err != nil { + return fmt.Errorf("default serving certs: %w", err) + } + if err := o.SecureServing.ApplyTo(&recommended.SecureServing); err != nil { + return fmt.Errorf("apply secure serving: %w", err) + } + if err := o.Authentication.ApplyTo(ctx, &recommended.Authentication, recommended.SecureServing); err != nil { + return fmt.Errorf("apply authentication: %w", err) + } + if err := o.Authorization.ApplyTo(&recommended.Config, func() []rootapiserver.NamedVirtualWorkspace { return vws }); err != nil { + return fmt.Errorf("apply authorization: %w", err) + } + + // The debug endpoint is outside every virtual workspace's root path, so + // the framework's authorizer resolves it to no virtual workspace and + // denies it. Granting it explicitly is what makes it reachable at all. + recommended.Authorization.Authorizer = union.New( + recommended.Authorization.Authorizer, + pathScopedAuthorizer(debugDirectoryPath, virtual.AuthenticatedOnlyAuthorizer()), + ) + + completed := rootCfg.Complete() + rootServer, err := rootapiserver.NewServer(completed, genericapiserver.NewEmptyDelegate()) + if err != nil { + return fmt.Errorf("create root apiserver: %w", err) + } + + rootServer.GenericAPIServer.Handler.NonGoRestfulMux.HandleFunc(debugDirectoryPath, func(w http.ResponseWriter, r *http.Request) { + if r.Method != http.MethodGet { + w.Header().Set("Allow", http.MethodGet) + http.Error(w, "method not allowed", http.StatusMethodNotAllowed) + return + } + producers, offerings := dir.Counts() + w.Header().Set("Content-Type", "application/json") + if err := json.NewEncoder(w).Encode(map[string]any{ + "ready": dir.Ready(), + "producers": producers, + "offerings": offerings, + }); err != nil { + klog.ErrorS(err, "encoding directory counts") + } + }) + + prepared := rootServer.GenericAPIServer.PrepareRun() + + klog.InfoS("marketplace-vw serving", + "offerings", catalog.RootPath+"/apis/"+marketplacev1alpha1.SchemeGroupVersion.Group+"/"+marketplacev1alpha1.SchemeGroupVersion.Version+"/offerings", + ) + + serveErr := make(chan error, 1) + go func() { + serveErr <- prepared.RunWithContext(ctx) + }() + + select { + case err := <-providerErr: + if err != nil && !errors.Is(err, context.Canceled) { + return fmt.Errorf("directory producer failed: %w", err) + } + return <-serveErr + case err := <-serveErr: + return err + } +} + +// pathScopedAuthorizer delegates only for one non-resource path, and has no +// opinion on anything else. +func pathScopedAuthorizer(path string, delegate authorizer.Authorizer) authorizer.Authorizer { + return authorizer.AuthorizerFunc(func(ctx context.Context, attrs authorizer.Attributes) (authorizer.Decision, string, error) { + if !attrs.IsResourceRequest() && attrs.GetPath() == path { + return delegate.Authorize(ctx, attrs) + } + return authorizer.DecisionNoOpinion, "", nil + }) +} diff --git a/marketplace/pkg/virtual/catalog/offerings.go b/marketplace/pkg/virtual/catalog/offerings.go new file mode 100644 index 0000000..e07b786 --- /dev/null +++ b/marketplace/pkg/virtual/catalog/offerings.go @@ -0,0 +1,105 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package catalog + +import ( + "context" + + apierrors "k8s.io/apimachinery/pkg/api/errors" + metainternalversion "k8s.io/apimachinery/pkg/apis/meta/internalversion" + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + "k8s.io/apimachinery/pkg/runtime" + "k8s.io/apiserver/pkg/registry/rest" + + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/pkg/directory" + marketplacev1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1" +) + +// OfferingsREST is the read-only catalog: every published APIExport joined +// with the Producer record that owns its workspace, named +// ".". Reading it is reading the consent form — Claims is +// exactly what enabling accepts, and Revision identifies that surface. +type OfferingsREST struct { + directory *directory.Directory + tables rest.TableConvertor +} + +var ( + _ rest.Storage = &OfferingsREST{} + _ rest.Getter = &OfferingsREST{} + _ rest.Lister = &OfferingsREST{} + _ rest.Scoper = &OfferingsREST{} + _ rest.SingularNameProvider = &OfferingsREST{} +) + +// NewOfferingsREST returns the catalog storage backed by the directory. +func NewOfferingsREST(d *directory.Directory) *OfferingsREST { + return &OfferingsREST{ + directory: d, + tables: rest.NewDefaultTableConvertor(marketplacev1alpha1.Resource("offerings")), + } +} + +func (r *OfferingsREST) New() runtime.Object { return &marketplacev1alpha1.CatalogOffering{} } +func (r *OfferingsREST) NewList() runtime.Object { return &marketplacev1alpha1.CatalogOfferingList{} } +func (r *OfferingsREST) Destroy() {} +func (r *OfferingsREST) NamespaceScoped() bool { return false } +func (r *OfferingsREST) GetSingularName() string { return "offering" } + +func (r *OfferingsREST) ConvertToTable(ctx context.Context, object runtime.Object, tableOptions runtime.Object) (*metav1.Table, error) { + return r.tables.ConvertToTable(ctx, object, tableOptions) +} + +func (r *OfferingsREST) Get(_ context.Context, name string, _ *metav1.GetOptions) (runtime.Object, error) { + if !r.directory.Ready() { + return nil, apierrors.NewServiceUnavailable("marketplace directory is not ready; try again shortly") + } + entry, ok := r.directory.Lookup(name) + if !ok { + return nil, apierrors.NewNotFound(marketplacev1alpha1.Resource("offerings"), name) + } + return toCatalogOffering(entry), nil +} + +func (r *OfferingsREST) List(_ context.Context, _ *metainternalversion.ListOptions) (runtime.Object, error) { + if !r.directory.Ready() { + return nil, apierrors.NewServiceUnavailable("marketplace directory is not ready; try again shortly") + } + list := &marketplacev1alpha1.CatalogOfferingList{} + for _, entry := range r.directory.Catalog() { + list.Items = append(list.Items, *toCatalogOffering(entry)) + } + return list, nil +} + +func toCatalogOffering(entry directory.Entry) *marketplacev1alpha1.CatalogOffering { + return &marketplacev1alpha1.CatalogOffering{ + ObjectMeta: metav1.ObjectMeta{Name: entry.Name()}, + Producer: entry.Producer, + Offering: entry.Offering, + DisplayName: entry.Detail.DisplayName, + Description: entry.Detail.Description, + Export: entry.Detail.Export, + WorkspacePath: entry.WorkspacePath, + Revision: entry.Detail.Revision, + Claims: entry.Detail.Claims, + Ready: entry.Detail.Ready, + DocsURL: entry.Detail.DocsURL, + Instructions: entry.Instructions, + Resources: entry.Resources, + } +} diff --git a/marketplace/pkg/virtual/catalog/virtualworkspace.go b/marketplace/pkg/virtual/catalog/virtualworkspace.go new file mode 100644 index 0000000..cf2f796 --- /dev/null +++ b/marketplace/pkg/virtual/catalog/virtualworkspace.go @@ -0,0 +1,87 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// Package catalog implements the marketplace virtual workspace: the +// read-only catalog at /services/marketplace. Each entry carries the bind +// coordinates — export, workspace path, claims at the current revision — +// so browsing the catalog is reading both the consent form and the +// APIBinding a consumer authors to enable. Enabling itself involves no +// virtual workspace at all: it is a plain kcp bind. +package catalog + +import ( + "context" + "errors" + "strings" + + restStorage "k8s.io/apiserver/pkg/registry/rest" + genericapiserver "k8s.io/apiserver/pkg/server" + + "github.com/kcp-dev/virtual-workspace-framework/framework" + "github.com/kcp-dev/virtual-workspace-framework/pkg/fixedgvs" + "github.com/kcp-dev/virtual-workspace-framework/pkg/rootapiserver" + + "github.com/kcp-dev/contrib-virtual-workspaces/access/pkg/virtual" + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/pkg/directory" + marketplacev1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1" +) + +const VirtualWorkspaceName = "marketplace" + +// RootPath is the URL prefix the front-proxy routes to this VW. +// +// GET RootPath/apis/marketplace.platform.kcp.io/v1alpha1/offerings +const RootPath = "/services/" + VirtualWorkspaceName + +// NewVirtualWorkspace builds the marketplace VW: a fixed-group-version +// delegated apiserver serving marketplace.platform.kcp.io/v1alpha1 with the +// read-only catalog, answered from the shared directory. Any authenticated +// caller may browse. +func NewVirtualWorkspace(d *directory.Directory) rootapiserver.NamedVirtualWorkspace { + vw := &fixedgvs.FixedGroupVersionsVirtualWorkspace{ + RootPathResolver: framework.RootPathResolverFunc(func(urlPath string, ctx context.Context) (bool, string, context.Context) { + if urlPath != RootPath && !strings.HasPrefix(urlPath, RootPath+"/") { + return false, "", ctx + } + return true, RootPath, ctx + }), + Authorizer: virtual.AuthenticatedOnlyAuthorizer(), + ReadyChecker: framework.ReadyFunc(func() error { + if !d.Ready() { + return errors.New("marketplace directory has not completed its initial sync") + } + return nil + }), + GroupVersionAPISets: []fixedgvs.GroupVersionAPISet{ + { + GroupVersion: marketplacev1alpha1.SchemeGroupVersion, + AddToScheme: marketplacev1alpha1.AddToScheme, + BootstrapRestResources: func(_ genericapiserver.CompletedConfig) (map[string]fixedgvs.RestStorageBuilder, error) { + return map[string]fixedgvs.RestStorageBuilder{ + "offerings": func(_ genericapiserver.CompletedConfig) (restStorage.Storage, error) { + return NewOfferingsREST(d), nil + }, + }, nil + }, + }, + }, + } + + return rootapiserver.NamedVirtualWorkspace{ + Name: VirtualWorkspaceName, + VirtualWorkspace: &virtual.WithoutAdmission{CoreVirtualWorkspace: vw}, + } +} diff --git a/marketplace/sdk/apis/marketplace/v1alpha1/doc.go b/marketplace/sdk/apis/marketplace/v1alpha1/doc.go new file mode 100644 index 0000000..b47acee --- /dev/null +++ b/marketplace/sdk/apis/marketplace/v1alpha1/doc.go @@ -0,0 +1,34 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// Package v1alpha1 holds the API types for the marketplace component +// (group marketplace.platform.kcp.io). +// +// One persisted, cluster-scoped kind: Producer, the registration record, +// in the catalog workspace. One virtual kind: CatalogOffering, served +// read-only by the marketplace virtual workspace — the catalog as users +// browse it. +// +// There is deliberately no kind for an offering and none for an +// enablement, because neither needs one. Publishing is annotating an +// APIExport (see AnnotationPublish), so the offering is the export. +// Enabling is creating a plain kcp APIBinding, so the enablement is the +// binding. Both are ordinary objects their own owner controls, which is +// why the marketplace has no write path into either workspace. +// +// +k8s:openapi-gen=true +// +groupName=marketplace.platform.kcp.io +package v1alpha1 diff --git a/marketplace/sdk/apis/marketplace/v1alpha1/register.go b/marketplace/sdk/apis/marketplace/v1alpha1/register.go new file mode 100644 index 0000000..f354753 --- /dev/null +++ b/marketplace/sdk/apis/marketplace/v1alpha1/register.go @@ -0,0 +1,50 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package v1alpha1 + +import ( + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + "k8s.io/apimachinery/pkg/runtime" + "k8s.io/apimachinery/pkg/runtime/schema" +) + +const GroupName = "marketplace.platform.kcp.io" + +var ( + SchemeBuilder = runtime.NewSchemeBuilder(addKnownTypes) + AddToScheme = SchemeBuilder.AddToScheme + SchemeGroupVersion = schema.GroupVersion{Group: GroupName, Version: "v1alpha1"} +) + +func Resource(resource string) schema.GroupResource { + return SchemeGroupVersion.WithResource(resource).GroupResource() +} + +func Kind(kind string) schema.GroupKind { + return SchemeGroupVersion.WithKind(kind).GroupKind() +} + +func addKnownTypes(scheme *runtime.Scheme) error { + scheme.AddKnownTypes(SchemeGroupVersion, + &Producer{}, + &ProducerList{}, + &CatalogOffering{}, + &CatalogOfferingList{}, + ) + metav1.AddToGroupVersion(scheme, SchemeGroupVersion) + return nil +} diff --git a/marketplace/sdk/apis/marketplace/v1alpha1/types.go b/marketplace/sdk/apis/marketplace/v1alpha1/types.go new file mode 100644 index 0000000..5a5a218 --- /dev/null +++ b/marketplace/sdk/apis/marketplace/v1alpha1/types.go @@ -0,0 +1,302 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package v1alpha1 + +import ( + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + "k8s.io/apimachinery/pkg/runtime" +) + +// Phase describes where a marketplace object is in its lifecycle. It is a +// coarse, human-first signal; Message carries the detail when a phase is +// not Ready. +type Phase string + +const ( + // PhasePending means the object has been observed but what it asks for + // has not materialized yet. + PhasePending Phase = "Pending" + // PhaseReady means everything the object asks for exists and is usable. + PhaseReady Phase = "Ready" + // PhaseError means the last reconciliation failed; Message says why. + PhaseError Phase = "Error" +) + +// ProducerMode says who owns the producer's workspace. +type ProducerMode string + +const ( + // ProducerModeProvisioned means the operator creates the producer's + // workspace under the producers parent, with the `producer` + // WorkspaceType carrying the publish binding. + ProducerModeProvisioned ProducerMode = "provisioned" + // ProducerModeExternal means the producer brings their own workspace + // (anywhere in kcp) and consents by binding marketplace-publish there + // themselves. + ProducerModeExternal ProducerMode = "external" +) + +// Producer is the registration record: it says which workspace is allowed +// to publish offerings under this name. It lives in the catalog workspace +// and grants nothing by existing — the reach into a producer workspace +// comes from the marketplace-publish binding there, never from this +// record. +// +// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object +// +kubebuilder:object:root=true +// +kubebuilder:resource:scope=Cluster +// +kubebuilder:subresource:status +type Producer struct { + metav1.TypeMeta `json:",inline"` + // +optional + metav1.ObjectMeta `json:"metadata,omitempty"` + + Spec ProducerSpec `json:"spec"` + // +optional + Status ProducerStatus `json:"status,omitempty"` +} + +// ProducerSpec is the desired state of a Producer. +type ProducerSpec struct { + // DisplayName is the human name of the producer, shown in the catalog. + // +kubebuilder:validation:MinLength=1 + DisplayName string `json:"displayName"` + // Description is free text for humans. + // +optional + Description string `json:"description,omitempty"` + // Mode is provisioned or external. + // +kubebuilder:validation:Enum=provisioned;external + Mode ProducerMode `json:"mode"` + // WorkspacePath is the canonical path of the producer's own workspace, + // for mode external. Ignored for mode provisioned, where the operator + // computes it. + // +optional + WorkspacePath string `json:"workspacePath,omitempty"` +} + +// ProducerStatus is the observed state of a Producer. +type ProducerStatus struct { + // +optional + Phase Phase `json:"phase,omitempty"` + // +optional + Message string `json:"message,omitempty"` + // Workspace is the name of the provisioned Workspace object, for mode + // provisioned. + // +optional + Workspace string `json:"workspace,omitempty"` + // WorkspacePath is the canonical path of the producer's workspace — + // computed for provisioned, copied from spec for external. Offerings + // bind against it. + // +optional + WorkspacePath string `json:"workspacePath,omitempty"` + // WorkspaceCluster is the logical cluster backing the producer's + // workspace. For external producers it is learned when the first + // Offering is published from that workspace. + // +optional + WorkspaceCluster string `json:"workspaceCluster,omitempty"` + // URL is the direct address of the producer's workspace, when known. + // +optional + URL string `json:"url,omitempty"` +} + +// ProducerList is the list form of Producer. +// +// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object +// +kubebuilder:object:root=true +type ProducerList struct { + metav1.TypeMeta `json:",inline"` + metav1.ListMeta `json:"metadata,omitempty"` + + Items []Producer `json:"items"` +} + +// The annotations that publish an APIExport to the marketplace. +// +// An offering has no object of its own: an APIExport IS the offering, and +// these annotations are its catalog card. That is not only a saving of one +// kind — it removes the possibility of the two disagreeing. The old +// Offering named an export and restated its claims, so it could name an +// export that did not exist, or claim what the export did not, and the +// operator existed largely to detect and report those two cases. An +// annotation cannot be wrong about which export it is on, and the export's +// own spec.permissionClaims are the claim surface, so there is nothing +// left to reconcile them against. +const ( + // MetadataDomain prefixes the marketplace's label and annotation keys. + MetadataDomain = "marketplace.kcp.hub" + + // AnnotationPublish opts an APIExport into the catalog. Its value must + // be "true"; anything else, or its absence, means not published. + // + // Publishing is the producer's own act, on their own object, in their + // own workspace — and removing this annotation revokes the `bind` + // grant, which is what takes an offering off the catalog. + AnnotationPublish = MetadataDomain + "/publish" + + // AnnotationDisplayName is the human name shown in the catalog. + // Absent, the export's own name is used. + AnnotationDisplayName = MetadataDomain + "/display-name" + + // AnnotationDescription is free text for humans. + AnnotationDescription = MetadataDomain + "/description" + + // AnnotationDocsURL links to the producer's own documentation. + AnnotationDocsURL = MetadataDomain + "/docs-url" + + // AnnotationInstructions names a ConfigMap in the same workspace as the + // export whose keys are sections of "how to use this" — one per client + // or scenario, written by the producer, shown to a consumer after they + // enable it. The content is static text the console renders, with a + // small set of {{variables}} it fills in: the server, the consumer's + // workspace, their identity. See the marketplace README for the list. + // + // A ConfigMap rather than more annotations because setup instructions + // for several clients are paragraphs and code blocks, not a line — + // and a ConfigMap is the one core object made for exactly that. + AnnotationInstructions = MetadataDomain + "/instructions" +) + +// OfferingClaim is one permission claim as the catalog shows it: what a +// consumer accepts when they enable the offering. +// +// It is a projection of the APIExport's own spec.permissionClaims, never a +// separate declaration — so what the catalog advertises and what the +// binding will carry cannot drift apart. +type OfferingClaim struct { + // Group and Resource name what is claimed, as kcp permission claims do. + // +optional + Group string `json:"group,omitempty"` + Resource string `json:"resource"` + // Verbs are the verbs claimed, as the export declares them. + Verbs []string `json:"verbs"` + // IdentityHash is set when the claimed resource is itself served by an + // APIExport, copied from the claim. + // +optional + IdentityHash string `json:"identityHash,omitempty"` + // MatchLabels is the scope the producer suggests for this claim, from + // the claim's defaultSelector. Empty means the claim covers every + // object of that resource, which is what a consumer accepts by + // default. + // +optional + MatchLabels map[string]string `json:"matchLabels,omitempty"` +} + +// CatalogOffering is the virtual, read-only view of one offering as the +// marketplace virtual workspace serves it: a published APIExport joined +// with the Producer record whose workspace it lives in, named +// ".". It carries everything needed to author the +// APIBinding that enabling means — the export, the workspace path it lives +// at, and its claims, identity hashes included. Reading the catalog is +// reading the consent form. +// +// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object +type CatalogOffering struct { + metav1.TypeMeta `json:",inline"` + // +optional + metav1.ObjectMeta `json:"metadata,omitempty"` + + // Producer is the catalog Producer record's name. + Producer string `json:"producer"` + // Offering is the name of the published APIExport in the producer's + // workspace — the offering and the export are the same object. + Offering string `json:"offering"` + // DisplayName and Description mirror the offering's card. + // +optional + DisplayName string `json:"displayName,omitempty"` + // +optional + Description string `json:"description,omitempty"` + // Export is the APIExport enabling binds, and WorkspacePath is the + // canonical path of the workspace that owns it — together the + // spec.reference.export of the APIBinding a consumer creates. + // +optional + Export string `json:"export,omitempty"` + // +optional + WorkspacePath string `json:"workspacePath,omitempty"` + // Revision identifies the claim surface below: it is a digest of + // Claims, so the same claims always produce the same revision and any + // change produces a different one. + // + // It is derived rather than counted because there is no longer an + // object to keep a counter on — which turns out to be the better + // property anyway. A consumer who recorded the revision they accepted + // can compare it with this one to see whether the consent form has + // changed since, and the answer does not depend on how many times a + // controller happened to observe it. + // +optional + Revision string `json:"revision,omitempty"` + // Claims is the claim surface a consumer accepts by enabling: the + // export's own permission claims, projected. + // +optional + Claims []OfferingClaim `json:"claims,omitempty"` + // Ready reports whether enabling can currently succeed. + Ready bool `json:"ready"` + // DocsURL links to the producer's own documentation, if they gave one. + // +optional + DocsURL string `json:"docsURL,omitempty"` + // Instructions is the producer's "how to use this", keyed by section. + // Static text with {{variables}} the console fills in; see + // AnnotationInstructions. + // +optional + Instructions map[string]string `json:"instructions,omitempty"` + // Resources is the API enabling adds: each resource the export serves, + // with the schema its APIResourceSchema declares, so a consumer can + // read what they would get before enabling it. A resource whose schema + // has not been seen is listed without versions. + // +optional + Resources []OfferingResource `json:"resources,omitempty"` +} + +// OfferingResource is one resource an offering serves, projected from the +// APIResourceSchema the export references. +type OfferingResource struct { + // Group and Resource name it as the export does. + // +optional + Group string `json:"group,omitempty"` + Resource string `json:"resource"` + // Schema is the APIResourceSchema's name in the producer's workspace. + // +optional + Schema string `json:"schema,omitempty"` + // Kind and Scope are the schema's. + // +optional + Kind string `json:"kind,omitempty"` + // +optional + Scope string `json:"scope,omitempty"` + // Versions are the schema's versions, in its order. + // +optional + Versions []OfferingResourceVersion `json:"versions,omitempty"` +} + +// OfferingResourceVersion is one version of an offered resource. +type OfferingResourceVersion struct { + Name string `json:"name"` + Served bool `json:"served"` + Storage bool `json:"storage"` + // Schema is the version's OpenAPI v3 schema, verbatim. + // +optional + // +kubebuilder:pruning:PreserveUnknownFields + Schema runtime.RawExtension `json:"schema,omitempty"` +} + +// CatalogOfferingList is the list form of CatalogOffering. +// +// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object +type CatalogOfferingList struct { + metav1.TypeMeta `json:",inline"` + metav1.ListMeta `json:"metadata,omitempty"` + + Items []CatalogOffering `json:"items"` +} diff --git a/marketplace/sdk/apis/marketplace/v1alpha1/zz_generated_deepcopy.go b/marketplace/sdk/apis/marketplace/v1alpha1/zz_generated_deepcopy.go new file mode 100644 index 0000000..7f204d5 --- /dev/null +++ b/marketplace/sdk/apis/marketplace/v1alpha1/zz_generated_deepcopy.go @@ -0,0 +1,227 @@ +//go:build !ignore_autogenerated + +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// Code generated by deepcopy-gen. DO NOT EDIT. + +package v1alpha1 + +import ( + runtime "k8s.io/apimachinery/pkg/runtime" +) + +// DeepCopyInto is a deepcopy function, copying the receiver, writing into out. in must be non-nil. +func (in *OfferingClaim) DeepCopyInto(out *OfferingClaim) { + *out = *in + if in.Verbs != nil { + in, out := &in.Verbs, &out.Verbs + *out = make([]string, len(*in)) + copy(*out, *in) + } + if in.MatchLabels != nil { + in, out := &in.MatchLabels, &out.MatchLabels + *out = make(map[string]string, len(*in)) + for key, val := range *in { + (*out)[key] = val + } + } +} + +// DeepCopy is a deepcopy function, copying the receiver, creating a new OfferingClaim. +func (in *OfferingClaim) DeepCopy() *OfferingClaim { + if in == nil { + return nil + } + out := new(OfferingClaim) + in.DeepCopyInto(out) + return out +} + +// DeepCopyInto is a deepcopy function, copying the receiver, writing into out. in must be non-nil. +func (in *OfferingResource) DeepCopyInto(out *OfferingResource) { + *out = *in + if in.Versions != nil { + in, out := &in.Versions, &out.Versions + *out = make([]OfferingResourceVersion, len(*in)) + for i := range *in { + (*in)[i].DeepCopyInto(&(*out)[i]) + } + } +} + +// DeepCopy is a deepcopy function, copying the receiver, creating a new OfferingResource. +func (in *OfferingResource) DeepCopy() *OfferingResource { + if in == nil { + return nil + } + out := new(OfferingResource) + in.DeepCopyInto(out) + return out +} + +// DeepCopyInto is a deepcopy function, copying the receiver, writing into out. in must be non-nil. +func (in *OfferingResourceVersion) DeepCopyInto(out *OfferingResourceVersion) { + *out = *in + in.Schema.DeepCopyInto(&out.Schema) +} + +// DeepCopy is a deepcopy function, copying the receiver, creating a new OfferingResourceVersion. +func (in *OfferingResourceVersion) DeepCopy() *OfferingResourceVersion { + if in == nil { + return nil + } + out := new(OfferingResourceVersion) + in.DeepCopyInto(out) + return out +} + +// DeepCopyInto is a deepcopy function, copying the receiver, writing into out. in must be non-nil. +func (in *Producer) DeepCopyInto(out *Producer) { + *out = *in + out.TypeMeta = in.TypeMeta + in.ObjectMeta.DeepCopyInto(&out.ObjectMeta) + out.Spec = in.Spec + out.Status = in.Status +} + +// DeepCopy is a deepcopy function, copying the receiver, creating a new Producer. +func (in *Producer) DeepCopy() *Producer { + if in == nil { + return nil + } + out := new(Producer) + in.DeepCopyInto(out) + return out +} + +// DeepCopyObject is a deepcopy function, copying the receiver, creating a new runtime.Object. +func (in *Producer) DeepCopyObject() runtime.Object { + if c := in.DeepCopy(); c != nil { + return c + } + return nil +} + +// DeepCopyInto is a deepcopy function, copying the receiver, writing into out. in must be non-nil. +func (in *ProducerList) DeepCopyInto(out *ProducerList) { + *out = *in + out.TypeMeta = in.TypeMeta + in.ListMeta.DeepCopyInto(&out.ListMeta) + if in.Items != nil { + in, out := &in.Items, &out.Items + *out = make([]Producer, len(*in)) + for i := range *in { + (*in)[i].DeepCopyInto(&(*out)[i]) + } + } +} + +// DeepCopy is a deepcopy function, copying the receiver, creating a new ProducerList. +func (in *ProducerList) DeepCopy() *ProducerList { + if in == nil { + return nil + } + out := new(ProducerList) + in.DeepCopyInto(out) + return out +} + +// DeepCopyObject is a deepcopy function, copying the receiver, creating a new runtime.Object. +func (in *ProducerList) DeepCopyObject() runtime.Object { + if c := in.DeepCopy(); c != nil { + return c + } + return nil +} + +// DeepCopyInto is a deepcopy function, copying the receiver, writing into out. in must be non-nil. +func (in *CatalogOffering) DeepCopyInto(out *CatalogOffering) { + *out = *in + out.TypeMeta = in.TypeMeta + in.ObjectMeta.DeepCopyInto(&out.ObjectMeta) + if in.Claims != nil { + in, out := &in.Claims, &out.Claims + *out = make([]OfferingClaim, len(*in)) + for i := range *in { + (*in)[i].DeepCopyInto(&(*out)[i]) + } + } + if in.Instructions != nil { + in, out := &in.Instructions, &out.Instructions + *out = make(map[string]string, len(*in)) + for key, val := range *in { + (*out)[key] = val + } + } + if in.Resources != nil { + in, out := &in.Resources, &out.Resources + *out = make([]OfferingResource, len(*in)) + for i := range *in { + (*in)[i].DeepCopyInto(&(*out)[i]) + } + } +} + +// DeepCopy is a deepcopy function, copying the receiver, creating a new CatalogOffering. +func (in *CatalogOffering) DeepCopy() *CatalogOffering { + if in == nil { + return nil + } + out := new(CatalogOffering) + in.DeepCopyInto(out) + return out +} + +// DeepCopyObject is a deepcopy function, copying the receiver, creating a new runtime.Object. +func (in *CatalogOffering) DeepCopyObject() runtime.Object { + if c := in.DeepCopy(); c != nil { + return c + } + return nil +} + +// DeepCopyInto is a deepcopy function, copying the receiver, writing into out. in must be non-nil. +func (in *CatalogOfferingList) DeepCopyInto(out *CatalogOfferingList) { + *out = *in + out.TypeMeta = in.TypeMeta + in.ListMeta.DeepCopyInto(&out.ListMeta) + if in.Items != nil { + in, out := &in.Items, &out.Items + *out = make([]CatalogOffering, len(*in)) + for i := range *in { + (*in)[i].DeepCopyInto(&(*out)[i]) + } + } +} + +// DeepCopy is a deepcopy function, copying the receiver, creating a new CatalogOfferingList. +func (in *CatalogOfferingList) DeepCopy() *CatalogOfferingList { + if in == nil { + return nil + } + out := new(CatalogOfferingList) + in.DeepCopyInto(out) + return out +} + +// DeepCopyObject is a deepcopy function, copying the receiver, creating a new runtime.Object. +func (in *CatalogOfferingList) DeepCopyObject() runtime.Object { + if c := in.DeepCopy(); c != nil { + return c + } + return nil +} diff --git a/marketplace/test/e2e/fixture_test.go b/marketplace/test/e2e/fixture_test.go new file mode 100644 index 0000000..9ed891d --- /dev/null +++ b/marketplace/test/e2e/fixture_test.go @@ -0,0 +1,480 @@ +//go:build e2e + +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// Package e2e tests the marketplace stack the way hack/ci/run-e2e-tests.sh +// stands it up: a real kcp, `marketplace-vw init` (twice), the operator +// and the virtual workspace as local processes. +// +// The tiers and the grants are the point of most of these tests: where +// bindings land and where they don't, whether `bind` follows the Offering, +// and whether the VW's enablement path really is nothing but a relayed +// SubjectAccessReview. +package e2e + +import ( + "context" + "crypto/rand" + "encoding/hex" + "os" + "path/filepath" + "strings" + "testing" + "time" + + rbacv1 "k8s.io/api/rbac/v1" + apiextensionsv1 "k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1" + apierrors "k8s.io/apimachinery/pkg/api/errors" + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + "k8s.io/apimachinery/pkg/runtime" + utilruntime "k8s.io/apimachinery/pkg/util/runtime" + "k8s.io/apimachinery/pkg/util/wait" + "k8s.io/client-go/kubernetes/scheme" + "k8s.io/client-go/rest" + "k8s.io/client-go/tools/clientcmd" + "sigs.k8s.io/controller-runtime/pkg/client" + + apisv1alpha1 "github.com/kcp-dev/sdk/apis/apis/v1alpha1" + apisv1alpha2 "github.com/kcp-dev/sdk/apis/apis/v1alpha2" + corev1alpha1 "github.com/kcp-dev/sdk/apis/core/v1alpha1" + kcptenancyv1alpha1 "github.com/kcp-dev/sdk/apis/tenancy/v1alpha1" + + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/pkg/offering" + marketplacev1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1" +) + +// The three workspaces init creates. +const ( + exportsPath = "root:marketplace:controllers" + catalogPath = "root:marketplace:catalog" + producersPath = "root:marketplace:producers" +) + +// The three exports, by the name their APIBinding takes. +const ( + exportCatalog = "marketplace-catalog" + exportPublish = "marketplace-publish" + exportProvisioner = "marketplace-provisioner" +) + +var testScheme = runtime.NewScheme() + +func init() { + utilruntime.Must(scheme.AddToScheme(testScheme)) + utilruntime.Must(corev1alpha1.AddToScheme(testScheme)) + utilruntime.Must(kcptenancyv1alpha1.AddToScheme(testScheme)) + utilruntime.Must(apisv1alpha1.AddToScheme(testScheme)) + utilruntime.Must(apisv1alpha2.AddToScheme(testScheme)) + utilruntime.Must(marketplacev1alpha1.AddToScheme(testScheme)) +} + +// adminRestConfig returns the kcp admin config from $KUBECONFIG, pointed at +// the given absolute workspace path. +func adminRestConfig(t *testing.T, workspacePath string) *rest.Config { + t.Helper() + kubeconfig := os.Getenv("KUBECONFIG") + if kubeconfig == "" { + t.Fatal("KUBECONFIG is not set; run this through hack/ci/run-e2e-tests.sh") + } + cfg, err := clientcmd.BuildConfigFromFlags("", kubeconfig) + if err != nil { + t.Fatalf("load kubeconfig: %v", err) + } + if workspacePath != "" { + host := cfg.Host + if i := strings.Index(host, "/clusters/"); i >= 0 { + host = host[:i] + } + cfg.Host = strings.TrimSuffix(host, "/") + "/clusters/" + workspacePath + } + return cfg +} + +func adminClient(t *testing.T, workspacePath string) client.Client { + t.Helper() + c, err := client.New(adminRestConfig(t, workspacePath), client.Options{Scheme: testScheme}) + if err != nil { + t.Fatalf("build client for %s: %v", workspacePath, err) + } + return c +} + +// userVWConfig authenticates as one of the PKI users against the virtual +// workspace, at RootPath or a per-cluster path below it. +func userVWConfig(t *testing.T, user, subPath string) *rest.Config { + t.Helper() + base := os.Getenv("MARKETPLACE_VW_URL") + if base == "" { + t.Fatal("MARKETPLACE_VW_URL is not set; run this through hack/ci/run-e2e-tests.sh") + } + pki := os.Getenv("MARKETPLACE_PKI_DIR") + if pki == "" { + t.Fatal("MARKETPLACE_PKI_DIR is not set; run this through hack/ci/run-e2e-tests.sh") + } + return &rest.Config{ + Host: strings.TrimSuffix(base, "/") + "/services/marketplace" + subPath, + TLSClientConfig: rest.TLSClientConfig{ + Insecure: true, // the VW's self-signed serving cert; identity is the client cert + CertFile: filepath.Join(pki, user+".crt"), + KeyFile: filepath.Join(pki, user+".key"), + }, + } +} + +// userKcpConfig authenticates as one of the PKI users straight at kcp, +// pointed at a workspace path — how a real user reaches the workspace a +// tenancy system granted them. +func userKcpConfig(t *testing.T, user, workspacePath string) *rest.Config { + t.Helper() + pki := os.Getenv("MARKETPLACE_PKI_DIR") + if pki == "" { + t.Fatal("MARKETPLACE_PKI_DIR is not set; run this through hack/ci/run-e2e-tests.sh") + } + cfg := adminRestConfig(t, workspacePath) + return &rest.Config{ + Host: cfg.Host, + TLSClientConfig: rest.TLSClientConfig{ + Insecure: true, + CertFile: filepath.Join(pki, user+".crt"), + KeyFile: filepath.Join(pki, user+".key"), + }, + } +} + +func userVWClient(t *testing.T, user, subPath string) client.Client { + t.Helper() + c, err := client.New(userVWConfig(t, user, subPath), client.Options{Scheme: testScheme}) + if err != nil { + t.Fatalf("build VW client for %s: %v", user, err) + } + return c +} + +func waitFor(t *testing.T, ctx context.Context, what string, cond func(ctx context.Context) (bool, error)) { + t.Helper() + if err := wait.PollUntilContextTimeout(ctx, time.Second, 3*time.Minute, true, cond); err != nil { + t.Fatalf("timed out waiting for %s: %v", what, err) + } +} + +func randomSuffix(t *testing.T) string { + t.Helper() + b := make([]byte, 4) + if _, err := rand.Read(b); err != nil { + t.Fatalf("rand: %v", err) + } + return hex.EncodeToString(b) +} + +// createWorkspace creates a workspace under root with the given type and +// waits for readiness (which, for typed workspaces, includes kcp having +// installed the type's default bindings). Cleaned up with the test. +func createWorkspace(t *testing.T, ctx context.Context, name, typeName, typePath string) *kcptenancyv1alpha1.Workspace { + t.Helper() + root := adminClient(t, "root") + ws := &kcptenancyv1alpha1.Workspace{ObjectMeta: metav1.ObjectMeta{Name: name}} + if typeName != "" { + ws.Spec.Type = &kcptenancyv1alpha1.WorkspaceTypeReference{ + Name: kcptenancyv1alpha1.WorkspaceTypeName(typeName), + Path: typePath, + } + } + if err := root.Create(ctx, ws); err != nil && !apierrors.IsAlreadyExists(err) { + t.Fatalf("create workspace %s: %v", name, err) + } + t.Cleanup(func() { + cleanupCtx, cancel := context.WithTimeout(context.Background(), time.Minute) + defer cancel() + _ = root.Delete(cleanupCtx, &kcptenancyv1alpha1.Workspace{ObjectMeta: metav1.ObjectMeta{Name: name}}) + }) + waitFor(t, ctx, "workspace "+name+" ready", func(ctx context.Context) (bool, error) { + if err := root.Get(ctx, client.ObjectKey{Name: name}, ws); err != nil { + return false, nil + } + return ws.Status.Phase == corev1alpha1.LogicalClusterPhaseReady && ws.Spec.Cluster != "", nil + }) + return ws +} + +// registerProducer creates a Provider record in the catalog and, for mode +// provisioned, waits for its workspace. Cleaned up with the test. +func registerProducer(t *testing.T, ctx context.Context, name string, mode marketplacev1alpha1.ProducerMode, workspacePath string) *marketplacev1alpha1.Producer { + t.Helper() + catalog := adminClient(t, catalogPath) + provider := &marketplacev1alpha1.Producer{ + ObjectMeta: metav1.ObjectMeta{Name: name}, + Spec: marketplacev1alpha1.ProducerSpec{ + DisplayName: strings.ToUpper(name[:1]) + name[1:], + Mode: mode, + WorkspacePath: workspacePath, + }, + } + if err := catalog.Create(ctx, provider); err != nil { + t.Fatalf("create provider %s: %v", name, err) + } + t.Cleanup(func() { + cleanupCtx, cancel := context.WithTimeout(context.Background(), 2*time.Minute) + defer cancel() + _ = catalog.Delete(cleanupCtx, &marketplacev1alpha1.Producer{ObjectMeta: metav1.ObjectMeta{Name: name}}) + }) + if mode == marketplacev1alpha1.ProducerModeProvisioned { + waitFor(t, ctx, "provider "+name+" ready", func(ctx context.Context) (bool, error) { + if err := catalog.Get(ctx, client.ObjectKey{Name: name}, provider); err != nil { + return false, nil + } + return provider.Status.Phase == marketplacev1alpha1.PhaseReady && + provider.Status.WorkspaceCluster != "", nil + }) + } + return provider +} + +// thingSchemaJSON is the minimal schema the test provider's API carries. +const thingSchemaJSON = `{ + "type": "object", + "properties": { + "apiVersion": {"type": "string"}, + "kind": {"type": "string"}, + "metadata": {"type": "object"}, + "spec": { + "type": "object", + "properties": {"message": {"type": "string"}} + } + } +}` + +// installThingsExport stands up the test provider's own API in its +// workspace: a schema and an APIExport named exportName that also declares +// a tenant-side claim on configmaps — the consent surface the +// offering scenarios exercise. +func installThingsExport(t *testing.T, ctx context.Context, c client.Client, exportName string) { + t.Helper() + group := strings.SplitN(exportName, ".", 2)[1] + schemaName := "v1alpha1." + exportName + + sch := &apisv1alpha1.APIResourceSchema{ + ObjectMeta: metav1.ObjectMeta{Name: schemaName}, + Spec: apisv1alpha1.APIResourceSchemaSpec{ + Group: group, + Names: apiextensionsv1.CustomResourceDefinitionNames{ + Plural: "things", Singular: "thing", Kind: "Thing", ListKind: "ThingList", + }, + Scope: apiextensionsv1.ClusterScoped, + Versions: []apisv1alpha1.APIResourceVersion{{ + Name: "v1alpha1", Served: true, Storage: true, + Schema: runtime.RawExtension{Raw: []byte(thingSchemaJSON)}, + }}, + }, + } + if err := c.Create(ctx, sch); err != nil && !apierrors.IsAlreadyExists(err) { + t.Fatalf("create schema: %v", err) + } + + export := &apisv1alpha2.APIExport{ + ObjectMeta: metav1.ObjectMeta{Name: exportName}, + Spec: apisv1alpha2.APIExportSpec{ + Resources: []apisv1alpha2.ResourceSchema{{ + Name: "things", Group: group, Schema: schemaName, + Storage: apisv1alpha2.ResourceSchemaStorage{CRD: &apisv1alpha2.ResourceSchemaStorageCRD{}}, + }}, + PermissionClaims: []apisv1alpha2.PermissionClaim{ + {GroupResource: apisv1alpha2.GroupResource{Group: "", Resource: "configmaps"}, Verbs: []string{"get", "list", "watch"}}, + }, + }, + } + if err := c.Create(ctx, export); err != nil && !apierrors.IsAlreadyExists(err) { + t.Fatalf("create export: %v", err) + } +} + +// publishExport puts the offering annotations on an existing APIExport and +// waits for the bind grant that publishing materializes. +// +// There is no object to wait on and no status to poll: the export IS the +// offering. What tells us the operator has seen it is the one thing +// publishing produces — `bind` on that export. +func publishExport(t *testing.T, ctx context.Context, c client.Client, exportName, displayName string) *apisv1alpha2.APIExport { + t.Helper() + export := annotateExport(t, ctx, c, exportName, map[string]string{ + marketplacev1alpha1.AnnotationPublish: "true", + marketplacev1alpha1.AnnotationDisplayName: displayName, + }) + t.Cleanup(func() { + cleanupCtx, cancel := context.WithTimeout(context.Background(), time.Minute) + defer cancel() + _ = unannotate(cleanupCtx, c, exportName) + }) + waitFor(t, ctx, "the bind grant for "+exportName, func(ctx context.Context) (bool, error) { + var role rbacv1.ClusterRole + err := c.Get(ctx, client.ObjectKey{Name: "marketplace:bind:" + exportName}, &role) + return err == nil, nil + }) + return export +} + +// unpublishExport removes the publish annotation, which is how an offering +// comes off the catalog. +func unpublishExport(t *testing.T, ctx context.Context, c client.Client, exportName string) { + t.Helper() + if err := unannotate(ctx, c, exportName); err != nil { + t.Fatalf("unpublish %s: %v", exportName, err) + } +} + +// annotateExport merges annotations onto an export, retrying the read the +// update raced. +func annotateExport(t *testing.T, ctx context.Context, c client.Client, exportName string, annotations map[string]string) *apisv1alpha2.APIExport { + t.Helper() + var export apisv1alpha2.APIExport + waitFor(t, ctx, "annotate export "+exportName, func(ctx context.Context) (bool, error) { + if err := c.Get(ctx, client.ObjectKey{Name: exportName}, &export); err != nil { + return false, nil + } + if export.Annotations == nil { + export.Annotations = map[string]string{} + } + for k, v := range annotations { + export.Annotations[k] = v + } + return c.Update(ctx, &export) == nil, nil + }) + return &export +} + +func unannotate(ctx context.Context, c client.Client, exportName string) error { + var export apisv1alpha2.APIExport + if err := c.Get(ctx, client.ObjectKey{Name: exportName}, &export); err != nil { + return client.IgnoreNotFound(err) + } + delete(export.Annotations, marketplacev1alpha1.AnnotationPublish) + return c.Update(ctx, &export) +} + +// acceptedClaimsFrom mirrors, on the consumer side, the claim surface the +// catalog advertises — what a consumer consents to when they enable. +// +// It projects the export's own permission claims with the same function +// the catalog serves them through, so the test accepts exactly what a +// person reading the catalog would have been shown. +func acceptedClaimsFrom(export *apisv1alpha2.APIExport) []apisv1alpha2.AcceptablePermissionClaim { + var out []apisv1alpha2.AcceptablePermissionClaim + for _, claim := range offering.Claims(export.Spec.PermissionClaims) { + selector := apisv1alpha2.PermissionClaimSelector{MatchAll: true} + if len(claim.MatchLabels) > 0 { + selector = apisv1alpha2.PermissionClaimSelector{ + LabelSelector: metav1.LabelSelector{MatchLabels: claim.MatchLabels}, + } + } + out = append(out, apisv1alpha2.AcceptablePermissionClaim{ + ScopedPermissionClaim: apisv1alpha2.ScopedPermissionClaim{ + PermissionClaim: apisv1alpha2.PermissionClaim{ + GroupResource: apisv1alpha2.GroupResource{Group: claim.Group, Resource: claim.Resource}, + Verbs: claim.Verbs, + IdentityHash: claim.IdentityHash, + }, + Selector: selector, + }, + State: apisv1alpha2.ClaimAccepted, + }) + } + return out +} + +// bindingFor is the APIBinding enabling an offering means: a plain kcp +// bind, authored by the consumer, referencing the published export with +// its claims accepted. +func bindingFor(name, producerPath string, export *apisv1alpha2.APIExport) *apisv1alpha2.APIBinding { + return &apisv1alpha2.APIBinding{ + ObjectMeta: metav1.ObjectMeta{Name: name}, + Spec: apisv1alpha2.APIBindingSpec{ + Reference: apisv1alpha2.BindingReference{ + Export: &apisv1alpha2.ExportBindingReference{ + Path: producerPath, + Name: export.Name, + }, + }, + PermissionClaims: acceptedClaimsFrom(export), + }, + } +} + +// bindOffering enables natively as whoever c authenticates as, and waits +// for the binding to be bound. Cleaned up with the test. +func bindOffering(t *testing.T, ctx context.Context, c client.Client, name, producerPath string, export *apisv1alpha2.APIExport) { + t.Helper() + binding := bindingFor(name, producerPath, export) + waitFor(t, ctx, "binding "+name+" to be accepted", func(ctx context.Context) (bool, error) { + err := c.Create(ctx, binding.DeepCopy()) + return err == nil || apierrors.IsAlreadyExists(err), nil + }) + t.Cleanup(func() { + cleanupCtx, cancel := context.WithTimeout(context.Background(), time.Minute) + defer cancel() + _ = c.Delete(cleanupCtx, &apisv1alpha2.APIBinding{ObjectMeta: metav1.ObjectMeta{Name: name}}) + }) + waitFor(t, ctx, "binding "+name+" to be bound", func(ctx context.Context) (bool, error) { + var got apisv1alpha2.APIBinding + if err := c.Get(ctx, client.ObjectKey{Name: name}, &got); err != nil { + return false, nil + } + return got.Status.Phase == apisv1alpha2.APIBindingPhaseBound, nil + }) +} + +// hasBinding reports whether the workspace has an APIBinding REFERENCING +// the named export. The reference, not the binding's name, is what decides +// which export serves here — name heuristics made "marketplace-catalog" +// look like a binding of "marketplace" and inverted an assertion. +func hasBinding(t *testing.T, ctx context.Context, c client.Client, exportName string) bool { + t.Helper() + var bindings apisv1alpha2.APIBindingList + if err := c.List(ctx, &bindings); err != nil { + t.Fatalf("list bindings: %v", err) + } + for _, b := range bindings.Items { + if b.Spec.Reference.Export != nil && b.Spec.Reference.Export.Name == exportName { + return true + } + } + return false +} + +// grantWorkspaceAdmin gives a user full RBAC plus kcp's workspace `access` +// verb in one workspace — the shape a tenancy system would materialize for +// an admin Membership, minted by hand here because this suite deliberately +// runs without one. +func grantWorkspaceAdmin(t *testing.T, ctx context.Context, c client.Client, user string) { + t.Helper() + suffix := randomSuffix(t) + role := &rbacv1.ClusterRole{ + ObjectMeta: metav1.ObjectMeta{Name: "e2e-admin-" + user + "-" + suffix}, + Rules: []rbacv1.PolicyRule{ + {APIGroups: []string{"*"}, Resources: []string{"*"}, Verbs: []string{"*"}}, + {NonResourceURLs: []string{"/"}, Verbs: []string{"access"}}, + }, + } + binding := &rbacv1.ClusterRoleBinding{ + ObjectMeta: metav1.ObjectMeta{Name: role.Name}, + Subjects: []rbacv1.Subject{{APIGroup: rbacv1.GroupName, Kind: "User", Name: user}}, + RoleRef: rbacv1.RoleRef{APIGroup: rbacv1.GroupName, Kind: "ClusterRole", Name: role.Name}, + } + for _, obj := range []client.Object{role, binding} { + if err := c.Create(ctx, obj); err != nil && !apierrors.IsAlreadyExists(err) { + t.Fatalf("grant admin to %s: %v", user, err) + } + } +} diff --git a/marketplace/test/e2e/scenarios_test.go b/marketplace/test/e2e/scenarios_test.go new file mode 100644 index 0000000..b7da84a --- /dev/null +++ b/marketplace/test/e2e/scenarios_test.go @@ -0,0 +1,332 @@ +//go:build e2e + +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package e2e + +import ( + "context" + "testing" + "time" + + rbacv1 "k8s.io/api/rbac/v1" + apierrors "k8s.io/apimachinery/pkg/api/errors" + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + "k8s.io/apimachinery/pkg/apis/meta/v1/unstructured" + "k8s.io/apimachinery/pkg/runtime/schema" + "k8s.io/client-go/dynamic" + "sigs.k8s.io/controller-runtime/pkg/client" + + apisv1alpha2 "github.com/kcp-dev/sdk/apis/apis/v1alpha2" + + "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/pkg/offering" + marketplacev1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1" +) + +func testContext(t *testing.T) context.Context { + t.Helper() + ctx, cancel := context.WithTimeout(context.Background(), 8*time.Minute) + t.Cleanup(cancel) + return ctx +} + +// The harness runs init twice; this asserts what must be there afterwards. +func TestScenarioInstallIsIdempotent(t *testing.T) { + ctx := testContext(t) + c := adminClient(t, exportsPath) + + for _, name := range []string{exportCatalog, exportPublish, exportProvisioner} { + var export apisv1alpha2.APIExport + if err := c.Get(ctx, client.ObjectKey{Name: name}, &export); err != nil { + t.Fatalf("APIExport %s missing after double init: %v", name, err) + } + } + var provisioner apisv1alpha2.APIExport + if err := c.Get(ctx, client.ObjectKey{Name: exportProvisioner}, &provisioner); err != nil { + t.Fatal(err) + } + if len(provisioner.Spec.Resources) != 0 { + t.Fatal("marketplace-provisioner must declare no resources; the export IS the claim") + } +} + +// The two hand-bound tiers each get exactly one binding, and neither can +// do the other's job. +func TestScenarioTiersCarryTheRightBindings(t *testing.T) { + ctx := testContext(t) + + catalog := adminClient(t, catalogPath) + if !hasBinding(t, ctx, catalog, exportCatalog) { + t.Fatal("the catalog workspace does not bind marketplace-catalog") + } + for _, absent := range []string{exportPublish, exportProvisioner} { + if hasBinding(t, ctx, catalog, absent) { + t.Fatalf("the catalog workspace must NOT bind %s", absent) + } + } + + providers := adminClient(t, producersPath) + if !hasBinding(t, ctx, providers, exportProvisioner) { + t.Fatal("the providers parent does not bind marketplace-provisioner") + } + for _, absent := range []string{exportCatalog, exportPublish} { + if hasBinding(t, ctx, providers, absent) { + t.Fatalf("the providers parent must NOT bind %s", absent) + } + } +} + +// A provisioned Provider gets a workspace whose type carries exactly the +// publish binding — and, because `provider` does not extend +// root:universal, neither tenancy.kcp.io nor topology.kcp.io: a provider +// cannot spawn workspaces or inspect topology. +func TestScenarioProvisionedProviderGetsAWorkspace(t *testing.T) { + ctx := testContext(t) + name := "prov-" + randomSuffix(t) + + provider := registerProducer(t, ctx, name, marketplacev1alpha1.ProducerModeProvisioned, "") + if provider.Status.WorkspacePath != producersPath+":"+name { + t.Fatalf("provider workspace path = %q, want %q", provider.Status.WorkspacePath, producersPath+":"+name) + } + + ws := adminClient(t, provider.Status.WorkspacePath) + waitFor(t, ctx, "the publish binding in the provider workspace", func(ctx context.Context) (bool, error) { + return hasBinding(t, ctx, ws, exportPublish), nil + }) + for _, absent := range []string{exportCatalog, exportProvisioner, "tenancy.kcp.io", "topology.kcp.io"} { + if hasBinding(t, ctx, ws, absent) { + t.Fatalf("a provider workspace must NOT bind %s", absent) + } + } +} + +// Publishing is annotating the export, and it materializes exactly one +// grant: `bind` on that export, to the configured consumers. +func TestScenarioAnnotatingAnExportPublishesAndGrantsBind(t *testing.T) { + ctx := testContext(t) + sfx := randomSuffix(t) + name := "prov-" + sfx + exportName := "things.e2e-" + sfx + ".marketplace.platform.kcp.io" + + provider := registerProducer(t, ctx, name, marketplacev1alpha1.ProducerModeProvisioned, "") + ws := adminClient(t, provider.Status.WorkspacePath) + installThingsExport(t, ctx, ws, exportName) + + // Before the annotation there is no grant: an export is not on the + // catalog merely by existing in a registered provider's workspace. + var role rbacv1.ClusterRole + if err := ws.Get(ctx, client.ObjectKey{Name: "marketplace:bind:" + exportName}, &role); !apierrors.IsNotFound(err) { + t.Fatalf("an unannotated export already has a bind grant (%v)", err) + } + + export := publishExport(t, ctx, ws, exportName, "things") + + if err := ws.Get(ctx, client.ObjectKey{Name: "marketplace:bind:" + exportName}, &role); err != nil { + t.Fatalf("the bind ClusterRole was not materialized: %v", err) + } + if len(role.Rules) != 1 || role.Rules[0].Verbs[0] != "bind" || role.Rules[0].ResourceNames[0] != exportName { + t.Fatalf("bind role grants %+v, want bind on %s only", role.Rules, exportName) + } + + // The claim surface is the export's own: there is no second place to + // declare it, so there is nothing that could disagree with it. + claims := offering.Claims(export.Spec.PermissionClaims) + if len(claims) != 1 || claims[0].Resource != "configmaps" { + t.Fatalf("claims = %+v, want exactly the export's configmaps claim", claims) + } + + // Un-publishing revokes it, without deleting anything. + unpublishExport(t, ctx, ws, exportName) + waitFor(t, ctx, "the bind grant to be revoked on un-publish", func(ctx context.Context) (bool, error) { + err := ws.Get(ctx, client.ObjectKey{Name: "marketplace:bind:" + exportName}, &role) + return apierrors.IsNotFound(err), nil + }) +} + +// standUpOffering is the shared spine: a provisioned provider publishing a +// things offering, and a PLAIN consumer workspace — the marketplace needs +// nothing bound there, which is the point. +func standUpOffering(t *testing.T, ctx context.Context) (producerPath, producerName string, export *apisv1alpha2.APIExport, consumer client.Client, consumerPath, consumerCluster string) { + t.Helper() + sfx := randomSuffix(t) + producerName = "prov-" + sfx + exportName := "things.e2e-" + sfx + ".marketplace.platform.kcp.io" + + provider := registerProducer(t, ctx, producerName, marketplacev1alpha1.ProducerModeProvisioned, "") + ws := adminClient(t, provider.Status.WorkspacePath) + installThingsExport(t, ctx, ws, exportName) + export = publishExport(t, ctx, ws, exportName, "things") + + consumerWS := createWorkspace(t, ctx, "consumer-"+sfx, "", "") + return provider.Status.WorkspacePath, producerName, export, + adminClient(t, "root:"+consumerWS.Name), "root:" + consumerWS.Name, consumerWS.Spec.Cluster +} + +// Enabling is a plain kcp APIBinding the consumer creates: kcp checks the +// bind grant publishing materialized, and the provider's API serves. +func TestScenarioNativeBindEnablesAnOffering(t *testing.T) { + ctx := testContext(t) + producerPath, _, export, consumer, consumerPath, _ := standUpOffering(t, ctx) + + bindOffering(t, ctx, consumer, "things", producerPath, export) + + var binding apisv1alpha2.APIBinding + if err := consumer.Get(ctx, client.ObjectKey{Name: "things"}, &binding); err != nil { + t.Fatal(err) + } + if len(binding.Spec.PermissionClaims) != 1 || binding.Spec.PermissionClaims[0].Resource != "configmaps" { + t.Fatalf("binding claims = %+v, want exactly the declared configmaps claim", binding.Spec.PermissionClaims) + } + + dyn, err := dynamic.NewForConfig(adminRestConfig(t, consumerPath)) + if err != nil { + t.Fatalf("dynamic client: %v", err) + } + gvr := schema.GroupVersionResource{ + Group: export.Name[len("things."):], + Version: "v1alpha1", + Resource: "things", + } + thing := &unstructured.Unstructured{Object: map[string]interface{}{ + "apiVersion": gvr.Group + "/v1alpha1", + "kind": "Thing", + "metadata": map[string]interface{}{"name": "proof"}, + "spec": map[string]interface{}{"message": "enabled through a plain kcp bind"}, + }} + waitFor(t, ctx, "the enabled API to serve", func(ctx context.Context) (bool, error) { + _, err := dyn.Resource(gvr).Create(ctx, thing, metav1.CreateOptions{}) + return err == nil || apierrors.IsAlreadyExists(err), nil + }) + + // Disable is deleting the binding; the API stops serving. + if err := consumer.Delete(ctx, &binding); err != nil { + t.Fatal(err) + } + waitFor(t, ctx, "the API to stop serving after unbind", func(ctx context.Context) (bool, error) { + _, err := dyn.Resource(gvr).Create(ctx, thing.DeepCopy(), metav1.CreateOptions{}) + return err != nil && !apierrors.IsAlreadyExists(err), nil + }) +} + +// Widening the export's claims changes the revision the catalog +// advertises — and the consumer's existing binding is structurally +// untouchable: the claims live on THEIR object, which nothing in the +// marketplace can write. +func TestScenarioClaimChangesChangeTheRevision(t *testing.T) { + ctx := testContext(t) + producerPath, producerName, export, consumer, _, _ := standUpOffering(t, ctx) + bindOffering(t, ctx, consumer, "things", producerPath, export) + + alice := userVWClient(t, "alice", "") + entryName := producerName + "." + export.Name + + var before marketplacev1alpha1.CatalogOffering + waitFor(t, ctx, "the catalog to list the offering", func(ctx context.Context) (bool, error) { + if err := alice.Get(ctx, client.ObjectKey{Name: entryName}, &before); err != nil { + return false, nil + } + return before.Ready && before.Revision != "", nil + }) + + // The provider widens the consent surface by editing the export — the + // only place it is declared. + ws := adminClient(t, producerPath) + waitFor(t, ctx, "widen the export's claims", func(ctx context.Context) (bool, error) { + var fresh apisv1alpha2.APIExport + if err := ws.Get(ctx, client.ObjectKey{Name: export.Name}, &fresh); err != nil { + return false, nil + } + fresh.Spec.PermissionClaims = append(fresh.Spec.PermissionClaims, apisv1alpha2.PermissionClaim{ + GroupResource: apisv1alpha2.GroupResource{Group: "", Resource: "secrets"}, + Verbs: []string{"get", "list", "watch"}, + DefaultSelector: &apisv1alpha2.PermissionClaimSelector{ + LabelSelector: metav1.LabelSelector{ + MatchLabels: map[string]string{"marketplace.platform.kcp.io/owner": producerName}, + }, + }, + }) + return ws.Update(ctx, &fresh) == nil, nil + }) + + var after marketplacev1alpha1.CatalogOffering + waitFor(t, ctx, "the catalog to advertise the wider surface", func(ctx context.Context) (bool, error) { + if err := alice.Get(ctx, client.ObjectKey{Name: entryName}, &after); err != nil { + return false, nil + } + return len(after.Claims) == 2, nil + }) + if after.Revision == before.Revision { + t.Fatalf("the claim surface changed but the revision did not (%q)", after.Revision) + } + scoped := false + for _, claim := range after.Claims { + if claim.Resource == "secrets" && len(claim.MatchLabels) > 0 { + scoped = true + } + } + if !scoped { + t.Fatalf("the catalog lost the provider's suggested scope: %+v", after.Claims) + } + + // The consumer's binding still carries what they accepted, verbatim. + var binding apisv1alpha2.APIBinding + if err := consumer.Get(ctx, client.ObjectKey{Name: "things"}, &binding); err != nil { + t.Fatal(err) + } + if len(binding.Spec.PermissionClaims) != 1 { + t.Fatalf("the consumer's binding changed without the consumer: %+v", binding.Spec.PermissionClaims) + } +} + +// Un-publishing revokes the bind grant: an offering off the catalog is an +// offering no USER can newly enable — being admin of one's own workspace +// grants nothing on the provider's side. (The shard admin is exempt: +// system:masters bypasses authorization, here as everywhere in Kubernetes +// — which this test found out the hard way.) +func TestScenarioUnpublishingRevokesBind(t *testing.T) { + ctx := testContext(t) + producerPath, _, export, consumer, consumerPath, _ := standUpOffering(t, ctx) + + // alice is full admin of the consumer workspace... + grantWorkspaceAdmin(t, ctx, consumer, "alice") + alice, err := client.New(userKcpConfig(t, "alice", consumerPath), client.Options{Scheme: testScheme}) + if err != nil { + t.Fatal(err) + } + + // The provider takes it off the catalog by removing one annotation. + // The export itself, and everyone already bound to it, stay exactly as + // they were. + ws := adminClient(t, producerPath) + unpublishExport(t, ctx, ws, export.Name) + waitFor(t, ctx, "the bind grant to be revoked", func(ctx context.Context) (bool, error) { + var role rbacv1.ClusterRole + err := ws.Get(ctx, client.ObjectKey{Name: "marketplace:bind:" + export.Name}, &role) + return apierrors.IsNotFound(err), nil + }) + + // ...and it does not help: her rights end at her workspace, and the + // export side's grant is gone. + binding := bindingFor("too-late", producerPath, export) + waitFor(t, ctx, "the unpublished export to refuse alice", func(ctx context.Context) (bool, error) { + err := alice.Create(ctx, binding.DeepCopy()) + if err == nil { + t.Fatal("alice bound an unpublished export; the bind grant did not gate it") + } + return apierrors.IsForbidden(err), nil + }) +} diff --git a/marketplace/test/e2e/scenarios_vw_test.go b/marketplace/test/e2e/scenarios_vw_test.go new file mode 100644 index 0000000..2411827 --- /dev/null +++ b/marketplace/test/e2e/scenarios_vw_test.go @@ -0,0 +1,211 @@ +//go:build e2e + +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package e2e + +import ( + "context" + "testing" + "time" + + apierrors "k8s.io/apimachinery/pkg/api/errors" + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + "sigs.k8s.io/controller-runtime/pkg/client" + + apisv1alpha2 "github.com/kcp-dev/sdk/apis/apis/v1alpha2" + + marketplacev1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/marketplace/sdk/apis/marketplace/v1alpha1" +) + +// Any authenticated caller can browse the catalog through the virtual +// workspace, and what they read is everything enabling needs: the export, +// the workspace path to reference, and the claims at the current revision. +func TestScenarioVWListsTheCatalog(t *testing.T) { + ctx := testContext(t) + producerPath, producerName, export, _, _, _ := standUpOffering(t, ctx) + + alice := userVWClient(t, "alice", "") + entryName := producerName + "." + export.Name + + var entry marketplacev1alpha1.CatalogOffering + waitFor(t, ctx, "the catalog to list the offering", func(ctx context.Context) (bool, error) { + if err := alice.Get(ctx, client.ObjectKey{Name: entryName}, &entry); err != nil { + return false, nil + } + return entry.Ready, nil + }) + if entry.Producer != producerName || entry.Offering != export.Name { + t.Fatalf("catalog entry misjoined: %+v", entry) + } + // The offering and the export are the same object, so the entry names + // the export twice over: as what it is, and as what to bind. + if entry.WorkspacePath != producerPath || entry.Export != export.Name { + t.Fatalf("catalog entry does not carry the bind coordinates: %+v", entry) + } + if len(entry.Claims) == 0 || entry.Claims[0].Resource != "configmaps" { + t.Fatalf("the catalog entry does not carry the consent surface: %+v", entry.Claims) + } + + var list marketplacev1alpha1.CatalogOfferingList + if err := alice.List(ctx, &list); err != nil { + t.Fatalf("list the catalog as alice: %v", err) + } + found := false + for _, item := range list.Items { + if item.Name == entryName { + found = true + } + } + if !found { + t.Fatalf("the catalog listing does not contain %s", entryName) + } +} + +// Enabling is governed by the consumer workspace's own RBAC and kcp's +// bind check, natively: whoever a tenancy system made admin there can +// bind, whoever holds nothing cannot even enter. This is the tandem, with +// no marketplace machinery in the path at all. +func TestScenarioAUserBindsWithTheirOwnCredential(t *testing.T) { + ctx := testContext(t) + producerPath, _, export, consumer, consumerPath, _ := standUpOffering(t, ctx) + + aliceCfg := userKcpConfig(t, "alice", consumerPath) + alice, err := client.New(aliceCfg, client.Options{Scheme: testScheme}) + if err != nil { + t.Fatal(err) + } + bobCfg := userKcpConfig(t, "bob", consumerPath) + bob, err := client.New(bobCfg, client.Options{Scheme: testScheme}) + if err != nil { + t.Fatal(err) + } + + binding := bindingFor("things", producerPath, export) + + // No grant yet: alice cannot even enter the workspace. + if err := alice.Create(ctx, binding.DeepCopy()); err == nil { + t.Fatal("alice bound without any RBAC in the consumer workspace") + } + + // The grant a tenancy admin Membership would materialize. + grantWorkspaceAdmin(t, ctx, consumer, "alice") + + waitFor(t, ctx, "alice's native bind to succeed", func(ctx context.Context) (bool, error) { + err := alice.Create(ctx, binding.DeepCopy()) + return err == nil || apierrors.IsAlreadyExists(err), nil + }) + t.Cleanup(func() { + cleanupCtx, cancel := context.WithTimeout(context.Background(), time.Minute) + defer cancel() + _ = consumer.Delete(cleanupCtx, &apisv1alpha2.APIBinding{ObjectMeta: metav1.ObjectMeta{Name: "things"}}) + }) + waitFor(t, ctx, "alice's binding to be bound", func(ctx context.Context) (bool, error) { + var got apisv1alpha2.APIBinding + if err := alice.Get(ctx, client.ObjectKey{Name: "things"}, &got); err != nil { + return false, nil + } + return got.Status.Phase == apisv1alpha2.APIBindingPhaseBound, nil + }) + + // bob holds nothing there: refused, by the workspace, not by us. + if err := bob.Create(ctx, bindingFor("bobs", producerPath, export)); err == nil { + t.Fatal("bob bound with no RBAC in the consumer workspace") + } + + // And alice can disable, natively. + if err := alice.Delete(ctx, &apisv1alpha2.APIBinding{ObjectMeta: metav1.ObjectMeta{Name: "things"}}); err != nil { + t.Fatalf("alice unbinding: %v", err) + } +} + +// A BYO provider needs no provisioning: any workspace becomes a provider +// workspace by binding marketplace-publish itself — the binding is the +// consent — and a Provider record naming its path makes its offerings +// resolvable. +func TestScenarioExternalProviderPublishesByBinding(t *testing.T) { + ctx := testContext(t) + sfx := randomSuffix(t) + wsName := "byo-" + sfx + producerName := "byo-prov-" + sfx + exportName := "things.byo-" + sfx + ".marketplace.platform.kcp.io" + + ws := createWorkspace(t, ctx, wsName, "", "") + byo := adminClient(t, "root:"+wsName) + + // The consent: the workspace's own admin binds marketplace-publish, + // accepting its claims. + binding := &apisv1alpha2.APIBinding{ + ObjectMeta: metav1.ObjectMeta{Name: exportPublish}, + Spec: apisv1alpha2.APIBindingSpec{ + Reference: apisv1alpha2.BindingReference{ + Export: &apisv1alpha2.ExportBindingReference{Path: exportsPath, Name: exportPublish}, + }, + PermissionClaims: acceptedPublishClaims(), + }, + } + waitFor(t, ctx, "binding marketplace-publish by hand", func(ctx context.Context) (bool, error) { + err := byo.Create(ctx, binding.DeepCopy()) + return err == nil || apierrors.IsAlreadyExists(err), nil + }) + + registerProducer(t, ctx, producerName, marketplacev1alpha1.ProducerModeExternal, "root:"+wsName) + installThingsExport(t, ctx, byo, exportName) + export := publishExport(t, ctx, byo, exportName, "things") + + // Publishing taught the Provider record its cluster. + catalog := adminClient(t, catalogPath) + var rec marketplacev1alpha1.Producer + if err := catalog.Get(ctx, client.ObjectKey{Name: producerName}, &rec); err != nil { + t.Fatal(err) + } + if rec.Status.WorkspaceCluster != ws.Spec.Cluster { + t.Fatalf("provider learned cluster %q, want %q", rec.Status.WorkspaceCluster, ws.Spec.Cluster) + } + + // And a consumer can enable it like any platform offering: a plain + // workspace, a plain bind. + consumerWS := createWorkspace(t, ctx, "consumer-"+sfx, "", "") + consumer := adminClient(t, "root:"+consumerWS.Name) + bindOffering(t, ctx, consumer, "things", "root:"+wsName, export) +} + +// acceptedPublishClaims mirrors, on the consumer side, every claim the +// publish export declares — what kcp's default-binding controller does for +// typed workspaces, spelled out here because BYO binds by hand. +func acceptedPublishClaims() []apisv1alpha2.AcceptablePermissionClaim { + accept := func(group, resource string, verbs ...string) apisv1alpha2.AcceptablePermissionClaim { + return apisv1alpha2.AcceptablePermissionClaim{ + ScopedPermissionClaim: apisv1alpha2.ScopedPermissionClaim{ + PermissionClaim: apisv1alpha2.PermissionClaim{ + GroupResource: apisv1alpha2.GroupResource{Group: group, Resource: resource}, + Verbs: verbs, + }, + Selector: apisv1alpha2.PermissionClaimSelector{MatchAll: true}, + }, + State: apisv1alpha2.ClaimAccepted, + } + } + return []apisv1alpha2.AcceptablePermissionClaim{ + accept("apis.kcp.io", "apiexports", "get", "list", "watch"), + accept("apis.kcp.io", "apiexportendpointslices", "get", "list", "watch"), + accept("apis.kcp.io", "apiresourceschemas", "get", "list", "watch"), + accept("core.kcp.io", "logicalclusters", "get", "list", "watch"), + accept("rbac.authorization.k8s.io", "clusterroles", "get", "list", "watch", "create", "update", "delete"), + accept("rbac.authorization.k8s.io", "clusterrolebindings", "get", "list", "watch", "create", "update", "delete"), + } +} diff --git a/mcp/README.md b/mcp/README.md index fd1109a..f4f7781 100644 --- a/mcp/README.md +++ b/mcp/README.md @@ -28,7 +28,10 @@ explanation. | Path | Description | |------|-------------| -| `cmd` | cobra commands: `serve`. | +| `cmd` | cobra commands: `serve`, `init`, `operator`. | +| `config/apiexport` | the marketplace offering: the `mcp` APIExport, its `MCPEndpoint` schema, the client instructions ConfigMap, the `bind` grant. | +| `pkg/bootstrap` | `init`: applies `config/apiexport` into `root:mcp:controllers` and mints the server's identity. | +| `pkg/operator` | watches the export's endpoint slice; writes the impersonation grant and the `MCPEndpoint` report into each workspace that enabled MCP. | | `internal/config` | flag surface. | | `internal/access` | client for the access virtual workspace, with the per-caller cache. | | `internal/mcp` | the virtual workspace: serving, authentication, per-caller scope. | @@ -60,6 +63,124 @@ The authentication configuration must match kcp's. Prefer kcp is started with; the `--oidc-*` flags work too but have to be kept in step by hand. +## Connecting a client + +Any MCP client that can send a bearer token works: the front-proxy +validates it against the same issuer as every other kcp request and +forwards the identity, and the server then acts as that person. In the +Tilt stack the issuer is dex at `https://dex.kcp.localhost:8443/dex`, the +server is `https://kcp.localhost:8443/services/mcp`, and the console's own +OAuth client — `kcp`, public, PKCE — is the one to use. + +### Why dynamic client registration does not work here + +The MCP spec expects a client to find its authorization server by itself: +fetch RFC 9728 metadata from the resource, fetch the server's RFC 8414 +metadata from the issuer, register a client there (RFC 7591), sign in. +This server implements its half — `--oauth-authorization-servers` turns on +the `/.well-known/oauth-protected-resource` endpoint and the +`WWW-Authenticate` hint on every 401, served ahead of the authentication +filters — but two things in front of and behind it stop the flow: + +- **kcp's front-proxy authenticates everything.** An unauthenticated + request for the metadata never reaches this server; the proxy answers + it with its own 401, a Kubernetes `Status` with no `WWW-Authenticate`. + The client then falls back to treating the server's origin as the + authorization server and POSTs `/register` to it — which is the + `Dynamic Client Registration rejected (HTTP 401): {"kind":"Status",…}` + Claude Code reports. +- **dex has no registration endpoint.** Its metadata carries no + `registration_endpoint`, so even a client that found it could not + register. + +Until that changes — the honest fix is this server on its own hostname, +authenticating OIDC tokens directly so discovery is reachable, plus a +registration endpoint that hands every registrant the public client — +clients have to be given the client up front. + +### Claude Code + +Pre-registered client, with discovery pointed straight at the issuer: + +```sh +claude mcp add-json kcp '{"type":"http","url":"https://kcp.localhost:8443/services/mcp","oauth":{"clientId":"kcp","callbackPort":8000,"authServerMetadataUrl":"https://dex.kcp.localhost:8443/dex/.well-known/openid-configuration"}}' +claude mcp login kcp +``` + +No secret — `kcp` is a public client — and port 8000 is a redirect URI dex +has for it (`hack/tilt/dex.yaml`). The plain `claude mcp add` form fails +for the reasons above. Claude Code runs on Node, which does not share the +browser's certificate exceptions, and the stack uses two self-signed CAs +(kcp's and dex's), so start it from a shell with both in one bundle: + +```sh +kubectl --kubeconfig .tilt/tilt-contrib.kubeconfig config view --raw \ + -o jsonpath='{.clusters[0].cluster.certificate-authority-data}' | base64 -d > /tmp/kcp-bundle.pem +cat .tilt/dex/ca.crt >> /tmp/kcp-bundle.pem +export NODE_EXTRA_CA_CERTS=/tmp/kcp-bundle.pem +``` + +### Codex + +Codex's OAuth flow needs registration too, so give it a token instead. +`contribctl login` runs the browser flow against dex and caches the ID +token, which kcp accepts as a bearer: + +```sh +bin/contribctl login --issuer https://dex.kcp.localhost:8443/dex --url https://kcp.localhost:8443 +export KCP_MCP_TOKEN=$(jq -r '.[].idToken' ~/.config/tenancyctl/tokens.json | head -1) +``` + +```toml +# ~/.codex/config.toml +[mcp_servers.kcp] +url = "https://kcp.localhost:8443/services/mcp" +bearer_token_env_var = "KCP_MCP_TOKEN" +``` + +Codex trusts the system store, so import both CA certificates there. + +### Checking without a client + +The same thing by hand: a token from dex's password grant (development +only; `enablePasswordDB` in the Tilt dex config) and an `initialize` +through the front-proxy, the request the e2e tests also start from: + +```sh +TOKEN=$(curl -sk -X POST https://dex.kcp.localhost:8443/dex/token \ + -d grant_type=password -d client_id=kcp -d scope='openid email groups' \ + -d username=alice@team-a.example.com -d password=password | jq -r .access_token) +curl -sk -X POST https://kcp.localhost:8443/services/mcp \ + -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \ + -H 'Accept: application/json, text/event-stream' \ + -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}' +``` + +A 200 with `"serverInfo":{"name":"kcp"}` means the whole chain — proxy, +token, server — is fine, and anything a client still reports is on the +client's side: usually the certificate, or registration. + +### The same instructions, in the console + +Whoever enables MCP in a project sees these steps on the producer's page +in the console, with the server, issuer, client id and their own +workspace filled in. They come from +[`config/apiexport/instructions.yaml`](config/apiexport/instructions.yaml), +a ConfigMap the `mcp` APIExport names in its +`marketplace.kcp.hub/instructions` annotation; `init` applies it +with the export, and the marketplace mirrors it into the catalog. To +change what people are told, edit that file and apply it into the +controllers workspace — no rebuild: + +```sh +kubectl --kubeconfig .tilt/tilt-contrib.kubeconfig \ + --server https://kcp.localhost:8443/clusters/root:mcp:controllers \ + apply -f mcp/config/apiexport/instructions.yaml +``` + +The format and the `{{variables}}` it may use are documented in the +[marketplace README](../marketplace/README.md#instructions-how-a-producer-says-here-is-how-to-use-this). + ## Testing `make test` is unit tests. `make test-e2e` is the real thing: @@ -123,7 +244,7 @@ operator policy over what AI agents may do, not a client preference. `core` is everything an agent needs to navigate its workspaces and read any resource in them, including CRDs and bound APIs, via the generic -`list_resources`/`get_resource`. `apis` is API provider machinery, `admin` is +`list_resources`/`get_resource`. `apis` is API producer machinery, `admin` is kcp operator internals (shards and topology exist only in the root workspace), and `write` is free-form mutation — all opt-in because they are noise or risk for ordinary callers. Every tool remains subject to the caller's scope and to @@ -145,6 +266,24 @@ internal function call. The cost is an HTTP hop, which the per-caller cache MCP session makes. The access graph is already eventually consistent, so the TTL widens an existing staleness window rather than introducing a new one. +**Enabling MCP is a marketplace offering.** MCP is not an API, so there is +nothing for a consumer to bind in order to "get" it. What they actually +have to do is let this server act as them in their workspace — see the +impersonation note below — and that is a per-workspace, opt-in, revocable +grant, which is exactly the shape of an enablement. + +So `config/apiexport/` publishes one APIExport whose permission claims +cover the RBAC that grant needs. Binding it is the consent; `mcp operator` +watching the export's endpoint slice spends those claims on the single +impersonation ClusterRole and ClusterRoleBinding, and then writes an +`MCPEndpoint` into the workspace so whoever enabled it can see that it +worked and where to point a client. Deleting the binding revokes the +claims and with them the operator's reach — consent and capability are the +same fact, rather than two things that can drift. + +`MCPEndpoint` has no spec on purpose: there is nothing to ask for, because +the binding is the request. It is a report. + **Why impersonation, not the caller's token.** Behind kcp's front-proxy the caller's bearer token is consumed by the proxy, which forwards identity as `X-Remote-*` headers instead. There is no token left to replay, so this server diff --git a/mcp/cmd/init.go b/mcp/cmd/init.go new file mode 100644 index 0000000..2ae6f81 --- /dev/null +++ b/mcp/cmd/init.go @@ -0,0 +1,93 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package cmd + +import ( + "fmt" + "os" + "time" + + "github.com/spf13/cobra" + + "k8s.io/client-go/tools/clientcmd" + "k8s.io/klog/v2" + + "github.com/kcp-dev/contrib-virtual-workspaces/mcp/pkg/bootstrap" +) + +var initOpts struct { + kubeconfig string + bootstrap.Options +} + +var initCmd = &cobra.Command{ + Use: "init", + Short: "Install the mcp APIExport a consumer enables by binding", + Long: `Install this component's kcp-side objects. + +One APIExport, and it is the enablement mechanism rather than an API: MCP +is an endpoint, so there is nothing for a consumer to bind in order to +"get" it. What they are consenting to is letting the MCP server act as +them in their workspace, and the export's permission claims are exactly +the RBAC the operator needs to grant itself that. Binding is the consent; +deleting the binding revokes it. + +Safe to run repeatedly: everything is created if absent and brought to +the committed shape otherwise.`, + Args: cobra.NoArgs, + SilenceUsage: true, + RunE: func(c *cobra.Command, _ []string) error { + cfg, err := clientcmd.BuildConfigFromFlags("", initOpts.kubeconfig) + if err != nil { + return fmt.Errorf("loading kubeconfig %q: %w", initOpts.kubeconfig, err) + } + + result, err := bootstrap.Init(c.Context(), cfg, initOpts.Options) + if err != nil { + return err + } + + logger := klog.FromContext(c.Context()) + logger.Info("mcp installed", + "workspace", result.WorkspacePath, + "exportCluster", result.ExportCluster, + "sliceURLs", result.SliceURLs) + logger.Info("a consumer enables MCP by binding this export", + "path", result.WorkspacePath, "export", bootstrap.ExportName) + return nil + }, +} + +func init() { + fs := initCmd.Flags() + fs.StringVar(&initOpts.kubeconfig, "kubeconfig", os.Getenv("KUBECONFIG"), + "Path to the kubeconfig for the target kcp. Defaults to $KUBECONFIG.") + fs.StringVar(&initOpts.WorkspacePrefix, "workspace-prefix", bootstrap.DefaultWorkspacePrefix, + "Parent path the component's workspace is created under.") + fs.StringVar(&initOpts.ControllersWorkspace, "controllers-workspace", bootstrap.DefaultControllersWorkspace, + "Name of the workspace this component owns, created under --workspace-prefix.") + fs.StringVar(&initOpts.WorkspaceType, "workspace-type", bootstrap.DefaultWorkspaceType, + "WorkspaceType for workspaces created here.") + fs.StringSliceVar(&initOpts.ServerUsers, "server-user", nil, + "Additional User to grant the operator role to, repeatable. kcp-operator mounts a "+ + "client certificate rather than a ServiceAccount token, so pass its common name, "+ + "e.g. --server-user=mcp-vw.") + fs.StringSliceVar(&initOpts.ServerGroups, "server-group", nil, + "Additional Group to grant the operator role to, repeatable.") + fs.DurationVar(&initOpts.Timeout, "timeout", 3*time.Minute, + "Bounds the apply-and-verify loop.") +} diff --git a/mcp/cmd/operator.go b/mcp/cmd/operator.go new file mode 100644 index 0000000..acbc999 --- /dev/null +++ b/mcp/cmd/operator.go @@ -0,0 +1,102 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package cmd + +import ( + "fmt" + "os" + "strings" + + "github.com/spf13/cobra" + + "k8s.io/client-go/tools/clientcmd" + + "github.com/kcp-dev/contrib-virtual-workspaces/mcp/pkg/bootstrap" + "github.com/kcp-dev/contrib-virtual-workspaces/mcp/pkg/operator" + "github.com/kcp-dev/contrib-virtual-workspaces/mcp/pkg/toolsets" +) + +var operatorOpts struct { + kubeconfig string + workspacePath string + operator.Options +} + +var operatorCmd = &cobra.Command{ + Use: "operator", + Short: "Grant MCP what it needs in each workspace that enabled it", + Long: `Reconcile the workspaces that have enabled MCP. + +A workspace enables MCP by binding this component's APIExport, which is +what puts it on the export's endpoint slice and what grants this operator +the claims it spends. For each such workspace it writes one thing — the +right for the MCP server to impersonate callers there — and then records +an MCPEndpoint so whoever enabled it can see that it worked and where to +point a client. + +Impersonation is all the server gets, and all it needs: every resource it +touches it touches as the caller, so kcp authorizes each request against +their rights.`, + Args: cobra.NoArgs, + SilenceUsage: true, + RunE: func(c *cobra.Command, _ []string) error { + cfg, err := clientcmd.BuildConfigFromFlags("", operatorOpts.kubeconfig) + if err != nil { + return fmt.Errorf("loading kubeconfig %q: %w", operatorOpts.kubeconfig, err) + } + // The endpoint slice lives in the workspace this component owns, so + // the client has to be pointed at it. An operator-minted kubeconfig + // addresses the root workspace, where there is no slice of ours and + // so nothing to discover — which looks exactly like a working + // operator that never reconciles anything. + if operatorOpts.workspacePath != "" { + cfg.Host = retargetHost(cfg.Host, operatorOpts.workspacePath) + } + operatorOpts.RestConfig = cfg + return operator.Run(c.Context(), operatorOpts.Options) + }, +} + +func init() { + fs := operatorCmd.Flags() + fs.StringVar(&operatorOpts.kubeconfig, "kubeconfig", os.Getenv("KUBECONFIG"), + "Path to the kubeconfig for the target kcp. Defaults to $KUBECONFIG.") + fs.StringVar(&operatorOpts.Slice, "apiexport-endpointslice", bootstrap.ExportName, + "APIExportEndpointSlice following the mcp export. The clusters on it are the "+ + "workspaces that enabled MCP.") + fs.StringVar(&operatorOpts.ServerURL, "server-url", "", + "Where an MCP client connects, reported to consumers in their MCPEndpoint, "+ + "e.g. https://kcp.example.com/services/mcp.") + fs.StringVar(&operatorOpts.ImpersonateUser, "impersonate-user", "", + "The identity the MCP server presents, and so the subject the impersonation "+ + "grant names. Required: it is what the grant is for.") + fs.StringSliceVar(&operatorOpts.Toolsets, "toolsets", toolsets.Default(), + "Toolsets the server exposes, reported to consumers.") + fs.StringVar(&operatorOpts.workspacePath, "workspace-path", "", + "Workspace holding this component's APIExport and endpoint slice, "+ + "e.g. root:mcp:controllers. Empty uses the kubeconfig's own cluster "+ + "URL unchanged, which only works if it already points there.") +} + +// retargetHost replaces whatever cluster a kubeconfig addresses with one +// workspace path, keeping the server. +func retargetHost(host, workspacePath string) string { + if i := strings.Index(host, "/clusters/"); i >= 0 { + host = host[:i] + } + return strings.TrimSuffix(host, "/") + "/clusters/" + workspacePath +} diff --git a/mcp/cmd/root.go b/mcp/cmd/root.go index 81aa41d..0b03647 100644 --- a/mcp/cmd/root.go +++ b/mcp/cmd/root.go @@ -39,6 +39,8 @@ var rootCmd = &cobra.Command{ func init() { rootCmd.AddCommand(serveCmd) + rootCmd.AddCommand(initCmd) + rootCmd.AddCommand(operatorCmd) klogFlags := goflag.NewFlagSet("klog", goflag.ContinueOnError) klog.InitFlags(klogFlags) diff --git a/mcp/config/apiexport/apiexport-mcp.yaml b/mcp/config/apiexport/apiexport-mcp.yaml new file mode 100644 index 0000000..f2723e9 --- /dev/null +++ b/mcp/config/apiexport/apiexport-mcp.yaml @@ -0,0 +1,51 @@ +# mcp - the offering a consumer enables to get MCP in their workspace. +# +# The claims are the point, not the resource. MCP is not an API: it is an +# endpoint at /services/mcp that acts on a caller's behalf, and behind the +# front-proxy the caller's token is consumed by the proxy, so the server +# has to IMPERSONATE them. kcp checks that right in every workspace it +# reaches into, and kcp RBAC does not inherit down the tree — so the +# server needs the grant written in each workspace that wants MCP. +# +# Binding this export is how a consumer says yes to that. The claims cover +# the ClusterRole and ClusterRoleBinding the operator then writes there — +# nothing more, which is why `impersonate` is the only verb it ever grants +# itself. Deleting the binding revokes the claims, and with them the +# operator's ability to touch that workspace at all. +# +# MCPEndpoint is served so the enablement is visible from inside: it is +# written by the operator, and it answers "did it work" and "where do I +# point my client" without leaving the workspace. +apiVersion: apis.kcp.io/v1alpha2 +kind: APIExport +metadata: + name: mcp + # Published to the marketplace catalog. The offering IS this export. + annotations: + marketplace.kcp.hub/publish: "true" + marketplace.kcp.hub/display-name: MCP + # The ConfigMap below, in this same workspace: how to connect a client. + marketplace.kcp.hub/instructions: mcp-instructions + marketplace.kcp.hub/description: >- + The Model Context Protocol over this workspace. Enabling lets the MCP + server act as you here; what a session can see is whatever your own + access allows. +spec: + resources: + - name: mcpendpoints + group: mcp.platform.kcp.io + schema: v261001-fbafaea.mcpendpoints.mcp.platform.kcp.io + storage: + crd: {} + permissionClaims: + - group: rbac.authorization.k8s.io + resource: clusterroles + verbs: [get, list, watch, create, update, delete] + - group: rbac.authorization.k8s.io + resource: clusterrolebindings + verbs: [get, list, watch, create, update, delete] + # Read-only, and only to learn the workspace's own canonical path for + # the endpoint it reports back. + - group: core.kcp.io + resource: logicalclusters + verbs: [get, list, watch] diff --git a/mcp/config/apiexport/apiexportendpointslice.yaml b/mcp/config/apiexport/apiexportendpointslice.yaml new file mode 100644 index 0000000..c97c6ce --- /dev/null +++ b/mcp/config/apiexport/apiexportendpointslice.yaml @@ -0,0 +1,12 @@ +# The slice the mcp operator follows to learn which workspaces have +# enabled MCP. A workspace appears here once it binds the export, which is +# the same moment it consented — so the slice is both the discovery +# mechanism and the list of workspaces the operator may act in. +apiVersion: apis.kcp.io/v1alpha1 +kind: APIExportEndpointSlice +metadata: + name: mcp +spec: + export: + name: mcp + path: __EXPORTS_PATH__ diff --git a/mcp/config/apiexport/apiresourceschema-mcpendpoints.mcp.platform.kcp.io.yaml b/mcp/config/apiexport/apiresourceschema-mcpendpoints.mcp.platform.kcp.io.yaml new file mode 100644 index 0000000..0560ee7 --- /dev/null +++ b/mcp/config/apiexport/apiresourceschema-mcpendpoints.mcp.platform.kcp.io.yaml @@ -0,0 +1,81 @@ +apiVersion: apis.kcp.io/v1alpha1 +kind: APIResourceSchema +metadata: + name: v261001-fbafaea.mcpendpoints.mcp.platform.kcp.io +spec: + group: mcp.platform.kcp.io + names: + kind: MCPEndpoint + listKind: MCPEndpointList + plural: mcpendpoints + singular: mcpendpoint + scope: Cluster + versions: + - additionalPrinterColumns: + - jsonPath: .status.url + name: URL + type: string + - jsonPath: .status.phase + name: Phase + type: string + - jsonPath: .metadata.creationTimestamp + name: Age + type: date + - jsonPath: .status.message + name: Message + priority: 1 + type: string + name: v1alpha1 + schema: + description: |- + MCPEndpoint reports that MCP is enabled in this workspace, and where to + reach it. + + It carries no spec because there is nothing to ask for: enabling MCP is + the APIBinding, and this object is what the operator writes back once + that binding has let it grant itself the impersonation it needs. Reading + it answers the two questions enabling raises — "did it work?" and "where + do I point my client?" — without leaving the workspace. + properties: + apiVersion: + description: |- + APIVersion defines the versioned schema of this representation of an object. + Servers should convert recognized schemas to the latest internal value, and + may reject unrecognized values. + More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + type: string + kind: + description: |- + Kind is a string value representing the REST resource this object represents. + Servers may infer this from the endpoint the client submits requests to. + Cannot be updated. + In CamelCase. + More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + type: string + metadata: + type: object + status: + description: MCPEndpointStatus is everything this kind has to say. + properties: + message: + type: string + phase: + description: Phase describes whether MCP is usable in this workspace. + type: string + toolsets: + description: Toolsets are the tool groups the server exposes. + items: + type: string + type: array + url: + description: |- + URL is where an MCP client connects. It is the same address for + every workspace — which workspaces a session can see comes from the + caller's own access, not from the URL. + type: string + type: object + type: object + served: true + storage: true + subresources: + status: {} diff --git a/mcp/config/apiexport/bootstrap.go b/mcp/config/apiexport/bootstrap.go new file mode 100644 index 0000000..3e97b0e --- /dev/null +++ b/mcp/config/apiexport/bootstrap.go @@ -0,0 +1,50 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// Package apiexport holds the kcp-side assets the mcp component needs in +// the workspace hosting its APIExport. +// +// One export, and it is the whole enablement mechanism. MCP is not an API, +// so there is nothing for a consumer to bind in order to "get" it — what a +// consumer actually has to do is let the MCP server act as them in their +// workspace. This export is how: its permission claims cover exactly the +// RBAC the server needs to grant itself that, so binding it IS the +// consent, and deleting the binding revokes every claim it carried. +// +// They are embedded rather than applied with kubectl so the init binary +// can bootstrap a deployment on its own, following the same pattern as +// kcp's own config packages. +package apiexport + +import "embed" + +//go:embed *.yaml +var FS embed.FS + +// Order is the sequence the assets must be applied in. It is load-bearing: +// +// - the schema before the export, because an APIExport naming an +// APIResourceSchema that does not exist yet is rejected; +// - the bind RBAC before the endpoint slice, because kcp gates slice +// creation on a `bind` verb against the export that cluster-admin does +// not satisfy. +var Order = []string{ + "apiresourceschema-mcpendpoints.mcp.platform.kcp.io.yaml", + "apiexport-mcp.yaml", + "instructions.yaml", + "rbac-bind.yaml", + "apiexportendpointslice.yaml", +} diff --git a/mcp/config/apiexport/instructions.yaml b/mcp/config/apiexport/instructions.yaml new file mode 100644 index 0000000..b9946fc --- /dev/null +++ b/mcp/config/apiexport/instructions.yaml @@ -0,0 +1,244 @@ +# How to use MCP, shown in the console to whoever enables it. +# +# Each key is a section; a leading number orders them and is not shown. +# The text is a small markdown subset — headings, paragraphs, lists, +# fenced code, `inline code`, [links](https://...) — with {{variables}} +# the console fills in for the person reading: {{server}} is the +# front-proxy, {{project}} and {{tenant}} are where they are working, +# {{user}} is who they are. Nothing here is executed anywhere; it is text +# rendered as text. +apiVersion: v1 +kind: ConfigMap +metadata: + name: mcp-instructions + # ConfigMaps are namespaced; the annotation names only the name, so the + # convention is the default namespace. + namespace: default +data: + 00-overview.md: | + # Connecting a client + + MCP is served at `{{server}}/services/mcp`, over streamable HTTP. It + signs you in with the same account as this console — the first + request answers with an OAuth challenge, your client opens the sign-in + page, and from then on every tool call runs as **{{user}}**. + + A session sees exactly the projects your access allows. Right now that + includes `{{tenant}}/{{project}}`; enabling MCP in another project adds + it to the same session, with no client change. + + ## What the tools are + + The default toolset is `core`, read-only: + + - `list_kcp_workspaces` — the projects you can reach, with their ids. + - `list_kcp_apibindings`, `get_kcp_apibinding` — what is enabled in one. + - `list_kcp_apiexports`, `get_kcp_apiexport` — what a producer publishes. + - `list_resources`, `get_resource` — any object of any bound API, by + group, version and resource. + + Every tool takes a `workspace`: the logical cluster id, not the name. + This project's is `{{cluster}}`. Writes (`create_resource`, + `patch_resource`, `delete_resource`, …) are the `write` toolset, which + the operator switches on separately — ask before assuming it is there. + + Pick a client below. + + 10-claude-code.md: | + # Claude Code + + ## Add the server + + This platform signs you in through `{{issuer}}`, which does not do + dynamic client registration — so Claude Code cannot invent a client + for itself, and the plain `claude mcp add` ends in *Dynamic Client + Registration rejected*. Hand it the public client the console already + uses instead, and tell it where the issuer is: + + ```sh + claude mcp add-json kcp '{"type":"http","url":"{{server}}/services/mcp","oauth":{"clientId":"{{clientId}}","callbackPort":8000,"authServerMetadataUrl":"{{issuer}}/.well-known/openid-configuration"}}' + ``` + + No secret: `{{clientId}}` is a public client doing PKCE, and port 8000 + is a redirect it is registered with. To share the server with everyone + working in a repository, add `--scope project` — that writes a + `.mcp.json` next to the code, which you commit. + + ## Sign in + + ```sh + claude mcp login kcp + ``` + + opens the browser on the same sign-in page as this console. Or, in a + session, type `/mcp`, select the server and choose *Authenticate*. + Afterwards `/mcp` lists it as *connected* with its tools. If the + browser warns about the certificate first, see the last section. + + ## Use it + + Tools are named `mcp__kcp__`, and Claude picks them from the + description; you just ask. Scope your questions to this project by + naming it: + + ``` + > which kcp workspaces can I see? + > in workspace {{cluster}}, which APIs are bound? + > list the resources of every bound API in {{cluster}} and summarise them + > get apibinding {{binding}} in {{cluster}} and explain its status + ``` + + If you want a tool called exactly, name it: + + ``` + > use list_resources on workspace {{cluster}} for group "" version v1 resource configmaps + ``` + + ## Keep it in the loop + + A `CLAUDE.md` line saves saying it every session: + + ```md + My kcp project is {{tenant}}/{{project}}, workspace id {{cluster}}. + Use the kcp MCP tools for anything about it; never guess resources, list them. + ``` + + ## Check or remove + + ```sh + claude mcp list # every server, with its health + claude mcp get kcp # this one, with the URL it was added as + claude mcp remove kcp + ``` + + 20-claude-desktop.md: | + # Claude Desktop + + Settings → Connectors → *Add custom connector*, then: + + - Name: `kcp` + - Remote MCP server URL: `{{server}}/services/mcp` + + Click *Add*, then *Connect*: the sign-in page opens in your browser. + Once connected, the tools appear under the connector in any chat. + + Ask as you would in Claude Code — name the workspace id `{{cluster}}` + when you mean this project, so the answer is about it and not about + the first workspace the tools happen to list. + + 30-codex.md: | + # Codex + + ## Get a token + + Codex's own OAuth flow needs the issuer to register clients on the + fly, which `{{issuer}}` does not do. Sign in with the platform CLI + instead and give Codex the token it caches: + + ```sh + contribctl login --issuer {{issuer}} --url {{server}} + export KCP_MCP_TOKEN=$(jq -r '.[].idToken' ~/.config/tenancyctl/tokens.json | head -1) + ``` + + The token expires with your session; run both again when Codex starts + answering 401. + + ## Add the server + + In `~/.codex/config.toml`: + + ```toml + [mcp_servers.kcp] + url = "{{server}}/services/mcp" + bearer_token_env_var = "KCP_MCP_TOKEN" + ``` + + Start Codex from a shell where `KCP_MCP_TOKEN` is set. `codex mcp + list` shows the server; in a session, `/mcp` shows what is connected + and which tools came with it. Older Codex releases only spoke HTTP + servers behind a flag; if the server is listed but never connects, add + `experimental_use_rmcp_client = true` at the top of the file. + + ## Use it + + Codex calls the tools by itself; name the workspace id so it does not + have to ask which project you mean: + + ``` + › list my kcp workspaces + › in kcp workspace {{cluster}}, what APIs are bound and what do they serve? + › read the configmaps in workspace {{cluster}} and tell me which look like instructions + ``` + + An `AGENTS.md` in the repository can carry the context so you do not + repeat it: + + ```md + The kcp project for this repo is {{tenant}}/{{project}} (workspace {{cluster}}). + Use the kcp MCP tools to look things up there rather than guessing. + ``` + + ## Check or remove + + ```sh + codex mcp list + codex mcp get kcp + codex mcp remove kcp + ``` + + 40-cursor.md: | + # Cursor + + In the project you are working on, create `.cursor/mcp.json` — or add + to it — with: + + ```json + { + "mcpServers": { + "kcp": { + "url": "{{server}}/services/mcp" + } + } + } + ``` + + Cursor shows the server under *Settings → MCP*, with a sign-in prompt + on first use. A global `~/.cursor/mcp.json` works the same way for + every project. + + 90-troubleshooting.md: | + # If it does not connect + + - **Dynamic Client Registration rejected (HTTP 401).** The client tried + to register itself, and this platform's issuer does not offer that. + Add the server with the pre-registered client as shown for your + client above; the plain *add* form cannot work here. + - **Sign-in works but tools see no workspaces.** MCP acts as you by + impersonation, and that right is granted per project when MCP is + enabled there. Check `mcpendpoints/mcp` in the project reports + `Ready`. + - **A tool is refused.** kcp authorizes every call as you, so a refusal + means your own role in that project does not allow it. + - **A write tool is missing.** The `write` toolset is off unless the + operator enabled it; `core` is read-only by design. + - **The browser warns about the certificate at sign-in.** Accept it + once at `{{issuer}}` and once at `{{server}}/services/mcp`, and again + whenever either is regenerated. + + ## The client refuses the certificate + + This development stack serves self-signed certificates — one for the + platform, another for the issuer — and a CLI does not share the + browser's exceptions. Build one bundle holding both and hand it to the + client. The platform's CA is in any kubeconfig that reaches + `{{server}}`; the issuer's is the file dex was started with (in this + stack, `.tilt/dex/ca.crt` in the repository): + + ```sh + kubectl config view --raw -o jsonpath='{.clusters[0].cluster.certificate-authority-data}' | base64 -d > kcp-bundle.pem + cat .tilt/dex/ca.crt >> kcp-bundle.pem + export NODE_EXTRA_CA_CERTS=$PWD/kcp-bundle.pem # Claude Code (Node); start claude from this shell + ``` + + Codex uses the system trust store: import both certificates there (on + macOS, Keychain Access → System → import, then trust each for SSL). diff --git a/mcp/config/apiexport/rbac-bind.yaml b/mcp/config/apiexport/rbac-bind.yaml new file mode 100644 index 0000000..b88f7d7 --- /dev/null +++ b/mcp/config/apiexport/rbac-bind.yaml @@ -0,0 +1,29 @@ +# Who may bind the mcp export. +# +# `bind` is what kcp checks when a consumer creates the APIBinding that +# enables MCP. Granting it to system:authenticated does not give anyone +# anything by itself: enabling still requires the right to create an +# APIBinding in a workspace of one's own, which is what a tenancy admin +# Membership materializes. This only opens the export's side of it. +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: mcp:bind +rules: + - apiGroups: ["apis.kcp.io"] + resources: ["apiexports"] + resourceNames: ["mcp"] + verbs: ["bind"] +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: mcp:bind +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: mcp:bind +subjects: + - apiGroup: rbac.authorization.k8s.io + kind: Group + name: system:authenticated diff --git a/mcp/pkg/bootstrap/bootstrap.go b/mcp/pkg/bootstrap/bootstrap.go new file mode 100644 index 0000000..f6238ed --- /dev/null +++ b/mcp/pkg/bootstrap/bootstrap.go @@ -0,0 +1,377 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// 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 + +import ( + "bytes" + "context" + "fmt" + "strings" + "time" + + rbacv1 "k8s.io/api/rbac/v1" + apierrors "k8s.io/apimachinery/pkg/api/errors" + "k8s.io/apimachinery/pkg/api/meta" + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + "k8s.io/apimachinery/pkg/apis/meta/v1/unstructured" + "k8s.io/apimachinery/pkg/runtime/schema" + "k8s.io/apimachinery/pkg/util/wait" + "k8s.io/apimachinery/pkg/util/yaml" + "k8s.io/client-go/discovery" + "k8s.io/client-go/discovery/cached/memory" + "k8s.io/client-go/dynamic" + "k8s.io/client-go/kubernetes" + "k8s.io/client-go/rest" + "k8s.io/client-go/restmapper" + "k8s.io/client-go/util/retry" + "k8s.io/klog/v2" + + accessbootstrap "github.com/kcp-dev/contrib-virtual-workspaces/access/pkg/bootstrap" + "github.com/kcp-dev/contrib-virtual-workspaces/mcp/config/apiexport" + mcpv1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/mcp/sdk/apis/mcp/v1alpha1" +) + +const ( + // DefaultWorkspacePrefix is the parent the component's workspace is + // created under. + DefaultWorkspacePrefix = "root:mcp" + // DefaultControllersWorkspace is the leaf this component owns. + DefaultControllersWorkspace = "controllers" + // DefaultWorkspaceType is the type used for workspaces created here. + DefaultWorkspaceType = "universal" + + // ExportName is the export a consumer binds to enable MCP, and the + // name of the endpoint slice that follows it. + ExportName = "mcp" + + // exportsPathPlaceholder is substituted at apply time: the endpoint + // slice has to name the workspace the export landed in, which is + // configurable, so no committed manifest can carry it. + exportsPathPlaceholder = "__EXPORTS_PATH__" +) + +// Options configures Init. +type Options struct { + // WorkspacePrefix and ControllersWorkspace locate the workspace the + // objects are installed into. + WorkspacePrefix string + ControllersWorkspace string + WorkspaceType string + + // ServerUsers and ServerGroups are the identities granted the role the + // operator needs to read through the export. kcp-operator mounts a + // client certificate, so its server arrives as a User. + ServerUsers []string + ServerGroups []string + + Timeout time.Duration +} + +// Result reports what Init installed. +type Result struct { + // WorkspacePath is where the objects landed. + WorkspacePath string + // ExportCluster is the logical cluster of that workspace, which is + // what a consumer's APIBinding references. + ExportCluster string + // SliceURLs are the per-shard virtual workspace URLs the slice + // resolved to. Empty until a consumer binds. + SliceURLs []string +} + +// Init creates the component's workspace and applies its assets. +func Init(ctx context.Context, cfg *rest.Config, opts Options) (*Result, error) { + if opts.WorkspacePrefix == "" { + opts.WorkspacePrefix = DefaultWorkspacePrefix + } + if opts.ControllersWorkspace == "" { + opts.ControllersWorkspace = DefaultControllersWorkspace + } + if opts.WorkspaceType == "" { + opts.WorkspaceType = DefaultWorkspaceType + } + if opts.Timeout == 0 { + opts.Timeout = 3 * time.Minute + } + + ctx, cancel := context.WithTimeout(ctx, opts.Timeout) + defer cancel() + logger := klog.FromContext(ctx) + + path, err := accessbootstrap.JoinWorkspacePath(opts.WorkspacePrefix, opts.ControllersWorkspace) + if err != nil { + return nil, err + } + + logger.Info("creating the mcp workspace", "path", path) + scoped, err := accessbootstrap.CreateWorkspacePath(ctx, cfg, path, opts.WorkspaceType) + if err != nil { + return nil, fmt.Errorf("create %s: %w", path, err) + } + + if err := applyAssets(ctx, scoped, path); err != nil { + return nil, err + } + + if len(opts.ServerUsers)+len(opts.ServerGroups) > 0 { + kube, err := kubernetes.NewForConfig(scoped) + if err != nil { + return nil, fmt.Errorf("build kubernetes client: %w", err) + } + if err := applyServerIdentity(ctx, kube, opts.ServerUsers, opts.ServerGroups); err != nil { + return nil, fmt.Errorf("grant the operator identity: %w", err) + } + } + + cluster, err := logicalClusterOf(ctx, scoped) + if err != nil { + return nil, err + } + + // A slice publishes no URL until something binds the export, so an + // empty answer here is the normal state of a fresh install, not a + // failure: the operator follows the slice and picks URLs up later. + urls := sliceURLs(ctx, scoped) + + logger.Info("mcp install complete", + "workspace", path, "cluster", cluster, "export", ExportName, "sliceURLs", urls) + return &Result{WorkspacePath: path, ExportCluster: cluster, SliceURLs: urls}, nil +} + +func applyAssets(ctx context.Context, cfg *rest.Config, exportsPath string) error { + dyn, err := dynamic.NewForConfig(cfg) + if err != nil { + return fmt.Errorf("build dynamic client: %w", err) + } + disco, err := discovery.NewDiscoveryClientForConfig(cfg) + if err != nil { + return fmt.Errorf("build discovery client: %w", err) + } + cache := memory.NewMemCacheClient(disco) + mapper := restmapper.NewDeferredDiscoveryRESTMapper(cache) + + for _, asset := range apiexport.Order { + raw, err := apiexport.FS.ReadFile(asset) + if err != nil { + return fmt.Errorf("read %s: %w", asset, err) + } + raw = bytes.ReplaceAll(raw, []byte(exportsPathPlaceholder), []byte(exportsPath)) + if err := applyManifest(ctx, dyn, mapper, cache, raw); err != nil { + return fmt.Errorf("apply %s: %w", asset, err) + } + } + return nil +} + +func applyManifest( + ctx context.Context, + dyn dynamic.Interface, + mapper *restmapper.DeferredDiscoveryRESTMapper, + cache discovery.CachedDiscoveryInterface, + raw []byte, +) error { + decoder := yaml.NewYAMLOrJSONDecoder(bytes.NewReader(raw), 4096) + for { + var obj unstructured.Unstructured + if err := decoder.Decode(&obj); err != nil { + if err.Error() == "EOF" { + return nil + } + return fmt.Errorf("decode manifest: %w", err) + } + if len(obj.Object) == 0 { + continue + } + + gvk := obj.GroupVersionKind() + mapping, err := mapper.RESTMapping(gvk.GroupKind(), gvk.Version) + if err != nil { + // A kind this bootstrap just installed may not be in cached + // discovery yet; refresh once and retry. + cache.Invalidate() + mapper.Reset() + mapping, err = mapper.RESTMapping(gvk.GroupKind(), gvk.Version) + if err != nil { + return fmt.Errorf("map %s: %w", gvk, err) + } + } + + // A namespaced kind has to be addressed through its namespace, or + // the server answers "method not allowed" — which reads like an + // RBAC problem and is not one. Cluster-scoped kinds have no + // namespace to give. + var client dynamic.ResourceInterface = dyn.Resource(mapping.Resource) + if mapping.Scope.Name() == meta.RESTScopeNameNamespace { + ns := obj.GetNamespace() + if ns == "" { + ns = metav1.NamespaceDefault + obj.SetNamespace(ns) + } + client = dyn.Resource(mapping.Resource).Namespace(ns) + } + if _, err := client.Create(ctx, &obj, metav1.CreateOptions{}); err != nil { + if !apierrors.IsAlreadyExists(err) { + return fmt.Errorf("create %s %s: %w", gvk.Kind, obj.GetName(), err) + } + // kcp keeps reconciling some of these (it creates and updates a + // default endpoint slice per export), so a get+update can 409. + err := retry.RetryOnConflict(retry.DefaultRetry, func() error { + existing, err := client.Get(ctx, obj.GetName(), metav1.GetOptions{}) + if err != nil { + return err + } + obj.SetResourceVersion(existing.GetResourceVersion()) + _, err = client.Update(ctx, &obj, metav1.UpdateOptions{}) + return err + }) + if err != nil { + // APIResourceSchemas are immutable; existing is as good as + // applied. + if apierrors.IsInvalid(err) || apierrors.IsForbidden(err) { + continue + } + return fmt.Errorf("update %s %s: %w", gvk.Kind, obj.GetName(), err) + } + } + } +} + +// applyServerIdentity grants the operator what it needs to read the export +// and act through its claims: kcp's workspace gate, the export objects +// themselves, and content on the export. +func applyServerIdentity(ctx context.Context, kube kubernetes.Interface, users, groups []string) error { + role := &rbacv1.ClusterRole{ + ObjectMeta: metav1.ObjectMeta{Name: mcpv1alpha1.GroupName + ":server"}, + Rules: []rbacv1.PolicyRule{ + { + // RBAC means nothing to an identity that cannot enter the + // workspace in the first place. + Verbs: []string{"access"}, + NonResourceURLs: []string{"/"}, + }, + { + APIGroups: []string{"apis.kcp.io"}, + Resources: []string{"apiexports", "apiexportendpointslices", "apibindings"}, + Verbs: []string{"get", "list", "watch"}, + }, + { + APIGroups: []string{"apis.kcp.io"}, + Resources: []string{"apiexports/content"}, + Verbs: []string{"*"}, + }, + }, + } + if _, err := kube.RbacV1().ClusterRoles().Create(ctx, role, metav1.CreateOptions{}); err != nil { + if !apierrors.IsAlreadyExists(err) { + return err + } + if err := retry.RetryOnConflict(retry.DefaultRetry, func() error { + existing, err := kube.RbacV1().ClusterRoles().Get(ctx, role.Name, metav1.GetOptions{}) + if err != nil { + return err + } + existing.Rules = role.Rules + _, err = kube.RbacV1().ClusterRoles().Update(ctx, existing, metav1.UpdateOptions{}) + return err + }); err != nil { + return err + } + } + + subjects := make([]rbacv1.Subject, 0, len(users)+len(groups)) + for _, u := range users { + subjects = append(subjects, rbacv1.Subject{APIGroup: rbacv1.GroupName, Kind: rbacv1.UserKind, Name: u}) + } + for _, g := range groups { + subjects = append(subjects, rbacv1.Subject{APIGroup: rbacv1.GroupName, Kind: rbacv1.GroupKind, Name: g}) + } + + binding := &rbacv1.ClusterRoleBinding{ + ObjectMeta: metav1.ObjectMeta{Name: role.Name}, + RoleRef: rbacv1.RoleRef{APIGroup: rbacv1.GroupName, Kind: "ClusterRole", Name: role.Name}, + Subjects: subjects, + } + if _, err := kube.RbacV1().ClusterRoleBindings().Create(ctx, binding, metav1.CreateOptions{}); err != nil { + if !apierrors.IsAlreadyExists(err) { + return err + } + return retry.RetryOnConflict(retry.DefaultRetry, func() error { + existing, err := kube.RbacV1().ClusterRoleBindings().Get(ctx, binding.Name, metav1.GetOptions{}) + if err != nil { + return err + } + existing.Subjects = subjects + existing.RoleRef = binding.RoleRef + _, err = kube.RbacV1().ClusterRoleBindings().Update(ctx, existing, metav1.UpdateOptions{}) + return err + }) + } + return nil +} + +func logicalClusterOf(ctx context.Context, cfg *rest.Config) (string, error) { + dyn, err := dynamic.NewForConfig(cfg) + if err != nil { + return "", fmt.Errorf("build dynamic client: %w", err) + } + lc, err := dyn.Resource(schema.GroupVersionResource{ + Group: "core.kcp.io", Version: "v1alpha1", Resource: "logicalclusters", + }).Get(ctx, "cluster", metav1.GetOptions{}) + if err != nil { + return "", fmt.Errorf("read this workspace's LogicalCluster: %w", err) + } + name := lc.GetAnnotations()["kcp.io/cluster"] + if name == "" { + return "", fmt.Errorf("the LogicalCluster carries no kcp.io/cluster annotation") + } + return name, nil +} + +// sliceURLs reports the URLs the endpoint slice has published, best effort. +func sliceURLs(ctx context.Context, cfg *rest.Config) []string { + dyn, err := dynamic.NewForConfig(cfg) + if err != nil { + return nil + } + var out []string + _ = wait.PollUntilContextTimeout(ctx, time.Second, 10*time.Second, true, + func(ctx context.Context) (bool, error) { + slice, err := dyn.Resource(schema.GroupVersionResource{ + Group: "apis.kcp.io", Version: "v1alpha1", Resource: "apiexportendpointslices", + }).Get(ctx, ExportName, metav1.GetOptions{}) + if err != nil { + return false, nil + } + endpoints, found, _ := unstructured.NestedSlice(slice.Object, "status", "endpoints") + if !found { + return false, nil + } + out = nil + for _, e := range endpoints { + if m, ok := e.(map[string]interface{}); ok { + if u, ok := m["url"].(string); ok && strings.TrimSpace(u) != "" { + out = append(out, u) + } + } + } + return len(out) > 0, nil + }) + return out +} diff --git a/mcp/pkg/operator/operator.go b/mcp/pkg/operator/operator.go new file mode 100644 index 0000000..2a878ef --- /dev/null +++ b/mcp/pkg/operator/operator.go @@ -0,0 +1,295 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// Package operator turns a consumer's APIBinding into working MCP. +// +// Enabling MCP is not binding an API — MCP is an endpoint, not a resource. +// What a consumer is actually consenting to is letting the MCP server act +// as them in their own workspace, because behind the front-proxy their +// bearer token is consumed by the proxy and the server has nothing to +// replay. It therefore impersonates them, and kcp checks that right in +// every workspace it reaches into. +// +// So the binding carries permission claims on ClusterRoles and +// ClusterRoleBindings, and this operator spends them on exactly one thing: +// writing the impersonation grant into the workspace that just consented. +// It then records an MCPEndpoint there, so the consumer can see that it +// worked and where to point a client. +// +// There is one workspace this operator can never reach: one that has not +// bound the export. A cluster appears on the endpoint slice because it +// bound, and the claims only apply where the binding is — so consent and +// capability are the same fact. +package operator + +import ( + "context" + "fmt" + "time" + + "github.com/go-logr/logr" + ctrl "sigs.k8s.io/controller-runtime" + "sigs.k8s.io/controller-runtime/pkg/client" + "sigs.k8s.io/controller-runtime/pkg/log" + "sigs.k8s.io/controller-runtime/pkg/manager" + metricsserver "sigs.k8s.io/controller-runtime/pkg/metrics/server" + mcbuilder "sigs.k8s.io/multicluster-runtime/pkg/builder" + mcmanager "sigs.k8s.io/multicluster-runtime/pkg/manager" + mcreconcile "sigs.k8s.io/multicluster-runtime/pkg/reconcile" + + rbacv1 "k8s.io/api/rbac/v1" + apierrors "k8s.io/apimachinery/pkg/api/errors" + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + "k8s.io/apimachinery/pkg/runtime" + "k8s.io/apimachinery/pkg/types" + utilruntime "k8s.io/apimachinery/pkg/util/runtime" + "k8s.io/client-go/kubernetes/scheme" + "k8s.io/client-go/rest" + "k8s.io/client-go/util/retry" + + "github.com/kcp-dev/multicluster-provider/apiexport" + apisv1alpha1 "github.com/kcp-dev/sdk/apis/apis/v1alpha1" + apisv1alpha2 "github.com/kcp-dev/sdk/apis/apis/v1alpha2" + corev1alpha1 "github.com/kcp-dev/sdk/apis/core/v1alpha1" + + "github.com/kcp-dev/contrib-virtual-workspaces/mcp/pkg/bootstrap" + mcpv1alpha1 "github.com/kcp-dev/contrib-virtual-workspaces/mcp/sdk/apis/mcp/v1alpha1" +) + +// endpointName is the single MCPEndpoint this operator maintains per +// workspace. One name, because there is one MCP server and one answer to +// "where do I point my client". +const endpointName = "mcp" + +// impersonatorRole is the grant this operator writes, and the only thing +// it ever writes. +const impersonatorRole = "mcp-virtual-workspace-impersonator" + +// Options configures the operator. +type Options struct { + // RestConfig reaches the kcp shard hosting the mcp APIExport. + RestConfig *rest.Config + // Slice is the endpoint slice following the mcp export; the clusters + // on it are the workspaces that enabled MCP. + Slice string + // ServerURL is where an MCP client connects, reported to consumers. + ServerURL string + // ImpersonateUser is the identity the MCP server presents, and so the + // subject the impersonation grant names. + ImpersonateUser string + // Toolsets is reported so a consumer can see what the server exposes. + Toolsets []string +} + +// Run starts the operator and blocks until ctx is cancelled. +func Run(ctx context.Context, opts Options) error { + if opts.RestConfig == nil { + return fmt.Errorf("rest config is required") + } + if opts.ImpersonateUser == "" { + return fmt.Errorf("--impersonate-user is required: it is the subject the grant names") + } + if opts.Slice == "" { + opts.Slice = bootstrap.ExportName + } + + logger := log.FromContext(ctx).WithName("mcp-operator") + sch := buildScheme() + + provider, err := apiexport.New(opts.RestConfig, opts.Slice, apiexport.Options{Scheme: sch, Log: &logger}) + if err != nil { + return fmt.Errorf("construct provider for %q: %w", opts.Slice, err) + } + mgr, err := mcmanager.New(opts.RestConfig, provider, manager.Options{ + Scheme: sch, + Metrics: metricsserver.Options{BindAddress: "0"}, + }) + if err != nil { + return fmt.Errorf("construct manager: %w", err) + } + + r := &reconciler{mgr: mgr, opts: opts, logger: logger} + + // Reconciling the LogicalCluster is how a per-workspace action is + // expressed: every bound workspace has exactly one, so one event per + // workspace is exactly what is wanted. There is no consumer object to + // watch — the binding is the request, and it lives on their side. + if err := mcbuilder.ControllerManagedBy(mgr). + Named("mcp-enablement"). + For(&corev1alpha1.LogicalCluster{}). + Complete(mcreconcile.Func(r.reconcile)); err != nil { + return fmt.Errorf("build enablement controller: %w", err) + } + + logger.Info("mcp operator running", + "slice", opts.Slice, "serverURL", opts.ServerURL, + "impersonateUser", opts.ImpersonateUser, "toolsets", opts.Toolsets) + return mgr.Start(ctx) +} + +func buildScheme() *runtime.Scheme { + sch := runtime.NewScheme() + utilruntime.Must(scheme.AddToScheme(sch)) + utilruntime.Must(corev1alpha1.AddToScheme(sch)) + utilruntime.Must(apisv1alpha1.AddToScheme(sch)) + utilruntime.Must(apisv1alpha2.AddToScheme(sch)) + utilruntime.Must(mcpv1alpha1.AddToScheme(sch)) + return sch +} + +type reconciler struct { + mgr mcmanager.Manager + opts Options + logger logr.Logger +} + +func (r *reconciler) reconcile(ctx context.Context, req mcreconcile.Request) (ctrl.Result, error) { + logger := log.FromContext(ctx).WithValues("cluster", req.ClusterName) + + cl, err := r.mgr.GetCluster(ctx, req.ClusterName) + if err != nil { + return ctrl.Result{}, fmt.Errorf("get cluster %q: %w", req.ClusterName, err) + } + c := cl.GetClient() + + var lc corev1alpha1.LogicalCluster + if err := c.Get(ctx, types.NamespacedName{Name: "cluster"}, &lc); err != nil { + return ctrl.Result{}, client.IgnoreNotFound(err) + } + + status := mcpv1alpha1.MCPEndpointStatus{ + Phase: mcpv1alpha1.PhaseReady, + URL: r.opts.ServerURL, + Toolsets: r.opts.Toolsets, + } + if err := r.ensureImpersonation(ctx, c); err != nil { + // Reported rather than only logged: the consumer enabled this and + // is owed an answer in their own workspace. + status.Phase = mcpv1alpha1.PhaseError + status.Message = "granting impersonation: " + err.Error() + status.URL = "" + if err := r.report(ctx, c, status); err != nil { + return ctrl.Result{}, err + } + return ctrl.Result{RequeueAfter: 30 * time.Second}, nil + } + + if err := r.report(ctx, c, status); err != nil { + return ctrl.Result{}, err + } + + logger.V(2).Info("mcp enabled in workspace", + "path", lc.Annotations["kcp.io/path"], "url", status.URL) + return ctrl.Result{}, nil +} + +// ensureImpersonation writes the grant, and nothing but the grant. +// +// Impersonation is the whole of what the MCP server needs and deliberately +// all it gets: every resource it touches, it touches as the caller, so kcp +// authorizes each request against their rights and the audit log records +// both identities. Giving this identity resource permissions of its own +// would quietly turn that into something else. +func (r *reconciler) ensureImpersonation(ctx context.Context, c client.Client) error { + role := &rbacv1.ClusterRole{ + ObjectMeta: metav1.ObjectMeta{Name: impersonatorRole}, + Rules: []rbacv1.PolicyRule{ + { + APIGroups: []string{""}, + Resources: []string{"users", "groups", "serviceaccounts"}, + Verbs: []string{"impersonate"}, + }, + { + // Extras are authorized as userextras/ and UIDs as + // uids, both in authentication.k8s.io. RBAC has no + // subresource wildcard, so the group is granted whole. + APIGroups: []string{"authentication.k8s.io"}, + Resources: []string{"*"}, + Verbs: []string{"impersonate"}, + }, + { + Verbs: []string{"access"}, + NonResourceURLs: []string{"/"}, + }, + }, + } + binding := &rbacv1.ClusterRoleBinding{ + ObjectMeta: metav1.ObjectMeta{Name: impersonatorRole}, + RoleRef: rbacv1.RoleRef{APIGroup: rbacv1.GroupName, Kind: "ClusterRole", Name: impersonatorRole}, + Subjects: []rbacv1.Subject{{ + APIGroup: rbacv1.GroupName, Kind: rbacv1.UserKind, Name: r.opts.ImpersonateUser, + }}, + } + + if err := upsert(ctx, c, role, func(existing client.Object) { + existing.(*rbacv1.ClusterRole).Rules = role.Rules + }); err != nil { + return err + } + return upsert(ctx, c, binding, func(existing client.Object) { + b := existing.(*rbacv1.ClusterRoleBinding) + b.Subjects, b.RoleRef = binding.Subjects, binding.RoleRef + }) +} + +// report records what a consumer needs to know, in their own workspace. +func (r *reconciler) report(ctx context.Context, c client.Client, status mcpv1alpha1.MCPEndpointStatus) error { + endpoint := &mcpv1alpha1.MCPEndpoint{ObjectMeta: metav1.ObjectMeta{Name: endpointName}} + if err := c.Create(ctx, endpoint); err != nil && !apierrors.IsAlreadyExists(err) { + return fmt.Errorf("create MCPEndpoint: %w", err) + } + return retry.RetryOnConflict(retry.DefaultRetry, func() error { + var existing mcpv1alpha1.MCPEndpoint + if err := c.Get(ctx, types.NamespacedName{Name: endpointName}, &existing); err != nil { + return err + } + if equalStatus(existing.Status, status) { + return nil + } + existing.Status = status + return c.Status().Update(ctx, &existing) + }) +} + +func equalStatus(a, b mcpv1alpha1.MCPEndpointStatus) bool { + if a.Phase != b.Phase || a.Message != b.Message || a.URL != b.URL || len(a.Toolsets) != len(b.Toolsets) { + return false + } + for i := range a.Toolsets { + if a.Toolsets[i] != b.Toolsets[i] { + return false + } + } + return true +} + +// upsert creates an object, or brings an existing one to what was asked +// for, retrying the read-modify-write on a conflicting update. +func upsert(ctx context.Context, c client.Client, desired client.Object, apply func(client.Object)) error { + if err := c.Create(ctx, desired.DeepCopyObject().(client.Object)); err == nil { + return nil + } else if !apierrors.IsAlreadyExists(err) { + return fmt.Errorf("create %T %s: %w", desired, desired.GetName(), err) + } + return retry.RetryOnConflict(retry.DefaultRetry, func() error { + existing := desired.DeepCopyObject().(client.Object) + if err := c.Get(ctx, types.NamespacedName{Name: desired.GetName()}, existing); err != nil { + return err + } + apply(existing) + return c.Update(ctx, existing) + }) +} diff --git a/mcp/sdk/apis/mcp/v1alpha1/doc.go b/mcp/sdk/apis/mcp/v1alpha1/doc.go new file mode 100644 index 0000000..7e98509 --- /dev/null +++ b/mcp/sdk/apis/mcp/v1alpha1/doc.go @@ -0,0 +1,28 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// Package v1alpha1 holds the API type for the mcp component (group +// mcp.platform.kcp.io). +// +// One kind, MCPEndpoint, and it is a report rather than a request: the +// operator writes it into a workspace that has enabled MCP, and whoever +// works there reads it to find out where to point a client and whether +// the enablement finished. Enabling is the APIBinding, not this object — +// which is why there is nothing here to create and no spec to fill in. +// +// +k8s:openapi-gen=true +// +groupName=mcp.platform.kcp.io +package v1alpha1 diff --git a/mcp/sdk/apis/mcp/v1alpha1/register.go b/mcp/sdk/apis/mcp/v1alpha1/register.go new file mode 100644 index 0000000..f1b4cc7 --- /dev/null +++ b/mcp/sdk/apis/mcp/v1alpha1/register.go @@ -0,0 +1,58 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package v1alpha1 + +import ( + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + "k8s.io/apimachinery/pkg/runtime" + "k8s.io/apimachinery/pkg/runtime/schema" +) + +// GroupName is the API group this component serves. +const GroupName = "mcp.platform.kcp.io" + +// Version is the served version. +const Version = "v1alpha1" + +// SchemeGroupVersion is the group/version of this API. +var SchemeGroupVersion = schema.GroupVersion{Group: GroupName, Version: Version} + +var ( + // SchemeBuilder registers this group's types. + SchemeBuilder = runtime.NewSchemeBuilder(addKnownTypes) + // AddToScheme adds this group's types to a scheme. + AddToScheme = SchemeBuilder.AddToScheme +) + +// Resource returns a GroupResource in this group. +func Resource(resource string) schema.GroupResource { + return SchemeGroupVersion.WithResource(resource).GroupResource() +} + +// Kind returns a GroupKind in this group. +func Kind(kind string) schema.GroupKind { + return SchemeGroupVersion.WithKind(kind).GroupKind() +} + +func addKnownTypes(scheme *runtime.Scheme) error { + scheme.AddKnownTypes(SchemeGroupVersion, + &MCPEndpoint{}, + &MCPEndpointList{}, + ) + metav1.AddToGroupVersion(scheme, SchemeGroupVersion) + return nil +} diff --git a/mcp/sdk/apis/mcp/v1alpha1/types.go b/mcp/sdk/apis/mcp/v1alpha1/types.go new file mode 100644 index 0000000..8c81795 --- /dev/null +++ b/mcp/sdk/apis/mcp/v1alpha1/types.go @@ -0,0 +1,87 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package v1alpha1 + +import ( + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" +) + +// Phase describes whether MCP is usable in this workspace. +type Phase string + +const ( + // PhasePending means the binding exists but the grant MCP needs is not + // in place yet. + PhasePending Phase = "Pending" + // PhaseReady means a client can connect and reach this workspace. + PhaseReady Phase = "Ready" + // PhaseError means the last reconciliation failed; Message says why. + PhaseError Phase = "Error" +) + +// MCPEndpoint reports that MCP is enabled in this workspace, and where to +// reach it. +// +// It carries no spec because there is nothing to ask for: enabling MCP is +// the APIBinding, and this object is what the operator writes back once +// that binding has let it grant itself the impersonation it needs. Reading +// it answers the two questions enabling raises — "did it work?" and "where +// do I point my client?" — without leaving the workspace. +// +// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object +// +kubebuilder:object:root=true +// +kubebuilder:resource:scope=Cluster +// +kubebuilder:subresource:status +// +kubebuilder:printcolumn:name="URL",type=string,JSONPath=`.status.url` +// +kubebuilder:printcolumn:name="Phase",type=string,JSONPath=`.status.phase` +// +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp` +// +kubebuilder:printcolumn:name="Message",type=string,JSONPath=`.status.message`,priority=1 +type MCPEndpoint struct { + metav1.TypeMeta `json:",inline"` + // +optional + metav1.ObjectMeta `json:"metadata,omitempty"` + + // +optional + Status MCPEndpointStatus `json:"status,omitempty"` +} + +// MCPEndpointStatus is everything this kind has to say. +type MCPEndpointStatus struct { + // +optional + Phase Phase `json:"phase,omitempty"` + // +optional + Message string `json:"message,omitempty"` + // URL is where an MCP client connects. It is the same address for + // every workspace — which workspaces a session can see comes from the + // caller's own access, not from the URL. + // +optional + URL string `json:"url,omitempty"` + // Toolsets are the tool groups the server exposes. + // +optional + Toolsets []string `json:"toolsets,omitempty"` +} + +// MCPEndpointList is the list form of MCPEndpoint. +// +// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object +// +kubebuilder:object:root=true +type MCPEndpointList struct { + metav1.TypeMeta `json:",inline"` + metav1.ListMeta `json:"metadata,omitempty"` + + Items []MCPEndpoint `json:"items"` +} diff --git a/mcp/sdk/apis/mcp/v1alpha1/zz_generated_deepcopy.go b/mcp/sdk/apis/mcp/v1alpha1/zz_generated_deepcopy.go new file mode 100644 index 0000000..f600c99 --- /dev/null +++ b/mcp/sdk/apis/mcp/v1alpha1/zz_generated_deepcopy.go @@ -0,0 +1,103 @@ +//go:build !ignore_autogenerated + +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// Code generated by deepcopy-gen. DO NOT EDIT. + +package v1alpha1 + +import ( + runtime "k8s.io/apimachinery/pkg/runtime" +) + +// DeepCopyInto is a deepcopy function, copying the receiver, writing into out. in must be non-nil. +func (in *MCPEndpointStatus) DeepCopyInto(out *MCPEndpointStatus) { + *out = *in + if in.Toolsets != nil { + in, out := &in.Toolsets, &out.Toolsets + *out = make([]string, len(*in)) + copy(*out, *in) + } +} + +// DeepCopy is a deepcopy function, copying the receiver, creating a new MCPEndpointStatus. +func (in *MCPEndpointStatus) DeepCopy() *MCPEndpointStatus { + if in == nil { + return nil + } + out := new(MCPEndpointStatus) + in.DeepCopyInto(out) + return out +} + +// DeepCopyInto is a deepcopy function, copying the receiver, writing into out. in must be non-nil. +func (in *MCPEndpoint) DeepCopyInto(out *MCPEndpoint) { + *out = *in + out.TypeMeta = in.TypeMeta + in.ObjectMeta.DeepCopyInto(&out.ObjectMeta) + in.Status.DeepCopyInto(&out.Status) +} + +// DeepCopy is a deepcopy function, copying the receiver, creating a new MCPEndpoint. +func (in *MCPEndpoint) DeepCopy() *MCPEndpoint { + if in == nil { + return nil + } + out := new(MCPEndpoint) + in.DeepCopyInto(out) + return out +} + +// DeepCopyObject is a deepcopy function, copying the receiver, creating a new runtime.Object. +func (in *MCPEndpoint) DeepCopyObject() runtime.Object { + if c := in.DeepCopy(); c != nil { + return c + } + return nil +} + +// DeepCopyInto is a deepcopy function, copying the receiver, writing into out. in must be non-nil. +func (in *MCPEndpointList) DeepCopyInto(out *MCPEndpointList) { + *out = *in + out.TypeMeta = in.TypeMeta + in.ListMeta.DeepCopyInto(&out.ListMeta) + if in.Items != nil { + in, out := &in.Items, &out.Items + *out = make([]MCPEndpoint, len(*in)) + for i := range *in { + (*in)[i].DeepCopyInto(&(*out)[i]) + } + } +} + +// DeepCopy is a deepcopy function, copying the receiver, creating a new MCPEndpointList. +func (in *MCPEndpointList) DeepCopy() *MCPEndpointList { + if in == nil { + return nil + } + out := new(MCPEndpointList) + in.DeepCopyInto(out) + return out +} + +// DeepCopyObject is a deepcopy function, copying the receiver, creating a new runtime.Object. +func (in *MCPEndpointList) DeepCopyObject() runtime.Object { + if c := in.DeepCopy(); c != nil { + return c + } + return nil +} diff --git a/producer-quickstart/.github/workflows/ci.yaml b/producer-quickstart/.github/workflows/ci.yaml new file mode 100644 index 0000000..0eaabf7 --- /dev/null +++ b/producer-quickstart/.github/workflows/ci.yaml @@ -0,0 +1,37 @@ +# What a producer's CI needs: the checks `make verify` runs, and proof the +# image builds. Push the image from a release workflow with the registry +# login this one deliberately leaves out. +name: ci + +on: + push: + branches: + - main + pull_request: + workflow_dispatch: + +permissions: + contents: read + +jobs: + verify: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # tag=v7.0.1 + - uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # tag=v6.5.0 + with: + go-version-file: go.mod + - name: Verify + run: make verify + + image: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # tag=v7.0.1 + - uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # tag=v4.2.0 + - name: Build + uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # tag=v6.18.0 + with: + context: . + push: false + tags: dbaas-producer:ci diff --git a/producer-quickstart/.gitignore b/producer-quickstart/.gitignore new file mode 100644 index 0000000..6cc17f4 --- /dev/null +++ b/producer-quickstart/.gitignore @@ -0,0 +1,3 @@ +/bin/ +*.test +cover.out diff --git a/producer-quickstart/Dockerfile b/producer-quickstart/Dockerfile new file mode 100644 index 0000000..89b61fa --- /dev/null +++ b/producer-quickstart/Dockerfile @@ -0,0 +1,19 @@ +# syntax=docker/dockerfile:1.4 +# Pinned to the build platform so multi-arch builds cross-compile instead of +# running the toolchain under emulation. +FROM --platform=$BUILDPLATFORM golang:1.26 AS builder +ARG TARGETOS +ARG TARGETARCH +WORKDIR /src +COPY go.mod go.sum ./ +RUN --mount=type=cache,target=/go/pkg/mod go mod download +COPY . . +ENV CGO_ENABLED=0 GOOS=${TARGETOS:-linux} GOARCH=${TARGETARCH} +RUN --mount=type=cache,target=/go/pkg/mod \ + --mount=type=cache,target=/root/.cache/go-build \ + go build -o /out/producer ./cmd/producer/ + +FROM gcr.io/distroless/static-debian12:nonroot +COPY --from=builder /out/producer /producer +USER 65532:65532 +ENTRYPOINT ["/producer"] diff --git a/producer-quickstart/Makefile b/producer-quickstart/Makefile new file mode 100644 index 0000000..cf98b98 --- /dev/null +++ b/producer-quickstart/Makefile @@ -0,0 +1,46 @@ +GO ?= go +BIN_DIR ?= bin +IMAGE ?= ghcr.io/example/dbaas-producer +TAG ?= latest + +# Where to publish to and run against. Any kcp admin kubeconfig; the Tilt +# stack in contrib-virtual-workspaces writes .tilt/tilt-contrib.kubeconfig. +KUBECONFIG ?= +WORKSPACE_PATH ?= root:marketplace:producers:dbaas + +.PHONY: help +help: ## Show this help + @grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf " \033[36m%-14s\033[0m %s\n", $$1, $$2}' + +.PHONY: build +build: ## Build the controller into bin/producer + $(GO) build -o $(BIN_DIR)/producer ./cmd/producer + +.PHONY: test +test: ## Unit tests (no cluster needed) + $(GO) test ./... + +.PHONY: generate +generate: ## Regenerate deepcopy and the APIResourceSchema from apis/ + ./hack/update-codegen.sh + +.PHONY: verify +verify: ## What CI runs: formatting, vet, build, tests, and that generate is committed + @out=$$(gofmt -l -s $$(find . -name '*.go' -not -path './$(BIN_DIR)/*')); \ + if [ -n "$$out" ]; then echo "not gofmt'd:"; echo "$$out"; exit 1; fi + $(GO) vet ./... + $(GO) mod tidy -diff + $(MAKE) build test generate + git diff --exit-code -- apis config + +.PHONY: image +image: ## Build the container image + docker build -t $(IMAGE):$(TAG) . + +.PHONY: publish +publish: ## Register the producer and publish the export (KUBECONFIG=) + KUBECONFIG=$(KUBECONFIG) ./hack/publish.sh + +.PHONY: run +run: build ## Run the controller locally against the producer workspace + $(BIN_DIR)/producer --kubeconfig $(KUBECONFIG) --workspace-path $(WORKSPACE_PATH) diff --git a/producer-quickstart/README.md b/producer-quickstart/README.md new file mode 100644 index 0000000..c1f01bc --- /dev/null +++ b/producer-quickstart/README.md @@ -0,0 +1,140 @@ +# producer-quickstart + +A producer, ready to copy. Take this directory, rename three things, and you +have an API on the marketplace: a Go type, the schema kcp serves for 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. Replace the fake provisioning in the reconciler with real work +and you are done. + +It is a template, not a library: nothing in it imports this repository. It +is its own Go module (`example.com/dbaas-producer`) so that the copy builds +on its own, and `make verify` at the root of this repository builds and +tests it so it cannot rot. + +The example it ships is a database-as-a-service: a `Database` kind in the +group `dbaas.example.com`, with `engine` and `size` in the spec and a +`phase`, `endpoint` and conditions in the status. + +## Quick start + +Against the Tilt stack of this repository (`make tilt-up` at the root): + +```sh +cp -r producer-quickstart ~/src/my-producer && cd ~/src/my-producer +make generate # deepcopy + APIResourceSchema from apis/ +make publish KUBECONFIG=$REPO/.tilt/tilt-contrib.kubeconfig # register, provision, publish +make run KUBECONFIG=$REPO/.tilt/tilt-contrib.kubeconfig # the controller, locally +``` + +Then enable **Databases** in a project from the console (Producers → Enable) +or `contribctl enable dbaas.dbaas.example.com`, open it in the sidebar, and +create one. It goes `Pending` → `Ready` with an endpoint in a couple of +seconds, in the console's table and in `kubectl get databases` alike. + +## Make it yours + +Three renames, in this order, then `make generate`: + +| What | Where | Example | +|------|-------|---------| +| Module path | `go.mod`, and the `example.com/dbaas-producer/...` imports | `github.com/acme/widgets-producer` | +| API group and kind | `apis/v1alpha1/` (`groupversion_info.go`, `database_types.go`), `config/apiexport.yaml` (`name`, `resources`), `config/apiexportendpointslice.yaml`, `cmd/producer/main.go` (slice default) | group `widgets.acme.com`, kind `Widget` | +| Producer name | `config/producer.yaml`, `config/deploy/deployment.yaml` (`--workspace-path`), `Makefile` (`WORKSPACE_PATH`, `IMAGE`) | `acme` | + +`make generate` rewrites `schema:` in `config/apiexport.yaml` to the new +schema's name; everything else that names the kind is listed above. +`grep -rn dbaas` finds whatever is left. + +## Layout + +| Path | What | +|------|------| +| `apis/v1alpha1/` | The Go types. Markers on them produce the schema, the validation, the defaults, and the printer columns. `zz_generated.deepcopy.go` is generated. | +| `internal/controller/` | The reconciler. `Reconcile` is a plain function over a `client.Client`, so the test drives it with a fake; the multicluster wrapper around it is ten lines. | +| `cmd/producer/` | The binary: a multicluster manager following the export's endpoint slice. | +| `config/` | What gets applied where: `producer.yaml` to the catalog workspace, the rest to the producer's own. `apiresourceschema-*.yaml` is generated. | +| `config/deploy/` | A Deployment for the controller, with the kubeconfig from a Secret. | +| `hack/update-codegen.sh` | controller-gen (deepcopy, CRDs) then kcp's apigen (CRDs → APIResourceSchema), then repoints the export. | +| `hack/publish.sh` | Registers the producer, waits for its workspace, publishes into it, waits for the `bind` grant. | +| `Dockerfile`, `.github/workflows/ci.yaml` | Multi-arch image; CI running `make verify` and a build of the image. | + +## How it fits together + +1. **Registration.** Whoever runs the platform applies `config/producer.yaml` + to the marketplace's catalog workspace. The marketplace operator + provisions a workspace for the producer (`root:marketplace:producers:dbaas`) + that is already bound to the publish export — registration is being + vouched for, and is the one step a producer cannot do alone. +2. **Publishing.** Into that workspace go the `APIResourceSchema`, the + `APIExport`, the `APIExportEndpointSlice` and the instructions + `ConfigMap` (`hack/publish.sh`). The export's annotations are the + offering — `publish: "true"`, a display name, a description, the + instructions' name — so there is no second object to keep in step. The + operator materializes `bind` on the export for the platform's consumers. +3. **Enabling.** A consumer creates an `APIBinding` in their project, from + the console or `contribctl enable`. kcp serves the API there; the + consumer accepts the export's `permissionClaims` on the binding, which is + how the producer gets reach into anything beyond its own kind. +4. **Reconciling.** The binding puts the project on the endpoint slice. The + controller follows the slice: every workspace on it becomes a cluster to + the multicluster manager, requests carry the cluster name, and the client + it hands back is scoped to that workspace — through the export's virtual + workspace, with the producer's own credential. The producer never lists + workspaces and never holds a credential to anything else. +5. **The console.** Nothing to write. The sidebar lists the producer, its + page shows the instructions (templated with the reader's workspace, + tenant, project and user) and the kinds it serves; each kind's table has + the columns from the `printcolumn` markers, the create form is built + from the schema, and edit is YAML. A kind with a `priority: 1` column + shows it in the detail view, as `kubectl -o wide` does. + +## The reconciler + +[`internal/controller/database_controller.go`](internal/controller/database_controller.go) +fakes provisioning: first pass sets `Pending` and requeues, second pass sets +`Ready` and an endpoint. Replace that with the real thing, keeping: + +- `status.observedGeneration`, so a spec change after `Ready` is noticed and + acted on, and a reader can tell a stale `Ready` from a current one; +- the phases and the `Ready` condition, so every client — the console, + kubectl, an agent over MCP — can tell what is going on without knowing the + producer; +- `RequeueAfter` for waiting, never sleeping in the reconciler; +- a finalizer (`controllerutil.AddFinalizer` on first sight, teardown then + `RemoveFinalizer` on deletion) once something exists outside kcp. + +The controller only touches its own kind, so the export claims nothing. A +producer that needs the consumer's `ConfigMaps`, or wants to write a +`Secret` with credentials next to the `Database`, declares that in +`config/apiexport.yaml` under `permissionClaims` — and the consumer sees +exactly that list on the catalog card before accepting it. + +## Changing the API + +Edit the Go types, `make generate`. The schema's name carries a hash of the +shape, so a changed API is a new schema and the export is repointed to it; +kcp moves existing bindings along. That is fine for additive changes with +defaults; for anything else, add a version rather than mutate `v1alpha1`. + +## Running it for real + +```sh +make image IMAGE=ghcr.io/acme/widgets-producer TAG=v0.1.0 +kubectl create namespace dbaas-producer +kubectl -n dbaas-producer create secret generic kcp-kubeconfig --from-file=kubeconfig=./producer.kubeconfig +kubectl apply -f config/deploy/deployment.yaml +``` + +The kubeconfig's identity needs two things in the producer's workspace: +read the `APIExportEndpointSlice`, and the export's content (the +`apiexports/content` verb) — which the workspace's owner has, and a +dedicated user or ServiceAccount can be granted. The binary takes +`--kubeconfig` (controller-runtime's, so `$KUBECONFIG` and in-cluster +config work too), `--workspace-path` to point it at the producer's +workspace whatever the kubeconfig's current cluster is, and +`--apiexport-endpointslice`. + +`make verify` is what CI runs: gofmt, vet, `go mod tidy -diff`, build, the +unit tests, and `make generate` with a clean `git diff` — so a type change +without its generated files fails in CI rather than at publish time. diff --git a/producer-quickstart/apis/v1alpha1/database_types.go b/producer-quickstart/apis/v1alpha1/database_types.go new file mode 100644 index 0000000..749161e --- /dev/null +++ b/producer-quickstart/apis/v1alpha1/database_types.go @@ -0,0 +1,114 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package v1alpha1 + +import ( + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" +) + +// Phase values a Database moves through. +const ( + PhasePending = "Pending" + PhaseReady = "Ready" + PhaseError = "Error" +) + +// ConditionReady is the one condition this producer reports. Add more as +// the real provisioning grows states worth watching for. +const ConditionReady = "Ready" + +// DatabaseSpec is what a consumer asks for. +type DatabaseSpec struct { + // Engine selects the database engine. + // +kubebuilder:validation:Enum=postgres;mysql + // +kubebuilder:default=postgres + // +optional + Engine string `json:"engine,omitempty"` + + // Size is the instance class. + // +kubebuilder:validation:Enum=small;medium;large + // +kubebuilder:default=small + // +optional + Size string `json:"size,omitempty"` +} + +// DatabaseStatus is what the producer reports back. +type DatabaseStatus struct { + // Phase summarises where provisioning is: Pending, Ready or Error. + // +optional + Phase string `json:"phase,omitempty"` + + // Endpoint is where the database answers once it is Ready. + // +optional + Endpoint string `json:"endpoint,omitempty"` + + // Message says why, in a sentence, when the phase alone is not enough. + // +optional + Message string `json:"message,omitempty"` + + // ObservedGeneration is the spec generation this status describes, so a + // reader can tell a stale Ready from a current one. + // +optional + ObservedGeneration int64 `json:"observedGeneration,omitempty"` + + // Conditions follow the usual Kubernetes shape, for tooling that reads + // them rather than the phase. + // +optional + // +listType=map + // +listMapKey=type + Conditions []metav1.Condition `json:"conditions,omitempty"` +} + +// Database is one database instance a consumer asked for in their +// workspace. +// +// Cluster-scoped: a kcp workspace is already the tenancy boundary, so a +// namespace inside it would be a second one nobody asked for. Namespaced +// kinds work too — drop the scope marker — and the console handles both. +// +// The printcolumn markers are the whole of making this kind presentable: +// kubectl and the console both ask kcp for a Table and show these columns, +// with no code in either that knows what a Database is. Columns with a +// priority are shown with -o wide, and in the console's detail view. +// +// +kubebuilder:object:root=true +// +kubebuilder:subresource:status +// +kubebuilder:resource:scope=Cluster,categories=dbaas +// +kubebuilder:printcolumn:name="Engine",type=string,JSONPath=`.spec.engine` +// +kubebuilder:printcolumn:name="Size",type=string,JSONPath=`.spec.size` +// +kubebuilder:printcolumn:name="Phase",type=string,JSONPath=`.status.phase` +// +kubebuilder:printcolumn:name="Endpoint",type=string,JSONPath=`.status.endpoint` +// +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp` +// +kubebuilder:printcolumn:name="Message",type=string,JSONPath=`.status.message`,priority=1 +type Database struct { + metav1.TypeMeta `json:",inline"` + metav1.ObjectMeta `json:"metadata,omitempty"` + + // +optional + Spec DatabaseSpec `json:"spec,omitempty"` + // +optional + Status DatabaseStatus `json:"status,omitempty"` +} + +// DatabaseList is a list of Databases. +// +// +kubebuilder:object:root=true +type DatabaseList struct { + metav1.TypeMeta `json:",inline"` + metav1.ListMeta `json:"metadata,omitempty"` + Items []Database `json:"items"` +} diff --git a/producer-quickstart/apis/v1alpha1/doc.go b/producer-quickstart/apis/v1alpha1/doc.go new file mode 100644 index 0000000..0c0851c --- /dev/null +++ b/producer-quickstart/apis/v1alpha1/doc.go @@ -0,0 +1,27 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// Package v1alpha1 is the API this producer publishes: one kind, Database, +// in the group dbaas.example.com. +// +// The Go types are the source of truth. `make generate` renders them into +// the APIResourceSchema in config/ (via controller-gen and kcp's apigen), +// so the schema kcp serves, the deepcopy code the controller needs, and +// the printer columns the console shows all come from the markers here. +// +// +kubebuilder:object:generate=true +// +groupName=dbaas.example.com +package v1alpha1 diff --git a/producer-quickstart/apis/v1alpha1/groupversion_info.go b/producer-quickstart/apis/v1alpha1/groupversion_info.go new file mode 100644 index 0000000..fd941d2 --- /dev/null +++ b/producer-quickstart/apis/v1alpha1/groupversion_info.go @@ -0,0 +1,37 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package v1alpha1 + +import ( + "k8s.io/apimachinery/pkg/runtime/schema" + "sigs.k8s.io/controller-runtime/pkg/scheme" +) + +var ( + // GroupVersion is the group and version this package serves. + GroupVersion = schema.GroupVersion{Group: "dbaas.example.com", Version: "v1alpha1"} + + // SchemeBuilder registers the kinds below with a scheme. + SchemeBuilder = &scheme.Builder{GroupVersion: GroupVersion} + + // AddToScheme adds the kinds in this package to a scheme. + AddToScheme = SchemeBuilder.AddToScheme +) + +func init() { + SchemeBuilder.Register(&Database{}, &DatabaseList{}) +} diff --git a/producer-quickstart/apis/v1alpha1/zz_generated.deepcopy.go b/producer-quickstart/apis/v1alpha1/zz_generated.deepcopy.go new file mode 100644 index 0000000..5606b27 --- /dev/null +++ b/producer-quickstart/apis/v1alpha1/zz_generated.deepcopy.go @@ -0,0 +1,106 @@ +//go:build !ignore_autogenerated + +// Code generated by controller-gen. DO NOT EDIT. + +package v1alpha1 + +import ( + "k8s.io/apimachinery/pkg/apis/meta/v1" + runtime "k8s.io/apimachinery/pkg/runtime" +) + +// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. +func (in *Database) DeepCopyInto(out *Database) { + *out = *in + out.TypeMeta = in.TypeMeta + in.ObjectMeta.DeepCopyInto(&out.ObjectMeta) + out.Spec = in.Spec + in.Status.DeepCopyInto(&out.Status) +} + +// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new Database. +func (in *Database) DeepCopy() *Database { + if in == nil { + return nil + } + out := new(Database) + in.DeepCopyInto(out) + return out +} + +// DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object. +func (in *Database) DeepCopyObject() runtime.Object { + if c := in.DeepCopy(); c != nil { + return c + } + return nil +} + +// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. +func (in *DatabaseList) DeepCopyInto(out *DatabaseList) { + *out = *in + out.TypeMeta = in.TypeMeta + in.ListMeta.DeepCopyInto(&out.ListMeta) + if in.Items != nil { + in, out := &in.Items, &out.Items + *out = make([]Database, len(*in)) + for i := range *in { + (*in)[i].DeepCopyInto(&(*out)[i]) + } + } +} + +// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new DatabaseList. +func (in *DatabaseList) DeepCopy() *DatabaseList { + if in == nil { + return nil + } + out := new(DatabaseList) + in.DeepCopyInto(out) + return out +} + +// DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object. +func (in *DatabaseList) DeepCopyObject() runtime.Object { + if c := in.DeepCopy(); c != nil { + return c + } + return nil +} + +// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. +func (in *DatabaseSpec) DeepCopyInto(out *DatabaseSpec) { + *out = *in +} + +// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new DatabaseSpec. +func (in *DatabaseSpec) DeepCopy() *DatabaseSpec { + if in == nil { + return nil + } + out := new(DatabaseSpec) + in.DeepCopyInto(out) + return out +} + +// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. +func (in *DatabaseStatus) DeepCopyInto(out *DatabaseStatus) { + *out = *in + if in.Conditions != nil { + in, out := &in.Conditions, &out.Conditions + *out = make([]v1.Condition, len(*in)) + for i := range *in { + (*in)[i].DeepCopyInto(&(*out)[i]) + } + } +} + +// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new DatabaseStatus. +func (in *DatabaseStatus) DeepCopy() *DatabaseStatus { + if in == nil { + return nil + } + out := new(DatabaseStatus) + in.DeepCopyInto(out) + return out +} diff --git a/producer-quickstart/cmd/producer/main.go b/producer-quickstart/cmd/producer/main.go new file mode 100644 index 0000000..0391141 --- /dev/null +++ b/producer-quickstart/cmd/producer/main.go @@ -0,0 +1,122 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// The producer's controller binary. +// +// It runs against the export's virtual workspace, not against any one +// workspace: the kubeconfig points at the producer's own workspace, where +// the APIExportEndpointSlice lives, and the multicluster provider follows +// that slice to every workspace that enabled the export. Each becomes a +// cluster the manager knows, and the controller reconciles Databases in all +// of them with one credential — the producer's own. +package main + +import ( + "flag" + "fmt" + "os" + "strings" + + "k8s.io/apimachinery/pkg/runtime" + utilruntime "k8s.io/apimachinery/pkg/util/runtime" + clientgoscheme "k8s.io/client-go/kubernetes/scheme" + ctrl "sigs.k8s.io/controller-runtime" + ctrlconfig "sigs.k8s.io/controller-runtime/pkg/client/config" + "sigs.k8s.io/controller-runtime/pkg/log/zap" + "sigs.k8s.io/controller-runtime/pkg/manager" + metricsserver "sigs.k8s.io/controller-runtime/pkg/metrics/server" + mcmanager "sigs.k8s.io/multicluster-runtime/pkg/manager" + + "github.com/kcp-dev/multicluster-provider/apiexport" + apisv1alpha1 "github.com/kcp-dev/sdk/apis/apis/v1alpha1" + + dbaasv1alpha1 "example.com/dbaas-producer/apis/v1alpha1" + "example.com/dbaas-producer/internal/controller" +) + +func main() { + var ( + workspacePath string + slice string + metricsAddr string + ) + // --kubeconfig is controller-runtime's: registered by its config + // package on the default flag set, falling back to $KUBECONFIG and then + // to in-cluster config, so it is not declared here. + flag.StringVar(&workspacePath, "workspace-path", "", + "The producer's workspace, e.g. root:marketplace:producers:dbaas: where the "+ + "export and its endpoint slice are. Empty uses the kubeconfig's cluster URL as is.") + flag.StringVar(&slice, "apiexport-endpointslice", "dbaas", + "APIExportEndpointSlice to follow. The clusters on it are the workspaces that enabled the export.") + flag.StringVar(&metricsAddr, "metrics-bind-address", "0", + "Address for Prometheus metrics; 0 disables them.") + zapOpts := zap.Options{} + zapOpts.BindFlags(flag.CommandLine) + flag.Parse() + + ctrl.SetLogger(zap.New(zap.UseFlagOptions(&zapOpts))) + logger := ctrl.Log.WithName("dbaas-producer") + + if err := run(workspacePath, slice, metricsAddr); err != nil { + logger.Error(err, "exiting") + os.Exit(1) + } +} + +func run(workspacePath, slice, metricsAddr string) error { + cfg, err := ctrlconfig.GetConfig() + if err != nil { + return fmt.Errorf("load kubeconfig: %w", err) + } + if workspacePath != "" { + cfg.Host = retargetHost(cfg.Host, workspacePath) + } + + // The scheme needs the producer's own kinds, the kcp kinds the provider + // watches to discover workspaces (APIBindings), and core. + sch := runtime.NewScheme() + utilruntime.Must(clientgoscheme.AddToScheme(sch)) + utilruntime.Must(apisv1alpha1.AddToScheme(sch)) + utilruntime.Must(dbaasv1alpha1.AddToScheme(sch)) + + providerLog := ctrl.Log.WithName("provider") + provider, err := apiexport.New(cfg, slice, apiexport.Options{Scheme: sch, Log: &providerLog}) + if err != nil { + return fmt.Errorf("construct provider for slice %q: %w", slice, err) + } + mgr, err := mcmanager.New(cfg, provider, manager.Options{ + Scheme: sch, + Metrics: metricsserver.Options{BindAddress: metricsAddr}, + }) + if err != nil { + return fmt.Errorf("construct manager: %w", err) + } + if err := (&controller.Reconciler{}).SetupWithManager(mgr); err != nil { + return fmt.Errorf("set up database controller: %w", err) + } + + ctrl.Log.Info("dbaas producer running", "host", cfg.Host, "slice", slice) + return mgr.Start(ctrl.SetupSignalHandler()) +} + +// retargetHost points a kubeconfig's server URL at a workspace by path, +// whatever cluster it named before. +func retargetHost(host, workspacePath string) string { + if i := strings.Index(host, "/clusters/"); i >= 0 { + host = host[:i] + } + return strings.TrimSuffix(host, "/") + "/clusters/" + workspacePath +} diff --git a/producer-quickstart/config/apiexport.yaml b/producer-quickstart/config/apiexport.yaml new file mode 100644 index 0000000..d704a77 --- /dev/null +++ b/producer-quickstart/config/apiexport.yaml @@ -0,0 +1,33 @@ +# The export, which is also the offering: the annotations publish it to the +# catalog, and spec.permissionClaims are what the consumer accepts when they +# enable it. There is no other object to keep in step. +# +# `schema:` is rewritten by `make generate` to the current schema's name. +apiVersion: apis.kcp.io/v1alpha2 +kind: APIExport +metadata: + name: dbaas.example.com + annotations: + # Only the exact string "true" publishes. + marketplace.kcp.hub/publish: "true" + marketplace.kcp.hub/display-name: Databases + marketplace.kcp.hub/description: Managed databases, one object per instance. + # A ConfigMap in this workspace (config/instructions.yaml): what the + # console shows a consumer after they enable this. + marketplace.kcp.hub/instructions: dbaas-instructions + # marketplace.kcp.hub/docs-url: https://docs.example.com/dbaas +spec: + resources: + - name: databases + group: dbaas.example.com + schema: v261002-64e2900.databases.dbaas.example.com + storage: + crd: {} + # This producer only touches its own kind, so it claims nothing. A + # producer that needs to read, say, the consumer's ConfigMaps or write a + # Secret with credentials lists that here — and the consumer sees exactly + # that list on the catalog card before they accept it. + # permissionClaims: + # - group: "" + # resource: secrets + # verbs: [create, get, update, delete] diff --git a/producer-quickstart/config/apiexportendpointslice.yaml b/producer-quickstart/config/apiexportendpointslice.yaml new file mode 100644 index 0000000..b3ea11b --- /dev/null +++ b/producer-quickstart/config/apiexportendpointslice.yaml @@ -0,0 +1,15 @@ +# The slice the controller follows. A workspace appears on it the moment it +# binds the export, which makes the slice both how the controller discovers +# consumers and the exact list of workspaces it may reach into. +# +# __PRODUCER_WORKSPACE__ is filled in by hack/publish.sh: the slice names +# the export by workspace path, and a provisioned producer's path is only +# known once the operator has created it. +apiVersion: apis.kcp.io/v1alpha1 +kind: APIExportEndpointSlice +metadata: + name: dbaas +spec: + export: + name: dbaas.example.com + path: __PRODUCER_WORKSPACE__ diff --git a/producer-quickstart/config/apiresourceschema-databases.dbaas.example.com.yaml b/producer-quickstart/config/apiresourceschema-databases.dbaas.example.com.yaml new file mode 100644 index 0000000..14bbddd --- /dev/null +++ b/producer-quickstart/config/apiresourceschema-databases.dbaas.example.com.yaml @@ -0,0 +1,174 @@ +apiVersion: apis.kcp.io/v1alpha1 +kind: APIResourceSchema +metadata: + name: v261002-64e2900.databases.dbaas.example.com +spec: + group: dbaas.example.com + names: + categories: + - dbaas + kind: Database + listKind: DatabaseList + plural: databases + singular: database + scope: Cluster + versions: + - additionalPrinterColumns: + - jsonPath: .spec.engine + name: Engine + type: string + - jsonPath: .spec.size + name: Size + type: string + - jsonPath: .status.phase + name: Phase + type: string + - jsonPath: .status.endpoint + name: Endpoint + type: string + - jsonPath: .metadata.creationTimestamp + name: Age + type: date + - jsonPath: .status.message + name: Message + priority: 1 + type: string + name: v1alpha1 + schema: + description: |- + Database is one database instance a consumer asked for in their + workspace. + + Cluster-scoped: a kcp workspace is already the tenancy boundary, so a + namespace inside it would be a second one nobody asked for. Namespaced + kinds work too — drop the scope marker — and the console handles both. + + The printcolumn markers are the whole of making this kind presentable: + kubectl and the console both ask kcp for a Table and show these columns, + with no code in either that knows what a Database is. Columns with a + priority are shown with -o wide, and in the console's detail view. + properties: + apiVersion: + description: |- + APIVersion defines the versioned schema of this representation of an object. + Servers should convert recognized schemas to the latest internal value, and + may reject unrecognized values. + More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + type: string + kind: + description: |- + Kind is a string value representing the REST resource this object represents. + Servers may infer this from the endpoint the client submits requests to. + Cannot be updated. + In CamelCase. + More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + type: string + metadata: + type: object + spec: + description: DatabaseSpec is what a consumer asks for. + properties: + engine: + default: postgres + description: Engine selects the database engine. + enum: + - postgres + - mysql + type: string + size: + default: small + description: Size is the instance class. + enum: + - small + - medium + - large + type: string + type: object + status: + description: DatabaseStatus is what the producer reports back. + properties: + conditions: + description: |- + Conditions follow the usual Kubernetes shape, for tooling that reads + them rather than the phase. + items: + description: Condition contains details for one aspect of the current + state of this API Resource. + properties: + lastTransitionTime: + description: |- + lastTransitionTime is the last time the condition transitioned from one status to another. + This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. + format: date-time + type: string + message: + description: |- + message is a human readable message indicating details about the transition. + This may be an empty string. + maxLength: 32768 + type: string + observedGeneration: + description: |- + observedGeneration represents the .metadata.generation that the condition was set based upon. + For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date + with respect to the current state of the instance. + format: int64 + minimum: 0 + type: integer + reason: + description: |- + reason contains a programmatic identifier indicating the reason for the condition's last transition. + Producers of specific condition types may define expected values and meanings for this field, + and whether the values are considered a guaranteed API. + The value should be a CamelCase string. + This field may not be empty. + maxLength: 1024 + minLength: 1 + pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ + type: string + status: + description: status of the condition, one of True, False, Unknown. + enum: + - "True" + - "False" + - Unknown + type: string + type: + description: type of condition in CamelCase or in foo.example.com/CamelCase. + maxLength: 316 + pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ + type: string + required: + - lastTransitionTime + - message + - reason + - status + - type + type: object + type: array + x-kubernetes-list-map-keys: + - type + x-kubernetes-list-type: map + endpoint: + description: Endpoint is where the database answers once it is Ready. + type: string + message: + description: Message says why, in a sentence, when the phase alone is + not enough. + type: string + observedGeneration: + description: |- + ObservedGeneration is the spec generation this status describes, so a + reader can tell a stale Ready from a current one. + format: int64 + type: integer + phase: + description: 'Phase summarises where provisioning is: Pending, Ready + or Error.' + type: string + type: object + type: object + served: true + storage: true + subresources: + status: {} diff --git a/producer-quickstart/config/deploy/deployment.yaml b/producer-quickstart/config/deploy/deployment.yaml new file mode 100644 index 0000000..ef4f237 --- /dev/null +++ b/producer-quickstart/config/deploy/deployment.yaml @@ -0,0 +1,51 @@ +# Runs the controller in a Kubernetes cluster, with a kubeconfig for the +# producer's workspace mounted from a Secret: +# +# kubectl create namespace dbaas-producer +# kubectl -n dbaas-producer create secret generic kcp-kubeconfig \ +# --from-file=kubeconfig= +# kubectl apply -f config/deploy/deployment.yaml +# +# The kubeconfig's identity needs, in the producer's workspace, to read the +# APIExportEndpointSlice and the export's content — which the workspace's +# owner has, and a dedicated ServiceAccount or user can be granted. +apiVersion: apps/v1 +kind: Deployment +metadata: + name: dbaas-producer + namespace: dbaas-producer + labels: + app.kubernetes.io/name: dbaas-producer +spec: + replicas: 1 + selector: + matchLabels: + app.kubernetes.io/name: dbaas-producer + template: + metadata: + labels: + app.kubernetes.io/name: dbaas-producer + spec: + containers: + - name: producer + image: ghcr.io/example/dbaas-producer:latest + args: + - --kubeconfig=/etc/kcp/kubeconfig + - --workspace-path=root:marketplace:producers:dbaas + - --apiexport-endpointslice=dbaas + volumeMounts: + - name: kubeconfig + mountPath: /etc/kcp + readOnly: true + resources: + requests: + cpu: 50m + memory: 64Mi + securityContext: + runAsNonRoot: true + allowPrivilegeEscalation: false + readOnlyRootFilesystem: true + volumes: + - name: kubeconfig + secret: + secretName: kcp-kubeconfig diff --git a/producer-quickstart/config/instructions.yaml b/producer-quickstart/config/instructions.yaml new file mode 100644 index 0000000..3def7fb --- /dev/null +++ b/producer-quickstart/config/instructions.yaml @@ -0,0 +1,56 @@ +# What a consumer sees in the console after enabling this, as tabs: each +# key is a section, the NN- prefix orders them and is dropped from the +# label. A markdown subset — headings, paragraphs, lists, fenced code, +# `inline code`, links — rendered as elements, never as HTML. {{variables}} +# are filled in for the reader: {{server}}, {{workspace}}, {{cluster}}, +# {{tenant}}, {{project}}, {{user}}, {{export}}, {{binding}}, and more; see +# the marketplace README for the list. +# +# A provisioned producer workspace starts with no namespace, hence the +# Namespace here; the marketplace finds the ConfigMap by name whatever +# namespace it is in. +apiVersion: v1 +kind: Namespace +metadata: + name: default +--- +apiVersion: v1 +kind: ConfigMap +metadata: + name: dbaas-instructions + namespace: default +data: + 00-overview.md: | + # Databases + + Enabling bound `dbaas.example.com` into `{{tenant}}/{{project}}`. A + `Database` object is one instance: say which engine and size, and the + producer reports where it answers in `status.endpoint` once it is + `Ready`. + + 10-kubectl.md: | + # kubectl + + Point a kubeconfig at the project and ask for one: + + ```sh + kubectl --server {{workspace}} apply -f - < registering producer $producer in $CATALOG" +kube "$SERVER/clusters/$CATALOG" apply -f "$HERE/config/producer.yaml" + +echo "==> waiting for the operator to provision its workspace" +deadline=$((SECONDS + TIMEOUT)) +while :; do + path="$(kube "$SERVER/clusters/$CATALOG" get producer "$producer" -o jsonpath='{.status.workspacePath}' 2>/dev/null || true)" + [ -n "$path" ] && break + if [ "$SECONDS" -ge "$deadline" ]; then + echo "producer $producer has no workspace after ${TIMEOUT}s. Is marketplace-operator running?" >&2 + exit 1 + fi + sleep 2 +done +echo " $path" +WS="$SERVER/clusters/$path" + +echo "==> publishing into $path" +kube "$WS" apply -f "$HERE"/config/apiresourceschema-*.yaml +kube "$WS" apply -f "$HERE/config/apiexport.yaml" +kube "$WS" apply -f "$HERE/config/instructions.yaml" +# The slice names the export by workspace path, known only now. +sed "s#__PRODUCER_WORKSPACE__#$path#" "$HERE/config/apiexportendpointslice.yaml" | kube "$WS" apply -f - + +echo "==> waiting for the bind grant" +deadline=$((SECONDS + TIMEOUT)) +while ! kube "$WS" get clusterrole "marketplace:bind:$export_name" >/dev/null 2>&1; do + if [ "$SECONDS" -ge "$deadline" ]; then + echo "no bind grant for $export_name after ${TIMEOUT}s; is the export annotated with publish: \"true\"?" >&2 + exit 1 + fi + sleep 2 +done + +cat <-..), +# so a changed API is a new schema and the export's reference has to follow; +# that is how kcp knows an existing binding is on an older revision. +set -euo pipefail + +HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +cd "${HERE}" + +CONTROLLER_GEN_VERSION="${CONTROLLER_GEN_VERSION:-v0.19.0}" +stage="$(mktemp -d)" +trap 'rm -rf "${stage}"' EXIT +mkdir -p "${stage}/crds" "${stage}/out" + +echo "==> deepcopy" +go run "sigs.k8s.io/controller-tools/cmd/controller-gen@${CONTROLLER_GEN_VERSION}" \ + object paths=./apis/... + +echo "==> CRDs (intermediate; kcp serves APIResourceSchemas, not CRDs)" +go run "sigs.k8s.io/controller-tools/cmd/controller-gen@${CONTROLLER_GEN_VERSION}" \ + crd paths=./apis/... output:crd:dir="${stage}/crds" + +# Seed with the committed schema so apigen keeps its name when nothing +# changed — a stable name means existing bindings stay current. +cp config/apiresourceschema-*.yaml "${stage}/out/" 2>/dev/null || true + +echo "==> APIResourceSchemas" +go run github.com/kcp-dev/sdk/cmd/apigen --input-dir "${stage}/crds" --output-dir "${stage}/out" + +python3 - "${stage}/out" config <<'PY' +import glob, os, re, sys +out, cfg = sys.argv[1], sys.argv[2] +for old in glob.glob(os.path.join(cfg, "apiresourceschema-*.yaml")): + os.remove(old) +export = open(os.path.join(cfg, "apiexport.yaml")).read() +for path in sorted(glob.glob(os.path.join(out, "apiresourceschema-*.yaml"))): + text = open(path).read() + name = re.search(r"^ name: (\S+)$", text, re.M).group(1) + _, plural_group = name.split(".", 1) + open(os.path.join(cfg, os.path.basename(path)), "w").write(text) + # schema: .. -> the new name + export, n = re.subn(r"schema: \S+\." + re.escape(plural_group) + r"$", "schema: " + name, export, flags=re.M) + print(" %s%s" % (name, "" if n else " (no export entry references it)")) +open(os.path.join(cfg, "apiexport.yaml"), "w").write(export) +PY +echo "==> done" diff --git a/producer-quickstart/internal/controller/database_controller.go b/producer-quickstart/internal/controller/database_controller.go new file mode 100644 index 0000000..b0da58a --- /dev/null +++ b/producer-quickstart/internal/controller/database_controller.go @@ -0,0 +1,170 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// Package controller reconciles Databases in every workspace that enabled +// the export. +// +// The controller does not know those workspaces; the multicluster manager +// does. It follows the export's APIExportEndpointSlice, and every workspace +// that binds the export shows up as a "cluster" — one request names both the +// cluster and the object, and the client it hands back is scoped to that +// workspace. A producer never lists workspaces, and never holds a credential +// to anything but its own export. +package controller + +import ( + "context" + "fmt" + "time" + + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + "k8s.io/apimachinery/pkg/types" + ctrl "sigs.k8s.io/controller-runtime" + "sigs.k8s.io/controller-runtime/pkg/client" + "sigs.k8s.io/controller-runtime/pkg/log" + "sigs.k8s.io/controller-runtime/pkg/predicate" + mcbuilder "sigs.k8s.io/multicluster-runtime/pkg/builder" + mcmanager "sigs.k8s.io/multicluster-runtime/pkg/manager" + mcreconcile "sigs.k8s.io/multicluster-runtime/pkg/reconcile" + + dbaasv1alpha1 "example.com/dbaas-producer/apis/v1alpha1" +) + +// provisioningDelay stands in for the time real provisioning takes. The +// point of keeping a Pending pass at all is that the consumer sees progress +// — a Database that goes straight to Ready teaches nothing about how the +// console and kubectl show status, which is half of what this template is +// for. +const provisioningDelay = 2 * time.Second + +// Reconciler is the multicluster side: it resolves the request's cluster to +// a client and hands the rest to Reconcile. +type Reconciler struct { + manager mcmanager.Manager +} + +// SetupWithManager registers the controller. One controller, watching one +// kind, across every workspace the provider discovers. +func (r *Reconciler) SetupWithManager(mgr mcmanager.Manager) error { + r.manager = mgr + // GenerationChangedPredicate: a status write bumps resourceVersion but + // not generation, so without it every status update the controller + // makes comes straight back as an event — and the Pending pass below + // would be followed by the Ready pass immediately, never waiting. + return mcbuilder.ControllerManagedBy(mgr). + Named("database"). + For(&dbaasv1alpha1.Database{}, mcbuilder.WithPredicates(predicate.GenerationChangedPredicate{})). + Complete(r) +} + +// Reconcile implements mcreconcile.Reconciler. +func (r *Reconciler) Reconcile(ctx context.Context, req mcreconcile.Request) (ctrl.Result, error) { + cl, err := r.manager.GetCluster(ctx, req.ClusterName) + if err != nil { + return ctrl.Result{}, fmt.Errorf("get cluster %q: %w", req.ClusterName, err) + } + ctx = log.IntoContext(ctx, log.FromContext(ctx).WithValues("cluster", req.ClusterName)) + return Reconcile(ctx, cl.GetClient(), req.NamespacedName) +} + +// Reconcile is the single-workspace logic: given a client for one workspace +// and the name of a Database in it, bring the status up to date with the +// spec. It is a plain function over client.Client so a test can drive it +// with a fake, with no kcp and no multicluster machinery. +// +// Replace the body with real provisioning. What should survive the +// replacement: observedGeneration (so a spec change is noticed), the +// Pending/Ready phases with a condition (so every client can tell what is +// going on), and returning RequeueAfter rather than sleeping. +func Reconcile(ctx context.Context, c client.Client, key types.NamespacedName) (ctrl.Result, error) { + logger := log.FromContext(ctx).WithValues("database", key.Name) + + var db dbaasv1alpha1.Database + if err := c.Get(ctx, key, &db); err != nil { + // Gone is fine: nothing to do for an object that no longer exists. + return ctrl.Result{}, client.IgnoreNotFound(err) + } + + // Deletion. Nothing external exists for this template, so there is no + // finalizer; a real producer that provisions something adds one on + // first sight (controllerutil.AddFinalizer) and tears down here before + // removing it. + if !db.DeletionTimestamp.IsZero() { + return ctrl.Result{}, nil + } + + // Already current: the status describes this generation and is final. + if db.Status.ObservedGeneration == db.Generation && db.Status.Phase == dbaasv1alpha1.PhaseReady { + return ctrl.Result{}, nil + } + + // First pass for this generation: acknowledge, then come back. + if db.Status.ObservedGeneration != db.Generation || db.Status.Phase != dbaasv1alpha1.PhasePending { + db.Status.ObservedGeneration = db.Generation + db.Status.Phase = dbaasv1alpha1.PhasePending + db.Status.Endpoint = "" + db.Status.Message = fmt.Sprintf("provisioning a %s %s instance", db.Spec.Size, db.Spec.Engine) + setReady(&db, metav1.ConditionFalse, "Provisioning", db.Status.Message) + if err := c.Status().Update(ctx, &db); err != nil { + return ctrl.Result{}, fmt.Errorf("update status: %w", err) + } + logger.Info("provisioning", "engine", db.Spec.Engine, "size", db.Spec.Size) + return ctrl.Result{RequeueAfter: provisioningDelay}, nil + } + + // Second pass: it is "up". The endpoint is where the real one would be + // reported — a connection string, a Secret name, whatever the engine + // hands back. + db.Status.Phase = dbaasv1alpha1.PhaseReady + db.Status.Endpoint = endpointFor(&db) + db.Status.Message = "" + setReady(&db, metav1.ConditionTrue, "Provisioned", "the database is ready") + if err := c.Status().Update(ctx, &db); err != nil { + return ctrl.Result{}, fmt.Errorf("update status: %w", err) + } + logger.Info("ready", "endpoint", db.Status.Endpoint) + return ctrl.Result{}, nil +} + +func endpointFor(db *dbaasv1alpha1.Database) string { + port := 5432 + if db.Spec.Engine == "mysql" { + port = 3306 + } + return fmt.Sprintf("%s://%s.dbaas.example.com:%d", db.Spec.Engine, db.Name, port) +} + +func setReady(db *dbaasv1alpha1.Database, status metav1.ConditionStatus, reason, message string) { + cond := metav1.Condition{ + Type: dbaasv1alpha1.ConditionReady, + Status: status, + Reason: reason, + Message: message, + ObservedGeneration: db.Generation, + LastTransitionTime: metav1.Now(), + } + for i := range db.Status.Conditions { + if db.Status.Conditions[i].Type != cond.Type { + continue + } + if db.Status.Conditions[i].Status == cond.Status { + cond.LastTransitionTime = db.Status.Conditions[i].LastTransitionTime + } + db.Status.Conditions[i] = cond + return + } + db.Status.Conditions = append(db.Status.Conditions, cond) +} diff --git a/producer-quickstart/internal/controller/database_controller_test.go b/producer-quickstart/internal/controller/database_controller_test.go new file mode 100644 index 0000000..717ebf6 --- /dev/null +++ b/producer-quickstart/internal/controller/database_controller_test.go @@ -0,0 +1,97 @@ +/* +Copyright 2026 The kcp Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package controller + +import ( + "context" + "testing" + + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + "k8s.io/apimachinery/pkg/runtime" + "k8s.io/apimachinery/pkg/types" + "sigs.k8s.io/controller-runtime/pkg/client/fake" + + dbaasv1alpha1 "example.com/dbaas-producer/apis/v1alpha1" +) + +// The reconcile logic is a function over a client, so this is the whole +// harness: a fake client with the status subresource, and two passes. +func TestReconcileProvisionsThenReady(t *testing.T) { + sch := runtime.NewScheme() + if err := dbaasv1alpha1.AddToScheme(sch); err != nil { + t.Fatal(err) + } + db := &dbaasv1alpha1.Database{ + ObjectMeta: metav1.ObjectMeta{Name: "orders", Generation: 1}, + Spec: dbaasv1alpha1.DatabaseSpec{Engine: "mysql", Size: "small"}, + } + c := fake.NewClientBuilder(). + WithScheme(sch). + WithStatusSubresource(&dbaasv1alpha1.Database{}). + WithObjects(db). + Build() + key := types.NamespacedName{Name: "orders"} + ctx := context.Background() + + res, err := Reconcile(ctx, c, key) + if err != nil { + t.Fatalf("first pass: %v", err) + } + if res.RequeueAfter == 0 { + t.Fatalf("first pass should requeue to finish provisioning, got %+v", res) + } + var got dbaasv1alpha1.Database + if err := c.Get(ctx, key, &got); err != nil { + t.Fatal(err) + } + if got.Status.Phase != dbaasv1alpha1.PhasePending || got.Status.ObservedGeneration != 1 { + t.Fatalf("after first pass: phase=%q observedGeneration=%d", got.Status.Phase, got.Status.ObservedGeneration) + } + + if _, err := Reconcile(ctx, c, key); err != nil { + t.Fatalf("second pass: %v", err) + } + if err := c.Get(ctx, key, &got); err != nil { + t.Fatal(err) + } + if got.Status.Phase != dbaasv1alpha1.PhaseReady { + t.Fatalf("after second pass: phase=%q message=%q", got.Status.Phase, got.Status.Message) + } + if want := "mysql://orders.dbaas.example.com:3306"; got.Status.Endpoint != want { + t.Fatalf("endpoint = %q, want %q", got.Status.Endpoint, want) + } + if len(got.Status.Conditions) != 1 || got.Status.Conditions[0].Status != metav1.ConditionTrue { + t.Fatalf("conditions = %+v", got.Status.Conditions) + } + + // A third pass is a no-op: current generation, final phase. + res, err = Reconcile(ctx, c, key) + if err != nil || res.RequeueAfter != 0 { + t.Fatalf("settled object should not requeue: res=%+v err=%v", res, err) + } +} + +func TestReconcileIgnoresMissing(t *testing.T) { + sch := runtime.NewScheme() + if err := dbaasv1alpha1.AddToScheme(sch); err != nil { + t.Fatal(err) + } + c := fake.NewClientBuilder().WithScheme(sch).Build() + if _, err := Reconcile(context.Background(), c, types.NamespacedName{Name: "nope"}); err != nil { + t.Fatalf("a missing object is not an error: %v", err) + } +}