# Java Microservice Helm Chart

## 概述

这是一个用于部署Java微服务应用到Kubernetes集群的Helm Chart。该Chart提供了完整的Kubernetes资源配置，包括Deployment、Service和ConfigMap，支持灵活的应用配置和资源管理。

**Chart版本：** 0.1.0  
**应用版本：** 1.0  
**API版本：** v2

---

## 主要特性

✅ **开箱即用的Deployment配置** - 包含health checks、资源限制和安全上下文  
✅ **灵活的服务发现** - 支持ClusterIP、NodePort和LoadBalancer类型  
✅ **应用配置管理** - 通过ConfigMap管理application.properties和application.yml  
✅ **Spring Boot集成** - 原生支持Spring Boot Actuator端点  
✅ **可扩展设计** - 完整的Helm模板化和参数配置  
✅ **生产就绪** - 包含liveness probe和readiness probe  

---

## 项目结构

```
java-microservice/
├── Chart.yaml                    # Helm Chart定义文件
├── values.yaml                   # 默认配置值
├── README.md                      # 本文件
└── templates/
    ├── deployment.yaml           # Kubernetes Deployment资源模板
    ├── service.yaml              # Kubernetes Service资源模板
    └── configmap.yaml            # Kubernetes ConfigMap资源模板
```

### 文件说明

| 文件 | 说明 |
|------|------|
| **Chart.yaml** | 定义Helm Chart的元数据（名称、版本、描述等） |
| **values.yaml** | 包含所有可配置的默认值和参数 |
| **templates/deployment.yaml** | 定义Kubernetes Pod、副本和容器配置 |
| **templates/service.yaml** | 定义Service用于服务发现和负载均衡 |
| **templates/configmap.yaml** | 定义ConfigMap用于存储应用配置文件 |

---

## 快速开始

### 前置条件

- Kubernetes集群 (1.16+)
- Helm 3.0+
- Docker镜像仓库访问权限

### 安装

#### 1. 使用默认配置安装

```bash
helm install java-app ./java-microservice
```

#### 2. 自定义配置安装

```bash
helm install java-app ./java-microservice \
  --set image.repository=your-registry/java-app \
  --set image.tag=1.0.0 \
  --set app.replicaCount=3
```

#### 3. 使用自定义values文件安装

```bash
helm install java-app ./java-microservice -f custom-values.yaml
```

#### 4. 验证安装

```bash
# 查看已安装的Release
helm list

# 获取Deployment详情
kubectl get deployment java-microservice

# 查看Pod状态
kubectl get pods -l app=java-microservice

# 查看Service
kubectl get svc java-microservice
```

---

## 配置参数

### 应用配置

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `app.name` | `java-microservice` | 应用名称，用于Deployment和Service命名 |
| `app.replicaCount` | `1` | Pod副本数量 |

### 镜像配置

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `image.repository` | `your-registry/java-app` | Docker镜像仓库地址 |
| `image.tag` | `1.0.0` | Docker镜像标签/版本 |
| `image.pullPolicy` | `IfNotPresent` | 镜像拉取策略（Always/IfNotPresent/Never） |

### Service配置

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `service.type` | `ClusterIP` | Service类型（ClusterIP/NodePort/LoadBalancer） |
| `service.port` | `8080` | Service暴露的端口 |
| `service.targetPort` | `8080` | 容器目标端口 |

### 应用属性配置

#### Properties文件配置（`.properties` 格式）

```yaml
application.properties:
spring.application.name={{ app.name }}
spring.protocol.name=spring
server.port={{ app.port }}
```

#### YAML文件配置（`.yml` 格式）

```yaml
config.yml:
  logging:
    level:
      root: INFO
      com:
        example: DEBUG
  management:
    endpoints:
      web:
        exposure:
          include: health,info,metrics
    endpoint:
      health:
        show-details: when-authorized
```

### 资源配置

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `resources.requests.cpu` | `250m` | CPU请求量 |
| `resources.requests.memory` | `256Mi` | 内存请求量 |
| `resources.limits.cpu` | `500m` | CPU限制量 |
| `resources.limits.memory` | `512Mi` | 内存限制量 |

### 高级配置

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `podAnnotations` | `{}` | Pod注解 |
| `securityContext` | `{}` | Pod安全上下文 |
| `nodeSelector` | `{}` | 节点选择器 |
| `tolerations` | `[]` | 容忍度配置 |
| `affinity` | `{}` | Pod亲和力配置 |

