doc: fix up k8s tutorial

Over time the Kubernetes tutorial has gone a bit stale: * the output from commands has gone stale; * we have larger diffs than expected in some situations; * we are not asserting the success of each step, which means that steps can fail and it go unnoticed; * we are not re-running the tutorial as part of CI; * we are not running the entire tutorial, we skip certain commands; * the tests in doc/tutorial/kubernetes pass even when critical files are missing (again because we ignore the exit code of all commands we run). The ultimate fix is to migrate to a living tutorial at: https://github.com/cue-examples/kubernetes-tutorial (which follows the same pattern as our FOSDEM 2022 talk). For now, this CL patches things up to reduce the diffs between what the end user sees in real life and the guide. Changes include: * reordering of original YAML inputs so that the first the first trim (effectively a key part of the ) For #824 Signed-off-by: Paul Jolly <paul@myitcv.io> Change-Id: Ie965fd24d710da69b18f0108e5415e6321859f8d
cue-lang · Feb 18, 2022 · cb58929 · cb58929
1 parent 65ff0f4
commit cb58929
Show file tree

Hide file tree

Showing 37 changed files with 247 additions and 233 deletions.
diff --git a/doc/tutorial/kubernetes/README.md b/doc/tutorial/kubernetes/README.md
@@ -92,15 +92,15 @@ into CUE.
 ```
 $ cd services
 $ cue import ./...
-must specify package name with the -p flag
+path, list, or files flag needed to handle multiple objects in file ./services/frontend/bartender/kube.yaml
 ```
 
 Since we have multiple packages and files, we need to specify the package to
 which they should belong.
 
 ```
 $ cue import ./... -p kube
-path, list, or files flag needed to handle multiple objects in file "./frontend/bartender/kube.yaml"
+path, list, or files flag needed to handle multiple objects in file ./services/frontend/bartender/kube.yaml
 ```
 
 Many of the files contain more than one Kubernetes object.
@@ -334,17 +334,17 @@ other a user of the template will want to specify.
 
 Let's compare the result of merging our new template to our original snapshot.
 
+<!-- TODO: fix error output below once https://cuelang.org/issues/1533 is fixed -->
+
 ```
 $ cue eval ./... -c > snapshot2
---- ./mon/alertmanager
-service.alertmanager.metadata.labels.component: incomplete value (string):
-    ./kube.cue:11:24
-service.alertmanager.spec.selector.component: incomplete value (string):
-    ./kube.cue:11:24
-deployment.alertmanager.spec.template.metadata.labels.component: incomplete value (string):
-    ./kube.cue:36:28
-service."node-exporter".metadata.labels.component: incomplete value (string):
-    ./kube.cue:11:24
+// /workdir/services/mon/alertmanager
+deployment.alertmanager.spec.template.metadata.labels.component: incomplete value string
+service.alertmanager.metadata.labels.component: incomplete value string
+service.alertmanager.spec.selector.component: incomplete value string
+// /workdir/services/mon/nodeexporter
+service."node-exporter".metadata.labels.component: incomplete value string
+service."node-exporter".spec.selector.component: incomplete value string
 ...
 ```
 
@@ -370,7 +370,8 @@ EOF
 
 ```
 # set the component label to our new top-level field
-$ sed -i.bak 's/component:.*string/component: #Component/' kube.cue && rm kube.cue.bak
+$ sed -i.bak 's/component:.*string/component: #Component/' kube.cue
+$ rm kube.cue.bak
 
 # add the new top-level field to our previous template definitions
 $ cat <<EOF >> kube.cue
@@ -406,11 +407,12 @@ $ cp snapshot2 snapshot
 The corresponding boilerplate can now be removed with `cue trim`.
 
 ```
-$ find . | grep kube.cue | xargs wc | tail -1
+$ find . | grep kube.cue | xargs wc -l | tail -1
     1792    3616   34815 total
+ 1887 total
 $ cue trim ./...
-$ find . | grep kube.cue | xargs wc | tail -1
-    1223    2374   22903 total
+$ find . | grep kube.cue | xargs wc -l | tail -1
+ 1312 total
 ```
 
 `cue trim` removes configuration from files that is already generated
@@ -421,8 +423,8 @@ The following is proof that nothing changed semantically:
 
 ```
 $ cue eval -c ./... > snapshot2
