usabilitydynamics/udx-worker-cnab repository overview

⁠UDX Worker CNAB

Secure, containerized tooling for building and publishing Helm-based applications as Porter CNAB bundles for Microsoft Marketplace Kubernetes offers.

⁠Quick Reference

• Source: https://github.com/udx/worker-cnab⁠
• Dockerfile: https://github.com/udx/worker-cnab/blob/latest/Dockerfile⁠
• Base image: https://hub.docker.com/r/usabilitydynamics/udx-worker⁠
• Deployment CLI: https://www.npmjs.com/package/@udx/worker-deployment⁠
• Microsoft Marketplace guide: https://learn.microsoft.com/en-us/partner-center/marketplace-offers/azure-container-technical-assets-kubernetes⁠

⁠Supported Tags

• latest
• Semantic version tags (recommended for CI/CD pinning)

⁠What It Is

UDX Worker CNAB extends usabilitydynamics/udx-worker with Porter, Helm, and ORAS for a repeatable Microsoft Marketplace packaging flow.

It owns the shared porter.yaml template, renders bundle configuration from environment variables, validates the CNAB payload, builds the bundle, and publishes the resulting OCI artifact to Azure Container Registry (ACR).

⁠Highlights

• Runs on the hardened UDX Worker runtime.
• Includes pinned, checksum-verified Porter, Helm, and ORAS releases.
• Builds Helm-based CNAB bundles with Marketplace-specific payload fields.
• Validates required payload files and extension registration parameters before build.
• Authenticates to ACR and validates the published bundle manifest after publish.
• Supports distinct application-image and CNAB-bundle repositories.

⁠Quick Start

⁠1) Prepare the CNAB payload

Create a directory containing:

cnab/
├── manifest.yaml
├── azuredeploy.json
├── createUIDefinition.json
└── helm/

manifest.yaml must include version and extensionRegistrationParameters.defaultScope. When defaultScope is cluster, it must also include extensionRegistrationParameters.namespace.

⁠2) Authenticate to Azure

Authenticate with an identity that can read the application image and push the CNAB bundle to the target ACR.

For local development, sign in with the Azure CLI:

az login

⁠3) Build and publish

Replace the example registry and image names, then run:

docker run --rm \
  --user root \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$PWD/cnab:/home/udx/ci/configs/cnab:ro" \
  -v "$HOME/.azure:/root/.azure:ro" \
  -e REGISTRY_REPO="example.azurecr.io/example-app-cnab" \
  -e APP_IMAGE_REPO="example.azurecr.io/example-app" \
  -e APP_IMAGE_TAG="1.0.0" \
  -e APP_NAME="example-app" \
  -e DISPLAY_NAME="Example App" \
  usabilitydynamics/udx-worker-cnab:latest

The worker renders porter.yaml, builds the CNAB bundle, publishes it to ACR, and validates the resulting OCI manifest.

⁠Configuration

Set RUN_CNAB_PUBLISH=false to build without publishing. Publishing requires a build in the same run.

⁠Deploy with Worker CLI

Use @udx/worker-deployment to keep local, CI/CD, and hosted runs consistent:

npm install -g @udx/worker-deployment
worker run --config=deploy.yml

The repository includes an example deploy.yml⁠ with the required Docker socket, optional CNAB payload mount, and Azure authentication mount.

⁠Marketplace Output

During the build, Worker CNAB renders the Marketplace-specific CNAB metadata required for Kubernetes offers, including:

• custom.helmchart
• custom.extensionregistrationparameters
• custom.packagingtoolversion
• custom.testparameterfile
• custom.skipdeployment

⁠Documentation

• Repository: https://github.com/udx/worker-cnab⁠
• Deployment guide: https://github.com/udx/worker-cnab/blob/latest/docs/deployment.md⁠
• Runtime behavior: https://github.com/udx/worker-cnab/blob/latest/docs/runtime.md⁠
• Troubleshooting: https://github.com/udx/worker-cnab/blob/latest/docs/troubleshoot.md⁠
• Base UDX Worker: https://hub.docker.com/r/usabilitydynamics/udx-worker⁠