> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akria.net/llms.txt
> Use this file to discover all available pages before exploring further.

# 管理测试 | Admin Environment

> 管理员操作手册 - 环境创建、权限管理和资源监控

# 🛡️ 管理测试环境手册 | Admin Test Environment Guide

本手册面向集群管理员，提供测试环境的创建、权限管理、资源监控和故障处理等完整操作指南。

<Info>
  本环境采用多租户隔离设计，通过 RBAC 和 ResourceQuota 实现严格的权限控制和资源隔离。
</Info>

## 📋 目录 | Table of Contents

<AccordionGroup>
  <Accordion title="环境创建" icon="plus">
    创建新的开发环境命名空间
  </Accordion>

  <Accordion title="权限管理" icon="key">
    生成开发人员 kubeconfig 配置
  </Accordion>

  <Accordion title="资源配额" icon="gauge">
    配置和管理资源限制
  </Accordion>

  <Accordion title="监控与验证" icon="chart-line">
    检查环境状态和权限隔离
  </Accordion>

  <Accordion title="扩容与维护" icon="wrench">
    在线扩容和环境清理
  </Accordion>
</AccordionGroup>

## 🏗️ 环境创建 | Environment Creation

### 创建新的开发环境

<Steps>
  <Step title="创建命名空间">
    ```bash theme={null}
    kubectl create namespace dev-1
    ```

    替换 `dev-1` 为对应的环境编号（dev-2, dev-3, dev-4 等）。
  </Step>

  <Step title="应用资源配额">
    ```bash theme={null}
    kubectl apply -f manifests/dev/admin/dev-1/quota.yaml
    kubectl apply -f manifests/dev/admin/dev-1/limits.yaml
    ```

    这将为环境设置 CPU、内存、存储等资源限制。
  </Step>

  <Step title="验证创建">
    ```bash theme={null}
    # 查看命名空间
    kubectl get ns dev-1

    # 查看配额
    kubectl describe quota dev-quota -n dev-1
    ```
  </Step>
</Steps>

### 资源配额配置示例

<Accordion title="查看 quota.yaml 示例" icon="file-code">
  ```yaml theme={null}
  apiVersion: v1
  kind: ResourceQuota
  metadata:
    name: dev-quota
    namespace: dev-1
  spec:
    hard:
      requests.cpu: "4"
      requests.memory: 8Gi
      limits.cpu: "4"
      limits.memory: 8Gi
      persistentvolumeclaims: "5"
      requests.storage: 20Gi
      pods: "20"
  ```
</Accordion>

<Accordion title="查看 limits.yaml 示例" icon="file-code">
  ```yaml theme={null}
  apiVersion: v1
  kind: LimitRange
  metadata:
    name: dev-limits
    namespace: dev-1
  spec:
    limits:
    - default:
        cpu: "100m"
        memory: "256Mi"
      defaultRequest:
        cpu: "100m"
        memory: "256Mi"
      type: Container
  ```
</Accordion>

## 🔐 权限管理 | Permission Management

### 生成开发人员 kubeconfig

<Warning>
  生成的 kubeconfig 文件包含敏感 Token，请妥善保管，严禁泄露。
</Warning>

<Steps>
  <Step title="准备脚本">
    ```bash theme={null}
    cd manifests/dev/admin
    chmod +x create-dev-kubeconfig.sh
    ```
  </Step>

  <Step title="编辑脚本（如需要）">
    如需修改命名空间，编辑脚本中的 `NAMESPACE` 变量。
  </Step>

  <Step title="执行脚本">
    ```bash theme={null}
    ./create-dev-kubeconfig.sh dev-1
    ```

    脚本会自动执行：

    * 创建 ServiceAccount (`dev-user`)
    * 创建 RoleBinding（绑定 `edit` 角色）
    * 生成 Token 并导出为 kubeconfig 格式
  </Step>

  <Step title="获取配置文件">
    执行成功后，会在当前目录生成 `dev-1-kubeconfig.yaml`。
  </Step>
</Steps>

### 脚本工作原理

