✍️ Add details about how to author YAML

slides/k8s/authoring-yaml.md

@@ -1,6 +1,6 @@
 # Authoring YAML
 
-- There are various ways to generate YAML with Kubernetes, e.g.:
+- We have already generated YAML implicitly, with e.g.:
 
   - `kubectl run`
 
@@ -32,26 +32,63 @@
 
 ---
 
-## We don't have to start from scratch
+## Various ways to write YAML
 
-- Create a resource (e.g. Deployment)
+- Completely from scratch with our favorite editor
 
-- Dump its YAML with `kubectl get -o yaml ...`
+  (yeah, right)
 
-- Edit the YAML
+- Dump an existing resource with `kubectl get -o yaml ...`
 
-- Use `kubectl apply -f ...` with the YAML file to:
+  (it is recommended to clean up the result)
 
-  - update the resource (if it's the same kind)
+- Ask `kubectl` to generate the YAML
 
-  - create a new resource (if it's a different kind)
+  (with a `kubectl create --dry-run -o yaml`)
 
-- Or: Use The Docs, Luke
+- Use The Docs, Luke
 
   (the documentation almost always has YAML examples)
 
 ---
 
+## Generating YAML from scratch
+
+- Start with a namespace:
+  ```yaml
+    kind: Namespace
+    apiVersion: v1
+    metadata:
+      name: hello
+  ```
+
+- We can use `kubectl explain` to see resource definitions:
+  ```bash
+  kubectl explain -r pod.spec
+  ```
+
+- Not the easiest option!
+
+---
+
+## Dump the YAML for an existing resource
+
+- `kubectl get -o yaml` works!
+
+- A lot of fields in `metadata` are not necessary
+
+  (`managedFields`, `resourceVersion`, `uid`, `creationTimestamp` ...)
+
+- Most objects will have a `status` field that is not necessary
+
+- Default or empty values can also be removed for clarity
+
+- This can be done manually or with the `kubectl-neat` plugin
+
+  `kubectl get -o yaml ... | kubectl neat`
+
+---
+
 ## Generating YAML without creating resources
 
 - We can use the `--dry-run` option
@@ -63,14 +100,18 @@
   kubectl create deployment web --image nginx --dry-run
   ```
 
+- Optionally clean it up with `kubectl neat`, too
+
 ]
 
-- We can clean up that YAML even more if we want
+Note: in recent versions of Kubernetes, we should use `--dry-run=client`
 
-  (for instance, we can remove the `creationTimestamp` and empty dicts)
+(Or `--dry-run=server`; more on that later!)
 
 ---
 
+class: extra-details
+
 ## Using `--dry-run` with `kubectl apply`
 
 - The `--dry-run` option can also be used with `kubectl apply`
@@ -87,6 +128,8 @@
 
 ---
 
+class: extra-details
+
 ## The limits of `kubectl apply --dry-run`
 
 .exercise[
@@ -112,6 +155,8 @@ The resulting YAML doesn't represent a valid DaemonSet.
 
 ---
 
+class: extra-details
+
 ## Server-side dry run
 
 - Since Kubernetes 1.13, we can use [server-side dry run and diffs](https://kubernetes.io/blog/2019/01/14/apiserver-dry-run-and-kubectl-diff/)
@@ -135,6 +180,8 @@ Instead, it has the fields expected in a DaemonSet.
 
 ---
 
+class: extra-details
+
 ## Advantages of server-side dry run
 
 - The YAML is verified much more extensively
@@ -149,6 +196,8 @@ Instead, it has the fields expected in a DaemonSet.
 
 ---
 
+class: extra-details
+
 ## `kubectl diff`
 
 - Kubernetes 1.13 also introduced `kubectl diff`
@@ -209,3 +258,8 @@ Note: we don't need to specify `--validate=false` here.
   - check that it still works!
 
 - That YAML will be useful later when using e.g. Kustomize or Helm
+
+???
+
+:EN:- Techniques to write YAML manifests
+:FR:- Comment écrire des *manifests* YAML

slides/kube-fullday.yml

@@ -64,7 +64,7 @@ content:
   - k8s/scalingdockercoins.md
   - shared/hastyconclusions.md
   - k8s/daemonset.md
-  #- k8s/dryrun.md
+  #- k8s/authoring-yaml.md
   #- k8s/exercise-yaml.md
   #- k8s/localkubeconfig.md
   #- k8s/accessinternal.md

slides/kube-selfpaced.yml

@@ -65,7 +65,7 @@ content:
   - k8s/scalingdockercoins.md
   - shared/hastyconclusions.md
   - k8s/daemonset.md
-  - k8s/dryrun.md
+  - k8s/authoring-yaml.md
   #- k8s/exercise-yaml.md
 -
   - k8s/rollout.md

slides/kube-twodays.yml

@@ -64,7 +64,7 @@ content:
   - k8s/scalingdockercoins.md
   - shared/hastyconclusions.md
   - k8s/daemonset.md
-  - k8s/dryrun.md
+  - k8s/authoring-yaml.md
   #- k8s/exercise-yaml.md
 -
   - k8s/localkubeconfig.md