From d32f8dbb6c6848e5bac8fbd1081b5523568d4f71 Mon Sep 17 00:00:00 2001 From: Wayne Witzel III Date: Mon, 27 Aug 2018 09:58:24 -0400 Subject: [PATCH 1/4] Update hooks/fsfreeze example Signed-off-by: Wayne Witzel III --- Dockerfile-fsfreeze-pause.alpine | 22 ++++++++++++++++ Makefile | 14 ++++++++++ docs/hooks.md | 44 ++++++++++++++++++++++++++++---- examples/nginx-app/with-pv.yaml | 13 ++++++++++ 4 files changed, 88 insertions(+), 5 deletions(-) create mode 100644 Dockerfile-fsfreeze-pause.alpine diff --git a/Dockerfile-fsfreeze-pause.alpine b/Dockerfile-fsfreeze-pause.alpine new file mode 100644 index 000000000..fdb04739c --- /dev/null +++ b/Dockerfile-fsfreeze-pause.alpine @@ -0,0 +1,22 @@ +# Copyright 2018 the Heptio Ark contributors. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +FROM alpine:3.7 + +MAINTAINER Wayne Witzel III + +RUN apk add --no-cache ca-certificates +RUN apk add --update --no-cache busybox util-linux + +ENTRYPOINT ["/bin/sh", "-c", "sleep infinity"] diff --git a/Makefile b/Makefile index 821b20ac3..35310a05b 100644 --- a/Makefile +++ b/Makefile @@ -129,9 +129,22 @@ shell: build-dirs build-image DOTFILE_IMAGE = $(subst :,_,$(subst /,_,$(IMAGE))-$(VERSION)) +build-fsfreeze: + @docker build -t $(REGISTRY)/fsfreeze-pause:$(VERSION) -f Dockerfile-fsfreeze-pause.alpine _output + @docker images -q $(REGISTRY)/fsfreeze-pause:$(VERSION) > $@ + +push-fsfreeze: + @docker push $(REGISTRY)/fsfreeze-pause:$(VERSION) +ifeq ($(TAG_LATEST), true) + docker tag $(REGISTRY)/fsfreeze-pause:$(VERSION) $(IMAGE):latest + docker push $(REGISTRY)/fsfreeze-pause:latest +endif + @docker images -q $(REGISTRY)/fsfreeze-pause:$(VERSION) > $@ + all-containers: $(MAKE) container $(MAKE) container BIN=ark-restic-restore-helper + $(MAKE) build-fsfreeze container: verify test .container-$(DOTFILE_IMAGE) container-name .container-$(DOTFILE_IMAGE): _output/bin/$(GOOS)/$(GOARCH)/$(BIN) $(DOCKERFILE) @@ -145,6 +158,7 @@ container-name: all-push: $(MAKE) push $(MAKE) push BIN=ark-restic-restore-helper + $(MAKE) push-fsfreeze push: .push-$(DOTFILE_IMAGE) push-name diff --git a/docs/hooks.md b/docs/hooks.md index 5097f4090..6a0416c10 100644 --- a/docs/hooks.md +++ b/docs/hooks.md @@ -14,11 +14,6 @@ As of version v0.7.0, Ark also supports "post" hooks - these execute after all c completed, as well as after all the additional items specified by custom actions have been backed up. -An example of when you might use both pre and post hooks is freezing a file system. If you want to -ensure that all pending disk I/O operations have completed prior to taking a snapshot, you could use -a pre hook to run `fsfreeze --freeze`. Next, Ark would take a snapshot of the disk. Finally, you -could use a post hook to run `fsfreeze --unfreeze`. - There are two ways to specify hooks: annotations on the pod itself, and in the Backup spec. ### Specifying Hooks As Pod Annotations @@ -51,4 +46,43 @@ Ark v0.7.0+ continues to support the original (deprecated) way to specify pre ho Please see the documentation on the [Backup API Type][1] for how to specify hooks in the Backup spec. +## Hook Example with fsfreeze + +We are going to walk through using both pre and post hooks for freezing a file system. Freezing the +file system is useful to ensure that all pending disk I/O operations have completed prior to taking a snapshot. + +We will be using [example/nginx-app/with-pv.yaml][2] for this example. Follow the [steps for your provider][3] to +setup this example. + +### Annotations + +The Ark [example/nginx-app/with-pv.yaml][2] serves as an example of adding the pre and post hook annotations directly +to your declarative deployment. Below is an example of what updating an object in place might look like. + +Place Ark in to restore only mode. By placing Ark in restore only mode you prevent Ark backups from running +while you are adding the annotations and avoid the condition where the pre hook freezes the file system, but +there is no post hook setup to unfreeze the file system. + + kubectl patch -n heptio-ark config default --type merge -p '{"restoreOnlyMode": true}' + +Now you patch your deployment with the required annotations. + + kubectl annotate pod -n nginx-example -l app=nginx pre.hook.backup.ark.heptio.com/command='["/sbin/fsfreeze", "--freeze", "/var/log/nginx"]' + kubectl annotate pod -n nginx-example -l app=nginx pre.hook.backup.ark.heptio.com/containr=fsfreeze + + kubectl annotate pod -n nginx-example -l app=nginx post.hook.backup.ark.heptio.com/command='["/sbin/fsfreeze", "--unfreeze", "/var/log/nginx"]' + kubectl annotate pod -n nginx-example -l app=nginx post.hook.backup.ark.heptio.com/containr=fsfreeze + +Finally remove Ark from restore only mode and test the pre and post hooks by creating a backup. You can use the Ark logs to verify that the pre and post +hooks are running and exiting without error. + + kubectl patch -n heptio-ark config default --type merge -p '{"restoreOnlyMode": false}' + ark backup create nginx-hook-test + + ark backup get nginx-hook-test + ark backup logs nginx-hook-test | grep hookCommand + + [1]: api-types/backup.md +[2]: https://github.com/heptio/ark/blob/master/examples/nginx-app/with-pv.yaml +[3]: cloud-common.md diff --git a/examples/nginx-app/with-pv.yaml b/examples/nginx-app/with-pv.yaml index b268f5986..daf333a66 100644 --- a/examples/nginx-app/with-pv.yaml +++ b/examples/nginx-app/with-pv.yaml @@ -48,6 +48,11 @@ spec: metadata: labels: app: nginx + annotations: + pre.hook.backup.ark.heptio.com/container: fsfreeze + pre.hook.backup.ark.heptio.com/command: '["/sbin/fsfreeze", "--freeze", "/var/log/nginx"]' + post.hook.backup.ark.heptio.com/container: fsfreeze + post.hook.backup.ark.heptio.com/command: '["/sbin/fsfreeze", "--unfreeze", "/var/log/nginx"]' spec: volumes: - name: nginx-logs @@ -62,6 +67,14 @@ spec: - mountPath: "/var/log/nginx" name: nginx-logs readOnly: false + - image: gcr.io/heptio-images/fsfreeze-pause:latest + name: fsfreeze + securityContext: + privileged: true + volumeMounts: + - mountPath: "/var/log/nginx" + name: nginx-logs + readOnly: false --- apiVersion: v1 From 030ea6c0adf2f5f9a2a494407019b770d5503d0f Mon Sep 17 00:00:00 2001 From: Wayne Witzel III Date: Mon, 27 Aug 2018 13:56:02 -0400 Subject: [PATCH 2/4] minor word updates and command wrapping Signed-off-by: Wayne Witzel III --- docs/hooks.md | 34 ++++++++++++++++++++-------------- 1 file changed, 20 insertions(+), 14 deletions(-) diff --git a/docs/hooks.md b/docs/hooks.md index 6a0416c10..ec0cea732 100644 --- a/docs/hooks.md +++ b/docs/hooks.md @@ -59,28 +59,34 @@ setup this example. The Ark [example/nginx-app/with-pv.yaml][2] serves as an example of adding the pre and post hook annotations directly to your declarative deployment. Below is an example of what updating an object in place might look like. -Place Ark in to restore only mode. By placing Ark in restore only mode you prevent Ark backups from running -while you are adding the annotations and avoid the condition where the pre hook freezes the file system, but -there is no post hook setup to unfreeze the file system. +Place Ark in restore only mode. This will prevent Ark backups from running while you are adding the +annotations and avoid the condition where the pre hook freezes the file system, but there is no +post hook setup to unfreeze it. - kubectl patch -n heptio-ark config default --type merge -p '{"restoreOnlyMode": true}' +```shell +kubectl patch -n heptio-ark config default --type merge -p '{"restoreOnlyMode": true}' +``` -Now you patch your deployment with the required annotations. +Now you patch your pod with the required annotations. - kubectl annotate pod -n nginx-example -l app=nginx pre.hook.backup.ark.heptio.com/command='["/sbin/fsfreeze", "--freeze", "/var/log/nginx"]' - kubectl annotate pod -n nginx-example -l app=nginx pre.hook.backup.ark.heptio.com/containr=fsfreeze +```shell +kubectl annotate pod -n nginx-example -l app=nginx pre.hook.backup.ark.heptio.com/command='["/sbin/fsfreeze", "--freeze", "/var/log/nginx"]' +kubectl annotate pod -n nginx-example -l app=nginx pre.hook.backup.ark.heptio.com/containr=fsfreeze - kubectl annotate pod -n nginx-example -l app=nginx post.hook.backup.ark.heptio.com/command='["/sbin/fsfreeze", "--unfreeze", "/var/log/nginx"]' - kubectl annotate pod -n nginx-example -l app=nginx post.hook.backup.ark.heptio.com/containr=fsfreeze +kubectl annotate pod -n nginx-example -l app=nginx post.hook.backup.ark.heptio.com/command='["/sbin/fsfreeze", "--unfreeze", "/var/log/nginx"]' +kubectl annotate pod -n nginx-example -l app=nginx post.hook.backup.ark.heptio.com/containr=fsfreeze +``` -Finally remove Ark from restore only mode and test the pre and post hooks by creating a backup. You can use the Ark logs to verify that the pre and post +Finally, remove Ark from restore only mode and test the pre and post hooks by creating a backup. You can use the Ark logs to verify that the pre and post hooks are running and exiting without error. - kubectl patch -n heptio-ark config default --type merge -p '{"restoreOnlyMode": false}' - ark backup create nginx-hook-test +```shell +kubectl patch -n heptio-ark config default --type merge -p '{"restoreOnlyMode": false}' +ark backup create nginx-hook-test - ark backup get nginx-hook-test - ark backup logs nginx-hook-test | grep hookCommand +ark backup get nginx-hook-test +ark backup logs nginx-hook-test | grep hookCommand +``` [1]: api-types/backup.md From 575c4ddc6d55d71ea493daeccf223118b20a9fe2 Mon Sep 17 00:00:00 2001 From: Wayne Witzel III Date: Mon, 27 Aug 2018 14:55:18 -0400 Subject: [PATCH 3/4] apply annotations on single line, no restore mode Signed-off-by: Wayne Witzel III --- docs/hooks.md | 23 ++++++----------------- 1 file changed, 6 insertions(+), 17 deletions(-) diff --git a/docs/hooks.md b/docs/hooks.md index ec0cea732..38fa8cfdf 100644 --- a/docs/hooks.md +++ b/docs/hooks.md @@ -59,29 +59,18 @@ setup this example. The Ark [example/nginx-app/with-pv.yaml][2] serves as an example of adding the pre and post hook annotations directly to your declarative deployment. Below is an example of what updating an object in place might look like. -Place Ark in restore only mode. This will prevent Ark backups from running while you are adding the -annotations and avoid the condition where the pre hook freezes the file system, but there is no -post hook setup to unfreeze it. - ```shell -kubectl patch -n heptio-ark config default --type merge -p '{"restoreOnlyMode": true}' +kubectl annotate pod -n nginx-example -l app=nginx \ + pre.hook.backup.ark.heptio.com/command='["/sbin/fsfreeze", "--freeze", "/var/log/nginx"]' \ + pre.hook.backup.ark.heptio.com/container=fsfreeze \ + post.hook.backup.ark.heptio.com/command='["/sbin/fsfreeze", "--unfreeze", "/var/log/nginx"]' \ + post.hook.backup.ark.heptio.com/container=fsfreeze ``` -Now you patch your pod with the required annotations. - -```shell -kubectl annotate pod -n nginx-example -l app=nginx pre.hook.backup.ark.heptio.com/command='["/sbin/fsfreeze", "--freeze", "/var/log/nginx"]' -kubectl annotate pod -n nginx-example -l app=nginx pre.hook.backup.ark.heptio.com/containr=fsfreeze - -kubectl annotate pod -n nginx-example -l app=nginx post.hook.backup.ark.heptio.com/command='["/sbin/fsfreeze", "--unfreeze", "/var/log/nginx"]' -kubectl annotate pod -n nginx-example -l app=nginx post.hook.backup.ark.heptio.com/containr=fsfreeze -``` - -Finally, remove Ark from restore only mode and test the pre and post hooks by creating a backup. You can use the Ark logs to verify that the pre and post +Now test the pre and post hooks by creating a backup. You can use the Ark logs to verify that the pre and post hooks are running and exiting without error. ```shell -kubectl patch -n heptio-ark config default --type merge -p '{"restoreOnlyMode": false}' ark backup create nginx-hook-test ark backup get nginx-hook-test From a8c42ab2458759a2206610973aacb9541b7a0fea Mon Sep 17 00:00:00 2001 From: Wayne Witzel III Date: Wed, 29 Aug 2018 16:15:03 -0400 Subject: [PATCH 4/4] fix GH md link Signed-off-by: Wayne Witzel III --- docs/hooks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/hooks.md b/docs/hooks.md index 38fa8cfdf..3d042b811 100644 --- a/docs/hooks.md +++ b/docs/hooks.md @@ -79,5 +79,5 @@ ark backup logs nginx-hook-test | grep hookCommand [1]: api-types/backup.md -[2]: https://github.com/heptio/ark/blob/master/examples/nginx-app/with-pv.yaml +[2]: examples/nginx-app/with-pv.yaml [3]: cloud-common.md