Hosting API
AddKubeMQ and the WithLicenseKey, WithDataVolume, and WithImageTag builder methods for provisioning a KubeMQ container in the Aspire AppHost.
The KubeMQ.Aspire.Hosting package adds a KubeMQ container resource to your Aspire AppHost. This page documents AddKubeMQ, its With* builder methods, the container resource it provisions, and the three endpoints it maps. For client-side registration see the Client API; for settings and connection strings see Configuration.
Packages
The integration ships two NuGet packages following the standard Aspire two-package model — one for the AppHost, one for the consuming service.
| Package | Project | Role |
|---|---|---|
KubeMQ.Aspire.Hosting | AppHost | Provision KubeMQ containers in the Aspire AppHost |
KubeMQ.Aspire.Client | Service | Configure IKubeMQClient with health checks, OpenTelemetry, and keyed DI |
dotnet add package KubeMQ.Aspire.Hostingdotnet add package KubeMQ.Aspire.ClientAddKubeMQ and builder methods
The hosting package extends IDistributedApplicationBuilder with AddKubeMQ and the resource with three With* builder methods. All builder methods return IResourceBuilder<KubeMQServerResource> so they chain fluently.
| Method | Description |
|---|---|
AddKubeMQ(name, grpcPort?) | Add a KubeMQ container resource. grpcPort fixes the host-side gRPC port; omit it to let Aspire auto-assign. |
WithLicenseKey(parameter) | Set the KUBEMQ_TOKEN environment variable from a secret ParameterResource. |
WithDataVolume(name?) | Bind a persistent volume to /store. Defaults the volume name to {resourceName}-data. |
WithImageTag(tag) | Override the Docker image tag (default tag: 2.5.0). |
var builder = DistributedApplication.CreateBuilder(args);
var kubemqKey = builder.AddParameter("kubemq-key", secret: true);
var messaging = builder.AddKubeMQ("messaging")
.WithLicenseKey(kubemqKey)
.WithDataVolume();
builder.AddProject<Projects.MyWebApi>("webapi")
.WithReference(messaging)
.WaitFor(messaging);
builder.Build().Run();WithLicenseKey takes an IResourceBuilder<ParameterResource>, not a raw string. Declare the parameter with builder.AddParameter("kubemq-key", secret: true) and supply the value via dotnet user-secrets or the Parameters configuration section so the key never lands in source.
Container resource
AddKubeMQ registers a KubeMQServerResource (a ContainerResource that also implements IResourceWithConnectionString) and configures the container as follows.
| Property | Value |
|---|---|
| Image | europe-docker.pkg.dev/kubemq/images/kubemq:2.5.0 (registry europe-docker.pkg.dev, image kubemq/images/kubemq, tag 2.5.0) |
| Lifetime | ContainerLifetime.Persistent — the container survives AppHost restarts |
| Connection string | host:port for the gRPC endpoint |
The connection string is expressed from the gRPC endpoint as {host}:{port} — there is no scheme prefix. This is the value WithReference(messaging) injects into a referencing service and that AddKubeMQClient("messaging") reads back.
public ReferenceExpression ConnectionStringExpression =>
ReferenceExpression.Create(
$"{GrpcEndpoint.Property(EndpointProperty.Host)}:{GrpcEndpoint.Property(EndpointProperty.Port)}");Endpoints
AddKubeMQ maps three endpoints on the container. The gRPC endpoint is the primary client connection; REST and Dashboard are exposed for the HTTP API and the web UI.
| Name | Target Port | Protocol |
|---|---|---|
grpc | 50000 | TCP |
rest | 9090 | HTTP |
dashboard | 8080 | HTTP |
Only the gRPC endpoint feeds the connection string. The host-side gRPC port is auto-assigned unless you pass grpcPort to AddKubeMQ — the in-container target port is always 50000.
Related
Was this page helpful?