kubeusr - Kubernetes User Management CLI

A command-line tool for managing Kubernetes users with RBAC integration.

Features

Create Users: Generate certificates and kubeconfig files for new users
Delete Users: Revoke access and clean up user resources
List Users: View all managed users and their configurations
Rotate Certificates: Update user certificates for security
Test Permissions: Verify user access and permissions
Role-based Access: Support for predefined roles with specific permissions

Installation

Quick Install Script (Recommended)

curl -sSL https://raw.githubusercontent.com/s4l10u/kubeusr/main/scripts/install.sh | bash

Manual Installation

Download the latest release from GitHub Releases
Extract the binary for your platform

Move it to a directory in your PATH:

tar -xzf kubeusr-linux-amd64.tar.gz
sudo mv kubeusr-linux-amd64 /usr/local/bin/kubeusr
chmod +x /usr/local/bin/kubeusr

Build from Source

git clone https://github.com/s4l10u/kubeusr.git
cd kubeusr
make build

Install Binary (from source)

make install

This installs kubeusr to your $GOPATH/bin directory.

Platform Support

kubeusr supports the following platforms:

Linux (amd64, arm64)
macOS (amd64, arm64)
Windows (amd64)

Quick Start

1. Check your kubectl context

# Verify you're connected to the right cluster
kubeusr context

# Verbose output shows more details
kubeusr context -v

2. Setup RBAC Roles (One-time)

# Setup all required RBAC roles in your cluster
kubeusr setup

3. Create Users

# Single namespace
kubeusr create --user john --role developer --namespace production

# Multiple namespaces
kubeusr create -u alice -r developer --namespaces prod,staging,dev

# With specific group
kubeusr create -u bob -r limited-admin -n staging -g admin-team

4. List Users

# List all users
kubeusr list

# Filter by role
kubeusr list --role developer

# JSON output
kubeusr list --output json

5. Test User Permissions

# Test specific user
kubeusr test --user john

# Test kubeconfig file
kubeusr test --kubeconfig /path/to/user-kubeconfig.yaml

6. Rotate Certificates

# Rotate single user
kubeusr rotate --user john

# Rotate all users
kubeusr rotate --all

7. Delete User

# Delete user (with confirmation)
kubeusr delete --user john

# Force delete
kubeusr delete --user john --force

Available Roles

Role	Description	Permissions
`limited-admin`	Administrative access without superuser privileges	Manage applications, pods, services, secrets. Cannot modify RBAC or nodes
`developer`	Namespace-scoped development access	Full access within assigned namespaces
`devops`	Deployment and infrastructure management	Cluster-wide deployment and infrastructure access
`reader`	Read-only access	View-only access to cluster resources
`security-auditor`	Security-focused read access	Read access to security-related resources
`support`	Limited operational access	Basic troubleshooting and support operations

Commands

Global Flags

