Update Pre/Post hooks example.

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 <[email protected]>
+
+RUN apk add --no-cache ca-certificates
+RUN apk add --update --no-cache busybox util-linux
+
+ENTRYPOINT ["/bin/sh", "-c", "sleep infinity"]

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

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,49 @@ 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 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}'
+```
+
+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
+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
+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

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