docs: add proposal of enhancing karmadactl

Signed-off-by: hulizhe <pompeii.hu@gmail.com>

docs/proposals/karmadactl/enhance_karmadactl_maintenance_experience.md

@@ -0,0 +1,283 @@
+---
+title: Enhance karmadactl operation and maintenance experience
+authors:
+- "@hulizhe"
+- "@zhzhuang-zju"
+reviewers:
+- "@RainbowMango"
+
+approvers:
+- "@RainbowMango"
+
+creation-date: 2024-07-22
+---
+
+# Enhance karmadactl operation and maintenance experience
+
+## Summary
+
+Karmadactl is a CLI (Command Line Interface) tool entirely dedicated to Karmada's multi-cluster scenarios. Currently, karmadactl implements commands such as `get` and `describe` for partial applications in a multi-cluster context. For instance, `karmadactl get` is used to display one or many resources in member clusters, and `karmadactl describe` shows detailed information about a specific resource or group of resources within a member cluster. However, these commands are exclusively focused on resources within member clusters, lacking capabilities to perform CRUD (Create, Read, Update, Delete) operations on Karmada control plane resources.
+
+Furthermore, some kubectl commands have not been adapted to multi-cluster scenarios, such as `create`, `label`, and `edit`. This omission prevents karmadactl from functioning independently of kubectl, necessitating the use of both tools to manage resources comprehensively across multi-cluster environments managed by Karmada.
+
+Therefore, this proposal plans to enhance the functionality of karmadactl in multi-cluster scenarios, aiming to further improve the operational experience of using karmadactl. The main enhancements include:
+
+- Enhancing the capabilities of `karmadactl get`, `karmadactl describe`, and similar commands to parse and interpret Karmada control plane resources.
+- Completing the implementation of features for commands such as `karmadactl create`, `karmadactl label`, and `karmadactl edit`.
+
+## Motivation
+
+<!--
+This section is for explicitly listing the motivation, goals, and non-goals of
+this KEP.  Describe why the change is important and the benefits to users.
+-->
+Currently, due to incomplete capabilities of karmadactl in multi-cluster scenarios, in actual operations and maintenance, karmadactl is often used in conjunction with kubectl. This leads to issues such as switching between karmadactl and kubectl commands under different usage scenarios, frequent context switching required by kubectl, and resource wastage:
+
+- Suppose Karmada has a deployment named `foo` that has been dispatched to member clusters member1 and member2.
+- If you wish to inspect the `foo` deployment under the Karmada control plane and in each member cluster,
+- Firstly, you would need to use the kubectl command `kubectl get --kubeconfig $HOME/.kube/karmada.config --context karmada-apiserver` to display the `foo` deployment in Karmada.
+- Next, you would switch to the karmadactl command `karmadactl get` to check the `foo` deployment in the member clusters.
+
+This disjointed process also creates a fragmented experience for the user, as described in the [issue](https://github.com/karmada-io/karmada/issues/5205).
+
+If karmadactl were capable of viewing resources from Karmada control plane, then the above requirements could be fulfilled simply by using the command `karmadactl get`.
+
+### Goals
+
+- Providing the ability for karmadactl to perform Create, Read, Update, and Delete (CRUD) operations on Karmada control plane resources.
+- Bridging the gap by incorporating functionalities into karmadactl that have yet to be inherited from kubectl, notably including `karmadactl create`, `karmadactl delete`, `karmadactl label`, `karmadactl edit`, `karamdactl patch`, `karmadactl annotate`, `karmadctl attach`, `karmadactl api-resources`, `karmadactl explain`, `karmadactl top node`.
+
+### Non-Goals
+
+- Optimization of command output for improved display and readability.
+- Replacing kubectl with karmadactl in the [karmada repository](https://github.com/karmada-io/karmada).
+
+## Proposal
+
+The usage scope for karmadactl commands, based on their specific functionalities, can be categorized as follows:
+
+- Karmada Control Plane
+- A Single Member Cluster
+- Multiple Member Clusters
+- Karmada Control Plane or a Single Member Cluster
+- Karmada Control Plane and Multiple Member Clusters
+
+To unify the representation of different commands with varying scopes of usage, the following conventions are agreed upon:
+
+- Default Scope: The default scope for commands is the Karmada Control Plane. Exceptions to this rule include commands such as `karmadactl logs` and `karmadactl exec`, which inherently operate within member clusters and cannot be applied to the Karmada control plane.
+- Specifying Member Clusters: If a command is intended to affect member clusters, the user must specify the target member cluster(s) via a flag. This allows the command to be directed towards a particular member cluster or a list of member clusters.
+
+These guidelines ensure that there is a clear and consistent way to differentiate between commands that operate at the level of the Karamda control plane versus those that target individual or multiple member clusters. This helps prevent ambiguity and ensures that users can accurately predict the behavior of each command based on its scope and the flags provided, facilitating more efficient and error-free operations within the Karmada multi-cluster environment.
+Currently, the flag set of karmadactl is only sufficient for viewing or modifying resources within member clusters. Therefore, the first step is to design and modify the flag set of karmadactl, ensuring it can accommodate the various scenarios outlined previously.
+
+Secondly, karmadactl commands can be classified based on whether they inherit from kubectl:
+
+- Inherited from kubectl: These commands represent extensions of single-cluster capabilities to multi-cluster scenarios.
+- Multi-cluster-specific abilities: These are commands unique to karmadactl, designed to address the specific requirements and complexities inherent to managing resources across multiple clusters.
+
+To facilitate a smooth transition for users moving from kubectl to karmadactl, efforts should be made to ensure that the user experience for identical commands remains as consistent as possible between the two tools. This includes maintaining similar command structures, output formatting, and behavior wherever feasible, while also leveraging the extended capabilities of karmadactl to manage resources effectively in a multi-cluster environment.
+
+Given that directly modifying resources in member clusters could potentially lead to conflicts between Karmada control plane and the member clusters, karmadactl should not offer the capability to directly create, delete, or update resources in member clusters.
+
+### User Stories (Optional)
+
+<!--
+Detail the things that people will be able to do if this KEP is implemented.
+Include as much detail as possible so that people can understand the "how" of
+the system. The goal here is to make this feel real for users without getting
+bogged down.
+-->
+
+#### Story 1
+
+As an operations personnel, I hope to be able to view resources from the current Karmada control plane as well as member clusters without context switching or changing between CLIs.
+
+**Scenario**:
+
+1. Given that both the Karmada control plane and member clusters have a deployment named `foo`.
+2. When I use the command `karmadactl get`, it will display deployment `foo` from the Karmada control plane as well as from all member clusters, providing a consolidated view of the resource across the multi-cluster environment.
+
+### Notes/Constraints/Caveats (Optional)
+
+<!--
+What are the caveats to the proposal?
+What are some important details that didn't come across above?
+Go in to as much detail as necessary here.
+This might be a good place to talk about core concepts and how they relate.
+-->
+
+### Risks and Mitigations
+
+<!--
+What are the risks of this proposal, and how do we mitigate?
+
+How will security be reviewed, and by whom?
+
+How will UX be reviewed, and by whom?
+
+Consider including folks who also work outside the SIG or subproject.
+-->
+
+## Design Details
+
+<!--
+This section should contain enough information that the specifics of your
+change are understandable. This may include API specs (though not always
+required) or even code snippets. If there's any ambiguity about HOW your
+proposal will be implemented, this is the place to discuss them.
+-->
+
+### CLI flags changes
+
+This proposal proposes new flags `ignore-host` and `all-clusters` in karmadactl flag set.
+
+| name           | shorthand      | default | usage                                                   |
+|----------------|----------------|---------|---------------------------------------------------------|
+| ignore-karmada | ignore-karmada | false   | Used to control whether karmada's resources are ignored |
+| all-clusters   | all-clusters   | false   | Used to specify whether to include all member clusters  |
+
+With these flag, we will:
+
+- When the usage scope of a karmadactl command includes Karmada control plane and member clusters, you can use the `--ignore-karmada` flag to specify that resources from the Karmada control plane should be ignored, focusing instead solely on resources within the member clusters.
+- When the usage scope of a karmadactl command includes member clusters, you can use the `--all-clusters` flag to determine whether the operation should be applied to resources across all member clusters.
+
+### Modification of Existing Commands
+
+#### karmadactl get
+
+- description: Display one or many resources in Karmada control plane and member clusters.
+- usage scope: Karmada control plane and member clusters.
+- scope-related flag set:
+
+| name           | shorthand      | default | usage                                                   |
+|----------------|----------------|---------|---------------------------------------------------------|
+| clusters       | C              | none    | Used to specify target member clusters                  |
+| all-clusters   | all-clusters   | false   | Used to specify whether to include all member clusters  |
+| ignore-karmada | ignore-karmada | false   | Used to control whether karmada's resources are ignored |
+
+- performance:
+<ol>
+<li>When the `clusters` flag is empty, the `all-clusters` flag is set to false, and the `ignore-karmada` flag is true, a message should be displayed stating "Please specify at least one target cluster," such as when running `karmadactl get --ignore-karmada`.</li>
+<li>When the `all-clusters` flag is set to true, the command's scope encompasses the Karmada control plane along with all member clusters. For example, the command `karmadactl get pods -C member1 --all-clusters` would display pods from the Karmada control plane as well as from all member clusters.</li>
+<li>When the `clusters` flag is not empty, the command's scope is the Karmada control plane along with member clusters specified by the `clusters` flag. For instance, the command `karmadactl get pods -C member1,member2` would display the pods from the Karmada control plane as well as from the member clusters member1 and member2.</li>
+</ol>
+
+#### karmadactl describe
+
+- description: Show details of a specific resource or group of resources in Karmada control plane or a member cluster.
+- usage scope: Karmada Control Plane or a Single Member Cluster
+- scope-related flag set:
+
+| name    | shorthand | default | usage                                 |
+|---------|-----------|---------|---------------------------------------|
+| cluster | C         | none    | Used to specify target member cluster |
+
+- performance:
+<ol>
+<li>When the `cluster` flag is empty, the command's scope defaults to the Karmada control plane. For example, running `karmadactl describe deployment foo` will display the detailed information of the deployment `foo` residing in the Karmada control plane.</li>
+<li>When the `cluster` flag is not empty, the command's scope is limited to the member cluster specified by the `cluster` flag. For example, running `karmadactl describe deployment foo -C member1` will show the details of the deployment `foo` specifically within the member cluster member1.</li>
+</ol>
+
+
+#### karmadactl top pod
+
+- description: Display resource (CPU/memory) usage of pods in member clusters.
+- usage scope: Multiple Member Clusters
+- scope-related flag set:
+
+| name         | shorthand    | default | usage                                                  |
+|--------------|--------------|---------|--------------------------------------------------------|
+| clusters     | C            | none    | Used to specify target member clusters                 |
+| all-clusters | all-clusters | false   | Used to specify whether to include all member clusters |
+
+- performance：
+<ol>
+<li>When the `clusters` flag is empty and the `all-clusters` flag is set to false, a message should prompt the user with "Please specify at least one target cluster," as would occur with a command like `karmadactl top pod`.</li>
+<li>When the `all-clusters` flag is set to true, the command's scope covers all member clusters. For example, running `karmadactl top pod -C member1 --all-clusters` would show metrics for pods across all member clusters.</li>
+<li>When the `clusters` flag is not empty, the command's scope is determined by the member clusters specified in the `clusters` flag. For instance, the command `karmadactl top pod -C member1,member2` would show metrics for pods from the member clusters member1 and member2.</li>
+</ol>
+
+### Adding New Commands
+
+#### karmadactl edit, create, delete, label, patch and annotate
+
+These commands provide the capability for karmadactl to create, delete, and update resources on the Karmada control plane with functionalities that are consistent with those available in kubectl.
+
+- usage scope: Karmada control plane
+- scope-related flag set: None.
+
+#### karmadactl top node
+
+- description: Display resource (CPU/memory) usage of nodes in member clusters.
+- usage scope: Multiple Member Clusters
+- scope-related flag set:
+
+| name         | shorthand    | default | usage                                                  |
+|--------------|--------------|---------|--------------------------------------------------------|
+| clusters     | C            | none    | Used to specify target member clusters                 |
+| all-clusters | all-clusters | false   | Used to specify whether to include all member clusters |
+
+- performance:
+<ol>
+<li>When the `clusters` flag is empty and the `all-clusters` flag is set to false, a message should prompt the user with "Please specify at least one target cluster," as would occur with a command like `karmadactl top node`.</li>
+<li>When the `all-clusters` flag is set to true, the command's scope covers all member clusters. For example, running `karmadactl top node -C member1 --all-clusters` would show metrics for nodes across all member clusters.</li>
+<li>When the `clusters` flag is not empty, the command's scope is determined by the member clusters specified in the `clusters` flag. For instance, the command `karmadactl top node -C member1,member2` would show metrics for nodes from the member clusters member1 and member2.</li>
+</ol>
+
+#### karmadactl attach
+- description: attach to a process that is already running inside an existing container in a member cluster.
+- usage scope: A Single Member Cluster
+- scope-related flag set:
+
+| name        | shorthand    | default | usage                                                |
+|-------------|--------------|---------|------------------------------------------------------|
+| cluster     | C            | none    | Used to specify target member cluster                |
+
+- performance:
+<ol>
+<li>When the `cluster` flag is empty, a message should be displayed indicating "Please specify at least one target cluster," such as when running `karmadactl attach mypod`.</li>
+<li>When the `cluster` flag is not empty, the command's scope is limited to the member cluster specified by the `cluster` flag. For example, running `karmadactl attach mypod -C member1` will attach to the pod named `mypod` located in the member cluster member1. </li>
+</ol>
+
+#### karmadactl api-resources
+- description: Print the supported API resources on the server in Karmada control plane or a member cluster.
+- usage scope: Karmada Control Plane or a Single Member Cluster
+- scope-related flag set:
+
+| name    | shorthand | default | usage                                 |
+|---------|-----------|---------|---------------------------------------|
+| cluster | C         | none    | Used to specify target member cluster |
+
+- performance:
+<ol>
+<li>When the `cluster` flag is empty, the command's scope defaults to the Karmada control plane. For example, running `karmadactl api-resources` will print the supported API resources on the server in Karmada control plane</li>
+<li>When the `cluster` flag is not empty, the command's scope is limited to the member cluster specified by the `cluster` flag. For example, running `karmadactl api-resources -C member1` will print the supported API resources on the server in member1.</li>
+</ol>
+
+#### karmadactl explain
+- description: Describe fields and structure of various resources in Karmada control plane or a member cluster.
+- usage scope: Karmada Control Plane or a Single Member Cluster
+- scope-related flag set:
+
+| name    | shorthand | default | usage                                 |
+|---------|-----------|---------|---------------------------------------|
+| cluster | C         | none    | Used to specify target member cluster |
+
+- performance:
+<ol>
+<li>When the `cluster` flag is empty, the command's scope defaults to the Karmada control plane. For example, running `karmadactl explain pods` will describe fields and structure of pods in Karmada control plane</li>
+<li>When the `cluster` flag is not empty, the command's scope is limited to the member cluster specified by the `cluster` flag. For example, running `karmadactl explain pods -C member1` will describe fields and structure of pods in member1.</li>
+</ol>
+
+## Alternatives
+
+<!--
+What other approaches did you consider, and why did you rule them out? These do
+not need to be as detailed as the proposal, but should include enough
+information to express the idea and why it was not acceptable.
+-->
+
+<!--
+Note: This is a simplified version of kubernetes enhancement proposal template.
+https://github.com/kubernetes/enhancements/tree/3317d4cb548c396a430d1c1ac6625226018adf6a/keps/NNNN-kep-template
+-->