Kubernetes integration

이 콘텐츠는 아직 번역되지 않았습니다.

This article is the reference for the Aspire Kubernetes hosting integration. It enumerates the AppHost APIs — with examples for both AppHost.cs and apphost.ts — that you use to model Kubernetes environment resources in your AppHost project. The integration enables you to publish and deploy your Aspire application to any Kubernetes cluster, generating Helm charts from your application model or deploying directly to a cluster using your current kubectl context.

Installation

To start building an Aspire app with Kubernetes deployment support, install the 📦 Aspire.Hosting.Kubernetes NuGet package:

C#
TypeScript

aspire add kubernetes

Learn more about aspire add in the command reference.

Or, choose a manual installation approach:

#:package Aspire.Hosting.Kubernetes@*

<PackageReference Include="Aspire.Hosting.Kubernetes" Version="*" />

aspire add kubernetes

Learn more about aspire add in the command reference.

This updates your aspire.config.json with the Kubernetes hosting integration package:

{
  "packages": {
    "Aspire.Hosting.Kubernetes": "*"
  }
}

Add Kubernetes environment

After installing the package, add a Kubernetes environment to your AppHost:

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
    .addNodeApp('api', './api', 'src/index.ts')
    .withHttpEndpoint({ env: 'PORT' })
    .withExternalHttpEndpoints();

await builder.build().run();

Configure Helm chart options

You can configure the generated Helm chart using the WithHelm method, which provides a fluent HelmChartOptions builder:

C#
TypeScript

builder.AddKubernetesEnvironment("k8s")
    .WithHelm(helm =>
    {
        helm.WithChartName("my-aspire-app")
            .WithChartVersion("1.0.0")
            .WithChartDescription("My Aspire application deployed to Kubernetes")
            .WithReleaseName("my-release")
            .WithNamespace("my-namespace");
    });

const k8s = await builder.addKubernetesEnvironment('k8s');
await k8s.withHelm(async (helm) => {
  await helm.withNamespace('my-namespace');
  await helm.withReleaseName('my-release');
  await helm.withChartName('my-aspire-app');
  await helm.withChartVersion('1.0.0');
  await helm.withChartDescription('My Aspire application deployed to Kubernetes');
});

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

The WithHelm method is the single configuration entry point for Helm chart settings. The available options are:

Method	Description
`WithChartName(string)`	Sets the Helm chart name (defaults to the application name).
`WithChartVersion(string)`	Sets the Helm chart version. Accepts a literal string or an Aspire parameter.
`WithChartDescription(string)`	Sets the description written into `Chart.yaml`.
`WithReleaseName(string)`	Sets the Helm release name used during deployment.
`WithNamespace(string)`	Sets the Kubernetes namespace for the deployment.

Configure a container registry

A vanilla Kubernetes cluster doesn’t know which container registry to use for your application images. Use AddContainerRegistry and WithContainerRegistry to specify a registry that is accessible from both your local machine and from the cluster:

C#
TypeScript

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

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

Customize individual resources

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

C#
TypeScript

using Aspire.Hosting.Kubernetes.Resources;

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

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

Publishing and deployment

The Kubernetes integration supports both aspire publish (generate Helm chart artifacts) and aspire deploy (deploy directly to your current cluster context).

For complete walkthroughs, see Deploy to Kubernetes clusters.