package storage import ( "encoding/json" "errors" "fmt" "os" "path/filepath" "strconv" "strings" "github.com/dokku/dokku/plugins/common" ) const ( helpHeader = `Usage: dokku storage[:COMMAND] Manage mounted volumes Additional commands:` helpContent = ` storage:annotations:report [] [], Displays annotations for one or more storage entries storage:annotations:set [], Set or clear a single annotation on a storage entry storage:create [] [flags], Register a named storage entry storage:destroy [--force] [--destroy-host-dir], Remove a named storage entry (must be unmounted from every app first) storage:ensure-directory [--chown option] , [DEPRECATED] use storage:create instead storage:exec [-- ...], Run a command (or shell) in a temporary container that mounts the entry storage:info [--format text|json], Show details for one storage entry storage:labels:report [] [], Displays labels for one or more storage entries storage:labels:set [], Set or clear a single label on a storage entry storage:list [--format text|json], List bind mounts for an app's container(s) (legacy host:container view) storage:list-entries [--scheduler s] [--format text|json], List registered storage entries storage:migrate [|--all], Re-run the legacy -v to attachment migration for an app storage:mount [--replace] ... [flags], Create or replace bind mounts storage:report [|--global] [], Displays a storage report for one or more apps storage:set [], Update a storage entry in place storage:unmount [--all] [...] [flags], Remove one or all bind mounts storage:wait , Wait for a storage entry's PVC to be bound (k3s)` ) // CommandHelp displays help for the storage plugin func CommandHelp() error { common.CommandUsage(helpHeader, helpContent) return nil } // CommandEnsureDirectory creates a persistent storage directory func CommandEnsureDirectory(directory string, chownFlag string) error { if err := ValidateDirectoryName(directory); err != nil { return err } chownID, err := ResolveChownID(chownFlag) if err != nil { return err } storageDirectory := filepath.Join(GetStorageDirectory(), directory) common.LogInfo1(fmt.Sprintf("Ensuring %s exists", storageDirectory)) if err := os.MkdirAll(storageDirectory, 0755); err != nil { return fmt.Errorf("Unable to create directory: %s", err.Error()) } if chownID != "false" { common.LogVerboseQuiet(fmt.Sprintf("Setting directory ownership to %s:%s", chownID, chownID)) if err := callStorageDirScript("chown-storage-dir", directory, chownID); err != nil { return fmt.Errorf("Unable to set directory ownership: %s", err.Error()) } } common.LogVerboseQuiet("Directory ready for mounting") return nil } // ResolveChownID converts a chown flag value to a numeric UID func ResolveChownID(chownFlag string) (string, error) { var chownID string switch chownFlag { case "herokuish": chownID = "32767" case "heroku": chownID = "1000" case "packeto": common.LogVerbose("Detected deprecated chown flag 'packeto'. Using 'paketo' instead. Please update your configuration.") chownID = "2000" case "paketo": chownID = "2000" case "root": chownID = "0" case "false": return "false", nil default: id, err := strconv.ParseUint(chownFlag, 10, 16) if err != nil { return "", errors.New("Unsupported chown permissions") } else { chownID = fmt.Sprint(id) } } userns, err := isUserNamespacesEnabled() if err != nil { return "", err } if userns && chownID != "false" { uid := 0 fmt.Sscanf(chownID, "%d", &uid) uid += 165536 chownID = fmt.Sprintf("%d", uid) } return chownID, nil } // ValidateChownOption reports whether a chown option is one the storage // plugin understands, mirroring the set ResolveChownID maps. An empty value // means no chown was requested. Unlike ResolveChownID it never shells out to // docker for the user namespace offset, so it is safe to call as a pure // validation step before anything has been written. func ValidateChownOption(chownFlag string) error { switch chownFlag { case "", "herokuish", "heroku", "packeto", "paketo", "root", "false": return nil } if _, err := strconv.ParseUint(chownFlag, 10, 16); err != nil { return errors.New("Unsupported chown permissions") } return nil } // isUserNamespacesEnabled checks if Docker user namespaces are enabled func isUserNamespacesEnabled() (bool, error) { result, err := common.CallExecCommand(common.ExecCommandInput{ Command: common.DockerBin(), Args: []string{"info", "-f", "{{range .SecurityOptions}}{{if eq . \"name=userns\"}}true{{end}}{{end}}"}, }) if err != nil { return false, err } return strings.TrimSpace(result.StdoutContents()) == "true", nil } // CommandMountInput captures the optional flags accepted by storage:mount // when the second argument is a named entry rather than a colon-form path. // // Replace and Specs drive the whole-set form, where the positional arguments // are mount specs carrying their own mount-time fields. Only ProcessType // scopes that call; every other mount-time field is rejected with Replace so // each one has exactly one spelling. type CommandMountInput struct { AppName string NameOrPath string ContainerDir string Phases []string ProcessType string Subpath string Readonly bool VolumeOptions string VolumeChown string Replace bool Specs []string } // CommandMount creates a new bind mount for an app. The second positional // argument may be either a legacy host:container[:options] string (kept // for back-compat on docker-local) or a registered storage entry name. func CommandMount(input CommandMountInput) error { if err := common.VerifyAppName(input.AppName); err != nil { return err } if input.Replace { return replaceMounts(input) } appScheduler := common.GetAppScheduler(input.AppName) // Legacy colon form: synthesize a legacy- entry plus an // attachment so storage:list (now attachment-only) sees the mount. // The storage docker-args trigger emits the corresponding -v flag at // deploy time, so behavior at the docker-run boundary is unchanged. if strings.Contains(input.NameOrPath, ":") { if appScheduler != SchedulerDockerLocal { return fmt.Errorf("colon-form mounts are only supported on docker-local apps; %s is a %s app. Create a named entry with 'dokku storage:create --scheduler %s' and mount it instead", input.AppName, appScheduler, appScheduler) } return mountLegacyColon(input.AppName, input.NameOrPath) } // Named-entry form: persist as an attachment. if !EntryExists(input.NameOrPath) { return fmt.Errorf("storage entry %q does not exist; create it first with `dokku storage:create`", input.NameOrPath) } if input.ContainerDir == "" { return errors.New("--container-dir is required when mounting a named storage entry") } entry, err := LoadEntry(input.NameOrPath) if err != nil { return err } if entry.Scheduler != appScheduler { return fmt.Errorf("storage entry %q is scheduler=%s but cannot be mounted on a %s app; recreate it with --scheduler %s", entry.Name, entry.Scheduler, appScheduler, appScheduler) } if err := ValidateChownOption(input.VolumeChown); err != nil { return err } phases := input.Phases if len(phases) == 0 { phases = []string{PhaseDeploy, PhaseRun} } processType := input.ProcessType if processType == "" { processType = DefaultProcessType } attachment := &Attachment{ EntryName: entry.Name, ContainerPath: input.ContainerDir, Phases: phases, ProcessType: processType, Subpath: input.Subpath, Readonly: input.Readonly, VolumeOptions: input.VolumeOptions, VolumeChown: input.VolumeChown, } // Idempotent contract: same (entry, container_dir, process_type) // tuple updates the mount-time fields in place rather than appending // a duplicate attachment. Lets declarative tooling change // --volume-options / --volume-chown / --phase / etc. without an // unmount-then-remount dance that briefly drops the volume. created, err := UpsertAttachment(input.AppName, attachment) if err != nil { return err } if created { common.LogInfo1(fmt.Sprintf("Storage entry %s mounted at %s on %s", entry.Name, input.ContainerDir, input.AppName)) } else { common.LogInfo1(fmt.Sprintf("Storage entry %s mount at %s on %s updated", entry.Name, input.ContainerDir, input.AppName)) } return nil } // resolveMountSpecEntry maps a parsed spec onto the storage entry it names. // // The single-mount form tells a named entry from a colon-form host path by the // presence of a colon, which every --replace spec has, so a leading "/" is the // discriminator instead. Without that rule a mistyped entry name would match // the docker volume grammar and silently register a legacy entry for a volume // that does not exist. // // The returned bool reports whether the entry still needs registering, so the // registry write can wait until every spec in the call has validated. func resolveMountSpecEntry(appName string, appScheduler string, spec string, parsed mountSpec) (*Entry, bool, error) { if strings.HasPrefix(parsed.EntryName, "/") { if appScheduler != SchedulerDockerLocal { return nil, false, fmt.Errorf("colon-form mounts are only supported on docker-local apps; %s is a %s app. Create a named entry with 'dokku storage:create --scheduler %s' and mount it instead", appName, appScheduler, appScheduler) } if err := VerifyPaths(spec); err != nil { return nil, false, err } entry := LegacyMountToEntry(spec) return entry, !EntryExists(entry.Name), nil } if !EntryExists(parsed.EntryName) { return nil, false, fmt.Errorf("storage entry %q does not exist; create it first with `dokku storage:create`", parsed.EntryName) } entry, err := LoadEntry(parsed.EntryName) if err != nil { return nil, false, err } if entry.Scheduler != appScheduler { return nil, false, fmt.Errorf("storage entry %q is scheduler=%s but cannot be mounted on a %s app; recreate it with --scheduler %s", entry.Name, entry.Scheduler, appScheduler, appScheduler) } return entry, false, nil } // replaceMounts swaps one process type's entire mount set for the declared one // in a single write, so a caller converging an app onto a declared set no // longer issues one storage:mount or storage:unmount per difference and can no // longer fail partway through holding a mixture of the two sets. // // Every spec is parsed and validated before anything is written, so a rejected // spec leaves the stored set untouched. Attachments belonging to other process // types are kept: an omitted --process-type scopes the replacement to // _default_ the same way it scopes a single storage:mount. // // Every other mount-time field comes from the spec that declares it rather // than from a call-level flag, so one call can vary them between mounts. func replaceMounts(input CommandMountInput) error { if input.ContainerDir != "" { return errors.New("The --container-dir flag cannot be used with --replace") } // Each mount-time field has exactly one spelling in this form, the token // in the spec that declares it, rather than a call-level default a token // overrides. A flag is taken as passed when it holds anything but its // zero value, which is what pflag leaves behind when it is absent; the // values that slip through - an empty string or an explicit false - ask // for what an omitted flag already gives. for _, conflict := range []struct { flag string set bool hint string }{ {"--phase", len(input.Phases) > 0, mountSpecKeyPhase + "=" + PhaseDeploy}, {"--volume-subpath", input.Subpath != "", mountSpecKeySubpath + "="}, {"--volume-readonly", input.Readonly, "ro"}, {"--volume-chown", input.VolumeChown != "", mountSpecKeyVolumeChown + "=