docs: More comments for dagger code

Signed-off-by: Ross Fairbanks <[email protected]>

main.go

@@ -61,6 +61,7 @@ func (m *GreenReviewsTooling) BenchmarkPipelineTest(ctx context.Context,
 	}
 
 	if kubeconfig == "" {
+		// This is a new k3s container so bootstrap flux and the monitoring stack.
 		_, err = p.SetupCluster(ctx)
 		if err != nil {
 			return nil, err
@@ -103,18 +104,22 @@ func (m *GreenReviewsTooling) Terminal(ctx context.Context,
 	return p.Terminal(ctx)
 }
 
+// newPipeline creates a new benchmark pipeline.
 func newPipeline(ctx context.Context, source *dagger.Directory, kubeconfig string) (*pipeline.Pipeline, error) {
 	var configFile *dagger.File
 	var err error
 
 	container := build(source)
 
 	if kubeconfig == "" {
+		// No kubeconfig so start a new k3s container using the k3s dagger
+		// module. See https://daggerverse.dev/mod/github.com/marcosnils/daggerverse/k3s
 		configFile, err = startK3sCluster(ctx)
 		if err != nil {
 			return nil, err
 		}
 	} else {
+		// Connect to an existing cluster via a kubeconfig.
 		configFile, err = getKubeconfig(kubeconfig)
 		if err != nil {
 			return nil, err
@@ -124,6 +129,8 @@ func newPipeline(ctx context.Context, source *dagger.Directory, kubeconfig strin
 	return pipeline.New(container, source, configFile)
 }
 
+// build builds a container image from the Dockerfile with any CLIs needed by
+// the pipeline such as kubectl.
 func build(src *dagger.Directory) *dagger.Container {
 	return dag.Container().
 		WithDirectory(sourceDir, src).
@@ -133,6 +140,7 @@ func build(src *dagger.Directory) *dagger.Container {
 		WithWorkdir(sourceDir)
 }
 
+// getKubeconfig returns a dagger file object pointing as the cluster kubeconfig.
 func getKubeconfig(configFilePath string) (*dagger.File, error) {
 	contents, err := os.ReadFile(configFilePath)
 	if err != nil {
@@ -144,6 +152,8 @@ func getKubeconfig(configFilePath string) (*dagger.File, error) {
 	return dir.File(filePath), nil
 }
 
+// startK3sCluster starts a new k3s container using the k3s dagger module and
+// returns its kubeconfig.
 func startK3sCluster(ctx context.Context) (*dagger.File, error) {
 	k3s := dag.K3S(clusterName)
 	kServer := k3s.Server()

pkg/pipeline/benchmark.go

@@ -25,6 +25,8 @@ const (
 	versionPlaceholder    = "$VERSION"
 )
 
+// Pipeline contains dagger objects that store the state of the pipeline and
+// allow it to interact with the dagger container.
 type Pipeline struct {
 	container  *dagger.Container
 	kubeconfig *dagger.File
@@ -64,6 +66,8 @@ func (p *Pipeline) Terminal(ctx context.Context) (*dagger.Container, error) {
 	return p.withKubeconfig().Terminal(), nil
 }
 
+// benchmark creates the CNCF project resource, applies the benchmark tests and
+// waits for the benchmark to complete.
 func (p *Pipeline) benchmark(ctx context.Context,
 	cncfProject,
 	config,
@@ -98,6 +102,7 @@ func (p *Pipeline) benchmark(ctx context.Context,
 	return p.container, nil
 }
 
+// delete cleans up the cluster at the end of the pipeline run.
 func (p *Pipeline) delete(ctx context.Context, cncfProject, config, benchmarkJobURL string) (*dagger.Container, error) {
 	// Delete benchmark job resources.
 	if _, err := p.exec(ctx, cmd.Delete(benchmarkJobURL)); err != nil {
@@ -117,6 +122,7 @@ func (p *Pipeline) delete(ctx context.Context, cncfProject, config, benchmarkJob
 	return p.container, nil
 }
 
+// deploy deploys the CNCF project by applying the flux manifest.
 func (p *Pipeline) deploy(ctx context.Context, cncfProject, config, version string) (*dagger.Container, error) {
 	fileName, fileContents, err := p.getManifestFile(ctx, cncfProject, config, version)
 	if err != nil {
@@ -148,12 +154,15 @@ func (p *Pipeline) echo(ctx context.Context, msg string) (string, error) {
 		Stderr(ctx)
 }
 
+// exec configures the container with the kubeconfig and executes a command.
 func (p *Pipeline) exec(ctx context.Context, args []string) (string, error) {
 	return p.withKubeconfig().
 		WithExec(args).
 		Stdout(ctx)
 }
 
+// execWithDir is the same as exec but mounts a directory so manifests can be
+// applied.
 func (p *Pipeline) execWithDir(ctx context.Context, manifestPath string, args []string) (string, error) {
 	dirPath := path.Dir(manifestPath)
 	dir := p.source.Directory(dirPath)
@@ -163,13 +172,16 @@ func (p *Pipeline) execWithDir(ctx context.Context, manifestPath string, args []
 		Stdout(ctx)
 }
 
+// execWithNewFile is the same as exec but mounts a manifest file so it can be
+// applied.
 func (p *Pipeline) execWithNewFile(ctx context.Context, name, contents string, args []string) (string, error) {
 	return p.withKubeconfig().
 		WithNewFile(name, contents).
 		WithExec(args).
 		Stdout(ctx)
 }
 
+// getManifestFile gets the manifest and ensures the version is correct.
 func (p *Pipeline) getManifestFile(ctx context.Context, project, config, version string) (string, string, error) {
 	manifestPath := getManifestPath(project, config)
 	manifest, err := p.source.File(manifestPath).Contents(ctx)
@@ -180,14 +192,17 @@ func (p *Pipeline) getManifestFile(ctx context.Context, project, config, version
 	return manifestFilename, strings.ReplaceAll(manifest, versionPlaceholder, version), nil
 }
 
+// withKubeconfig adds the kubeconfig to the dagger container.
 func (p *Pipeline) withKubeconfig() *dagger.Container {
 	return p.container.
-		// Bust cache to ensure commands are run.
+		// Bust cache with dynamic value to ensure layers are rebuilt and
+		// commands are not cached by container engine.
 		WithEnvVariable(bustCacheEnvVar, time.Now().String()).
 		WithEnvVariable(kubeconfigEnvVar, KubeconfigPath).
 		WithFile(KubeconfigPath, p.kubeconfig)
 }
 
+// getManifestPath get the correct path in the projects dir.
 func getManifestPath(project, config string) string {
 	if config == "" {
 		config = project

pkg/pipeline/setup_cluster.go

@@ -60,6 +60,8 @@ func (p *Pipeline) SetupCluster(ctx context.Context) (*dagger.Container, error)
 	return p.container, nil
 }
 
+// getNodeName gets the name of the cluster node. In CI all clusters are single
+// node.
 func (p *Pipeline) getNodeName(ctx context.Context) (string, error) {
 	stdout, err := p.exec(ctx, cmd.GetNodeNames())
 	if err != nil {
@@ -74,6 +76,7 @@ func (p *Pipeline) getNodeName(ctx context.Context) (string, error) {
 	return parts[0], nil
 }
 
+// clusterManifests are applied to bootstrap the monitoring stack.
 func clusterManifests() []string {
 	return []string{
 		// Namespace must be created first for dependencies.
@@ -99,6 +102,7 @@ func localSetupPatches() [][]string {
 	}
 }
 
+// nodeLabels are added to ensure they match label selectors in k8s manifests.
 func nodeLabels() map[string]string {
 	return map[string]string{
 		"cncf-project":                      "wg-green-reviews",