Secret

This page covers building custom secrets providers. If you only need to configure secret resolution for a deployment, use Providers > Secret.

Secrets providers resolve named secrets at server startup. When the Gestalt config references a structured secret ref, the secrets provider fetches the value from whatever backend it wraps (a cloud key vault, a file on disk, an environment variable, etc.) and injects it into the config before any other component starts.

The built-in env and file providers cover local development. For production deployments that store secrets in a cloud vault, use an external secrets provider.

The examples on this page use a Google Secret Manager provider as the running example.

Manifest

A secrets provider manifest declares kind: secrets:


kind: secrets
source: github.com/your-org/secrets/google
version: 0.0.1
displayName: Google Secret Manager
description: Resolves secrets from Google Cloud Secret Manager.
spec:
  configSchemaPath: ./secrets_config.json

The optional spec.configSchemaPath field points to a JSON Schema that validates the config block in the server config.

Interface

A secrets provider implements two methods: Configure and GetSecret. Configure receives the provider name and the raw config map. GetSecret receives a secret name and returns the resolved value as a string.

Go


package googlesecrets
 
import (
	"context"
	"fmt"
 
	secretmanager "cloud.google.com/go/secretmanager/apiv1"
	"cloud.google.com/go/secretmanager/apiv1/secretmanagerpb"
)
 
type GoogleSecrets struct {
	client  *secretmanager.Client
	project string
	version string
}
 
func New() *GoogleSecrets { return &GoogleSecrets{} }
 
func (s *GoogleSecrets) Configure(ctx context.Context, _ string, config map[string]any) error {
	s.project, _ = config["project"].(string)
	if s.project == "" {
		return fmt.Errorf("project is required")
	}
	s.version, _ = config["version"].(string)
	if s.version == "" {
		s.version = "latest"
	}
	var err error
	s.client, err = secretmanager.NewClient(ctx)
	return err
}
 
func (s *GoogleSecrets) GetSecret(ctx context.Context, name string) (string, error) {
	resp, err := s.client.AccessSecretVersion(ctx, &secretmanagerpb.AccessSecretVersionRequest{
		Name: fmt.Sprintf("projects/%s/secrets/%s/versions/%s", s.project, name, s.version),
	})
	if err != nil {
		return "", err
	}
	return string(resp.Payload.Data), nil
}

Python


from google.cloud import secretmanager
import gestalt
 
class GoogleSecrets(gestalt.SecretsProvider):
    def configure(self, name: str, config: dict) -> None:
        self.project = config["project"]
        self.version = config.get("version", "latest")
        self.client = secretmanager.SecretManagerServiceClient()
 
    def get_secret(self, name: str) -> str:
        resource = f"projects/{self.project}/secrets/{name}/versions/{self.version}"
        response = self.client.access_secret_version(request={"name": resource})
        return response.payload.data.decode("utf-8")

Rust


use std::sync::Mutex;
use gestalt::SecretsProvider;
 
pub struct GoogleSecrets {
    project: Mutex<String>,
    version: Mutex<String>,
}
 
#[gestalt::async_trait]
impl SecretsProvider for GoogleSecrets {
    async fn configure(
        &self, _name: &str, config: serde_json::Map<String, serde_json::Value>,
    ) -> gestalt::Result<()> {
        *self.project.lock().unwrap() = config
            .get("project").and_then(|v| v.as_str())
            .ok_or_else(|| gestalt::Error::config("project is required"))?
            .to_string();
        *self.version.lock().unwrap() = config
            .get("version").and_then(|v| v.as_str())
            .unwrap_or("latest").to_string();
        Ok(())
    }
 
    async fn get_secret(&self, name: &str) -> gestalt::Result<String> {
        let project = self.project.lock().unwrap().clone();
        let version = self.version.lock().unwrap().clone();
        // Call Secret Manager API with projects/{project}/secrets/{name}/versions/{version}
        todo!()
    }
}
 
gestalt::export_secrets_provider!(constructor = GoogleSecrets::default);

TypeScript


import { SecretManagerServiceClient } from "@google-cloud/secret-manager";
import { defineSecretsProvider } from "@valon-technologies/gestalt";
 
let client: SecretManagerServiceClient;
let project = "";
let version = "latest";
 
export const provider = defineSecretsProvider({
  configure(_name, config) {
    project = config.project as string;
    if (!project) throw new Error("project is required");
    version = (config.version as string) ?? "latest";
    client = new SecretManagerServiceClient();
  },
  async getSecret(name) {
    const [resp] = await client.accessSecretVersion({
      name: `projects/${project}/secrets/${name}/versions/${version}`,
    });
    return resp.payload?.data?.toString() ?? "";
  },
});

Config reference

To use a secrets provider in a Gestalt deployment, reference it as a named entry in the providers.secrets block:


providers:
  secrets:
    google:
      source: ./google-secrets/manifest.yaml
      config:
        project: my-gcp-project

source: ./manifest.yaml points at the provider’s manifest.yaml during development. For production, use a published provider-release.yaml metadata URL:


providers:
  secrets:
    google:
      source: https://artifacts.example.com/secrets/google/v0.0.1/provider-release.yaml
      config:
        project: my-gcp-project

The config block is passed to Configure at startup.

Built-in providers

Two simple providers are built in and do not require a plugin manifest:

env resolves secrets from environment variables. Secret names are uppercased with hyphens converted to underscores. An optional prefix is prepended.


providers:
  secrets:
    default:
      source: env
      config:
        prefix: GESTALT_

file reads secrets from files in a directory. Each secret name maps to a file in the configured directory.


providers:
  secrets:
    default:
      source: file
      config:
        dir: /run/secrets

Available providers

Provider	Source ref	Description
AWS Secrets Manager	`github.com/valon-technologies/gestalt-providers/secrets/aws`	Config: `region` (required), `versionStage`, `endpoint`
Azure Key Vault	`github.com/valon-technologies/gestalt-providers/secrets/azure`	Config: `vaultUrl` (required), `version`
Google Secret Manager	`github.com/valon-technologies/gestalt-providers/secrets/google`	Config: `project` (required), `version`
HashiCorp Vault	`github.com/valon-technologies/gestalt-providers/secrets/vault`	Config: `address` (required), `token` (required), `mountPath`, `namespace`