Indiko.Blocks.Configuration.Consul 2.7.6

Indiko.Blocks.Configuration.Consul

Configuration block for loading application settings from HashiCorp Consul Key-Value store in distributed microservices environments.

Overview

This package provides a configuration block that loads settings from Consul KV store, enabling centralized configuration management for distributed applications. It supports dynamic configuration updates and service-specific configuration paths.

Features

• Consul KV Integration: Load configuration from Consul Key-Value store
• Service-Specific Config: Configuration paths scoped by service ID
• JSON Configuration: Store configuration as JSON in Consul
• Dynamic Updates: Support for configuration changes without restart
• Early Loading: Loads before other blocks (BlockLoadOrder -1)
• IConfiguration Integration: Seamlessly integrates with ASP.NET Core configuration
• Fallback Support: Gracefully handles missing configuration keys

Installation

dotnet add package Indiko.Blocks.Configuration.Consul

Quick Start

Configuration (appsettings.json)

{
  "ConsulConfigurationStore": {
    "ServiceId": "my-service",
    "ConfigurationPath": "appsettings",
    "ConsulAddress": "http://consul:8500"
  }
}

Enable in Your Application

The Consul configuration block is typically auto-discovered and loaded. Ensure the ConsulConfigurationStore section is configured.

Store Configuration in Consul

Store your configuration as JSON in Consul under the key: {ServiceId}/{ConfigurationPath}

Example: my-service/appsettings

{
  "Database": {
    "ConnectionString": "Server=db-server;Database=mydb",
    "MaxRetryCount": 3
  },
  "ApiSettings": {
    "Endpoint": "https://api.example.com",
    "Timeout": 30
  },
  "FeatureFlags": {
    "EnableNewUI": true,
    "EnableBetaFeatures": false
  }
}

Using Consul CLI

# Write configuration to Consul
consul kv put my-service/appsettings @appsettings.json

# Read configuration
consul kv get my-service/appsettings

# Update a specific value
consul kv put my-service/appsettings '{"Database":{"ConnectionString":"..."}}'

Usage Examples

Accessing Configuration

using Microsoft.Extensions.Configuration;

public class MyService
{
    private readonly IConfiguration _configuration;

    public MyService(IConfiguration configuration)
    {
        _configuration = configuration;
    }

    public void Connect()
    {
        var connectionString = _configuration["Database:ConnectionString"];
        var maxRetries = _configuration.GetValue<int>("Database:MaxRetryCount");
    }
}

Type-Safe Configuration

// Define settings class
public class DatabaseSettings
{
    public string ConnectionString { get; set; }
    public int MaxRetryCount { get; set; }
}

public class ApiSettings
{
    public string Endpoint { get; set; }
    public int Timeout { get; set; }
}

// Register in ConfigureServices
services.Configure<DatabaseSettings>(Configuration.GetSection("Database"));
services.Configure<ApiSettings>(Configuration.GetSection("ApiSettings"));

// Inject and use
public class MyService
{
    private readonly DatabaseSettings _dbSettings;
    private readonly ApiSettings _apiSettings;

    public MyService(
        IOptions<DatabaseSettings> dbOptions,
        IOptions<ApiSettings> apiOptions)
    {
        _dbSettings = dbOptions.Value;
        _apiSettings = apiOptions.Value;
    }
}

Explicit Service Registration

using Indiko.Blocks.Configuration.Consul.Extensions;

public override void ConfigureServices(IServiceCollection services)
{
    // Explicitly use Consul configuration
    services.UseConsulConfiguration();
    
    base.ConfigureServices(services);
}

Key Components

ConsulSettingsConfigurationBlock

The main configuration block implementation.

[BlockLoadOrder(-1)]
public sealed class ConsulSettingsConfigurationBlock : BlockBase, IConsulSettingsConfigurationBlock
{
    public override void ConfigureServices(IServiceCollection services)
    {
        services.UseConsulConfiguration();
        base.ConfigureServices(services);
    }
}

ConsulConfigurationProvider

Provider that loads configuration from Consul KV store.

public sealed class ConsulConfigurationProvider : ConfigurationProvider
{
    public override void Load()
    {
        // Load from Consul: {ServiceId}/{ConfigurationPath}
    }
}

ConsulConfigurationSource

Configuration source for Consul integration.

