feat: add command-line tool admiralctl and implement the migrate subcommand

[YTGhost]

Summary

KubeAdmiral is a multi-cluster management system for Kubernetes, developed from Kubernetes Federation v2. However, it currently lacks a command-line tool to simplify user operations. Therefore, this proposal aims to set up the code framework for the KubeAdmiral command-line tool: admiralctl, and to implement the subcommand to import resources from existing clusters into the federation.

Motivation

By developing admiralctl, we can greatly simplify user operations and enhance the overall usability of KubeAdmiral.

Goals

We need to achieve the following goals:

• Using mainstream command-line tool frameworks ensures that while the command-line tool is user-friendly, the code remains easy to maintain.
• Implement the subcommand to import resources from existing clusters into the federation.
• Adequate unit tests and detailed usage documentation.

Non-Goals/Future Work

• Implementation of more subcommands like admiralctl join, admiralctl unjoin, and so on.

Proposal

Command line tool framework selection

For the command line tool framework selection, after research, the cobra framework was finally selected for the following reasons:

1. Clean design: cobra provides a clear structure for managing commands, subcommands, flags, and arguments, making building complex CLI tools intuitive and simple.
2. Built-in help commands: Without writing any additional code, cobra automatically generates -h or --help flags for your application, displaying help information about commands.
3. Powerful flag parsing: Integration with the pflag library provides more powerful flag parsing than flag in the Go standard library.
4. Extensibility: you can easily add or modify commands, making the program very extensible for future development.
5. Automatic Documentation Generation: cobra can automatically generate documentation for your CLI in Markdown, man, or other formats, which is useful for keeping documentation and code synchronized.
6. Persistent flags: provides a way to define flags for a particular command and allow subcommands to inherit those flags, which can be very useful in certain situations.
7. Adopted by several large projects: kubectl, kubeadm, and many other well-known projects use cobra, which validates its stability and reliability in production environments.
8. Community support: Due to its popularity in the Go community, there are tons of examples, tutorials, and other resources available, which greatly lowers the barrier to learning.

Admiralctl migrate subcommand implementation

1. Get the information about the legacy workload to be migrated.
2. create the corresponding workload on the control plane.
3. if AutoCreatePolicy is true, create a PropagationPolicy or ClusterPropagationPolicy and bind the policy to the corresponding workload on the control plane (by labeling).

Command design

./admiralctl --help
admiralctl controls the Kubernetes cluster federation manager.

Resource Management Commands:
  federalize    federalize resource from target clusters to Kubeadmiral control plane

Other Commands:
  completion    Generate the autocompletion script for the specified shell

Usage:
  admiralctl [flags] [options]

Use "admiralctl <command> --help" for more information about a given command.
Use "admiralctl options" for a list of global command-line options (applies to all commands).

./admiralctl migrate --help
Federalize resources from target cluster to Kubeadmiral control plane. The target cluster needs to have joined the
federation.

 If the resource already exists in Kubeadmiral control plane, you need to edit PropagationPolicy and OverridePolicy to
propagate it.

Examples:
  # Federalize deployment(default/busybox) from cluster1 to Kubeadmiral
  admiralctl federalize deployment busybox -n default -C cluster1
  
  # Federalize deployment(default/busybox) with gvk from cluster1 to Kubeadmiral
  admiralctl federalize deployment.v1.apps busybox -n default -C cluster1
  
  # Support to use '--dry-run' to print resource and policy that need to be deployed
  admiralctl federalize deployment busybox -n default -C cluster1 --dry-run
  
  # Support to use '--policy-name' to specify a policy that already exists
  admiralctl federalize deployment busybox -n default -C cluster1 --auto-create-policy=false --policy-name=<POLICY_NAME>
  
  # Federalize secret(default/default-secret) from cluster1 to Kubeadmiral
  admiralctl federalize secret default-secret -n default -C cluster1
  
  # Support to use '--cluster-kubeconfig' to specify the kubeconfig of member cluster
  admiralctl federalize deployment busybox -n default -C cluster1 --cluster-kubeconfig=<CLUSTER_KUBECONFIG_PATH>
  
  # Support to use '--cluster-kubeconfig' and '--cluster-context' to specify the kubeconfig and context of member
cluster
  admiralctl federalize deployment busybox -n default -C cluster1 --cluster-kubeconfig=<CLUSTER_KUBECONFIG_PATH>
--cluster-context=<CLUSTER_CONTEXT>

Options:
    --auto-create-policy=true:
        Automatically create a PropagationPolicy for namespace-scoped resources or create a ClusterPropagationPolicy
        for cluster-scoped resources.

    -C, --cluster='':
        The name of target cluster (eg. -C=member1).

    --cluster-context='':
        Context name of target cluster in kubeconfig.

    --cluster-kubeconfig='':
        Path of the target cluster's kubeconfig.

    --dry-run=false:
        Run the command in dry-run mode.

    -n, --namespace='':
        The namespace of the resource to be federalized.

    -o, --output='yaml':
        Output format: yaml or json.

    --policy-name='':
        The name of the PropagationPolicy or ClusterPropagationPolicy that is automatically created after migration.
        If not specified, the policy name will be the resource name with resource group and kind.

    --scheduling-mode='Duplicate':
        determines the mode used by the scheduler when scheduling federated objects, One of: Duplicate or Divide,
        default is Duplicate.

Usage:
  admiralctl federalize <RESOURCE_TYPE> <RESOURCE_NAME> -n <NAMESPACE> -C <CLUSTER_NAME> [options]

Use "admiralctl options" for a list of global command-line options (applies to all commands).

[CLAassistant]

All committers have signed the CLA.

[YTGhost]

@mrlihanbo PTAL, incidentally, maybe I should revamp the build-related scripts to build admiralctl in this PR by the way?

[mrlihanbo]

Resource Management Commands? /cc @limhawjia @gary-lgy

[mrlihanbo]

Federalize may be better? /cc @gary-lgy @limhawjia

[mrlihanbo]

It is strange to federalize the resources in deleting status. Should we forbid the operation in preflight？/cc @gary-lgy @limhawjia

[mrlihanbo]

Maybe we should support specifying exist propagation policy when federalize member cluster resources？ /cc @gary-lgy @limhawjia

[wy-lucky]

Pod maybe be deleted if it specifies not exist node name by k8s, should we remove spec.NodeName when Kind is Pod? cc @mrlihanbo