Skip to content

etcdctl: organize etcdctl subcommand #20162

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

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

Conversation

hwdef
Copy link
Contributor

@hwdef hwdef commented Jun 12, 2025

fix: #17777

The code might be a bit ugly, thanks to the reviewers, I'm still getting used to the etcd project.:)

I delete template for etcdctl. The reasons are as follows:

  • In etcdctl, the template is not very useful; it merely prints additional version and API version information, which can be obtained through the etcdctl version command.
  • The template restricts the output format of group commands, and using Cobra's native output is actually better. With the template, it becomes harder to achieve an aesthetically pleasing output format.

If this change is not appropriate, I can revert it.:)

before:

./bin/etcdctl --help
NAME:
  etcdctl - A simple command line client for etcd3.

USAGE:
  etcdctl [flags]

VERSION:
  3.7.0-alpha.0

API VERSION:
  3.7

COMMANDS:
  alarm disarm                  Disarms all alarms
  alarm list                    Lists all alarms
  auth disable                  Disables authentication
  auth enable                   Enables authentication
  auth status                   Returns authentication status
  check datascale               Check the memory usage of holding data for different workloads on a given server endpoint.
  check perf                    Check the performance of the etcd cluster
  compaction                    Compacts the event history in etcd
  completion                    Generate completion script
  defrag                        Defragments the storage of the etcd members with given endpoints
  del                           Removes the specified key or range of keys [key, range_end)
  downgrade cancel              Cancel the ongoing downgrade action to cluster
  downgrade enable              Start a downgrade action to cluster
  downgrade validate            Validate downgrade capability before starting downgrade
  elect                         Observes and participates in leader election
  endpoint hashkv               Prints the KV history hash for each endpoint in --endpoints
  endpoint health               Checks the healthiness of endpoints specified in `--endpoints` flag
  endpoint status               Prints out the status of endpoints specified in `--endpoints` flag
  get                           Gets the key or a range of keys
  help                          Help about any command
  lease grant                   Creates leases
  lease keep-alive              Keeps leases alive (renew)
  lease list                    List all active leases
  lease revoke                  Revokes leases
  lease timetolive              Get lease information
  lock                          Acquires a named lock
  make-mirror                   Makes a mirror at the destination etcd cluster
  member add                    Adds a member into the cluster
  member list                   Lists all members in the cluster
  member promote                Promotes a non-voting member in the cluster
  member remove                 Removes a member from the cluster
  member update                 Updates a member in the cluster
  move-leader                   Transfers leadership to another etcd cluster member.
  put                           Puts the given key into the store
  role add                      Adds a new role
  role delete                   Deletes a role
  role get                      Gets detailed information of a role
  role grant-permission         Grants a key to a role
  role list                     Lists all roles
  role revoke-permission        Revokes a key from a role
  snapshot save                 Stores an etcd node backend snapshot to a given file
  txn                           Txn processes all the requests in one transaction
  user add                      Adds a new user
  user delete                   Deletes a user
  user get                      Gets detailed information of a user
  user grant-role               Grants a role to a user
  user list                     Lists all users
  user passwd                   Changes password of user
  user revoke-role              Revokes a role from a user
  version                       Prints the version of etcdctl
  watch                         Watches events stream on keys or prefixes

