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 ¶
const ( KindKubernetes = "kubernetes" KindSSH = "ssh" KindWebhook = "webhook" )
Target kinds.
Variables ¶
This section is empty.
Functions ¶
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.
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.
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.
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.
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.