---

## 使用示例

### 示例1：部署到开发环境

```bash
helm install java-dev ./java-microservice \
  --namespace dev \
  --create-namespace \
  --set image.repository=your-registry/java-app \
  --set image.tag=dev-latest \
  --set app.replicaCount=1
```

### 示例2：生产环境部署（高可用）

```bash
helm install java-prod ./java-microservice \
  --namespace prod \
  --create-namespace \
  --values prod-values.yaml
```

其中 `prod-values.yaml` 内容如下：

```yaml
app:
  replicaCount: 3

image:
  repository: your-registry/java-app
  tag: "1.0.0"

service:
  type: LoadBalancer
  port: 80
  targetPort: 8080

resources:
  requests:
    cpu: 500m
    memory: 512Mi
  limits:
    cpu: 1000m
    memory: 1024Mi
```

### 示例3：更新现有Release

```bash
helm upgrade java-app ./java-microservice \
  --set image.tag=1.1.0
```

### 示例4：配置数据库连接

编辑 `values.yaml` 中的数据库配置：

```yaml
config:
  properties:
    spring.datasource.url: jdbc:mysql://mysql-service:3306/mydb
    spring.datasource.username: appuser
    spring.datasource.password: secure-password
```

然后安装或升级：

```bash
helm install java-app ./java-microservice
```

---

## 模板详解

### Deployment Template (deployment.yaml)

**功能：**
- 定义应用Pod的部署配置
- 配置容器镜像、端口和环境变量
- 挂载ConfigMap作为配置文件
- 配置health checks（liveness和readiness probe）
- 支持资源限制和安全策略

**关键特性：**
```yaml
# Health Check配置
livenessProbe:
  httpGet:
    path: /actuator/health
    port: http
  initialDelaySeconds: 30
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /actuator/health
    port: http
  initialDelaySeconds: 5
  periodSeconds: 5

# 环境变量配置
env:
  - name: JAVA_OPTS
    value: "-Xmx512m -Xms256m"

# ConfigMap挂载
volumeMounts:
  - name: config-volume
    mountPath: /etc/config
    readOnly: true
```

### Service Template (service.yaml)

**功能：**
- 暴露应用服务到集群内外
- 支持多种服务类型
- 配置端口映射和负载均衡

**支持的Service类型：**
- `ClusterIP`：仅在集群内访问（默认）
- `NodePort`：通过节点IP和端口访问
- `LoadBalancer`：通过外部负载均衡器访问

### ConfigMap Template (configmap.yaml)

**功能：**
- 将应用配置外部化
- 支持`.properties`和`.yml`两种格式
- 配置无需重新构建镜像

**配置文件位置（容器内）：**
- `/etc/config/application.properties`
- `/etc/config/application.yml`

---

## 常见操作

### 查看Release状态

```bash
helm status java-app
```

### 查看Release使用的Values

```bash
helm get values java-app
```

### 查看Release部署的资源

```bash
helm get manifest java-app
```

### 测试模板渲染

```bash
helm template java-app ./java-microservice --debug
```

### 删除Release

```bash
helm uninstall java-app
```

### 查看Pod日志

```bash
kubectl logs -l app=java-microservice -f
```

### 访问应用

#### 本地端口转发（开发环境）

```bash
kubectl port-forward svc/java-microservice 8080:8080
curl http://localhost:8080/actuator/health
```

#### 通过Service（集群内）

```bash
curl http://java-microservice:8080/actuator/health
```

#### 通过NodePort

```bash
# 获取节点IP和NodePort
kubectl get nodes -o wide
kubectl get svc java-microservice

# 访问
curl http://<NODE_IP>:<NODE_PORT>/actuator/health
```

---

## 故障排查

### 问题1：Pod处于Pending状态

```bash
# 查看Pod事件
kubectl describe pod <pod-name>

# 检查资源可用性
kubectl top nodes
```

**解决方案：**
- 检查集群资源是否充足
- 调整资源请求和限制
- 检查节点是否有污点（taints）

### 问题2：镜像拉取失败

```bash
# 查看Pod日志
kubectl describe pod <pod-name>
```

**解决方案：**
- 验证镜像仓库地址
- 检查镜像标签是否正确
- 配置镜像拉取密钥（如果为私有仓库）

### 问题3：应用无法启动

