> ## 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.

# 模版规范 | YAML Standards

> K3s 集群部署配置的标准格式和最佳实践

# 🛠️ YAML 规范 | YAML Standards

为了确保部署成功并符合集群安全标准，请参考以下标准模板和最佳实践。

<Warning>
  所有部署必须使用 `project-team` 命名空间，错误的命名空间将导致部署失败。
</Warning>

## 📋 目录 | Table of Contents

<AccordionGroup>
  <Accordion title="基础部署配置" icon="server">
    包含 Deployment、Service 等核心资源
  </Accordion>

  <Accordion title="配置管理" icon="gear">
    ConfigMap 和 Secret 的使用规范
  </Accordion>

  <Accordion title="资源限制" icon="gauge">
    CPU 和内存的合理配置
  </Accordion>

  <Accordion title="健康检查" icon="heart-pulse">
    Liveness 和 Readiness 探针配置
  </Accordion>
</AccordionGroup>

## 1. 基础部署配置 | Base Deployment

### Deployment 模板

使用以下模板作为你的基础部署配置：

```yaml deployment.yaml theme={null}
apiVersion: apps/v1
kind: Deployment
metadata:
  name: your-app-name
  namespace: project-team
  labels:
    app: your-app-name
    version: v1.0.0
spec:
  replicas: 1
  selector:
    matchLabels:
      app: your-app-name
  template:
    metadata:
      labels:
        app: your-app-name
    spec:
      containers:
      - name: your-app
        image: your-image:tag
        imagePullPolicy: IfNotPresent
        ports:
        - containerPort: 8080
          name: http
        resources:
          requests:
            cpu: "100m"
            memory: "128Mi"
          limits:
            cpu: "500m"
            memory: "512Mi"
        env:
        - name: ENV_VAR
          value: "value"
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /ready
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 5
```

### Service 配置

为你的应用创建 Service 以暴露服务：

```yaml service.yaml theme={null}
apiVersion: v1
kind: Service
metadata:
  name: your-app-service
  namespace: project-team
spec:
  selector:
    app: your-app-name
  ports:
  - protocol: TCP
    port: 80
    targetPort: 8080
    name: http
  type: ClusterIP
```

<Tip>
  使用 `ClusterIP` 类型适用于内部服务访问。如需外部访问，考虑使用 `NodePort` 或 `LoadBalancer`。
</Tip>

## 2. 配置管理 | Configuration Management

### ConfigMap 示例

使用 ConfigMap 管理应用配置：

```yaml configmap.yaml theme={null}
apiVersion: v1
kind: ConfigMap
metadata:
  name: your-app-config
  namespace: project-team
data:
  app.properties: |
    server.port=8080
    logging.level=INFO
  database.yml: |
    host: db.example.com
    port: 5432
```

在 Deployment 中引用 ConfigMap：

```yaml theme={null}
spec:
  containers:
  - name: your-app
    volumeMounts:
    - name: config
      mountPath: /etc/config
  volumes:
  - name: config
    configMap:
      name: your-app-config
```

### Secret 示例

敏感信息使用 Secret 管理：

```yaml secret.yaml theme={null}
apiVersion: v1
kind: Secret
metadata:
  name: your-app-secret
  namespace: project-team
type: Opaque
stringData:
  username: admin
  password: your-secure-password
```

<Danger>
  Secret 中的敏感信息应使用 base64 编码，或通过 `kubectl create secret` 命令创建，避免在 YAML 文件中明文存储。
</Danger>

在 Deployment 中使用 Secret：

```yaml theme={null}
spec:
  containers:
  - name: your-app
    env:
    - name: DB_USERNAME
      valueFrom:
        secretKeyRef:
          name: your-app-secret
          key: username
    - name: DB_PASSWORD
      valueFrom:
        secretKeyRef:
          name: your-app-secret
          key: password
```

## 3. 资源限制 | Resource Limits

### 资源请求和限制

<CodeGroup>
  ```yaml 小型应用 theme={null}
  resources:
    requests:
      cpu: "100m"
      memory: "128Mi"
    limits:
      cpu: "500m"
      memory: "512Mi"
  ```

  ```yaml 中型应用 theme={null}
  resources:
    requests:
      cpu: "250m"
      memory: "256Mi"
    limits:
      cpu: "1000m"
      memory: "1Gi"
  ```

  ```yaml 大型应用 theme={null}
  resources:
    requests:
      cpu: "500m"
      memory: "512Mi"
    limits:
      cpu: "2000m"
      memory: "2Gi"
  ```
</CodeGroup>

### 资源单位说明

| 单位     | 说明                    | 示例                      |
| ------ | --------------------- | ----------------------- |
| CPU    | 1 = 1 核心，1000m = 1 核心 | `500m` = 0.5 核心         |
| Memory | 使用二进制单位               | `512Mi` = 512 Mebibytes |

<Note>
  必须同时设置 `requests` 和 `limits`。`requests` 用于调度决策，`limits` 用于资源限制。
</Note>

## 4. 健康检查 | Health Checks

### Liveness Probe

检测容器是否正在运行，失败时重启容器：

```yaml theme={null}
livenessProbe:
  httpGet:
    path: /health
    port: 8080
  initialDelaySeconds: 30
  periodSeconds: 10
  timeoutSeconds: 5
  failureThreshold: 3
```

### Readiness Probe

检测容器是否准备好接收流量：

```yaml theme={null}
readinessProbe:
  httpGet:
    path: /ready
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 5
  timeoutSeconds: 3
  successThreshold: 1
  failureThreshold: 3
```

### TCP 探针

对于不支持 HTTP 的服务，使用 TCP 探针：

```yaml theme={null}
livenessProbe:
  tcpSocket:
    port: 3306
  initialDelaySeconds: 30
  periodSeconds: 10
```

## 5. 完整示例 | Complete Example

以下是一个完整的应用部署示例：

<AccordionGroup>
  <Accordion title="Deployment + Service" icon="server">
    完整示例，包含 Deployment 和 Service：

    <CodeGroup>
      ```yaml Deployment theme={null}
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: example-app
        namespace: project-team
      spec:
        replicas: 2
        selector:
          matchLabels:
            app: example-app
        template:
          metadata:
            labels:
              app: example-app
          spec:
            containers:
            - name: app
              image: example/app:latest
              ports:
              - containerPort: 8080
              resources:
                requests:
                  cpu: "200m"
                  memory: "256Mi"
                limits:
                  cpu: "500m"
                  memory: "512Mi"
      ```

      ```yaml Service theme={null}
      apiVersion: v1
      kind: Service
      metadata:
        name: example-app-service
        namespace: project-team
      spec:
        selector:
          app: example-app
        ports:
        - port: 80
          targetPort: 8080
      ```
    </CodeGroup>

    **注意**：在实际部署时，这两个资源可以放在同一个文件中，使用 `---` 分隔。
  </Accordion>
</AccordionGroup>

## ✅ 检查清单 | Checklist

部署前请确认：

* [ ] 命名空间设置为 `project-team`
* [ ] 资源限制已合理配置
* [ ] 健康检查探针已配置
* [ ] 镜像标签明确（避免使用 `latest`）
* [ ] ConfigMap 和 Secret 正确引用
* [ ] 标签选择器匹配正确

<CardGroup cols={2}>
  <Card title="团队协作" icon="users" href="/guides/team-collab/welcome">
    了解开发流程和 Git 工作流
  </Card>

  <Card title="快速开始" icon="rocket" href="/guides/website-overview/quickstart">
    学习如何部署应用
  </Card>
</CardGroup>