<CardGroup cols={3}>
  <Card title="创建 ServiceAccount" icon="user">
    在目标 Namespace 创建 `dev-user` ServiceAccount
  </Card>

  <Card title="绑定角色" icon="link">
    将 K8s 原生的 `edit` 角色绑定给 ServiceAccount（仅限该 Namespace）
  </Card>

  <Card title="生成 Token" icon="key">
    创建 Secret 并提取 Token，生成标准 kubeconfig 格式
  </Card>
</CardGroup>

### 分发给开发人员

<Steps>
  <Step title="安全传输">
    通过安全渠道（加密邮件、安全聊天工具等）将 `dev-1-kubeconfig.yaml` 发送给对应的开发人员。
  </Step>

  <Step title="使用指导">
    指导开发人员：

    * 保存文件到本地安全位置
    * 设置 `KUBECONFIG` 环境变量
    * 验证连接：`kubectl get pods -n dev-1`
  </Step>
</Steps>

## 📊 资源配额管理 | Resource Quota Management

### 查看配额使用情况

```bash theme={null}
# 查看所有开发环境的配额
for ns in dev-1 dev-2 dev-3 dev-4; do
  echo "=== $ns ==="
  kubectl describe quota dev-quota -n $ns
done
```

### 在线扩容环境

<Tip>
  更新 `ResourceQuota` 是**热更新**，不会影响正在运行的 Pod，只会影响新创建或重启后的 Pod 调度。
</Tip>

<Steps>
  <Step title="修改配额文件">
    编辑 `manifests/dev/admin/dev-1/quota.yaml`，调大 `hard` 部分的数值：

    ```yaml theme={null}
    spec:
      hard:
        requests.cpu: "8"        # 从 4 增加到 8
        requests.memory: 16Gi    # 从 8Gi 增加到 16Gi
        limits.cpu: "8"
        limits.memory: 16Gi
    ```
  </Step>

  <Step title="应用更改">
    ```bash theme={null}
    kubectl apply -f manifests/dev/admin/dev-1/quota.yaml
    ```
  </Step>

  <Step title="验证生效">
    ```bash theme={null}
    kubectl describe quota dev-quota -n dev-1
    ```

    查看 `Used` 和 `Hard` 列，确认新限制已生效。
  </Step>
</Steps>

<Warning>
  如果新限制调小了且当前已用量超标，现有 Pod 仍会运行，但无法再启动任何新 Pod。
</Warning>

## 🔍 监控与验证 | Monitoring & Verification

### 检查命名空间状态

```bash theme={null}
# 查看所有开发相关的命名空间
kubectl get ns | grep dev

# 查看特定环境的资源
kubectl get pods,svc,sa -n dev-1
```

### 验证权限隔离

利用 `kubectl auth can-i` 模拟开发用户身份验证权限隔离：

<CodeGroup>
  ```bash 验证本命名空间权限 theme={null}
  # 验证 dev-user 可以在其所属 namespace 获取 Pod (应返回 yes)
  kubectl auth can-i get pods -n dev-1 --as=system:serviceaccount:dev-1:dev-user
  ```

  ```bash 验证跨命名空间隔离 theme={null}
  # 验证 dev-user 不能跨 namespace 访问 (应返回 no)
  kubectl auth can-i get pods -n dev-2 --as=system:serviceaccount:dev-1:dev-user
  ```

  ```bash 验证集群级权限 theme={null}
  # 验证 dev-user 无法访问集群级资源 (应返回 no)
  kubectl auth can-i get nodes --as=system:serviceaccount:dev-1:dev-user
  ```
</CodeGroup>

### 管理员验证方法

<AccordionGroup>
  <Accordion title="方法 A：临时验证（推荐）" icon="clock">
    直接指定 kubeconfig 文件运行命令：

    ```bash theme={null}
    kubectl --kubeconfig=./dev-1-kubeconfig.yaml get pods
    ```

    无需切换终端，可以同时管理生产环境和验证开发环境。
  </Accordion>

  <Accordion title="方法 B：合并上下文（高级）" icon="code-branch">
    如果您希望在同一个 kubectl 中自由切换上下文：

    1. **合并配置文件**（仅当前终端生效）：
       ```bash theme={null}
       export KUBECONFIG=$HOME/.kube/config:$(pwd)/dev-1-kubeconfig.yaml
       ```

    2. **查看所有上下文**：
       ```bash theme={null}
       kubectl config get-contexts
       ```
       您会看到 `dev-user-dev-1-context` 和原来的 `default` 上下文。

    3. **切换上下文**：
       ```bash theme={null}
       kubectl config use-context dev-user-dev-1-context
       ```
  </Accordion>
