Deploy to Kubernetes clusters

Este conteúdo não está disponível em sua língua ainda.

Deploy your Aspire application to any existing Kubernetes cluster. Aspire generates a complete Helm chart from your application model, and you can either apply it yourself or let aspire deploy install it directly using your current kubectl context.

For hosting integration setup and configuration, see Kubernetes integration.

Prerequisites

Aspire prerequisites
Aspire CLI installed
kubectl installed with a configured cluster context
Helm v4.2.0 or later installed and available on your PATH
An existing Kubernetes cluster (local or remote)

Configure your AppHost

Add the Kubernetes hosting integration to your AppHost and configure a Kubernetes environment:

aspire add kubernetes

The Aspire CLI adds the 📦 Aspire.Hosting.Kubernetes integration to your AppHost.

Then add the Kubernetes environment in your AppHost:

TypeScript
C#

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const k8s = await builder.addKubernetesEnvironment('k8s');

const api = await builder
    .addNodeApp('api', './api', 'src/index.ts')
    .withHttpEndpoint({ env: 'PORT' })
    .withExternalHttpEndpoints();

await builder.build().run();

var builder = DistributedApplication.CreateBuilder(args);

var k8s = builder.AddKubernetesEnvironment("k8s");

var api = builder.AddProject<Projects.MyApi>("api");

builder.Build().Run();

When a Kubernetes environment is present, all compute resources are automatically published as Kubernetes workloads — no additional opt-in is required.

Configure a container registry

Unlike managed targets such as AKS, a vanilla Kubernetes cluster doesn’t know which container registry to use for your application images. Without a registry, Aspire has no way to make your locally-built images available to cluster nodes. You must provide a container registry that is accessible from both your local machine (to push images) and from the cluster (to pull images):

TypeScript
C#

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const registry = await builder.addContainerRegistry('registry', 'myregistry.example.com:5000');
const k8s = await builder.addKubernetesEnvironment('k8s');
await k8s.withContainerRegistry(registry);

const api = await builder
    .addNodeApp('api', './api', 'src/index.ts')
    .withHttpEndpoint({ env: 'PORT' })
    .withExternalHttpEndpoints();

await builder.build().run();

var builder = DistributedApplication.CreateBuilder(args);

var registry = builder.AddContainerRegistry("registry", "myregistry.example.com:5000");
builder.AddKubernetesEnvironment("k8s").WithContainerRegistry(registry);

var api = builder.AddProject<Projects.MyApi>("api");

builder.Build().Run();

The registry endpoint must be reachable from both your local machine and from the Kubernetes cluster nodes. When you run aspire deploy, Aspire builds your container images, pushes them to this registry, and configures the Helm chart to pull from it.

Publish Helm chart artifacts

To generate Kubernetes deployment artifacts without deploying, use aspire publish:

aspire publish -o k8s-artifacts

This command analyzes your application model and produces a complete Helm chart in the specified output directory:

Directoryk8s-artifacts/
- Chart.yaml Chart metadata (name, version, etc.)
- values.yaml Configurable values for the chart
- Directorytemplates/
  - Directory<resource>/
    deployment.yaml Deployment or StatefulSet
    service.yaml Service for connectivity
    config.yaml Configuration data (ConfigMap)

The publisher generates the following Kubernetes resources from your application model:

Deployments or StatefulSets for your application services
Services for network connectivity between resources
ConfigMaps for application configuration, connection strings, and environment variables

You can then deploy these artifacts using helm, kubectl, or your existing GitOps workflow.

Deploy to a cluster

To deploy directly to your current Kubernetes cluster, use aspire deploy:

aspire deploy

aspire deploy uses your current kubectl context and deploys the application using helm install. Aspire builds container images, generates the Helm chart, and installs it to the cluster in a single command.

For subsequent deployments, aspire deploy automatically upgrades the existing Helm release.

Deploy published artifacts with Helm

If you prefer to publish first and deploy separately — for example, in a CI/CD pipeline — use Helm to install the generated chart:

Install the chart to your cluster:
Install with Helm
```
helm install my-app ./k8s-artifacts
```
For subsequent deployments, upgrade the existing release:
Upgrade with Helm
```
helm upgrade my-app ./k8s-artifacts
```

Override default values using --set flags or a custom values file:

helm upgrade my-app ./k8s-artifacts \
    --set api.image.repository=myregistry.azurecr.io/api \
    --set api.image.tag=v1.2.0

Alternatively, create a custom values file for your environment:

api:
  image:
    repository: myregistry.azurecr.io/api
    tag: v1.2.0

helm upgrade my-app ./k8s-artifacts -f values.production.yaml

Customize the Kubernetes environment

Helm settings

Use WithHelm to configure Helm chart settings such as namespace, release name, and chart version:

TypeScript
C#

const k8s = await builder.addKubernetesEnvironment('k8s');
await k8s.withHelm(async (helm) => {
  await helm.withNamespace('my-namespace');
  await helm.withReleaseName('my-release');
  await helm.withChartVersion('1.0.0');
});

builder.AddKubernetesEnvironment("k8s")
    .WithHelm(helm =>
    {
        helm.WithNamespace("my-namespace");
        helm.WithReleaseName("my-release");
        helm.WithChartVersion("1.0.0");
    });

Helm is the default deployment engine. Call WithHelm only when you need to customize the defaults.

Node pools

Use AddNodePool to reference an existing node pool in your cluster, then WithNodePool to schedule specific workloads on it:

TypeScript
C#

const k8s = await builder.addKubernetesEnvironment('k8s');
const gpuPool = await k8s.addNodePool('gpu');

const worker = await builder.addContainer('ml-worker', 'my-ml-image');
await worker.withNodePool(gpuPool);

