Cue documentation is missing practical aspects of using CUE as configuration language

[romange]

Based on what I saw https://cuelang.org/docs/ is mostly focused on theoretical aspects of the language.
It is pretty hard to project its features on real use-cases for engineers that are not experts in Jsonnet/GCL/HCL.

Specifically,

1. Based on github discussions I saw there are for and if constructs and maybe there are other features present, but I could not find them in the official docs. I would like to see list of features supported even with scarce/no documentation so I could know what to ask about in slack/github channels.

2. I would like to see practical examples that tackle use-cases of conditional configurations based on runtime arguments, similarly to this ytt example: https://github.com/romange/docker/blob/master/packer/provision/userdata.yml#L47
   There I generate yaml (or json) configurations using ytt conditional constructs from the same source configuration.

3. I saw that ytt has schema support as well. It would be interesting to see how cue compares to ytt.

[PierreR]

related to #1013

I would be interested in knowing how to define functional abstractions.

The most practical way we have found so far is to use templates to build a list keyed by ids:

For instance:

1. Client using the abstraction

_kibana: "\(_id)": {
	limits: memory: "4G"
	requests: cpu:  "1"
}

2. Abstraction akin to helm chart

_kibana: [ID=_]: {
	namespace: strings.Split(ID, "/")[2]
        ...
}

// everything you want to do to build a Kibana k8s resources
for id, v in _kibana {
	deployment: "\(id)/kibana": {
	....
}

3. Abstrations for resources

deployment: [_]: {
	kind:       "Deployment"
	spec: {
		template: spec: containers: [...{
			_env: [string]: string | {}
		}]
	}
}

for k,v in deployment {
	for c in v.spec.template.spec.containers {
		if len(c._env) > 0 {
			deployment: "\(k)" : spec: template: spec: containers: [ {
				env: [
					for x, y in c._env {
						if (y & string) != _|_ {name: x, value: y}
						if (y & {}) != _|_ {name: x, y}
					},
				]
			}]
		}}
}

This is simple enough and almost works (see #1134).

I would be interested in knowing other alternatives, ...

[myitcv]

@romange - thank you, documentation is one area that we know needs attention that we are looking to tackle in parallel to the primary focus of reaching language stability and a backwards compatibility in a v1.0.0 release.

As @PierreR points out above, #1013 will end up being the main focus of that effort. Until then, the language specification is the definitive source of language features, combined with parts of cuelang.org.

Please feel free to add comments/suggestions to #336 and #936.