doc: some doc improvements
Change-Id: Iba972438cf0bed8a845c1f4d4ddbbbb59ba35f71
diff --git a/README.md b/README.md
index 32a67ec..43774f3 100644
--- a/README.md
+++ b/README.md
@@ -29,7 +29,7 @@
The CUE tooling also provides integrated declarative scripting
aimed at simplifying putting configurations to good use while
-giving static analyis tools maximum domain knowledge.
+giving static analysis tools maximum domain knowledge.
Some highlights:
diff --git a/doc/tutorial/kubernetes/README.md b/doc/tutorial/kubernetes/README.md
index 0dd9789..3cfd06f 100644
--- a/doc/tutorial/kubernetes/README.md
+++ b/doc/tutorial/kubernetes/README.md
@@ -213,17 +213,12 @@
of configurations.
Manual tailoring will usually give better results, but takes considerably
more thought, while taking the quick and dirty approach gets you mostly there.
-The steps presented here also help to create a manual config
+The result of such a quick conversion also forms a good basis for
+a more thoughtful manual optimization.
### Create top-level template
Now we have imported the YAML files we can start the simplification process.
-Let's focus on the objects defined in the various `kube.cue` files.
-
-```
-$ find . | grep kube.cue | xargs cat | wc
- 1733 3444 33615
-```
Before we start the restructuring, lets save a full evaluation so that we
can verify that simplifications yield the same results.
@@ -232,6 +227,7 @@
$ cue eval ./... > snapshot
```
+We focus on the objects defined in the various `kube.cue` files.
A quick inspection reveals that many of the Deployments and Services share
common structure.
@@ -243,7 +239,6 @@
```
Modify this file as below.
-Comments are added just as an explanation and can be omitted.
```
$ cat <<EOF > kube.cue
@@ -253,7 +248,7 @@
apiVersion: "v1"
kind: "Service"
metadata: {
- name: Name // as per the cue import command this is the field name
+ name: Name
labels: {
app: Name // by convention
domain: "prod" // always the same in the given files
@@ -274,7 +269,7 @@
deployment <Name>: {
apiVersion: "extensions/v1beta1"
kind: "Deployment"
- metadata name: Name // by the cue import command the same as the field name
+ metadata name: Name
spec: {
// 1 is the default, but we allow any number
replicas: 1 | int
@@ -294,15 +289,20 @@
By replacing the service and deployment name with `<Name>` we have changed the
definition into a template.
-Templates are applied to (are unified with) all entries in the struct in which
-they are defined.
-So we need to strip all fields specific to the `breaddispatcher` definition.
+CUE bind the field name to `Name` as a result.
+During importing we used `metadata.data` as a key for the object names,
+so we can now set this field to `Name`.
-We also generalized some fields: it seems that each Kubernets object in our
-config file has a component label corresponding to the directory in which
-it is defined.
+Templates are applied to (are unified with) all entries in the struct in which
+they are defined,
+so we need to either strip fields specific to the `breaddispatcher` definition,
+generalize them, or remove them.
+
+One of the labels defined in the Kubernetes metadata seems to be always set
+to parent directory name.
We enforce this by defining `component: string`, meaning that a field
-of name `component` must be set to some string value.
+of name `component` must be set to some string value, and then define this
+later on.
Any underspecified field results in an error when converting to, for instance,
JSON.
So a deployment or service will only be valid if this label is defined.
@@ -1029,18 +1029,6 @@
In the next sections we will show how to get there.
-### Getting started
-
-Setup a new directory with a copy of the original data and save a snapshot.
-
-```
-$ cp -a testdata tmp2
-$ cd tmp2/services
-$ cue import ./... -p kube -l '"\(strings.ToCamel(kind))" "\(metadata.name)"' -fR
-# cue eval ./... > snapshot
-```
-
-
### Outline
The basic premis of our configuration is to maintain two configurations,
@@ -1159,10 +1147,6 @@
All other fields that we way want to define can go into a generic kubernetes
struct that gets merged in with all other generated kubernetes data.
-
-```
- kubernetes: {}
-```
This even allows us to augment generated data, such as adding additional
fields to the container.
@@ -1189,6 +1173,48 @@
} for k, spec in deployment
```
+The complete top-level model definitions can be found at
+[doc/tutorial/kubernetes/manual/services/cloud.cue](https://cue.googlesource.com/cue/+/master/doc/tutorial/kubernetes/manual/services/cloud.cue).
+
+The tailorings for this specific project (the labels) are defined
+[here](https://cue.googlesource.com/cue/+/master/doc/tutorial/kubernetes/manual/services/kube.cue).
+
+
+### Converting to Kubernetes
+
+Converting services is fairly straightforward.
+
+```
+kubernetes services: {
+ "\(k)": x.kubernetes & {
+ apiVersion: "v1"
+ kind: "Service"
+
+ metadata name: x.name
+ metadata labels: x.label
+ spec selector: x.label
+
+ spec ports: [ p for p in x.port ]
+ } for k, x in service
+}
+```
+
+We add the Kubernetes boilerplate, map the top-level fields and mix in
+the raw `kubernetes` fields for each service.
+
+Mapping deployments is a bit more involved, though analogous.
+The complete definitions for Kubernetes conversions can be found at
+[doc/tutorial/kubernetes/manual/services/k8s.cue](https://cue.googlesource.com/cue/+/master/doc/tutorial/kubernetes/manual/services/k8s.cue).
+
+Converting the top-level definitions to concrete Kubernetes code is the hardest
+part of this exercise.
+That said, most CUE users will never have to resort to this level of CUE
+to write configurations.
+For instance, none of the files in the subdirectories contain comprehensions,
+not even the template files in these directores (such as `kitchen/kube.cue`).
+
+
+
### Metrics
