Add information about --record

slides/k8s/record.md

@@ -0,0 +1,169 @@
+# Recording deployment actions
+
+- Some commands that modify a Deployment accept an optional `--record` flag
+
+  (Example: `kubectl set image deployment worker worker=alpine --record`)
+
+- That flag will store the command line in the Deployment
+
+  (Technically, using the annotation `kubernetes.io/change-cause`)
+
+- It gets copied to the corresponding ReplicaSet
+
+  (Allowing to keep track of which command created or promoted this ReplicaSet)
+
+- We can view this information with `kubectl rollout history`
+
+---
+
+## Using `--record`
+
+- Let's make a couple of changes to a Deployment and record them
+
+.exercise[
+
+- Roll back `worker` to image version 0.1:
+  ```bash
+  kubectl set image deployment worker worker=dockercoins/worker:v0.1 --record
+  ```
+
+- Promote it to version 0.2 again:
+  ```bash
+  kubectl set image deployment worker worker=dockercoins/worker:v0.2 --record
+  ```
+
+- View the change history:
+  ```bash
+  kubectl rollout history deployment worker
+  ```
+
+]
+
+---
+
+## Pitfall #1: forgetting `--record`
+
+- What happens if we don't specify `--record`?
+
+.exercise[
+
+- Promote `worker` to image version 0.3:
+  ```bash
+  kubectl set image deployment worker worker=dockercoins/worker:v0.3
+  ```
+
+- View the change history:
+  ```bash
+  kubectl rollout history deployment worker
+  ```
+
+]
+
+--
+
+It recorded version 0.2 instead of 0.3! Why?
+
+---
+
+## How `--record` really works
+
+- `kubectl` adds the annotation `kubernetes.io/change-cause` to the Deployment
+
+- The Deployment controller copies that annotation to the ReplicaSet
+
+- `kubectl rollout history` shows the ReplicaSets' annotations
+
+- If we don't specify `--record`, the annotation is not updated
+
+- The previous value of that annotation is copied to the new ReplicaSet
+
+- In that case, the ReplicaSet annotation does not reflect reality!
+
+---
+
+## Pitfall #2: recording `scale` commands
+
+- What happens if we use `kubectl scale --record`?
+
+.exercise[
+
+- Check the current history:
+  ```bash
+  kubectl rollout history deployment worker
+  ```
+
+- Scale the deployment:
+  ```bash
+  kubectl scale deployment worker --replicas=3 --record
+  ```
+
+- Check the change history again:
+  ```bash
+  kubectl rollout history deployment worker
+  ```
+
+]
+
+--
+
+The last entry in the history was overwritten by the `scale` command! Why?
+
+---
+
+## Actions that don't create a new ReplicaSet
+
+- The `scale` command updates the Deployment definition
+
+- But it doesn't create a new ReplicaSet
+
+- Using the `--record` flag sets the annotation like before
+
+- The annotation gets copied to the existing ReplicaSet
+
+- This overwrites the previous annotation that was there
+
+- In that case, we lose the previous change cause!
+
+---
+
+## Updating the annotation directly
+
+- Let's see what happens if we set the annotation manually
+
+.exercise[
+
+- Annotate the Deployment:
+  ```bash
+  kubectl annotate deployment worker kubernetes.io/change-cause="Just for fun"
+  ```
+
+- Check that our annotation shows up in the change history:
+  ```bash
+  kubectl rollout history deployment worker
+  ```
+
+]
+
+--
+
+Our annotation shows up (and overwrote whatever was there before).
+
+---
+
+## Using change cause
+
+- It sounds like a good idea to use `--record`, but:
+
+  *"Incorrect documentation is often worse than no documentation."*
+  <br/>
+  (Bertrand Meyer)
+
+- If we use `--record` once, we need to either:
+
+  - use it every single time after that
+
+  - or clear the Deployment annotation after using `--record`
+    <br/>
+    (subsequent changes will show up with a `<none>` change cause)
+
+- A safer way is to set it through our tooling

slides/k8s/rollout.md

@@ -265,6 +265,8 @@ Note the `3xxxx` port.
 
 ---
 
+class: extra-details
+
 ## Changing rollout parameters
 
 - We want to:
@@ -294,6 +296,8 @@ spec:
 
 ---
 
+class: extra-details
+
 ## Applying changes through a YAML patch
 
 - We could use `kubectl edit deployment worker`

slides/kube-fullday.yml

@@ -48,6 +48,7 @@ chapters:
   - shared/hastyconclusions.md
   - k8s/daemonset.md
 - - k8s/rollout.md
+  #- k8s/record.md
   - k8s/namespaces.md
   #- k8s/kustomize.md
   #- k8s/helm.md

slides/kube-halfday.yml

@@ -51,6 +51,7 @@ chapters:
   - shared/hastyconclusions.md
   - k8s/daemonset.md
   - k8s/rollout.md
+  #- k8s/record.md
 - - k8s/logs-cli.md
 # Bridget hasn't added EFK yet
   #- k8s/logs-centralized.md

slides/kube-selfpaced.yml

@@ -48,6 +48,7 @@ chapters:
 #  - shared/hastyconclusions.md
   - k8s/daemonset.md
   - k8s/rollout.md
+  - k8s/record.md
   - k8s/namespaces.md
 - - k8s/kustomize.md
   - k8s/helm.md

slides/kube-twodays.yml

@@ -48,6 +48,7 @@ chapters:
   - shared/hastyconclusions.md
 - - k8s/daemonset.md
   - k8s/rollout.md 
+  - k8s/record.md
   - k8s/namespaces.md
   - k8s/kustomize.md
   #- k8s/helm.md