# Kubernetes Getting Start

**Repository Path**: jeffwang78/kubernetes-getting-start

## Basic Information

- **Project Name**: Kubernetes Getting Start
- **Description**: Kubernetes getting start - Learning notes
- **Primary Language**: YAML
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2023-01-09
- **Last Updated**: 2023-03-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README


## Kubenertes Getting Start 

## 1. Minikube 

### 1.1 install 

See: https://minikube.sigs.k8s.io/docs/start/

To install the latest minikube stable release on x86-64 Linux using Debian package:

```console
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube_latest_amd64.deb

sudo dpkg -i minikube_latest_amd64.deb
```

WSL2 需要启动 systemd 。 
windows 用户目录下，建立 .wslconfig 
```ini 
[boot]
systemd=true 

```
```
> wsl --shutdown 
# 等待 关闭后，在启动可见 systemctl已生效。

```

K8S 从 1.24开始删除了 dockerslim 。因此，需要替换runtime 。 或者，使用低版本 K8S(当前版本 1.26, 使用1.23即可)。

```console
$ minikube start --nodes=2 --kubernetes-version=v1.23.8

$ docker ps
CONTAINER ID   IMAGE                    COMMAND                  CREATED              STATUS              PORTS                             NAMES
d3113c438e41   kicbase/stable:v0.0.36   "/usr/local/bin/entr…"   54 seconds ago       Up 53 seconds       127.0.0.1:49182->22/tcp, 127.0.0.1:49181->2376/tcp, 127.0.0.1:49180->5000/tcp, 127.0.0.1:49179->8443/tcp, 127.0.0.1:49178->32443/tcp   minikube-m02
f89bc797ed5c   kicbase/stable:v0.0.36   "/usr/local/bin/entr…"   About a minute ago   Up About a minute   127.0.0.1:49177->22/tcp, 127.0.0.1:49176->2376/tcp, 127.0.0.1:49175->5000/tcp, 127.0.0.1:49174->8443/tcp, 127.0.0.1:49173->32443/tcp   minikube
```

可见已启动两个 node。

启动 dashboard ，并在浏览器查看：

```
$ minikube dashboard 

🔌  Enabling dashboard ...
    ▪ Using image docker.io/kubernetesui/dashboard:v2.7.0
    ▪ Using image docker.io/kubernetesui/metrics-scraper:v1.0.8
💡  Some dashboard features require the metrics-server addon. To enable all features please run:

        minikube addons enable metrics-server
🤔  Verifying dashboard health ...
🚀  Launching proxy ...
🤔  Verifying proxy health ...

🎉  Opening http://127.0.0.1:46483/api/v1/namespaces/kubernetes-dashboard/services/http:kubernetes-dashboard:/proxy/ in your default browser...

```
浏览器打开该URL即可看到 dashboard 界面。查看Nodes：
```
$ kubectl get nodes
NAME           STATUS   ROLES                  AGE   VERSION
minikube       Ready    control-plane,master   19m   v1.23.8
minikube-m02   Ready    <none>                 18m   v1.23.8
```

## 2. 基础概念 

### 2.1 Swarm 和 K8S 

Swarm 的概念非常简单，是一种递进式的定义。
* Container: 基础容器。 
    * Service： 同一容器的多个实例集群。
        * Stack: 多个服务的集群。
* Resource
    * Volume
    * Network 
    * Config 

层次关系也很清晰：
```mermaid
graph LR 
  subgraph stack[Stack: demo]
    subgraph s1[service: demo_app1]
        c1(("container: \napp1.1"))
        c12(("container: \napp1.2"))
    end 
    subgraph s2[service: demo_app2]
        c2(("container: \napp2.1"))
        c22(("container: \napp2.2"))
    end
  end 
```
因此，Swarm 的概念是完全从 container 延伸而来，直观而容易理解。

K8S 概念则要复杂一些，这是因为它使用的声明式对象管理。

#### 2.1.1 POD
K8S 最基础的工作单元是**POD**。而POD的各种管理、组织形式, 使用了Deployments, DeamonSet, StatefulSet, Job 等概念。

POD并不等于容器, 而是K8S包装后的容器(或多个容器)。这一点在刚刚看官方文档时会比较困惑，因此，在理解K8S整体之前，可以先简单的认为POD**相当于**Swarm里的容器。

#### 2.1.2 Deployment
Deployments 则是Pod的部署声明。声明一个 Deployment 时，主要包括：
* container：使用的镜像及参数(如环境变量)。
* replicas: 副本数量。

这很容易联想到 Swarm的 Service。但我们看到，K8S也有Service啊。。。这两个Service还有相似之处呢？

Deployment 声明的 Pod，可以实现多个实例的集群运行，但它没有**对外暴露端口**。这相当于 Swarm里的Service没有publish端口，从而无法从集群外访问。

在K8S里想让一个服务对外可见时，需要再声明一个Service，在Service中暴露端口。
因此，Depolyment + Service 大约等于 Swarm 的Service 。

#### 2.1.3 RepilcaSet 和 StatefulSet 

当你理解了这一点时，另两个名词又出现了：ReplicaSet 和 StatefulSet。 字面上看，一个是副本集合，另一个是有状态集合。
StatefulSet 的 Statefull 是指，每个运行副本的Pod的信息和资源都是有状态的，当Pod容器被销毁、被重启时，这些资源会得到保留，并应用在重启后的容器。

举个例子，如果你想运行一个 Nacos集群, 这个集群需要配置 参与 cluster的各个主机名，这时，就可以使用 StatefulSet，StatefulSet中每个容器的DNS名称是固定的,绑定的存储也是固定的。

这样看起来，StatefulSet 比 Swarm 的Service高级一点点。 StatefulSet + Service 相当于 Swarm 的 Service 。

ReplicaSet 呢？ 官方已经讲了，使用Deployment 默认创建的就是 ReplicaSet。RepilcaSet与StatefulSet的区别在于，RS 仅保证实例数量。

#### 2.1.4 DaemonSet

DeamonSet就很简单了，每个节点运行一个实例。这相当于 Swarm Global Service。

#### 2.1.5 Job 和 CronJob 

Job 是作业，与之对应的 CronJob 定时任务。K8S提供调度来完成作业，这在实际系统部署时是很常用的功能。  

#### 2.1.6 ReplicationController

另一个是 ReplicationController ，这是用来控制副本的控制器，比如监视副本数量，重启，收缩等。

使用 Deployment + ReplicaSet 会创建。

#### 2.1.7 容器相关概念小结

综上，大致的对应关系如下：
|**K8S**|**Swarm**|**说明**|
|--|--|--|
|Pod|container| 仅仅是约等于|
|Deployment|Service| 无对外暴露端口 |
|ReplicaSet| | Deployment 代替 |
|StatefulSet|Service| 无对外暴露端口|
|DeameonSet| Global Servive | | 
| Job | 无 | 一次性任务 |
| CronJob| 无 | 定时任务 |
|ReplicationController | | Deployment 代替 |
|Service| Service | 对外暴露端口 |

稍微有点糊涂的是，K8S 的 Service 和 Deployment 是分别声明的，那么，两者之间是什么关系呢？

#### 2.1.8 Service

K8S 的 Service 是一个 **网络** 概念，仅仅用于暴露服务端口。 

举个例子，创建一个 Nginx Deployment ，再创建一个 Apache Deployment。两者都提供Web服务，并且，两者都共享同一个NFS静态网页存储Volume。当外界需要使用WEB服务时，访问任意Nginx或Apache都能得到服务。此时，可以将这两组Depolyment的Pod实例都作为一个服务使用80端口暴露到外部。

#### 2.1.9 Ingress

Docker Swarm 中的 Ignress publish ports 配置，在K8S中被升级为独立的、可声明、可管理的对象Ingress了。

#### 2.1.10 Namespace

Namespace是指 名空间。 名空间用来划分不同的应用，可以按照名空间进行应用部署、资源管理、安全认证。

Kubernetes 的系统组件在 `kube-system` 名空间中。缺省的 应用名空间 是 `default`。

可以使用 `kubectl create <name>`来创建一个名空间。kubectl 操作的是当前名空间，可以通过 `-n <name>` 或 `-namespace <name>` 来操作该名空间的对象。对于get list类命令，可以使用 `-A` 表示全部
名空间。比如：`kubectl get deploy -A` 来获取全部名空间里的 deployments。

可以通过命令设置当前名空间：
```
$ kubectl config set-context --current --namespace=kube-system
Context "minikube" modified.
$ kubectl config view | grep namespace
    namespace: kube-system
```

Swarm没提供名空间的概念，而是通过 Stack 来实现了一组具有共同前缀的服务, 类似于名空间。

### 2.2 Pod 相关
#### 2.2.1 Pod 

K8S POD 是一个用于管理其他应用容器的 "容器"。K8S 使用Pause容器 来运行并管理 POD (及其中的应用容器)。一个POD可以管理一个或多个 容器。

比如，Pod中定义一个容器： nginx,启动该Pod将创建两个container：
* pause: 用于POD管理，创建Pod的网络和存储等共享资源。
* nginx：应用容器。

在节点上使用 docker ps 可以看到这两个container。

虽然可以直接声明一个POD，但通常是通过更高层的Deployment、StatefulSet(这些称之为 Workload)间接声明的。

为考察POD的基本知识，可以从 K8S 系统的 POD开始。

```
$ kubectl get pods -A 
NAMESPACE              NAME                                         READY   STATUS    RESTARTS   AGE
kube-system            coredns-64897985d-r8qzp                      1/1     Running   0          28h
kube-system            etcd-minikube                                1/1     Running   0          28h
kube-system            metrics-server-7d54f9b645-q4rs9              1/1     Running   0          68m
kubernetes-dashboard   kubernetes-dashboard-6f75b5c656-9jc2k        1/1     Running   0          28h
```
上述命令列出了所有的POD。
> -A 指示 全部名空间 --all-namespace=true。 
> 使用 -o wide 可显示 POD运行的 Node 信息。

查看某一个 POD 的信息：

```
$ kubectl describe pod/coredns-64897985d-r8qzp -n kube-system |more
Name:                 coredns-64897985d-r8qzp
Namespace:            kube-system
Node:                 minikube/192.168.49.2
Start Time:           Tue, 03 Jan 2023 11:04:50 +0800
Labels:               k8s-app=kube-dns
                      pod-template-hash=64897985d
Status:               Running
IP:                   10.244.0.2
IPs:
  IP:           10.244.0.2
Controlled By:  ReplicaSet/coredns-64897985d
Containers:
  coredns:
    Container ID:  docker://f033279baf864e1bb892c9b1823b237c56c4788a5b2cc1a05dd4d970618004d2
    Image:         k8s.gcr.io/coredns/coredns:v1.8.6
    Image ID:      docker-pullable://k8s.gcr.io/coredns/coredns@sha256:5b6ec0d6de9baaf3e92d0f66cd96a25b9edbce8716f5f15dcd1a6
16b3abd590e
    Ports:         53/UDP, 53/TCP, 9153/TCP
    Host Ports:    0/UDP, 0/TCP, 0/TCP
    Args:
      -conf
      /etc/coredns/Corefile
    Liveness:     http-get http://:8080/health delay=60s timeout=5s period=10s #success=1 #failure=5
    Readiness:    http-get http://:8181/ready delay=0s timeout=1s period=10s #success=1 #failure=3
    Environment:  <none>
    Mounts:
      /etc/coredns from config-volume (ro)
      /var/run/secrets/kubernetes.io/serviceaccount from kube-api-access-krjlm (ro)
```
以上是部分信息，可见该POD 的名字，名空间，运行节点名称，Labels等信息。
还有一部分是 Containers，其中定义了一个容器：
* image： k8s.gcr.io/coredns/coredns:v1.8.6。
* 容器暴露(expose)三个端口: 53/UDP，53/TCP，9153、TCP。
* Liveness/Readiness: 这个类似于Swarm里的 Health probe 了。
* Enviroment：环境变量
* Mounts: 加载的卷。
* Ports: 相当于 容器 的 expose.

可见 K8S 的 Container 信息 类似于 Docker Compose 形式。

> 这个命令类似于`docker container inspect `, 注意其参数包括 pods 表明对象类型。这与docker 命令的差别是，docker 是按照不同的对象类型组织命令: `docker <type> inspect `，而 K8S 则使用相同的命令来 处理不同的 对象类型，这得益于其 *声明式* 管理方式(`kubectl describe <type>`)。


可以使用底层的 Docker 命令来查看相应的container信息
```
# 如果使用 minikube，需要先进入 minikube 容器： 
# docker exec -it minikube bash 

$ docker ps | grep coredns 
f033279baf86   a4ca41631cc7           "/coredns -conf /etc…"   29 hours ago   Up 29 hours             k8s_coredns_coredns-64897985d-r8qzp_kube-system_5d5fc278-ebbf-4a9a-a2e2-0827b4d2953d_0
8dec9f4942c3   k8s.gcr.io/pause:3.6   "/pause"                 29 hours ago   Up 29 hours             k8s_POD_coredns-64897985d-r8qzp_kube-system_5d5fc278-ebbf-4a9a-a2e2-0827b4d2953d_0
```
从命令输出可见，K8S 创建了一个容器，注意其 ID 正好是 `f033279baf86`，和describe中的`Container ID:  docker://f033279baf86` 一致。
另一个容器 使用 k8s.gcr.io/pause 镜像，这是 该Pod 的管理容器。

#### 2.2.2 创建Pod
```yaml
# samples/ngix-pod.yaml
apiVersion: v1
kind: Pod
metadata:
  name: nginx
spec:
  containers:
  - name: nginx
    image: nginx:alpine
    ports:
    - containerPort: 80
```
该文件声明了一个K8S对象：
* 一个 Pod: 通过`kind: Pod`指定对象类型
* 名为`nginx`: 通过metadata.name: nginx指定
* 包含一个容器：通过spec.container 指定。
    * 容器名称：nginx
    * 镜像名称：nginx:alpine
    * 端口: 暴露端口 80。

在K8S部署该Pod：
```
# 部署 pod
$ kubectl apply -f samples/nginx-pod.yaml
pod/nginx created
# 查看该pod的事件
$ kubectl events  pod/nginx
LAST SEEN   TYPE     REASON      OBJECT      MESSAGE
70s         Normal   Scheduled   Pod/nginx   Successfully assigned default/nginx to minikube-m02
67s         Normal   Pulling     Pod/nginx   Pulling image "nginx:alpine"
37s         Normal   Pulled      Pod/nginx   Successfully pulled image "nginx:alpine" in 30.19601896s
36s         Normal   Created     Pod/nginx   Created container nginx
35s         Normal   Started     Pod/nginx   Started container nginx
# 参看Pod状态

wangjf@DESKTOP-60J9GOH:~/mvnprojects/kube$ kubectl  get pod/nginx -o wide
NAME    READY   STATUS    RESTARTS   AGE     IP           NODE           NOMINATED NODE   READINESS GATES
nginx   1/1     Running   0          5m16s   10.244.1.6   minikube-m02   <none>           <none>
```
在events中可见，通过拉取镜像，创建容器，启动容器几个步骤后，Pod有一个实例在(`minikube-m02`)运行了。
登录到minikube-m02节点上，查看 docker 信息：
```
$ docker ps | grep nginx
6e4b75299e4a   nginx                          "/docker-entrypoint.…"   5 minutes ago   Up 5 minutes             k8s_nginx_nginx_default_12d44aa9-a386-4865-bb23-df89fa4b29ff_0
6495c47b7556   k8s.gcr.io/pause:3.6           "/pause"                 6 minutes ago   Up 6 minutes             k8s_POD_nginx_default_12d44aa9-a386-4865-bb23-df89fa4b29ff_0
```
可见，nginx 和对应的 pause 容器 已经运行了。

#### 2.2.3 Pod Probe 

为了更好的体现Pod服务状态，为其添加Probe。

K8S支持三种Probe探针：
- liveness：服务是否存活。如该探针返回失败，则Pod状态为 Failure，持续一段时间后将被调度重启。
- readiness: 服务是否就绪。如该探针返回失败，则不会向该Pod发送流量(即不对外提供服务)。
- startup：服务是否启动。设置该探针后，liveness/readniess探针无效，这个配置用于启动较慢的服务。

官方文档的这段解释很精准到位：
> 如果你的应用程序对后端服务有严格的依赖性，你可以同时实现存活态和就绪态探针。 当应用程序本身是健康的，存活态探针检测通过后，就绪态探针会额外检查每个所需的后端服务是否可用。 这可以帮助你避免将流量导向只能返回错误信息的 Pod。

K8S Probe 和 Swarm 的 heal check 类似。 

下面在nginx上配置探针，这里可以体现出K8S对容器管理的到位之处。Swarm的Heal check 实现方式是在 目标容器中执行命令。比如：`curl -f localhost:80/ ...`。这就需要在业务容器中配置这些 Utility。K8S 支持三种检查方式：
* exec：即在目标容器执行命令，同 Swarm一致。
* httpGet: 使用http get方式访问容器。
* tcpSocket: 访问端口，如容器监听了该端口，即认为成功。
* gRPC：执行gRPC调用。

这里使用httpGet和tcpSocket两种方式：
```yaml 
---
spec:
  containers:
  - name: nginx
    image: nginx:alpine
    ports:
    - containerPort: 80
    livenessProbe: 
      httpGet: 
        path: /
        port: 80 
      initialDelaySeconds: 2
      periodSeconds: 1 
    readinessProbe:
      tcpSocket:
        port: 80
      initialDelaySeconds: 3
      periodSeconds: 1        
  restartPolicy: OnFailure
```
> 注意 `restartPolicy` 是 spec 的子属性，和containers平级。

删除旧Pod并重新部署pod(这是因为Pod不允许更新这些配置)。
```
$ kubectl delete pod/nginx
pod "nginx" deleted
$ kubectl apply -f samples/nginx-pod.yaml
pod/nginx created
$ kubectl events pod/nginx
LAST SEEN   TYPE     REASON      OBJECT      MESSAGE
46m         Normal   Scheduled   Pod/nginx   Successfully assigned default/nginx to minikube-m02
46m         Normal   Pulling     Pod/nginx   Pulling image "nginx:alpine"
46m         Normal   Pulled      Pod/nginx   Successfully pulled image "nginx:alpine" in 30.19601896s
46m         Normal   Created     Pod/nginx   Created container nginx
46m         Normal   Started     Pod/nginx   Started container nginx
4m51s       Normal   Killing     Pod/nginx   Stopping container nginx
4m31s       Normal   Scheduled   Pod/nginx   Successfully assigned default/nginx to minikube-m02
4m30s       Normal   Pulled      Pod/nginx   Container image "nginx:alpine" already present on machine
4m30s       Normal   Created     Pod/nginx   Created container nginx
4m29s       Normal   Started     Pod/nginx   Started container nginx
```
来看Probe的效果：
```
$ kubectl describe pod nginx | grep ness
    Liveness:       http-get http://:80/ delay=2s timeout=1s period=1s #success=1 #failure=3
    Readiness:      tcp-socket :80 delay=3s timeout=1s period=1s #success=1 #failure=3
```
还可以使用logs查看nginx日志：
```
# --tail=3 的意思是显示最后三行日志
$ kubectl logs pod/nginx --tail=3
10.244.1.1 - - [04/Jan/2023:12:54:50 +0000] "GET / HTTP/1.1" 200 615 "-" "kube-probe/1.23" "-"
10.244.1.1 - - [04/Jan/2023:12:54:51 +0000] "GET / HTTP/1.1" 200 615 "-" "kube-probe/1.23" "-"
10.244.1.1 - - [04/Jan/2023:12:54:52 +0000] "GET / HTTP/1.1" 200 615 "-" "kube-probe/1.23" "-"
```
可见，每秒钟都访问了一次。

HttpGet方式的Health check为应用容器管理提供了很多方便。

#### 2.2.4 发布服务

此时的nginx容器尚不能对外提供服务，需要为其配置一个网络服务来对外暴露服务。

K8S 的Service采用声明式管理，因此，需要单独创建一个 Service，并为该Service指定其"使用的" POD。

```yaml
apiVersion: 1
# samples/ngix-service.yaml
apiVersion: v1
kind: Service
metadata: 
  name: web-service
spec:
  type: NodePort
  selector:
    app/name: nginx 
  ports: 
    - protocol: TCP
      nodePort: 31001
      port: 8080
      targetPort: 80
```
这个service里面仅包括一个selector 和 一个 ports。
ports用来控制集群外暴露端口、集群内服务端口和容器端口。
* nodePort: 集群外端口，在Node上开放的监听端口。K8S对NodePort范围约定为30000-32767。
* port:集群内部端口，仅用于内部服务。配合ClusterIP可访问该服务。
* targetPort: 容器expose的端口号。

部署该服务：
```
$ kubectl apply -f samples/nginx-service.yaml 
service web-service created 
$ kubectl describe service/web-service 
Name:                     web-service
Namespace:                default
Labels:                   <none>
Annotations:              <none>
Selector:                 app/name=nginx
Type:                     NodePort
IP Family Policy:         SingleStack
IP Families:              IPv4
IP:                       10.98.134.132
IPs:                      10.98.134.132
Port:                     <unset>  8080/TCP
TargetPort:               80/TCP
NodePort:                 <unset>  31001/TCP
Endpoints:                <none>
Session Affinity:         None
External Traffic Policy:  Cluster
Events:                   <none>
```

注意其中的`Endpoints <none>`，这表明，该服务尚未接入任何Endpoint，也就是说，这个服务虽然绑定了31001端口，但并不知道要将该流量转发到哪里。

Service如何确定Endpoint呢？答案是使用**selector**来选择Pod。上文有`selector app/name=nginx`, 这就定义了一个selector，app/name是label，因此，web-service 将选中所有 labels中包含`app/name=nginx` 的pod。

目前 `Endpoints <none>` 当然因为没有选中符合条件的 Pod。 因此，需要给Pod添加Labels。
```yaml
metadata:
  name: nginx
  labels:
    app/name: nginx
```
更新Pod：
```
$ kubectl apply -f samples/nginx-pod.yaml
pod/nginx configured
$ kubectl get pod/nginx -o wide
NAME    READY   STATUS    RESTARTS   AGE   IP           NODE           NOMINATED NODE   READINESS GATES
nginx   1/1     Running   0          33m   10.244.1.8   minikube-m02   <none>           <none>
$ kubectl describe service/web-service | grep Endpoint
Endpoints:                10.244.1.8:80
```
Pod nginx的IP 是 10.244.1.8，expose端口为80，而web-service 的 EndPoints 中包含了 10.244.1.8:80，这就说明 service 已经选中了 Pod。 

```
$ curl lcoalhost:31001
<!DOCTYPE html>
...
<p><em>Thank you for using nginx.</em></p>
...
```
如果使用minikube需要先登入容器
```
$ docker exec -it minikube bash
```
或者，先参看minikube容器的ip。
```
$  docker network inspect minikube -f "{{json .Containers }}" | jq
{
  "d3113c438e41c9196b3d3513f7e938d9f1c5d39c0fbca70600ddf08b34cc564a": {
    "Name": "minikube-m02",
    "EndpointID": "08da4a1895268ef52bf48d09af81c23bd786a4c9e859b3fa9290df083bbd5893",
    "MacAddress": "02:42:c0:a8:31:03",
    "IPv4Address": "192.168.49.3/24",
    "IPv6Address": ""
  },
  "f89bc797ed5cb3cef55e14974c38e8d01609deed0c0df68c2368f7bc4ff19f8d": {
    "Name": "minikube",
    "EndpointID": "1b512b7ab74e24ed7ba7834e8ec961955e7a092ecfb0ab9302792ee3efd67dfe",
    "MacAddress": "02:42:c0:a8:31:02",
    "IPv4Address": "192.168.49.2/24",
    "IPv6Address": ""
  }
}
```
可见两个minikube节点容器的IP 分别是 192.168.49.2 和 .3。
```
$ curl 192.168.49.3:31001
<!DOCTYPE html>
...
<p><em>Thank you for using nginx.</em></p>
...
$ curl 192.168.49.2:31001
<!DOCTYPE html>
...
<p><em>Thank you for using nginx.</em></p>
...
```

访问任意一个node的31001端口，都可以访问到web-service并最终访问到pod nginx。这和Docker Swarm的效果是一致的。

#### 2.2.5 Pod多个副本

使用Deployment来创建多副本POD集合(ReplicaSet)。

```yaml
# samples/ngix-deployment.yaml
apiVersion: v1
kind: Deployment
metadata:
  name: nginx-rs
spec:
  replicas: 3
  selector:
    matchLabels:
      app/name: nginx
```
上文定义了一个Deployment，名字为 nginx-rs。其spec中包含：
* replicas：副本数量3。
* selector: 选择器，这里定义的是 label 选择器，选择标签是 app/name=nginx 的 Pod。

那么，这个ReplicaSet中的Pod如何定义呢？使用Pod Template来定义，顾名思义，模板就是指用来创建一系列Pod副本的template。

直接将 `nginx-pod.yaml`中的信息复制到 template 下：
```yaml
  template: 
    metadata:
      name: nginx
      labels:
        app/name: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:alpine
        ports:
        - containerPort: 80
        livenessProbe: 
          httpGet: 
            path: /
            port: 80 
          initialDelaySeconds: 2
          periodSeconds: 30 
    #   restartPolicy: OnFailure
```

使用 kubectl 部署：
```
$ kubectl apply -f samples/nginx-deployment.yaml
deployment.apps/nginx-rs created
$ kubectl get deploy/nginx-rs  -o wide
NAME       READY   UP-TO-DATE   AVAILABLE   AGE   CONTAINERS   IMAGES         SELECTOR
nginx-rs   3/3     3            3           31s   nginx        nginx:alpine   app/name=nginx
$ kubectl describe deploy/nginx-rs
Name:                   nginx-rs
Namespace:              default
CreationTimestamp:      Thu, 05 Jan 2023 11:55:47 +0800
Labels:                 <none>
Annotations:            deployment.kubernetes.io/revision: 1
Selector:               app/name=nginx
Replicas:               3 desired | 3 updated | 3 total | 3 available | 0 unavailable
StrategyType:           RollingUpdate
MinReadySeconds:        0
RollingUpdateStrategy:  25% max unavailable, 25% max surge
Pod Template:
...
Conditions:
...
OldReplicaSets:  <none>
NewReplicaSet:   nginx-rs-7fddddcdb8 (3/3 replicas created)
Events:
  Type    Reason             Age   From                   Message
  ----    ------             ----  ----                   -------
  Normal  ScalingReplicaSet  2m9s  deployment-controller  Scaled up replica set nginx-rs-7fddddcdb8 to 3
```
可见，deployment 实质上是创建了一个 ReplicaSet：
```
$ kubectl get rs/nginx-rs-7fddddcdb8 -o wide
NAME                  DESIRED   CURRENT   READY   AGE     CONTAINERS   IMAGES         SELECTOR
nginx-rs-7fddddcdb8   3         3         3       4m30s   nginx        nginx:alpine   app/name=nginx,pod-template-hash=7fddddcdb8
# 再看对应的 pod(使用label选择 pod)
$ kubectl get pod -l app/name=nginx  -o wide
NAME                        READY   STATUS    RESTARTS   AGE     IP            NODE           NOMINATED NODE   READINESS GATES
nginx                       1/1     Running   0          114m    10.244.1.8    minikube-m02   <none>           <none>
nginx-rs-7fddddcdb8-f2ct7   1/1     Running   0          5m52s   10.244.1.9    minikube-m02   <none>           <none>
nginx-rs-7fddddcdb8-vns9f   1/1     Running   0          5m52s   10.244.1.10   minikube-m02   <none>           <none>
nginx-rs-7fddddcdb8-zlb2t   1/1     Running   0          5m52s   10.244.0.3    minikube       <none>           <none>
```
注意这里也包括了 之前单独创建的 pod。

那么，web-service是否也会匹配这几个pod做为Endpoints呢？
```
$ kubectl describe service/web-service | grep Endpoint
Endpoints:                10.244.0.3:80,10.244.1.10:80,10.244.1.8:80 + 1 more...
```
由此可以体会到 Service 基于 selector 匹配的强大之处。

ReplicaSet支持缩放，包括自动缩放。这里演示如何进行缩放。

为跟踪缩放过程，打开一个窗口，执行：
```
$ kubectl get pod -w -l app/name=nginx
NAME                        READY   STATUS    RESTARTS   AGE
nginx-rs-7fddddcdb8-8prpj   1/1     Running   0          79m
nginx-rs-7fddddcdb8-zlb2t   1/1     Running   0          3h29m
```
该命令会一直跟踪nginx pod 的执行情况。
另一个窗口进行缩放：
```
$ kubectl scale deployment/nginx-rs --replicas=5
deployment.apps/nginx-rs scaled
wangjf@DESKTOP-60J9GOH:~/mvnprojects/kube$ kubectl get deploy/nginx-rs
NAME       READY   UP-TO-DATE   AVAILABLE   AGE
nginx-rs   5/5     5            5           130m
```

此时，第一个窗口信息大概是：
```
$ kubectl get pod -w -l app/name=nginx
NAME                        READY   STATUS    RESTARTS   AGE
nginx-rs-7fddddcdb8-5gxq4   1/1     Running   0          2m46s
nginx-rs-7fddddcdb8-8prpj   1/1     Running   0          82m
nginx-rs-7fddddcdb8-zlb2t   1/1     Running   0          3h32m
nginx-rs-7fddddcdb8-dgb8s   0/1     Pending   0          0s
nginx-rs-7fddddcdb8-vfn2g   0/1     Pending   0          0s
nginx-rs-7fddddcdb8-dgb8s   0/1     ContainerCreating   0          0s
nginx-rs-7fddddcdb8-vfn2g   0/1     ContainerCreating   0          0s
nginx-rs-7fddddcdb8-dgb8s   1/1     Running             0          3s
nginx-rs-7fddddcdb8-vfn2g   1/1     Running             0          3s
```
可见，原有3个副本，scale时，先创建两个Pod，再创建Pod容器，再启动容器。

再将其缩减为 2 个副本：
```
$ kubectl scale deployment/nginx-rs --replicas=2
deployment.apps/nginx-rs scaled
```
第一个窗口输出：
```
nginx-rs-7fddddcdb8-vfn2g   1/1     Terminating         0          2m15s
nginx-rs-7fddddcdb8-5gxq4   1/1     Terminating         0          5m7s
nginx-rs-7fddddcdb8-vfn2g   0/1     Terminating         0          2m16s
nginx-rs-7fddddcdb8-5gxq4   0/1     Terminating         0          5m9s
nginx-rs-7fddddcdb8-dgb8s   0/1     Terminating         0          2m17s
```
删除了三个Pod。

当然也可以通过修改yaml文件，将replicas 改为 5、2 进行缩放。

#### 2.2.6 小结

通过对 Pod、Service、Deployment 的简单介绍。可以对K8S基本概念有初步的认识。
K8S底层基于容器技术实现(containerd 而非局限于docker)，因此，通过与Docker Swarm的简要对比可以帮助简化概念、加强理解。


### 2.3 卷 Volume 

#### 2.3.1 对比

K8S 支持卷作为 容器存储。当然，Docker也支持，但与K8S相比，Docker的Volume过于简陋了。

K8S 对 Docker Volume 的最大改进是支持动态分配(PVC)：即当Pod创建时进行按需分配，并可依据Pod要求保持、复用其数据(StatefulSet)。

#### 2.3.2 K8S 卷类型

