marketplace

command
v0.1.2 Latest Latest
Warning

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

Go to latest
Published: Nov 11, 2026 License: Apache-2.0 Imports: 2 Imported by: 0

README

Marketplace

A producer/offering marketplace for 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/, the publish flow in pkg/operator/publish.go, and what an annotated export means in 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 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 is the executable version of this section, and it leaves a working .e2e/ behind to poke at.

1. Build
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.

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):

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:

export KUBECONFIG=$PWD/.kcp/admin.kubeconfig
4. Install the exports
bin/marketplace-vw init --kubeconfig "$KUBECONFIG"

This creates the three workspaces from 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
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
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/, 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.

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:

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:

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.

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:

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:

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:

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:

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:

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 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:

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.

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/ writes one), or forwarded request-header identity behind the front-proxy.

Probing by hand:

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<date>-<git sha>.<plural>.<group>) 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 to the new file name.

Testing

From the repository root:

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) 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/) 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.

Documentation

Overview

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.

Directories

Path Synopsis
Package cmd holds the marketplace binary's subcommands.
Package cmd holds the marketplace binary's subcommands.
config
apiexport
Package apiexport holds the kcp-side assets the marketplace component needs.
Package apiexport holds the kcp-side assets the marketplace component needs.
pkg
bootstrap
Package bootstrap installs the kcp-side objects the marketplace needs: the three APIExports and their endpoint slices, the producer WorkspaceType, and the two hand-bound tiers (catalog and producers parent).
Package bootstrap installs the kcp-side objects the marketplace needs: the three APIExports and their endpoint slices, the producer WorkspaceType, and the two hand-bound tiers (catalog and producers parent).
cli
Package cli holds the marketplace's user-facing commands: browsing the catalog, and enabling an offering in a workspace.
Package cli holds the marketplace's user-facing commands: browsing the catalog, and enabling an offering in a workspace.
directory
Package directory is the in-memory index the marketplace virtual workspace answers from: Providers mirrored from the catalog tier, published APIExports mirrored from every producer workspace.
Package directory is the in-memory index the marketplace virtual workspace answers from: Providers mirrored from the catalog tier, published APIExports mirrored from every producer workspace.
offering
Package offering reads an APIExport as a catalog card.
Package offering reads an APIExport as a catalog card.
operator
Package operator reconciles the marketplace API into producer workspaces and bind grants.
Package operator reconciles the marketplace API into producer workspaces and bind grants.
provider
Package provider populates the marketplace directory: Providers from the catalog tier's export, offerings from the APIExports published in each producer workspace — the same multicluster discovery the operator runs, but read-only into the in-memory directory the virtual workspace answers from.
Package provider populates the marketplace directory: Providers from the catalog tier's export, offerings from the APIExports published in each producer workspace — the same multicluster discovery the operator runs, but read-only into the in-memory directory the virtual workspace answers from.
server
Package server wires the marketplace virtual workspace binary together: the directory, the producer that fills it, and a virtual-workspace root apiserver serving the catalog read-only at /services/marketplace behind kcp's front-proxy.
Package server wires the marketplace virtual workspace binary together: the directory, the producer that fills it, and a virtual-workspace root apiserver serving the catalog read-only at /services/marketplace behind kcp's front-proxy.
virtual/catalog
Package catalog implements the marketplace virtual workspace: the read-only catalog at /services/marketplace.
Package catalog implements the marketplace virtual workspace: the read-only catalog at /services/marketplace.
sdk
apis/marketplace/v1alpha1
Package v1alpha1 holds the API types for the marketplace component (group marketplace.platform.kcp.io).
Package v1alpha1 holds the API types for the marketplace component (group marketplace.platform.kcp.io).

Jump to

Keyboard shortcuts

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