# k8s-podman-demo

**Repository Path**: imjasonliao/k8s-podman-demo

## Basic Information

- **Project Name**: k8s-podman-demo
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-30
- **Last Updated**: 2025-10-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# K8s Podman Demo - Mac M1 Kubernetes 演示项目

一个在 Mac M1 上使用 Podman 和 Kind 构建的完整 Kubernetes 演示项目，展示自动扩展、负载均衡和高可用性特性。

## 🚀 项目特性

- ✅ **Mac M1 优化** - 专为 Apple Silicon 架构设计
- ✅ **Podman 容器运行时** - 使用 Podman 替代 Docker
- ✅ **Kind 集群** - 轻量级 Kubernetes 集群
- ✅ **自动扩展 (HPA)** - 基于 CPU 和内存使用率的自动扩缩容
- ✅ **负载均衡** - 轮询算法分发请求到不同 Pod
- ✅ **高可用性** - 最少 2 个 Pod 实例，支持扩展到 6 个
- ✅ **资源优化** - 针对 4CPU/6G 内存环境优化
- ✅ **健康检查** - 完整的存活、就绪和启动探针
- ✅ **Metrics Server** - 集成资源监控和自动扩展

## 📁 项目结构

```
k8s-podman-demo/
├── app/                          # 应用代码
│   ├── app.py                   # Flask 应用
│   ├── requirements.txt         # Python 依赖
│   └── Dockerfile               # 容器镜像配置
├── deployment/                  # Kubernetes 配置
│   ├── 00-kind-k8s-demo.yaml   # Kind 集群配置
│   ├── 00-metrics-server.yaml  # Metrics Server 配置
│   ├── 01-namespace.yaml       # 命名空间配置
│   ├── 02-k8s-demo-app.yaml    # 应用部署配置
│   └── 03-hpa.yaml             # 自动扩展配置
├── deploy.sh                   # 一键部署脚本
└── README.md                   # 项目文档
```

## 🛠️ 环境要求

### 系统要求
- macOS (Apple Silicon M1/M2)
- 至少 4CPU 和 6GB 内存分配给 Podman

### 工具安装
```bash
# 安装 Homebrew (如果尚未安装)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装必要工具
brew install podman kind kubectl hey

# 初始化 Podman
podman machine init
podman machine start
```

## ⚡ 快速开始

### 一键部署
```bash
# 克隆项目
git clone <repository-url>
cd k8s-podman-demo

# 一键部署所有组件
chmod +x deploy.sh
./deploy.sh
```

### 手动部署步骤

1. **创建 Kind 集群**
   ```bash
   kind create cluster --config deployment/00-kind-k8s-demo.yaml
   ```

2. **安装 Metrics Server**
   ```bash
   kubectl apply -f deployment/00-metrics-server.yaml
   ```

3. **构建和加载应用镜像**
   ```bash
   cd app
   podman build -t localhost/k8s-demo-app:0.0.1 -f Dockerfile .
   cd ..
   kind load docker-image localhost/k8s-demo-app:0.0.1 --name k8s-demo
   ```

4. **部署应用到 Kubernetes**
   ```bash
   kubectl apply -f deployment/01-namespace.yaml
   kubectl apply -f deployment/02-k8s-demo-app.yaml
   kubectl apply -f deployment/03-hpa.yaml
   ```

## 🧪 测试和验证

### 基本功能测试
```bash
# 获取访问信息
NODE_IP=$(kubectl get nodes -o jsonpath='{.items[0].status.addresses[?(@.type=="InternalIP")].address}')
NODE_PORT=$(kubectl get service k8s-demo-service -n k8s-demo -o jsonpath='{.spec.ports[0].nodePort}')

# 测试应用端点
curl http://${NODE_IP}:${NODE_PORT}/
curl http://${NODE_IP}:${NODE_PORT}/health
curl http://${NODE_IP}:${NODE_PORT}/info
curl http://${NODE_IP}:${NODE_PORT}/api/v1/users
```

### 负载均衡测试
```bash
# 验证请求被轮询分配到不同 Pod
for i in {1..10}; do
    curl -s http://${NODE_IP}:${NODE_PORT}/info | grep -o '"pod_name":"[^"]*"'
    sleep 1
done
```