K8S官方文档对卷的分类比较模糊，这里按照用途进行了归并：
* 临时卷：随POD创建、消亡的临时存储，如：emptyDir，可用于映射内存临时存储。
* 投射卷：Projection，Kube内部使用它用于挂载密钥，host、resolver，config等数据文件。projection 的特点是可以将多个卷/文件 `投射`到一个 卷 目录下。 
* 持久卷：这是应用经常使用的卷。持久卷可以使用Provisioner 供应者 进行动态制备，大部分Provisioner里会作为服务组件部署在K8S集群中，供应用使用。

#### 2.3.2 K8S 卷驱动

卷驱动driver是 Docker 的概念，K8S里对应的是 Provisioner 供应者。 

其他的存储比如：NFS、Ceph以及各大云供应商提供存储，一般是网络存储了，则比较适合 StatefulSet 应用。

此类存储有两种方式引入，一种是使用K8S自带的(in-tree)驱动，另一种是使用CSI 驱动。从趋势上看，K8S会逐步放弃in-tree驱动，一方面减少K8S社区压力，另一方面第三方厂家提供的CSI驱动从性能、兼容性、更新频度几方面都是优于in-tree的，再有，CSI是推行中的规范。

各大云厂商均会提供动态制备的卷驱动。

#### 2.3.3 Local 卷

Local卷使用节点的本地目录作为卷，因此这种卷很简单，它的问题也很明显：不会在节点之间迁移，因此，可以用作 无状态应用的卷。

> Loacl 卷 相当于 Docker 中的 olume。

> 还有一个 HostPath卷，相当于 Docker 中的 bind Vloume，但不建议在集群中使用。

K8S使用StorageClass 术语来描述存储卷的分类，分类里会引用provisioner。官方推荐使用storageClass来区分不同类型的存储，这里使用官方的例子，首先建立一个storage class。
```yaml
# samples/local-storage-class.yaml 
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: local-storage
provisioner: kubernetes.io/no-provisioner
volumeBindingMode: WaitForFirstConsumer
```
上文声明了一个 local-storage。no-provisioner 表示不需要使用供应商，这也意味着不能用于动态创建卷。

```
$ kubectl apply -f samples/local-storage-class.yaml
storageclass.storage.k8s.io/local-storage created
$ kubectl get sc
NAME                 PROVISIONER                    RECLAIMPOLICY   VOLUMEBINDINGMODE      ALLOWVOLUMEEXPANSION   AGE
local-storage        kubernetes.io/no-provisioner   Delete          WaitForFirstConsumer   false                  95s
standard (default)   k8s.io/minikube-hostpath       Delete          Immediate              false                  2d10h
```
这里的 kubectl get sc ， sc是 storageclsss 的简写形式。

local-storage 创建后，就可以创建一个Local持久卷：

```yaml
apiVersion: v1
kind: PersistentVolume
metadata:
  name: local-pv
  labels:
    storage/type: local
spec:
  storageClassName: local-storage
  capacity:
    storage: 100Mi
  accessModes:
    - ReadWriteOnce
  local:
    path: "/var/data/local"
  nodeAffinity:
    required:
      nodeSelectorTerms:
      - matchExpressions:
        - key: kubernetes.io/hostname
          operator: In
          values:
          - minikube
```
Local 卷依赖节点本地文件系统，因此，在定义时需要限定某一个节点上，同样，使用Local卷的Pod，也会被分配到该节点上。

当然，也可以在每个节点都建立相同目录。

在K8S中部署：
```
$ kubectl apply -f samples/local-pv.yaml
persistentvolume/local-pv-volume created
wangjf@DESKTOP-60J9GOH:~/mvnprojects/kube$ kubectl get pv
NAME              CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS      CLAIM   STORAGECLASS    REASON   AGE
local-pv          100Mi      RWO            Retain           Available           local-storage            5s
```
`get pv` 中的 pv 是 persistent volume 的缩写。
注意，StorageClass定义中使用了 `WaitForFirstConsumer`，因此，此时pv状态并不是 BOUND，当第一个用户请求卷时，才会被绑定。

卷声明后，再声明一组持久存储申请对象(PVC，Persistent Volume Claim)。PVC描述了Pod在持久卷里申请存储空间的方法。

```
# samples/local-pvc.yaml 
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: local-pvc
spec:
  storageClassName: local-storage
  volumeName: local-pv
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Mi
```
注意，这里通过 `volumeName: local-pv` 指定了从local-pv中申请。如果不指定，K8S会依据 StorageClass和容量需求来分配一个卷(如果存在多个卷的话)。
```
$ kubectl apply -f samples/local-pvc.yaml
persistentvolumeclaim/local-pvc created
$ kubectl get pvc
NAME        STATUS   VOLUME     CAPACITY   ACCESS MODES   STORAGECLASS    AGE
local-pvc   Bound    local-pv   100Mi      RWO            local-storage   3m34s

$ kubectl get pv
NAME       CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS   CLAIM               STORAGECLASS    REASON   AGE
local-pv   100Mi      RWO            Retain           Bound    default/local-pvc   local-storage            3m45s
```
PVC建立后，与local-pv卷绑定起来了。


再通过PVC将卷挂载到Pod上。修改nginx deployment 即可(本文使用了新的文件nginx-ls-deployment.yaml)：
```
    spec:
      volumes:      
      - name: local-path
        persistentVolumeClaim:
          claimName: local-pvc
      containers:
        ...
        volumeMounts:
        - mountPath: "/usr/share/nginx/html/local"
          name: local-path
```
在 pod template中添加了PVC，并在容器中挂载。挂载路径为 nginx html 目录下的 local。

部署该Deployment：
```
$ kubectl apply -f samples/nginx-ls-deployment.yaml
deployment.apps/nginx-rs created
$ kubectl get pods -l app/name=nginx -o wide
NAME                        READY   STATUS    RESTARTS   AGE   IP           NODE       NOMINATED NODE   READINESS GATES
nginx-rs-6d49fbb644-62nsr   1/1     Running   0          17s   10.244.0.6   minikube   <none>           <none>
nginx-rs-6d49fbb644-pqn4r   1/1     Running   0          17s   10.244.0.7   minikube   <none>           <none>
nginx-rs-6d49fbb644-sbc5b   1/1     Running   0          17s   10.244.0.8   minikube   <none>           <none>
``` 

注意，这时已经将全部副本都调度到 minikube节点了(因为 Local 卷 使用了这个节点)。

可以登入minikube 检查卷挂载情况：
```
$ docker exec -it minikube bash
root@minikube:/# ls /var/data/local
root@minikube:/# echo "Hello minikube!" > /var/data/local/index.html 
root@minikube:/# curl localhost:31001/local/
Hello minikube!
```
再查看 pvc的使用情况：
```
$ kubectl describe pvc local-pvc
Name:          local-pvc
Namespace:     default
StorageClass:  local-storage
Status:        Bound
Volume:        local-pv
Labels:        <none>
Annotations:   pv.kubernetes.io/bind-completed: yes
Finalizers:    [kubernetes.io/pvc-protection]
Capacity:      100Mi
Access Modes:  RWO
VolumeMode:    Filesystem
Used By:       nginx-rs-6d49fbb644-62nsr
               nginx-rs-6d49fbb644-pqn4r
               nginx-rs-6d49fbb644-sbc5b
```
可见三个Pod在使用。

> 可以使用 subPathExpression来为 Pod 分配单独的 目录。

可以注意到，每个Pod都挂载同一个目录，这种行为和Docker 的 Volume 很接近了。


#### 2.3.3 使用 NFS 卷


NFS 存储是较容易搭建环境的，因此，这里以 NFS 为例。

首先建立NFS存储环境。

```
$ sudo apt install nfs-kernel-server -y
# 查看服务状态
$ systemctl status nfs-kernel-server
● nfs-server.service - NFS server and services
   Loaded: loaded (/lib/systemd/system/nfs-server.service; enabled; vendor preset: enabled)
   Active: active (exited) since Thu 2023-01-05 20:21:12 CST; 1min 23s ago
 Main PID: 1970339 (code=exited, status=0/SUCCESS)
    Tasks: 0 (limit: 3488)
   CGroup: /system.slice/nfs-server.service

Jan 05 20:21:11 DESKTOP-60J9GOH systemd[1]: Starting NFS server and services...
Jan 05 20:21:12 DESKTOP-60J9GOH systemd[1]: Started NFS server and services.
#
```
建立目录/var/data/nfs 目录作为NFS共享目录。并在/etc/exports下添加定义：
```
$ sudo mkdir -p /var/data/nfs
$ sudo chmod 777 /var/data/nfs 

$ sudo vi /etc/exports
# 添加目录
/var/data/nfs *(rw,sync,no_subtree_check)

#重新加载导出配置
$ sudo exportfs -ar
$ showmount -e
Export list for DESKTOP-60J9GOH:
/var/data/nfs *
```    
至此配置完成，已经建立了NFS的共享目录。

同样的，使用 storageClass 来标志 NFS 卷。
这里将全部nfs卷定义放在一个文件`samples/nfs-volume.yaml`里来定义。
```yaml
apiVersion: v1
kind: PersistentVolume
metadata:
  name: nfs-pv
  labels:
    storage/type: nfs
spec:
  storageClassName: nfs-static-storage
  capacity:
    storage: 200Mi
  accessModes:
    - ReadWriteOnce
  nfs:
    path: "/var/data/nfs"
    server: 172.21.57.232
    readOnly: false 
```
这里配置了 nfs 的共享路径和server 地址。

将nfs配置在 K8S中部署：
```
$ kubectl apply -f samples/nfs-volume.yaml
storageclass.storage.k8s.io/nfs-static-storage created
persistentvolume/nfs-pv created
persistentvolumeclaim/nfs-pvc created
wangjf@DESKTOP-60J9GOH:~/mvnprojects/kube$ kubectl get sc
NAME                 PROVISIONER                    RECLAIMPOLICY   VOLUMEBINDINGMODE      ALLOWVOLUMEEXPANSION   AGE
local-storage        kubernetes.io/no-provisioner   Delete          WaitForFirstConsumer   false                  15h
nfs-static-storage   kubernetes.io/no-provisioner   Delete          WaitForFirstConsumer   false                  10s
standard (default)   k8s.io/minikube-hostpath       Delete          Immediate              false                  3d1h
wangjf@DESKTOP-60J9GOH:~/mvnprojects/kube$ kubectl get pv
NAME       CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS      CLAIM               STORAGECLASS         REASON   AGE
local-pv   100Mi      RWO            Retain           Bound       default/local-pvc   local-storage                 97m
nfs-pv     200Mi      RWO            Retain           Available                       nfs-static-storage            13s
wangjf@DESKTOP-60J9GOH:~/mvnprojects/kube$ kubectl get pvc
NAME        STATUS    VOLUME     CAPACITY   ACCESS MODES   STORAGECLASS         AGE
local-pvc   Bound     local-pv   100Mi      RWO            local-storage        97m
nfs-pvc     Pending                                        nfs-static-storage   22s
```

在Deployment 中添加 nfs Mount 信息：
```yaml
    volumes:      
      - name: nfs-path
        persistentVolumeClaim:
          claimName: nfs-pvc
    ...
    containers:
    ...
      volumeMounts:
        - mountPath: "/usr/share/nginx/html/nfs"
          name: nfs-path
```
添加了nfs卷。重新部署：
```
$ kubectl apply -f samples/nginx-nfs-deployment.yaml
deployment.apps/nginx-rs configured
# 再看pvc状态：
$ kubectl get pvc
NAME        STATUS   VOLUME     CAPACITY   ACCESS MODES   STORAGECLASS         AGE
local-pvc   Bound    local-pv   100Mi      RWO            local-storage        170m
nfs-pvc     Bound    nfs-pv     200Mi      RWO            nfs-static-storage   72m
```
如使用 `kubectl get pods -w `则会发现原Pod都被删除并启动了新的Pod。

同样，在nfs的共享目录下添加一个文件：
```
$ echo "Hello NFS Volume!" > /var/data/nfs/index.html
$ curl 192.168.49.3:31001/nfs/
Hello NFS Volume!
```
可见已经将nfs 卷 mount到 pod了。
再看nfs卷挂载情况：
```
$ docker exec minikube nfsstat -m 
/var/lib/kubelet/pods/ada94928-f965-44f0-aa76-42e3702bd8d4/volumes/kubernetes.io~nfs/nfs-pv from 172.21.57.232:/var/data/nfs
 Flags: rw,relatime,vers=4.1,rsize=524288,wsize=524288,namlen=255,hard,proto=tcp,timeo=600,retrans=2,sec=sys,clientaddr=192.168.49.2,local_lock=none,addr=172.21.57.232

/var/lib/kubelet/pods/f951a38b-0093-4598-a75d-2bba197145c9/volumes/kubernetes.io~nfs/nfs-pv from 172.21.57.232:/var/data/nfs
 Flags: rw,relatime,vers=4.1,rsize=524288,wsize=524288,namlen=255,hard,proto=tcp,timeo=600,retrans=2,sec=sys,clientaddr=192.168.49.2,local_lock=none,addr=172.21.57.232

/var/lib/kubelet/pods/f29eeaf5-6d92-4089-9bf1-9f5ef8d2cc83/volumes/kubernetes.io~nfs/nfs-pv from 172.21.57.232:/var/data/nfs
 Flags: rw,relatime,vers=4.1,rsize=524288,wsize=524288,namlen=255,hard,proto=tcp,timeo=600,retrans=2,sec=sys,clientaddr=192.168.49.2,local_lock=none,addr=172.21.57.232
```
三个 Pod 分别挂载了nfs-pv。

关于持久卷的动态制备，将结合StatefulSet来介绍。

### 2.4 Ingress

K8S内部使用DNS为每一个对象(Pod、Service等)提供域名服务，因此，集群内部可以使用稳定的域名来访问内部服务。

K8S对外的入口可以使用Service(上文有简要介绍)，也可以使用Ingress暴露端口。

#### 2.4.1 Ingress及Ingress Controller

Ingress 是入口的意思。在Swarm中，Ingress是用于集群内服务发现的overlay网络服务，而K8S的Ingress侧重于外部对集群访问的入口控制。

K8S通过Service对象暴露端口，可以供外部访问，但其端口是随机的，即使人工指定，也限定在30000范围端口。同时，多个服务需要对外暴露多个端口，这对外部负载均衡配置是有点繁琐的，在微服务架构下，这一点更为明显。

我们知道，微服务可以使用网关服务(Gateway)来代理内部微服务，将不同的请求 rewrite 到 不同的 服务上。

K8S的Ingress提供了类似的能力。典型的 Ingress 模式如下图：

```mermaid 
graph LR
    c([Web Client])
    subgraph k8s[K8S Cluster]
        ig[Ingress]
        svc[Service]
        p1[Pod]
        p2[Pod]
        svc2[Service]
        p3[Pod]
        p4[Pod]
    end

    c --Ingress Loadbalancer--> ig -- Route Rules --> svc
    svc --> p1 
    svc --> p2 
    ig -- Route Rules --> svc2
    svc2 --> p3 
    svc2 --> p4    

```

先来看一个官方ingress示例声明：
```
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-wildcard-host
spec:
  rules:
  - host: "foo.bar.com"
    http:
      paths:
      - pathType: Prefix
        path: "/bar"
        backend:
          service:
            name: service1
            port:
              number: 80
  - host: "*.foo.com"
    http:
      paths:
      - pathType: Prefix
        path: "/foo"
        backend:
          service:
            name: service2
            port:
              number: 80
```

rules中定义了两个路由规则：
- host=foo.bar.com path=/bar：转发至backend 服务 service1。
- host=*.foo.com path=/foo：转发到service2 。

这个路由规则和Spring Gateway很相似，host匹配header中的 'Host', pathType Prefix 匹配 请求URL的前缀。一旦匹配，就将请求转发至相应的服务。

当然也可以不匹配 host, 仅使用path做匹配，此时不写host属性即可。

注意这里的  backend.service.port，是指Service的内部端口(因为一个Service可以配置多个端口的)。

Ingress仅支持 HTTP/HTTPS，Ingress 默认使用80和443标准端口号，这个端口号无法在ingress声明中配置，只能依赖于Ingress Controller。

#### 2.4.2 Ingress Controller

Ingress控制器是完成ingress处理的服务，可以使用多种IngressControler，典型的控制器是 Nginx Ingress Controller(Nginx强大的无法回避)。

不同的Ingress 控制器，通过 Ingress Class 声明和引用。IngressClass 类似于 StorageClass，也仅仅是一个分类标识名称。

```
$ kubectl get ingressClass
NAME    CONTROLLER             PARAMETERS   AGE
nginx   k8s.io/ingress-nginx   <none>       14h
```
可以查看到 ingress class 有 nginx。

*注意*：
> Nginx ingress 在 minikube 需要通过 addons启动。
```
$ minikube addons enable ingress
```

查看 nginx的配置：
```
$ kubectl describe ingressclass nginx
Name:         nginx
Labels:       app.kubernetes.io/component=controller
              app.kubernetes.io/instance=ingress-nginx
              app.kubernetes.io/name=ingress-nginx
Annotations:  ingressclass.kubernetes.io/is-default-class: true
Controller:   k8s.io/ingress-nginx
Events:       <none>
```
注意这里设置了is-default-class: true的注解，该注解表示nginx是默认的Ingress Class。

```
$ kubectl get deploy -A -o wide | grep ingress-nginx
ingress-nginx          ingress-nginx-controller    1/1     1            1           15h     controller                  k8s.gcr.io/ingress-nginx/controller:v1.2.1                                                                              app.kubernetes.io/component=controller,app.kubernetes.io/instance=ingress-nginx,app.kubernetes.io/name=ingress-nginx

$ kubectl get deploy -n ingress-nginx
NAME                       READY   UP-TO-DATE   AVAILABLE   AGE
ingress-nginx-controller   1/1     1            1           15h

$ kubectl describe deploy ingress-nginx-controller -n ingress-nginx
Name:                   ingress-nginx-controller
Namespace:              ingress-nginx
...
Replicas:               1 desired | 1 updated | 1 total | 1 available | 0 unavailable
StrategyType:           RollingUpdate
Pod Template:
...
  Service Account:  ingress-nginx
  Containers:
   controller:
    Image:       k8s.gcr.io/ingress-nginx/controller:v1.2.1
    Ports:       80/TCP, 443/TCP, 8443/TCP
    Host Ports:  80/TCP, 443/TCP, 0/TCP
    Args:
      /nginx-ingress-controller
   ...
```

可见ingress nginx Controller开放的端口(Host Ports)是 80, 443 端口。
nginx controller 使用 Nginx 进行反向代理，这样就比较容易理解 ingress 的实现方式了，无非是将 路由规则rules 内容转换成 Nginx 的 相应upstream配置。

#### 2.4.3 Ingress 示例

使用 nginx ingressClass 来创建一个ingress:

```yaml
# samples/example-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
spec:
  ingressClassName: nginx
  rules:
  - host: "s1.example.net"
    http:
      paths:
      - pathType: Prefix
        path: "/"
        backend:
          service:
            name: web-service
            port:
              number: 80
  - host: "*.example.net"
    http:
      paths:
      - pathType: Prefix
        path: "/nfs"
        backend:
          service:
            name: web-service
            port:
              number: 80
```
这里定义了两个路由规则，一个是`s1.example.net/` 转发至 web-service。另一个是 `*.example.net/nfs/` 转发至 web-service。

部署ingress:
```
$ kubectl apply -f samples/example-ingress.yaml
ingress.networking.k8s.io/example-ingress created
$ kubectl get ingress
NAME              CLASS   HOSTS                          ADDRESS        PORTS   AGE
example-ingress   nginx   s1.example.net,*.example.net   192.168.49.2   80      8m40s
```

域名可以在本机 /etc/hosts上配置，IP指向节点IP或ClusterIP。
```
192.168.49.2    s1.example.net
192.168.49.2    s2.example.net
```

使用curl 进行测试：
```
$ curl s1.example.net
...
<title>Welcome to nginx!</title>
...
$ curl s1.example.net/local/
Hello minikube!

$ curl s1.example.net/nfs/
Hello NFS Volume!

$ curl s2.example.net/nfs/
Hello NFS Volume!

$ curl s2.example.net/local/
<center><h1>404 Not Found</h1></center>

$ curl 192.168.49.2/
<center><h1>404 Not Found</h1></center>
```

这样可以验证转发的效果了。

但要注意，ingress-nginx 仅做转发，没有做像 Spring gateway 那样的 URL rewite。Ingress的目的是提供多服务集成入口。所以，通常使用 host 虚拟主机方式转发即可。

### 2.5 集群内 DNS 

K8S 内部使用DNS 服务，并为所有的Pod 提供 DNS解析。

Pod 和 Service 都具有DNS名称，其中 Service 的DNS名称是稳定的，而POD的名称并不稳定。

K8S会为每个POD 生成一个 resolv.conf 来指定其DNS服务。如：
```
$ kubectl get pods -o wide
NAME                        READY   STATUS    RESTARTS   AGE   IP            NODE       NOMINATED NODE   READINESS GATES
nginx-rs-5697d79d5d-5r8l7   1/1     Running   0          24h   10.244.0.10   minikube   <none>           <none>
nginx-rs-5697d79d5d-g4xq8   1/1     Running   0          24h   10.244.0.11   minikube   <none>           <none>
nginx-rs-5697d79d5d-tn9sw   1/1     Running   0          24h   10.244.0.9    minikube   <none>           <none>
# 选择一个 pod 访问其 resolv.conf 文件：

$ kubectl exec nginx-rs-5697d79d5d-5r8l7 -- cat /etc/resolv.conf
nameserver 10.96.0.10
search default.svc.cluster.local svc.cluster.local cluster.local
options ndots:5
```

dns 搜索路径为 三个层次，
- cluster.local: 这是集群的域名。
- svc.cluster.local: 这是 Service 的使用的域名。
- default: 这是Pod所在名空间名字。

Pod 的域名是 `IP地址.namespace.pod.集群域名`。本例中 Pod Ip是 10.244.0.10，将其转换为 - 分割方式：
```
10-244-0-10.default.pod.cluster.local
10-244-0-11.default.pod.cluster.local
10-244-0-9.default.pod.cluster.local

```
使用 nslookup 来访问其域名：
```
$ kubectl exec nginx-rs-5697d79d5d-5r8l7 -- nslookup 10-244-0-9.default.pod.cluster.local
Server:         10.96.0.10
Address:        10.96.0.10:53

Name:   10-244-0-9.default.pod.cluster.local
Address: 10.244.0.9
```

如果Pod绑定了Service，则可以从另一个域名来访问：
```
# IP地址.服务名.namespace.svc.集群域名
$ kubectl exec nginx-rs-5697d79d5d-5r8l7 -- nslookup \
10-244-0-9.web-service.default.svc.cluster.l
ocal
Server:         10.96.0.10
Address:        10.96.0.10:53

Name:   10-244-0-9.web-service.default.svc.cluster.local
Address: 10.244.0.9

# 查询所有Pod 
$ kubectl exec nginx-rs-5697d79d5d-5r8l7 -- nslookup *.web-service.default.svc.cluster.local
Server:         10.96.0.10
Address:        10.96.0.10:53


Name:   *.web-service.default.svc.cluster.local
Address: 10.244.0.10
Name:   *.web-service.default.svc.cluster.local
Address: 10.244.0.9
Name:   *.web-service.default.svc.cluster.local
Address: 10.244.0.11
```

而服务的 DNS 就是 `服务名.namespace.svc.集群域名` :
```
$ kubectl exec nginx-rs-5697d79d5d-5r8l7 -- nslookup web-service.default.svc.cluster.local
Server:         10.96.0.10
Address:        10.96.0.10:53

Name:   web-service.default.svc.cluster.local
Address: 10.98.134.132
 
# 简写 域名 匹配 search list 也是可以的:
$ kubectl exec nginx-rs-5697d79d5d-5r8l7 -- nslookup -d web-service
Server:         10.96.0.10
Address:        10.96.0.10:53

Query #0 completed in 6ms:
authoritative answer:
Name:   web-service.default.svc.cluster.local
Address: 10.98.134.132
```

因此，如果在Pod中需要访问Service，同一个名空间的情况下，只需要使用service name，不同名空间的，添加 serviceName.namespace 就可以了。

> 与Swarm相比，Swarm允许参数化定制 Container 的 hostname来访问服务，K8S则不允许，要求使用Service来暴露服务，如需要给Pod分配稳定的DNS名字，需要使用StatefulSet。


### 2.6 ConfigMap 

Docker 提供 Config 可以进行 配置类数据的管理，K8S 使用 ConfigMap 来提供此类功能。

ConfigMap 实质上是把文件内容保存起来，并可以在Pod中使用。常见的用途是用于应用的配置文件。

#### 2.6.1 声明 ConfigMap

ConfigMap同样使用YAML文件声明：
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: nginx-files
data:
  sample-env.txt: |
     TYPE=nginx
     STR=normalText
  # 类文件键
  config.html: |
    <html><body><h2>
      Hello ConfigMap!! 
    </h2></body></html>
```
同样使用 apply 来创建ConfigMap：
```
$ kubectl  apply -f samples/config/nginx-files-config.yaml
configmap/nginx-files created
$ kubectl get configmap
NAME               DATA   AGE
kube-root-ca.crt   1      4d4h
nginx-files        2      16s

$ kubectl describe  configmap nginx-files
Name:         nginx-files
Namespace:    default
Labels:       <none>
Annotations:  <none>

Data
====
config.html:
----
<html><body><h2>
  Hello ConfigMap!!
</h2></body></html>

sample-env.txt:
----
TYPE=nginx
STR=normalText


BinaryData
====

Events:  <none>
```
当然也可以直接使用文件来创建ConfigMap：
```
kubectl create configmap nginx-files2 \
    --from-file=samples/config/sample-env.txt \
    --from-file=samples/config/config.html
configmap/nginx-files2 created

$ kubectl describe  configmap nginx-files2
Name:         nginx-files2
Namespace:    default
Labels:       <none>
Annotations:  <none>

Data
====
sample-env.txt:
----
TYPE=nginx
STR=normalText
config.html:
----
<html><body><h2>
    Hello ConfigMap!!
</h2></body></html>
```
这两种方式的内容是相同。


#### 2.6.2 Pod 挂载 ConfigMap 文件

Pod可以将 ConfigMap 做为文件挂载，使用方法和卷类似。

```yaml
# samples/ngix-config-deployment.yaml
    spec:
      volumes:
      - name: config-html 
        configMap:
          name: nginx-files
          items:
          - key: config.html
            path: index.html
    ...
      containers:
      ...
        volumeMounts:
        - mountPath: "/usr/share/nginx/html/config"
          name: config-html  
```
上文使用 `nginx-files` ConfigMap 中的 `key: config.html` 内容作为文件`path: index.html`。

该文件mount到 "/usr/share/nginx/html/config"。

部署deployment：
```
$ kubectl apply -f samples/nginx-config-deployment.yaml
deployment.apps/nginx-rs configured

$ curl s1.example.net/config/
<html><body><h2>
  Hello ConfigMap!!
</h2></body></html>
```
可见ConfigMap已经挂载好了。

#### 2.6.3 Pod 引用 ConfigMap 变量

Pod内的Container可以使用环境变量，在PodTemplate中可以直接定义变量，也可以引用ConfigMap。

环境变量可以单独写文件中，形如：

```yaml
TYPE=nginx
STR=normalText
```
这里可以使用 `#` 作为行注释。

使用命令参数 `--from-env-file` 创建 configMap:
```
$ kubectl create cm nginx-envs --from-env-file=samples/config/sample-env.txt
configmap/nginx-envs created

$ kubectl describe cm nginx-envs
Name:         nginx-envs
Namespace:    default
Labels:       <none>
Annotations:  <none>

Data
====
STR:
----
normalText
TYPE:
----
nginx
```

这样就可以在Pod container 中引用变量：
``` yaml 
      containers:
      - name: nginx
        image: nginx:alpine
        ports:
        - containerPort: 80
        env:
        # 1
        - name: CM_SOME_ENV
          value: SOME_VALUE
        - name: CM_SAMPLE_ENV_TXT
        # 2
          valueFrom:
            configMapKeyRef: 
              name: nginx-envs
              key:  STR
        - name: CM_VAR 
        # 3
          value: "CM_INCLUDE_$(CM_SOME_ENV)_VALUE" 
        - name: CM_UNDEFINE_ENV
          valueFrom:
            configMapKeyRef:
              name: nginx-envs
              key:  undefined
        # 4
              optional: true 
        # 5
        envFrom:
        # 6 
        - prefix: CM_
          configMapRef: 
            name: nginx-envs
```
上文表现了环境变量定义的各种方法：
1. 使用 **name/value** 直接定义。
2. 使用 **CongfigMapKeyRef** 来引用环境变量值。
3. 使用 **$(VAR_NAME)** 引用其他变量值。
4. 使用 **optional = true** 来定义可选变量，避免因configMap或 configMap Key 不存在时 出现错误。
5. 使用 **envFrom** 将整个ConfigMap 中的 Key/Value 全部作为环境变量。
6. 使用 **prefix: CM_** 在ConfigMap的 key 前附加前缀'CM_'。

> 注意：修改环境变量会导致 所有 pod 重新创建。

```
$ kubectl apply -f samples/nginx-config-deployment.yaml
deployment.apps/nginx-rs configured

$ kubectl get pods
NAME                       READY   STATUS    RESTARTS   AGE
nginx-rs-d6774464b-6xbwc   1/1     Running   0          5m3s
nginx-rs-d6774464b-fr5zb   1/1     Running   0          5m6s
nginx-rs-d6774464b-gl2tp   1/1     Running   0          5m10s

# 选择一个 参看环境变量
$ kubectl describe pod nginx-rs-7f7fd8c66c-9599c | grep CM_
      nginx-envs  ConfigMap with prefix 'CM_'  Optional: false
      CM_SOME_ENV:        SOME_VALUE
      CM_SAMPLE_ENV_TXT:  <set to the key 'STR' of config map 'nginx-envs'>  Optional: false
      CM_VAR:             CM_INCLUDE_$(CM_SOME_ENV)_VALUE
      CM_UNDEFINE_ENV:    <set to the key 'undefined' of config map 'nginx-envs'>  Optional: true

# 查看实际取值：
$ kubectl exec nginx-rs-7f7fd8c66c-9599c -- sh -c set  | grep CM_
CM_SAMPLE_ENV_TXT='normalText'
CM_SOME_ENV='SOME_VALUE'
CM_STR='normalText'
CM_TYPE='nginx'
CM_VAR='CM_INCLUDE_SOME_VALUE_VALUE'
```

### 2.7 Secret


### 2.8 StatefulSet 

StatefulSet 是和 Stateless相对的 ReplicaSet，Stateful 是指每个副本都需要保持其状态，这里的状态包括：
* 唯一：hostname 和 dns 域名是稳定、唯一的。命名使用 spec.metadata.name + 序号 (0, 1,2, ...)。
* 粘性：使用的卷会按照副本序号保持，并在副本更新、重建时，根据副本序号重新绑定之前的卷。
* 有序：副本的启动顺序严格按照 副本序号的顺序，0 启动后才会依次启动 1, 2, 3...。收缩、删除、重启时与之相反。

这几点都是依赖于 副本 序号的，可以说，StatefulSet 是一种管理机制，和Deployment 不同，Deployment 的命名使用hash，DNS 域名 使用 IP，存储随机分配，更没有启动顺序(参考 RollingUpdate)，

#### 2.8.1 简易例子

既然是K8S的管理机制的差异，那么在 StatefulSet 和 Deployment 的声明上基本没啥差别，可以直接从deployment修改：
```yaml
# from samples/ngix-nfs-deployment.yaml
# to samples/nginx-statefulset.yml
apiVersion: apps/v1
# 修改 Kind 
# kind: Deployment
kind: StatefulSet
metadata:
#   name: nginx-rs
# 修改名字
  name: nginx-sts
  labels:
    app/name: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app/name: nginx
# 必须添加一个服务
  serviceName: web-service
...
```