```bash
# 查看容器日志
kubectl logs <pod-name>

# 进入容器调试
kubectl exec -it <pod-name> -- /bin/bash
```

**解决方案：**
- 检查应用配置是否正确
- 验证数据库连接信息
- 检查Spring Boot Actuator是否正确配置

### 问题4：Health Check失败

```bash
# 手动测试health endpoint
kubectl exec -it <pod-name> -- curl localhost:8080/actuator/health
```

**解决方案：**
- 调整probe的initialDelaySeconds
- 检查应用是否正确实现了health endpoint
- 查看应用日志获取更多信息

---

## 安全最佳实践

### 1. 使用私有镜像仓库

```bash
# 创建镜像拉取Secret
kubectl create secret docker-registry regcred \
  --docker-server=your-registry \
  --docker-username=username \
  --docker-password=password \
  --docker-email=email@example.com

# 在values.yaml中引用
imagePullSecrets:
  - name: regcred
```

### 2. 配置资源限制

始终为容器设置CPU和内存限制，防止资源耗尽。

### 3. 安全上下文配置

```yaml
securityContext:
  runAsNonRoot: true
  runAsUser: 1000
  readOnlyRootFilesystem: true
```

### 4. RBAC配置

为应用创建最小权限的Service Account。

### 5. 敏感信息管理

- 使用Kubernetes Secrets存储密码和API Key
- 不要在ConfigMap中存储敏感信息
- 定期轮换凭证

---

## 性能优化

### 1. 调整JVM内存参数

```yaml
env:
  - name: JAVA_OPTS
    value: "-Xmx1024m -Xms512m -XX:+UseG1GC"
```

### 2. 优化Health Check

```yaml
livenessProbe:
  initialDelaySeconds: 60  # 增加初始延迟时间
  periodSeconds: 30        # 减少检查频率
```

### 3. 配置副本和自动扩展

```bash
# 使用HPA（Horizontal Pod Autoscaler）
kubectl autoscale deployment java-microservice \
  --min=2 --max=10 --cpu-percent=80
```

---

## 升级和回滚

### 升级应用版本

```bash
# 使用新镜像标签升级
helm upgrade java-app ./java-microservice \
  --set image.tag=1.1.0

# 查看升级状态
helm status java-app
```

### 回滚到前一版本

```bash
# 查看历史发布
helm history java-app

# 回滚到指定版本
helm rollback java-app 1
```

---

## 监控和日志

### 查看应用日志

```bash
# 查看当前Pod日志
kubectl logs -l app=java-microservice

# 跟踪日志（实时）
kubectl logs -l app=java-microservice -f

# 查看前50行日志
kubectl logs -l app=java-microservice --tail=50
```

### Spring Boot Actuator端点

该Chart已配置以下Actuator端点：

- `/actuator/health` - 应用健康状态
- `/actuator/info` - 应用信息
- `/actuator/metrics` - 应用指标

访问这些端点：

```bash
kubectl exec -it <pod-name> -- \
  curl -s http://localhost:8080/actuator/health | json_pp
```

---

## 贡献指南

欢迎提交Issue和Pull Request来改进此Chart。

---

## 许可证

此Chart遵循开源许可证。

---

## 相关资源

- [Helm官方文档](https://helm.sh/docs/)
- [Kubernetes官方文档](https://kubernetes.io/docs/)
- [Spring Boot官方文档](https://spring.io/projects/spring-boot)
- [Spring Boot Actuator文档](https://spring.io/guides/gs/actuator-service/)

---

## 更新日志

### v0.1.0 (2026-01-15)
- 初始版本
- 支持基础Deployment、Service和ConfigMap
- 包含Spring Boot应用配置管理
- 配置Health Check和资源限制

---

## 常见问题（FAQ）

**Q: 如何修改应用配置而不重新部署？**  
A: 编辑ConfigMap并重启Pod即可：
```bash
kubectl rollout restart deployment/java-microservice
```

**Q: 支持多环境部署吗？**  
A: 是的，为每个环境创建不同的values文件，使用`-f`参数指定。

**Q: 如何扩展副本数量？**  
A: 使用`--set app.replicaCount=N`或编辑values.yaml。

**Q: 支持灰度发布吗？**  
A: 可以使用Helm升级，并通过修改镜像标签来实现灰度。

---

更多帮助请查看[官方Helm文档](https://helm.sh/docs/)