deploy

package
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 5, 2026 License: AGPL-3.0 Imports: 18 Imported by: 0

Documentation

Overview

Package deploy pushes a renewed certificate to where it is actually used.

Auto-renewal without this is half a feature: it produces a new certificate on a schedule and leaves somebody to copy it onto a server by hand, which is the step that gets forgotten and the reason the certificate expired in the first place. A deployment target closes the loop — renewal writes the new material to the Kubernetes Secret, the load balancer or the webhook that consumes it, and reloads whatever needs reloading.

Targets are best-effort in the same way notifications are: a target that is down must never turn a successful renewal into a failed one. Failures are recorded on the target row and retried on the next pass.

Index

Constants

View Source
const (
	KindKubernetes = "kubernetes"
	KindSSH        = "ssh"
	KindWebhook    = "webhook"
)

Target kinds.

Variables

This section is empty.

Functions

func Kinds

func Kinds() []string

Kinds lists every target kind, for the settings UI.

Types

type Bundle

type Bundle struct {
	CommonName   string
	SerialNumber string
	NotAfter     time.Time

	CertificatePEM []byte
	// ChainPEM is the issuers above the leaf; FullchainPEM is the leaf
	// followed by those issuers, which is what most servers want in one file.
	ChainPEM      []byte
	FullchainPEM  []byte
	RootPEM       []byte
	PrivateKeyPEM []byte
}

Bundle is the material a target writes out. Not every target uses every field: a webhook receives all of it, an SSH target writes only the paths it was configured with.

func (Bundle) HasKey

func (b Bundle) HasKey() bool

HasKey reports whether the bundle carries private key material. A BYO-CSR certificate has none, and a target that needs one has to say so rather than write an empty file over a working key.

type Kubernetes

type Kubernetes struct {
	// APIURL is the API server, e.g. https://10.0.0.1:6443. Inside a cluster
	// this is https://kubernetes.default.svc.
	APIURL string
	// Token is a ServiceAccount token.
	Token      string
	Namespace  string
	SecretName string
	// CABundlePEM verifies the API server. In a cluster this is the contents
	// of /var/run/secrets/kubernetes.io/serviceaccount/ca.crt.
	CABundlePEM string
	// InsecureSkipVerify disables that verification. It exists because a
	// freshly bootstrapped cluster may be presenting a certificate this very
	// instance has not yet issued.
	InsecureSkipVerify bool
	// Annotations and Labels are written onto the Secret, which is how a
	// reloader controller is told to restart the pods that mount it.
	Annotations map[string]string
	Labels      map[string]string
}

Kubernetes writes the certificate into a `kubernetes.io/tls` Secret.

It talks to the API server directly rather than shelling out to kubectl: Certio is a single static binary and adding a kubectl dependency to a container image would be a much larger change than one HTTP call. The token needs only get/create/update on secrets in the one namespace — a Role that narrow is worth writing out rather than reaching for cluster-admin.

func (*Kubernetes) Deploy

func (k *Kubernetes) Deploy(ctx context.Context, bundle Bundle) error

Deploy creates or replaces the Secret.

func (*Kubernetes) Describe

func (k *Kubernetes) Describe() string

Describe summarises the target without naming the token.

func (*Kubernetes) Kind

func (k *Kubernetes) Kind() string

Kind identifies the target type.

type SSH

type SSH struct {
	Host string
	Port int
	User string
	// PrivateKeyPEM authenticates to the host. Password is the fallback for
	// an appliance that allows nothing else.
	PrivateKeyPEM string
	Passphrase    string
	Password      string

	// HostKey is the expected public key, in authorized_keys form. Deploying
	// a private key to a host whose identity was never checked would hand it
	// to whoever answers the address.
	HostKey string
	// InsecureIgnoreHostKey disables that check. It is a deliberate opt-in and
	// it is named to be unpleasant to type.
	InsecureIgnoreHostKey bool

	// Paths to write. An empty path is skipped, so a target can deploy the
	// fullchain alone if that is all the server reads.
	CertPath      string
	KeyPath       string
	ChainPath     string
	FullchainPath string
	RootPath      string

	// ReloadCommand runs after a successful write, e.g. "systemctl reload nginx".
	ReloadCommand string
	// FileMode is applied to everything except the key, which is always 0600.
	FileMode string
}

SSH writes the certificate onto a server over SSH and runs a reload command.

Files are written by piping into `cat` inside a shell that has already set a restrictive umask, rather than over SFTP: it needs no subsystem enabled on the far end, and it keeps the private key from existing world-readable even momentarily. The write goes to a temporary file and is then moved into place, so a server reading the file during the copy never sees half of one.

func (*SSH) Deploy

func (s *SSH) Deploy(ctx context.Context, bundle Bundle) error

Deploy copies the bundle and reloads the service.

func (*SSH) Describe

func (s *SSH) Describe() string

Describe summarises the target without naming any credential.

func (*SSH) Kind

func (s *SSH) Kind() string

Kind identifies the target type.

type Target

type Target interface {
	Deploy(ctx context.Context, bundle Bundle) error
	Kind() string
	// Describe is the one-line summary shown in the UI and the audit log. It
	// must never include a secret.
	Describe() string
}

Target delivers a bundle to one destination.

func Build

func Build(kind string, config map[string]string) (Target, error)

Build constructs a Target from a kind and its decrypted settings.

type Webhook

type Webhook struct {
	URL     string
	Secret  string
	Headers map[string]string
	// IncludeKey controls whether the private key is sent at all. A receiver
	// that only needs to know a renewal happened should not be handed one.
	IncludeKey bool
}

Webhook posts the renewed material to an endpoint that knows what to do with it — the escape hatch for every deployment Certio does not model natively.

The body is signed with HMAC-SHA256 over the exact bytes sent, so a receiver about to install a private key can verify it came from Certio and not from whoever else can reach the URL. Verifying that signature is the difference between a deployment hook and a way to have arbitrary key material installed on your servers.

func (*Webhook) Deploy

func (w *Webhook) Deploy(ctx context.Context, bundle Bundle) error

Deploy posts the bundle.

func (*Webhook) Describe

func (w *Webhook) Describe() string

Describe summarises the target without naming the secret.

func (*Webhook) Kind

func (w *Webhook) Kind() string

Kind identifies the target type.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL