# kk

**Repository Path**: nbcx/kk

## Basic Information

- **Project Name**: kk
- **Description**: kk is a CLI tool to manage kubernetes pods (info, restart, shell) by name.
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-16
- **Last Updated**: 2026-10-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# kk - Kubernetes Pod Manager

`kk` is a simple yet powerful CLI tool designed to streamline Kubernetes pod management. It allows you to quickly find, view logs, restart, and shell into pods using fuzzy name matching across *all* namespaces.

## Features

- **Fuzzy Matching**: Find pods by partial name search.
- **Global Search**: Searches for pods across all namespaces by default.
- **Interactive Selection**: Commands that act on a single pod prompt for selection when multiple pods match.
- **Container Selection**: Interactive prompt to select a container if a pod has multiple containers (for logs and shell).
- **Rich Command Set**:
  - Watch pod status across namespaces, including CPU and memory usage.
  - Stream logs with advanced filtering (`grep`/`filter`).
  - "Live" view shortcut for monitoring logs.
  - Restart pods.
  - Shell into pods.

## Installation

You can build and install `kk` from source. Ensure you have Go installed (1.18+ recommended).

```bash
git clone <repository-url>
cd kk
go install .
```

Or build a binary:

```bash
go build -o kk .
# Move 'kk' to a directory in your PATH
mv kk /usr/local/bin/
```

## Usage

The general syntax is:

```bash
kk [command] [pod_name_pattern] [flags]
```

If no command is specified, `kk` continuously displays a status table for all matching pods.

### Global Flags

- `--kubeconfig`: Path to your kubeconfig file (defaults to `~/.kube/config`).
- `--namespace`, `-n`: Match namespace names by case-insensitive substring. The default status view uses all namespaces when omitted; when set, it selects a matching namespace before listing pods (one match automatically, multiple matches interactively). Also supplies the initial namespace filter for `pods` and the pod selection filter for `restart`, `shell`, `logs`, `live`, and `cm` / `configmap`.

```bash
# Start namespace selection with names containing 'prod'
kk pods -n prod

# Start pod selection with namespaces containing 'prod' and pod names containing 'api'
kk logs api -n prod
kk restart api -n prod
kk shell api -n prod
kk cm api -n prod
```

### Commands

#### 1. Pod Status (Default)

Display all pods whose names contain the query, with columns `NAMESPACE`, `NAME`, `READY`, `STATUS`, `RESTARTS`, `AGE`, `CPU`, and `MEMORY`. Without `-n`, results span all namespaces and no selection is required.

The table refreshes every two seconds, including when no pods match yet. Type to edit the pod name filter, use Backspace to delete, and press Esc or Ctrl+C to exit. The local `--watch` / `-w` flag defaults to `true`; use `--watch=false` for one-time output.

```bash
# Watch all pods whose names contain 'api', across all namespaces
kk api

# Select a namespace containing 'prod', then watch all matching pods in it
kk api -n prod

# Print the matching pods once
kk api --watch=false
```

Use `kk pods` to choose a namespace before displaying its pod status table.

#### 2. View Logs (`logs`)

View logs for a pod. Supports tailing, following, and filtering.

```bash
# Basic log view
kk logs my-app

# Follow logs (stream)
kk logs -f my-app

# Tail last 500 lines
kk logs --tail=500 my-app

# Filter logs by keyword (client-side grep)
kk logs --grep="error" my-app
```

#### 3. Live Logs (`live`)

A shortcut command for `logs -f --tail=100`. Great for quickly checking recent activity.

```bash
kk live my-app
# Equivalent to: kk logs -f --tail=100 my-app
```

#### 4. Restart Pod (`restart`)

Restart a pod by deleting it (Kubernetes will recreate it if it's managed by a deployment/replica set).

```bash
kk restart my-app
```

#### 5. Shell (`shell`)

Open an interactive shell (`sh`) inside a pod's container.

```bash
kk shell my-app
```

#### 6. View/Edit ConfigMaps (`configmap`)

List ConfigMaps associated with a pod (via volumes or env vars) and edit them.

```bash
kk configmap my-app
# or
kk cm my-app
```

#### 7. List Namespaces (`namespaces` / `ns`)

List namespaces with case-insensitive substring filtering. The local `--filter` / `-f` flag sets the initial filter; `-n` continues to apply to selection flows and does not filter this list.

In a terminal, type to edit the filter, use Backspace to delete, and press Esc or Ctrl+C to exit. Results update immediately; an empty result stays editable, and a single match remains a list. With non-TTY input or output, print the filtered list once for piping or redirection.

```bash
# Browse all namespaces
kk ns

# Start with namespace names containing 'prod'
kk ns -f prod
kk namespaces --filter prod
```