### 自动扩展测试
```bash
# 监控自动扩展（在终端1运行）
watch -n 2 'kubectl get hpa -n k8s-demo && kubectl get pods -n k8s-demo'

# 生成负载触发扩展（在终端2运行）
kubectl run -it --rm load-test --image=busybox -- /bin/sh -c 'while true; do wget -q -O- http://k8s-demo-service.k8s-demo.svc.cluster.local/cpu-intensive; done'
```

## 📊 监控和管理

### 查看集群状态
```bash
# 查看所有资源状态
kubectl get all -n k8s-demo

# 查看详细部署信息
kubectl describe deployment k8s-demo-app -n k8s-demo

# 查看 HPA 状态和事件
kubectl describe hpa k8s-demo-hpa -n k8s-demo

# 查看资源使用情况
kubectl top pods -n k8s-demo
kubectl top nodes
```

### 查看应用日志
```bash
# 查看特定 Pod 日志
kubectl logs -f -n k8s-demo <pod-name>

# 查看所有应用 Pod 日志
kubectl logs -f -n k8s-demo -l app=k8s-demo-app
```

### 进入 Pod 调试
```bash
kubectl exec -it -n k8s-demo <pod-name> -- /bin/sh
```

## 🧹 资源清理
### clean.sh清理 Kubernetes 资源
```bash
# 一键部署所有组件
chmod +x clean.sh
./clean.sh
```

### 手动清理 Kubernetes 资源
```bash
# 删除应用部署
kubectl delete -f deployment/ --recursive

# 或单独删除资源
kubectl delete deployment k8s-demo-app -n k8s-demo
kubectl delete service k8s-demo-service -n k8s-demo
kubectl delete hpa k8s-demo-hpa -n k8s-demo
kubectl delete namespace k8s-demo
```

### 清理集群
```bash
# 删除 Kind 集群
kind delete cluster --name k8s-demo

# 停止 Podman 虚拟机
podman machine stop
```

## 🔧 故障排除

### 常见问题解决

1. **HPA 显示 `<unknown>` 指标**
   ```bash
   # 检查 Metrics Server 状态
   kubectl get apiservices | grep metrics
   kubectl logs -n kube-system -l k8s-app=metrics-server
   ```

2. **Pod 无法启动**
   ```bash
   # 查看 Pod 详细状态
   kubectl describe pod -n k8s-demo <pod-name>
   
   # 查看 Pod 日志
   kubectl logs -n k8s-demo <pod-name>
   ```

3. **服务无法访问**
   ```bash
   # 检查服务端点
   kubectl get endpoints -n k8s-demo k8s-demo-service
   
   # 使用端口转发测试
   kubectl port-forward service/k8s-demo-service -n k8s-demo 8080:80
   ```

4. **镜像加载失败**
   ```bash
   # 验证镜像是否加载到集群
   kind get nodes --name k8s-demo | xargs -I {} docker exec {} crictl images | grep k8s-demo-app
   
   # 重新加载镜像
   kind load docker-image localhost/k8s-demo-app:0.0.1 --name k8s-demo
   ```

## 📝 API 端点

| 端点                | 方法 | 描述                    |
| ------------------- | ---- | ----------------------- |
| `/`                 | GET  | 欢迎页面，显示 Pod 信息 |
| `/health`           | GET  | 健康检查端点            |
| `/info`             | GET  | 详细的 Pod 和请求信息   |
| `/cpu-intensive`    | GET  | 模拟 CPU 密集型任务     |
| `/memory-intensive` | GET  | 模拟内存密集型任务      |
| `/api/v1/users`     | GET  | 示例用户 API            |
| `/api/v1/products`  | GET  | 示例产品 API            |

## 🎯 学习要点

通过这个项目，您可以学习到：

1. **容器技术** - 使用 Podman 构建和管理容器镜像
2. **Kubernetes 基础** - Pods、Deployments、Services、Namespaces
3. **自动扩展** - Horizontal Pod Autoscaler 配置和使用
4. **服务发现** - Kubernetes Service 和负载均衡
5. **监控指标** - Metrics Server 集成和资源监控
6. **健康检查** - 存活、就绪和启动探针配置
7. **资源管理** - CPU 和内存资源限制与请求

## 🤝 贡献

欢迎提交 Issue 和 Pull Request 来改进这个项目！

## 📄 许可证

本项目采用 MIT 许可证。