修改了 Kind 和metadata.name ，添加了 spec.serviceName。 StatefulSet必须绑定一个服务，这个服务会为其分配 DNS。

使用 kubectl apply 部署：
```
$ kubectl apply -f samples/nginx-statefulset.yaml
statefulset.apps/nginx-sts created

$ kubectl get po 
NAME                        READY   STATUS    RESTARTS   AGE
nginx-rs-7f7fd8c66c-9599c   1/1     Running   0          18h
nginx-rs-7f7fd8c66c-d2kxz   1/1     Running   0          18h
nginx-rs-7f7fd8c66c-fqk4r   1/1     Running   0          18h
nginx-sts-0                 1/1     Running   0          12m
nginx-sts-1                 1/1     Running   0          11m
nginx-sts-2                 1/1     Running   0          11m
```
注意看 nginx-sts 的pod，其名称是 metadata.name-<序号>。 AGE列 的时间可以看出，副本 0 是最先创建的，之后才依次创建 1, 2。

> 序号是从0 开始的，可以使用 spec.ordinals 修改。如：`ordinals: 1`。

再来看DNS：
```
$ kubectl exec -it nginx-sts-0 -- sh

/ # cat /etc/hosts
# Kubernetes-managed hosts file.
127.0.0.1       localhost
::1     localhost ip6-localhost ip6-loopback
fe00::0 ip6-localnet
fe00::0 ip6-mcastprefix
fe00::1 ip6-allnodes
fe00::2 ip6-allrouters
10.244.1.22     nginx-sts-0.web-service.default.svc.cluster.local       nginx-sts-0

/ # nslookup nginx-sts-1.web-service.default.svc.cluster.local
Server:         10.96.0.10
Address:        10.96.0.10:53

Name:   nginx-sts-1.web-service.default.svc.cluster.local
Address: 10.244.1.23

/ # ping nginx-sts-2.web-service -c 2
PING nginx-sts-2.web-service (10.244.1.24): 56 data bytes
64 bytes from 10.244.1.24: seq=0 ttl=63 time=0.264 ms
64 bytes from 10.244.1.24: seq=1 ttl=63 time=0.073 ms

--- nginx-sts-2.web-service ping statistics ---
2 packets transmitted, 2 packets received, 0% packet loss
round-trip min/avg/max = 0.073/0.168/0.264 ms
```

Stateful 的DNS和其他Pod没有差别，其区别在于，pod name 和 hostname是稳定的。
启动一个窗口执行 `kubectl get pods -w ` 用于观察 pod的状态变化。 另一个窗口执行：
```
$ kubectl delete po nginx-sts-0
pod "nginx-sts-0" deleted

$ 
$ kubectl get pod  -w
NAME                        READY   STATUS    RESTARTS   AGE
nginx-sts-0                 1/1     Running   0          22m
nginx-sts-1                 1/1     Running   0          22m
nginx-sts-2                 1/1     Running   0          22m

# delete 
nginx-sts-0                 1/1     Terminating   0          23m
nginx-sts-0                 0/1     Terminating   0          23m
nginx-sts-0                 0/1     Pending       0          0s
nginx-sts-0                 0/1     ContainerCreating   0          0s
nginx-sts-0                 1/1     Running             0          2s

# scale 0
nginx-sts-2                 1/1     Terminating         0          29m
nginx-sts-2                 0/1     Terminating         0          29m
nginx-sts-1                 1/1     Terminating         0          5m46s
nginx-sts-1                 0/1     Terminating         0          5m47s
nginx-sts-0                 1/1     Terminating         0          6m9s
nginx-sts-0                 0/1     Terminating         0          6m10s

# scale 3
nginx-sts-0                 0/1     Pending             0          0s
nginx-sts-0                 0/1     ContainerCreating   0          0s
nginx-sts-0                 1/1     Running             0          2s
nginx-sts-1                 0/1     Pending             0          0s
nginx-sts-1                 0/1     ContainerCreating   0          1s
nginx-sts-1                 1/1     Running             0          3s
nginx-sts-2                 0/1     Pending             0          0s
nginx-sts-2                 0/1     ContainerCreating   0          0s
nginx-sts-2                 1/1     Running             0          2s
```

可见，删除后自动创建的 Pod 名称不变，收缩时是从 最高序号 开始，扩展时 是从最低序号开始。这就是 StatefulSet 的唯一、粘性、有序的特点。

#### 2.8.2 VolumeClaimTemplate 存储

StatefulSet 存储 可以采用 VolumeClaimTemplate 进行模板化申请。这里申请的存储应以storageClass为限定。这涉及到provisioner动态制备。

VolumeClaimTemplate 就是一个 persistentVolumeClaim 的模板，声明内容类似。

在上一个例子中将 container 中定义 的 persistentVolumeClaim 移到  spec.VolumeClaimTemplate中：

```yaml
# samples/nginx-nfs-statefulset.yml
... 
  template:
    metadata:
      name: nginx
      labels:
        app/name: nginx
    spec:
    # 不使用预定义的 pvc，改用 pvc template 
      # volumes:      
      # - name: nfs-path
      #   persistentVolumeClaim:
      #     claimName: nfs-pvc
      containers:
      ...
        volumeMounts:
        - mountPath: "/usr/share/nginx/html/nfs"
          name: nfs-path
  volumeClaimTemplates:
#   copy from nfs-pvc
  - metadata:
#   名称和 volumeMounts中保持一致
      name: nfs-path
    spec:
      accessModes: [ "ReadWriteOnce" ]
      storageClassName: nfs-static-storage
      resources:
        requests:
          storage: 100Mi
```
将声明保存为 `samples/nginx-nfs-statefulset.yml` 并部署：
```
# 首先删除之前的 statefulset。
$ kubectl delete sts/nginx-sts
statefulset.apps "nginx-sts" deleted

$ kubectl apply -f samples/nginx-nfs-statefulset.yaml
statefulset.apps/nginx-sts created
```

> 注意：删除原 stateful 而不是 apply 修改，是因为新增的 *volumeClaimTemplate* 不允许 修改，只能重建。

> 也可以使用 `kubectl replace ...` 。

这时查看 pod 状态：
```
$ kubectl get pod  -w
NAME                        READY   STATUS    RESTARTS   AGE
nginx-sts-0                 0/1     Pending   0          2m46s
```
可见 nginx-sts-0 一直处在 **Pending** 状态，检查Pending原因：
```
$ kubectl events sts/nginx-sts

5m6s                  Normal    SuccessfulCreate       StatefulSet/nginx-sts                        create Claim nfs-path-nginx-sts-0 Pod nginx-sts-0 in StatefulSet nginx-sts success
5m6s                  Normal    SuccessfulCreate       StatefulSet/nginx-sts                        create Pod nginx-sts-0 in StatefulSet nginx-sts successful

0s (x21 over 5m)      Normal    WaitForPodScheduled    PersistentVolumeClaim/nfs-path-nginx-sts-0   waiting for pod nginx-sts-0 to be scheduled

0s (x6 over 5m20s)    Warning   FailedScheduling       Pod/nginx-sts-0                              0/2 nodes are available: 2 node(s) didn't find available persistent volumes to bind.

```
可见，问题是：

**0/2 nodes are available: 2 node(s) didn't find available persistent volumes to bind.**

也就是说，在两个节点上都找不到可用的 PV。
```
$ kubectl get pv
NAME       CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS   CLAIM               STORAGECLASS         REASON   AGE
local-pv   100Mi      RWO            Retain           Bound    default/local-pvc   local-storage                 2d2h
nfs-pv     200Mi      RWO            Retain           Bound    default/nfs-pvc     nfs-static-storage            2d
```
当前定义的两个 PV都已经分配了。因此，需要再进一步定义几个NFS的PV。

> 为了简单起见，这里不再创建新的 NFS export 目录，仅用于演示效果。

将nfs-volume中的 PV 定义复制一份，并修改`metadata.name`，如：
```yaml
# samples/nfs-pvlist.yaml 
---
apiVersion: v1
kind: PersistentVolume
metadata:
  name: nfs-pv1
  labels:
    storage/type: nfs
spec:
  storageClassName: nfs-static-storage
  capacity:
    storage: 200Mi
  accessModes:
    - ReadWriteOnce
  nfs:
    path: "/var/data/nfs"
    server: 172.21.57.232
    readOnly: false 
```
这里把名字改成了 `pv1` 路径还是指向 `/var/data/nfs`。如果建立了其他的NFS目录，这里可以修改成对应的目录。

部署 该 PV： 
```
$ kubectl apply -f samples/nfs-pvlist.yaml
$ kubectl get pv -w
NAME       CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS   CLAIM                          STORAGECLASS         REASON   AGE
local-pv   100Mi      RWO            Retain           Bound    default/local-pvc              local-storage
2d2h
nfs-pv     200Mi      RWO            Retain           Bound    default/nfs-pvc                nfs-static-storage
2d1h
nfs-pv1    200Mi      RWO            Retain           Available                    nfs-static-storage
1m

nfs-pv1    200Mi      RWO            Retain           Bound    default/nfs-path-nginx-sts-0   nfs-static-storage
1m

```
当建立了新的 PV (storageClass=nfs-static-storage)之后，就被 nginx statefulSet 获取并绑定了。再看 `get pod -w` 窗口：
```
nginx-sts-0                 0/1     Pending             0          0s
nginx-sts-0                 0/1     Pending             0          1s
nginx-sts-0                 0/1     ContainerCreating   0          1s

nginx-sts-0                 1/1     Running             0          3s
nginx-sts-1                 0/1     Pending             0          0s
```
可见，nginx-sts-0 已经建立完成，因此，立即启动了 nginx-sts-1，没有空闲的PV，因此，sts-1 进入 Pending状态。

只要依次再创建两个PV就可以满足 nginx-sts-1 和 nginx-sts-2 的使用了，这里采用一个创建小技巧：
```
$ kubectl create -f samples/nfs-pvlist.yaml --edit -o yaml      
```
```yaml
# Please edit the object below. Lines beginning with a '#' will be ignored,
# and an empty file will abort the edit. If an error occurs while saving this file will be
# reopened with the relevant failures.
#
apiVersion: v1
kind: PersistentVolume
metadata:
  labels:
    storage/type: nfs
  name: nfs-pv1
spec:
  accessModes:
  - ReadWriteOnce
  capacity:
    storage: 200Mi
  nfs:
    path: /var/data/nfs
    readOnly: false
    server: 172.21.57.232
  storageClassName: nfs-static-storage
~
# 这里会出现一个 VI 窗口，在VI 中将 nfs-pv1 修改 nfs-pv2，保存退出。

```
这会建立一个 nfs-pv2。按此方法在建立 pv3，可见 PV 状态：
```
$ kubectl get pv
NAME       CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS   CLAIM                          STORAGECLASS         REASON   AGE
nfs-pv     200Mi      RWO            Retain           Bound    default/nfs-pvc                nfs-static-storage
2d1h
nfs-pv1    200Mi      RWO            Retain           Bound    default/nfs-path-nginx-sts-0   nfs-static-storage
27m
nfs-pv2    200Mi      RWO            Retain           Bound    default/nfs-path-nginx-sts-1   nfs-static-storage
27m
nfs-pv3    200Mi      RWO            Retain           Bound    default/nfs-path-nginx-sts-2   nfs-static-storage
33s
```
删除一个Pod，观察变化：
```
$ kubectl delete pod/nginx-sts-1
pod "nginx-sts-1" deleted
$ kubectl get pvc 
$ kubectl get pvc -w
NAME                   STATUS   VOLUME     CAPACITY   ACCESS MODES   STORAGECLASS         AGE
nfs-path-nginx-sts-0   Bound    nfs-pv1    200Mi      RWO            nfs-static-storage   31m
nfs-path-nginx-sts-1   Bound    nfs-pv2    200Mi      RWO            nfs-static-storage   31m
nfs-path-nginx-sts-2   Bound    nfs-pv3    200Mi      RWO            nfs-static-storage   30m
```
注意，PVC并没有被删除，当 pod sts-1自动启动后，仍将使用 nfs-path-nginx-sts-1, 从而 挂载 nfs-pv2。

> 如果 PV 和 VolumeClaimTemplate 中的 accessMode设定为 ReadWriteMany，这就允许多一个PV被多个PVC领用，此时将领用同一个PV。

> 注意VolumeClaimTemplate 定义了 `storageClass`，因此，只会申请同类的PV。

> 申请PV时会检查满足 request的 容量的 PV。  

> VolumeClaimTemplate 不允许更改，因此，如果需要修改的话，必须删除 StatefulSet重新建立。由于默认的 `persistentVolumeClaimRetentionPolicy` 策略为`Retain`，即删除时会保留PVC，因此，即使删除了StatefulSet，相应PVC/PV都保持绑定状态，需要手动删除PVC。

本例使用了静态分配PV，可以看出使用VolumeClaimTemplate之后，每一个Pod都会创建一个新的 PVC 对象，并挂载单独的卷。 这样就可以实现每个Pod存储的独立、唯一、保持。

如果生产环境使用的StorageClass支持动态制备，则应使用动态制备的存储申请方案。后文将介绍 NFS 动态制备。

### 2.9 K8S API

在许多对象的声明中，都可以看到：
```yaml
apiVersion: apps/v1
---
apiVersion: v1
---
apiVersion: storage.k8s.io/v1
```
为什么每个`apiVersion`的取值是不同的，有些还带有目录？ 

这里的 apiVersion 是指 k8s API 的版本信息，附带了不同API的分类名称。这样讲尚不直观，来看下文的详细说明。


#### 2.9.1 kube-apiserver

所有Kubernetes的操作(如：kubectl create\apply\set\get ...)，都是对通过访问 kube-apiserver 来完成的，kube-apiserver是一组 REST 服务，完成对K8S各类对象的管理。

先来看看kube-apiserver如何启动的：
```
$ kubectl get pod -n kube-system | grep apiserver
kube-apiserver-minikube            1/1     Running   0              5d5h

# minikube 中的 apiserver pod 。

$ kubectl get pod -n kube-system kube-apiserver-minikube -o yaml
```
```yaml 
#  ...
spec:
  containers:
  - command:
    - kube-apiserver
    - --advertise-address=192.168.49.2
    - --allow-privileged=true
    - --authorization-mode=Node,RBAC
    - --client-ca-file=/var/lib/minikube/certs/ca.crt
    - --enable-admission-plugins=NamespaceLifecycle,LimitRanger,ServiceAccount,DefaultStorageClass,DefaultTolerationSeconds,NodeRestriction,MutatingAdmissionWebhook,ValidatingAdmissionWebhook,ResourceQuota
    - --enable-bootstrap-token-auth=true
    - --etcd-servers=https://127.0.0.1:2379
    - --secure-port=8443
    image: k8s.gcr.io/kube-apiserver:v1.23.8
    # ...
```
重点看 `--advertise-address=192.168.49.2` 和 `--secure-port=8443`, 这就是API Server的地址。

使用kubectl 正确配置后，也可使用 kubectl cluster-info 来显示API-server 地址：

```
$ kubectl cluster-info
Kubernetes control plane is running at https://127.0.0.1:49174
CoreDNS is running at https://127.0.0.1:49174/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy  
```
其中 control plane 地址，就是 api-server。

这两个地址不同是因为 minikube 运行在 docker 容器中(docker on docker ...)虚拟的节点上。

kubectl 就是使用这个这个地址来访问API Server的。


#### 2.9.2 API 分组

K8S的 API 很多，按照其功能、管理的对象类型进行了分组。在学习之前，可以先使用proxy访问API Server。 
```
$ kubectl proxy 
Starting to serve on 127.0.0.1:8001

# 另开窗口

$ curl http://localhost:8001/
```
```json
{
  "paths": [
    "/.well-known/openid-configuration",
    "/api",
    "/api/v1",
    "/apis",
    "/apis/admissionregistration.k8s.io/v1",
    "/apis/apiextensions.k8s.io",
    "/apis/apiextensions.k8s.io/v1",
    "/apis/apiregistration.k8s.io/v1",
    "/apis/apps/v1",
    // ...
    "/apis/rbac.authorization.k8s.io",
    "/apis/rbac.authorization.k8s.io/v1",
    "/apis/scheduling.k8s.io/v1",
    "/apis/storage.k8s.io",
    "/apis/storage.k8s.io/v1",
    "/apis/storage.k8s.io/v1beta1",
    "/healthz",
    "/healthz/autoregister-completion",
    "/healthz/etcd",
    "/healthz/log",
    "/healthz/ping",
    // ...
    ]
}
```
K8S很友好，会返回一系列的 URL 路径，这些路径有三种，
* /api/v1: 这是核心API, v1 是版本号。
* /apis/apps/v1: apis开头的是api分组，后面是 分组名称(GROUP)，在后面v1是版本号(VERSION)。
* /healthz/ livnessz 等：这是容器健康等API。
这里重点讨论 api和apis。

> K8S会保留API的多个版本，如`/apis/storage.k8s.io/v1` 和 `/apis/storage.k8s.io/v1beta1`。

可以看到，YAML文件中的`apiVersion` 值得就是 GROUP/VERSION。
核心API 的GROUP不需要写。因此，是 `apiVerison: v1`。

另一个命令可以看到全部的 api 分组信息：
```
$ kubectl api-versions
admissionregistration.k8s.io/v1
apiextensions.k8s.io/v1
apiregistration.k8s.io/v1
apps/v1
...
rbac.authorization.k8s.io/v1
scheduling.k8s.io/v1
storage.k8s.io/v1
storage.k8s.io/v1beta1
v1
```

#### 2.9.3 API 和 资源(RESOURCE)

REST API 核心理念，是使用URI表示 **资源**，使用 HTTP METHOD (get/post/delete。。。) 表示动作。

K8S API管理的资源分为很多种类型(RESOURCE_TYPE)，每个资源的名字在同类中是唯一的。URL 规则中使用了RESOURCE_TYPE和RESOURCE_NAME 来标志 一个具体的资源。不指定NAME时，意味着获取该类型的全部资源。

先来试一下：
```
$ curl http://localhost:8001/api/v1/namespaces/default
```
```json
{
  "kind": "Namespace",
  "apiVersion": "v1",
  "metadata": {
    "name": "default",
    "uid": "d8c2057e-67d7-45d0-8e41-388d646efda0",
    "resourceVersion": "207",
    "creationTimestamp": "2023-01-03T03:04:06Z",
    "labels": {
      "kubernetes.io/metadata.name": "default"
    },
 //   ...
    "status": {
    "phase": "Active"
  }
}
```
这个 URL 中，各部分含义：
- /api : 核心API
- /v1 : 版本号 VERSION
- /namespace：RESOURCE_TYPE 资源类型是 名空间。
- /default : RESOURCE_NAME 名空间名称是 default。

CURL 默认使用 GET ， GET 在 REST里的语义就是 **查看** 。因此，K8S 返回了 名空间 `default`的 状态信息，相当于：`kubectl get namespace default -o json`

分组 API 也遵循相同的 规则， 如：
```
$ curl http://localhost:8001/apis/networking.k8s.io/v1/ingressclasses/nginx/
```
```json
{
  "kind": "IngressClass",
  "apiVersion": "networking.k8s.io/v1",
  "metadata": {
    "name": "nginx",
    "uid": "e44fbc9d-e745-44d7-92fc-b5d8af9f9880",
    "resourceVersion": "232990",
    "generation": 1,
    "creationTimestamp": "2023-01-06T11:29:13Z",
    "labels": {
      "app.kubernetes.io/component": "controller",
      "app.kubernetes.io/instance": "ingress-nginx",
      "app.kubernetes.io/name": "ingress-nginx"
    }
  },
//  ...
 "spec": {
    "controller": "k8s.io/ingress-nginx"
  }
}
```
这个 URL 中，各部分含义：
- /apis : API分组
- /networking.k8s.io： 分组名称 GROUP 
- /v1 : 版本号 VERSION
- /ingressclasses：RESOURCE_TYPE 资源类型是 ingressClass。
- /nginx : RESOURCE_NAME ingressClasses 是 nginx。

K8S 的 资源 有些是从属于 Namespace 的，有些从属于 集群的(即不属于任何 namespace)。上面两个例子都是集群资源。当需要访问名空间资源时，需要在 RESOURCE_TYPE前加上 `namespaces/所属名空间名(NAMESPACE)`。形如`/apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCE_TYPE/RESOURCE_NAME/`如：
```
$ curl http://localhost:8001/apis/apps/v1/namespaces/default/deployments/nginx-rs
```

这个 URL 中，各部分含义：
* /apis : API分组
* /apps ： 分组名称 GROUP 
- /v1 : 版本号 VERSION
- /deployments：RESOURCE_TYPE 资源类型是 deployment。
- namespaces: 表示选择某一namespaces
- default: NAMESPACE, namespace 的名称。 
- /nginx-rs : RESOURCE_NAME 是 nginx-rs。

#### 2.9.4 API 的 操作类型(verbs)

每个资源的API操作都使用REST风格定义。下文摘自官方资料：
> 几乎所有对象资源类型都支持标准 HTTP 动词 - GET、POST、PUT、PATCH 和 DELETE。 Kubernetes 也使用自己的动词，这些动词通常写成小写，以区别于 HTTP 动词。

> Kubernetes 使用术语 list 来描述返回资源集合， 以区别于通常称为 get 的单个资源检索。 如果你发送带有 ?watch 查询参数的 HTTP GET 请求， Kubernetes 将其称为 watch 而不是 get（有关详细信息，请参阅快速检测更改）。

> 对于 PUT 请求，Kubernetes 在内部根据现有对象的状态将它们分类为 create 或 update。 update 不同于 patch；patch 的 HTTP 动词是 PATCH。

> ubernetes API 允许客户端对对象或集合发出初始请求，然后跟踪自该初始请求以来的更改：watch。 客户端可以发送 list 或者 get 请求，然后发出后续 watch 请求。

#### 2.9.5 查看资源清单
API 管理哪些资源，资源是否属于名空间，可以使用该命令：
```
$ kubectl api-resources -o wide
```
| **NAME** | **SHORTNAMES** | **APIVERSION** | **NAMESPACED** | **KIND** |    **VERBS** | **CATEGORIES** |
| --- | --- | --- | --- |--- |--- |--- |
|configmaps |cm | v1 | true | ConfigMap | create,delete, deletecollection, get,list,patch, update,watch | |
|endpoints| ep | v1 | true | Endpoints | create,delete, deletecollection, get,list,patch, update,watch | |
| events | ev | v1| true | Event | create,delete, deletecollection, get,list,patch ,update,watch | |
| namespaces | ns | v1 | false | Namespace | create,delete, get,list,patch, update,watch | |
| nodes | no| v1| false | Node |  create,delete, deletecollection, get,list,patch, update,watch | |
| persistentvolumeclaims |  pvc | v1 | true | PersistentVolumeClaim | create,delete, deletecollection, get,list,patch, update,watch | |
| persistentvolumes | pv | v1 | false | PersistentVolume | create,delete, deletecollection, get,list,patch, update,watch | |
| pods | po | v1 | true | Pod | create,delete, deletecollection, get,list,patch, update,watch |  all |
|   |

这里只是截取了一些。命令输出中 各列 含义如下：
* NAME: API 中的 RESOURCE_TYPE。同时也是 `kubectl get <资源类型>` 中的 资源类型。
* SHORTNAME: `kubectl get <资源类型>` 中的 资源类型 简写。
* APIVERSION: API 的版本号。
* NAMESPACED: 资源是否从属于 namespace(true/false)。
* KIND: 在 yaml 声明的 Kind 字段值。
* VERBS: 资源支持的 操作。


### 2.10 资源管理方式

K8S 提供的 声明式 对象管理方式，将对象(资源)都以 YAML/JSON 格式进行声明，这大大简化了资源的管理，使资源的可读性很强。

#### 2.10.1 Kubectl apply

通常的管理方法是 使用 `kubectl apply -f <文件名>`来进行管理。`apply` 意味着 `应用`，根据文件中的资源Kind/name等确定是否该`create` 还是 `update`。

kubectl apply 还支持使用目录，将同一个目录下的yaml文件全部检查一遍，并apply其中的对象。
kubectl apply 可以使用 -R 参数来指定递归执行其子目录下的yaml文件。

这样就大大方便了一组应用的声明、部署(尤其是，K8S对资源的关联是松耦合的，当资源申请不到时，会挂起申请者，当资源具备时，再进行Create，因此，YAML文件的执行顺序并不是很要紧，特例是 Service 和 Pod之间，需要先创建 Service，这时POD 中的 SERVICE_ 环境变量才会生效)。

而在 kubectl get 命令中，也支持使用 `-f -R` 参数，获取文件中定义的对象。比如：
```
$ kubectl get  -f samples/nfs-volume.yaml
NAME                                             PROVISIONER                    RECLAIMPOLICY   VOLUMEBINDINGMODE      ALLOWVOLUMEEXPANSION   AGE
storageclass.storage.k8s.io/nfs-static-storage   kubernetes.io/no-provisioner   Delete          WaitForFirstConsumer   false                  2d22h

NAME                      CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS   CLAIM             STORAGECLASS         REASON   AGE
persistentvolume/nfs-pv   200Mi      RWO            Retain           Bound    default/nfs-pvc   nfs-static-storage
  2d22h

NAME                            STATUS   VOLUME   CAPACITY   ACCESS MODES   STORAGECLASS         AGE
persistentvolumeclaim/nfs-pvc   Bound    nfs-pv   200Mi      RWO            nfs-static-storage   2d22h
```

#### 2.10.2 API Server 

如前所述，kubectl 所有操作均通过 API Server 完成的，因此，可以直接使用 API Server。

如果Pod中应用需要检索、管理 K8S对象时，可以使用API server。此时建议使用 K8S 提供的 各语言环境 API库，如 Java 库。

此时需要进行鉴权。参见下文的 **安全** 。

#### 2.10.3 kubectl create

某些简单的 资源 可以直接采用 kubectl create命令来创建，如namespace:

```
$ kubectl create ns <namespace name>
```

复杂的资源就不建议这样了。

因此类似的还有 kubectl set / patch /label 等用于修改 资源 声明的命令。

#### 2.10.4 修改 

修改的主要方法自然是修改 YAML 文件，但也有简便的方法可以快速编辑。如：
```
$ kubectl edit <resource type> <resource name> 
```

这命令会打开一个 编辑窗口，编辑结束后，Kubectl 将 apply 修改后的内容。

#### 2.10.5 获取YAML 

使用 `kubectl get <resoure type> <resource name> -o yaml ` 可以取得 资源的 YAML 定义。

可以将该信息保存在文件中。

#### 2.10.6 历史及版本

K8S 应用 常用的部署形式是 Delployment、StatefulSet、DaemonSet(Job 是一次性任务，不需要历史管理)。
这些 对象 由于版本、配置变化等，会多次编辑、发布，K8S 记录了这些历史版本信息。

```
$ kubectl rollout history deploy nginx-rs
deployment.apps/nginx-rs
REVISION  CHANGE-CAUSE
3         <none>
4         <none>
5         <none>
6         <none>
7         <none>
8         <none>
9         <none>
10        <none>
```
可见该 deployment 已经 有这么多版本了(注意，scale 也会记录一个版本)。

K8S 允许查看任意版本的对象内容：
```
kubectl rollout history deploy nginx-rs --revision=5 -o yaml 
```
CHANGE-CAUSE 通过 annotation 注解 `kubernetes.io/change-cause` 来定义：
```yaml
# samples/ngix-nfs-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-rs
  annotations: 
    kubernetes.io/change-cause: add change-cause example  
```
Apply 该文件后，再查询 可见：
```
$ kubectl apply -f samples/nginx-nfs-deployment.yaml
deployment.apps/nginx-rs configured
$ kubectl rollout history deploy nginx-rs
deployment.apps/nginx-rs
REVISION  CHANGE-CAUSE
4         <none>
5         <none>
6         <none>
7         <none>
8         <none>
9         <none>
10        <none>
11        add change-cause example
```

#### 2.10.7 diff 比较

当编辑了资源声明 YAML 之后，可以使用该命令检查 文件定义与 K8S 当前版本资源的差异，例如，把 `sample/nfs-volume.yaml` 中的 storage: 200Mi 改成 300：

```
$ kubectl diff -f samples/nfs-volume.yaml
diff -u -N /tmp/LIVE-2986072598/v1.PersistentVolume..nfs-pv /tmp/MERGED-3148704781/v1.PersistentVolume..nfs-pv
--- /tmp/LIVE-2986072598/v1.PersistentVolume..nfs-pv    2023-01-09 11:23:36.125010080 +0800
+++ /tmp/MERGED-3148704781/v1.PersistentVolume..nfs-pv  2023-01-09 11:23:36.125010080 +0800
@@ -17,7 +17,7 @@
   accessModes:
   - ReadWriteOnce
   capacity:
-    storage: 200Mi
+    storage: 300Mi
   claimRef:
     apiVersion: v1
     kind: PersistentVolumeClaim
```

这是一个方便实用的功能。


## 3. 安全

K8S 的安全管理分为两部分：
* 集群管理的安全：控制从外部访问集群API-Server的安全，使用用户认证机制。
* 集群内部的安全：控制集群内应用(POD)访问AP-Server的安全。使用ServiceAccount即RBAC或ABAC。

### 3.1 用户认证

K8S 的用户认证方式采用签名证书。这是因为 K8S 的核心是 api-server，而访问api-server 的方式就是通过HTTPS，使用客户端证书进行身份认证是很合理的方法。

K8S 的用户是外部管理的，即，K8S并不直接管理用户，也不会考虑用户的来源，用户信息的安全，这是由K8S系统外的安全措施来保证的。

使用客户端证书进行身份认证的方式是：
1. 客户端生成密钥对。
2. 使用K8S 的 CA证书进行签名（K8S会生成一个CA证书，也可以从外部导入一个CA证书）。
3. 客户端需要保护好证书安全。
4. 客户端访问api-server时携带该证书(典型的应用是使用`kubectl`)。
5. api-server 使用鉴权模块进行身份认证(K8S还支持其他鉴权机制如token，本文仅介绍证书机制)。
6. 身份认证通过后，api-server 通过 RBAC或ABAC进行鉴权，检查该客户端是否具备访问该资源的权限。
7. 根据鉴权结果执行操作(允许或拒绝)。

#### 3.1.2 Kubectl 查看客户端认证信息

本文仅介绍kubectl的认证机制，首先看一下 kubectl 如何使用客户端证书。

先用命令查看一下 kubectl 当前配置信息：
```
$ kubectl config view --minify
```
```yaml
apiVersion: v1
clusters:
- cluster:
    certificate-authority: ~/.minikube/ca.crt
      name: cluster_info
    server: https://127.0.0.1:49174
  name: minikube
contexts:
- context:
    cluster: minikube
    namespace: default
    user: minikube
  name: minikube
current-context: minikube
kind: Config
preferences: {}
users:
- name: minikube
  user:
    client-certificate: ~/.minikube/profiles/minikube/client.crt
    client-key: ~/.minikube/profiles/minikube/client.key
```
可见config中定义了:
* 一个 cluster minikube，它的CA根证书保存在 `~/.minikube/ca.crt`。
* 当前上下文context： 上下文默认的 cluster/user/namespace等。
* 用户信息：名为`minikube`的user，以及其使用的客户端证书及私钥。

重点关注user 的 client-certificate和client-key。

使用 openssl 查看 CA 证书内容：
```
$ openssl x509 -in ./ca.crt -noout -text
Certificate:
    Data:
# 证书颁发者Issuer和Subject都是 minikubeCA。 
        Issuer: CN = minikubeCA
        Subject: CN = minikubeCA
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
        X509v3 extensions:
            X509v3 Basic Constraints: critical
# 表示这是一个CA证书
                CA:TRUE
                ...
```

