Cryptyx.Gcp.Secrets.Extensions 0.1.1

Cryptyx.Gcp.Secrets.Extensions

Enterprise-grade Microsoft.Extensions.Configuration provider for Google Cloud Secret Manager.

Features

Installation

dotnet add package Cryptyx.Gcp.Secrets.Extensions

Quick Start

Minimal — Application Default Credentials (ADC)

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddGcpSecretManager("my-gcp-project-id");

var app = builder.Build();

// Secrets are now available via Configuration
var connectionString = app.Configuration["Database:ConnectionString"];

Workload Identity Federation (GKE / Cloud Run)

No code changes needed — Workload Identity is handled automatically by Application Default Credentials when running on GKE or Cloud Run with Workload Identity configured:

// Works automatically on GKE with Workload Identity, Cloud Run, or GCE
builder.Configuration.AddGcpSecretManager("my-gcp-project-id");

Service Account JSON Key File

builder.Configuration.AddGcpSecretManager(
    "my-gcp-project-id",
    jsonCredentialPath: "/secrets/service-account.json");

Pre-configured Client

var client = new SecretManagerServiceClientBuilder
{
    JsonCredentials = Environment.GetEnvironmentVariable("GCP_CREDENTIALS_JSON")
}.Build();

builder.Configuration.AddGcpSecretManager("my-gcp-project-id", client);

Prefix Secret Manager (Built-in)

The library ships with PrefixGcpSecretManager — a built-in implementation that filters secrets by a prefix and maps the remaining segments to hierarchical configuration keys using a configurable delimiter (default --):

// Secrets: SERVICEA--DatabaseHost, SERVICEA--Database--Host--Port, SERVICEB--ApiKey
builder.Configuration.AddGcpSecretManager(options =>
{
    options.ProjectId = "my-gcp-project-id";
    options.Manager = new PrefixGcpSecretManager("SERVICEA");
});

// Result:
//   "DatabaseHost"       → config["DatabaseHost"]
//   "Database--Host--Port" → config["Database:Host:Port"]
//   SERVICEB--ApiKey     → skipped (wrong prefix)

Custom delimiter:

options.Manager = new PrefixGcpSecretManager("SERVICEA", "_");
// SERVICEA_KEY_SUBKEY → KEY:SUBKEY

No prefix (delimiter-only mode):

options.Manager = new PrefixGcpSecretManager();
// KEY--SUBKEY--SUBKEY1 → KEY:SUBKEY:SUBKEY1

Custom Secret Manager

Implement IGcpSecretManager to control which secrets are loaded and how they map to configuration keys. This is useful for prefix-based filtering, environment isolation, or any custom key transformation:

public class PrefixSecretManager : IGcpSecretManager
{
    private readonly string _prefix;

    public PrefixSecretManager(string prefix)
        => _prefix = $"{prefix}-";

    public bool Load(Secret secret)
        => secret.SecretName.SecretId.StartsWith(_prefix, StringComparison.OrdinalIgnoreCase);

    public string GetKey(Secret secret)
        => secret.SecretName.SecretId[_prefix.Length..]
            .Replace("__", ConfigurationPath.KeyDelimiter);
}

// Usage:
builder.Configuration.AddGcpSecretManager(options =>
{
    options.ProjectId = "my-gcp-project-id";
    options.Manager = new PrefixSecretManager("MyApp");
});

With secrets named MyApp-Database__Host and MyApp-Database__Port, the above produces configuration keys Database:Host and Database:Port.

Automatic Secret Reload

Periodically poll GCP Secret Manager for updated values. Configuration consumers using IOptionsSnapshot<T> or IOptionsMonitor<T> automatically receive the updated values:

builder.Configuration.AddGcpSecretManager(options =>
{
    options.ProjectId = "my-gcp-project-id";
    options.ReloadInterval = TimeSpan.FromMinutes(5);
});

Note: The minimum reload interval is 30 seconds to prevent excessive API calls and cost overruns. Intervals shorter than 30 seconds are automatically clamped.

GCP Label Filters

Pre-filter secrets server-side using GCP Secret Manager's label filter syntax:

builder.Configuration.AddGcpSecretManager(options =>
{
    options.ProjectId = "my-gcp-project-id";
    options.Filter = "labels.env=production";
});

Full Configuration Example

using Cryptyx.Gcp.Secrets.Extensions;

var builder = WebApplication.CreateBuilder(args);

if (builder.Environment.IsProduction())
{
    builder.Configuration.AddGcpSecretManager(options =>
    {
        options.ProjectId = builder.Configuration["GCP:ProjectId"]!;
        options.ReloadInterval = TimeSpan.FromMinutes(5);
        options.Manager = new PrefixSecretManager("MyApp");
        options.Filter = "labels.env=production";
    });
}

var app = builder.Build();
app.MapGet("/", (IConfiguration config) => $"DB: {config["Database:Host"]}");
app.Run();

Secret Naming Conventions

DefaultGcpSecretManager (double underscore __)

Convention: Use double underscores (__) for hierarchical configuration keys, following the same pattern as environment variable configuration in .NET.

PrefixGcpSecretManager (double dash --)

Authentication Methods

Target Frameworks

• .NET 6.0 (LTS)
• .NET 8.0 (LTS)
• .NET 9.0
• .NET 10.0

Contributing

Contributions are welcome! Please read CONTRIBUTING.md before submitting a pull request.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License — see the LICENSE file for details.

Security

If you discover a security vulnerability, please report it responsibly by emailing security@gcpsecretmanager.dev instead of opening a public issue.