scripts/azure-marketplace/README.md
This guide walks you through publishing Bytebase as an Azure Container Offer on Azure Marketplace.
Azure Account Setup
Technical Requirements
Tools
bytebase/
├── scripts/azure-marketplace/
│ ├── manifest.yaml # Package metadata
│ ├── createUiDefinition.json # Azure portal deployment UI
│ ├── mainTemplate.json # ARM template for deployment
│ ├── values-azure.yaml # Azure-specific Helm values
│ └── README.md # This file
├── helm-charts/bytebase/ # Your existing Helm chart
│ ├── Chart.yaml
│ ├── values.yaml
│ └── templates/
│ ├── statefulset.yaml # Needs modification (see below)
│ └── ...
└── scripts/
└── Dockerfile # Your existing Dockerfile
Azure Marketplace requires images to use the global.azure.images pattern. You need to update your helm-charts/bytebase/templates/statefulset.yaml file.
{{- if $registryMirrorHost }}
image: {{ trimSuffix "/" $registryMirrorHost }}/bytebase/bytebase:{{ $version }}
{{- else }}
image: bytebase/bytebase:{{ $version }}
{{- end }}
{{- if .Values.global.azure.images.bytebase }}
# Azure Marketplace image path
image: {{ .Values.global.azure.images.bytebase.registry }}/{{ .Values.global.azure.images.bytebase.repository }}:{{ .Values.global.azure.images.bytebase.tag }}
{{- else if $registryMirrorHost }}
# Registry mirror path
image: {{ trimSuffix "/" $registryMirrorHost }}/bytebase/bytebase:{{ $version }}
{{- else }}
# Default Docker Hub path
image: bytebase/bytebase:{{ $version }}
{{- end }}
This change allows Azure Marketplace to retag and host images in their registry while maintaining backward compatibility with existing deployments.
# Login to Azure
az login
# Create resource group (if needed)
az group create --name bytebase-marketplace --location eastus
# Create Azure Container Registry
az acr create \
--resource-group bytebase-marketplace \
--name bytebaseacr \
--sku Premium \
--location eastus
# Login to ACR
az acr login --name bytebaseacr
# Get ACR login server
ACR_LOGIN_SERVER=$(az acr show --name bytebaseacr --query loginServer --output tsv)
echo "ACR Login Server: $ACR_LOGIN_SERVER"
You have two options: use the official Bytebase image from Docker Hub, or build your own.
# Pull the official Bytebase image
docker pull bytebase/bytebase:3.11.1
# Tag for ACR
docker tag bytebase/bytebase:3.11.1 $ACR_LOGIN_SERVER/bytebase/bytebase:3.11.1
# Push to ACR
docker push $ACR_LOGIN_SERVER/bytebase/bytebase:3.11.1
# From the root of your repository
cd /Users/ecmadao/Develop/Bytebase/ecmadao/bytebase
# Build the Docker image
docker build -f scripts/Dockerfile -t bytebase/bytebase:3.11.1 .
# Tag for ACR
docker tag bytebase/bytebase:3.11.1 $ACR_LOGIN_SERVER/bytebase/bytebase:3.11.1
# Push to ACR
docker push $ACR_LOGIN_SERVER/bytebase/bytebase:3.11.1
Automated Script:
./scripts/azure-marketplace/push-to-acr.sh
Edit scripts/azure-marketplace/manifest.yaml and update the registry and image references:
registries:
- name: <your-acr-name>.azurecr.io
url: <your-acr-name>.azurecr.io
images:
- image: <your-acr-name>.azurecr.io/bytebase/bytebase:3.11.1
platform: linux/amd64
The CNAB bundle must be built and published by Microsoft's CPA tool to ensure proper OCI artifact format.
cd azure-marketplace
./package.sh
This script will:
cpa verifycpa buildbundleStep 5a: Verify artifacts
cd /Users/ecmadao/Develop/Bytebase/ecmadao/bytebase
docker run --rm \
-v /var/run/docker.sock:/var/run/docker.sock \
-v $(pwd):/data \
-w /data/azure-marketplace \
mcr.microsoft.com/container-package-app:latest \
cpa verify
Step 5b: Build and publish CNAB bundle
IMPORTANT: The CPA tool needs Azure CLI authentication to push to ACR. You must mount your Azure credentials:
# Ensure you're logged in to Azure
az login
az acr login --name <your-acr-name>
# Run CPA with Azure credentials mounted
docker run --rm \
-v /var/run/docker.sock:/var/run/docker.sock \
-v $(pwd)/..:/data \
-v $HOME/.azure:/root/.azure \
-w /data/azure-marketplace \
mcr.microsoft.com/container-package-app:latest \
/bin/bash -c "az acr login --name <your-acr-name> && cpa buildbundle --force"
What this does:
<your-acr-name>.azurecr.io/bytebase:3.11.1Verify the bundle:
# Check the bundle manifest has proper CNAB annotations
az acr manifest show --registry <your-acr-name> --name bytebase:3.11.1 | grep "io.cnab"
You should see annotations like:
io.cnab.runtime_version: 1.2.0org.opencontainers.artifactType: application/vnd.cnab.manifest.v1Troubleshooting:
Common authentication issues include:
The key is that the CPA tool itself must push the bundle - manual docker push will not create the proper CNAB/OCI artifact format that Partner Center requires.
Before submitting to Partner Center, test your deployment UI:
Go to Azure Portal CreateUI Sandbox: https://portal.azure.com/#blade/Microsoft_Azure_CreateUIDef/SandboxBlade
Copy the contents of scripts/azure-marketplace/createUiDefinition.json
Paste and test the UI flow
Verify all fields, validations, and outputs work correctly
For detailed, step-by-step instructions on creating your Partner Center offer, see:
📖 PARTNER_CENTER_GUIDE.md - Complete walkthrough with field-by-field instructions
Quick Overview:
bytebase (permanent, must be unique)<your-acr-name>.azurecr.io/bytebase:3.11.1Required Materials:
Timeline: 2-4 weeks for Microsoft certification after submission
Review and Submit
Certification Process
Address Feedback
Once certification passes:
Before submitting, test locally:
# Install your Helm chart with Azure values
helm install bytebase-test ./helm-charts/bytebase \
-f scripts/azure-marketplace/values-azure.yaml \
--set bytebase.option.externalPg.url="postgresql://user:pass@host:5432/db" \
--set bytebase.option.external-url="https://test.example.com" \
--namespace bytebase \
--create-namespace
# Verify deployment
kubectl get pods -n bytebase
kubectl logs -n bytebase -l app=bytebase
# Clean up
helm uninstall bytebase-test -n bytebase
Pros:
Cons:
Pros:
Cons:
Microsoft takes a commission on marketplace transactions:
BYOL offers still have a marketplace fee (~3%) for listing.
After publishing, to release new versions:
manifest.yaml with new versioncpa buildbundle to create new CNABCritical Requirement: Partner Center requires CNAB bundles in proper OCI artifact format, not regular Docker v2 manifests.
What This Means:
cpa buildbundle)docker push will NOT work (creates wrong manifest type)io.cnab.runtime_version and org.opencontainers.artifactTypeHow to Verify:
# Check your bundle format
az acr manifest show --registry <your-acr-name> --name bytebase:3.11.1
# Should show:
# - annotations.io.cnab.runtime_version: "1.2.0"
# - annotations.org.opencontainers.artifactType: "application/vnd.cnab.manifest.v1"
# - mediaType: "application/vnd.oci.image.manifest.v1+json" (for manifests)
If your bundle shows mediaType: "application/vnd.docker.distribution.manifest.v2+json" instead, it was pushed incorrectly and Partner Center will reject it with error: "The artifact you selected is not a valid Cloud Native Application Bundle (CNAB)"
Solution: Delete the incorrect bundle and republish using the CPA tool with Azure CLI authentication as described in Step 5b.
Problem: Error "The artifact you selected is not a valid Cloud Native Application Bundle (CNAB)" Solution:
az acr manifest show commandProblem: ACR images can't be pulled during packaging
Solution: Ensure you're logged into ACR: az acr login --name <acr-name>
Problem: cpa buildbundle fails with authentication errors
Solution:
az loginaz acr login --name <acr-name>-v $HOME/.azure:/root/.azureProblem: cpa verify fails with Helm chart errors
Solution:
Chart.yaml apiVersion is v2Problem: UI definition doesn't load in sandbox Solution:
Problem: Certification blocked by vulnerability scan Solution:
docker scan locally before submitting