Documentation
¶
Overview ¶
Package caddy holds the parts of SC's Caddy configuration that both edges render.
SC runs Caddy in two places — a container on a vm resource's machines (pkg/clouds/vm) and a Deployment in front of a Kubernetes cluster (pkg/clouds/pulumi/kubernetes) — and they are configured by different structs. That is fine for anything genuinely path-specific, and a liability for anything whose correctness lives in Caddy or in a Caddy module, because then the knowledge has to be right twice. The shared ACME store was the first case where it was right once: the vm path had `ingress.acmeStorage` and the Kubernetes path's only route to the same feature was hand-writing the block into `caddyfilePrefix`, with the module's two silent parser rules to rediscover and the credentials in cleartext.
Put a thing here when getting it wrong would be invisible until a certificate fails to renew.
Index ¶
Constants ¶
const ( // The three credential env vars. Rendered into a Caddyfile as `{$NAME}` // placeholders and resolved by Caddy's own parser at config-load time, so the // value is never in the generated file: on the vm path they arrive in a 0600 env // file, on the Kubernetes path in a Secret. EnvAcmeS3AccessKey = "SC_ACME_S3_ACCESS_KEY" EnvAcmeS3SecretKey = "SC_ACME_S3_SECRET_KEY" EnvAcmeS3EncryptionKey = "SC_ACME_S3_ENCRYPTION_KEY" // DefaultAcmeStoragePrefix matches certmagic-s3's own default. Named here because // it is rendered explicitly — a generated Caddyfile that says where the // certificates are beats one that leaves it to the module. DefaultAcmeStoragePrefix = "acme" // DefaultAcmeStorageRegion applies only when an endpoint is set, which means the // store is not real AWS and conventionally ignores the region. DefaultAcmeStorageRegion = "us-east-1" // AcmeStorageEncryptionKeyLen is secretbox's key size. certmagic-s3 rejects any // other length. AcmeStorageEncryptionKeyLen = 32 )
const ( DefaultRequestBufferBytes = 1 << 20 // 1MiB MaxRequestBufferBytes = 16 << 20 // 16MiB )
DefaultRequestBufferBytes is the `request_buffers` size every SC-generated reverse_proxy block gets unless the stack overrides it; MaxRequestBufferBytes caps the override because the buffer is held in the edge's memory per in-flight request.
The contract is documented on api.SimpleContainerLBConfig.RequestBufferSize.
const AssetsDir = "assets"
AssetsDir is the prefix every path in FS carries. Kept as a constant because both consumers have to strip it, and a literal in two packages is how the next move of these files breaks one of them silently.
const CaddyfilePath = AssetsDir + "/Caddyfile"
CaddyfilePath is the snippet library inside FS.
Variables ¶
var FS embed.FS
FS is the asset tree: `assets/Caddyfile` (the snippet library) and `assets/pages/*.html` (the error pages it serves). Consumers copy the tree to /etc/caddy — as a ConfigMap-backed volume in Kubernetes (kubernetes.EmbedFSToTextVolumes) or as files on the host in the VM path.
Functions ¶
func RequestBufferBytes ¶
RequestBufferBytes resolves lbConfig.requestBufferSize to a byte count.
Shared by both ingress paths — the Kubernetes edge and the single-VM Caddy — for the same reason the assets are: the value decides whether a chunked upload reaches the application with a Content-Length (Django #28668), so a path that parsed it differently would present as "file upload works in Kubernetes and not on the VM". The error strings are part of that: an operator who hits the cap should read the same sentence wherever they are.
An empty value yields the default. A parsed 0 yields 0, which both callers render as "omit the directive entirely" — the documented escape hatch for an edge running Caddy < 2.6.0, which predates `request_buffers`.
func Token ¶
Token quotes a Caddyfile token when it contains anything Caddy's parser would read as structure. Not applied to `{$VAR}` placeholders, which must stay unquoted to be substituted.
func WriteAcmeStorageGlobals ¶
func WriteAcmeStorageGlobals(b *strings.Builder, s *AcmeStorage, indent, logHint string)
WriteAcmeStorageGlobals renders the two global directives a shared certificate store needs: `storage s3` — the thing that makes origin HTTPS possible on a fleet at all, rather than a tuning knob — and the `persist_config off` that keeps its credentials out of Caddy's config autosave.
Both, from one function, because rendering the store without the guard is a credential exposure and there is no reason to ever want it (see writeAdminConfigPersistOff).
`indent` prefixes every line and is doubled for the subdirectives inside the block, because the two edges nest their global options differently (a tab on the vm path, two spaces on the Kubernetes one) and a Caddyfile is whitespace-insensitive but diffs are not. `logHint` completes the "if certificates never issue, look here" sentence with the command that reads the right log on this edge; an empty string omits it.
The block ends with a newline. A caller assembling it into a larger block alongside others should TrimRight it, since Caddy accepts the blank line and a reviewer reads it as an accident.
Module: github.com/techknowlogick/certmagic-s3, baked into simplecontainer/caddy and gated by the image build's `caddy list-modules | grep -qE '^caddy\.storage\.s3$'`. An SC binary newer than the image it names will render a block the image's Caddy cannot parse, and Caddy answers that with a config-load failure at container start — which is loud, and the correct way for that skew to present.
Two rendering rules, both forced by the module's own parser (s3.go, UnmarshalCaddyfile):
- EVERY BOOLEAN CARRIES AN EXPLICIT VALUE. The parser reads each subdirective with `if !d.Args(&value) { continue }`, so a bare `use_path_style` is not an error and is not true — it is SILENTLY SKIPPED. A fleet on minio with a bare `use_path_style` would therefore address buckets virtual-host style, fail every request, and say nothing about why.
- CREDENTIALS ARE `{$VAR}` PLACEHOLDERS, resolved by Caddy's parser at load time from whatever the caller of CredentialEnv delivered. The Caddyfile is world-readable inside the container and is echoed by `caddy adapt`. They do not go through Token, which would quote the braces into a literal.
Types ¶
type AcmeStorage ¶
type AcmeStorage struct {
// Bucket is required. It must already exist: SC does not create it here, because
// the bucket for a fleet generally lives in the same parent stack (a `yc-bucket` /
// `gcp-bucket` resource) or on an operator-run minio, and inventing a second
// owner for it would make a `sc destroy` able to take the certificates with it.
Bucket string `json:"bucket" yaml:"bucket"`
// Endpoint is the store's base URL, scheme included
// (`https://storage.yandexcloud.net`, `http://10.0.0.4:9000`). Empty means real
// AWS S3.
//
// Setting it also switches the SDK to computing request checksums only when
// required, which is what makes most non-AWS implementations work at all.
Endpoint string `json:"endpoint,omitempty" yaml:"endpoint,omitempty"`
// Region is required when Endpoint is empty, since that is real AWS and the wrong
// region is a failed request rather than a redirect. With an Endpoint it defaults
// to `us-east-1`, which S3-compatible stores conventionally ignore.
Region string `json:"region,omitempty" yaml:"region,omitempty"`
// AccessKey / SecretKey are the static credential, both or neither.
//
// Neither means the AWS SDK's default chain — an EC2 instance role, in practice.
// That works on AWS and nowhere else: a VPS has no instance metadata, so on
// Cloud.ru, MWS or byo, omitting them is a silent fall-through to "no credentials"
// whose only symptom is certificates that never issue. SecretKey is a credential:
// write it as `${secret:...}`. Neither value reaches the rendered Caddyfile — see
// CredentialEnv.
AccessKey string `json:"accessKey,omitempty" yaml:"accessKey,omitempty"`
SecretKey string `json:"secretKey,omitempty" yaml:"secretKey,omitempty"`
// Prefix is the key prefix inside the bucket. Defaults to `acme`.
//
// Worth setting when one bucket serves several fleets: two fleets sharing a prefix
// share locks and certificates, which is correct only if they also share every
// domain name.
Prefix string `json:"prefix,omitempty" yaml:"prefix,omitempty"`
// PathStyle selects path-style addressing (`<endpoint>/<bucket>/<key>`) over
// virtual-host style (`<bucket>.<endpoint>/<key>`). Defaults to TRUE whenever
// Endpoint is set and false otherwise.
//
// That default is the useful one: virtual-host addressing needs the bucket name to
// resolve as a DNS label under the endpoint, which minio does not serve at all and
// several S3-compatible clouds serve only for some bucket names. Real AWS prefers
// virtual-host. Set it explicitly to override.
PathStyle *bool `json:"pathStyle,omitempty" yaml:"pathStyle,omitempty"`
// Insecure disables TLS verification against the store. For a minio with a
// self-signed certificate, and nothing else — the credential and every private key
// the fleet owns travel over this connection. Prefer plain `http://` on a private
// network, which is at least honest about what it is.
Insecure bool `json:"insecure,omitempty" yaml:"insecure,omitempty"`
// EncryptionKey encrypts the stored objects with secretbox. Exactly 32 bytes when
// set; a credential, so write it as `${secret:...}`.
//
// Unset means the module logs `Clear text certificate storage active` and stores
// the fleet's private keys as they are. Acceptable when the bucket is private AND
// the cloud encrypts at rest; on a minio running on one of the fleet's own
// machines it is neither, so set it there.
EncryptionKey string `json:"encryptionKey,omitempty" yaml:"encryptionKey,omitempty"`
}
AcmeStorage is an S3-compatible bucket holding a fleet's certificates and ACME challenge state, rendered as Caddy's `storage s3` global option.
S3 and not one module per cloud. The image also carries `caddy.storage.gcs`, but GCS serves an S3-compatible interop endpoint and `gcp-bucket` already exports HMAC credentials for it, so one code path covers Yandex, AWS, GCP, minio and anything else that speaks S3. The GCS module stays what GKE's edge uses. There is deliberately no `type:` field: one legal value is not a choice, and adding the field later with a default of `s3` stays backwards compatible.
Every field is a property of the STORE, not of a machine or a replica — the whole point is that every front door writes to the same place.
func (*AcmeStorage) CredentialEnv ¶
func (s *AcmeStorage) CredentialEnv() map[string]string
CredentialEnv is the name→value map of everything that must NOT be rendered into the Caddyfile: the two static-credential halves and the encryption key. The caller's job is to deliver these out of band (a 0600 env file on a machine, a Secret in a cluster) under exactly these names, because WriteAcmeStorageGlobals renders `{$NAME}` placeholders for them.
AccessKey and SecretKey come as a pair or not at all. The block renders the two placeholders together, and a placeholder with no value expands to the empty string rather than failing — which would read as "the credential is wrong" instead of "the credential is missing".
func (*AcmeStorage) Enabled ¶
func (s *AcmeStorage) Enabled() bool
Enabled reports whether this store is configured enough to render. A nil store and a store with no bucket both mean "no shared store", because a bucket is the one field with no useful default.
func (*AcmeStorage) StoragePrefix ¶
func (s *AcmeStorage) StoragePrefix() string
StoragePrefix resolves Prefix's default. Rendered explicitly rather than left to the module, so the generated Caddyfile says where the fleet's certificates actually are.
func (*AcmeStorage) StorageRegion ¶
func (s *AcmeStorage) StorageRegion() string
StorageRegion resolves Region's default, which only applies when there is an endpoint — Validate refuses an empty region without one.
func (*AcmeStorage) UsePathStyle ¶
func (s *AcmeStorage) UsePathStyle() bool
UsePathStyle resolves PathStyle's default: on whenever there is an endpoint.
func (*AcmeStorage) Validate ¶
func (s *AcmeStorage) Validate(field string) error
Validate checks the shared certificate store. `field` is the operator-facing path of this struct in the surrounding config (`ingress.acmeStorage` on a vm resource, `caddy.acmeStorage` on a Kubernetes one) so every refusal names something greppable in the file the operator is holding.
Every refusal here replaces a failure that is otherwise invisible until a certificate does not renew, which is weeks after the deploy that caused it and on a machine nobody is watching. The store is only consulted on issuance and renewal, so a misconfigured one serves perfectly from cache until it matters.