Set up Elasticsearch in the AppHost

This article is the reference for the Aspire Elasticsearch Hosting integration. It enumerates the AppHost APIs — with C# examples — that you use to model an Elasticsearch resource in your AppHost project.

If you’re new to the Elasticsearch integration, start with the Get started with Elasticsearch integrations guide. For how consuming apps read the connection information this page exposes, see Connect to Elasticsearch.

Installation

To start building an Aspire app that uses Elasticsearch, install the 📦 Aspire.Hosting.Elasticsearch NuGet package:

C#

Terminal

aspire add elasticsearch

Learn more about aspire add in the command reference.

Or, choose a manual installation approach:

C# — AppHost.cs

#:package Aspire.Hosting.Elasticsearch@*

XML — AppHost.csproj

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

TypeScript

Terminal

aspire add elasticsearch

Learn more about aspire add in the command reference.

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

aspire.config.json

{
  "packages": {
    "Aspire.Hosting.Elasticsearch": "13.3.0"
  }
}

Caution

The TypeScript AppHost doesn’t currently expose an addElasticsearch(...) API. After installing the package, use builder.addConnectionString(...) to reference an existing Elasticsearch instance, or builder.addContainer(...) with the docker.io/library/elasticsearch image to spin up a new one.

Add Elasticsearch resource

Once you’ve installed the hosting integration in your AppHost project, you can add an Elasticsearch resource as shown in the following example:

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var elasticsearch = builder.AddElasticsearch("elasticsearch");

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(elasticsearch);

// After adding all resources, run the app...

TypeScript

The TypeScript AppHost doesn’t currently expose an addElasticsearch(...) API. To add an Elasticsearch instance to a TypeScript AppHost, use builder.addContainer(...) with the docker.io/library/elasticsearch image, or use builder.addConnectionString(...) to reference an existing instance.

1. When Aspire adds a container image to the AppHost, as shown in the preceding example with the docker.io/library/elasticsearch image, it creates a new Elasticsearch instance on your local machine.

2. The Elasticsearch resource includes default credentials with a username of "elastic" and a randomly generated password. To set an explicit password, see Add Elasticsearch resource with parameters.

3. The AppHost reference call configures a connection in the consuming project named after the referenced Elasticsearch resource, such as elasticsearch in the preceding example.

Note

When you reference an Elasticsearch resource from the AppHost, Aspire makes several properties available to the consuming project, such as the connection URI. For a complete list of these properties and per-language connection examples, see Connect to Elasticsearch.

Add Elasticsearch resource with data volume

Add a data volume to the Elasticsearch resource as shown in the following example:

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var elasticsearch = builder.AddElasticsearch("elasticsearch")
    .WithDataVolume(isReadOnly: false);

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(elasticsearch);

// After adding all resources, run the app...

TypeScript

The TypeScript AppHost doesn’t currently expose an addElasticsearch(...) API. Data volume configuration is not available for Elasticsearch in TypeScript AppHosts.

The data volume is used to persist Elasticsearch data outside the lifecycle of its container. The data volume is mounted at the /usr/share/elasticsearch/data path in the Elasticsearch container and when a name parameter isn’t provided, the name is generated at random. For more information on data volumes and details on why they’re preferred over bind mounts, see Docker docs: Volumes.

Add Elasticsearch resource with data bind mount

Add a data bind mount to the Elasticsearch resource as shown in the following example:

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var elasticsearch = builder.AddElasticsearch("elasticsearch")
    .WithDataBindMount(
        source: @"C:\Elasticsearch\Data",
        isReadOnly: false);

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(elasticsearch);

// After adding all resources, run the app...

TypeScript

The TypeScript AppHost doesn’t currently expose an addElasticsearch(...) API. Data bind mount configuration is not available for Elasticsearch in TypeScript AppHosts.

Note

Data bind mounts have limited functionality compared to volumes, which offer better performance, portability, and security, making them more suitable for production environments. However, bind mounts allow direct access and modification of files on the host system, ideal for development and testing where real-time changes are needed.

Data bind mounts rely on the host machine’s filesystem to persist Elasticsearch data across container restarts. The data bind mount is mounted at the C:\Elasticsearch\Data on Windows (or /Elasticsearch/Data on Unix) path on the host machine in the Elasticsearch container. For more information on data bind mounts, see Docker docs: Bind mounts.

Add Elasticsearch resource with parameters

When you want to explicitly provide the password used by the container image, you can pass it as a parameter:

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var password = builder.AddParameter("password", secret: true);

var elasticsearch = builder.AddElasticsearch("elasticsearch", password: password);

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(elasticsearch);

// After adding all resources, run the app...

TypeScript

The TypeScript AppHost doesn’t currently expose an addElasticsearch(...) API. Password parameters are not available for Elasticsearch in TypeScript AppHosts.

When no password parameter is provided, Aspire generates a strong password automatically. For more information on providing parameters, see External parameters.

Connect to an existing Elasticsearch instance

In C#, call AsExisting instead of AddElasticsearch to reference an externally managed Elasticsearch instance:

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var elasticsearch = builder.AddElasticsearch("elasticsearch")
    .AsExisting(connectionStringParameter: builder.AddParameter("elasticsearch-cs", secret: true));

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(elasticsearch);

// After adding all resources, run the app...

TypeScript

The TypeScript AppHost doesn’t currently expose an addElasticsearch(...) API. To connect to an existing Elasticsearch instance from a TypeScript AppHost, use builder.addConnectionString(...) with a parameter and reference that connection string from your consuming apps instead.

Connection properties

For the full reference of Elasticsearch connection properties — and how consuming apps in C#, TypeScript, Python, and Go read them — see Connect to Elasticsearch.

Hosting integration health checks

The Elasticsearch hosting integration automatically adds a health check for the Elasticsearch resource. The health check verifies that the Elasticsearch instance is running and that a connection can be established to it.

The hosting integration relies on the 📦 AspNetCore.HealthChecks.Elasticsearch NuGet package.