var k8s = builder.AddKubernetesEnvironment("k8s");
var gpuPool = k8s.AddNodePool("gpu");

builder.AddContainer("ml-worker", "my-ml-image")
    .WithNodePool(gpuPool);

Per-resource customization

Use PublishAsKubernetesService to modify the generated Kubernetes resources for individual services:

TypeScript
C#

const service = await builder.addContainer('service', 'nginx');
await service.withEnvironment('MY_ENV', 'value');
await service.publishAsKubernetesService(async (resource) => {
  // Scale to 3 replicas
  await resource.workload.spec.replicas.set(3);
});

using Aspire.Hosting.Kubernetes.Resources;

builder.AddContainer("service", "nginx")
    .WithEnvironment("MY_ENV", "value")
    .PublishAsKubernetesService(resource =>
    {
        // Scale to 3 replicas
        if (resource.Workload is Deployment deployment)
        {
            deployment.Spec.Replicas = 3;
        }
    });

Deployment considerations

Container images

The publisher generates parameterized Helm values for container image references. If you haven’t specified custom container images, the generated values.yaml contains placeholders that you override at deployment time using --set or a custom values file.

Resource names

Resource names in Kubernetes must follow DNS naming conventions. The integration automatically normalizes Aspire resource names by:

Converting to lowercase
Replacing invalid characters with hyphens
Ensuring names don’t start or end with hyphens

Environment-specific configuration

Use external parameters to configure values that differ between development and production environments.

Parameters inside environment expressions

When a parameter is embedded inside a larger environment variable expression — for example, a URL that contains a host parameter — the publisher declares the parameter as its own entry in values.yaml. The embedded parameter doesn’t become an extra environment variable; instead, the generated ConfigMap or Secret references it directly, so you can override just that value at deployment time without reconstructing the entire URL.

Use an Aspire reference expression for composition, not a TypeScript string interpolation of a resource handle:

TypeScript
C#

import { 
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder, 
function refExpr(strings: TemplateStringsArray, ...values: unknown[]): ReferenceExpression
Creates a reference expression from a tagged template literal
refExpr } from './.aspire/modules/aspire.mjs';

const 
const builder: IDistributedApplicationBuilder
builder = await 
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder();
await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.addKubernetesEnvironment(name: string): KubernetesEnvironmentResource
Adds a Kubernetes environment to the application model.
addKubernetesEnvironment('k8s');
const 
const host: ParameterResource
host = await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.addParameter(name: string, options?: {
    value?: string;
    publishValueAsDefault?: boolean;
    secret?: boolean;
}): ParameterResource (+1 overload)
Adds a parameter resource
addParameter('host', { 
value?: string | undefined
value: 'localhost' });
const 
const myapp: ContainerResource
myapp = await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.addContainer(name: string, image: string | AddContainerOptions): ContainerResource
Adds a container resource to the application.
addContainer('myapp', 'nginx');
await 
const myapp: ContainerResource
myapp.
ContainerResource.withEnvironment(name: string, value: string | IResourceWithConnectionString | IValueProvider): ContainerResource
Sets an environment variable
withEnvironment('SOME_URL', 
function refExpr(strings: TemplateStringsArray, ...values: unknown[]): ReferenceExpression
Creates a reference expression from a tagged template literal
refExpr`http://${
const host: ParameterResource
host}/test`);

await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.build(): DistributedApplication
Builds the distributed application
build().
DistributedApplication.run(cancellationToken?: cancellationToken): void
Runs the distributed application
run();

var builder = DistributedApplication.CreateBuilder(args);
builder.AddKubernetesEnvironment("k8s");
var host = builder.AddParameter("host", "localhost");

builder.AddContainer("myapp", "nginx")
    .WithEnvironment("SOME_URL", $"http://{host}/test");

builder.Build().Run();

The generated values.yaml declares both the composed environment value and the nested host parameter under the resource’s config section, and the ConfigMap template references the nested value:

config:
  myapp:
    SOME_URL: ""
    host: ""

data:
  SOME_URL: "http://{{ .Values.config.myapp.host }}/test"

When you deploy with aspire deploy, Aspire resolves each nested parameter and the composed expression using the parameter’s effective value — for example, SOME_URL becomes http://localhost/test. If you install the chart yourself, override the nested entry, such as --set config.myapp.host=example.com. Secret parameters are declared under secrets.<resource> instead, and any environment variable that embeds a secret parameter is emitted in the resource’s Secret rather than its ConfigMap.

Conflicting Helm value paths, including names that collide after normalization, fail publishing rather than overwriting another entry.

Service discovery

In Kubernetes, services discover each other using the cluster’s built-in DNS. A service named api is reachable at api.<namespace>.svc.cluster.local. The generated Helm charts configure service references automatically using Kubernetes-native DNS resolution.

Troubleshooting

Connection strings empty in Kubernetes

If your application can’t find connection strings at runtime, verify that the generated ConfigMaps and Secrets are correctly mounted as environment variables in your pod specifications. Check that the resource names in your Helm values match the expected connection string names.

Password and authentication issues

Kubernetes Secrets store values as base64-encoded strings. Verify that your Secrets are properly encoded and that the generated templates reference them correctly. Use kubectl get secret <name> -o yaml to inspect Secret contents.

Install external Helm charts

Use AddHelmChart on the Kubernetes environment to install pre-existing Helm charts — such as cert-manager, NGINX ingress, or monitoring tools — as post-deploy pipeline steps alongside your application’s own chart.

See Install external Helm charts for a full walkthrough of adding external charts, configuring Helm values, overriding namespaces and release names, and choosing destroy-time uninstall behavior.