</AccordionGroup>

## 🛠️ 常用管理命令 | Common Admin Commands

### 批量检查资源

<CodeGroup>
  ```bash 检查所有开发环境 theme={null}
  for ns in dev-1 dev-2 dev-3 dev-4; do
    echo "=== $ns ==="
    kubectl get pods,svc -n $ns
  done
  ```

  ```bash 检查资源使用情况 theme={null}
  kubectl top pods -n dev-1
  kubectl top nodes
  ```

  ```bash 查看事件 theme={null}
  kubectl get events -n dev-1 --sort-by='.lastTimestamp'
  ```
</CodeGroup>

### 快速清理

如果需要删除并重建测试环境：

```bash theme={null}
# 删除 namespace 会自动清理其下的所有 sa, secret 和 rolebinding
kubectl delete ns dev-1

# 重新创建
kubectl create namespace dev-1
kubectl apply -f manifests/dev/admin/dev-1/quota.yaml
kubectl apply -f manifests/dev/admin/dev-1/limits.yaml
```

<Danger>
  删除命名空间会永久删除该环境下的所有资源，包括持久化存储（PVC）。请谨慎操作！
</Danger>

## 📈 资源监控 | Resource Monitoring

### 实时监控面板

访问 [Grafana 监控面板](https://monitor.akria.net) 查看：

* 集群整体资源使用情况
* 各命名空间的资源消耗
* Pod 运行状态和健康度

### 命令行监控

```bash theme={null}
# 查看节点资源
kubectl top nodes

# 查看所有命名空间的资源使用
kubectl top pods --all-namespaces

# 查看特定环境的资源使用
kubectl top pods -n dev-1
```

## 🔧 故障处理 | Troubleshooting

### 常见问题

<AccordionGroup>
  <Accordion title="开发人员无法连接集群" icon="exclamation-triangle">
    **检查步骤**：

    1. 验证 ServiceAccount 是否存在：`kubectl get sa -n dev-1`
    2. 检查 RoleBinding：`kubectl get rolebinding -n dev-1`
    3. 验证 Token Secret：`kubectl get secret -n dev-1 | grep dev-user`
    4. 重新生成 kubeconfig
  </Accordion>

  <Accordion title="资源配额不足" icon="exclamation-triangle">
    **解决方法**：

    1. 查看当前使用：`kubectl describe quota dev-quota -n dev-1`
    2. 评估是否需要扩容
    3. 修改配额文件并应用
    4. 通知开发人员资源已扩容
  </Accordion>

  <Accordion title="跨命名空间访问问题" icon="exclamation-triangle">
    **验证隔离**：

    ```bash theme={null}
    # 验证 dev-1 用户无法访问 dev-2
    kubectl auth can-i get pods -n dev-2 --as=system:serviceaccount:dev-1:dev-user
    ```

    如果返回 `yes`，说明权限配置有误，需要检查 RoleBinding。
  </Accordion>
</AccordionGroup>

## 📚 相关文档 | Related Documentation

<CardGroup cols={2}>
  <Card title="测试环境使用手册" icon="flask" href="/technical/infra-deploy/test-environment-guide">
    开发人员操作指南
  </Card>

  <Card title="基础设施概览" icon="server" href="/technical/infra-deploy/infrastructure-overview">
    了解集群架构
  </Card>

  <Card title="部署指南" icon="rocket" href="/technical/infra-deploy/deployment-guide">
    生产环境部署操作
  </Card>

  <Card title="YAML 规范" icon="file-code" href="/technical/infra-deploy/yaml-best-practices">
    配置文件标准格式
  </Card>
</CardGroup>

<Note>
  定期检查各环境的资源使用情况，及时响应开发人员的资源需求，确保环境稳定运行。
</Note>