diff --git a/cmd/backup/config.go b/cmd/backup/config.go index 3afbe251..db39acac 100644 --- a/cmd/backup/config.go +++ b/cmd/backup/config.go @@ -37,7 +37,8 @@ type Config struct { BackupRetentionDays int32 `split_words:"true" default:"-1"` BackupPruningLeeway time.Duration `split_words:"true" default:"1m"` BackupPruningPrefix string `split_words:"true"` - BackupStopContainerLabel string `split_words:"true" default:"true"` + BackupStopContainerLabel string `split_words:"true"` + BackupStopDuringBackupLabel string `split_words:"true" default:"true"` BackupStopServiceTimeout time.Duration `split_words:"true" default:"5m"` BackupFromSnapshot bool `split_words:"true"` BackupExcludeRegexp RegexpDecoder `split_words:"true"` diff --git a/cmd/backup/script.go b/cmd/backup/script.go index 65b8009d..747a4ddc 100644 --- a/cmd/backup/script.go +++ b/cmd/backup/script.go @@ -322,7 +322,7 @@ func (s *script) createArchive() error { "Using BACKUP_FROM_SNAPSHOT has been deprecated and will be removed in the next major version.", ) s.logger.Warn( - "Please use `archive-pre` and `archive-post` commands to prepare your backup sources. Refer to the README for an upgrade guide.", + "Please use `archive-pre` and `archive-post` commands to prepare your backup sources. Refer to the documentation for an upgrade guide.", ) backupSources = filepath.Join("/tmp", s.c.BackupSources) // copy before compressing guard against a situation where backup folder's content are still growing. diff --git a/cmd/backup/stop_restart.go b/cmd/backup/stop_restart.go index ca3265ba..0dba1381 100644 --- a/cmd/backup/stop_restart.go +++ b/cmd/backup/stop_restart.go @@ -5,6 +5,7 @@ import ( "errors" "fmt" "io" + "os" "sync" "time" @@ -87,9 +88,23 @@ func (s *script) stopContainersAndServices() (func() error, error) { } isDockerSwarm := dockerInfo.Swarm.LocalNodeState != "inactive" + labelValue := s.c.BackupStopDuringBackupLabel + if s.c.BackupStopContainerLabel != "" { + s.logger.Warn( + "Using BACKUP_STOP_CONTAINER_LABEL has been deprecated and will be removed in the next major version.", + ) + s.logger.Warn( + "Please use BACKUP_STOP_DURING_BACKUP_LABEL instead. Refer to the docs for an upgrade guide.", + ) + if _, ok := os.LookupEnv("BACKUP_STOP_DURING_BACKUP_LABEL"); ok { + return noop, errors.New("(*script).stopContainersAndServices: both BACKUP_STOP_DURING_BACKUP_LABEL and BACKUP_STOP_CONTAINER_LABEL have been set, cannot continue") + } + labelValue = s.c.BackupStopContainerLabel + } + filterMatchLabel := fmt.Sprintf( "docker-volume-backup.stop-during-backup=%s", - s.c.BackupStopContainerLabel, + labelValue, ) allContainers, err := s.cli.ContainerList(context.Background(), types.ContainerListOptions{}) diff --git a/docs/how-tos/replace-deprecated-backup-stop-container-label.md b/docs/how-tos/replace-deprecated-backup-stop-container-label.md new file mode 100644 index 00000000..f8841cb3 --- /dev/null +++ b/docs/how-tos/replace-deprecated-backup-stop-container-label.md @@ -0,0 +1,19 @@ +--- +title: Replace deprecated BACKUP_STOP_CONTAINER_LABEL setting +layout: default +parent: How Tos +nav_order: 19 +--- + +# Replace deprecated `BACKUP_STOP_CONTAINER_LABEL` setting + +Version `v2.36.0` deprecated the `BACKUP_STOP_CONTAINER_LABEL` setting and renamed it `BACKUP_STOP_DURING_BACKUP_LABEL` which is supposed to signal that this will stop both containers _and_ services. +Migrating is done by renaming the key for your custom value: + +```diff + env: +- BACKUP_STOP_CONTAINER_LABEL: database ++ BACKUP_STOP_DURING_BACKUP_LABEL: database +``` + +The old key will stay supported until the next major version, but logs a warning each time a backup is taken. diff --git a/docs/how-tos/set-up-notifications.md b/docs/how-tos/set-up-notifications.md index 23d2aaf6..3c0b4a59 100644 --- a/docs/how-tos/set-up-notifications.md +++ b/docs/how-tos/set-up-notifications.md @@ -76,7 +76,7 @@ Configuration, data about the backup run and helper functions will be passed to Here is a list of all data passed to the template: -* `Config`: this object holds the configuration that has been passed to the script. The field names are the name of the recognized environment variables converted in PascalCase. (e.g. `BACKUP_STOP_CONTAINER_LABEL` becomes `BackupStopContainerLabel`) +* `Config`: this object holds the configuration that has been passed to the script. The field names are the name of the recognized environment variables converted in PascalCase. (e.g. `BACKUP_STOP_DURING_BACKUP_LABEL` becomes `BackupStopDuringBackupLabel`) * `Error`: the error that made the backup fail. Only available in the `title_failure` and `body_failure` templates * `Stats`: objects that holds stats regarding script execution. In case of an unsuccessful run, some information may not be available. * `StartTime`: time when the script started execution diff --git a/docs/how-tos/stop-containers-during-backup.md b/docs/how-tos/stop-containers-during-backup.md index f87f7540..bc913458 100644 --- a/docs/how-tos/stop-containers-during-backup.md +++ b/docs/how-tos/stop-containers-during-backup.md @@ -14,7 +14,7 @@ In many cases, it will be desirable to stop the services that are consuming the This image can automatically stop and restart containers and services. By default, any container that is labeled `docker-volume-backup.stop-during-backup=true` will be stopped before the backup is being taken and restarted once it has finished. -In case you need more fine grained control about which containers should be stopped (e.g. when backing up multiple volumes on different schedules), you can set the `BACKUP_STOP_CONTAINER_LABEL` environment variable and then use the same value for labeling: +In case you need more fine grained control about which containers should be stopped (e.g. when backing up multiple volumes on different schedules), you can set the `BACKUP_STOP_DURING_BACKUP_LABEL` environment variable and then use the same value for labeling: ```yml version: '3' @@ -28,7 +28,7 @@ services: backup: image: offen/docker-volume-backup:v2 environment: - BACKUP_STOP_CONTAINER_LABEL: service1 + BACKUP_STOP_DURING_BACKUP_LABEL: service1 volumes: - data:/backup/my-app-backup:ro - /var/run/docker.sock:/var/run/docker.sock:ro diff --git a/docs/recipes/index.md b/docs/recipes/index.md index cd483f0b..5a2220c0 100644 --- a/docs/recipes/index.md +++ b/docs/recipes/index.md @@ -352,7 +352,7 @@ services: AWS_ACCESS_KEY_ID: AKIAIOSFODNN7EXAMPLE AWS_SECRET_ACCESS_KEY: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY # Label the container using the `data_1` volume as `docker-volume-backup.stop-during-backup=service1` - BACKUP_STOP_CONTAINER_LABEL: service1 + BACKUP_STOP_DURING_BACKUP_LABEL: service1 volumes: - data_1:/backup/data-1-backup:ro - /var/run/docker.sock:/var/run/docker.sock:ro @@ -362,7 +362,7 @@ services: <<: *backup_environment # Label the container using the `data_2` volume as `docker-volume-backup.stop-during-backup=service2` BACKUP_CRON_EXPRESSION: "0 3 * * *" - BACKUP_STOP_CONTAINER_LABEL: service2 + BACKUP_STOP_DURING_BACKUP_LABEL: service2 volumes: - data_2:/backup/data-2-backup:ro - /var/run/docker.sock:/var/run/docker.sock:ro diff --git a/docs/reference/index.md b/docs/reference/index.md index 9eb157de..fa94a9cf 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -324,7 +324,7 @@ You can populate below template according to your requirements and use it as you # control (e.g. when running multiple containers based on this image), you can # override this default by specifying a different value here. -# BACKUP_STOP_CONTAINER_LABEL="service1" +# BACKUP_STOP_DURING_BACKUP_LABEL="service1" # When trying to scale down Docker Swarm services, give up after # the specified amount of time in case the service has not converged yet.