Tutorial 08 — List and Deploy via Google Cloud Marketplace
> Status note.* The Helm chart at deploy/helm/buttrbase-backend-rust/ is real and committed — you can run it against a GKE cluster right now using tutorial 07. The Google Cloud Marketplace *listing* (the Producer Portal product, the deployer image, the Marketplace entitlement wiring) is forward-looking: this tutorial is a packaging guide for when you take that chart to market, not a guide to a listing that exists today. Steps that require a Google Producer Portal account are marked *[Marketplace listing — forward-looking] so the distinction is never ambiguous.
This tutorial is one layer thin: it explains what GCP Marketplace adds on top of the chart, how to push the image to Artifact Registry so GCP can reference it, how the deployer package wraps the chart, and what a customer sees when they install from the Marketplace. For everything about how Helm install actually works — topology values, secrets, the /health probe — see 07-deploy-with-helm.md. That document is the substrate; this one references it, it does not repeat it.
1. Why GCP Marketplace
Google Cloud Marketplace lets a GKE customer deploy ButtrBase directly into their own GCP project* — they find the listing, click *Configure & Deploy, pick a cluster, and the Marketplace UI drives the same Helm values the operator would set by hand. The purchase is settled through their existing GCP billing account; ButtrBase never touches their payment method.
This maps exactly to the single-tenant-byoc topology: the customer owns the GKE cluster, the Postgres instance (typically Cloud SQL), and the Cloud Storage bucket. ButtrBase's Mothership provisions the tenant record and issues the encryption keys; the customer's infrastructure runs the workload. See the deployment matrix in docs/specs/federation-and-deployment-architecture.md for where single-tenant-byoc sits relative to the other topologies and why the marketplace path lands there.
| What GCP Marketplace provides | What you still own |
|-------------------------------|-------------------|
| One-click install UI into customer's GKE | The Helm chart logic and values files |
| GCP billing integration (consumption charges) | Mothership provisioning and entitlement sync |
| Artifact Registry hosting for the deployer image | The container image (ghcr.io/buttrbase/buttrbase-backend-rust) |
| Marketplace listing search and discoverability | The support, SLA, and upgrade path |
2. Prerequisites
- A GCP project with billing enabled and the following APIs active: Artifact Registry*, **Google Kubernetes Engine**, *Cloud SQL Admin (if using Cloud SQL for Postgres).
gcloudCLI authenticated:gcloud auth login && gcloud auth configure-docker REGION-docker.pkg.dev.- A GKE cluster (1.25+) and
kubectlconfigured against it. - Helm 3.12+.
- Marketplace listing — forward-looking] A Google Cloud Partner account enrolled in the Producer Portal. Partner onboarding is the gating step — Google reviews the application before you can submit a listing. See [Google's partner onboarding documentation for the current process.
3. Create an Artifact Registry repository
The Marketplace deployer image and the application image must live in Artifact Registry (not GHCR) so GCP's validation pipeline can reach them.
gcloud artifacts repositories create buttrbase \
--repository-format=docker \
--location=us \
--description="ButtrBase Marketplace images"
Confirm it exists:
gcloud artifacts repositories describe buttrbase --location=us
4. Push the application image to Artifact Registry
The chart's default image is ghcr.io/buttrbase/buttrbase-backend-rust. The Marketplace deployer must reference an Artifact Registry URI. Tag and push a pinned release:
Pull the image you want to list (pin a real tag — never list 'latest' on Marketplace)
docker pull ghcr.io/buttrbase/buttrbase-backend-rust:0.1.0Tag for Artifact Registry
docker tag \
ghcr.io/buttrbase/buttrbase-backend-rust:0.1.0 \
us-docker.pkg.dev/YOUR_GCP_PROJECT/buttrbase/buttrbase-backend-rust:0.1.0Push
docker push us-docker.pkg.dev/YOUR_GCP_PROJECT/buttrbase/buttrbase-backend-rust:0.1.0
Replace YOUR_GCP_PROJECT with your GCP project ID and us with your chosen Artifact Registry region throughout. After this step the image is accessible to GCP's scanning and deployment pipelines.
5. Package the chart as a Marketplace Kubernetes app
[Marketplace listing — forward-looking]
GCP Marketplace Kubernetes apps require three artifacts on top of the raw Helm chart:
| Artifact | Purpose |
|----------|---------|
| schema.yaml | Declares the user-facing configuration fields that the Marketplace UI renders as a form (cluster selector, Postgres URL, region, etc.). Maps the form fields to Helm values. |
| Deployer image | A container that GCP's deployment runner executes. It runs helm upgrade --install with the values the customer supplied via schema.yaml. Built from the marketplace-tools base image. |
| Application CRD instance | A kind: Application object (from the Kubernetes Application spec) that the Marketplace controller uses to track the install and report status back to the listing. |
The canonical reference for building these is Google's marketplace-tools repository. That repo provides the base deployer image, schema.yaml authoring guides, and validation tooling — reproduce from there rather than from this tutorial.
The chart at deploy/helm/buttrbase-backend-rust/ slots in as-is. The deployer will invoke it with a values overlay shaped like values-single-tenant-byoc.yaml, with the customer's inputs (tenant slug, region, Postgres URL, storage bucket) injected from the schema.yaml form fields at install time.
6. Submit the listing
[Marketplace listing — forward-looking]
Submission happens entirely in the Producer Portal web UI. The steps are:
1. Create a new Kubernetes app product in the Producer Portal.
2. Upload the deployer image URI (the Artifact Registry path from step 4).
3. Fill in product metadata: name, description, category, support contacts, pricing model.
4. Attach the schema.yaml so the Marketplace UI can render the configuration form for customers.
5. Run the Marketplace's automated validation scan against your deployer image. The scan checks the image is pullable, the deployer runs without errors against a test cluster, and the Application CRD reports healthy.
6. Submit for Google's review. Review timelines vary; expect several business days for a first submission.
Do not attempt to drive these steps from the gcloud CLI — the Marketplace producer workflow is portal-native and does not have a stable gcloud marketplace ... subcommand surface at this time.
7. Customer install experience
Once the listing is live, a customer's path is:
1. Find ButtrBase* in the GCP Marketplace and click *Get Started.
2. Select the GKE cluster and namespace to deploy into (their own project).
3. Fill in the configuration form generated from schema.yaml: Postgres connection string (typically a Cloud SQL private IP), GCS bucket name, tenant slug, region.
4. Click Deploy. GCP's deployment runner pulls the deployer image, runs helm upgrade --install with the customer-supplied values, and monitors the Application CRD for readiness.
5. The Marketplace UI shows the install as Active once the deployer reports success.
The customer never sees a Helm command. Underneath, the deployer is running the same chart as 07, with topology values matching values-single-tenant-byoc.yaml. The secrets (database URL, secret key, encryption key) are supplied through the schema.yaml form as secure fields and materialized as a Kubernetes Secret in the customer's cluster — same three keys the chart reads: database-url, secret-key, encryption-key.
8. Verify the install
Verification is identical to tutorial 07 — the chart is the same chart. Once the customer's deployment is running, check readiness and probe the health endpoint:
kubectl -n buttrbase rollout status deploy/buttrbase --timeout=120s
kubectl -n buttrbase port-forward svc/buttrbase 4300:4300 &
curl -fsS http://localhost:4300/health && echo " ✓ healthy"
Confirm the topology round-tripped:
kubectl -n buttrbase exec deploy/buttrbase -- printenv BUTTRBASE_RUST_DEPLOYMENT_MODE
→ single-tenant-byoc
If the pod is not ready, read the logs — the two dominant first-install failures are a database-url the pod's network cannot reach and an encryption-key that is not 32 bytes hex. Both appear in the first ten log lines.
Done
You have the full GCP Marketplace packaging path: the image is in Artifact Registry, the chart is ready for the deployer wrapper, and the customer-facing install flow maps cleanly to single-tenant-byoc. From here:
07-deploy-with-helm.md is the ground truth for chart behavior, values semantics, and secret layout.09 covers the same chart packaged as an EKS Marketplace listing (AMI + Helm, Metering Service entitlement wiring).10 covers the Managed Application and AKS path.