再看 client-certificate 客户端证书：
```
$ openssl x509 -in ./profiles/minikube/client.crt -noout -text
Certificate:
    Data:
    # 颁发者是 minikubeCA
        Issuer: CN = minikubeCA
    # 主体 Subject 
        Subject: O = system:masters, CN = minikube-user
        X509v3 extensions:
            X509v3 Basic Constraints: critical
                CA:FALSE
```
client.cert是由 minikubeCA签发的。来分析一下Subject(主体) 内容，这很重要：
* O: organization 组织，在这里代表 K8S 的 **用户组** 
* CN: 通用名Common Name，在这里代表 K8S 的**用户名**

system:master用户组是特殊用户组，通常只能建立普通用户。

这样，当 kubectl 访问时，会携带CA 签发的证书，这时 api-server 才会认证该证书。


> 注意，私钥的安全是由用户自己来保证的。


#### 3.1.2 用户组Group和用户User

证书中的O 和 CN 代表用户组和用户名。

K8S内部定义的组以 `system:`开头。当然可以自定义组名称，但应避免使用 `system:` 前缀。

已知的K8S内部组包括：
* system:master, 这是K8S超级用户组，该组的用户不进行鉴权，即拥有全部资源的访问权限。
* system:authenticated, 已认证用户组，当用户通过身份认证后，即在该组中。默认可以访问自身资源。
* system:unauthenticated，未认证用户组。
* system:serviceaccounts, K8S 服务账户(ServiceAccount)组。在下文RBAC会讲到。

还有其他的组是K8S 组件创建的组，不在讨论范围内。

用户可以自己定义一个组，比如：某个应用管理组，这种组通常会绑定到某个具体名空间的管理权限。

本例中将使用 app 组，用户名 为 appadmin，绑定的namespace 是 app。

#### 3.1.3 生成用户证书并签名

生成用户证书的过程包括两部分：
1. 使用任意工具(本例使用openssl)生成RSA 密钥。
2. 创建一个 CSR 证书签名请求。
2. K8S CA使用CSR生成证书并对证书进行签名。

首先用openssl生成密钥：
```
$ cd ~/
# 初始化随机数
$ openssl rand -writerand .rnd
$ cd ~/.kube
$ mkdir -p profiles/appadmin 
$ cd profiles/appadmin 
# 生成 2048 bits RSA key 
$ openssl genrsa -out appadmin.key 2048
Generating RSA private key, 2048 bit long modulus (2 primes)
...............................+++++
..............+++++
e is 65537 (0x010001)
```

有了公钥和私钥之后，就需要创建CSR(Certficate Signing Request)。
本例使用openssl使用命令行创建CSR, 创建CSR时需要指定:
* key： 即appadmin.key
* 证书Subject域信息: 即 `O=app` 和 `CN=appadmin`。

> CSR包含Subject域数据、公钥，并对其使用 私钥 签名。

使用openssl建立 CSR: 
```
$ openssl req \
  -new \
  -key appadmin.key \
  -out appadmin.csr \
  -subj "/O=app/CN=appadmin"

$ openssl req -subject -in appadmin.csr -noout
subject=O = app, CN = appadmin
```

本例中持有CA私钥(minikube CA的私钥和证书放在一个目录下，名为ca.key)，因此可以直接使用`openssl x509 -req` 命令来生成CA签名证书。

K8S 也提供了生成签名证书的方法，本例使用该方法。

K8S 的方式是创建一个 CertificateSigningRequest (CSR) 对象并提交到 K8S api-server，由具有管理权限的用户批准该申请，即可生成签名证书。

```yaml 
# samples/auth/appadmin-csr.yaml
apiVersion: certificates.k8s.io/v1
kind: CertificateSigningRequest
metadata:
# 申请的名字，并非用户名。
  name: appadmin-req
spec:
# 申请内容，将appadmin.csr内容使用base64编码。
  request: <appadmin.csr base64>
# 签名者是内置的，用于约束证书用途，本例中申请用于 api-server 的客户端认证。
  signerName: kubernetes.io/kube-apiserver-client
# 证书过期时间，默认为一年。这里的单位是秒。
  expirationSeconds: 8640000  # 100 day
# 证书用途，必须包括 'client auth'
  usages:
  - client auth
```
request的内容可以通过`base64`命令进行编码：
```
$ base64 appadmin.csr -w 0
LS0tLS1CRUdJTiBDRVJU .....
```
将结果复制到文件中即可。

> 上例使用了不换行的(-w 0) base64，换行的文本可以 使用 `request: |` 多行文本模式来编写。

在kubectl 提交该请求：
```
$ kubectl apply -f samples/auth/appadmin-csr.yaml
certificatesigningrequest.certificates.k8s.io/appadmin-req created
```
参看并批准该请求：
```
$ kubectl get csr
NAME           AGE   SIGNERNAME                            REQUESTOR       REQUESTEDDURATION   CONDITION
appadmin-req   48s   kubernetes.io/kube-apiserver-client   minikube-user   100d                Pending

$ kubectl certificate approve appadmin-req
certificatesigningrequest.certificates.k8s.io/appadmin-req approved
# 也可以用 deny 拒绝。

$ kubectl get csr
NAME           AGE     SIGNERNAME                            REQUESTOR       REQUESTEDDURATION   CONDITION
appadmin-req   3m23s   kubernetes.io/kube-apiserver-client   minikube-user   100d                Approved,Issued
# 申请已批准，证书已签发。
```
注意其中`REQUESTOR minikube-user`，和之前看到的 client.crt 中的 `CN`域一致。

签发的证书保存在 csr 申请的 status.certificate 字段中：
```
$ kubectl get csr appadmin-req -o yaml
```
```yaml
apiVersion: certificates.k8s.io/v1
kind: CertificateSigningRequest
metadata:
  annotations:
  creationTimestamp: "2023-01-10T02:26:57Z"
  name: appadmin-req
  resourceVersion: "526427"
  uid: 11dc047f-d141-4f59-a67d-4fbec80985f3
spec:
  expirationSeconds: 8640000
  groups:
  - system:masters
  - system:authenticated
  request: LS0tLS ...
  signerName: kubernetes.io/kube-apiserver-client
  usages:
  - client auth
  username: minikube-user
status:
  certificate: LS0tLS1CRUdJT...
  conditions:
  - lastTransitionTime: "2023-01-10T02:29:21Z"
    lastUpdateTime: "2023-01-10T02:29:21Z"
    message: This CSR was approved by kubectl certificate approve.
    reason: KubectlApprove
    status: "True"
    type: Approved
```
可以将status.certificate复制并使用base64解码，其内容是一个X509证书。或使用下面的命令直接将其保存：
```
$ kubectl get csr appadmin-req -o jsonpath='{.status.certificate}' | base64 -d > ~/.kube/profiles/appadmin/appadmin-client.crt
$ openssl x509 -in ~/.kube/profiles/appadmin/appadmin-client.crt -noout -text
Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            2e:94:73:b4:d1:6f:0e:36:5c:91:28:87:d7:77:0c:d5
        Signature Algorithm: sha256WithRSAEncryption
        Issuer: CN = minikubeCA
        Validity
            Not Before: Jan 10 02:24:21 2023 GMT
            Not After : Apr 20 02:24:21 2023 GMT
        Subject: O = app, CN = appadmin
        ...
```

#### 3.1.4 使用appadmin用户

需要配置 kubectl 使用 appadmin 用户证书及密钥。

```
$ cd ~/.kube/profiles/appadmin/
# 指定 用户名，证书，私钥。
$ kubectl config set-credentials appadmin --client-certificate=appadmin-client.crt --client-key=appadmin.key
User "appadmin" set.

$ kubectl config view | grep user -3
```
```yaml
...
users:
- name: appadmin
  user:
    client-certificate: profiles/appadmin/appadmin-client.crt
    client-key: profiles/appadmin/appadmin.key
- name: minikube
  user:
    client-certificate: ~/.minikube/profiles/minikube/client.crt
    client-key: ~/.minikube/profiles/minikube/client.key
```
> 由于 profiles目录在 ~/.kube目录下，因此这里使用了相对路径。

设置一个使用 appadmin 的 kube context 并切换： 
```
$ kubectl config set-context mk-app --cluster=minikube --user=appadmin --namespace=default
Context "mk-app" created.

$ kubectl config set current-context mk-app
Property "current-context" set.

$ kubectl config get-contexts
CURRENT   NAME       CLUSTER    AUTHINFO   NAMESPACE
          minikube   minikube   minikube   default
*         mk-app     minikube   appadmin   default
```

试着访问一下K8S资源：
```
$ kubectl get pods
Error from server (Forbidden): pods is forbidden: User "appadmin" cannot list resource "pods" in API group "" in the namespace "default"
```
appadmin用户被拒绝了，这时因为它没有list pods 的授权。

下一章 RBAC中介绍如何授权。

> 用户的`$HOME`目录下有一个`.kube/config` 文件，kubectl 的配置信息就保存在这个文件中。

### 3.2 RBAC 

RBAC 是 Role Based Authorization Control 的缩写。意思是基于角色的授权管理。

回顾 api-server 的章节，其中定义了:
* api-group: API分组，每组API管理一部分资源。
* resource: 资源，资源有些是按照名空间进行管理。有些是Cluster级别的。
* verbs: 操作，对资源的操作动词，如：create,get,list,delete,patch等。

授权的客体已经很明确了，就是： api-group/namespace/resource_type/resource/verbs。即：对何种资源进行何种操作。

授权的主体一般是`用户`。上文介绍了基于证书的用户，注意这是从集群外部访问api-server的用户，在集群内部的各组件、应用访问api-server时，使用`ServiceAccount`。

另一个授权主体是 Group(即：上文中的 Subject O 定义的名字)，组用户会继承组的授权。组和用户的定义完全由证书中的 Subject O/CN决定，无法通过其他方式改变。

因此，授权主体包括：
* 用户: user，是指外部使用证书(或令牌)进行身份认证的用户。
* 组：group。
* ServiceAccount: 集群内部管理的账户。


只需要建立 授权主体-客体 的关系，就可以完成授权和鉴权了。

RBAC 管理方法采用了 Role 角色 来建立 `主体-客体` 关系:
* 建立Role。
* 建立Role和客体的关系。
* 建立Role和主体的绑定关系(RoleBinding)。
* 主体继承了Role的授权。

```mermaid
graph TB
  rb[RoleBinding]
  rb -->rr[RoleRef] --> r[Role] 
  rs[rules] --> ag[apiGroups] --> res[resources] --> rsn[resourceName] 
  rs--> vb[verbs]
  s[Subjects]
  s --> g[Group] 
  s--> u[User]
  s--> sa[ServiceAccount]
  r-->rs
  rb-->s 
```

#### 3.2.2 Role

Role作为顶级对象，同样使用YAML来声明，先使用命令查看一下role的资源信息：
```
$ kubectl api-resources |grep Role
clusterrolebindings                            rbac.authorization.k8s.io/v1           false        ClusterRoleBinding
clusterroles                                   rbac.authorization.k8s.io/v1           false        ClusterRole
rolebindings                                   rbac.authorization.k8s.io/v1           true         RoleBinding
roles                                          rbac.authorization.k8s.io/v1           true         Role
```
Role 由 `rbac.authorization.k8s.io/v1` api管理，Kind是`Role`，由此可以写出yaml文件头：
```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: appadmin-role
```
Role中需要使用rules来定义一组授权规则，rule 相当于 `客体`，遵循 上面提到的 `api-group/namespace/resource_type/verbs` 的结构：
```yaml
rules:
- apiGroups: ["", "apps"]
  resources: ["pods", "delployments", "statefulsets"]
  verbs: 
  - get
  - list
  - watch 
```
这个规则定义了对核心API(使用"")和"apps"的资源 pods, deployments, statefullsets 的 get/list/watch授权(均为查看性质的授权)。

还可以再rule中使用resourceNames 来指定具体资源的名字。通常并不需要这样做。

由于Role是namespace级别的，因此，必须指定一个namespace。可以在YAML中定义 `metadata.namespace`，也可以在apply时使用当前名空间。

appadmin 的职责是管理应用的部署，因此，它需要对上述资源有修改权限，可以使用命令查看资源有哪些verbs:
```
$ kubectl api-resources -o wide | grep statefulsets
statefulsets                      sts          apps/v1                                true         StatefulSet
        create,delete,deletecollection,get,list,patch,update,watch   all
```
因此，需要在verbs加上：
```yaml
  verbs: 
  - create
  - delete
  - deletecollection
  - get
  - list
  - patch
  - update
  - watch
```
或者用通配符：
```yaml
  verbs: ["*"]
```
还需要赋予其他对象的查看权限，比如，允许查看 RBAC的资源：
```yaml
rules:
- apiGroups: ["rbac.authorization.k8s.io"]
  resources: ["*"]
  verbs: ["get", "list"] 
```

使用apply在default名空间创建该 Role：
```
# 先切换回 minikube 用户，否则无权限操作。
$ kubectl config set current-context minikube

$ kubectl apply -f samples/auth/appadmin-role.yaml
role.rbac.authorization.k8s.io/appadmin-role created
$ kubectl get roles
NAME            CREATED AT
appadmin-role   2023-01-10T06:53:57Z
``` 
下一步将 Role 绑定 到 用户 appadmin 
#### 3.2.3 RoleBinding

K8S 使用 RoleBinding 建立 Role 和 用户(或其他`主体`)的关系。

> 可以使用命令 `kubectl explain RoleBinding` 来查看资源说明。

同样使用YAML声明RoleBinding:
```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: appadmin-rb
subjects:
# 注意：这里使用 apiGroup, 而非 apiGroups.
- apiGroup: rbac.authorization.k8s.io
# 主体 User appadmin 
  kind: User
  name: appadmin
roleRef:
# 角色 appadmin-role
  name: appadmin-role
  apiGroup: rbac.authorization.k8s.io
  kind: Role
```

在 kubectl apply:
```
$ kubectl apply -f samples/auth/appadmin-role.yaml
role.rbac.authorization.k8s.io/appadmin-role unchanged
rolebinding.rbac.authorization.k8s.io/appadmin-rb created

$ kubectl get rolebindings
NAME          ROLE                 AGE
appadmin-rb   Role/appadmin-role   20s
```

这样就可以使用 appadmin用户来操作：
```
$ kubectl config set current-context mk-app
Property "current-context" set.

$ kubectl get pods
NAME                        READY   STATUS    RESTARTS   AGE
nginx-rs-5697d79d5d-96vnx   1/1     Running   0          27h
nginx-rs-5697d79d5d-fztjj   1/1     Running   0          27h
nginx-rs-5697d79d5d-nw2qk   1/1     Running   0          27h
nginx-sts-0                 1/1     Running   0          2d1h
nginx-sts-1                 1/1     Running   0          2d

$ kubectl delete pod/nginx-rs-5697d79d5d-96vnx
pod "nginx-rs-5697d79d5d-96vnx" deleted
```
对namespace default 的授权已经实现。

#### 3.2.1 ServiceAccount 

**ServiceAccount**是集群内部的用户，因此，完全由K8S管理。

集群内的组件、应用通过设置ServiceAccount来启用授权。workload 资源(pod/deploy/sts/ds等)都可以设置。设置ServiceAccount后，pod应用访问api-server时，将使用ServiceAccount鉴权。

比如：某个应用需要检测其他服务是否就绪，这时需要访问api-server，那么它需要有对这个资源的 get/list授权。

ServiceAccount广泛用于集群组件，比如，DNS 组件就需要监视(watch)所有pod, workload, service，这样才能在新Pod建立之后，更新域名信息。

本节仅简要介绍一下ServiceAccount。

新建ServiceAccount同样采用YAML声明。

```yaml
apiVersion: v1 
kind: ServiceAccount 
metadata:
  name: accountName
automountServiceAccountToken: true 
secrets: []
```

也可以直接用命令创建：
```
kubectl create sa <ServiceAccount Name>
```

对 Service Account 授权仍使用 RoleBinding, 将SA信息填写在其中的 subjects即可：
```yaml
subjects:
- apiGroup: ""
  kind: ServiceAccount 
  name: <ServiceAccount Name> 
``` 

`automountServiceAccountToken` 是指将ServiceAccount使用的认证信息以Secrets文件形式挂载到pod，这样pod就可以以其身份来认证鉴权了。

要使用ServiceAccount，在Pod声明中使用 serviceAccountName定义，如：
```yaml
apiVersion: apps/v1
kind: Deployment
spec: 
  template:
    serviceAccountName: <name>
```

#### 3.2.4 ClusterRole/ClusterRolebinding 

CulsterRole和ClusterRoleBinding 于 Role/Rolebinding 类似，通常是用于管理非namespace的资源。

也可以在RoleBinding中引用ClusterRole，将其`复制`到namespace中，这时ClusterRole就相当于一个模板。

### 3.3 模拟用户

kubectl 提供了一种模拟用户的命令，可以比较方便的检查用户和ServiceAccount的授权情况。

使用 `kubectl --as='username/ServiceAccountName'` 选项即可。 如:
```
$ kubectl get service
NAME          TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE
kubernetes    ClusterIP   10.96.0.1       <none>        443/TCP          7d5h
web-service   NodePort    10.98.134.132   <none>        8080:31001/TCP   5d19h

$ kubectl get service --as=appadmin
Error from server (Forbidden): services is forbidden: User "appadmin" cannot list resource "services" in API group "" in the namespace "default"
```

还可以用 kubectl auth can-i 来检查授权。

## 4. 存储动态制备

### 4.1 动态制备概念

所谓动态制备，是指不需要预先创建PV，而是在PVC申请PV时，根据`StorageClass`查找Provisioner，由Provisioner创建新的PV来满足PVC需求。

整个流程大致如下：
1. StorageClass指定的Provisioner会以组件Pod方式运行在K8S中。
2. Provisioner监视(watch)所有符合StorageClass的PVC。
2. Pod 通过 PVC 申请 PV。
3. K8S 检查PVC中的StorageClass。获取符合条件的PV。
4. 如果没有满足条件的PV，K8S将Pod挂起，并等待合适的PV(被其他Pod释放或新的PV创建)。
5. Provisioner监视到挂起的PVC后，根据自身配置情况，创建新的PV。
6. 如第三步，K8S将新建PV分配给Pod。
7. Pod运行结束后，根据PVC的Policy来决定是否保留或删除PV。
8. 删除PV的请求被Provisioner监视到，执行实际的删除/空间回收。

### 4.2 Provisioner 部署形式

由动态制备的流程可知，实现一个Provisioner的核心是Provisoner组件Pod，而组件与K8S其他组件、应用是解耦的。即：
* K8S并不需要关心Provisioner是否存在，如何运行，也不对其进行管理。两者之间的关联仅仅是StorageClass指定的 Provsioner 名字。
* Provisoner不需要关心应用Pod的具体信息，而仅依赖于PVC。
* K8S /Provisioner/ 应用POD三者之间，通过Provisioner 监视 PVC 建立联系。

PVC 到 Provisoner的链路如下：
```mermaid
graph LR
  p[Provisioner]
  sc[StorageClass]
  pv[PersistentVolume]
  pvc[PersistentVolumeClaim]
  pod[Pod]

  pod --> pvc --> sc --> p --> pv 
```

下图更详细的描述几者之间的关系： 

```mermaid
graph LR 
  p[Provisioner]
  sc[StorageClass]
  pv[PersistentVolume]
  pvc[PersistentVolumeClaim]
  pvct[VolumeCliamTemplate]
  pod[Pod]

  sc --provisioner--> p
  pvc --storageClassName--> sc 
  pvc --Claim request--> pv
  pvct --Create--> pvc
  pod --Declare--> pvc
  pod --Declare--> pvct

  p --Watch--> pvc 
  p --Create--> pv 

```

因此，Provisioner的工作内容实际是：
1. 监视(Watch) StorageClass: 找到包含provisiner名字的sc。
2. 监视(Watch) PVC：找到包含应用Provisioner的PVC。
2. 根据PVC创建PV。
3. 监视PV，当PV解绑后，可控制回收PV或删除PV。
4. 假如Provisoner重启动了，需要监视PV来获取已经动态制备的PV(因此，通常会在动态制备PV上添加一些标志性的Label)。

这里要注意的是，Pod 绑定 PV 的过程，是K8S完成的，而非 Provisioner。

这些工作都需要访问 api-server，那么，Provision就需要恰当的授权。至少需要：
```yaml
rules:
  - apiGroups: [""]
    resources: 
    - persistentvolumeclaims
    verbs: 
    - get
    - list
    - watch
  - apiGroups: [""]
    resources: 
    - persistentvolumes
    verbs: ["get", "list", "watch", "create","delete", "update"]
    # verbs: ["*"]
  - apiGroups: ["storage.k8s.io"]
    resources:
    - storageclasses 
    verbs: ["get", "list", "watch"]
```

在 RBAC中需要创建一个 ServiceAccount，一个 Role(或ClusterRole)和相应的RoleBinding(ClusterRoleBinding)。

由于 PVC 属于 namespace 资源，因此，假如多个名空间需要使用该Provsioner，还需要在每个名空间分别授权。

Provisioner当然可以运行在K8S之外，但在K8S集群内运行更佳，因此，大部分Provisioner还需要部署一个Deployment(或DaemonSet)。 

如果Provisioner是有状态的，需要保存一些数据，那么部署会复杂一些，比如：使用DaemonSet结合Local来存储较少的数据。

### 4.3 NFS动态制备

本例采用nfs-subdir-provisioner作为动态制备器。从名称可以看出，该provisioner是使用了子目录(subdir)
的方式进行动态制备。即：以一个NFS目录作为待分配的空间，在其中建立子目录来产生动态制备的PV。

这种方式实现原理简单，缺陷也很明显：Provisioner 绑定了一个 NFS目录，当需要部署多个NFS目录时，就需要创建不同的 Pdovisoner Pod，使用不同的Provisoner名称加以区分。

个人觉得更理想的方法是在 provisoner的 paramter中指定 NFS 目录信息。这样通过不同的stroageClass来区分NFS目录更为合理。比如：
```yaml
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: nfs-client-<server-export>
provisioner: k8s-sigs.io/nfs-subdir-external-provisioner
parameters:
  archiveOnDelete: "false"
  nfsServer: <ServerIP>
  nfsExport: <export dir>
  storage: 100Gi
```
但并没有这样实现，大约是因为基于NFS存储并非主流云存储方式，因此没有费心去处理这些细节。

这从部署资料也能看出来，推荐将其部署在应用相同的名空间中。这样使用方便。


#### 4.3.1 下载nfs-subdir

该项目主页为 https://github.com/kubernetes-sigs/nfs-subdir-external-provisioner/。 可以使用 git clone 该项目。

```
git clone https://github.com/kubernetes-sigs/nfs-subdir-external-provisioner.git
```

#### 4.3.2 部署说明

官方提供了 helm Chart，本例中为了更好的理解 Provisioner，使用手动安装。

#### 4.3.3 准备 NFS export dir 

上例中已经创建了 NFS Server 和目录。可以新建一个 目录，也可以就用原来的目录。
为简单起见，使用原来的目录。

#### 4.3.4 部署文件说明

Clone项目后，手动部署文件保存在 `deploy/`目录下，在`depoly/objects/`目录下还有一组按对象单独编写的声明文件。本例使用 `objects`目录下，这样部署文件的结构更清晰。
```
$ cd /deploy/objects
$ tree
├── README.md
├── class.yaml               # StorageClass 
├── clusterrole.yaml         # ClusterRole
├── clusterrolebinding.yaml  # ClusterRoleBinding 
├── deployment.yaml          # Deployment
├── role.yaml                # Role
├── rolebinding.yaml         # RoleBinding
└── serviceaccount.yaml      # ServiceAccount
``` 
核心文件是 deployment.yaml 用来部署Provisioner POD。
class.yaml 是StorageClass的示例文件。
其他文件是RBAC所需的授权资源。

##### 4.3.4.1 RBAC 文件

前文介绍了Provisoner所需的资源授权，来看一下 nfs-subdir的ClusterRole授权：
```yaml
kind: ClusterRole
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: nfs-client-provisioner-runner
rules:
  - apiGroups: [""]
    resources: ["nodes"]
    verbs: ["get", "list", "watch"]
  - apiGroups: [""]
    resources: ["persistentvolumes"]
    verbs: ["get", "list", "watch", "create", "delete"]
  - apiGroups: [""]
    resources: ["persistentvolumeclaims"]
    verbs: ["get", "list", "watch", "update"]
  - apiGroups: ["storage.k8s.io"]
    resources: ["storageclasses"]
    verbs: ["get", "list", "watch"]
  - apiGroups: [""]
    resources: ["events"]
    verbs: ["create", "update", "patch"]
```
该授权中增加了node和event的授权。
> 由于 persistentVolume是集群级别(非名空间)资源，因此，需要使用ClusterRole。  

> role.yaml的用途，推测应为 Leader election的。

serviceaccount.yaml定义了nfs-client-provisioner 账户。

clusterrolebinding.yaml将ClusterRole 绑定到 ServiceAccount：
```yaml
kind: ClusterRoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: run-nfs-client-provisioner
subjects:
  - kind: ServiceAccount
    name: nfs-client-provisioner
    # replace with namespace where provisioner is deployed
    namespace: default
roleRef:
  kind: ClusterRole
  name: nfs-client-provisioner-runner
  apiGroup: rbac.authorization.k8s.io
```

##### 4.3.4.2 StorageClass文件

class.yaml定义了storageClss 的示例：
```yaml
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: nfs-client
provisioner: k8s-sigs.io/nfs-subdir-external-provisioner 
# or choose another name, must match deployment's env PROVISIONER_NAME'
parameters:
  archiveOnDelete: "false"
``` 
nfs-subdir 有三个paramter, 用于控制PV删除时的数据处理方式，archive是指将删除的PV目录归档。

这里定义的 metadata.name 和 provisioner 名字都是可以修改的。

注意应保持 provisioner 和 deployment 中的 环境变量 `PROVISIONER_NAME` 一致。

##### 4.3.4.3 Deployment 文件

重点看 deployment.yaml 中的 pod template 部分：
```yaml
    spec:
    # 使用 nfs-client-provisioner 账户运用
      serviceAccountName: nfs-client-provisioner
      containers:
        - name: nfs-client-provisioner
          image: k8s.gcr.io/sig-storage/nfs-subdir-external-provisioner:v4.0.2
          volumeMounts:
            - name: nfs-client-root
              mountPath: /persistentvolumes
          env:
            - name: PROVISIONER_NAME
              value: k8s-sigs.io/nfs-subdir-external-provisioner
            - name: NFS_SERVER
              value: 10.3.243.101
            - name: NFS_PATH
              value: /ifs/kubernetes
      volumes:
        - name: nfs-client-root
          nfs:
            server: 10.3.243.101
            path: /ifs/kubernetes
```
可以看到，nfs-subdir的实现方式，是将一个NFS目录作为Volume挂载到容器，再为PVC建立subdir的PV。

部署前，需要修改这几项内容，指向预备好的NFS Server。

##### 4.3.4.4 修改namespace

上述文件中均已绑定namespace为default，如需部署在其他名空间，需要将其修改为自定义的名空间。

#### 4.3.5 部署nfs-subdir-provisoner

本例中已将相关文件复制到samples/nfs-subdir/, 并修改其中的deployment.yaml 中的 NFS 信息：
```yaml
    spec:
      serviceAccountName: nfs-client-provisioner
      containers:
        - name: nfs-client-provisioner
          # 无法使用k8s.gcr.io，使用dockerio的镜像
          image: dyrnq/nfs-subdir-external-provisioner:v4.0.2
          # image: k8s.gcr.io/sig-storage/nfs-subdir-external-provisioner:v4.0.2
          volumeMounts:
            - name: nfs-client-root
              mountPath: /persistentvolumes
          env:
            - name: PROVISIONER_NAME
              value: k8s-sigs.io/nfs-subdir-external-provisioner
            - name: NFS_SERVER
              value: nfs-server
            - name: NFS_PATH
              value: /var/data/nfs
      volumes:
        - name: nfs-client-root
          nfs:
            path: /var/data/nfs
            server: nfs-server
```
本例中使用 `nfs-server`代替ip地址。需要在节点的/etc/hosts中添加主机名如：
```
172.24.129.138  nfs-server
```

使用kubectl部署目录中的全部yaml 即可，：
```
$ cd samples/nfs-subdir/
$ kubectl apply -f samples/nfs-subdir/
storageclass.storage.k8s.io/nfs-client created
clusterrole.rbac.authorization.k8s.io/nfs-client-provisioner-runner created
clusterrolebinding.rbac.authorization.k8s.io/run-nfs-client-provisioner created
deployment.apps/nfs-client-provisioner created
role.rbac.authorization.k8s.io/leader-locking-nfs-client-provisioner created
rolebinding.rbac.authorization.k8s.io/leader-locking-nfs-client-provisioner created
serviceaccount/nfs-client-provisioner created

$ kubectl get pods
NAME                                     READY   STATUS    RESTARTS   AGE
nfs-client-provisioner-b8fdbfc6b-82wbd   1/1     Running   0          8s
```

#### 4.3.6 测试

只需要修改之前的 StatefulSet 的 StorageClass 即可：

```yaml
# samples/nginx-nfs-subdir-statefulset.yaml
  volumeClaimTemplates:
  - metadata:
      name: nfs-path
    spec:
      accessModes: [ "ReadWriteOnce" ]
      storageClassName: nfs-client
      resources:
        requests:
          storage: 100Mi
```
部署即可:
```
# 删除原nginx-sts
$ kubectl delete -f samples/nginx-nfs-statefulset.yaml
statefulset.apps "nginx-sts" deleted

$ kubectl apply -f samples/nginx-nfs-subdir-statefulset.yaml
statefulset.apps/nginx-sts created

$ kubectl get pvc
NAME                   STATUS    VOLUME     CAPACITY   ACCESS MODES   STORAGECLASS         AGE
local-pvc              Bound     local-pv   100Mi      RWO            local-storage        5d3h
nfs-path-nginx-sts-0   Bound     nfs-pv1    200Mi      RWO            nfs-static-storage   3d
nfs-path-nginx-sts-1   Bound     nfs-pv2    200Mi      RWO            nfs-static-storage   3d
nfs-path-nginx-sts-2   Bound     nfs-pv3    200Mi      RWO            nfs-static-storage   3d
nfs-path-nginx-sts-3   Pending                                        nfs-static-storage   2d2h
```

注意到 nginx-sts 仍然使用了旧的PV, 这是因为 StatefulSet 保留了PVC, 因此, 重启后仍使用该pvc.
需要手动删除pvc.
```
# 先缩至0 
$ kubectl scale sts/nginx-sts --replicas=0
statefulset.apps/nginx-sts scaled

$ kubectl delete  pvc -l app/name=nginx
persistentvolumeclaim "nfs-path-nginx-sts-0" deleted
persistentvolumeclaim "nfs-path-nginx-sts-1" deleted
persistentvolumeclaim "nfs-path-nginx-sts-2" deleted
persistentvolumeclaim "nfs-path-nginx-sts-3" deleted

# 再改回 3
$ kubectl scale sts/nginx-sts --replicas=3
statefulset.apps/nginx-sts scaled

$ kubectl get  pvc -l app/name=nginx 
NAME                   STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS   AGE
nfs-path-nginx-sts-0   Bound    pvc-28d05ee3-bdeb-47d1-9f1a-75e961ddff99   100Mi      RWO            nfs-client     15s
nfs-path-nginx-sts-1   Bound    pvc-d9e8d3bb-35be-49b7-b2d1-353886ebd4c3   100Mi      RWO            nfs-client     11s
nfs-path-nginx-sts-2   Bound    pvc-b889b9e3-1253-474b-bb78-7deeaf994bf1   100Mi      RWO            nfs-client     7s
```