OPTIONS:
      --auth-jwt-token=""                       JWT token used for authentication (if this option is used, --user and --password should not be set)
      --cacert=""                               verify certificates of TLS-enabled secure servers using this CA bundle
      --cert=""                                 identify secure client using this TLS certificate file
      --command-timeout=5s                      timeout for short running command (excluding dial timeout)
      --debug[=false]                           enable client-side debug logging
      --dial-timeout=2s                         dial timeout for client connections
  -d, --discovery-srv=""                        domain name to query for SRV records describing cluster endpoints
      --discovery-srv-name=""                   service name to query when using DNS discovery
      --endpoints=[127.0.0.1:2379]              gRPC endpoints
  -h, --help[=false]                            help for etcdctl
      --hex[=false]                             print byte strings as hex encoded strings
      --insecure-discovery[=true]               accept insecure SRV records describing cluster endpoints
      --insecure-skip-tls-verify[=false]        skip server certificate verification (CAUTION: this option should be enabled only for testing purposes)
      --insecure-transport[=true]               disable transport security for client connections
      --keepalive-time=2s                       keepalive time for client connections
      --keepalive-timeout=6s                    keepalive timeout for client connections
      --key=""                                  identify secure client using this TLS key file
      --max-recv-bytes=0                        client-side response receive limit in bytes (if 0, it defaults to "math.MaxInt32")
      --max-request-bytes=0                     client-side request send limit in bytes (if 0, it defaults to 2.0 MiB (2 * 1024 * 1024).)
      --password=""                             password for authentication (if this option is used, --user option shouldn't include password)
      --user=""                                 username[:password] for authentication (prompt if password is not supplied)
  -w, --write-out="simple"                      set the output format (fields, json, protobuf, simple, table)

after:

$ ./bin/etcdctl 
A simple command line client for etcd3.

Usage:
  etcdctl [command]

Key-value commands
  compaction  Compacts the event history in etcd
  del         Removes the specified key or range of keys [key, range_end)
  get         Gets the key or a range of keys
  lease       Lease related commands
  put         Puts the given key into the store
  txn         Txn processes all the requests in one transaction
  watch       Watches events stream on keys or prefixes

Cluster maintenance commands
  alarm       Alarm related commands
  defrag      Defragments the storage of the etcd members with given endpoints
  downgrade   Downgrade related commands
  endpoint    Endpoint related commands
  member      Membership related commands
  move-leader Transfers leadership to another etcd cluster member.
  snapshot    Manages etcd node snapshots

Concurrency commands
  elect       Observes and participates in leader election
  lock        Acquires a named lock

Authentication commands
  auth        Enable or disable authentication
  role        Role related commands
  user        User related commands

Utility commands
  check       commands for checking properties of the etcd cluster
  completion  Generate completion script
  help        Help about any command
  make-mirror Makes a mirror at the destination etcd cluster
  version     Prints the version of etcdctl

Flags:
      --auth-jwt-token string        JWT token used for authentication (if this option is used, --user and --password should not be set)
      --cacert string                verify certificates of TLS-enabled secure servers using this CA bundle
      --cert string                  identify secure client using this TLS certificate file
      --command-timeout duration     timeout for short running command (excluding dial timeout) (default 5s)
      --debug                        enable client-side debug logging
      --dial-timeout duration        dial timeout for client connections (default 2s)
  -d, --discovery-srv string         domain name to query for SRV records describing cluster endpoints
      --discovery-srv-name string    service name to query when using DNS discovery
      --endpoints strings            gRPC endpoints (default [127.0.0.1:2379])
  -h, --help                         help for etcdctl
      --hex                          print byte strings as hex encoded strings
      --insecure-discovery           accept insecure SRV records describing cluster endpoints (default true)
      --insecure-skip-tls-verify     skip server certificate verification (CAUTION: this option should be enabled only for testing purposes)
      --insecure-transport           disable transport security for client connections (default true)
      --keepalive-time duration      keepalive time for client connections (default 2s)
      --keepalive-timeout duration   keepalive timeout for client connections (default 6s)
      --key string                   identify secure client using this TLS key file
      --max-recv-bytes int           client-side response receive limit in bytes (if 0, it defaults to "math.MaxInt32")
      --max-request-bytes int        client-side request send limit in bytes (if 0, it defaults to 2.0 MiB (2 * 1024 * 1024).)
      --password string              password for authentication (if this option is used, --user option shouldn't include password)
      --user string                  username[:password] for authentication (prompt if password is not supplied)
  -w, --write-out string             set the output format (fields, json, protobuf, simple, table) (default "simple")

Use "etcdctl [command] --help" for more information about a command.

@k8s-ci-robot
Copy link

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: hwdef
Once this PR has been reviewed and has the lgtm label, please assign ahrtr for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@k8s-ci-robot
Copy link

Hi @hwdef. Thanks for your PR.

I'm waiting for a etcd-io member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

@hwdef hwdef changed the title organize etcdctl subcommand etcdctl: organize etcdctl subcommand Jun 12, 2025
@ahrtr
Copy link
Member

ahrtr commented Jun 12, 2025

@hwdef hwdef force-pushed the organize-etcdctl-commands branch from 31e4263 to 069530b Compare June 23, 2025 15:13
Signed-off-by: hwdef <hwdefcom@outlook.com>
@hwdef hwdef force-pushed the organize-etcdctl-commands branch from 069530b to c346678 Compare June 28, 2025 16:59
@hwdef
Copy link
Contributor Author

hwdef commented Jun 28, 2025

/cc @serathius @fuweid @ahrtr @ivanvc @jmhbnz @siyuanfoundation

This PR is ready for review. Please take a look :-)

@hwdef
Copy link
Contributor Author

hwdef commented Jul 2, 2025

kindly ping @ivanvc @jmhbnz

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Development

Successfully merging this pull request may close these issues.

Organize etcdctl commands and add more documents
4 participants