feat(cli): add 'local mirror list' and 'cluster portal export', label educates containers

Add two commands, reimplemented against this branch (the referenced
PR educates#871 is a divergent refactor on a different architecture and is not
directly portable):

- 'educates local mirror list' lists the deployed local registry mirrors
  as a table (name, URL, username, status, container name).
- 'educates cluster portal export' exports a training portal and the
  workshops it references as sanitised, re-appliable Kubernetes YAML —
  to stdout as one stream, or with --as-files one file per resource.
  The --image-repository / --workshop-version options substitute the
  $(image_repository) / $(workshop_version) variables in the workshops.

Give every container Educates creates via the Docker client a consistent
set of educates.dev/* labels so they can be discovered, filtered, and
cleaned up by label rather than by container name:

- New pkg/constants holds the educates.dev/{app,role,mirror,url,username}
  keys and the registry/mirror/resolver role values.
- The registry and mirror containers move to the namespaced keys (mirrors
  now also carry url/username); the resolver container, which previously
  had no labels, is labelled app=educates role=resolver.
- ListRegistryMirrors and the bulk-delete path share one label filter.

The kind node container is created by the kind library and keeps its own
io.x-k8s.kind.* labels; it stays discovered by its well-known name.

Author: jorgemoralespou

client-programs/pkg/cmd/cluster_portal_cmd_group.go

@@ -25,6 +25,7 @@ func (p *ProjectInfo) NewClusterPortalCmdGroup() *cobra.Command {
 				p.NewClusterPortalOpenCmd(),
 				p.NewClusterPortalDeleteCmd(),
 				p.NewClusterPortalPasswordCmd(),
+				p.NewClusterPortalExportCmd(),
 			},
 		},
 	}

client-programs/pkg/cmd/cluster_portal_export_cmd.go

@@ -0,0 +1,198 @@
+package cmd
+
+import (
+	"context"
+
+	"github.com/pkg/errors"
+	"github.com/spf13/cobra"
+	k8serrors "k8s.io/apimachinery/pkg/api/errors"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
+	"k8s.io/client-go/dynamic"
+
+	"github.com/educates/educates-training-platform/client-programs/pkg/cluster"
+	"github.com/educates/educates-training-platform/client-programs/pkg/utils"
+)
+
+var clusterPortalExportExample = `
+  # Export a training portal and its workshops as YAML to stdout:
+  educates cluster portal export
+
+  # Export a specific training portal:
+  educates cluster portal export --portal my-portal
+
+  # Export the YAML resources as files in a directory:
+  educates cluster portal export --portal my-portal --as-files ./export
+`
+
+type ClusterPortalExportOptions struct {
+	KubeconfigOptions
+	Portal          string
+	AsFiles         string
+	Repository      string
+	WorkshopVersion string
+}
+
+func (o *ClusterPortalExportOptions) Run() error {
+	if o.Portal == "" {
+		o.Portal = "educates-cli"
+	}
+
+	clusterConfig, err := cluster.NewClusterConfigIfAvailable(o.Kubeconfig, o.Context)
+	if err != nil {
+		return err
+	}
+
+	dynamicClient, err := clusterConfig.GetDynamicClient()
+	if err != nil {
+		return errors.Wrap(err, "unable to create Kubernetes client")
+	}
+
+	documents, err := exportTrainingPortalDocuments(dynamicClient, o.Portal, o.Repository, o.WorkshopVersion)
+	if err != nil {
+		return err
+	}
+
+	if o.AsFiles != "" {
+		return utils.WriteExportedDocuments(o.AsFiles, documents)
+	}
+
+	return utils.PrintExportedDocuments(documents)
+}
+
+// exportTrainingPortalDocuments fetches the training portal and each
+// workshop it references, sanitizes them for re-apply, and returns them as
+// named YAML documents (trainingportal.yaml first, then one per workshop).
+func exportTrainingPortalDocuments(client dynamic.Interface, portal, repository, workshopVersion string) ([]utils.ExportedYAMLDocument, error) {
+	trainingPortalClient := client.Resource(trainingPortalResource)
+
+	trainingPortal, err := trainingPortalClient.Get(context.TODO(), portal, metav1.GetOptions{})
+	if err != nil {
+		if k8serrors.IsNotFound(err) {
+			return nil, errors.Errorf("training portal %q does not exist", portal)
+		}
+		return nil, errors.Wrapf(err, "unable to fetch training portal %q in cluster", portal)
+	}
+
+	workshopNames, err := extractWorkshopNamesFromTrainingPortal(trainingPortal)
+	if err != nil {
+		return nil, err
+	}
+
+	documents := make([]utils.ExportedYAMLDocument, 0, len(workshopNames)+1)
+
+	portalData, err := utils.RenderResourceAsYAMLDocument(utils.SanitizeTrainingPortalResourceForExport(utils.SanitizeResourceForExport(trainingPortal)))
+	if err != nil {
+		return nil, errors.Wrapf(err, "unable to generate YAML for training portal %q", trainingPortal.GetName())
+	}
+	documents = append(documents, utils.ExportedYAMLDocument{Name: "trainingportal.yaml", Data: portalData})
+
+	workshopsClient := client.Resource(workshopResource)
+
+	for _, name := range workshopNames {
+		workshop, err := workshopsClient.Get(context.TODO(), name, metav1.GetOptions{})
+		if err != nil {
+			if k8serrors.IsNotFound(err) {
+				return nil, errors.Errorf("workshop %q referenced by training portal %q does not exist", name, portal)
+			}
+			return nil, errors.Wrapf(err, "unable to fetch workshop %q in cluster", name)
+		}
+
+		workshopData, err := utils.RenderResourceAsYAMLDocument(utils.SanitizeWorkshopResourceForExport(utils.SanitizeResourceForExport(workshop), &utils.WorkshopResourceExportConfig{
+			Repository:      repository,
+			WorkshopVersion: workshopVersion,
+		}))
+		if err != nil {
+			return nil, errors.Wrapf(err, "unable to generate YAML for workshop %q", name)
+		}
+
+		documents = append(documents, utils.ExportedYAMLDocument{Name: name + ".yaml", Data: workshopData})
+	}
+
+	return documents, nil
+}
+
+// extractWorkshopNamesFromTrainingPortal returns the de-duplicated workshop
+// names referenced in a training portal's spec.workshops.
+func extractWorkshopNamesFromTrainingPortal(trainingPortal *unstructured.Unstructured) ([]string, error) {
+	workshops, _, err := unstructured.NestedSlice(trainingPortal.Object, "spec", "workshops")
+	if err != nil {
+		return nil, errors.Wrap(err, "unable to retrieve workshops from training portal")
+	}
+
+	names := []string{}
+	seen := map[string]struct{}{}
+
+	for _, item := range workshops {
+		object, ok := item.(map[string]interface{})
+		if !ok {
+			return nil, errors.Errorf("invalid workshop reference in training portal %q", trainingPortal.GetName())
+		}
+
+		name, ok := object["name"].(string)
+		if !ok || name == "" {
+			return nil, errors.Errorf("invalid workshop reference in training portal %q", trainingPortal.GetName())
+		}
+
+		if _, exists := seen[name]; exists {
+			continue
+		}
+
+		seen[name] = struct{}{}
+		names = append(names, name)
+	}
+
+	return names, nil
+}
+
+func (p *ProjectInfo) NewClusterPortalExportCmd() *cobra.Command {
+	var o ClusterPortalExportOptions
+
+	var c = &cobra.Command{
+		Args:    cobra.NoArgs,
+		Use:     "export",
+		Short:   "Export portal and its workshops from Kubernetes",
+		Example: clusterPortalExportExample,
+		RunE:    func(_ *cobra.Command, _ []string) error { return o.Run() },
+	}
+
+	c.Flags().StringVar(
+		&o.Kubeconfig,
+		"kubeconfig",
+		"",
+		"kubeconfig file to use instead of $KUBECONFIG or $HOME/.kube/config",
+	)
+	c.Flags().StringVar(
+		&o.Context,
+		"context",
+		"",
+		"Context to use from Kubeconfig",
+	)
+	c.Flags().StringVarP(
+		&o.Portal,
+		"portal",
+		"p",
+		"educates-cli",
+		"name to be used for training portal and workshop name prefixes",
+	)
+	c.Flags().StringVar(
+		&o.AsFiles,
+		"as-files",
+		"",
+		"write YAML resources as files in the target directory instead of stdout",
+	)
+	c.Flags().StringVar(
+		&o.Repository,
+		"image-repository",
+		"localhost:5001",
+		"the address of the image repository",
+	)
+	c.Flags().StringVar(
+		&o.WorkshopVersion,
+		"workshop-version",
+		"latest",
+		"version of the workshop being exported",
+	)
+
+	return c
+}

client-programs/pkg/cmd/local_mirror_cmd_group.go

@@ -21,6 +21,7 @@ func (p *ProjectInfo) NewLocalMirrorCmdGroup() *cobra.Command {
 			Commands: []*cobra.Command{
 				p.NewLocalMirrorDeployCmd(),
 				p.NewLocalMirrorDeleteCmd(),
+				p.NewLocalMirrorListCmd(),
 			},
 		},
 	}

client-programs/pkg/cmd/local_mirror_list_cmd.go

@@ -0,0 +1,47 @@
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/pkg/errors"
+	"github.com/spf13/cobra"
+
+	"github.com/educates/educates-training-platform/client-programs/pkg/registry"
+	"github.com/educates/educates-training-platform/client-programs/pkg/utils"
+)
+
+var localMirrorListExample = `
+  # List the deployed local image registry mirrors:
+  educates local mirror list
+`
+
+func (p *ProjectInfo) NewLocalMirrorListCmd() *cobra.Command {
+	var c = &cobra.Command{
+		Args:    cobra.NoArgs,
+		Use:     "list",
+		Short:   "Lists the local image registry mirrors",
+		Example: localMirrorListExample,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			mirrors, err := registry.ListRegistryMirrors()
+			if err != nil {
+				return errors.Wrap(err, "failed to list registry mirrors")
+			}
+
+			if len(mirrors) == 0 {
+				fmt.Println("No mirrors found.")
+				return nil
+			}
+
+			rows := make([][]string, 0, len(mirrors))
+			for _, m := range mirrors {
+				rows = append(rows, []string{m.Name, m.URL, m.Username, m.Status, m.ContainerName})
+			}
+
+			fmt.Println(utils.PrintTable([]string{"NAME", "URL", "USERNAME", "STATUS", "CONTAINER_NAME"}, rows))
+
+			return nil
+		},
+	}
+
+	return c
+}

client-programs/pkg/constants/containers.go

@@ -0,0 +1,20 @@
+// Package constants holds shared constant values used across the CLI.
+package constants
+
+const (
+	// Container label keys applied to the Docker containers Educates
+	// creates directly (the local registry, registry mirrors, and the
+	// DNS resolver) so they can be discovered, filtered, and cleaned up
+	// by label rather than by container name.
+	EducatesContainersAppLabelKey      = "educates.dev/app"
+	EducatesContainersRoleLabelKey     = "educates.dev/role"
+	EducatesContainersMirrorLabelKey   = "educates.dev/mirror"
+	EducatesContainersURLLabelKey      = "educates.dev/url"
+	EducatesContainersUsernameLabelKey = "educates.dev/username"
+
+	// Container label values.
+	EducatesContainersAppLabel          = "educates"
+	EducatesContainersRegistryRoleLabel = "registry"
+	EducatesContainersMirrorRoleLabel   = "mirror"
+	EducatesContainersResolverRoleLabel = "resolver"
+)