可以看一下NFS服务的目录：
```
$ ls /var/data/nfs/
default-nfs-path-nginx-sts-0-pvc-28d05ee3-bdeb-47d1-9f1a-75e961ddff99
default-nfs-path-nginx-sts-1-pvc-d9e8d3bb-35be-49b7-b2d1-353886ebd4c3
default-nfs-path-nginx-sts-2-pvc-b889b9e3-1253-474b-bb78-7deeaf994bf1
```
可以看到建立了三个子目录。

## 5. Helm 

### 5.1 Helm简介

Helm 是 K8S 资源包管理工具，也是官方推荐使用的工具。

在前一个例子中，使用 nfs-subdir 的时候，需要将 namespace 修改为想要的内容。会不会有此疑问：
* K8S YAML文件为什么不能使用变量呢？

想要更方便的复用K8S资源文件，必须提供方便的可配置的方法。Helm就应运而生了。

Helm 分为两部分功能：
1. 包管理：提供了一套组织K8S资源文件的结构，称之为包，Helm提供仓库(repo)，允许用户上传、下载K8S资源包。Helm 还提供包依赖、包版本管理。简言之，就是 K8S 的 apt/yum。 
2. 模板技术：提供了扩展的Golang template，可以方便的对一组资源文件进行模板化编写。 

仓库和包管理的功能，使得Helm社区壮大，可以在Helm的官方仓库找到大量的K8S资源包。许多开源产品也提供Helm安装包，这些包可以简单配置后使用，也可以对其进行修改。

掌握Helm的重点是如何利用模板技术，编写简洁的，方便复用的 K8S资源包。

可参考官方文档：https://helm.sh/zh/docs/ 

### 5.2 Helm 基础

#### 5.2.1 安装

Helm 使用 Go 语言编写，继承了一贯简单风格，仅有一个可执行文件`helm`。

直接从 github release页面下载即可：
```
$ curl -LO https://get.helm.sh/helm-v3.10.3-linux-amd64.tar.gz
```
将其解压并移动到 /usr/bin或其他系统路径。安装即可完成。

#### 5.2.2 包结构

使用 helm 创建一个样例包：
```
$ helm create nginx-sts
Creating nginx-sts

$ tree nginx-sts/
nginx-sts/
├── Chart.yaml                    # Chart 声明
├── charts                        # 依赖子chart
├── templates                     # 模板目录，资源等放在该目录下
│   ├── NOTES.txt                 # 说明文件
│   ├── _helpers.tpl              # 用于声明命名模板
│   ├── deployment.yaml           # deployment 样例
│   ├── hpa.yaml                  # 自动缩放控制器 样例
│   ├── ingress.yaml              # ingress 样例
│   ├── service.yaml              # Service 样例
│   ├── serviceaccount.yaml       # 服务账户 样例
│   └── tests                     # 测试
│       └── test-connection.yaml  # 测试 Service 样例
└── values.yaml                   # Chart 使用的 变量 数据
```
templates目录下的文件在安装时都会作为模板进行处理。

下文将分章节说明各部分文件的用途。

#### 5.2.3 values.yaml

values.yaml中包含了`配置`数据，在Helm文档称之为`configuration values`。
```
$ cat values.yaml
```
```yaml
# Default values for nginx-sts.
# This is a YAML-formatted file.
# Declare variables to be passed into your templates.

replicaCount: 1
image:
  repository: nginx
  pullPolicy: IfNotPresent
  # Overrides the image tag whose default is the chart appVersion.
  tag: ""

imagePullSecrets: []
nameOverride: ""
fullnameOverride: ""
# ...
```
这里定义的变量，可以转换为Values.的成员变量，比如:
```
{{ .Values.replicaCount }}
{{ .Values.image.repository }}

{{ .Values.imagePullSecrets.[0] }}
```

在Helm提供的样例Values基础上是补充所需的变量推荐的方法。

根据这些变量的名字，大致就能猜到它的用途，比如：
* imagePullSecrets是用于定义 containers 镜像服务器认证信息的。
* replicaCount是用于deployment或StatefulSet 的replicas。

#### 5.2.4 Chart.yaml

Chart.yaml 声明 Helm 包。Helm 包就叫做`Chart`。
```yaml
apiVersion: v2
name: nginx-sts
description: A Helm chart for Kubernetes

# A chart can be either an 'application' or a 'library' chart.
type: application

# This is the chart version. This version number should be incremented each time you make changes
version: 0.1.0

# This is the version number of the application being deployed. This version number should be
# incremented each time you make changes to the application.
appVersion: "1.16.0"
```
Chart形式类似于K8S的资源声明。 其中的 `version` 是指 Chart版本号，使用版本号的规则，Chart发布时回控制。`appVersion` 是 应用的版本号。这两者的差异是，假设部署一个Prometheus资源，那么，`appVersion`应该是 Prometheus 的版本号。而 `version` 是 Chart 包的版本号。

#### 5.2.5 charts 依赖

在Charts.yaml 中没有描述 子 Chart (sub charts) 的信息。下面简要介绍一下：
```yaml
dependencies: # chart 必要条件列表 （可选）
- name: chart名称 (nginx)
  version: chart版本 ("1.2.3")
  repository: （可选）仓库URL ("https://example.com/charts") 或别名 ("@repo-name")
  condition: （可选） 解析为布尔值的yaml路径，用于启用/禁用chart (e.g. subchart1.enabled )
  tags: # （可选）
    - 用于一次启用/禁用 一组chart的tag
  import-values: # （可选）
    - ImportValue 保存源值到导入父键的映射。每项可以是字符串或者一对子/父列表项
  alias: （可选） chart中使用的别名。当你要多次添加相同的chart时会很有用
```

使用 `dependencies` 罗列子chart信息。包括 名称，版本，以及所在的Helm仓库。

其他内容并不常用。

定义了dependencies 后，使用命令: `helm dependency update` 或简写 `helm dep up` 就可以将子Chart下载到charts目录下。

在helm执行安装时，会自动安装子chart。(也可以使用 tags , condition 等选项来控制是否安装)

在values.yaml中可以定义子chart的配置数据，使用sub chart 的名字，如：
```yaml
subChartName:
  data1: 
  data2: 
# 或者用别名
subChartAliasName:
  data1:
```
SubChart模板执行时，`.Values`的内容是 `subChartName`。 

#### 5.2.6 templates

Helm使用Golang 模板定义所有的资源文件，看一下deployment.yaml例子：
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "nginx-sts.fullname" . }}
  labels:
    {{- include "nginx-sts.labels" . | nindent 4 }}
spec:
  {{- if not .Values.autoscaling.enabled }}
  replicas: {{ .Values.replicaCount }}
  {{- end }}
  selector:
    matchLabels:
      {{- include "nginx-sts.selectorLabels" . | nindent 6 }}
# 
```
看这个例子比较复杂，其中大量使用了`命名模版`。但从含义上大致能看出来模板的意思。比如：
* `name: {{ include "nginx-sts.fullname" . }}` include 是包含 一个`命名模板`。
* `replicas: {{ .Values.replicaCount }}` ，使用 values.yaml 中的 replicaCount 替换。
* `{{- if }} ... {{- end }}`，这是 if 流程控制。

下文会简要介绍go模板的语法和常用方法。

### 5.3 Helm/Go模板

Go 模板是 Go语言发明的一种模板技术。广泛应用于Go生态。Go 模板的最大优点是可以自由的引入go语言函数。

GO 模板语句使用 `{{ }}` 包含，其中的内容将作为模板进行渲染(替换)。

Go 模板技术较容易掌握，Helm官方文档有详尽的介绍和例子。Helm对go模板进行了一些扩展(主要是增加了函数)。

Helm 模板主要包括以下内容:
* 访问对象：go 的对象传递至模板中，可以访问其成员。
* 函数及管道：在 go 中调用函数，或使用管道调用函数。
* 流程控制：if-else 、range 循环。
* 变量：使用 `$varname:= <value>` 来声明变量。
* 命名模板：可以理解为子模版。使用 define 定义命名模板，使用 include 或 template来执行命名模板。

#### 5.3.1 访问对象(Helm内置对象)

Helm 向模板传递的对象称之为`内置对象`。包括：
* Values: Values.yaml中定义了配置数据。
* Chart: Chart.yaml的配置。
* Release: Helm 执行版本发布的数据。
* Template: 当前模板的信息。如：Name(模板文件名)，BasePath(路径)等。
* Capabilities: 提供K8S集群的版本等支持性信息。

另有工具类：Files，提供一组函数用于访问资源文件。

在模板中访问对象的方法是：` {{ .Chart.name }} `, 其中 `.` 指示`当前对象`。后面的则是按照成员层次访问。

`当前对象`随着作用域会发生变化：
* with: 使用with 会改变当前对象，
  * 如：`{{ with .Chart }} {{ .name }} {{ end }}。将.Chart设定为当前变量，类似于JavaScript 的with。
* range: 使用range 循环时，循环作用域内的当前对象，是range的迭代item。
  * 如： `{{ range .Values.imagePullSecrets }} {{ . }} {{ end }}`，range 作用域中的 `.`代表.Values.imagePullSecrets 列表的 item。

> 可以向命名模板传递对象，该对象将作为模板中的`当前对象`。

在模板输出中渲染对象的值的方法，就是直接使用 {{ .Chart.name }}。

#### 5.3.2 调用函数

GO 模板中的函数是除了if-else end range with 等保留字之外的任何 `名称`,均作为函数调用。
如：`{{ sum 1 2 }}`，sum 就是函数名， 1 2 是它的两个参数，相当于：`sum (1,2)` 。

> 因此也可以理解，为什么引用对象时需要使用 `.` 开头。

另一种调用方法是使用`管道`。类似于 linux shell 中的管道概念：
* 一个命令的输出，作为另一个命令的输入。`cat etc/hosts | more` 
GO 模板的管道是：
* 一个表达式(函数，对象，变量等)的返回值，作为 另一个函数的输入参数。当然，参数只能有一个。如：
  * {{ .Chart.name | upper | quote }}: 相当于 `quote ( upper ( .Chart.Name ) )`, 把名字大写，并加双引号。

#### 5.3.3 定义变量

GO 中可以定义变量，语法是：`{{ $varname := <value> }}`。

变量是有作用域的，在range with 等作用域的变量仅在此范围内有效。

特殊变量 `$` 指代根对象，在任何作用域中，使用 `{{ $.Values...  }}` 都是可以访问到 chart 的 Values.yaml数据的。

变量在range中比较有用：
```
  toppings: |-
    {{- range $index, $topping := .Values.pizzaToppings }}
      {{ $index }}: {{ $topping }}
    {{- end }}
# 对于列表类型的迭代，$index是item序号，$stopping 是 item 。

{{- range $key, $val := .Values.favorite }}
  {{ $key }}: {{ $val | quote }}
  {{- end }}
# 对于 map 的迭代，$key 是 key键值， $val 是value.   
```

#### 5.2.7 流程控制

循环 range 和 with 在上文已有介绍。

经典的 if - else 语法如下：
```
{{ if 表达式 }}
{{ else }}
{{ end }}
``` 
表达式，在 Go 使用术语 pipeline。实质是指 if 后的条件是一系列函数，或者对象。
模板不使用 boolean 表达式，而是使用函数替代。如：
* eq : 等于
* ne: 不等
* not : 非
* gt: 
* lt: 
* and: 
* or:
* ... 

#### 5.2.8 计算

数学计算符号+-*/都没有，全部使用函数实现：
* add
* sub 
* ...

#### 5.2.9 命名模板

可以使用 define 定义命名模板，使用 include 或 template来执行模板。

如：
```
{{ define "chart.labels"}}
  app/name: {{ .name }}-test
  app/version: "1.0"
{{ end }}
```
调用时：
```
{{ template "chart.labels" .Chart }}
```
其中的 `.Chart` 很重要，template 将使用 .Chart 作为其 根对象。

通常会使用 include 而非 template 来调用 模板，这是因为 template 无法进行灵活的输出控制。
> 两者的区别：可以将 template 理解为无返回值的函数，在函数中直接输出结果。而include 理解为有返回值函数，可以使用管道对其结果进行处理。

#### 5.2.10 空白控制

YAML文件是使用空白来表示文件结构的，因此，模板中如何处理空白变得异常重要。。。

GO 模板提供了下列方法来控制：
* `{{- .Chart.name }}`: 左边的 `-` 表示 删除左边的全部空白。
* `{{ .Chart.name -}}`: 右边的 `-` 表示 删除右边的空白，注意，包括换行符。
* `{{- .Chart.name | indent 6 }}`: 使用函数 indent 对文本进行 缩进，这里指定缩进6个空格。

可以看到官方的各种例子中大量使用上述技巧。

#### 5.2.11 常用函数

集合函数：
* list： 创建一个集合 `$ l := list 1 2 3 4 5 6 `
* tuple: 创建一个 tuple `tuple "a" 1, "3" ` 

字符串函数：
* qoute: 加引号。sqoute是单引号。 
* printf: 格式化 `printf "%s has %d dogs." .Name .NumberDogs`
* cat: 用空格连接字符串，相当于`javascript join`
* indent: 退格。
* contains，hasPrefix，hasSuffix：检查字符串中是否包含(或前缀、后缀)在另一个字符串。`contains "cat" "catch" `.
* substr: 取子串，substr startIndex endIndex string，`substr 0 5 "hello world"` 
* trim: 去掉两端空格。
* trimAll, trimPrefix，trimSuffix: 移除全部(或前缀，后缀)字符, `trimAll "$" "$5.00"` 
* lower, upper, title, untitle,camelcase,snakecase,kebabcase：各类大小写转换。

base64：
* b64enc: base64编码
* b64dec: base64解码

### 5.3 Helm 创建示例

本节使用Helm 创建之前的nginx-nfs-subdir-sts。

#### 5.3.1 内容
nginx-nfs-subdir-sts 中包括：
* StatefulSet 
* nfs-subdir-provisioner
* StorageClass 
* Servive
* Ingress
* Namespace 

使用一个Ingress + Service 来对外暴露 StatefulSet。
StatefulSet 使用 StorageClass 引用 nfs-subdir-provisioner。

另外，创建一个Namespace来自动创建名空间。

#### 5.3.2 开始

仍使用nginx-sts作为helm 名称。可以使用 `helm create nginx-sts` 创建。

#### 5.3.3 添加nfs-subdir依赖

在Chart.yml中添加依赖：
```yaml
dependencies:
  - name: nfs-subdir-external-provisioner
    repository: https://kubernetes-sigs.github.io/nfs-subdir-external-provisioner/
    version: 4.0.16
```
下载依赖包：
```
$ cd helm nginx-sts
$ helm dep up
Getting updates for unmanaged Helm repositories...
...Successfully got an update from the "https://kubernetes-sigs.github.io/nfs-subdir-external-provisioner/" chart repository
Saving 1 charts
Downloading nfs-subdir-external-provisioner from repo https://kubernetes-sigs.github.io/nfs-subdir-external-provisioner/
Deleting outdated charts

$ ls charts
nfs-subdir-external-provisioner-4.0.16.tgz
```
`nfs-subdir` chart下载成功，打包的格式是 tgz。

可以将该包接开，并查看其中的 values.yaml，这里包含安装时的配置数据。从中摘了一些需要使用的数据项：
```yaml
image:
# 由于难以访问google镜像，此处需要修改。
  repository: k8s.gcr.io/sig-storage/nfs-subdir-external-provisioner
  tag: v4.0.2
  pullPolicy: IfNotPresent
nfs:
# nfs服务器的地址，需要配置。
  server:
# nfs export 路径，需要配置 
  path: /nfs-storage
  mountOptions:
  volumeName: nfs-subdir-external-provisioner-root
  # Reclaim policy for the main nfs volume
  reclaimPolicy: Retain
  # For creating the StorageClass automatically:
storageClass:
  create: true
  # Set a provisioner name. If unset, a name will be generated. 
  # provisionerName:

  # Set StorageClass as the default StorageClass
  # Ignored if storageClass.create is false
  defaultClass: false

  # Set a StorageClass name
  # Ignored if storageClass.create is false
  # 在VolumeClaimTemplate需要使用 storage class 名字
  name: nfs-client
```

在values.yaml中定义 上述数据:
```yaml
nfs-subdir-external-provisioner: 
  image:
    repository: dyrnq/nfs-subdir-external-provisioner
    tag: v4.0.2
  nfs:
    server: nfs-server
    path: /var/data/nfs
  
```
使用 sub chart 的名字,或别名,定义其配置数据, `nfs-subdir-external-provisioner` 包含的配置数据将和values.yaml 中的数据合并。

storageclass 的值，也可以定义在values.yaml中，但这里想要演示以下 import-values 的功能：因此，在Chart.yaml添加：
```yaml
  dependencies:
  - name: nfs-subdir-external-provisioner
    repository: https://kubernetes-sigs.github.io/nfs-subdir-external-provisioner/
    version: 4.0.16
    import-values:
    - child: storageClass
      parent: nfsStorageClass
```
增加了 `import-values` 声明，将 sub chart 的 `storageClass`数据引入到 parent Chart 的 `nfsStorageClass`，这样就可以使用 `.Values.nfsStorageClass.name` 来引用。

#### 5.3.4 声明 StatefulSet

可以在原有的 StatefulSet `nginx-nfs-subdir-statefulset.yaml` 中修改就可以完成。

##### 5.3.4.1 metadata 
首先来看，metadata部分：
```yaml
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: {{ include "nginx-sts.fullname" . }}
  labels:
    {{- include "nginx-sts.labels" . | nindent 4 }}
```
这里使用了两个`命名模板`，这两个模板定义在自动生成的 _helper.tpl中：
```yaml
{{/*
Create a default fully qualified app name.
We truncate at 63 chars because some Kubernetes name fields are limited to this (by the DNS naming spec).
If release name contains chart name it will be used as a full name.
*/}}
{{- define "nginx-sts.fullname" -}}
{{- if .Values.fullnameOverride }}
{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- $name := default .Chart.Name .Values.nameOverride }}
{{- if contains $name .Release.Name }}
{{- .Release.Name | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
{{- end }}
{{- end }}
{{- end }}
```
对nginx-sts-fullname说明：
* `{{/* */}}`: 注释，不会渲染。
* `{{- define "nginx-sts.fullname" -}}`: 声明`命名模板`。注意前后`-`会删除所有空格包括换行符。
* `{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}`：trunc 63 是截断字符串保留最多63个字符。
* `{{- $name := default .Chart.Name .Values.nameOverride }}`: default 是指当第一个参数为空时，使用第二参数值。还可写作：`.ChartName | default .Values.nameOverride` 
* 关注上述流程控制语句的空白处理。

这是一个Helm推荐模板，使用Release.name ，Chart.name 和 nameOrride来定义最终的资源名称。

```yaml
{{/*
Common labels
*/}}
{{- define "nginx-sts.labels" -}}
helm.sh/chart: {{ include "nginx-sts.chart" . }}
{{ include "nginx-sts.selectorLabels" . }}
{{- if .Chart.AppVersion }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
{{- end }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end }}

{{/*
Selector labels
*/}}
{{- define "nginx-sts.selectorLabels" -}}
app.kubernetes.io/name: {{ include "nginx-sts.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}
```
对象的标签，这里使用了 K8S 官网的 建议 使用的 标签。
由于 app.kubernetes.io名字比较长，可以根据自己组织的命名来修改，如：
`app.<Your org name>/name`。或者直接写作 `app/name`这种比较短的模式。

本例中将去掉k8s.io的名字，这样在使用命令行时比较方便。

当然，这些模板不是必须使用的，只是一种惯例。初期会提高学习难度，如果觉得麻烦，可以简化。

另，可以加上一个storage class 标签。那么，可以直接在其中增加：
```yaml
{{- if .Values.nfsStorageClass.name }}
app/storage: {{ if .Values.nfsStorageClass.name }}
{{- end }}
```

##### 5.3.4.2 spec

spec部分：
```yaml
spec:
  serviceName: {{ .Values.service.name }}
  {{- if not .Values.autoscaling.enabled }}
  replicas: {{ .Values.replicaCount }}
  {{- end }}
  selector:
    matchLabels:
      {{- include "nginx-sts.selectorLabels" . | nindent 6 }}
  volumeClaimTemplates:
  - metadata:
      name: {{ .Values.volumeMount.name }}
    spec:
      accessModes: [ "ReadWriteOnce" ]
      storageClassName: {{ .Values.nfsStorageClass.name }}
      resources:
        requests:
          storage: 100Mi
```

这部分 matchLabels内容都是相同的。使用了三个配置：
```
service:
  name: web-service
  type: ClusterIP
  port: 80

volumeMount: 
  name: nfs-path
  path: "/usr/share/nginx/html/nfs"
```

##### 5.3.4.3 pod template

Podtemplate 部分可以采用标准模板来实现：
```yaml
  template:
    metadata:
      {{- with .Values.podAnnotations }}
      annotations:
        {{- toYaml . | nindent 8 }}
      {{- end }}
      labels:
        {{- include "nginx-sts.selectorLabels" . | nindent 8 }}
```
labels 使用了 selectorLabels。
container部分：
```yaml
    spec:
      {{- with .Values.imagePullSecrets }}
      imagePullSecrets:
        {{- toYaml . | nindent 8 }}
      {{- end }}
      containers:
        - name: {{ .Chart.Name }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
          imagePullPolicy: {{ .Values.image.pullPolicy }}
          ports:
          - name: http
            containerPort: {{ .Values.service.port }}
            protocol: TCP
          livenessProbe: 
          httpGet: 
            path: /
            port: 80 
          initialDelaySeconds: 2
          periodSeconds: 30
          volumeMounts:
          - mountPath: {{ .Values.volumeMount.path }}
            name: {{ .Values.volumeMount.name }}
```
其中引用了 Image 和 vloumeMount等配置数据。

`toYaml` 的作用是将对象按yaml格式渲染。注意`indent`的使用，必须符合缩进要求。

#### 5.3.5 service 

Service 内容很简单，使用Helm默认service.yaml即可：
```yaml
apiVersion: v1
kind: Service
metadata:
  name: {{ include "nginx-sts.fullname" . }}
  labels:
    {{- include "nginx-sts.labels" . | nindent 4 }}
spec:
  type: {{ .Values.service.type }}
  ports:
    - port: {{ .Values.service.port }}
      targetPort: http
      protocol: TCP
      name: http
  selector:
    {{- include "nginx-sts.selectorLabels" . | nindent 4 }}
```
这里的service type 在values中定义，使用了ClusterIP。ClusterIP 是将 服务集中在一个虚拟IP 上。

注意 selector 使用和其他资源相同的 labels。这样，在使用 kubectl get 时可以使用一致的查询方式。

#### 5.3.5 ingress 

ingress 基本上，使用Helm默认的ingress.yaml就可以了，只是需要在values.yaml中补充hosts映射。

如：
```yaml
# valaues.yaml
ingress:
  enabled: true
  className: nginx
  annotations: 
    # kubernetes.io/ingress.class: nginx
    # kubernetes.io/tls-acme: "true"
  hosts:
  - host: "s1.example.net"
    http:
      paths:
      - pathType: Prefix
        path: "/"
  - host: "*.example.net"
    http:
      paths:
      - pathType: Prefix
        path: "/nfs"
```

默认的backend 是 Service.yaml定义的服务。因此，仅把host/path定义即可。

> ingress.yaml官方模板比较复杂，可以按照自己的文件直接修改模板化即可。

#### 5.3.5 ignore

Helm会将templates目录下所有yaml文件都作为K8S资源文件提交至K8S，本例中，deployment 和 hpa 都没有使用。一种方法是将之删除，另一种办法是使用 `.helmignore` 文件。

类似与 `.gitignore`，`.helmignore`用来忽略不需要的文件。

```yaml
# 在文件中补充

deployment.yaml
hpa.yaml
```

在部署时，helm 会忽略ignore 的文件。

#### 5.3.5 部署

使用 helm 部署时，会引入一个新的概念：Release。
由于Helm Chart 是一个资源包文件，采用了模板化的手段，很容易使用不同配置数据部署多个实例，每一个部署的实例，都是一个Release。Release时指定的名称，用于识别不同的实例。

如使用名称 my 来部署例子：
```
$ helm install my ./nginx-sts
NAME: my
LAST DEPLOYED: Sat Jan 14 19:33:36 2023
NAMESPACE: default
STATUS: deployed
REVISION: 1
NOTES:
1. Get the application URL by running these commands:
  http://s1.example.net/
  http://*.example.net/nfs

$ helm list
NAME    NAMESPACE       REVISION        UPDATED                                 STATUS          CHART           APP VERSION
my      default         1               2023-01-14 19:33:36.628034145 +0800 CST deployed        nginx-sts-0.1.0 1.16.0
```

看一下 my 的资源：
```
$ kubectl get all -l helm.sh/chart=nginx-sts-0.1.0
NAME                   TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)   AGE
service/my-nginx-sts   ClusterIP   10.99.27.212   <none>        80/TCP    12m

NAME                            READY   AGE
statefulset.apps/my-nginx-sts   3/3     12m
```
使用 label `helm.sh/chart=nginx-sts-0.1.0` 来筛选，。
注意发布后的资源名称变成了 `my-nginx-sts`，相当于 release 和 chart 名字的组合。这是 Helm 标准模板的写法。当然可以按照自己的需求进行修改。但标准的做法是一种很好的实践。

Helm 可以对 release 进行管理，包括：install、delete、upgrade。

可以查看 helm 管理的资源信息：
```
$ kubectl get svc/my-nginx-sts -o jsonpath="{.metadata.managedFields}" | jq
```
```json
[
  {
    "apiVersion": "v1",
    "fieldsType": "FieldsV1",
    "fieldsV1": {
      "f:metadata": {
        "f:annotations": {
          ".": {},
          "f:meta.helm.sh/release-name": {},
          "f:meta.helm.sh/release-namespace": {}
        },
        "f:labels": {
          ".": {},
          "f:app.kubernetes.io/managed-by": {},
          "f:app.kubernetes.ioa/managed-by": {},
          "f:app/instance": {},
          "f:app/name": {},
          "f:app/version": {},
          "f:helm.sh/chart": {}
        }
      }
      // ...
]      
```
资源的 managedFields 包含了 Helm 管理的 注解、标签等信息。Helm通过这些标签可以追溯Release的资源。

#### 5.4 调试及其他

在编写 Chart 过程中，注意使用增量方式进行测试，避免出现 YAML 格式问题。测试方式为：
```
$ helm lint nginx-sts
==> Linting nginx-sts
[INFO] Chart.yaml: icon is recommended

1 chart(s) linted, 0 chart(s) failed
# 或
$ helm install --dryrun <release> <chart>
```
`dryrun` 不会真正的向 K8S 发布资源，只是会进行K8S资源的语法检查，错误信息会提示到具体的模板行，根据这一信息可以进行修改。

还可以使用：
```
$ helm template --dryrun <release> <chart> 
```
这将输出模板渲染结果。将其保存后可以检查错误信息。

当安装后也可以从K8S 获取资源信息，如：
```
helm get manifest <release Name>
```

helm 使用 kubectl 相同的 `.kube/config` 环境配置。

> TODO: Helm 官网信息完备，本部分介绍的不充分(比如：文件处理)。

## 6. 监控

### 6.1 监控服务概况

系统监控通用架构是采用下述组件架构：
```mermaid 
graph BT 
  c((Collector))
  s[Monitor-TSDB]
  ui[Visualization UI]
  a[Alert]

  c -- Push/Pull --> s
  ui -.-> s
  a -.-> s
```
各组件包括：
* Collector: 采集器，部署在目标上，收集监视数据(metrics)
* Monitor：监视服务，从Collector抓取metrics数据(或Collector推送)，保存在 TSDB中。
* Visualization: 监视metric的可视化。
* Alert: 告警，配置告警规则，并可推送告警信息至外部。

流行的K8S的监控架构也是如此：
* Collector: cAdvisor，采集节点及容器的metric。
* Monitor: 自然是 Prometheus。
* 可视化：Granfana。
* Alert：Prometheus自带AlertManager。

### 6.2 监控方案 

#### 6.2.1 cAdvidor

cAdvisor 是google提供的容器指标采集程序。K8S已经将其集成在Kubelet服务中，也就是说，不在需要单独安装cAdvisor。

cAdvisor通过api-server对外提供metrics，当然支持Prometheus格式的metrics。

K8S的cAdvisor接口集成至核心api的node资源中，通过访问api-server即可得到节点和容器的metrics。
```
$ kubectl get --raw /api/v1/nodes/minikube/proxy/metrics/cadvisor  | grep my-nginx-sts | grep cpu_load | tail -2
container_cpu_load_average_10s{container="nginx-sts",id="/docker/f89bc797ed5cb3cef55e14974c38e8d01609deed0c0df68c2368f7bc4ff19f8d/kubepods/besteffort/pod61ff6ed8-6cc5-4232-8733-1cc3e1d7c601/d5a3babf817595d825e53f0090e9f42541d67dfec47f1027d41ee45018d27d37",image="sha256:ae893c58d83fe2bd391fbec97f5576c9a34fea55b4ee9daf15feb9620b14b226",name="k8s_nginx-sts_my-nginx-sts-2_default_61ff6ed8-6cc5-4232-8733-1cc3e1d7c601_0",namespace="default",pod="my-nginx-sts-2"} 0 1673786242701
container_cpu_load_average_10s{container="nginx-sts",id="/kubepods/besteffort/pod61ff6ed8-6cc5-4232-8733-1cc3e1d7c601/d5a3babf817595d825e53f0090e9f42541d67dfec47f1027d41ee45018d27d37",image="sha256:ae893c58d83fe2bd391fbec97f5576c9a34fea55b4ee9daf15feb9620b14b226",name="k8s_nginx-sts_my-nginx-sts-2_default_61ff6ed8-6cc5-4232-8733-1cc3e1d7c601_0",namespace="default",pod="my-nginx-sts-2"} 0 1673786233004
```
上述命令可以看到 POD my-nginx-sts-2的cpu使用情况， 
使用kubectl访问api-server 即可得到metric数据, 其URL为：`/api/v1/nodes/<node name>/proxy/metrics/cadvisor`。
还可以通过 kubelet 端口访问，`/metrics/cadvisor`

#### 6.2.2 kube-state-metrics 

cadvisor 暴露的是 容器相关的性能指标，而非 K8S 资源 ，如: Deployment/Statefullset 等状态是无法得到的，作为补充，`kue-state-metrics` 会更为方便，

#### 6.2.3 Prometheus

Prometheus是目前主流的 监控系统 TSBD。它具备水平扩展的能力，大量的exportor可以深入监视不同的应用系统。

Prometheus定时抓取数据，并提供PromQL进行聚合查询。部署Prometheus的重点是如何采集数据。
Prometheus通过配置http/s端点来抓取数据，配置内容称为 scrape_config，如：
```yaml
# The job name assigned to scraped metrics by default.
job_name: <job_name>

static_config:
  # The targets specified by the static config.
  targets:
    [ - '<host>' ]
```
static_config可以配置静态的(不变的)scrape endpiont。而在K8S中，绝大部分Metrics是从Pod暴露的，而Pod的IP是随机分配的，(虽然 StatefullSet DNS是稳定的，但并不能涵盖所有的需求)。

因此，Prometheus 提供了动态的配置机制，称之为 Service Discovery，简称SD，用来支持动态配置。特别针对 K8S 提供了 kubernetes_sd_configs 。如：
```yaml
job_name: "kubernetes-cadvisor"
kubernetes_sd_configs:
  role: node
scheme: https

metrics_path: /metrics/cadvisor

```
这是选择了 node kubelet 的 metric ，可以使用 `/metrics`或 `/metrics/cadvisor`来抓取数据。