-$ diff snapshot snapshot2 | wc
-       0       0       0
+$ diff snapshot snapshot2 | wc -l
+0
 ```
 
 We can do better, though.
@@ -571,8 +573,8 @@ Then we run trim to further reduce our configuration:
 
 ```
 $ cue trim ./...
-$ find . | grep kube.cue | xargs wc | tail -1
-    1129    2270   22073 total
+$ find . | grep kube.cue | xargs wc -l | tail -1
+ 1242 total
 ```
 This is after removing the rewritten and now redundant deployment definition.
 
@@ -606,14 +608,21 @@ deployment: breaddispatcher: spec: template: {
         "prometheus.io.scrape": "true"
         "prometheus.io.port":   "7080"
     }
-$ find . | grep kube.cue | xargs wc | tail -1
-     975    2116   20264 total
+$ find . | grep kube.cue | xargs wc -l | tail -1
+ 1090 total
 ```
 
 Another 150 lines lost!
 Collapsing lines like this can improve the readability of a configuration
 by removing considerable amounts of punctuation.
 
+We save the result as the new baseline:
+
+```
+cue eval -c ./... > snapshot2
+cp snapshot2 snapshot
+```
+
 
 ### Repeat for several subdirectories
 
@@ -650,27 +659,48 @@ $ cue fmt ./frontend
 
 # check differences
 $ cue eval -c ./... > snapshot2
