Documentation
¶
Index ¶
- Constants
- Variables
- func HasNoNewPrivileges(opts []string) bool
- func IsMinecraftImage(image string) bool
- func MinecraftBootstrapCapabilities() []string
- func PreflightProfile(profile RuntimeProfile) error
- func PreflightRuntime(spec RuntimeSpec) error
- func RunContract(t *testing.T, describe func(RuntimeSpec) RuntimeProfile)
- type ContainerLimits
- type DaemonEnforcement
- type RuntimeIssue
- type RuntimeIssueCode
- type RuntimeIssueSeverity
- type RuntimeProfile
- type RuntimeSpec
Constants ¶
const ( ItzgDefaultUID = 1000 ItzgDefaultGID = 1000 )
ItzgDefaultUID and ItzgDefaultGID are the accounts shipped in itzg/minecraft-server. A different uid/gid during root-then-drop tries to rewrite /etc/passwd and /etc/group, which fails on a read-only root.
const SkipChown = "SKIP_CHOWN"
SkipChown tells the itzg image not to recursively chown /data.
const SkipNsswitchConf = "SKIP_NSSWITCH_CONF"
SkipNsswitchConf tells the itzg image not to rewrite /etc/nsswitch.conf.
Variables ¶
var ErrRuntimeIncompatible = errors.New("container configuration is incompatible with this image or runtime")
ErrRuntimeIncompatible reports a container configuration that cannot boot the configured image. It is raised from the fully-resolved Docker configuration, before any daemon mutation, so an unsupported combination never replaces a running container or leaves a half-created one behind.
Functions ¶
func HasNoNewPrivileges ¶
HasNoNewPrivileges reports whether security options keep the no-new-privileges bit.
func IsMinecraftImage ¶
IsMinecraftImage reports whether an image reference is the itzg Minecraft server image, which is the image that follows the root-start-then-drop bootstrap contract the profile checks.
func MinecraftBootstrapCapabilities ¶
func MinecraftBootstrapCapabilities() []string
MinecraftBootstrapCapabilities are the capabilities the itzg entrypoint needs to prepare /data and drop to the game user.
func PreflightProfile ¶
func PreflightProfile(profile RuntimeProfile) error
PreflightProfile is PreflightRuntime for an already-described profile.
func PreflightRuntime ¶
func PreflightRuntime(spec RuntimeSpec) error
PreflightRuntime inspects the resolved configuration and returns an error when it cannot boot the configured image. The returned error wraps ErrRuntimeIncompatible and every fatal issue.
func RunContract ¶
func RunContract(t *testing.T, describe func(RuntimeSpec) RuntimeProfile)
RunContract executes the shared runtime and storage fixture suite through describe. Panel's container create path and Cloud's node agent both pass their own describe function so the same cases cover both callers.
Types ¶
type ContainerLimits ¶
type ContainerLimits struct {
// RequestedMemoryMB is the server's configured memory.
RequestedMemoryMB int64
// RequestedMemoryBytes and RequestedMemorySwapBytes are HostConfig values
// sent to Docker. MemoryBytes and MemorySwapBytes are effective: zero when
// /info says the daemon cannot apply them.
RequestedMemoryBytes int64
RequestedMemorySwapBytes int64
MemoryBytes int64
MemorySwapBytes int64
// SwapDisabled is true when the request sets MemorySwap equal to Memory or
// leaves both unset. It describes the request, not daemon capability.
SwapDisabled bool
// RequestedPidsLimit is the process cap on the request. PidsLimit is
// effective, or 0 when the daemon default applies or /info says pids
// limits are unsupported.
RequestedPidsLimit int64
PidsLimit int64
// CPULimit is the configured CPU cap, or 0 for unlimited.
CPULimit float64
// RequestedWritableLayerMB is storage-opt size on the request.
// WritableLayerMB is effective, or 0 when the layer is unbounded, the
// root is read-only, or /info says storage-opt size is unsupported.
RequestedWritableLayerMB int64
WritableLayerMB int64
// WorldDiskEnforced is true only when the daemon quotas the world bind.
// Panel admission (storage.world_quota_mb) can refuse create without
// setting this. storage-opt size never sets it, including overlay2+xfs.
WorldDiskEnforced bool
}
ContainerLimits is the enforcement that is actually requested from the daemon, next to the limit the caller asked for. A zero effective value means no limit: it is never reported as if the requested limit applied.
type DaemonEnforcement ¶
type DaemonEnforcement struct {
Rootless bool
CgroupDriver string
CgroupVersion string
StorageDriver string
MemoryLimitSupported bool
SwapLimitSupported bool
PidsLimitSupported bool
WritableLayerQuotaSupported bool
}
DaemonEnforcement records which cgroup and storage limits the Docker daemon reports as supported. Callers compare this against the resolved container request so an ignored limit is never presented as enforced.
func (DaemonEnforcement) CgroupLimitsQualified ¶
func (d DaemonEnforcement) CgroupLimitsQualified() bool
CgroupLimitsQualified reports whether memory/swap/pids caps are expected to apply on this daemon. Rootless mode needs cgroup v2 delegation; a v1 rootless daemon may ignore resource flags even when MemoryLimit is true.
type RuntimeIssue ¶
type RuntimeIssue struct {
Code RuntimeIssueCode
Severity RuntimeIssueSeverity
// Detail says what the effective configuration is.
Detail string
// Remedy says what to change. It never suggests weakening confinement
// beyond what the image actually needs.
Remedy string
}
RuntimeIssue is one compatibility finding with an actionable remedy.
func (RuntimeIssue) Error ¶
func (i RuntimeIssue) Error() string
Error renders the issue as a single diagnostic sentence.
type RuntimeIssueCode ¶
type RuntimeIssueCode string
RuntimeIssueCode is a stable machine-readable identifier for a compatibility finding. It is part of the operator-facing diagnostic, so keep it stable.
const ( // RuntimeIssueDataMountMissing is raised when no /data mount is present. RuntimeIssueDataMountMissing RuntimeIssueCode = "data_mount_missing" // RuntimeIssueDataMountReadOnly is raised when /data is mounted read-only. RuntimeIssueDataMountReadOnly RuntimeIssueCode = "data_mount_read_only" // RuntimeIssueRootfsReadOnlyNsswitch is raised when the root filesystem is // read-only but the image was not told to skip its /etc/nsswitch.conf // rewrite. The entrypoint fails and the container restart-loops. RuntimeIssueRootfsReadOnlyNsswitch RuntimeIssueCode = "read_only_root_blocks_nsswitch" // RuntimeIssueBootstrapCapabilitiesMissing is raised when the container // starts as root and drops privileges but no longer holds the capabilities // that the drop needs. RuntimeIssueBootstrapCapabilitiesMissing RuntimeIssueCode = "bootstrap_capabilities_missing" // RuntimeIssueNoNewPrivilegesDisabled is raised when no-new-privileges was // replaced instead of extended by an override. RuntimeIssueNoNewPrivilegesDisabled RuntimeIssueCode = "no_new_privileges_disabled" // RuntimeIssuePrivilegedMode is raised for full privilege mode. RuntimeIssuePrivilegedMode RuntimeIssueCode = "privileged_mode" // RuntimeIssueWritableRootfs is raised when the read-only root default was // turned off. RuntimeIssueWritableRootfs RuntimeIssueCode = "writable_rootfs" // RuntimeIssueNonNumericUser is raised when config.User names a user that // Docker can only resolve through the image's /etc/passwd. RuntimeIssueNonNumericUser RuntimeIssueCode = "non_numeric_user" // RuntimeIssueCustomEntrypoint is raised when an override replaces the // image entrypoint that performs first-boot preparation. RuntimeIssueCustomEntrypoint RuntimeIssueCode = "custom_entrypoint" // RuntimeIssueTmpfsMissing is raised when /tmp is not a tmpfs on a // read-only root. RuntimeIssueTmpfsMissing RuntimeIssueCode = "tmpfs_missing" // RuntimeIssueTmpfsTooSmall is raised when /tmp is too small for unpacking // a server jar or mod archive. RuntimeIssueTmpfsTooSmall RuntimeIssueCode = "tmpfs_too_small" // RuntimeIssueTmpfsExec is raised when /tmp stays executable. RuntimeIssueTmpfsExec RuntimeIssueCode = "tmpfs_exec" // RuntimeIssueHostNetwork is raised for host networking. RuntimeIssueHostNetwork RuntimeIssueCode = "host_network" // RuntimeIssueHostDevice is raised for a host device mapping. RuntimeIssueHostDevice RuntimeIssueCode = "host_device" // RuntimeIssueDataOwnerMismatch is raised when the container runs as a // numeric user that cannot own the world directory the panel created. RuntimeIssueDataOwnerMismatch RuntimeIssueCode = "data_owner_mismatch" // RuntimeIssueMemoryLimitUnset is raised when the container has no memory // limit, so one server can consume the node. RuntimeIssueMemoryLimitUnset RuntimeIssueCode = "memory_limit_unset" // RuntimeIssueSwapEnabled is raised when the 0-swap policy was overridden. RuntimeIssueSwapEnabled RuntimeIssueCode = "swap_enabled" // RuntimeIssuePidsLimitUnset is raised when the fork-bomb guard is absent. RuntimeIssuePidsLimitUnset RuntimeIssueCode = "pids_limit_unset" // RuntimeIssueWritableLayerUnbounded is raised for a writable root with no // writable-layer cap. RuntimeIssueWritableLayerUnbounded RuntimeIssueCode = "writable_layer_unbounded" // RuntimeIssueStorageQuotaIsNotAWorldQuota is raised when a storage-opt // size is presented as if it bounded the world. RuntimeIssueStorageQuotaIsNotAWorldQuota RuntimeIssueCode = "storage_quota_is_not_a_world_quota" // RuntimeIssueWorldQuotaExceeded is raised when storage.world_quota_mb is // set and measured world bytes meet or exceed it. Creation is refused. RuntimeIssueWorldQuotaExceeded RuntimeIssueCode = "world_quota_exceeded" // RuntimeIssueWorldQuotaUnmeasured is raised when a world quota is set but // world bytes could not be measured, so admission fails closed. RuntimeIssueWorldQuotaUnmeasured RuntimeIssueCode = "world_quota_unmeasured" // RuntimeIssueWritableLayerCapIgnored is raised when a writable-layer cap // is configured but the root is read-only, so nothing is capped. RuntimeIssueWritableLayerCapIgnored RuntimeIssueCode = "writable_layer_cap_ignored" // RuntimeIssueMemoryLimitUnsupported is raised when the container requests a // memory cap but the daemon reports it cannot enforce one. RuntimeIssueMemoryLimitUnsupported RuntimeIssueCode = "memory_limit_unsupported" // RuntimeIssueSwapLimitUnsupported is raised when swap is enabled on the // request but the daemon reports swap limits are unavailable. RuntimeIssueSwapLimitUnsupported RuntimeIssueCode = "swap_limit_unsupported" // RuntimeIssuePidsLimitUnsupported is raised when a process cap is set but // the daemon reports pids limits are unavailable. RuntimeIssuePidsLimitUnsupported RuntimeIssueCode = "pids_limit_unsupported" // RuntimeIssueRootlessCgroupUnqualified is raised when a rootless daemon is // not on cgroup v2, so cgroup resource flags may be ignored. RuntimeIssueRootlessCgroupUnqualified RuntimeIssueCode = "rootless_cgroup_unqualified" // RuntimeIssueWritableLayerCapUnsupported is raised when a writable-layer // cap is requested on a storage stack that does not support storage-opt size. RuntimeIssueWritableLayerCapUnsupported RuntimeIssueCode = "writable_layer_cap_unsupported" // RuntimeIssueImageUnpinned is raised when a Minecraft image is a moving // tag. It is a warning: the container can still boot, but a rebuilt tag // can change what the next recreate runs. RuntimeIssueImageUnpinned RuntimeIssueCode = "image_unpinned" // RuntimeIssueRootlessHostRootData is raised when a rootless daemon must run // the root-then-drop bootstrap but the world directory is still owned by // host uid 0. The entrypoint cannot chown it into the user namespace. RuntimeIssueRootlessHostRootData RuntimeIssueCode = "rootless_host_root_data" // RuntimeIssueReadOnlyRootUserMod is raised when root-then-drop would // usermod/groupmod an account that is not already in the image, which // needs a writable /etc. RuntimeIssueReadOnlyRootUserMod RuntimeIssueCode = "read_only_root_blocks_usermod" // RuntimeIssueSensitiveMount is raised when an override bind shadows a // sensitive container path (for example /etc or the Docker socket). RuntimeIssueSensitiveMount RuntimeIssueCode = "sensitive_mount_target" // RuntimeIssueTmpfsReplaced is raised when a bind or volume covers /tmp // and therefore replaces the default noexec tmpfs. RuntimeIssueTmpfsReplaced RuntimeIssueCode = "tmpfs_replaced" )
type RuntimeIssueSeverity ¶
type RuntimeIssueSeverity string
RuntimeIssueSeverity orders issues by whether they block a boot.
const ( // RuntimeFatal issues mean the container cannot reach a playable state as // configured. They stop creation. RuntimeFatal RuntimeIssueSeverity = "fatal" // RuntimeWarning issues mean the configuration is weaker or more fragile // than the default, but the image can still boot. They are reported and // never stop creation. RuntimeWarning RuntimeIssueSeverity = "warning" )
type RuntimeProfile ¶
type RuntimeProfile struct {
Image string
// ImageDigest is the sha256 digest when the image reference is pinned.
// Empty means the reference is a tag.
ImageDigest string
ImagePinned bool
MinecraftImage bool
User string
RootStartDropUser bool
ReadOnlyRootfs bool
DataMount string
DataWritable bool
Tmpfs map[string]string
CapAdd []string
CapDrop []string
Privileged bool
NoNewPrivileges bool
NetworkMode string
Devices []string
Entrypoint []string
Limits ContainerLimits
// SkipDataChown is true when SKIP_CHOWN is set so the image will not
// recursively chown /data on this start.
SkipDataChown bool
Issues []RuntimeIssue
}
RuntimeProfile is the effective, inspectable runtime description of one container: what it runs as, what it can write, how confined it is, and which limits are actually enforced.
func DescribeRuntime ¶
func DescribeRuntime(spec RuntimeSpec) RuntimeProfile
DescribeRuntime returns the effective profile of a resolved runtime spec together with its compatibility issues.
func (RuntimeProfile) Description ¶
func (p RuntimeProfile) Description() string
Description renders a one-line summary of the effective profile for logs and diagnostics.
func (RuntimeProfile) Fatal ¶
func (p RuntimeProfile) Fatal() bool
Fatal reports whether any issue blocks a boot.
type RuntimeSpec ¶
type RuntimeSpec struct {
// Image is the resolved image reference.
Image string
// DataPath is the host directory bound to /data.
DataPath string
// MinecraftImage marks an image that follows the itzg first-boot
// contract: start as root, prepare /data, rewrite /etc/nsswitch.conf, then
// drop to the unprivileged game user through gosu.
MinecraftImage bool
// RequestedMemoryMB is the memory the server record asked for, which the
// effective container limit is derived from.
RequestedMemoryMB int64
// WritableLayerMB is the operator's writable-layer cap. It is applied only
// when the root filesystem is writable.
WritableLayerMB int64
// WorldQuotaMB is panel admission against measured world bytes. 0 disables.
// It is not a daemon, xfs, or volume quota and does not set WorldDiskEnforced.
WorldQuotaMB int64
// WorldBytes is the metrics collector's world-directory total when known.
WorldBytes int64
// WorldBytesKnown is false when a set quota could not be measured.
WorldBytesKnown bool
// DataOwnerUID is the owner of DataPath when the platform can report it.
// It lets the profile tell a supported non-root path (the directory was
// prepared for that uid) from one that would fail at boot.
DataOwnerUID *int
// Daemon is the Docker daemon's reported limit capabilities when known.
// Missing means qualification was not performed; no daemon issue is raised.
Daemon *DaemonEnforcement
// Config and HostConfig are the resolved daemon request.
Config *container.Config
HostConfig *container.HostConfig
}
RuntimeSpec is the fully-resolved configuration that is about to be sent to the Docker daemon. Because it is taken after the defaults and every operator override have been applied, a check here sees exactly what the daemon will run rather than what the helpers meant. It does not carry a panel server row, an RPC handler, or a transport protobuf.