Deploy to Kubernetes

此内容尚不支持你的语言。

Kubernetes is a supported deployment target for Aspire applications. By adding the Kubernetes hosting integration to your AppHost, you can use aspire publish to generate a complete set of Helm chart artifacts ready for deployment to any Kubernetes cluster.

For hosting integration setup and configuration, see Kubernetes integration.

To configure your AppHost for Kubernetes, add a Kubernetes environment with AddKubernetesEnvironment:

C#
TypeScript

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.Build().Run();

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

const builder = await createBuilder();

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

const api = await builder.addProject('api', '../MyApi/MyApi.csproj', 'http');

await builder.build().run();

Generate Kubernetes artifacts

To generate Kubernetes deployment artifacts from your Aspire application, run the aspire publish command:

aspire publish -o k8s-artifacts

This command analyzes your application model and produces a complete Helm chart in the specified output directory. The generated chart structure looks like this:

文件夹k8s-artifacts/
- Chart.yaml Chart metadata (name, version, etc.)
- values.yaml Configurable values for the chart
- 文件夹templates/
  - 文件夹<resource>/
    deployment.yaml Deployment or StatefulSet
    service.yaml Service for connectivity
    configmap.yaml Configuration data
    secret.yaml Sensitive data

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 and connection strings
Secrets for sensitive data such as passwords and connection strings
Dockerfiles copied into the output directory for container build contexts

Deploy with Helm

After generating artifacts, use Helm to deploy your application to a Kubernetes cluster:

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

Supported resource mappings

The Kubernetes publisher converts Aspire resources to their Kubernetes equivalents:

Aspire resource	Kubernetes resource
Project resources	Deployments or StatefulSets
Container resources	Deployments or StatefulSets
Connection strings	ConfigMaps and Secrets
Environment variables	ConfigMaps and Secrets
Endpoints	Services
Volumes	PersistentVolumes and PersistentVolumeClaims

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.

Helm chart name

By default, the Helm chart name is derived from your AppHost project. Configure a custom chart name using WithProperties:

C#
TypeScript

var builder = DistributedApplication.CreateBuilder(args);

builder.AddKubernetesEnvironment("k8s")
    .WithProperties(k8s =>
    {
        k8s.HelmChartName = "my-aspire-app";
    });

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

const builder = await createBuilder();

const k8s = await builder.addKubernetesEnvironment('k8s');
await k8s.withProperties(async (k8s) => {
  await k8s.helmChartName.set('my-aspire-app');
});

Customize Kubernetes services

Use the PublishAsKubernetesService callback to modify the generated Kubernetes resources for individual services. This provides fully typed access to the Kubernetes object model:

C#
TypeScript

var builder = DistributedApplication.CreateBuilder(args);

builder.AddContainer("service", "nginx")
    .WithEnvironment("ORIGINAL_ENV", "value")
    .PublishAsKubernetesService(resource =>
    {
        // Customize the generated Kubernetes resource
    });

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

const builder = await createBuilder();

const service = await builder.addContainer('service', 'nginx');
await service.withEnvironment('ORIGINAL_ENV', 'value');
await service.publishAsKubernetesService(async (resource) => {
  // Customize the generated Kubernetes resource
});

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.

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.