-$ diff snapshot snapshot2
-368a369
->                             prometheus.io.port:   "7080"
-577a579
->                             prometheus.io.port:   "8080"
+$ diff -wu snapshot snapshot2
+--- snapshot	2022-02-18 11:47:53.480063388 +0000
++++ snapshot2	2022-02-18 11:47:54.444165162 +0000
+@@ -188,6 +188,7 @@
+                 metadata: {
+                     annotations: {
+                         "prometheus.io.scrape": "true"
++                        "prometheus.io.port":   "7080"
+                     }
+                     labels: {
+                         app:       "host"
+@@ -327,6 +328,7 @@
+                 metadata: {
+                     annotations: {
+                         "prometheus.io.scrape": "true"
++                        "prometheus.io.port":   "8080"
+                     }
+                     labels: {
+                         app:       "valeter"
 $ cp snapshot2 snapshot
 ```
 
 Two lines with annotations added, improving consistency.
 
 ```
 $ cue trim -s ./frontend/...
-$ find . | grep kube.cue | xargs wc | tail -1
-     931    2052   19624 total
+$ find . | grep kube.cue | xargs wc -l | tail -1
+ 1046 total
 ```
 
-Another 40 lines removed.
+Another 40 odd lines removed.
 We may have gotten used to larger reductions, but at this point there is just
 not much left to remove: in some of the frontend files there are only 4 lines
 of configuration left.
 
+We save the result as the new baseline:
+
+```
+cue eval -c ./... > snapshot2
+cp snapshot2 snapshot
+```
+
 
 #### Directory `kitchen`
 
@@ -781,7 +811,7 @@ $ find . | grep kube.cue | xargs wc | tail -1
      807    1862   17190 total
 ```
 
-The diff shows that we added the `_hadDisks` option, but otherwise reveals no
+The diff shows that we added the `_hasDisks` option, but otherwise reveals no
 differences.
 We also reduced the configuration by a sizeable amount once more.
 

diff --git a/doc/tutorial/kubernetes/original/services/frontend/bartender/kube.yaml b/doc/tutorial/kubernetes/original/services/frontend/bartender/kube.yaml
@@ -3,19 +3,19 @@ kind: Service
 metadata:
   name: bartender
   labels:
-    component: frontend
     app: bartender
     domain: prod
+    component: frontend
 spec:
   ports:
   - port: 7080
-    targetPort: 7080
     protocol: TCP
+    targetPort: 7080
     name: client
   selector:
-    component: frontend
     app: bartender
     domain: prod
+    component: frontend
 ---
 apiVersion: apps/v1
 kind: Deployment
@@ -25,18 +25,18 @@ spec:
   replicas: 1
   template:
     metadata:
-      labels:
-        component: frontend
-        app: bartender
-        domain: prod
       annotations:
         prometheus.io.scrape: "true"
         prometheus.io.port: "7080"
+      labels:
+        app: bartender
+        domain: prod
+        component: frontend
     spec:
       containers:
-      - name: bartender
-        image: gcr.io/myproj/bartender:v0.1.34
+      - image: gcr.io/myproj/bartender:v0.1.34
         ports:
         - containerPort: 7080
+        name: bartender
         args: [
         ]
diff --git a/doc/tutorial/kubernetes/original/services/frontend/breaddispatcher/kube.yaml b/doc/tutorial/kubernetes/original/services/frontend/breaddispatcher/kube.yaml
@@ -4,18 +4,18 @@ metadata:
   name: breaddispatcher
   labels:
     app: breaddispatcher
-    component: frontend
     domain: prod
+    component: frontend
 spec:
   ports:
   - port: 7080
-    targetPort: 7080
     protocol: TCP
+    targetPort: 7080
     name: client
   selector:
     app: breaddispatcher
-    component: frontend
     domain: prod
+    component: frontend
 ---
 apiVersion: apps/v1
 kind: Deployment
@@ -25,19 +25,19 @@ spec:
   replicas: 1
   template:
     metadata:
-      labels:
-        app: breaddispatcher
-        component: frontend
-        domain: prod
       annotations:
         prometheus.io.scrape: "true"
         prometheus.io.port: "7080"
+      labels:
+        app: breaddispatcher
+        domain: prod
+        component: frontend
     spec:
       containers:
-      - name: breaddispatcher
-        image: gcr.io/myproj/breaddispatcher:v0.3.24
+      - image: gcr.io/myproj/breaddispatcher:v0.3.24
         ports:
         - containerPort: 7080
+        name: breaddispatcher
         args: [
           "-etcd=etcd:2379",
           "-event-server=events:7788",

diff --git a/doc/tutorial/kubernetes/original/services/frontend/host/kube.yaml b/doc/tutorial/kubernetes/original/services/frontend/host/kube.yaml
@@ -4,18 +4,18 @@ metadata:
   name: host
   labels:
     app: host
-    component: frontend
     domain: prod
+    component: frontend
 spec:
   ports:
   - port: 7080
-    targetPort: 7080
     protocol: TCP
+    targetPort: 7080
     name: client
   selector:
     app: host
-    component: frontend
     domain: prod
+    component: frontend
 ---
 apiVersion: apps/v1
 kind: Deployment
@@ -25,17 +25,17 @@ spec:
   replicas: 2
   template:
     metadata:
+      annotations:
+        prometheus.io.scrape: "true"
       labels:
         app: host
-        component: frontend
         domain: prod
-      annotations:
-        prometheus.io.scrape: "true"
+        component: frontend
     spec:
       containers:
-      - name: host
-        image: gcr.io/myproj/host:v0.1.10
+      - image: gcr.io/myproj/host:v0.1.10
         ports:
         - containerPort: 7080
+        name: host
         args: [
         ]
diff --git a/doc/tutorial/kubernetes/original/services/frontend/maitred/kube.yaml b/doc/tutorial/kubernetes/original/services/frontend/maitred/kube.yaml
@@ -4,13 +4,13 @@ metadata:
   name: maitred
   labels:
     app: maitred
-    component: frontend
     domain: prod
+    component: frontend
 spec:
   ports:
   - port: 7080
-    targetPort: 7080
     protocol: TCP
+    targetPort: 7080
     name: client
   selector:
     app: maitred
@@ -24,18 +24,18 @@ spec:
   replicas: 1
   template:
     metadata:
-      labels:
-        app: maitred
-        component: frontend
-        domain: prod
       annotations:
         prometheus.io.scrape: "true"
         prometheus.io.port: "7080"
+      labels:
+        app: maitred
+        domain: prod
+        component: frontend
     spec:
       containers:
-      - name: maitred
-        image: gcr.io/myproj/maitred:v0.0.4
+      - image: gcr.io/myproj/maitred:v0.0.4
         ports:
         - containerPort: 7080
+        name: maitred
         args: [
         ]