也可以选择某些POD的端口进行监控。这时需要使用`role: pod`。

#### 6.2.4 Grafana

Grafana 与 Prometheus 的集成是成熟的方案。使用Grafana 通过 PromQL 创建监视可视化界面, Grafana 提供了大量的模板，稍加修改即可满足需求。

#### 6.2.5 Prometheus Operator

Prometheus Operator 是 为简化Prometheus部署、配置而产生的开源项目，Prometheus的配置文件很复杂，Prometheus Operator 利用K8S 的CRD声明和发布Prometheus配置方案，并提供了很多便利的手段。比如：Operator只需要声明一个 PodMinitor 就可以 自动生成并配置 对特定Pod endpoint metric 抓取。而无需考虑如何捕获Pod端点信息，如何将其加入 Prometheus scrape config 等。

#### 6.2.6 小结

为更深入了解 K8S metric接口 和 Prometheus 的配置机制，将先从不借助 Operator手动配置 Prometheus 开始。此后再介绍 Operator 的原理(K8S CRD)和部署示例。

最终的部署会包括对 K8S 各服务组件的监视(/metrics和 /metrics/cadvisor)，K8S资源监视(kube-state-metrics)，应用metrics监视(nginx sidecard模式)，以及 Prometheus Operator 部署方案。

### 6.3 手动部署 Prometheus 

Prometheus 首先是一个 TSDB 时序数据库，它需要持久化数据存储，因此，如果要部署多个实例实现高可用，应考虑使用StatefulSet(也可以使用)。

对K8S 组件的监视，需要了解组件暴露的 endpoint 并将其配置在 Prometheus中。

#### 6.3.1 编制 Prometheus Statefulset

利用之前的知识，编辑一个 Statefulset YAML如下：

```yaml
# samples/monitor/prometheus-sts.yml
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: prometheus
  labels:
    app/name: prometheus
spec:
  replicas: 1
  selector:
    matchLabels:
      app/name: prometheus
  serviceName: prom-service
  # ... 
```
replicas 可以设定为`2`实现高可用。

container 设置，使用了 readiness和liveness：
```yaml
      containers:
      - name: prometheus
        image: prom/prometheus:v2.41.0
        ports:
        - containerPort: 9090
        livenessProbe: 
          httpGet: 
            path: /-/healthy
            port: 9090 
          initialDelaySeconds: 2
          periodSeconds: 30
        readinessProbe:
          httpGet:
            path: /-/ready
            port: 9090
        volumeMounts:
        - mountPath: "/prometheus"
          name: nfs-prom
```
volume 使用了 NFS-subdir 的 vct：
```yaml
  volumeClaimTemplates:
  - metadata:
      name: nfs-prom
    spec:
      accessModes: [ "ReadWriteOnce" ]
      storageClassName: nfs-client
      resources:
        requests:
          storage: 400Mi
```
另需要创建一个prom-service：
```yaml
# samples/monitor/prometheus-svc.yaml
apiVersion: v1
kind: Service
metadata: 
  name: prom-service
spec:
  type: NodePort
  selector:
    app/name: prometheus 
  ports: 
    - protocol: TCP
      port: 9090
      nodePort: 31090
      targetPort: 9090
```
使用kubectl 部署即可。`kubectl  apply -f samples/monitor/`

#### 6.3.2 port-forward 

开发阶段可以使用 port-forward 命令针对Pod/服务进行端口转发，方便调试：
```
$ kubectl port-forward svc/prom-service 9090:9090
Forwarding from 127.0.0.1:9090 -> 9090
Forwarding from [::1]:9090 -> 9090
```
从 localhost:9090可访问到prom-service服务. 从`Status-targets`中可以看到 prometheus 实例已经启动了。

#### 6.3.3 访问 Kubelet metrics 

##### 6.3.3.1 外部访问

kubelet metrics 有两种途径可以访问，第一是从api-server代理，访问：
```
# kubelet 
https://<api-server:port>/api/v1/nodes/minikube/proxy/metrics
# 节点 cadvisor 
https://<api-server:port>/api/v1/nodes/minikube/proxy/metrics/cadvisor
```
另一个途径是访问kubelet 端口。
```
https://<node:port>/metrics
https://<node:port>/metrics/advisor
```
首先尝试 api-server，为简化HTTPS认证，可使用 kubectl proxy命令代理一个http端口。访问HTTPS的话，需要客户端证书。使用 kubectl 可以查看到证书，在 3. 安全 部分已经说明了。
```
$ kubectl config view
apiVersion: v1
clusters:
- cluster:
    certificate-authority: ~/.minikube/ca.crt
    extensions:
    - extension:
        last-update: Sat, 14 Jan 2023 18:52:52 CST
        provider: minikube.sigs.k8s.io
        version: v1.28.0
      name: cluster_info
    server: https://127.0.0.1:49154
  name: minikube
  ...
  - name: minikube
  user:
    client-certificate: ~/.minikube/profiles/minikube/client.crt
    client-key: ~/.minikube/profiles/minikube/client.key
```
api-server 地址和用户证书、密钥文件都可以看到。使用 curl 可以访问：
```
$ curl -k https://127.0.0.1:49154/api/v1/nodes/minikube/proxy/metrics/cadvisor \
  --cert ~/.minikube/profiles/minikube/client.crt \
  --key ~/.minikube/profiles/minikube/client.key
```
这里使用`-k`跳过服务器证书认证环节。如需认证可指定 ca : `--cacert ~/.minikube/ca.crt`。

非 lolcalhost 地址可以使用命令查看：
```
$ kubectl describe svc/kubernetes
Name:              kubernetes
Namespace:         default
Labels:            component=apiserver
                   provider=kubernetes
Annotations:       <none>
Selector:          <none>
Type:              ClusterIP
IP Family Policy:  SingleStack
IP Families:       IPv4
IP:                10.96.0.1
IPs:               10.96.0.1
Port:              https  443/TCP
TargetPort:        8443/TCP
Endpoints:         192.168.49.2:8443
Session Affinity:  None
Events:            <none>
```
集群外可访问`192.168.49.2:8443`，集群内访问：`10.96.0.1:443` 。

kubelet 运行在每个节点上，默认使用 10250端口提供服务，可以通过节点IP和该端口访问，客户端证书与上文一致:
```
curl -k https://192.168.49.2:10250/metrics \
  --cert ~/.minikube/profiles/minikube/client.crt \
  --key ~/.minikube/profiles/minikube/client.key
```

##### 6.3.3.2 Pod 内访问

另一种安全认证方式是使用token，将token添加在HTTP-HEADER中。

在Pod中无法直接访问客户端证书，代之以 ServiceAccount 的 Token。
官方的例子如下：
```sh
# 指向内部 API 服务器的主机名
APISERVER=https://kubernetes.default.svc

# 服务账号令牌的路径
SERVICEACCOUNT=/var/run/secrets/kubernetes.io/serviceaccount

# 读取 Pod 的名字空间
NAMESPACE=$(cat ${SERVICEACCOUNT}/namespace)

# 读取服务账号的持有者令牌
TOKEN=$(cat ${SERVICEACCOUNT}/token)

# 引用内部证书机构（CA）
CACERT=${SERVICEACCOUNT}/ca.crt

# 使用令牌访问 API
curl --cacert ${CACERT} --header "Authorization: Bearer ${TOKEN}" -X GET ${APISERVER}/api
```
当Pod启动时，会将ServiceAccount 的令牌 和 CA 证书挂载在 `/var/run/secrets/kubernetes.io/serviceaccount`目录下。通过 https 头中添加认证Token来访问api-server。

#### 6.3.4 配置 prometheus.yaml

只需要将上述地址和认证信息配置在 prometheus 中即可实现监控。为此，修改 Prometheus默认的配置文件/etc/prometheus/prometheus.yml。
```
# 类似于 docker cp ，从 pod 复制文件。
$ kubectl cp prometheus-0:/etc/prometheus/prometheus.yml samples/monitor/prometheus.yml
```
编辑 配置文件：
```yaml
  - job_name: "kubelet"
    static_configs:
      - targets: 
        - "192.168.49.2:10250"
        - "192.168.49.3:10250"
    scheme: https
    metrics_path: /metrics
    tls_config:
      ca_file: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt 
      # cert_file: /var/lib/kubelet/pki/kubelet-client-current.pem
      # key_file: /var/lib/kubelet/pki/kubelet-client-current.pem
      # 相当于 curl -k 参数
      insecure_skip_verify: true
    authorization:
      type: Bearer
      credentials_file: /var/run/secrets/kubernetes.io/serviceaccount/token
```
使用 `insecure_skip_verify: true` 来跳过对CA的验证，因为CA签发使用的是域名，并非节点IP。

#### 6.3.5 配置RBAC权限
之前部署的prometheus使用ServiceAccount default并没有访问节点API权限，需要创建新的账户并分配权限。为此创建一个RBAC文件(为方便起见，把ClusterRole ClusterRoleBinding ServiceAccount 写在一个文件中)。

由于节点(nodes)属于集群资源，因此需要使用ClusterRole。
```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole 
metadata:
  name: prometheus
rules:
- apiGroups: [""]
  resources:
  - nodes
  - nodes/metrics
  - nodes/proxy
  verbs:
  - "get"
  - "list"
  - "watch"
- nonResourceURLs:
  - "/metrics"
  - "/metrics/cadvisor"
  verbs: 
  - get
```
由于 `/metrics`不属于资源，因此需要使用 `nonResourceURLs`声明。
`nodes/proxy`用于访问api-server代理时。

还需要将 Service Account 指定到 prometheus statefulSet中。
```yaml
    spec:
      serviceAccountName: prometheus
```
apply 上述资源。

#### 6.3.6 配置文件刷新

Prometheus 可以通过两种方式热重启，重新加载配置文件。
1. 使用 `--web.enable-lifecycle=true`启动prometheus，可访问POST /-/reload热重启。
2. 发送signal HUP。`kill -HUP <pid>`。

本例使用signal方式:
```
$ kubectl cp samples/monitor/prometheus.yml prometheus-0:/etc/prometheus/prometheus.yml
$ kubectl exec prometheus-0 -- kill -HUP 1
```
> K8S 容器 pid 是1。可通过ps 命令查看。

curl访问prometheus api:
```
$ curl 192.168.49.2:31090/api/v1/targets | jq
```
```json
{
  "status": "success",
  "data": {
    "activeTargets": [
      {
        "labels": {
          "instance": "192.168.49.3:10250",
          "job": "kubelet"
        },
        "scrapePool": "kubelet",
        "scrapeUrl": "https://192.168.49.3:10250/metrics",
        "globalUrl": "https://192.168.49.3:10250/metrics",
        "lastError": "",
        "lastScrape": "2023-01-23T11:36:06.924859999Z",
        "lastScrapeDuration": 0.048961602,
        "health": "up",
        "scrapeInterval": "15s",
        "scrapeTimeout": "10s"
      },
      {
        "labels": {
          "instance": "192.168.49.2:10250",
          "job": "kubelet"
        },
        "scrapePool": "kubelet",
        "scrapeUrl": "https://192.168.49.2:10250/metrics",
        "globalUrl": "https://192.168.49.2:10250/metrics",
        "lastError": "",
        "lastScrape": "2023-01-23T11:36:04.687527635Z",
        "lastScrapeDuration": 0.092662603,
        "health": "up",
        "scrapeInterval": "15s",
        "scrapeTimeout": "10s"
      },
      { 
        "labels": {
          "instance": "localhost:9090",
          "job": "prometheus"
        }
      }
    ],
    "droppedTargets": []
  }
}
```

抓取Kubelet metrics 服务已经生效。

#### 6.3.7 使用ConfigMap

可以使用configMap作为配置文件，这样启动时会自动挂载该文件。

```
$ kubectl create cm prometheus-yaml --from-file=samples/monitor/
prometheus.yml
configmap/prometheus-yaml created

$ kubectl get cm prometheus-yaml -o yaml
apiVersion: v1
data:
  prometheus.yml: "# my global config\nglobal:\n  scrape_interval: 15s # Set the scrape
    interval to every 15 seconds. Default is every 1 minute.\n  evaluation_interval:
    15s # Evaluate rules every 15 seconds. The default is every 1 minute.\n  # scrape_timeout
    is set to the global default (10s).\n\n# Alertmanager configuration\nalerting:\n
    ....
kind: ConfigMap
metadata:
  creationTimestamp: "2023-01-24T03:25:10Z"
  name: promtheus-yaml
  namespace: default
  resourceVersion: "1932188"
  uid: 9cd346ee-3249-42d9-b020-d5a6ce1331f4
```

编辑prometheus-sts 添加ConfigMap:
```yaml
    spec:
      containers:
      - name: prometheus
        # ....
        volumeMounts:
        - mountPath: "/prometheus"
          name: nfs-prom
        - mountPath: "/etc/prometheus"
          name: config-yaml
      volumes:
      - name: config-yaml
        configMap:
          name: prometheus-yaml
          items:
          - key: prometheus.yml
            path: prometheus.yml
```
将configMap的 prometheus.yml mount 到 /etc/prometheus目录下。这样就可以通过修改configMap来刷新配置文件。

### 6.4 使用`kubernetes_sd_config`

Prometheus 对 K8S 和 Dockers等容器类编排工具都提供了动态配置的功能。

`kubernetes_sd_config`可以通过简单配置来实现动态发现K8S节点、服务、Pod等ip地址的能力(`sd`是`Service Discovery` 的缩写)。

#### 6.4.1 role = node

使用不同的`role`来引用K8S 的节点、服务、POD，之前的配置文件可以简化为：
```yaml
  - job_name: "kubelet"
    kubernetes_sd_config:
      - role: node  
    scheme: https
    metrics_path: /metrics
    tls_config:
      ca_file: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt 
    # 相当于 curl -k 参数
      insecure_skip_verify: true
    authorization:
      type: Bearer
      credentials_file: /var/run/secrets/kubernetes.io/serviceaccount/token
```
注意，把 `static_configs targets` 修改为 `kubernetes_sd_config`，动态产生 targets。其他认证等信息仍保持不变。

更新该configMap：
```
$ kubectl delete  cm prometheus-yaml
$ kubectl create cm prometheus-yaml --from-file=prometheus.yml=samples/monitor/prometheus-sd.yml
$ kubectl exec prometheus-0 -- kill -HUP 1
$ kubectl logs prometheus-0
ts=2023-01-24T10:03:02.691Z caller=main.go:1234 level=info msg="Completed loading of configuration file" filename=/etc/prometheus/prometheus.yml totalDuration=17.6796ms db_storage=3.2µs remote_storage=3.6µs web_handler=1.1µs query_engine=1.9µs scrape=16.117ms scrape_sd=683.4µs notify=25.9µs notify_sd=16.3µs rules=2.1µs tracing=9.2µs

$ curl 192.168.49.2:31090/api/v1/targets | jq
```

#### 6.4.2 role = pod

发现POD目标时，可指定 role : pod。sd_config会返回符合条件的pod地址和信息。

此时Prometheus 需要具备 对 pod 的访问权限，因此，需在prometheus-rbac.yaml 添加：
```yaml
rules:
- apiGroups: [""]
  resources:
  - nodes
  - nodes/metrics
  - nodes/proxy
  - pods
  verbs:
  - "get"
  - "list"
  - "watch"
```
本例来访问 prometheus:
```yaml
  - job_name: "prom-test"
    kubernetes_sd_configs:
      - role: pod
        selectors:
          - role: pod
            label: app/name=prometheus
```
注意，这里用了 `selectors label` 来选择 一组 pod。其方式与K8S的标签选择相同。

使用 curl 访问 targets后，可得到prom-test的信息：
```json
      {
        "discoveredLabels": {
          "__address__": "10.244.1.7:9090",
          "__meta_kubernetes_namespace": "default",
          "__meta_kubernetes_pod_container_image": "prom/prometheus:v2.41.0",
          "__meta_kubernetes_pod_container_init": "false",
          "__meta_kubernetes_pod_container_name": "prometheus",
          "__meta_kubernetes_pod_container_port_number": "9090",
          "__meta_kubernetes_pod_container_port_protocol": "TCP",
          "__meta_kubernetes_pod_controller_kind": "StatefulSet",
          "__meta_kubernetes_pod_controller_name": "prometheus",
          "__meta_kubernetes_pod_host_ip": "192.168.49.3",
          "__meta_kubernetes_pod_ip": "10.244.1.7",
          "__meta_kubernetes_pod_label_app_name": "prometheus",
          "__meta_kubernetes_pod_label_controller_revision_hash": "prometheus-755bccf47f",
          "__meta_kubernetes_pod_label_statefulset_kubernetes_io_pod_name": "prometheus-0",
          "__meta_kubernetes_pod_labelpresent_app_name": "true",
          "__meta_kubernetes_pod_labelpresent_controller_revision_hash": "true",
          "__meta_kubernetes_pod_labelpresent_statefulset_kubernetes_io_pod_name": "true",
          "__meta_kubernetes_pod_name": "prometheus-0",
          "__meta_kubernetes_pod_node_name": "minikube-m02",
          "__meta_kubernetes_pod_phase": "Running",
          "__meta_kubernetes_pod_ready": "true",
          "__meta_kubernetes_pod_uid": "13ff59c3-e089-48bb-9939-c4aef51050bc",
          "__metrics_path__": "/metrics",
          "__scheme__": "http",
          "__scrape_interval__": "15s",
          "__scrape_timeout__": "10s",
          "job": "prom-test"
        },
        "labels": {
          "instance": "10.244.1.7:9090",
          "job": "prom-test"
        },
        "scrapePool": "prom-test",
        "scrapeUrl": "http://10.244.1.7:9090/metrics",
        "globalUrl": "http://10.244.1.7:9090/metrics",
        "lastError": "",
        "lastScrape": "2023-01-24T12:02:57.253072866Z",
        "lastScrapeDuration": 0.046549599,
        "health": "up",
        "scrapeInterval": "15s",
        "scrapeTimeout": "10s"
      }
```
服务发现生成抓取URL： `http://10.244.1.7:9090/metrics`，使用了 pod IP + containerPort + /metrics 组合而成。

在discoverLabels中，包含一组 `__meta_kuberbetes_pod_` 开头的 标签，这些标签包括了 pod 的各项信息，可以使用这些信息来进行 relabling。

#### 6.4.3 role = service 

与 pod 类似，这里不进行演示。
需增加权限 services 。

#### 6.4.5 配置监视 nginx 

Prometheus支持使用 Exporter 获取nginx的监视数据。最简单的 exportor 是 `nginx/nginx-prometheus-exporter`。exporter需要nginx stub_status模块支持。

nginx stub_status 模块提供连接数等简要指标信息。需要在 nginx 配置中添加:
```
location /nginx_status{
  stub_status;
}
```
因此，需要为nginx镜像配置一个 ConfigMap。

exporter可以使用单独的容器运行。本例中利用K8S Pod 的sidecard功能，即：在一个pod中部署多个容器，这些镜像之间会共享网络和存储。

Pod template 中 conatiners 是一个数组，因此，在其中添加exporter镜像即可。

本例基于 helm 进行修改。

##### 6.4.5.1 添加values.yaml配置

在 values.yaml中添加关于 exporter 的配置项：
```yaml
exporter:
  repository: nginx/nginx-prometheus-exporter
  pullPolicy: IfNotPresent
  # Overrides the image tag whose default is the chart appVersion.
  tag: "0.11"
  port: 9113
  uri: "/nginx_status"
```
这里定义了 image，端口 以及 stub_status 开放的 uri。

##### 6.4.5.2 添加 container 

在 statefulset.yaml中添加 exporter container:
```yaml
        - name: {{ .Chart.Name }}-exporter
          securityContext:
            {{- toYaml .Values.securityContext | nindent 12 }}
          image: {{ .Values.exporter.repository }}:{{ .Values.exporter.tag | default "latest" }}
          imagePullPolicy: {{ .Values.exporter.pullPolicy }}
          args:
            - -nginx.scrape-uri=http://localhost:{{ .Values.service.port }}{{ .Values.exporter.uri | default "/nginx_status" }}
          ports:
            - name: metrics
              containerPort: {{ .Values.exporter.port }}
              protocol: TCP
          livenessProbe:
            httpGet:
              path: /
              port: metrics
          resources:
            {{- toYaml .Values.resources | nindent 12 }}
```
container名字使用了 `{{ .Chart.Name }}-exporter`，本例中为 `nginx-sts-exporter`。

image 部分引用了 `.Values.exporter` 的配置。

exporter的启动参数中，添加 `-nginx.scrape-uri`，注意，多个container之间访问可使用localhost。此配置的URI为：`http://localhost:80/nginx_status`。


##### 6.4.5.3 添加 ConfigMap

把nginx配置文件复制出来，编写 ConfigMap。这里使用了`range`循环，文件名定义在 configMap.files中：
```yaml
configMap:
  create: true
  files:
    - default.conf
  mountPath: /etc/nginx/conf.d
``` 
多个文件可以挂载在一个目录下，本例挂载在 /etc/nginx/conf.d目录下。

使用该信息可以创建 CM:
```yaml
data:
{{- range .Values.configMap.files }}
{{ ( $.Files.Glob . ).AsConfig | indent 2 }}
{{- end }}
{{- end -}}
```
这里使用了 Files 获取文件内容，AsConfig函数，将其保存成 `文件名 : 文件内容` 的形式。

##### 6.4.5.4 mount ConfigMap

在 nginx 容器配置中增加 volumes 和 mount 信息：
```yaml
      volumes:
      - name: {{ .Chart.Name }}-cm
        configMap: 
          name: {{ include "nginx-sts.fullname" . }}
          items: 
          {{- range .Values.configMap.files }}
          - key: {{ . }}
            path: {{ . }}
          {{- end }}
```
> key 名称 即 path 文件名。

```yaml
          volumeMounts:
          {{- if .Values.configMap.create }}
          - mountPath: {{ .Values.configMap.mountPath }}
            name: {{ .Chart.Name }}-cm
          {{- end }}
```


##### 6.4.5.5 更新验证

至此，配置完成，使用 helm upgrade 更新 release即可。
```
$ cd helm 
$ helm upgrade my nginx-sts 
Release "my" has been upgraded. Happy Helming!
NAME: my
LAST DEPLOYED: Wed Jan 25 14:58:16 2023
NAMESPACE: default
STATUS: deployed
REVISION: 5
NOTES:
1. Get the application URL by running these commands:
  http://s1.example.net/
  http://*.example.net/nfs
```

执行curl检查配置是否正确：
```
$ kubectl exec my-nginx-sts-0 -- curl localhost:9113/metrics
Defaulted container "nginx-sts" out of: nginx-sts, nginx-sts-exporter
# HELP nginx_connections_accepted Accepted client connections
# TYPE nginx_connections_accepted counter
nginx_connections_accepted 508
# HELP nginx_connections_active Active client connections
# TYPE nginx_connections_active gauge
nginx_connections_active 1
# HELP nginx_connections_handled Handled client connections
# TYPE nginx_connections_handled counter
...

$ kubectl exec my-nginx-sts-0 -- curl localhost:80/nginx_status
Defaulted container "nginx-sts" out of: nginx-sts, nginx-sts-exporter
Active connections: 1
server accepts handled requests
 512 512 513
Reading: 0 Writing: 1 Waiting: 0

```

可见，exporter已经可以工作。

##### 6.4.5.6 配置 prometheus 

这里的重点是筛选出exporter 容器，跳过 nginx 容器，以及如何定义端口号。
exporter使用 9113 端口，当然可以使用 relabel 直接修改 `__address__`。

首先通过 label selector 来选择 nginx-sts 的容器：
```yaml
  - job_name: "nginx-exporter"
    kubernetes_sd_configs:
      - role: pod 
        selectors:
          - role: pod 
            label: app/name=nginx-sts
```

再通过 port name 是否是 metric 来判断该容器是否需要保留。如：
```yaml
  relabel_configs:
  - source_labels: [__meta_kubernetes_pod_container_port_name]
    action: keep 
    regex: metrics
```
注意，仅仅保留 container_port_name == metrics 的 conatainer 和 端口号，此时生成的 URL 就是 `<pod_ip>:<pod_container_port_number>`。本例中就是 `<pod_id>:9113` 。

更新该配置，并热启动 prometheus 。
访问 prometheus /api/v1/targets 可以看到已经发现了三个exporter实例。

### 6.5 Alertmanager 

Prometheus 使用 AlertRules 和 alert manager 配置并管理告警信息。Alertmanager 可以将告警进行分组、抑制、静默操作，并可将告警信息Push到recievers（如：邮件SMTP，Webhook，微信，钉钉）。

#### 6.5.1 运行 Alertmanager

简便起见，直接运行一个 alertmanager :
```
# 类似于 docker run 启动POD。
$ kubectl run alertmanager --image=prom/alertmanager:v0.25.0 --port=9030
pod/alertmanager created

# 为其打上标签
$ kubectl label pod/alertmanager app/name=alertmanager
pod/alertmanager labeled

$ kubectl get pod -L app/name
NAME                                                  READY   STATUS    RESTARTS        AGE     NAME
alertmanager                                          1/1     Running   0               14h     alertmanager
```
> 使用 `-L <label name>` 可以显示 label 值

#### 6.5.2 配置 prometheus 连接 alertmanager

在 Prometheus 配置中 修改 alertmanager ：
```yaml
    # Alertmanager configuration
    alerting:
      alertmanagers:
        - kubernetes_sd_configs:
          - role: pod
            selectors:
              - role: pod
                label: app/name=alertmanager
        # - static_configs:
        #     - targets:
        #       # - alertmanager:9093
```
更新 ConfigMap 并热启动 prometheus。
> ConfigMap更新后不会立即挂载到 Pod，K8S 使用 watch 监视 资源变化，这中间的间隔时间默认是2分钟。
> 可以通过观察 Pod 中文件时间来确认是否更新了配置： 
```
$ kubectl exec prometheus-0 -- ls -la /etc/prometheus
total 12
drwxrwxrwx    3 root     root          4096 Jan 26 04:49 .
drwxr-xr-x    1 root     root          4096 Jan 24 11:43 ..
drwxr-xr-x    2 root     root          4096 Jan 26 04:49 ..2023_01_26_04_49_45.2407579084
lrwxrwxrwx    1 root     root            32 Jan 26 04:49 ..data -> ..2023_01_26_04_49_45.2407579084
lrwxrwxrwx    1 root     root            21 Jan 24 11:43 prometheus.yml -> ..data/prometheus.yml
# 文件名的时间，是ConfigMap 更新的时间。
```

使用 curl 访问 prometheus /api/v1/alertmanagers :
```
$ curl 192.168.49.2:31090/api/v1/alertmanagers | jq 
```
```json
{
  "status": "success",
  "data": {
    "activeAlertmanagers": [
      {
        "url": "http://10.244.1.3:9030/api/v2/alerts"
      }
    ],
    "droppedAlertmanagers": []
  }
}
```
可见该alertmanager已经被prometheus发现了。

#### 6.5.3 简单的告警规则

Prometheus告警规则设置使用单独的文件保存，修改prometheus 配置中的 rules部分：
```yaml
  rule_files:
  - "alert-rules.yml"
```

在 alert-rules.yml 中编制简单的告警规则：
```yaml
# alert-rules.yml: |
    groups: 
    - name: example 
      rules:
      # alert 表示这是一个告警规则，另一类型是 record rule。
      - alert: nginx instance down 
      # 检查 nginx_up 数量是否小于 3.
      # 小于3表示 运行 nginx 的实例小于3个。
        expr: sum (nginx_up)  by (job) < 3
      # 此告警触发后，处于Pending 状态，如 30s 后仍存在，则 触发告警(fire)。
        for: 30s 
        labels:
          severity: warn
        annotations:
          summary: "nginx instance down"
          desription: "Expect nginx nstances is 3, acutal instances is {{ $value }}"
```

将上述信息写入 configMap，并在 prometheus-sts.yaml 中添加 ：
```yaml
      - name: config-yaml
        configMap:
          name: prometheus-yaml
          items:
          - key: prometheus.yml
            path: prometheus.yml
          - key: alert-rules.yml
            path: alert-rules.yml
```

kubectl apply ，等待 config map 重新挂载后，使用 kill -HUP 1 热重启 prometheus 。
```
$ kubectl get sts/my-nginx-sts
NAME           READY   AGE
my-nginx-sts   3/3     12d

# 当前是 3个实例，将其收缩至 2 个
$ kubectl scale sts/my-nginx-sts --replicas=2
statefulset.apps/my-nginx-sts scaled
```
此时实例数变为 2 个。获取 prometheus 的 alerts 信息：
```
$ curl 192.168.49.2:31090/api/v1/alerts | jq
```
```json
{
  "status": "success",
  "data": {
    "alerts": [
      {
        "labels": {
          "alertname": "nginx instance down",
          "job": "nginx-exporter",
          "severity": "warn"
        },
        "annotations": {
          "desription": "Expect nginx nstances is 3, acutal instances is 2",
          "summary": "nginx instance down"
        },
        "state": "firing",
        "activeAt": "2023-01-26T11:46:34.182414007Z",
        "value": "2e+00"
      }
    ]
  }
}
```
注意状态是 pending。等待 30 秒后， 再次查看alerts: `"state": "firing",` 此时该 告警 已经触发。将其replicas 改回 3 个 即可恢复该告警。
```
$ kubectl scale sts/my-nginx-sts --replicas=3
statefulset.apps/my-nginx-sts scaled

$ curl 192.168.49.2:31090/api/v1/alerts | jq
```
```json
{
  "status": "success",
  "data": {
    "alerts": []
  }
}
```
可见该告警已经被取消。
> prometheus 对 rules 的计算间隔时间默认是：`evaluation_interval` = 1m，（也可以将其修改为较短的时间，如：10s）。因此，等待最长的时间是 `for`时间和 eval 时间 中较大的那个。

#### 6.5.4 receiver 

。。。

### 6.6 Grafana 

Grafana OpenSource 是开源的 监控数据 可视化系统。Grafana 的特点是可以对接多种数据源，兼容流行的 TSDB如prometheues, graphite等，使用灵活的数据查询语句，配合类型多样的可视化界面及操作，可以实现监视数据的接入、可视化、告警等处理。

Grafana 最大的优势在于其社区提供的大量仪表盘(Dashboard)模板，可以方便的创建各种服务监视界面。比如：想监视 K8S 集群，直接搜索、安装、展示 相应 仪表盘即可。 这种方式本质上是深度绑定了数据源和UI。

Grafana 的定制能力同样值得称道，社区预制的仪表盘，本质是一组 JSON 文件(及相应的资源)，这些都允许用户自行编辑、修改。而其 界面上也提供了 配置修改的编辑器。这样就极大方便了用户，降低了使用门槛。

另一特点是 grafana 已经形成了完备的云平台微服务的监控服务栈，这些产品可以快速部署并天然集成在一起，形成整体解决方案，比如：使用 Loki 进行日志归集 和 检索。

Grafana的缺点与Kinbana类似，它的整个UI不能独立运行，不允许嵌套至其他界面中(iframe方式不考虑)。因此，无法集成至其他产品。使其限制在 `管理工具`范畴内。

#### 6.6.1 理解 Grafana 的 概念

Grafana 有两个重要概念：
* 数据源：即监视数据的来源，各类主流TSDB均可作为数据源。
* Dashboard：仪表盘，即从 数据源中选择数据，并进行可视化。

数据源比较好理解，本例使用 prometheus作为数据源。

