caddy_gcp_secret_manager

README

caddy-gcp-secret-manager

This package provides a module for the Caddy web server to use Google Cloud Platform's Secret Manager product to store TLS certificates.

Features

• Secure retrieval and storage of TLS certificates
• Clustering compatible - locks with TTLs are written to Secret Manager

Usage

Building

To use this module with Caddy, you'll need to create a custom build with xcaddy.

xcaddy build --with github.com/trea/caddy-gcp-secret-manager

Via Docker

You can build this module (and others) into Caddy with xcaddy using Docker. The following example uses a multi-phase build to build the Caddy binary with xcaddy, and then copies your newly built binary over the original binary in the core Caddy image.

FROM caddy:2.6.4-builder AS builder

RUN xcaddy --with github.com/trea/caddy-gcp-secret-manager

FROM caddy:2.6.4

COPY --from=builder /usr/bin/caddy /usr/bin/caddy

Caddyfile Configuration Examples

Application Default Credentials

The Google Cloud Platform Client library used by this package uses Application Default Credentials by default which can automatically configure authentication and authorization.

The following configuration would use Caddy's static file server to serve files in /var/www/html at https://example.com and the TLS certificate will be stored in GCP Secret Manager.

your-project-id should be replaced with the Project ID for your project from your Google Cloud Platform console.

{
    storage gcp-secret-manager your-project-id
}

example.com:443 {
    file_server /var/www/html
}

Specified Credentials

If you need to point to a specific credentials file, you can do so in configuration as well by setting the credentials_file option nested under the storage block.

{
    storage gcp-secret-manager your-project-id {
        credentials_file /mnt/gcp-credentials.json
    }
}

example.com:443 {
    file_server /var/www/html
}

Use with certmagic

Because Caddy's TLS is built on top of certmagic, this package can be used with certmagic directly like so:

package main

import (
	"log"
	"net/http"

	"github.com/caddyserver/certmagic"

	caddy_gcp_secret_manager "github.com/trea/caddy-gcp-secret-manager"
)

func main() {

	storage, err := caddy_gcp_secret_manager.NewSecretManagerStorage("my-gcp-project")

	if err != nil {
		log.Fatalf("Unable to initialize storage: %+v", err)
	}

	// read and agree to your CA's legal documents
	// provide an email address
	// use the staging endpoint while we're developing
	//
	// uncomment and change the values on the following lines as applicable

	//certmagic.DefaultACME.Agreed = true
	//certmagic.DefaultACME.Email = "you@yours.com"
	//certmagic.DefaultACME.CA = certmagic.LetsEncryptStagingCA
	
	certmagic.Default.Storage = storage

	mux := http.NewServeMux()
	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("Hello world!"))
	})

	if err := certmagic.HTTPS([]string{"example.com"}, mux); err != nil {
		log.Fatalf("Unable to start listener: %+v", err)
	}
}

NewSecretManagerStorage also accepts option.ClientOption if you need to alter connection configuration as shown in the client examples.

Documentation

Index

• Variables
• type CaddyGcpSecretManagerStorage
  • func (c CaddyGcpSecretManagerStorage) CaddyModule() caddy.ModuleInfo
  • func (c CaddyGcpSecretManagerStorage) Cleanup() error
  • func (c CaddyGcpSecretManagerStorage) Provision(context caddy.Context) error
  • func (c *CaddyGcpSecretManagerStorage) UnmarshalCaddyfile(d *caddyfile.Dispenser) error
  • func (c CaddyGcpSecretManagerStorage) Validate() error
• type SecretManagerStorage
  • func NewSecretManagerStorage(projectID string, opts ...option.ClientOption) (*SecretManagerStorage, error)
  • func (s SecretManagerStorage) Close() error
  • func (s SecretManagerStorage) Delete(ctx context.Context, key string) error
  • func (s SecretManagerStorage) Exists(ctx context.Context, key string) bool
  • func (s SecretManagerStorage) List(ctx context.Context, prefix string, recursive bool) (list []string, err error)
  • func (s SecretManagerStorage) Load(ctx context.Context, key string) ([]byte, error)
  • func (s *SecretManagerStorage) Lock(ctx context.Context, name string) error
  • func (s SecretManagerStorage) Stat(ctx context.Context, key string) (certmagic.KeyInfo, error)
  • func (s SecretManagerStorage) Store(ctx context.Context, key string, value []byte) error
  • func (s *SecretManagerStorage) Unlock(ctx context.Context, name string) error

Variables

var (
	ErrInvalidJSON     = errors.New("invalid JSON")
	ErrCredentialsFile = errors.New("unable to read credentials file")
)

var ErrKeyNotFound = errors.New("unable to find key")

Types

type CaddyGcpSecretManagerStorage

type CaddyGcpSecretManagerStorage struct {
	Fs              fs.FS
	ProjectID       string
	CredentialsFile string
	// contains filtered or unexported fields
}

func (CaddyGcpSecretManagerStorage) CaddyModule

func (c CaddyGcpSecretManagerStorage) CaddyModule() caddy.ModuleInfo

func (CaddyGcpSecretManagerStorage) Cleanup

func (c CaddyGcpSecretManagerStorage) Cleanup() error

func (CaddyGcpSecretManagerStorage) Provision

func (c CaddyGcpSecretManagerStorage) Provision(context caddy.Context) error

func (*CaddyGcpSecretManagerStorage) UnmarshalCaddyfile

func (c *CaddyGcpSecretManagerStorage) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

func (CaddyGcpSecretManagerStorage) Validate

func (c CaddyGcpSecretManagerStorage) Validate() error

type SecretManagerStorage

type SecretManagerStorage struct {
	// contains filtered or unexported fields
}

func NewSecretManagerStorage

func NewSecretManagerStorage(projectID string, opts ...option.ClientOption) (*SecretManagerStorage, error)

func (SecretManagerStorage) Close

func (s SecretManagerStorage) Close() error

func (SecretManagerStorage) Delete

func (s SecretManagerStorage) Delete(ctx context.Context, key string) error

func (SecretManagerStorage) Exists

func (s SecretManagerStorage) Exists(ctx context.Context, key string) bool

func (SecretManagerStorage) List

func (s SecretManagerStorage) List(ctx context.Context, prefix string, recursive bool) (list []string, err error)

func (SecretManagerStorage) Load

func (s SecretManagerStorage) Load(ctx context.Context, key string) ([]byte, error)

func (*SecretManagerStorage) Lock

func (s *SecretManagerStorage) Lock(ctx context.Context, name string) error

func (SecretManagerStorage) Stat

func (s SecretManagerStorage) Stat(ctx context.Context, key string) (certmagic.KeyInfo, error)

func (SecretManagerStorage) Store

func (s SecretManagerStorage) Store(ctx context.Context, key string, value []byte) error

func (*SecretManagerStorage) Unlock

func (s *SecretManagerStorage) Unlock(ctx context.Context, name string) error