Edit

Share via

Aspire Kubernetes hosting integration

Includes: Hosting integration included Hosting integration only — Client integration not included Client integration not included

The Aspire Kubernetes hosting integration enables you to generate Kubernetes deployment manifests from your Aspire application model. This integration allows you to define your application's infrastructure and deployment configuration using the familiar Aspire AppHost and then publish it as Kubernetes YAML manifests for deployment to any Kubernetes cluster.

Hosting integration

To get started with the Aspire Kubernetes hosting integration, install the 📦 Aspire.Hosting.Kubernetes NuGet package in the AppHost project.

dotnet add package Aspire.Hosting.Kubernetes

For more information, see dotnet add package or Manage package dependencies in .NET applications.

Add Kubernetes environment

After installing the package, add a Kubernetes environment to your AppHost project using the AddKubernetesEnvironment method:

var builder = DistributedApplication.CreateBuilder(args);

// Add Kubernetes environment
var k8s = builder.AddKubernetesEnvironment("k8s");

// Add your application resources
var cache = builder.AddRedis("cache");

var apiService = builder.AddProject<Projects.ApiService>("apiservice")
                        .WithReference(cache);

builder.AddProject<Projects.Web>("webfrontend")
       .WithExternalHttpEndpoints()
       .WithReference(cache)
       .WithReference(apiService);


builder.Build().Run();

Tip

With the k8s variable assigned, you can pass that to the WithComputeEnvironment API to disambiguate compute resources for solutions that define more than one. Otherwise, the k8s variable isn't required.

Configure Kubernetes environment properties

You can customize the Kubernetes environment using the WithProperties method:

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.Build().Run();

The WithProperties method allows you to configure various aspects of the Kubernetes deployment, including the Helm chart name that will be used for generating the Kubernetes resources.

Generate Kubernetes manifests

To generate Kubernetes manifests from your Aspire application, use the aspire publish command:

aspire publish -o k8s-artifacts

For more information, see aspire publish command reference.

This command generates a complete set of Kubernetes YAML manifests in the specified output directory (k8s-artifacts in this example). The generated artifacts include:

  • Deployments or StatefulSets for your application services.
  • Services for network connectivity.
  • ConfigMaps for application configuration.
  • Secrets for sensitive data.
  • Helm charts for easier deployment management.

Supported resources

The Kubernetes hosting integration supports converting various Aspire resources to their Kubernetes equivalents:

  • Project resources → Deployments or StatefulSets.
  • Container resources → Deployments or StatefulSets.
  • Connection strings → ConfigMaps and Secrets.
  • Environment variables → ConfigMaps and Secrets.
  • Endpoints → Services and ingress configuration.
  • Volumes → PersistentVolumes and PersistentVolumeClaims.

Deployment considerations

When deploying to Kubernetes, consider the following:

Container images

Ensure your application projects are configured to build container images. The Kubernetes publisher will reference the container images for your projects. If you haven't specified custom container images, the integration will use parameterized Helm values that you can override during deployment.

Resource names

Resource names in Kubernetes must follow DNS naming conventions. The integration automatically converts Aspire resource names to valid Kubernetes 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 environment-specific values that should be different between development and production environments.

See also