GCP Secret Manager Emulator

Lightweight gRPC emulator for Google Cloud Secret Manager API

A standalone gRPC server that implements the Google Cloud Secret Manager API for local testing and CI/CD environments. No GCP credentials or internet connectivity required.

Features

• Full gRPC API Implementation - Complete Secret Manager v1 API
• No GCP Credentials - Works entirely offline without authentication
• Fast & Lightweight - In-memory storage, starts in milliseconds
• Docker Support - Pre-built container for easy deployment
• Thread-Safe - Concurrent access with proper synchronization
• Real SDK Compatible - Works with official cloud.google.com/go/secretmanager client
• High Test Coverage - 87% coverage with comprehensive integration tests

Supported Operations

Secrets

• CreateSecret - Create new secrets with labels
• GetSecret - Retrieve secret metadata
• ListSecrets - List all secrets with pagination
• DeleteSecret - Remove secrets

Secret Versions

• AddSecretVersion - Add new version with payload
• GetSecretVersion - Retrieve version metadata
• AccessSecretVersion - Retrieve version payload

Unimplemented Operations

The following operations return Unimplemented errors. See API Reference for workarounds.

Not Yet Implemented

• UpdateSecret - Modify secret metadata (labels, annotations)
• ListSecretVersions - List all versions for a secret
• EnableSecretVersion / DisableSecretVersion - State management
• DestroySecretVersion - Permanently destroy a version
• IAM methods (SetIamPolicy, GetIamPolicy, TestIamPermissions)

Rationale: These operations are rarely needed for local testing and CI/CD workflows. The emulator focuses on core secret storage and retrieval operations.

Quick Start

Install

go install github.com/blackwell-systems/gcp-secret-manager-emulator/cmd/server@latest

Run Server

# Start on default port 9090
server

# Custom port
server --port 8080

# With debug logging
server --log-level debug

Use with GCP SDK

package main

import (
    "context"
    "fmt"

    secretmanager "cloud.google.com/go/secretmanager/apiv1"
    "google.golang.org/api/option"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
)

func main() {
    ctx := context.Background()

    // Connect to emulator instead of real GCP
    conn, _ := grpc.NewClient(
        "localhost:9090",
        grpc.WithTransportCredentials(insecure.NewCredentials()),
    )

    client, _ := secretmanager.NewClient(ctx, option.WithGRPCConn(conn))
    defer client.Close()

    // Use client normally - API is identical to real GCP
    // ...
}

Docker

# Build
docker build -t gcp-secret-manager-emulator .

# Run
docker run -p 9090:9090 gcp-secret-manager-emulator

# In CI/CD
services:
  gcp-emulator:
    image: gcp-secret-manager-emulator:latest
    ports:
      - "9090:9090"

Use Cases

• Local Development - Test GCP Secret Manager integration without cloud access
• CI/CD Pipelines - Fast integration tests without GCP credentials
• Unit Testing - Deterministic test environment
• Demos & Prototyping - Showcase GCP integrations offline
• Cost Reduction - Avoid GCP API charges during development

Configuration

Environment Variables

Variable	Default	Description
GCP_MOCK_PORT	9090	Port to listen on
GCP_MOCK_LOG_LEVEL	info	Log level: debug, info, warn, error

Command Line Flags

server --help

Flags:
  --port int           Port to listen on (default 9090)
  --log-level string   Log level (default "info")

Documentation

📚 View Full Documentation

• API Reference - Complete API documentation with examples
• Architecture Guide - System design, components, and diagrams

Testing

# Run all tests
go test ./...

# With coverage
go test -cover ./...

# With race detector
go test -race ./...

Differences from Real GCP

Intentional Simplifications:

• No authentication/authorization (all requests succeed)
• No IAM permissions or resource policies
• No encryption at rest (in-memory storage)
• No replication or regional constraints
• Simplified error responses (no retry-after headers)

Perfect for:

• Development and testing workflows
• CI/CD environments
• Local integration testing

Not for:

• Production use
• Security testing
• Performance benchmarking

Project Status

Extracted from vaultmux where it powers GCP backend integration tests. Used in production CI pipelines.

Disclaimer

This project is not affiliated with, endorsed by, or sponsored by Google LLC or Google Cloud Platform. "Google Cloud", "Secret Manager", and related trademarks are property of Google LLC. This is an independent open-source implementation for testing and development purposes.

License

Apache License 2.0 - See LICENSE for details.