Elasticsearch integration

Elasticsearch is a distributed, RESTful search and analytics engine, scalable data store, and vector database capable of addressing a growing number of use cases. The Elasticsearch integration enables you to connect to existing Elasticsearch instances, or create new instances from Aspire with the docker.io/library/elasticsearch container image.

Hosting integration

The Elasticsearch hosting integration models an Elasticsearch instance as the ElasticsearchResource type. To access this type and APIs, add the 📦 Aspire.Hosting.Elasticsearch NuGet package in your AppHost project:

Aspire CLI

Aspire CLI — Add Aspire.Hosting.Elasticsearch package

aspire add elasticsearch

The Aspire CLI is interactive, be sure to select the appropriate search result when prompted:

Aspire CLI — Example output prompt

Select an integration to add:

> elasticsearch (Aspire.Hosting.Elasticsearch)
> Other results listed as selectable options...

Note

If there's only one result, the CLI selects it automatically. You'll still need to confirm the version.

apphost.cs (C# file-based app)

C# — AppHost.cs

#:package Aspire.Hosting.Elasticsearch@*

PackageReference (*.csproj)

XML — Add Aspire.Hosting.Elasticsearch package reference

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

Add Elasticsearch resource

In your AppHost project, call AddElasticsearch on the builder instance to add an Elasticsearch resource:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

var myService = builder.AddProject<Projects.ExampleProject>()
                       .WithReference(elasticsearch);

When Aspire adds a container image to the AppHost, it creates a new Elasticsearch instance on your local machine. The Elasticsearch resource includes default credentials with a username of "elastic" and a randomly generated password.

Tip

If you’d rather connect to an existing Elasticsearch instance, call AddConnectionString instead. For more information, see Reference existing resources.

Add Elasticsearch resource with data volume

To add a data volume to the Elasticsearch resource, call the WithDataVolume method on the Elasticsearch resource:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

var myService = builder.AddProject<Projects.ExampleProject>()
                       .WithReference(elasticsearch);

The data volume is used to persist the 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

To add a data bind mount to the Elasticsearch resource, call the WithDataBindMount method:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

var myService = builder.AddProject<Projects.ExampleProject>()
                       .WithReference(elasticsearch);

Note

Data bind mounts have limited functionality compared to volumes, and when you use a bind mount, a file or directory on the host machine is mounted into a container.

Data bind mounts rely on the host machine’s filesystem to persist the Elasticsearch data across container restarts. For more information on data bind mounts, see Docker docs: Bind mounts.

Add Elasticsearch resource with password parameter

When you want to explicitly provide the password used by the container image, you can provide these credentials as parameters:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

var myService = builder.AddProject<Projects.ExampleProject>()
                       .WithReference(elasticsearch);

For more information on providing parameters, see External parameters.

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.

Client integration

To get started with the Aspire Elasticsearch client integration, install the 📦 Aspire.Elastic.Clients.Elasticsearch NuGet package:

.NET CLI

.NET CLI — Add Aspire.Elastic.Clients.Elasticsearch package

dotnet add package Aspire.Elastic.Clients.Elasticsearch

Program.cs (C# file-based app)

Program.cs

#:package Aspire.Elastic.Clients.Elasticsearch@*

PackageReference (*.csproj)

XML — Add Aspire.Elastic.Clients.Elasticsearch package reference

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

The Elasticsearch client integration registers an ElasticsearchClient instance that you can use to interact with Elasticsearch.

Add Elasticsearch client

In the Program.cs file of your client-consuming project, call the AddElasticsearchClient extension method to register an ElasticsearchClient for use via the dependency injection container:

builder.AddElasticsearchClient(connectionName: "elasticsearch");

Tip

The connectionName parameter must match the name used when adding the Elasticsearch resource in the AppHost project.

You can then retrieve the ElasticsearchClient instance using dependency injection. For example, to retrieve the connection from an example service:

public class ExampleService(ElasticsearchClient client)
{
    // Use client...
}

Add keyed Elasticsearch client

There might be situations where you want to register multiple ElasticsearchClient instances with different connection names. To register keyed Elasticsearch clients, call the AddKeyedElasticsearchClient method:

builder.AddKeyedElasticsearchClient(name: "products");
builder.AddKeyedElasticsearchClient(name: "orders");

Then you can retrieve the ElasticsearchClient instances using dependency injection:

public class ExampleService(
    [FromKeyedServices("products")] ElasticsearchClient productsClient,
    [FromKeyedServices("orders")] ElasticsearchClient ordersClient)
{
    // Use clients...
}

For more information on keyed services, see .NET dependency injection: Keyed services.

Configuration

The Elasticsearch integration provides multiple options to configure the server connection based on the requirements and conventions of your project.

Use a connection string

When using a connection string from the ConnectionStrings configuration section, you can provide the name of the connection string when calling AddElasticsearchClient:

builder.AddElasticsearchClient("elasticsearch");

Then the connection string will be retrieved from the ConnectionStrings configuration section:

{
  "ConnectionStrings": {
    "elasticsearch": "http://elastic:password@localhost:27011"
  }
}

Use configuration providers

The Elasticsearch integration supports Microsoft.Extensions.Configuration. It loads the ElasticClientsElasticsearchSettings from configuration using the Aspire:Elastic:Clients:Elasticsearch key. Example appsettings.json:

{
  "Aspire": {
    "Elastic": {
      "Clients": {
        "Elasticsearch": {
          "DisableHealthChecks": false,
          "DisableTracing": false,
          "HealthCheckTimeout": "00:00:03",
          "ApiKey": "<Valid ApiKey>",
          "Endpoint": "http://elastic:password@localhost:27011",
          "CloudId": "<Valid CloudId>"
        }
      }
    }
  }
}

Use inline delegates

You can pass the Action<ElasticClientsElasticsearchSettings> delegate to set up options inline:

builder.AddElasticsearchClient(
    "elasticsearch",
    static settings =>
        settings.Endpoint = new Uri("http://elastic:password@localhost:27011"));

Use CloudId and ApiKey with configuration providers

When using Elastic Cloud, you can provide the CloudId and ApiKey in the configuration:

builder.AddElasticsearchClient("elasticsearch");

Example appsettings.json:

{
  "Aspire": {
    "Elastic": {
      "Clients": {
        "Elasticsearch": {
          "ApiKey": "<Valid ApiKey>",
          "CloudId": "<Valid CloudId>"
        }
      }
    }
  }
}

Use CloudId and ApiKey with inline delegates

builder.AddElasticsearchClient(
    "elasticsearch",
    static settings =>
    {
        settings.ApiKey = "<Valid ApiKey>";
        settings.CloudId = "<Valid CloudId>";
    });

Client integration health checks

By default, Aspire integrations enable health checks for all services. The Elasticsearch integration uses the configured client to perform a PingAsync. If the result is an HTTP 200 OK, the health check is considered healthy, otherwise it’s unhealthy.

Observability and telemetry

Tracing

The Elasticsearch integration will emit the following tracing activities using OpenTelemetry:

• Elastic.Transport