--kubeconfig: Path to kubeconfig file (uses kubectl's resolution: KUBECONFIG env var, then $HOME/.kube/config)
--namespace, -n: Target namespace (default: production)
--organization: Organization name for certificate (default: kubernetes-users)
--verbose, -v: Verbose output
--config: Config file (default: $HOME/.kubeusr.yaml)

context

Display the current kubectl context that kubeusr will use.

kubeusr context
kubeusr context -v  # verbose output

setup

Setup RBAC roles in the cluster (one-time operation).

kubeusr setup [--force]

Flags:

--force, -f: Force update existing roles

create

Create a new Kubernetes user.

kubeusr create --user <username> --role <role> [--namespace <ns>] [--group <group>]
kubeusr create --user <username> --role <role> --namespaces <ns1,ns2,ns3>

Flags:

--user, -u: Username (required)
--role, -r: User role (required)
--group, -g: User group (optional)
--namespaces: Comma-separated list of namespaces (alternative to --namespace)

delete

Delete a Kubernetes user.

kubeusr delete --user <username> [--force]

Flags:

--user, -u: Username (required)
--force, -f: Force deletion without confirmation

list

List all Kubernetes users.

kubeusr list [--role <role>] [--output <format>]

Flags:

--role, -r: Filter by role
--output, -o: Output format (table, json, yaml)

rotate

Rotate user certificates.

kubeusr rotate --user <username>
kubeusr rotate --all

Flags:

--user, -u: Username to rotate
--all, -a: Rotate all users

test

Test user permissions.

kubeusr test --user <username>
kubeusr test --kubeconfig <path>

Flags:

--user, -u: Username to test
--kubeconfig, -k: Kubeconfig file to test

Configuration

kubeusr supports configuration via YAML file at $HOME/.kubeusr.yaml:

kubeconfig: /path/to/kubeconfig
namespace: production
organization: my-company  # Organization name for certificates
verbose: false

# Default settings for user creation
defaults:
  namespace: production
  organization: kubernetes-users
  backup_retention_days: 30

# Directory settings
directories:
  base_dir: ~/.kube/kubeusr
  backup_dir: ~/.kube/kubeusr/backups

File Locations

User kubeconfigs: ~/.kube/kubeusr/<username>-kubeconfig.yaml
User info: ~/.kube/kubeusr/<username>-info.yaml
Backups: ~/.kube/kubeusr/backups/

Examples

Complete User Lifecycle

# 0. Verify kubectl context
kubeusr context

# 1. One-time setup (creates all RBAC roles)
kubeusr setup

# 2. Create developer user with access to multiple namespaces
kubeusr create -u dev1 -r developer --namespaces development,staging,testing

# 3. Verify permissions
kubeusr test -u dev1

# 4. List all users
kubeusr list

# 5. Rotate certificates (recommended every 90 days)
kubeusr rotate -u dev1

# 6. Remove user when no longer needed (cleans up all namespace bindings)
kubeusr delete -u dev1

Context Switching

# kubeusr uses the same context as kubectl
kubectl config current-context
kubeusr context

# Switch contexts
kubectl config use-context production-cluster
kubeusr context  # now uses production-cluster

# Use KUBECONFIG environment variable
export KUBECONFIG=/path/to/different/config
kubeusr context  # uses the new config

# Use specific kubeconfig file
kubeusr --kubeconfig /path/to/config context

Batch Operations

# Setup roles first
kubeusr setup

# Create multiple users with different namespace access
kubeusr create -u dev1 -r developer --namespaces dev,test
kubeusr create -u dev2 -r developer --namespaces dev,staging  
kubeusr create -u ops1 -r devops --namespaces prod,staging,dev

# Create users with custom organization
kubeusr create -u contractor1 -r developer -n dev --organization external-contractors

# Rotate all certificates
kubeusr rotate --all

# List users by role
kubeusr list -r developer -o json | jq '.[] | .username'

Security Considerations

Certificate Rotation: Rotate certificates regularly (every 90 days recommended)
Backup Management: Regularly clean up old backups
Access Reviews: Periodically review user access with kubeusr list
Permission Testing: Use kubeusr test to verify user permissions
Principle of Least Privilege: Assign minimal required roles

Troubleshooting

Common Issues

Certificate not approved

kubectl get csr
kubectl certificate approve <csr-name>

Permission denied

# Verify you have admin access
kubectl auth can-i "*" "*" --all-namespaces

# Check RBAC is applied
kubectl get clusterroles | grep -E "(limited-admin|developer|devops)"

User not found

# Check user files exist
ls ~/.kube/kubeusr/

Debug Mode

Run any command with -v for verbose output:

kubeusr create -u test -r reader -v

Development

Prerequisites

Go 1.21+
Kubernetes cluster access
kubectl configured

Building

# Development setup
make dev-setup

# Format and test
make fmt vet test

# Build
make build

# Build for all platforms
make build-all

Testing

# Run tests
make test

# Test against real cluster (requires kubectl access)
go test ./pkg/user -v

Contributing

Fork the repository
Create feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

PapiHack/kubeusr

kubeusr - Kubernetes User Management CLI

Features

Installation

Quick Install Script (Recommended)

Manual Installation

Build from Source

Install Binary (from source)

Platform Support

Quick Start

1. Check your kubectl context

2. Setup RBAC Roles (One-time)

3. Create Users

4. List Users

5. Test User Permissions

6. Rotate Certificates

7. Delete User

Available Roles

Commands

Global Flags

context

setup

create

delete

list

rotate

test

Configuration

File Locations

Examples

Complete User Lifecycle

Context Switching

Batch Operations

Security Considerations

Troubleshooting

Common Issues

Debug Mode

Development

Prerequisites

Building

Testing

Contributing

License