367 lines
8.6 KiB
Markdown
367 lines
8.6 KiB
Markdown
# Kubectl-Style CLI Example
|
|
|
|
This example demonstrates how to build a kubectl-style CLI with nested resource commands and consistent flag handling.
|
|
|
|
## Structure
|
|
|
|
```
|
|
myctl/
|
|
├── cmd/
|
|
│ ├── root.go # Root command with global flags
|
|
│ ├── get/
|
|
│ │ ├── get.go # Parent "get" command
|
|
│ │ ├── pods.go # Get pods subcommand
|
|
│ │ ├── services.go # Get services subcommand
|
|
│ │ └── deployments.go # Get deployments subcommand
|
|
│ ├── create/
|
|
│ │ ├── create.go # Parent "create" command
|
|
│ │ ├── deployment.go # Create deployment subcommand
|
|
│ │ └── service.go # Create service subcommand
|
|
│ ├── delete/
|
|
│ │ └── delete.go # Delete command (accepts any resource)
|
|
│ ├── apply.go # Apply from file/stdin
|
|
│ └── completion.go # Shell completion
|
|
└── main.go
|
|
```
|
|
|
|
## Usage Pattern
|
|
|
|
```bash
|
|
# Get resources
|
|
myctl get pods
|
|
myctl get pods my-pod
|
|
myctl get pods --namespace production
|
|
myctl get services --all-namespaces
|
|
|
|
# Create resources
|
|
myctl create deployment my-app --image nginx:latest --replicas 3
|
|
myctl create service my-svc --port 80 --target-port 8080
|
|
|
|
# Delete resources
|
|
myctl delete pod my-pod
|
|
myctl delete deployment my-app --force
|
|
|
|
# Apply configuration
|
|
myctl apply -f deployment.yaml
|
|
myctl apply -f config.yaml --dry-run
|
|
```
|
|
|
|
## Key Features
|
|
|
|
### 1. Resource-Based Organization
|
|
|
|
Commands are organized by resource type:
|
|
- `get <resource>` - Retrieve resources
|
|
- `create <resource>` - Create resources
|
|
- `delete <resource>` - Delete resources
|
|
|
|
### 2. Consistent Flag Handling
|
|
|
|
Global flags available to all commands:
|
|
- `--namespace, -n` - Target namespace
|
|
- `--all-namespaces, -A` - Query all namespaces
|
|
- `--output, -o` - Output format (json|yaml|text)
|
|
- `--verbose, -v` - Verbose logging
|
|
|
|
### 3. Command Groups
|
|
|
|
Organized help output:
|
|
```
|
|
Basic Commands:
|
|
get Display resources
|
|
describe Show detailed information
|
|
|
|
Management Commands:
|
|
create Create resources
|
|
delete Delete resources
|
|
apply Apply configuration
|
|
```
|
|
|
|
## Implementation Example
|
|
|
|
### Root Command (cmd/root.go)
|
|
|
|
```go
|
|
package cmd
|
|
|
|
import (
|
|
"github.com/spf13/cobra"
|
|
"myctl/cmd/get"
|
|
"myctl/cmd/create"
|
|
"myctl/cmd/delete"
|
|
)
|
|
|
|
var (
|
|
namespace string
|
|
allNamespaces bool
|
|
output string
|
|
)
|
|
|
|
var rootCmd = &cobra.Command{
|
|
Use: "myctl",
|
|
Short: "Kubernetes-style resource management CLI",
|
|
}
|
|
|
|
func Execute() error {
|
|
return rootCmd.Execute()
|
|
}
|
|
|
|
func init() {
|
|
// Global flags
|
|
rootCmd.PersistentFlags().StringVarP(&namespace, "namespace", "n", "default", "target namespace")
|
|
rootCmd.PersistentFlags().BoolVarP(&allNamespaces, "all-namespaces", "A", false, "query all namespaces")
|
|
rootCmd.PersistentFlags().StringVarP(&output, "output", "o", "text", "output format (text|json|yaml)")
|
|
|
|
// Command groups
|
|
rootCmd.AddGroup(&cobra.Group{ID: "basic", Title: "Basic Commands:"})
|
|
rootCmd.AddGroup(&cobra.Group{ID: "management", Title: "Management Commands:"})
|
|
|
|
// Register commands
|
|
rootCmd.AddCommand(get.GetCmd)
|
|
rootCmd.AddCommand(create.CreateCmd)
|
|
rootCmd.AddCommand(delete.DeleteCmd)
|
|
}
|
|
|
|
// Helper to get global flags
|
|
func GetNamespace() string {
|
|
return namespace
|
|
}
|
|
|
|
func GetAllNamespaces() bool {
|
|
return allNamespaces
|
|
}
|
|
|
|
func GetOutput() string {
|
|
return output
|
|
}
|
|
```
|
|
|
|
### Get Command Parent (cmd/get/get.go)
|
|
|
|
```go
|
|
package get
|
|
|
|
import (
|
|
"github.com/spf13/cobra"
|
|
)
|
|
|
|
var GetCmd = &cobra.Command{
|
|
Use: "get",
|
|
Short: "Display resources",
|
|
Long: `Display one or many resources`,
|
|
GroupID: "basic",
|
|
}
|
|
|
|
func init() {
|
|
// Add resource subcommands
|
|
GetCmd.AddCommand(podsCmd)
|
|
GetCmd.AddCommand(servicesCmd)
|
|
GetCmd.AddCommand(deploymentsCmd)
|
|
}
|
|
```
|
|
|
|
### Get Pods Subcommand (cmd/get/pods.go)
|
|
|
|
```go
|
|
package get
|
|
|
|
import (
|
|
"fmt"
|
|
|
|
"github.com/spf13/cobra"
|
|
"myctl/cmd"
|
|
"myctl/internal/client"
|
|
)
|
|
|
|
var (
|
|
selector string
|
|
watch bool
|
|
)
|
|
|
|
var podsCmd = &cobra.Command{
|
|
Use: "pods [NAME]",
|
|
Short: "Display pods",
|
|
Long: `Display one or many pods`,
|
|
Args: cobra.MaximumNArgs(1),
|
|
ValidArgsFunction: func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
|
|
// Dynamic completion: fetch pod names
|
|
return client.ListPodNames(cmd.GetNamespace()), cobra.ShellCompDirectiveNoFileComp
|
|
},
|
|
RunE: func(cmd *cobra.Command, args []string) error {
|
|
namespace := cmd.GetNamespace()
|
|
allNamespaces := cmd.GetAllNamespaces()
|
|
output := cmd.GetOutput()
|
|
|
|
if len(args) == 0 {
|
|
// List pods
|
|
return listPods(namespace, allNamespaces, selector, output)
|
|
}
|
|
|
|
// Get specific pod
|
|
podName := args[0]
|
|
return getPod(namespace, podName, output)
|
|
},
|
|
}
|
|
|
|
func init() {
|
|
// Command-specific flags
|
|
podsCmd.Flags().StringVarP(&selector, "selector", "l", "", "label selector")
|
|
podsCmd.Flags().BoolVarP(&watch, "watch", "w", false, "watch for changes")
|
|
}
|
|
|
|
func listPods(namespace string, allNamespaces bool, selector string, output string) error {
|
|
// Implementation
|
|
fmt.Printf("Listing pods (namespace: %s, all: %v, selector: %s, format: %s)\n",
|
|
namespace, allNamespaces, selector, output)
|
|
return nil
|
|
}
|
|
|
|
func getPod(namespace, name, output string) error {
|
|
// Implementation
|
|
fmt.Printf("Getting pod: %s (namespace: %s, format: %s)\n", name, namespace, output)
|
|
return nil
|
|
}
|
|
```
|
|
|
|
### Create Deployment (cmd/create/deployment.go)
|
|
|
|
```go
|
|
package create
|
|
|
|
import (
|
|
"fmt"
|
|
|
|
"github.com/spf13/cobra"
|
|
)
|
|
|
|
var (
|
|
image string
|
|
replicas int
|
|
port int
|
|
)
|
|
|
|
var deploymentCmd = &cobra.Command{
|
|
Use: "deployment NAME",
|
|
Short: "Create a deployment",
|
|
Args: cobra.ExactArgs(1),
|
|
RunE: func(cmd *cobra.Command, args []string) error {
|
|
name := args[0]
|
|
|
|
if image == "" {
|
|
return fmt.Errorf("--image is required")
|
|
}
|
|
|
|
fmt.Printf("Creating deployment: %s\n", name)
|
|
fmt.Printf(" Image: %s\n", image)
|
|
fmt.Printf(" Replicas: %d\n", replicas)
|
|
if port > 0 {
|
|
fmt.Printf(" Container Port: %d\n", port)
|
|
}
|
|
|
|
return createDeployment(name, image, replicas, port)
|
|
},
|
|
}
|
|
|
|
func init() {
|
|
deploymentCmd.Flags().StringVar(&image, "image", "", "container image (required)")
|
|
deploymentCmd.Flags().IntVar(&replicas, "replicas", 1, "number of replicas")
|
|
deploymentCmd.Flags().IntVar(&port, "port", 0, "container port")
|
|
|
|
deploymentCmd.MarkFlagRequired("image")
|
|
}
|
|
|
|
func createDeployment(name, image string, replicas, port int) error {
|
|
// Implementation
|
|
return nil
|
|
}
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
### 1. Consistent Flag Naming
|
|
- Use single-letter shortcuts for common flags (`-n`, `-o`, `-v`)
|
|
- Use descriptive long names (`--namespace`, `--output`, `--verbose`)
|
|
- Keep flag behavior consistent across commands
|
|
|
|
### 2. Dynamic Completion
|
|
Provide shell completion for resource names:
|
|
|
|
```go
|
|
ValidArgsFunction: func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
|
|
return client.ListResourceNames(), cobra.ShellCompDirectiveNoFileComp
|
|
}
|
|
```
|
|
|
|
### 3. Error Messages
|
|
Provide helpful error messages with suggestions:
|
|
|
|
```go
|
|
if image == "" {
|
|
return fmt.Errorf("--image is required. Example: --image nginx:latest")
|
|
}
|
|
```
|
|
|
|
### 4. Dry Run Support
|
|
Support `--dry-run` for preview:
|
|
|
|
```go
|
|
if dryRun {
|
|
fmt.Printf("Would create deployment: %s\n", name)
|
|
return nil
|
|
}
|
|
```
|
|
|
|
### 5. Output Formats
|
|
Support multiple output formats:
|
|
|
|
```go
|
|
switch output {
|
|
case "json":
|
|
return printJSON(pods)
|
|
case "yaml":
|
|
return printYAML(pods)
|
|
default:
|
|
return printTable(pods)
|
|
}
|
|
```
|
|
|
|
## Testing
|
|
|
|
```go
|
|
func TestGetPodsCommand(t *testing.T) {
|
|
cmd := get.GetCmd
|
|
cmd.SetArgs([]string{"pods", "--namespace", "production"})
|
|
|
|
err := cmd.Execute()
|
|
if err != nil {
|
|
t.Errorf("Expected no error, got %v", err)
|
|
}
|
|
}
|
|
```
|
|
|
|
## Advanced Features
|
|
|
|
### 1. Watch Mode
|
|
```go
|
|
if watch {
|
|
return watchPods(namespace, selector)
|
|
}
|
|
```
|
|
|
|
### 2. Label Selectors
|
|
```go
|
|
podsCmd.Flags().StringVarP(&selector, "selector", "l", "", "label selector (e.g., app=nginx)")
|
|
```
|
|
|
|
### 3. Field Selectors
|
|
```go
|
|
podsCmd.Flags().StringVar(&fieldSelector, "field-selector", "", "field selector (e.g., status.phase=Running)")
|
|
```
|
|
|
|
### 4. Multiple Output Formats
|
|
```go
|
|
podsCmd.Flags().StringVarP(&output, "output", "o", "text", "output format (text|json|yaml|wide)")
|
|
```
|
|
|
|
This example provides a complete kubectl-style CLI structure that you can adapt for your resource management needs.
|