public class ConsulConfigurationSource : IConfigurationSource
{
    public IConfigurationProvider Build(IConfigurationBuilder builder)
    {
        return new ConsulConfigurationProvider(serviceId, configurationPath, consulClient);
    }
}

Configuration Options

ConsulConfigurationStoreOptions

public class ConsulConfigurationStoreOptions
{
    // Service identifier used as base path in Consul KV
    public string ServiceId { get; set; }
    
    // Configuration file name/path (e.g., "appsettings")
    public string ConfigurationPath { get; set; }
    
    // Consul server address (e.g., "http://consul:8500")
    public string ConsulAddress { get; set; }
}

Full Configuration Example

{
  "ConsulConfigurationStore": {
    "ServiceId": "user-service",
    "ConfigurationPath": "appsettings",
    "ConsulAddress": "http://localhost:8500"
  }
}

Advanced Scenarios

Environment-Specific Configuration

Store different configurations per environment:

# Development
consul kv put user-service/appsettings.development @appsettings.dev.json

# Production
consul kv put user-service/appsettings.production @appsettings.prod.json

Configure the path based on environment:

{
  "ConsulConfigurationStore": {
    "ServiceId": "user-service",
    "ConfigurationPath": "appsettings.production",
    "ConsulAddress": "http://consul:8500"
  }
}

Multiple Configuration Paths

Load configuration from multiple Consul paths:

var builder = new ConfigurationBuilder();

// Load shared configuration
builder.AddConsul("shared/database", options =>
{
    options.ConsulAddress = "http://consul:8500";
});

// Load service-specific configuration
builder.AddConsul("user-service/appsettings", options =>
{
    options.ConsulAddress = "http://consul:8500";
});

var configuration = builder.Build();

Hierarchical Configuration

Organize configuration hierarchically in Consul:

shared/
  database
  cache
  logging
user-service/
  appsettings
  features
order-service/
  appsettings
  features

Configuration Watching and Reload

Monitor Consul for configuration changes:

public class MyService
{
    private readonly IOptionsMonitor<DatabaseSettings> _settings;

    public MyService(IOptionsMonitor<DatabaseSettings> settings)
    {
        _settings = settings;
        
        // React to configuration changes
        _settings.OnChange(newSettings =>
        {
            Console.WriteLine("Database configuration changed!");
            ReconfigureDatabase(newSettings);
        });
    }

    private void ReconfigureDatabase(DatabaseSettings settings)
    {
        // Update database connection pool, etc.
    }
}

Deployment Patterns

Docker Compose

version: '3.8'
services:
  consul:
    image: consul:latest
    ports:
      - "8500:8500"
    volumes:
      - consul-data:/consul/data

  my-service:
    build: .
    environment:
      - ConsulConfigurationStore__ConsulAddress=http://consul:8500
    depends_on:
      - consul

volumes:
  consul-data:

Kubernetes

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  appsettings.json: |
    {
      "ConsulConfigurationStore": {
        "ServiceId": "user-service",
        "ConfigurationPath": "appsettings",
        "ConsulAddress": "http://consul.default.svc.cluster.local:8500"
      }
    }

Benefits

1. Centralized Management: Single source of truth for configuration
2. Dynamic Updates: Change configuration without redeploying
3. Service Discovery: Integrates with Consul service mesh
4. Version Control: Consul KV supports versioning
5. Access Control: Consul ACL for secure configuration
6. Audit Trail: Track configuration changes

Error Handling

The provider gracefully handles missing keys:

// Returns null if key doesn't exist
var value = Configuration["NonExistent:Key"];

// Use GetValue with default
var timeout = Configuration.GetValue<int>("Api:Timeout", 30);

Target Framework

• .NET 10

Dependencies

• Indiko.Blocks.Configuration.Abstractions
• Indiko.Blocks.Common.Abstractions
• Consul
• Microsoft.Extensions.Configuration

License

See LICENSE file in the repository root.

Related Packages

• Indiko.Blocks.Configuration.Abstractions - Configuration abstractions
• Indiko.Blocks.Configuration.AppSettings - AppSettings-based configuration
• Indiko.Blocks.Communication.ServiceToService.Consul - Consul service discovery
• Indiko.Blocks.Common.Management - Block management system

Resources

• Consul Documentation
• Consul KV Store