doc/tutorial/kubernetes: tidy up and move to github.com/cue-examples

[cueckoo]

Originally opened by @myitcv in cuelang/cue#824

Here are the remaining TODOs following a recent review of the Kubernetes tutorial as part of https://cue-review.googlesource.com/c/cue/+/8961:

• the output from commands has gone a bit 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 tutorial still "works" it's just that a user following along might well, understandably, be thrown by discrepancies.

Fundamentally we need to fix the scenario where today, running CUE_UPDATE=1 go test ./... using Go 1.16 breaks by removing a series of files in doc/tutorial/kubernetes/quick/**/*.cue.

Ideally we fix this by making the tutorial a guide that is re-run with an appropriate Docker image using preguide. That however raises the question of whether the tutorial should continue to live as part of the main repo:

• re-running the guide each time will take some time
• however the guide is a good source of potential issues and so any diffs that result from a change in CUE are potentially of significance/interest and so catching these as early as possible would be best

We could/should use something like https://github.com/thetirefire/badidea for a minimal Kubernetes setup so that the guide can run kubectl

2022-05-19 update: progress being made over in https://github.com/cue-examples/kubernetes-tutorial.

[cueckoo]

Original reply by @pfiaux in cuelang/cue#824 (comment)

Hey, I'm not sure if this is the right place to post but I recently completed the tutorial (this weekend) and ran into a few issues. Let me know if I should create a separate issue instead.

There are the ones I remember, I looked at a few commits above and didn't see them sorry if I missed them.

The dump command uses --dry-run which spits out warning, changing it to --dry-run=client worked for me (kubectl 1.19).

After generating definitions from the go code and adding k8s_defs.cue I couldn't dump anymore (i.e. cue cmd dump ./frontend/maitred) I was getting something like this:

service.maitred.spec.ports.0.targetPort: conflicting values close(#IntOrString) and (*7080 | int) (mismatched types struct and int):
../cue.mod/gen/k8s.io/api/core/v1/types_go_gen.cue:4769:15
../cue.mod/gen/k8s.io/apimachinery/pkg/util/intstr/intstr_go_gen.cue:16:15
./kube.cue:83:16
From what I could see port is defined as int32 and targetPort int or string or fallback to port, the following changes to kube.cue worked for me:

import "k8s.io/apimachinery/pkg/util/intstr"
// ... rest of the code here
 				// Replacing the port definitions:
				port:       *Port | int32
				targetPort?: *Port | intstr.#IntOrString

[cueckoo]

Original reply by @myitcv in cuelang/cue#824 (comment)

Thanks @pfiaux. One of the challenges with the tutorial is that we do not, currently, faithfully execute each command as the user would. This issue is precisely about fixing it so that we do, in order that we don't run into problems of the sort you have reported.

One way of achieving that would be to re-run the tutorial within a docker container that has kubectl available. If you or anyone else has advice on a minimal Docker image that would allow us to do that, it would be greatly appreciated.

[cueckoo]

Original reply by @pfiaux in cuelang/cue#824 (comment)

From what I remember with dry run you don't actually need much from the cluster itself, just a connection (I think at the time I ran it against an empty minikube cluster i had locally). I've had some luck getting k3s/k3d (https://github.com/rancher/k3d) running locally, I haven't tried in a pipeline tho.

I'm not familiar with github actions would https://github.com/AbsaOSS/k3d-action be a possible solution?

There's also https://kind.sigs.k8s.io/ but image looks bigger and I have no idea how easy it is.

[cueckoo]

Original reply by @myitcv in cuelang/cue#824 (comment)

I've had some luck getting k3s/k3d (https://github.com/rancher/k3d) running locally, I haven't tried in a pipeline tho.

Thanks, this is useful. I just managed to get k3d working, to then call kubectl against it (all we need to do is invoke kubectl --dry-fun). So in theory, this will work as part of a preguide guide.

I'm not familiar with github actions would https://github.com/AbsaOSS/k3d-action be a possible solution?

I'm sure something like that works, yes, but we need something that will work client side here, in case changes need to be made to the tutorial. The k3d approach you suggested (or even minikube) sounds like it's the best way forwards.

Appreciate your suggestions!

[cueckoo]

Original reply by @myitcv in cuelang/cue#824 (comment)

Whilst waiting at the dentist (random, I realise) I made a bit more progress on this using k3d.

The Docker image I am using is defined here:

https://github.com/play-with-go/docker/tree/cue-kubernetes-tutorial/cue-kubernetes-tutorial

A partially converted guide can be found here:

https://github.com/play-with-go/play-with-go/blob/cue-kubernetes-tutorial/guides/2021-03-10-cue-kubernetes-tutorial/guide.cue

As an aide memoire, that guide can be regenerated via:

go run github.com/play-with-go/preguide/cmd/preguide gen -runargs 'term1=-v cue-kubernetes-tutorial:/var --privileged -e GOMODCACHE=/var/gomodcache -e GOCACHE=/var/gocache' -run kubernetes -out ../_posts

Proof that this setup works with kubectl can be found in the log:

https://github.com/play-with-go/play-with-go/blob/cue-kubernetes-tutorial/guides/2021-03-10-cue-kubernetes-tutorial/go115_en_log.txt

[myitcv]

Update: I've retitled this to better reflect the goal to move the Kubernetes tutorial outside of the main repo. A WIP translation to a preguide version can be found at https://github.com/cue-examples/kubernetes-tutorial

[mvdan]

I believe https://review.gerrithub.io/c/cue-lang/cue/+/1192692 and https://review.gerrithub.io/c/cue-lang/cuelang.org/+/1192689 resolved this issue :)