From 7d489a95e3dc79c04cf197530ee34c9ec04e7708 Mon Sep 17 00:00:00 2001 From: Frederik Ring Date: Mon, 29 Jan 2024 15:15:29 +0100 Subject: [PATCH] Rename and deprecate BACKUP_STOP_CONTAINER_LABEL --- cmd/backup/config.go | 3 ++- cmd/backup/script.go | 2 +- cmd/backup/stop_restart.go | 17 ++++++++++++++++- ...-deprecated-backup-stop-container-label.md | 19 +++++++++++++++++++ docs/how-tos/set-up-notifications.md | 2 +- docs/how-tos/stop-containers-during-backup.md | 4 ++-- docs/recipes/index.md | 4 ++-- docs/reference/index.md | 15 +++++++-------- 8 files changed, 50 insertions(+), 16 deletions(-) create mode 100644 docs/how-tos/replace-deprecated-backup-stop-container-label.md diff --git a/cmd/backup/config.go b/cmd/backup/config.go index 3afbe25..db39aca 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 65b8009..747a4dd 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 ca3265b..0dba138 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 0000000..f8841cb --- /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 23d2aaf..3c0b4a5 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 f87f754..bc91345 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 cd483f0..5a2220c 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 9eb157d..8caf775 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -316,15 +316,14 @@ You can populate below template according to your requirements and use it as you # GPG_PASSPHRASE="" -########### STOPPING CONTAINERS DURING BACKUP +########### STOPPING CONTAINERS AND SERVICES DURING BACKUP -# Containers can be stopped by applying a -# `docker-volume-backup.stop-during-backup` label. By default, all containers -# that are labeled with `true` will be stopped. If you need more fine grained -# 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" +# Containers or services can be stopped by applying a +# `docker-volume-backup.stop-during-backup` label. By default, all containers and +# services that are labeled with `true` will be stopped. If you need more fine +# grained control (e.g. when running multiple containers based on this image), +# you can override this default by specifying a different value here. +# 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.