选择(查询)数据的方法是依赖于数据源的，不同的数据源，采用不同的查询方法，这一点grafana并没有费力气实现数据源之间的接口兼容性，而是 直接使用 数据源自身的查询语言，如，Prometheus 就是用 PQL， MySql 使用 SQL 。当然，为方便使用，grafana 的 数据源插件 会实现一个 数据 explore 和 query editor，可视化的操作数据源，构建查询语句。因此，必须熟悉数据源的查询语言，才能更好的使用它。

Dashboard 仪表盘 是一组 数据查询、可视化 Panel的 集合。Panel 实现数据查询和可视化，Dashboard 为其提供布局，环境参数。比如，数据库监视可能包括：
* 存储
* 内存
* 连接数
* Query 性能
* 索引性能

这些信息分别采用不同的形式显示(Panel)，在界面的位置就由 Dashboard 决定。同时，Dashboard提供全局环境参数，比如：监视的目标数据库 ip 地址或 实例名。

#### 6.6.2 Grafana 存储

Grafana 数据保存在 /var/lib/grafana 。

#### 6.6.3 安装 Grafana

Grafana官网提供了 deployment 样例，直接使用这个样例来部署Grafana：
```
$ kubectl apply -f samples/monitor/grafana.yaml
deployment.apps/grafana created
service/grafana created

$ kubectl describe svc grafana
Name:                     grafana
Namespace:                default
Labels:                   <none>
Annotations:              <none>
Selector:                 app/name=grafana
Type:                     NodePort
IP Family Policy:         SingleStack
IP Families:              IPv4
IP:                       10.111.48.145
IPs:                      10.111.48.145
Port:                     <unset>  3000/TCP
TargetPort:               http-grafana/TCP
NodePort:                 <unset>  31899/TCP
Endpoints:                10.244.1.4:3000
Session Affinity:         None
External Traffic Policy:  Cluster
Events:                   <none>
```

使用 31899 端口访问 Grafana 即可。

#### 6.6.4 配置 prometheus 数据源

登录 Grafana后，选择添加 数据源。类型选择 Prometheus 。由于Prometheus没有配置安全限制，因此，直接使用服务名`http://prom-service:9090`来访问即可。

> 相当于访问 prom-service.svc.cluster.local。

添加后，选择 explore 即可看到 Prometheus 的 Metrics。

为演示 `Dashboard`，可在数据源面板上选择 Dashboard，并选择 `Prometheus 2.0 Stats import`。 

之后，打开 左侧的 Dashboard ，查看仪表盘列表，在其中` General` 文件夹 中 选择 `Prometheus 2.0 Stats` 并打开，立即就可显示 Dashboard 的界面：

![Prometheus Dashboard](img/grafana-prom.png)

Grafana 预制仪表板 的便利性可见一斑。

#### 6.6.5 配置 Dashboard 

配置 dashboard 需要理解 metric 的含义，理解 PromQL 查询语句，选择合适的时间序列，再配置其 可视化 样式。

新建一个Dashboard，并在其中添加一个 Panel。
* 将 Panel Title 命名为 Memory。
* Query 部分 输入：`go_memstats_alloc_bytes{job='kubelet'}` 这会查询出 kubelet 的 内存分配数据。
* Option 的 `legend` 选择 custom 并 输入：`{{instance}}` ，将系列的 标签 显示为 instance label。
* Graph style 选择 Bars 条形图。 
* Gradient mode 选择 Hue，这样会根据不同的数值显示不同的颜色。
* Unit 选择 bytes，即字节。Grafana会根据数据的级别显示不同的单位。
* Stack Series 是指是否堆积。

选择后保存，即可看到Panel 的效果：

![Kubelet Memory](img/panel-mem.png)

Dashboard 可以保存为一个 Json 文件，在 Dashboard 的 JSOM Model 中，展示了全部配置信息。

Dashboard 可以定义 Variable, 变量可以在查询中使用，通常进行选择、过滤。也可以在界面上显示，与用户交互。

将 Kube节点信息，定义一个变量 `nodeName`。Type 为 `Query`，表示从数据源中查询获得变量值清单。
Query 语句 使用 `label_values(kubelet_node_name, node)` 即：从 kubelet_node_name 中获取 标签 `node` 的值，作为变量值。

> label_values 是 Grafana 的 模板函数，并非 Prometheus函数。

定义后，在 Dashboard上可显示 Node Name 下拉列表框，包含三个值：All，minikube, minikube-m02。

下一步将变量与 Panel 查询关联。在Memory Panel 中，修改查询语句，添加标签选择：
`go_memstats_alloc_bytes{job='kubelet', instance='${nodeName}'}` 

NodeName 选择 `minikube` 使用 Query Inspector 按钮来检查 Query 内容：
`Expr: go_memstats_alloc_bytes{job='kubelet', instance='minikube'}`

可见，grafana 将 ${nodeName} 替换为 选中的值。这样，查询结果就仅包含 minikube 的数据。

但选择 `All` 时，会出现No Data，同样使用 Query Inspector 查看：
`expr: go_memstats_alloc_bytes{job='kubelet', instance='(minikube|minikube-m02)'}`

Grafana 默认的 ALL 值 是使用Regex连接全部值。Prometheus中需要使用波浪线`~`指定正则表达式：
`go_memstats_alloc_bytes{job='kubelet', instance=~'(minikube|minikube-m02)'}`

当变量值列表很大时，这种方式并不可取，因此，可以在变量的 ALL 定义中，使用 `.+` 来代替列表。

这时，查询全部变成：` instance=~'.+' `。


#### 6.6.6 Provisoning

Grafana 提供了强大的界面，可以方便的 编辑 DataSource/Dashboard，从 0 开始搭建 Grafana 并非难事。所有的资源配置保存在 Grafana 的本地存储中(默认使用 SQLite 文件数据库)。由于 Grafana 存储是轻量级的，基本是元数据存储，因此，其存储消耗并不大。当然可以将 存储 放在 PV 上，在切换环境部署时可以将数据复制挂载到新环境即可。

但更多时候想要快速搭建，因此，这就需要使用非数据库的配置方式。这在 Grafana称之为`Provisoning`。

Provisioning 实际就是将数据源、Dashbord 配置外置了。

这样，只需要将 数据源等配置编制成 ConfigMap，(多个grafana实例时，可将 Dashboard 挂载在共享卷) 即可实现 Grafana 的 搭建。


### 6.7 Prometheus-operator

Prometheus-operator 是使用K8S CRD 手段管理 Prometheus 监控的开源软件。通过 Operator 可以方便的添加 K8S 组件、Pod、Service、Node 等各类资源的监视、Prometheus 规则的发布、管理。

#### 6.7.1 K8S CRD

CRD 是 Custom Resource Definitions 的缩写，即：定制资源声明。在 `K8s API和资源` 部分，描述了K8S API 和 资源的关系： K8S 各类 API 负责管理资源, 如 核心 API 管理 Pod 等资源。
CRD 与此类似，使用定制的API组来管理CRD。

本质上，K8S 的声明性 资源定义方式，为 资源管理提供了一个良好的框架。如：
- 声明资源：编制 YAML 文件，其中指定 API 分组和 资源类型。
- 创建资源：使用 kubectl apply -f 创建资源。
- 监视资源：CRD Operator 监视 需要的资源(watch)。
  - 执行资源定义的动作：
    - Pod: 运行 一个 POD.
    - StatefulSet: 运行一个 sts。
    - Service：创建 网络 服务并 select endpoint。

> 注意，资源的 operator 与 资源之间是解耦的。api-server 提供资源声明的存储、访问能力。


#### 6.7.2 Prometheus CRD 

Prometheus-Operator 定义了一组 CRD: 
* Prometheus, 定义prometheus的deployment。which defines a desired Prometheus deployment.
* Alertmanager, 定义Alertmanager。which defines a desired Alertmanager deployment.
* ThanosRuler, 定义ThanosRuler。which defines a desired Thanos Ruler deployment.
* ServiceMonitor, 定义服务监视内容，Operator自动生成Prometheus的target 配置。 which declaratively specifies how groups of Kubernetes services should be monitored. The Operator automatically generates Prometheus scrape configuration based on the current state of the objects in the API server.
* PodMonitor, 定义Pod监视。which declaratively specifies how group of pods should be monitored. The Operator automatically generates Prometheus scrape configuration based on the current state of the objects in the API server.
* Probe, 定义静态Pod或Ingress 监视。 which declaratively specifies how groups of ingresses or static targets should be monitored. The Operator automatically generates Prometheus scrape configuration based on the definition.
* PrometheusRule, 定义 Rules，该Rule将自动挂载到 Prometheus 。which defines a desired set of Prometheus alerting and/or recording rules. The Operator generates a rule file, which can be used by Prometheus instances.
* AlertmanagerConfig, 定义 alert Manager 配置。which declaratively specifies subsections of the Alertmanager configuration, allowing routing of alerts to custom receivers, and setting inhibit rules.

Operator 将 Prometheus 各项应用配置需求以 K8S CRD 方式 声明，并保存在 K8S API-server，根据CRD内容来运行、配置 Prometheus，这样就极大的方便了复杂集群中Prometheus管理。

这对其他应用也带来了好处，比如：需要对某个微服务进行监控，只需要创建相应的 PodMonitor即可。更进一步，此CRD文件可以由 微服务的开发者提供，这可极大降低集群管理员的工作。

另一方面，集中的、文件声明式管理Prometheus 配置数据的方式，与 Helm结合后又能带来更大的便利。


### 6.8 kube-prometheus-stack

Kube-prometheus-stack 是一个完整的Helm Chart ：
* Prometheus-operator
  * prometheus
  * alertManager 
* NodeExporter
* kube-state-metrics
* Grafana 

使用该Chart 会在K8S集群中创建上述服务，并将 K8S 相关 Dashboard 集成 到 grafana。

#### 6.8.1 安装

> 由于 k8s.io 镜像仓库无法访问，可能需要 手动修改一些镜像地址。

```
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts

helm pull prometheus-community/kube-prometheus-stack

ls -l 
415615 Jan 29 16:50 kube-prometheus-stack-44.2.0.tgz
```
将其解压可以修改其中的 k8s image。

安装前先创建 namespace：
```
kubectl create ns monitor 

kubectl config set-context --current --namespace=monitor

helm install kube-prometheus-stack kube-prometheus-stack --debug -n monitor

# 使用 -n 指定 安装名空间，不指定的话使用 默认名空间。
# --debug 可以看到安装的进程。

...
NOTES:
kube-prometheus-stack has been installed. Check its status by running:
  kubectl --namespace monitor get pods -l "release=kube-prometheus-stack"
```

kube-prometheus-stack 中有两个镜像需要修改：
* nginx-admission: 在 values.yaml 的 prometheusOperator.admissionWebhooks.patch.image 。
* kube-state-metrics: 在 charts/kube-state-metrics中。

以上可以使用 aliyun 的google镜像库。

也可以在安装过程中修改，如：
```
kubectl get jobs 
kube-prometheus-stack-admission-patch 

kubectl edit jobs kube-prometheus-stack-admission-patch

# 另一个job是 kube-prometheus-stack-admission-create
```
修改镜像即可。

或使用 `--values kps-values.yaml` ，在 kps-values.yaml 中修改相应的配置。
```yaml
prometheusOperator:
  enabled: true
  admissionWebhooks:
    patch:
      enabled: true
      image:
        # registry: k8s.gcr.io
        # repository: ingress-nginx/kube-webhook-certgen
        # update image registry
        registry: registry.cn-hangzhou.aliyuncs.com
        repository: google_containers/kube-webhook-certgen

kube-state-metrics:
  image:
    # repository: registry.k8s.io/kube-state-metrics/kube-state-metrics
    # tag: "v2.7.0"
    repository: bitnami/kube-state-metrics
    tag: 2.7.0

```

安装完毕后，可查看部署情况：
```console
$ kubectl get pod
NAME                                                        READY   STATUS    RESTARTS      AGE
alertmanager-kube-prometheus-stack-alertmanager-0           2/2     Running   1 (54m ago)   54m
kube-prometheus-stack-grafana-ffccd799d-djd8m               3/3     Running   0             54m
kube-prometheus-stack-kube-state-metrics-85c5ff5655-cgpjc   1/1     Running   0             37m
kube-prometheus-stack-operator-ccb5d9cb5-sjgl2              1/1     Running   0             54m
kube-prometheus-stack-prometheus-node-exporter-5xf2s        1/1     Running   0             54m
kube-prometheus-stack-prometheus-node-exporter-pt8dl        1/1     Running   0             54m
prometheus-kube-prometheus-stack-prometheus-0               2/2     Running   0             54m
```

其中grafana 服务 为 ClusterIP, 集群外部无法访问，可使用 NodePort将其 暴露出来。或在开发过程采用 port-forward。

grafana 默认创建一个密码，保存在 secrets中。
```
$ kubectl get secrets | grep grafana
kube-prometheus-stack-grafana                                  Opaque                                3      67m
kube-prometheus-stack-grafana-token-ts4bf                      kubernetes.io/service-account-token   3      67m

# 查看其内容，并使用 base64 解码：
$ kubectl get secrets kube-prometheus-stack-grafana -o jsonpath='{.data.admin-password}' | base64 -d

prom-operator
```
使用admin/该密码登录即可。

Grafana 已经加载了 K8S 的各个Dashboard，可以用来监视集群状态了。

6.8.2 ServiceMonitor CRD

部署后，创建一个　ServiceMonitor CRD　来监视 nginx。在此之前，先查看一下已有的资源：
```
# smon 是 servicemonitors 的缩写。
$ kubectl get smon -n monitor
NAME                                             AGE
kube-prometheus-stack-alertmanager               41h
kube-prometheus-stack-apiserver                  41h
kube-prometheus-stack-coredns                    41h
kube-prometheus-stack-grafana                    41h
kube-prometheus-stack-kube-controller-manager    41h
kube-prometheus-stack-kube-etcd                  41h
kube-prometheus-stack-kube-proxy                 41h
kube-prometheus-stack-kube-scheduler             41h
kube-prometheus-stack-kube-state-metrics         41h
kube-prometheus-stack-kubelet                    41h
kube-prometheus-stack-operator                   41h
kube-prometheus-stack-prometheus                 41h
kube-prometheus-stack-prometheus-node-exporter   41h

$ kubectl get smon/kube-prometheus-stack-grafana -o yaml
```
```yaml
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  annotations:
  # ...
  labels:
  # ...
    release: kube-prometheus-stack
  name: kube-prometheus-stack-grafana
  namespace: monitor
spec:
  endpoints:
  - honorLabels: true
    path: /metrics
    port: http-web
    scheme: http
    scrapeTimeout: 30s
  jobLabel: kube-prometheus-stack
  namespaceSelector:
    matchNames:
    - monitor
  selector:
    matchLabels:
      app.kubernetes.io/instance: kube-prometheus-stack
      app.kubernetes.io/name: grafana
```
spec中:
- endpoints: 抓取 k8s endpoints(即所有与服务绑定的端点，通常就是 pod)
- namespaceSelector: 目标服务所在的名空间。 
- selector: label 匹配

参照这个例子，编制 Nginx CRD
```yaml
kind: ServiceMonitor
metadata:
  labels:
  # 由于 prometheus 设置了 serviceMonitorSelector: matchLabels: 
  #  release: kube-prometheus-stack
  # 因此，只会应用 带有该 Label 的 smon
    release: kube-prometheus-stack
  name: prometheus-op-nginx
  # CRD 统一保存在 monitor ns
  namespace: monitor
spec:
  endpoints:
  - honorLabels: true
    path: /metrics
    # port metrics 需定义在 相应的 服务 中
    port: metrics
    scheme: http
    scrapeTimeout: 30s
  # 使用目标 service 的  helm.sh/chart 标签值 作为 job 值
  jobLabel: helm.sh/chart
  namespaceSelector:
    matchNames:
    # 目标 service 名空间 default
    - default
  selector:
    matchLabels:
    # 目标 service 的 标签
      app/instance: my
      app/name: nginx-sts
```
ServiceMonitor 先抓取服务的 endpoints。抓取服务时 使用 namespace 和 label，endpoint 中的 port name 也必须匹配。
(使用 Service Monitor 会加上标签 service = service name, 使用 pod monitor 则没有)。

创建该CRD后，需要等待一会(watch/update 的间隔)，再看prometheus 的 targets 中是否有
`serviceMonitor/monitor/prometheus-op-nginx`。

也可查看 prometheus 实例中 的配置文件：
```
$ kubectl exec -it svc/kube-prometheus-stack-prometheus -- sh
/prometheus $ cat /etc/prometheus/config_out/prometheus.env.yaml
```
```yaml
- job_name: serviceMonitor/monitor/prometheus-op-nginx/0
  honor_labels: true
  kubernetes_sd_configs:
  - role: endpoints
    namespaces:
      names:
      # 仅选择 default namespace 的服务
      - default
  scrape_timeout: 30s
  metrics_path: /metrics
  scheme: http
  relabel_configs:
  - source_labels:
    - job
    # 保存原 Job 标签
    target_label: __tmp_prometheus_job_name
  - action: keep
    source_labels:
    - __meta_kubernetes_service_label_app_instance
    - __meta_kubernetes_service_labelpresent_app_instance
    # app/instance = my 
    regex: (my);true
  - action: keep
    source_labels:
    - __meta_kubernetes_service_label_app_name
    - __meta_kubernetes_service_labelpresent_app_name
    # app/name = nginx-sts
    regex: (nginx-sts);true
  - action: keep
    source_labels:
    - __meta_kubernetes_endpoint_port_name
    # port: metrics
    regex: metrics
```
当targets未按预期出现时，可查看 由 Prometheus Operator 生成的 kubernetes_sd_config 来解决问题。

#### 6.8.3 自动抓取配置

上一节 的 ServiceMonitor 可以发现，Operator 通过 service 的 label 来抓取 pod，而非 其名称。因此，并不仅仅局限于某一个服务。这就带来了所谓的 `自动抓取`配置。

> K8S 部署的应用通过服务暴露endpoint，因此，仅针对服务就基本能涵盖 监视 需求。

流行的做法是 约定一组annotation，如：
```yaml
  annotations:
    ## Set true to allow Prometheus discover and scrape metrics
    prometheus.io/scrape: "true"  
    ## Set port of HTTP URL that exposes metrics
    prometheus.io/port: "9000"
    ## Set path of HTTP URL that exposes metrics
    prometheus.io/path: "/minio/v2/metrics/cluster" 
```
然后使用 kubernetes_sd_config，根据是否声明了 `prometheus.io/scrape: "true"` 来 决定保留该 endpoint。

可以使用 ServiceMonitor 来实现类似的做法。
```yaml
# samples/monitor/prom-discovery-smon.yaml
spec:
  endpoints:
  - honorLabels: true
    relabelings:
    # 有 prometheus.io/scrape=true 才保留
    - sourceLabels: [__meta_kubernetes_service_annotation_prometheus_io_scrape]
      action: keep
      regex: "true"
    # 将prometheus.io/path 的值 替换 metrics_path 
    # 默认值是 /metrics
    - sourceLabels: [__meta_kubernetes_service_annotation_prometheus_io_path]
      action: replace
      targetLabel: __metrics_path__
      regex: (.+)
      # 替换 地址中的 port 
    - sourceLabels: [__address__, __meta_kubernetes_service_annotation_prometheus_io_port]
      action: replace
      regex: ([^:]+)(?::\d+)?;(\d+)
      replacement: $1:$2
      targetLabel: __address__
      # 包含 io port 或者，port name 包含 metrics的才保留。
    - sourceLabels: 
      - __meta_kubernetes_service_annotationpresent_prometheus_io_port
      - __meta_kubernetes_endpoint_port_name
      separator: ;
      action: keep
      # 如果没有定义 promtheus.io/port，必须包含一个 metrics的 端口名称。
      regex: .*(true|metrics).*
  namespaceSelector:
    matchNames:
    # 包含的 namespace。不写表示全部 名空间。
    - default
    - loki 
  selector:
  # 不写表示全部
    matchLabels: {}
```
注意这里使用了 service_annotation, 需要将 annotation 定义在 service 上，而非 pod。

据此，将 相应的 annonation 定义 在 需要的 服务即可，如：
```
kubectl annotate svc/my-nginx-sts -n default prometheus.io/scrape=true
```
给 my-nginx-sts 服务 scrape=true, 而在 服务中的 `portName: *metrics*` 被选中作为了 端口号。

### 6.9 小结

Prometheus + Grafana 的组合 是 K8S监视的主流方案，有大量资源可借用。Prometheus Operator 进一步简化了 Prometheus 的配置管理和动态更新。

大规模集群实践中，Prometheus Operator 可以很容易实现多实例多分片的 prometheus 部署。

SpringBoot 应用的 metric 通过 actuator/metrics 暴露，同样可以集成到Prometheus/Grafana。

## 7. 日志

各类应用和系统的日志是集群运行时重要的资产，通过检查日志，可以方便的定位问题、解决问题。

ELK 是较为流行的应用栈，ELK 利用 ES 的强大高效的查询能力，对日志进行检索。由于 Logstash 过重，有出现了使用 Beat 替换 Logstash 的 EFK 栈。

与之相比，Loki 作为轻量级、可伸缩的 日志采集检索方案，也是在容器时代流行的方案之一。特别是，Loki使用Grafana 作为前端时，降低了整个方案的复杂性。

本文使用 Loki 进行K8S 日志采集和处理。

### 7.1 Loki 架构

Loki 架构与其他日志采集系统类似，使用 Agent 进行日志采集，Loki 组件进行日志聚集存储，并提供查询、搜索能力。Loki 也可以作为数据源与 Grafana 对接实现可视化。

Loki 支持多种 Agent, 常见的是 Promtail 和 Flunt Bit。采集的日志格式推荐使用 logfmt，这样不需要特殊配置即可实现标签索引。

Loki 的存储采用对象存储，以 AWS S3 为标准，非AWS用户可使用开源 MinIO 替代 S3。(单机版使用 BoltDB本地存储)。

Loki 日志索引并未像 ELK 那样提供全文检索能力，而是借鉴了 Prometheus 的 label 方式，仅对 label 进行 索引，这样降低了索引的空间需求(也降低检索时内存消耗)，当然缺点是 全文检索 效率低，但这已经可满足一般的日志检索需求。


Loki 还支持 可伸缩 部署，典型的模式是读写分离：

![ Loki simple scalable deployment ](img/loki-simple-scalable.png) 

上图使用 3 个 write节点, 两个 read 节点，各组件说明如下：
- Distributor： 分发组件，当Agent将采集到的日志流发送至 Distributor 时，Distributor 进行验证、预处理、限流等控制，将 日志流 转发至 `Ingester` 。Distributor 是stateless应用，因此，前端可使用 Loadbalancer。
- Ingester: 写入器，将日志流写入存储，并形成 索引数据。
- Querier: 查询器，提供 LogQL 查询服务。
- Query forntend: 查询前置器，对大量查询请求进行排队，并转发给 Querier。
- Ruler：规则引擎，参照 Prometheus的 RecordRule 和 Alert Rule 模式，用于规则计算、聚合、告警。
- Index gateway: 多个查询节点时，使用 index gateway 可以隐藏节点配置(并不是必要的，通过 service 也是可以的)。

Loki 还支持微服务模式，即将每个组件都独立部署。这种方式管理复杂。小规模集群使用 读写分离模式足够了。

新版本的 Loki 支持 backend 部署模式，即将 read/write 修改为 read/write/backend三部分。原来集成在 read 中的 compactor 、index gateway、ruler等都放在 backend 中，read 仅保留 querier 和 frontend 。这种结构更适合，比如 compactor 等可按需选择是否启动了。


### 7.2 Loki 部署方案

Loki 提供了完备的 Helm Chart，可以高度自动化、定制化的 部署 Loki。

```
helm repo add grafana https://grafana.github.io/helm-charts
"grafana" has been added to your repositories
```

为定制安装，需要编制一个 loki-values.yaml 来定制其内容。

> 可参考的办法是将 Chart中的 values.yaml 文件提取出来，` helm show values grafana/loki > loki-values.yaml`。


独立部署 Loki 也较为方便。这样可以更好的理解 Loki 机制。本文采用独立部署的方式。 

#### 7.2.1 部署模式

如架构一节所描述的，使用 读写分离模式，分别部署 StatefulSet 用于应对 读/写 节点。

Loki 节点间的内存同步机制使用 in-memory, 不单独安装 memcache 

在 read 节点前，部署独立的 query front-end 节点。

#### 7.2.2 存储 

根据 Loki 架构，想实现可伸缩部署，理想的方法是使用 AWS S3 对象存储，开源的 MinIO 是 S3 的替代产品，仍然能提供生产环境级别的高可用能力，因此，推荐使用 MinIO作为存储。

MinIO 生产环境部署 官方推荐使用 MinIO Operator 插件。测试环境直接编制 StatefulSet(单节点使用Deployment) 就可以了。

#### 7.2.3 Agent Promtail

由于 Fluntd 是流行的日志采集服务，因此，很多用户会优先选择使用 Flunt bit 作为采集端。

但Promtail 也很优秀, 并且它是 `Prometheus-inspired` 项目(受Prometheus启发的项目)，因此，其配置方式与Prometheus高度一致(比如：scrape_config 连文档都是直接从prometheus搬过来的)。这也可以简化学习过程。

还有一点，Promtail 是 Grafana 家族成员，在持续支持和集成方面应具备一些优势。

### 7.3 安装 MinIO

测试环境采用单节点单存储(Single Node Single Drive， SNSD) 模式安装 MinIO。这样直接使用 StatefulSet 就可以完成安装。

#### 7.3.1 MinIO StatefulSet 

StatefulSet 使用PVC，这里可以使用 Local-storage 绑定本地目录。也可以使用之前的 NFS(NFS 存储 性能低于 Local，但很方便)。

重点看一下 container 部分：
```yaml
      containers:
      - name: minio
        image: minio/minio:RELEASE.2023-01-31T02-24-19Z
        args: 
        # 参数，minio server /data --console-address :9001
          - server
          - /data 
          # 指定 MinIO console 服务端口 
          - --console-address 
          - :9001
        envFrom:
        # 从 ConfigMap minio-env获取 环境变量。
          - configMapRef: 
              name: minio-env
        ports:
        # api 访问端口
        - name: http
          containerPort: 9000
        # console 访问端口
        - name: console
          containerPort: 9001
        readinessProbe:
        # readiness 
          httpGet:
            path: /minio/health/ready
            port: 9000
            scheme: HTTP
```
MinIO 使用 环境变量传递 访问密钥，可以将 env 信息 保存在 ConfigMap 或 Secrets 中，然后在 container env 中使用。

> MINIO_ROOT_USER/PASSWORD 可不填写，Minio会生成 用户密码，这些信息会写在 log 里。使用生成的认证信息登陆后，应立即修改密码。

StatefulSet 添加了 `资源` 限制:
```yaml
        resources:
          limits:
            cpu: 200m
            memory: 512Mi
```

再定义 namespace loki , config map 和 service 。

完成后 `apply -f "samples/loki/minio*.yaml"` 。

使用 logs 查看 创建的 MinIO 实例：
```
$ kubectl logs --timestamps=true minio-0
2023-02-01T07:15:15.616698911Z Formatting 1st pool, 1 set(s), 1 drives per set.
2023-02-01T07:15:15.617017511Z WARNING: Host local has more than 0 drives of set. A host failure will result in data becoming unavailable.
2023-02-01T07:15:16.488215426Z MinIO Object Storage Server
2023-02-01T07:15:16.489322326Z Copyright: 2015-2023 MinIO, Inc.
2023-02-01T07:15:16.489360026Z License: GNU AGPLv3 <https://www.gnu.org/licenses/agpl-3.0.html>
2023-02-01T07:15:16.489423926Z Version: RELEASE.2023-01-31T02-24-19Z (go1.19.4 linux/amd64)
2023-02-01T07:15:16.489432326Z
2023-02-01T07:15:16.490445627Z Status:         1 Online, 0 Offline.
2023-02-01T07:15:16.490611027Z API: http://10.244.1.7:9000  http://127.0.0.1:9000
2023-02-01T07:15:16.689798622Z Console: http://10.244.1.7:9001 http://127.0.0.1:9001
2023-02-01T07:15:16.689860722Z
2023-02-01T07:15:16.689877122Z Documentation: https://min.io/docs/minio/linux/index.html
2023-02-01T07:15:16.689888922Z Warning: The standard parity is set to 0. This can lead to data loss.
```

为 Minio建立了NodePort 服务，以方便 访问其 console，详见：`samples/loki/minio-svc.yaml`，其中使用了 prometheus.io 自动配置：
```yaml
annotations:
    prometheus.io/scrape: "true" 
    prometheus.io/path: /minio/v2/metrics/cluster
```

> 在配置 Minio时使用了`MINIO_PROMETHEUS_AUTH_TYPE: public`，因此，访问 metrics 不需要配置 TOKEN 认证 

#### 7.3.2 初始化 MinIO 环境

通过 nodePort 的端口可以访问 MinIO console，用户名密码使用 configMap 中的定义。

登录后创建 Loki 需要的 Buckets:
- chunks: 保存 chunks 。 
- ruler： 保存 ruler 。

暂时不使用 Ruler, 因此仅创建 chunks 就可以了。bucket 名称 定义为 `loki-chunks`。

访问 MiniIO 需要提供 Access Key / Secret Key。

在 Identity 中 创建新 用户 `loki`，赋予 readwrite 权限，在该用户下创建 service Account，选择 `Create Access Key` 默认生成的 key 就可以。

本例生成的 keys: 
```
Access Key: 7yNws3p8ElA8gbQm
Secret Key: AFwj8GukogbdhSNhlhAuCfmLXIzDDFSr
```

### 7.4 Loki 配置

Loki 的所有组件编译为一个可执行文件，通过指定 -target 来分别启动不同的组件，因此，配置也是可以共享的。

Loki -target 的单一组件包括：
- ingester
- distributor
- query-frontend
- query-scheduler
- querier
- index-gateway
- ruler
- compactor
Loki -target 其他组合值：
- all: 单一模式全部组件。
- read: 读模式 包括 querier、ruler、FE　
- write: 写模式 包括 distributor、ingester。
<!-- - table-manager -->

不同的组件，都有独立的配置模块，配置独立的数据。

全局配置有一项是和 `租户` 有关的:
- `auth_enabled` : 是否认证客户端，设置为 false 即可。 

> 设置为 false 会导致 S3 上保存 chunks 目录为： fake。这是默认的 `租户` 名称。如果要该名字，需要 设置 auth_enabled: true，并在 Http 头 添加: `X-Scope-OrgID: 自定义名称`，这些头信息需要在 promtail 和 Grafana 端配置。

#### 7.4.1 Server 部分

Server 部分定义了 Loki 组件 服务信息，包括http(s) 端口设置，grpc 设置，tls设置。以及服务连接性能tweak 配置信息。
以下信息来自官网：
```yaml
# HTTP server listen host
# CLI flag: -server.http-listen-address
# 默认值绑定 0.
[http_listen_address: <string>]

# HTTP server listen port
# CLI flag: -server.http-listen-port
[http_listen_port: <int> | default = 80]

# TLS configuration for serving over HTTPS
http_tls_config:
# ca cert key 等配置，略。

# gRPC server listen host
# CLI flag: -server.grpc-listen-address
[grpc_listen_address: <string>]

# gRPC server listen port
# CLI flag: -server.grpc-listen-port
[grpc_listen_port: <int> | default = 9095]

# TLS configuration for serving over gRPC
grpc_tls_config:
# 略

# Register instrumentation handlers (/metrics, etc.)
# CLI flag: -server.register-instrumentation
[register_instrumentation: <boolean> | default = true]
# 暴露 metrics.

# http/grpc 连接配置。如 read/write time out 等等。略。
[http_server_read_timeout: <duration> | default = 30s]

# Log only messages with the given severity or above. Supported values [debug,
# info, warn, error]
# CLI flag: -log.level
[log_level: <string> | default = "info"]

# Base path to serve all API routes from (e.g., /v1/).
# CLI flag: -server.path-prefix
[http_path_prefix: <string> | default = ""]
```
大部分默认值已经足够使用了，tls 配置的话，需要指定 相应的 tls_config。
另外，可能会修改端口的定义。比如： read 用一个8081，write 用另一个8082之类。

