Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

YTGhost
Copy link

@YTGhost YTGhost commented Aug 15, 2023

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
Copy link

CLAassistant commented Aug 15, 2023

CLA assistant check
All committers have signed the CLA.

@YTGhost YTGhost marked this pull request as draft August 15, 2023 15:23
@YTGhost YTGhost force-pushed the feat-admiralctl branch 2 times, most recently from 6c9984d to c6d1551 Compare September 15, 2023 06:08
@YTGhost YTGhost marked this pull request as ready for review September 15, 2023 10:52
@YTGhost
Copy link
Author

YTGhost commented Sep 15, 2023

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

@YTGhost YTGhost changed the title WIP: add command-line tool admiralctl and implement the migrate subcommand feat: add command-line tool admiralctl and implement the migrate subcommand Sep 15, 2023
ioStreams := genericclioptions.IOStreams{In: os.Stdin, Out: os.Stdout, ErrOut: os.Stderr}
groups := templates.CommandGroups{
{
Message: "Advanced Commands:",
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

{
Message: "Advanced Commands:",
Commands: []*cobra.Command{
migrate.NewCmdMigrate(f, parentCommand),
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

// populated by the kubernetes.
// The kubernetes will set this fields in case of graceful deletion. This field is read-only and can't propagate to
// member clusters.
unstructured.RemoveNestedField(workload.Object, "metadata", "deletionTimestamp")
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

return fmt.Errorf("failed to create resource %q(%s/%s) in control plane: %w", gvr, o.Namespace, o.name, err)
}

if o.AutoCreatePolicy {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


unstructured.RemoveNestedField(workload.Object, "status")

if workload.GetKind() == common.ServiceKind {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

…ommand

Signed-off-by: Liang Deng <[email protected]>

Signed-off-by: Liang Deng <[email protected]>

Signed-off-by: Liang Deng <[email protected]>

Signed-off-by: Liang Deng <[email protected]>

Signed-off-by: Liang Deng <[email protected]>
miraclejzd pushed a commit to miraclejzd/kubeadmiral that referenced this pull request Dec 16, 2023
miraclejzd added a commit to miraclejzd/kubeadmiral that referenced this pull request Jan 3, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants