Skip to main content

How to add WebAssembly components to IDPBuilder

IDPBuilder is an open source tool that enables you to run a complete internal developer platform (IDP) on your local machine, using standard cloud-native technologies like Kubernetes and Argo CD—and requiring only Docker or a compatible container system as a dependency.

Cosmonic Control is easy to deploy with IDPBuilder, which can be helpful for platform teams working with WebAssembly (Wasm). A deployment of Cosmonic Control with IDPBuilder generally uses the following open source tools:

  • Gitea - Self-hosted Git server that runs inside the Kubernetes cluster
  • Argo CD - Continuous delivery system that enables GitOps workflows
  • Envoy - Service proxy that provides cluster ingress

Users can push code to the local Git server to trigger Argo workflows and roll out WebAssembly workloads on Cosmonic Control.

Why use IDPBuilder and Wasm?​

For teams leveraging the isolation, efficiency, and composability of Wasm, IDPBuilder provides...

  • Wasm helps platform teams Shift Down: Application team tenants can use a lightweight abstraction that is more secure, portable, and easier to to maintain.
  • Accelerated application development: Cosmonic Control features accelerative development experiences like SandboxMCP.ai, enabling developers to generate MCP tools straight from OpenAPI specs and compile to Wasm artifacts.
  • Simplified IDP development: Platform teams can quickly spin up a platform development environment that utilizes WebAssembly components, requiring only the open source Wasm Shell CLI to build and publish Wasm artifacts.
  • Integration testing for platforms: Use an IDPBuilder environment for integration testing on applications and services that utilize Wasm.
  • Reference implementations: Create a single binary which can demonstrate an IDP reference implementation.

Walkthrough​

The instructions below demonstrate how to launch an IDP environment that is pre-integrated with Cosmonic Control. After successful deployment, the following endpoints will be available:

Requirements​

Install IDPBuilder​

You can install the idpbuilder CLI tool via Homebrew or from the project's GitHub releases page.

Using Homebrew:

brew install cnoe-io/tap/idpbuilder

See the IDPbuilder documentation for more information.

Deploy the IDP stack​

Use the idpbuilder CLI tool to create a new IDP environment based on the Cosmonic Labs example repository:

idpbuilder create --host localhost.cosmonic.sh --extra-ports "80:80" -p https://github.com/cosmonic-labs/idp-stack//cosmonic-control

Once the IDP is successfully created, you can find the admin password for the cluster's Argo CD UI by running:

idpbuilder get secrets -p argocd

Log in with the username admin and the returned password to access the Argo CD UI.

Argo CD UI

Port-forward the Console UI​

Start a port-forward the Console UI:

kubectl -n cosmonic-system port-forward svc/console 8081:8081

Now you can open the Console UI at http://localhost:8081/.

Log in with the following demo credentials (configurable at installation):

  • User: test_admin
  • Password: wasm123

Deploy a Wasm component​

You can use Helm to deploy another Wasm component from the Cosmonic Template Catalog, such as the Hono Swagger UI Example, directly to the cluster:

helm install hono-swagger-ui --version 0.1.2 oci://ghcr.io/cosmonic-labs/charts/http-trigger -f https://raw.githubusercontent.com/cosmonic-labs/control-demos/refs/heads/main/hono-swagger-ui/values.http-trigger.yaml

Helm should return a result like:

Pulled: ghcr.io/cosmonic-labs/charts/http-trigger:0.1.2
Digest: sha256:df04451ac7093fc134a6a6c594c8961c0fa2a12a5c81a9605fc5a8f8e8f61e29
NAME: hono-swagger-ui
LAST DEPLOYED: Mon Nov  3 07:21:45 2025
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
The hono-swagger-ui trigger has been deployed successfully.

The HTTP Server is serving on http://hono-swagger-ui.localhost.cosmonic.sh/ui

The HTTP-trigger Chart leverages the HTTP Trigger CRD and is customized with the values for the hono-swagger-ui example:

# For the 'http-trigger' helm chart
components:
  - name: hono-swagger-ui
    image: ghcr.io/cosmonic-labs/control-demos/hono-swagger-ui:0.1.2

ingress:
  host: "hono-swagger-ui.localhost.cosmonic.sh"

hostInterfaces:
  - namespace: wasi
    package: config
    version: 0.2.0-draft
    interfaces:
      - runtime
  - namespace: wasi
    package: logging
    version: 0.1.0-draft
    interfaces:
      - logging

pathNote: "/ui"

Try other examples, such as the "Blobby" blobstore fileserver example):

helm install blobby --version 0.1.2 oci://ghcr.io/cosmonic-labs/charts/http-trigger -f https://raw.githubusercontent.com/cosmonic-labs/control-demos/refs/heads/main/blobby/values.http-trigger.yaml

See the Blobby documentation for instructions on usage.

In review​

In alignment with upstream standards for both WebAssembly and Kubernetes, we have deployed Cosmonic Control integrated with IDPBuilder.

We deployed Custom Resource Definitions (CRDs) for wasmCloud and Cosmonic Control:

kubectl get crd -A | grep -E "wasmcloud|cosmonic"
artifacts.runtime.wasmcloud.dev             2025-11-02T16:11:48Z
hosts.runtime.wasmcloud.dev                 2025-11-02T16:11:48Z
httptriggers.control.cosmonic.io            2025-11-02T16:11:48Z
projectenvironments.control.cosmonic.io     2025-11-02T16:11:48Z
workloaddeployments.runtime.wasmcloud.dev   2025-11-02T16:11:48Z
workloadreplicasets.runtime.wasmcloud.dev   2025-11-02T16:11:48Z
workloads.runtime.wasmcloud.dev             2025-11-02T16:11:48Z

The Cosmonic operator was deployed to watch those CRDs:

kubectl get deploy -A | grep -i operator
cosmonic-system      operator                           1/1     1            1           20h

We setup three HTTPTriggers, each running in their own sandbox, in two different namespaces, on a single multi-tenant wasmCloud host:

kubectl get workloads -A
NAMESPACE         NAME                                              HOSTID                                 READY
cosmonic-system   welcome-tour-94dbb874f-7dcb86c9c6-56c59c99f8      f752cb64-3861-4e4d-9a70-21ec4a7ef001   True
default           blobby-8488c98f44-6855b68dfc-6466cf6c6c           f752cb64-3861-4e4d-9a70-21ec4a7ef001   True
default           hono-swagger-ui-85d4547558-84d47ddc96-c9b8768b9   f752cb64-3861-4e4d-9a70-21ec4a7ef001   True

Clean up​

Delete the IDP:

idpbuilder delete

Make sure the kind cluster has been deleted:

kind delete cluster