本文中使用默认80端口。

#### 7.4.2 Loki 存储配置

Loki (Ingester) 为 日志流 建立索引 Index，并将 Index 和 数据 (Chunks) 分别存储。因此，存储的配置需要包括 这两部分，在 Loki 配置中，使用 `store` 表示 存储 Index, 使用 `object_store` 表示存储 Chunks，这一点在文档中有介绍。

##### 7.4.2.1 schema_config

如何存储 Loki 的 index 和 chunks，配置在 schema_config 中：
```yaml
schema_config:
  configs:
    - <period_config>
``` 
Loki 支持schema切换，通过 period_config 指定生效日期来决定采用哪一个配置。本节仅考虑定义一个shecma。
```yaml
# The date of the first day that index buckets should be created. Use
# a date in the past if this is your only period_config, otherwise
# use a date when you want the schema to switch over.
# In YYYY-MM-DD format, for example: 2018-04-15.
# schema 生效时间。
[from: <daytime>]

# store and object_store below affect which <storage_config> key is
# used.

# Which store to use for the index. Either aws, aws-dynamo, gcp, bigtable, bigtable-hashed,
# cassandra, boltdb or boltdb-shipper.
# 保存索引 的 storage 配置名称 。
store: <string>

# Which store to use for the chunks. Either aws, azure, gcp,
# bigtable, gcs, cassandra, swift or filesystem. If omitted, defaults to the same
# value as store.
# 保存 chunks的 storage 
[object_store: <string>]

# The schema version to use, current recommended schema is v11.
# 使用 v11 
schema: <string>

# Configures how the index is updated and stored.
index:
  # Table prefix for all period tables.
  # 保存 Index 的表名称。
  prefix: <string>
  # Table period.
  # 每个表 保存 的数据周期，默认是 7 天。
  [period: <duration> | default = 168h]
  # A map to be added to all managed tables.
  tags:
    [<string>: <string> ...]

# Configured how the chunks are updated and stored.
# 与 Index 配置类似。
chunks:
  # Table prefix for all period tables.
  prefix: <string>
  # Table period.
  [period: <duration> | default = 168h]
  # A map to be added to all managed tables.
  tags:
    [<string>: <string> ...]

# How many shards will be created. Only used if schema is v10 or greater.
# 分片
[row_shards: <int> | default = 16]
```
其中的 index / chunks prefix 是指 数据存储的 `表`，这在不同存储中含义不同，在 文件系统 或 S3 中，代表目录。表的周期性是指，每隔指定的时间，创建新表保存新数据。

schema 中 没有定义具体的存储配置，而是通过名字引用。具体配置在 storage_config 中。
示例：
```yaml
schema_config:
  configs:
  - from: "2022-01-01"
    schema: v11
    store: store1
    object_store: store2
    index: 
      prefix: loki_index_
      period: 48h
    chunks:
      prefix: loki_chunks_
      period: 48h
```
这里使用 store1 保存索引，store2 保存 chunks。

##### 7.4.2.2 storage_config 

storage_config 定义 上文 中使用的 store。

Loki storage_config 的配置有些费解，每一种存储(如AWS/ GCS 、BoltDB等)只能定义一个。

由于S3/MinIO 主流，而 BoltDB-shipper 模式是推荐模式，因此，这里仅介绍这两种配置。

##### 7.4.2.3 S3/MinIO 存储配置

S3、MinIO 配置必须以 aws: 开始。如：
```yaml
storage_config:
  aws:
    s3: s3://access_key:secret_access_key@region/bucket_name
```
而在 schema 中 使用 `aws` 引用。

也可以使用展开的配置：
```yaml
# Configures storing chunks in AWS. Required options only required when aws is
# present.
aws:
  # S3 or S3-compatible endpoint URL with escaped Key and Secret encoded.
  # If only region is specified as a host, the proper endpoint will be deduced.
  # Use inmemory:///<bucket-name> to use a mock in-memory implementation.
  # CLI flag: -s3.url
  [s3: <string>]

  # Set to true to force the request to use path-style addressing
  # CLI flag: -s3.force-path-style
  [s3forcepathstyle: <boolean> | default = false]

  # Comma separated list of bucket names to evenly distribute chunks over.
  # Overrides any buckets specified in s3.url flag
  # CLI flag: -s3.buckets
  [bucketnames: <string> | default = ""]

  # S3 Endpoint to connect to.
  # CLI flag: -s3.endpoint
  [endpoint: <string> | default = ""]

  # AWS region to use.
  # CLI flag: -s3.region
  [region: <string> | default = ""]

  # AWS Access Key ID.
  # CLI flag: -s3.access-key-id
  [access_key_id: <string> | default = ""]

  # AWS Secret Access Key.
  # CLI flag: -s3.secret-access-key
  [secret_access_key: <string> | default = ""]

  # Disable https on S3 connection.
  # CLI flag: -s3.insecure
  [insecure: <boolean> | default = false]

  # Enable AES256 AWS Server Side Encryption.
  # CLI flag: -s3.sse-encryption
  [sse_encryption: <boolean> | default = false]
```
本例中的 MinIO配置可使用：
```yaml
storage_config:
  aws:
    # 指向 MinIO 服务 的 cluster 内部域名。
    # service.namespace.svc.<cluster.local>
    endpoint: minio.loki.svc:9000
    # 没有设置 region，可在 MinIO Console 设置。
    # region:
    # 保存 loki 数据的 桶名称。
    bucketnames: loki-data
    # 将region buckets 放在 URL 的 path 部分，而非 host部分。
    s3forcepathstyle: true
    # 不安全的(使用 http 而非 https)
    insecure: true
    # 应使用 环境变量传入 更为安全。 
    # <-s3.access-key-id>
    access_key_id: 7yNws3p8ElA8gbQm
    # <-s3.secret-access-key>
    secret_access_key: AFwj8GukogbdhSNhlhAuCfmLXIzDDFSr
```

##### 7.4.2.4 BoltDB Shipper 模式

2.0 版 Loki 引入了 BoltDB shipper 模式，这是推荐模式。
BoltDB Shipper，顾名思义，首先是依赖于 `BoltDB` 本地存储，然后以 `Shipper` 的角色，将数据发送至 远端存储。此模式可在 local 的 BoltDB 同时保存 Index 和 Chunk。并可将 Index/Chunk 延迟同步到 远端的 Object_store (配置中使用了 `shared_store` 指定远端存储)。

之所以使用这种模式，是考虑到性能和可扩展性。

假如索引或Chunk直接存储到远端，那么会带来一下问题：
- 日志流写入速度和数据量都很高，这会频繁写入远端。
- 远端写入响应时间与本地写入不在一个数量级，必然导致写操作队列阻塞，并发能力不够。
- 过于频繁访问远端存储可能会导致远端存储的性能下降(如文件碎片化)。
- 查询时 也必然会出现对远端数据的大量读操作。

降低实时写入、读取时对远端存储的依赖，方法很简单，就是提供`就地缓存`。也就是在写入时即缓存。那么就需要同时缓存 index 和 Chunk。 然后定时(如 15m) 批量将 index 和 chunk 上传(share) 至远端。

当然，本地缓存的存储周期、替换模式这些是需要根据实际情况进行配置的。 而在 批量上传间隙，为避免 查询 结果缺少 最新数据，查询端也会 进行本地缓存查询，具体而言，就是在 Ingester 节点进行查询。

由此，BoltDB Shipper 的整体 写模式为：
```mermaid
graph LR 
  [agent] --> [distributor] --> [Ingester] --> [BoltDB] --> [shared_store] --> [Remote Store (MinIO)] 
end
```
而在 查询 读 的时候:
```mermaid
graph LR
  [FE] --> [Querier] -->  
```

##### 7.4.2.5 BoltDB Shipper 配置  

BoltDB shipper 的配置如下：
```yaml
# Configures storing index in an Object Store(GCS/S3/Azure/Swift/Filesystem) in the form of
# boltdb files.
# Required fields only required when boltdb-shipper is defined in config.
boltdb_shipper:
  # Directory where ingesters would write boltdb files which would then be
  # uploaded by shipper to configured storage
  # CLI flag: -boltdb.shipper.active-index-directory
  # 本地保存索引的目录
  [active_index_directory: <string> | default = ""]

  # Shared store for keeping boltdb files. Supported types: gcs, s3, azure,
  # filesystem
  # CLI flag: -boltdb.shipper.shared-store
  # 索引文件同步
  [shared_store: <string> | default = ""]

  # Cache location for restoring boltDB files for queries
  # CLI flag: -boltdb.shipper.cache-location
  # 本地缓存 目录 (供查询使用)。
  [cache_location: <string> | default = ""]

  # TTL for boltDB files restored in cache for queries
  # CLI flag: -boltdb.shipper.cache-ttl
  # 缓存 文件 的 TTL 时间(过期将丢弃)。
  [cache_ttl: <duration> | default = 24h]

  # Resync downloaded files with the storage
  # CLI flag: -boltdb.shipper.resync-interval
  [resync_interval: <duration> | default = 5m]

  # Number of days of index to be kept downloaded for queries. Works only with
  # tables created with 24h period.
  # CLI flag: -boltdb.shipper.query-ready-num-days
  [query_ready_num_days: <int> | default = 0]
```
其中主要配置为：
```yaml
storage_config:
  boltdb_shipper:
    active_index_directory: /loki/index
    cache_location: /tmp/loki_cache
    shared_store: aws
```

#### 7.4.3 Ring / KV store 

Loki 各组件分布式部署时，形成各自的组件集群，集群通讯的机制称之为 `Consistent hash rings`：集群中的组件形成一个 `环`，实现集群服务发现、数据任务分片、高可用、水平扩展。

集群中每个节点加入Ring后，Ring 可以保持一个节点计数，在此基础上可以分发数据和任务。

节点信息保存在 KV Store 中，可选的 KV Store 包括 consul/etcd/inmemory/memberlist。

官方推荐使用 memberlist ring，可以由distributor/ingester/queriers 共享一个 ring。因此，使用一个 公共的 ring 配置就可以了。

```yaml
common:
  ring:
# The key-value store used to share the hash ring across multiple instances.
  kvstore:
    # Backend storage to use for the ring. Supported values are: consul, etcd,
    # inmemory, memberlist, multi.
    # CLI flag: -<prefix>.store
    [store: <string> | default = "memberlist"]

  # The prefix for the keys in the store. Should end with a /.
  # CLI flag: -<prefix>.prefix
  [prefix: <string> | default = "collectors/"]

```
由于默认的 common.ring.kvstore 就是 memberlist，如果没有特殊的定义，不需要再定义。

而在需要使用 ring 的组件中，只需要定义：
```yaml
  ring:
    kvstore:
      store: memberlist
```
就可以了。

memberlist 服务的信息需要配置在 <memberlist> 块 中，可以参考官方文档。在局域网环境中，大部分使用默认值就可以。

memberlist 库 是一种去中心的 分布式 数据同步机制。每个加入 memberlist 的节点之前相互扩散数据，一定时间后实现 个节点间数据的一致性。 很明显，这种机制 同步数据量有限，且不适用于 强一致性 需求。

在Loki 和 grafana 的很多产品中，使用 Memberlist 来实现 集群节点 管理。如 Loki 中的 distributor 需要将 日志流 分发到 多个 Ingester 写入，因此，distributor 需要了解：
- 一共有几个 Ingester。
- 每个 Ingester 的 端点信息(ip:port)。
- 每个 Ingester 的 任务 状态。
- Ingester 存活 情况(加入、退出)。

这也就是 Ring 的含义，memberlist 数据同步完成之后，在每个节点都会保持相同的数据，这样就可以满足上述各项需求。

摘录部分 memberlist 的配置如下：

```yaml
# IP address to listen on for gossip messages. Multiple addresses may be
# specified. Defaults to 0.0.0.0
# CLI flag: -memberlist.bind-addr
[bind_addr: <list of string> | default = ]

# Port to listen on for gossip messages.
# CLI flag: -memberlist.bind-port
[bind_port: <int> | default = 7946]

# If this node fails to join memberlist cluster, abort.
# CLI flag: -memberlist.abort-if-join-fails
[abort_if_cluster_join_fails: <boolean> | default = true]

# If not 0, how often to rejoin the cluster. Occasional rejoin can help to fix
# the cluster split issue, and is harmless otherwise. For example when using
# only few components as a seed nodes (via -memberlist.join), then it's
# recommended to use rejoin. If -memberlist.join points to dynamic service that
# resolves to all gossiping nodes (eg. Kubernetes headless service), then rejoin
# is not needed.
# CLI flag: -memberlist.rejoin-interval
[rejoin_interval: <duration> | default = 0s]

# Other cluster members to join. Can be specified multiple times. It can be an
# IP, hostname or an entry specified in the DNS Service Discovery format (see
# https://grafana.com/docs/mimir/latest/operators-guide/configuring/about-dns-service-discovery/
# for more details).
# CLI flag: -memberlist.join
[join_members: <list of string> | default = ]
```
地址 和 端口 不必解释。

`join_members` 罗列一组需要加入该 ring(也即 使用相同的 memberlist) 的 端点。端点可以配置 ip 地址，hostname，或者使用 服务端点 发现。
K8S环境中可以使用服务发现，比如：
```yaml
  join_members:
  # 解析该 headless 服务包含的端点内容
    - memberlist.loki.svc:9746
    # - loki-read:9746
    # - loki-write:9746 
```

#### 7.4.4 distributor 配置

distributor 负责将 agent push 的日志分发到 ingester，包含一些 与 Ingester有关的 配置，这部分保持默认值即可。
仅需配置 ring，指定其 使用 memberlist。
```yaml
distributor:
  ring:
    kvstore:
      store: memberlist
```

#### 7.4.5 Ingester 配置

Ingester 负责写入数据。主要配置包括 ring 、副本数、以及写入参数。
ring 配置：
```yaml
lifecycler:
  ring:
    kvstore:
      store: memberlist 
    # The number of ingesters to write to and read from.
    # CLI flag: -ingester.replication-factor
    # [replication_factor: <int> | default = 3]
    replication_factor: 2 
```
其他写参数中：
- concurrent_flushes: 并发写入数，默认 32，视 资源情况调整。
- chunk 文件控制：单个 chunk文件大小和时长。
  - chunk_block_size：
  - chunk_target_size：
  - chunk_encoding：
  - max_chunk_age： 
- autoforget_unhealthy：如不使用 statefulSet 部署，则需要设置为 true。因为一旦Pod Down了，重新启动的Pod使用不同的hostname，不会再以原来的 nodeName 加入了。
- WAL: 默认开启，不需要设置。

#### 7.4.6 querier 配置

查询器的配置，主要是各项查询性能参数，这些参数都很容易理解，采用默认值即可。
这其中包括 query 与 ingester / store 的 关系的配置信息：
```yaml
# Maximum lookback beyond which queries are not sent to ingester.
# 0 means all queries are sent to ingester.
# CLI flag: -querier.query-ingesters-within
[query_ingesters_within: <duration> | default = 3h]

# Only query the store, and not attempt any ingesters.
# This is useful for running a standalone querier pool operating only against
# stored data.
# CLI flag: -querier.query-store-only
[query_store_only: <boolean> | default = false]

# When true, queriers only query the ingesters, and not stored data.
# This is useful when the object store is unavailable.
# CLI flag: -querier.query-ingester-only
[query_ingester_only: <boolean> | default = false]
```

其中 `query_ingester_with` 表示从 ingester 查询 多久 的数据。



#### 7.4.7 query-front 和 query-range 

单独部署 query-front 的话，需要在其中添加 querier的 服务名。
使用 read/write 模式不需要单独配置。
query_range 需要配置 下文。
```yaml
query_range:
  align_queries_with_step: true
```

> query-scheduler 可能需要配置。待查，资料不完整。


#### 7.4.8 compactor 

compactor 会随着 read 模式启动。简单配置如下：
```yaml
compactor:
  working_directory: /tmp/compactor
  shared_store: s3
  compaction_interval: 15m
```

### 7.5 Loki 安装

了解了配置信息之后，loki 安装就很简单了。需要的 K8S 清单如下：
- Secrets: MinIO 的访问密码
- ConfigMap: read/write 公共的配置文件。
- Read
  - StatefulSet
  - Service
- Write
  - StatefulSet 
  - Service
- memberlist headless Service

> Promtail 后继再安装配置。

#### 7.5.1 Secrets

保存MinIO Access Key的数据，定义在samples/loki/minio-secret.yaml中。 

> 使用 stringData 就不再需要 base64 。

#### 7.5.2 ConfigMap 

ConfigMap中包含 loki 的配置文件。届时将其 mount 到 pod 即可。

定义在 loki.yaml中，内容为之前配置章节描述的数据。

> 在 schema 中 store **必须** 使用： `boltdb-shipper`，而在 stroage config 中，**必须** 使用 `boltdb_shipper`。这两个地方名字不同，不能写错。 

#### 7.5.3 StatefulSet 

Read、Write 的部署类似，仅仅是 -target 不同，因此，合并在一起来介绍。

和其他部署没什么区别，只需要调整 容器 部分：

```yaml
  
```

Read 和 Write 的区别是 -target 参数 修改为 read。

在 read/write 加入标签：`kv-store: memberlist` 。

> 对于 write 应使用 pvc 挂载 /loki/ 目录作为存储，/tmp 可考虑使用 内存。

#### 7.5.4 Service 

Service 可以使用 集群内部的 clusterIP即可。

memberlist headless 服务聚合 所有 Loki pod。使用 selector:
`kv-store: memberlist`

这样就将Loki 所有组件 都加入到 memberlist ring 中。

### 7.6 部署 Promtail

Promtail 使用 Daemonset，每个节点运行一个实例。 

由于Promtail 需要访问 docker 的 日志，因此，需要使用 hostPath 访问 `/var/log/pods`,和底层 docker 的 `/var/lib/docker/containers/`。

> K8S 的日志链接至 /var/lib/docker/containers目录下。

Promtail 使用与 `prometheus`完全相同的 K8S 动态发现机制，因此，scrape_config 配置抓取 Pod 日志的部分，是可以借鉴 prometheus 的配置。由于需要动态发现，因此，需要使用 RBAC 授权，这授权内容和 prometheus 是一样的。

Promatil 需要配置 loki 服务，使用 loki write 服务名即可(如果不在一个名空间，需要写：`loki-write.loki.svc`)。

#### 7.6.1 使用 helm 安装

使用 grafana/promtail Chart 可以方便的安装promtail。

把需要调整的配置项，放在 pt-values.yaml 中：
```yaml
daemonset:
  # -- Deploys Promtail as a DaemonSet
  enabled: true

configmap:
  # -- If enabled, promtail config will be created as a ConfigMap instead of a secret
  enabled: true

rbac:
  # -- Specifies whether RBAC resources are to be created
  create: true

serviceAccount:
  # -- Specifies whether a ServiceAccount should be created
  create: true
  # -- The name of the ServiceAccount to use.
  # If not set and `create` is true, a name is generated using the fullname template
  name: promtail

# ServiceMonitor configuration
serviceMonitor:
  # -- If enabled, ServiceMonitor resources for Prometheus Operator are created
  enabled: false
# 使用 service-discovery 监视

# -- Section for crafting Promtails config file. The only directly relevant value is `config.file`
# which is a templated string that references the other values and snippets below this key.
# @default -- See `values.yaml`
config:
  # -- The log level of the Promtail server
  # Must be reference in `config.file` to configure `server.log_level`
  # See default config in `values.yaml`
  logLevel: info
  # -- The port of the Promtail server
  # Must be reference in `config.file` to configure `server.http_listen_port`
  # See default config in `values.yaml`
  serverPort: 3101
  # -- The config of clients of the Promtail server
  # Must be reference in `config.file` to configure `clients`
  # @default -- See `values.yaml`
  clients:
  # loki-write 服务
    - url: http://loki-write/loki/api/v1/push
  snippets:
    pipelineStages:
      - docker: {}
```
注意，由于使用的是 Docker 而非 CRI 标准，因此，此处日志 pipeline 应使用 docker，而非默认的 cri。

使用 helm 安装即可：
```
helm upgrade --install -f pt-values.yaml promtail promtail 
```

安装后，会出现 promtail 的  DaemonSet。

Promtail 默认会抓取所有的 日志文件。并将其推送至 Loki。

为 promtail-metrics 服务 添加 promtheus.io 的 annotations:
```
kubectl annotate svc/promtail-metrics prometheus.io/scrape=true
```
由于 promtail 端口定义名为 http-metrics，路径为 metrics，不需要额外配置。


### 7.7 与Grafana集成

Loki 与 grafana 集成很简单，在数据源中添加 Loki 数据源即可。
数据源地址写服务域名，端口号：`http://loki-read.loki.svc:80` 即可。

此后就可以在 explore 中查询 日志了。

#### 7.7.1 LogQL

LogQL 和 PromQL 很相似。区别在于它使用管道符来执行日志特殊的操作。

首先要选择一个 日志流 (Stream)，这里的流的概念采用了 Prometheus 的 Metric 操作方式，即通过一组标签来选择：
```
{job='loki-write', instance='loki-write-0'} 
```

日志解析出来的标签都可以使用。也可以使用 PromQL中的各类操作如 `~ !`等比较。

流选择之后，对流内容进行检索、解析。比如，想在流中搜索 'error'。使用
`{job='loki/loki-write', pod='loki-write-0'} |='error'`

对流进一步格式化，可以使用相应的格式化，比如，Loki 使用 Logfmt 格式日志，那么可以再解析，进一步选择解析后的 标签：
`{job='loki/loki-write', pod='loki-write-0'} | logfmt | level = 'error'`

如果要统计一段时间内的日志数量、增长率等，可以使用 sum/rate 等类PromQL 的查询语句，构建Grafana Dashboard时通常会用到这些。


#### 7.7.2 Promtail 提取标签

在 LogQL 中可以对日志流进一步执行格式解析，提取标签，如上例使用 `| logfmt`，那么，是否可以在 Promtail 即完成标签提取呢？ 

使用 math 可以选择一个日志流，并对其进一步解析：
```yaml
pipeline_stages:
  - docker: {}
  - match:
      selector: '{job="loki/loki-read"}'
      pipeline_name: "loki-read"
      stages:
      - logfmt:
          mapping:
            timestamp: ts
            level:
            caller:
            component:
      - labels:
          timestamp: ts
          level:
          caller:
          component: 
```

如上，首先使用 docker 格式解析数据，在针对 loki-read 日志，使用 logfmt 格式解析，并提取 `ts, level, caller, component`作为标签。

假如存在其他格式的日志，也可参照此方式进行处理。比如：典型的 logback 日志。

针对不同应用 的流水线配置，最好是采用类似 Prometheus Operator 的方式进行动态管理，为此，将在 `Ansible Operator` 部分加以解释。


#### 7.7.3 Pipeline 自动配置

当系统中存在很多不同日志格式的应用时，为这些应用日志单独定义 Pipeline 解析标签，会显得很不方便：pipeline 配置只能写在配置文件中，每次都需要针对不同的应用修改配置。

幸运的是，Promtail 完全照搬了 Prometheus的服务发现机制，因此，参考 Prometheus 的自动服务发现配置，可以为 Promtail 日志解析找到出路。

一个集群中，应尽量去统一日志格式，比如，golang各类应用通常使用 logfmt 格式。Spring应用通常采用 logback 标准格式，或者为了方便 ELK 而采用 Json格式。如果能够全部统一，自然不在需要单独的配置了。即使有差异，这种差异是可以调整到较少的几种格式下(流行的格式)。

因此，针对组织内约定的日志格式，配置相应的 Pipeline 是可行的，完备的。比如：
- logfmt
- json 
- logback
- nginx
之后，只需要模仿 Prometheus 服务发现机制，使用 annotations来声明即可，如：
```yaml
  annotations:
    promtail/scrape: "true"
    promtail/pipeline: "logfmt"
```
就可以在配置中进行处理，如：
```yaml
# relabel config 
# Drop promtail/scrape: false 
  - action: drop 
    source_labels:
      - __meta_kubernetes_pod_annotationpresent_promtail_scrape
      - __meta_kubernetes_pod_annotation_promtail_scrape
    separator: ;
    regex: (true;false)
    # promtail/pipeline as match label.
    - action: replace 
      source_labels:
        - __meta_kubernetes_pod_annotationpresent_promtail_pipeline
        - __meta_kubernetes_pod_annotation_promtail_pipeline
      regex: (true);(.+)
      replacement: $2 
      target_label: promtail_pipeline_name
```
注意，这里使用的是 pod 的 annotation
在 pipeline 部分，使用 match: 
```yaml
  - match:
  # 使用 提取的 pipeline_name 作为选择符。
    selector: "{promtail_pipeline_name='logfmt'}"
    pipeline_name: "logfmt"
    stages:
    - logfmt:
        mapping:
        # ...
    - labels:
        # ...
    # Drop promtail_pipeline_name
    - labeldrop:
      - promtail_pipeline_name
```
这样就可以通过声明来配置 日志解析了。

该方法不够完美的问题点在于：
- 在 pod 上添加 annotaions，会导致Pod重建。(不像Service那样完全无影响)
- 需要提前规划好 pipeline。添加新的 pipeline必须修改配置。

有一个开源项目 Log Operator和 Loki Operator, 个人觉得，为日志单独启动一个CRD管理并非必要。上面的方式已经可以满足定制需要了。

另外的两个relabel 配置是：
```yaml
# drop Pending pod
  - action: drop 
    source_labels:
      - __meta_kubernetes_pod_phase
    separator: ;
    regex: Pending
  # Drop Succeed Job 。
  - action: drop 
    source_labels:
      - __meta_kubernetes_pod_controller_kind
      - __meta_kubernetes_pod_phase
    separator: ;
    regex: Job;Succeeded
```
分别drop掉 Pending 状态的 Pod（这时还没有日志产生）、Job 产生的日志(这种日志可能已经被清理会导致promtail 频繁写 error 日志)。

以上配置可见`pt-values.yaml`。


### 7.8 数据保存周期

#### 7.8.1 tablemamager

#### 7.8.2 compactor 

### 7.9 对接 K8S Event

K8S 的 events 是很重要的信息来源，当节点和资源发生变化时，会记录事件。

需要将 K8S 事件接入到监控体系中，这里引入一个新的 exporter: `kubernetes-event-exporter`

KEE 支持将 events 提取出来，并分发到多种通道。从目前项目情况来看，仍存在一些 事件重复的现象，但就目前开源体系来看，KEE是较好的一个项目了。

本文将 K8S Events数据接入Loki。另一个选择是接入 AlertManager，这种选择的问题是，Events警告无法消除，如果能通过某种规则引擎来计算的话，就更为理想了。 

7.9.1 Exporter 配置

项目地址： https://github.com/resmoio/kubernetes-event-exporter

配置包括两部分，事件路由 (routes) 和 接收方 (receivers)，即：哪些 事件(通过名空间、类型等筛选) 需要 转发至 哪里。
```yaml
routes:
  - route:
      match: 
        receiver:
          loki 
receivers:
  - name: loki
    webhook:
      endpoint: ...
    ... 
```
以 webhook 方式 push 到 loki。

#### 7.9.2 Loki push api 

Loki distributor 提供 push api，支持 JSON POST 格式日志流。

官网原文如下：
> Alternatively, if the Content-Type header is set to application/json, a JSON post body can be sent in the following format:
```json
{
  "streams": [
    {
      "stream": {
        "label": "value"
      },
      "values": [
          [ "<unix epoch in nanoseconds>", "<log line>" ],
          [ "<unix epoch in nanoseconds>", "<log line>" ]
      ]
    }
  ]
}
```

#### 7.9.3 Receiver 配置 

KEE 提供了 layout 来定义webhook 的请求信息。loki receiver 需要组成符合 loki push 要求的格式。
```yaml
receivers:
  - name: loki
    webhook:
      # loki-write 服务 
      endpoint: http://loki-write.loki.svc/loki/api/v1/push 
      layout: 
        # loki push json 格式。
        streams: 
        - stream: 
        # 以下为 stream 标签
        # stream 使用 events以与其他日志区别。
        # 其他Docker 日志均为 stdout/err
            stream: events
            # 从 event 对象 提取 属性。 
            type: "{{ .Type }}"
            reason: "{{ .Reason }}"
            namespace: "{{ .InvolvedObject.Namespace }}"
            kind: "{{ .InvolvedObject.Kind }}"
            resourceName: "{{ .InvolvedObject.Name }}"
            node_name: "{{ .Source.Host }}"
            component: "{{ .Source.Component }}"
            # time: "{{ .Metadata.CreationTimestamp }}"
          values:
          # [["unix nano", " log messgae "],[ next log ]] 
            # 将时间转成 Unix UTC 纳秒。
          - - "{{ .CreationTimestamp.UnixNano }}"
            #  日志内容
            - "time={{ .CreationTimestamp }} count={{ .Count }} msg={{ .Message }}"
          
```

这将把数据推送至 Loki 服务。


> 日志内容 采用了 logfmt 的形式，应考虑补充其他信息如：type, reason, namespace, name 等 增加可读性。

> 进一步配置可关注 过期时间 配置。 

#### 7.9.4 使用 Helm 安装

bitnami 提供了 一个简单的 Chart：
```
$ helm repo add bitnami https://charts.bitnami.com/bitnami
$ helm install -f fee-avlues.yaml -n monitor <releaseName> bitnami/kubernetes-event-exporter
```

配置 自定义 的 values 文件，重点在 config 部分，参见上文。

#### 7.9.5 使用 stdout 

另一个办法是将 日志输出到 stdout 。这样就可以通过 promtail 采集日志方式 收集 events了。

```yaml
receivers:
  - name: stdout 
    stdout: {}
    # 使用 layout 定义输出格式。
```
之后再使用 promtail 采集日志，配置 pipeline 可以解析出 type/reason 等几个信息。

#### 7.9.6 Grafana 查询

使用 grafana explore loki 数据，使用 label filter {stream='events'} 就可以看到 数据了。

#### 7.10 小结

至此，采用 PLG(Promtail-Loki-Grafana) 的 日志采集、查询工具栈已介绍完。
与 Promteheus 类似，可以使用 简单声明方式定制日志解析方法。这样可简化应用部署工作。

有一个组件没有提及的是关于 Loki 的 ruler 和 告警，这些告警也和 Grafana 的告警机制有关。

告警规则属于运维时需要按需定制的工作，首先可以借鉴开源的产品Ruler，再根据自己应用的特性规划告警。这部分知识背景庞杂，需要经验的积累。

而告警的推送是另一个话题，重点在于:
- 使用何种推送途径
- 如何将不同的信息推送至不同的目的地(人)

另外，告警不是越多越好，而是越少越好(至少，高等级的告警越少越好)，因而告警规则的级别因谨慎定义。

## 8. 其他

### 8.1 为 Pod 设置资源

### 8.3 安全context

### 8.3 Projection 卷

### 8.4 Job
 
## 9. 回顾

### 9.1 快速部署示例

使用 minikube 搭建本节的示例快速开始：
1. 安装 minikube 并启动。
2. 创建 nfs 服务。
3. 部署 nfs-subdir-provisioner
4. 使用helm 安装 prometheus-operator
5. 安装 grafana 
6. 安装 Minio
7. 安装 Loki 
8. 安装 Promtial.