Arkanis.Aspire.Hosting.Extensions.Kubernetes.CloudNativePostgres 1.0.0-dev.9

Arkanis.Aspire.Hosting.Extensions.Kubernetes.CloudNativePostgres

.NET Aspire hosting extensions for publishing CloudNativePG database resources. This package maps Aspire PostgreSQL resources to CloudNativePG database manifests and credentials backed by External Secrets.

Installation

dotnet add package Arkanis.Aspire.Hosting.Extensions.Kubernetes.CloudNativePostgres

Quick Start

using Aspire.Hosting;
using Aspire.Hosting.Extensions.Kubernetes;
using Aspire.Hosting.Extensions.Kubernetes.CloudNativePostgres;
using Aspire.Hosting.Extensions.Kubernetes.ExternalSecrets;
using Aspire.Hosting.Extensions.Kubernetes.KubernetesConnections;

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres");
var api = builder.AddProject<Projects.Api>("api");
var kubernetes = builder.AddKubernetesEnvironment("kubernetes");

postgres.WithCloudNativePostgresDatabase(database => database
    .WithClusterName("production")
    .WithDatabaseName("application")
    .InKubernetesEnvironment(kubernetes)
    .WithCredentialsSecret(credentials => credentials
        .FromSourceSecret("application-credentials")
        .ToTargetSecret("postgres-connection", "ConnectionStrings__ApplicationDatabase")
        .UsingSecretStore(ExternalSecretStoreOptions.ClusterSecretStore("postgres-production-credentials"))
        .RefreshEvery("30m")));

api.WithKubernetesConnectionString(postgres, "ApplicationDatabase");

builder.Build().Run();

WithCloudNativePostgresDatabase(...) emits the CloudNativePG Database manifest during Kubernetes publish. Credentials are emitted as an External Secrets Operator ExternalSecret that reads the CloudNativePG credential Secret and writes an application-local connection string Secret. WithKubernetesConnectionString(...) points the consuming workload at that generated Secret through ConnectionStrings__ApplicationDatabase.

Use configuration binding when you prefer appsettings-driven deployment details.

postgres.WithCloudNativePostgresDatabase(database =>
    database.WithConfigurationFrom(builder.Configuration));

Custom Connection-String Templates

Use WithConnectionStringTemplateSuffix(...) for an additional provider-specific clause.

The CloudNativePG overload of WithKubernetesConnectionString(...) configures the source credentials and then creates the existing destination Secret reference.

api.WithKubernetesConnectionString(
    postgres,
    "ApplicationDatabase",
    credentials => credentials.WithConnectionStringTemplateSuffix("Ssl Mode=Require"));

The same suffix can be configured through the resource-local configuration path.

{
  "Kubernetes": {
    "CloudNativePostgres": {
      "Resources": {
        "postgres": {
          "CredentialsSecret": {
            "ConnectionStringTemplateSuffix": "Ssl Mode=Require"
          }
        }
      }
    }
  }
}

Use WithConnectionStringTemplate(...) when the complete connection-string template must differ from the default.

postgres.WithCloudNativePostgresDatabase(database => database
    .WithClusterName("production")
    .WithCredentialsConnectionStringTemplate(annotation =>
        $"{{{{ `Host={{{{ .host }}}};Database={annotation.Credentials.DatabaseName};Ssl Mode=Require` }}}}"));

The callback returns the final Helm template value, rather than a runtime connection string.

The outer {{ ... }} is a Helm raw-string action.

It causes Helm to preserve the inner ESO expressions such as {{ .host }}.

External Secrets Operator evaluates those inner expressions after the CloudNativePG credentials Secret is extracted.

When writing the callback as a C# interpolated string, each literal brace is doubled.

Therefore {{{{ in the C# source emits {{, and }}}} emits }} in the Helm template.

A full template callback and a suffix are mutually exclusive.

For advanced External Secrets Operator changes, CustomizeExternalSecret(...) runs after the library configures the target, source extraction, and connection-string template.

It can add template data or deliberately replace the connection-string key.

postgres.WithCloudNativePostgresDatabase(database => database
    .WithClusterName("production")
    .CustomizeCredentialsExternalSecret((externalSecret, _) =>
        externalSecret.WithTemplateData("Database__Host", "{{ `{{ .host }}` }}")));

Scope

This package emits CloudNativePG and External Secrets publishing intent during Aspire publish. It does not install CloudNativePG, install External Secrets Operator, create operator credentials, or apply generated manifests to a live cluster.

Generated Names

WithCloudNativePostgresDatabase emits a CloudNativePG Database custom resource whose spec.name is the configured DatabaseName value, or the Aspire resource name when DatabaseName is omitted. The custom resource metadata.name defaults to {ClusterName}-{DatabaseName} after Kubernetes object-name normalization, or {ClusterName}-{ResourceName} when DatabaseName is omitted. Use MetadataName in configuration or WithMetadataName(...) in code to preserve an existing object name or choose a different Kubernetes object name. Credentials secret defaults remain resource-local: the source platform secret defaults to the effective database name with -credentials after normalization, while the target app secret defaults to {ResourceName}-connection after normalization.

Dependencies

This package references Arkanis.Aspire.Hosting.Extensions.Kubernetes. This package also references Arkanis.Aspire.Hosting.Extensions.Kubernetes.ExternalSecrets.

Repository

Source, issues, and release workflow details are available at https://github.com/ArkanisCorporation/Aspire.Hosting.Extensions.Kubernetes.