# 官方示例 pods/simple-pod.yaml

apiVersion: v1
kind: Pod
metadata:
  name: nginx
spec:
  containers:
  - name: nginx
    image: nginx:1.14.2
    ports:
    - containerPort: 80

$ kubectl apply -f https://k8s.io/examples/pods/simple-pod.yaml

func (kl *Kubelet) syncLoop(ctx context.Context, updates <-chan kubetypes.PodUpdate, handler SyncHandler) {
	// Pod 同步定时器: 每秒一次
	syncTicker := time.NewTicker(time.Second)
	defer syncTicker.Stop()
	
	// Pod 异常清理定时器: 每 2 秒一次
	housekeepingTicker := time.NewTicker(housekeepingPeriod)
	defer housekeepingTicker.Stop()
	
	...

	for {
		...
		
		// 记录同步开始时间
		kl.syncLoopMonitor.Store(kl.clock.Now())
		// 调用 syncLoopIteration 方法执行具体的同步操作
		if !kl.syncLoopIteration(ctx, updates, handler, syncTicker.C, housekeepingTicker.C, plegCh) {
			break
		}
		// 记录同步结束时间
		kl.syncLoopMonitor.Store(kl.clock.Now())
	}
}

func (kl *Kubelet) syncLoopIteration(ctx context.Context, <-chan ...) bool {
	// 处理不同事件
	// 哪个事件来了算哪个 :-)
	select {
	case u, open := <-configCh:
		// 来自 {文件系统, ApiServer, HTTP} 的 Pod 变更事件
		// 再次检测具体的事件类型 (创建、删除、更新等)
		switch u.Op {
		case kubetypes.ADD:
			// 创建 Pods
			handler.HandlePodAdditions(u.Pods)
		case kubetypes.UPDATE:
			// 更新 Pods
			handler.HandlePodUpdates(u.Pods)
		case kubetypes.REMOVE:
			// 直接删除 Pods
			handler.HandlePodRemoves(u.Pods)
		case kubetypes.RECONCILE:
			// 协调 Pods
			handler.HandlePodReconcile(u.Pods)
		case kubetypes.DELETE:
			// 优雅删除 Pods
			// 不同于上面的直接删除操作
			// 注意: 这里的删除使用的是先更新、后删除操作，实现优雅删除
			handler.HandlePodUpdates(u.Pods)
		}

		kl.sourcesReady.AddSource(u.Source)

	case e := <-plegCh:
		// 更新运行时缓存
		if isSyncPodWorthy(e) {
			if pod, ok := kl.podManager.GetPodByUID(e.ID); ok {
				// 同步 Pod 的运行时状态
				handler.HandlePodSyncs([]*v1.Pod{pod})
			}
		}

		if e.Type == pleg.ContainerDied {
			// 如果是需要更新 Pod 内部的容器运行时
			// 直接删除当前运行的容器
			if containerID, ok := e.Data.(string); ok {
				kl.cleanUpContainersInPod(e.ID, containerID)
			}
		}
	case <-syncCh:
		// 定时同步 Pod
		podsToSync := kl.getPodsToSync()
		handler.HandlePodSyncs(podsToSync)
	case update := <-kl.livenessManager.Updates():
		// 存活探针检测失败的 Pod
		if update.Result == proberesults.Failure {
			handleProbeSync(kl, update, handler, "liveness", "unhealthy")
		}
	case update := <-kl.readinessManager.Updates():
		// 就绪探针检测失败的 Pod
		ready := update.Result == proberesults.Success
		handleProbeSync(kl, update, handler, "readiness", status)
	case update := <-kl.startupManager.Updates():
		// 启动探针检测失败的 Pod
		started := update.Result == proberesults.Success
		handleProbeSync(kl, update, handler, "startup", status)
	case <-housekeepingCh:
		// 清理 Pod
		if !kl.sourcesReady.AllReady() {
			// 如果资源还未就绪，无需清理
		} else {
			// 开始清理 Pods
			if err := handler.HandlePodCleanups(ctx); err != nil {
				klog.ErrorS(err, "Failed cleaning pods")
			}
		}
	}
	return true
}

func (kl *Kubelet) HandlePodAdditions(pods []*v1.Pod) {
	// 根据 Pod 的创建时间进行排序
	// 因为上文中提到，主循环中的事件处理依赖于 channel 的读取，无法保证顺序
	sort.Sort(sliceutils.PodsByCreationTime(pods))
	
	// 遍历要创建的 Pod 列表
	for _, pod := range pods {
		// 直接将 Pod 添加到专门的 Pod 管理器中
		// 因为 kubelet 依赖于从 Pod 管理器获取期望状态
		// 如果一个 Pod 不存在于 Pod 管理器中
		// 也就意味着该 Pod 已经从 ApiServer 中被删除了，不需要执行其他额外操作了
		kl.podManager.AddPod(pod)
		
		// 将创建 Pod 的操作分发到 podWorkers.UpdatePod 方法
		kl.podWorkers.UpdatePod(UpdatePodOptions{
			Pod:        pod,
			MirrorPod:  mirrorPod,
			UpdateType: kubetypes.SyncPodCreate,
			StartTime:  start,
		})
	}
}

func (p *podWorkers) UpdatePod(options UpdatePodOptions) {
	...
	
	status, ok := p.podSyncStatuses[uid]
	if !ok {
		// 如果当前 Pod 不存在于 Pod 状态中
		// 就先创建对应的 Pod 状态
		status = &podSyncStatus{
			syncedAt: now,
			fullname: kubecontainer.BuildPodFullName(name, ns),
		}
		...
		p.podSyncStatuses[uid] = status
	}

    ...

	// Pod 已经完成并终止
	// 此时 Pod 状态不能被更新，直到 Pod UID 被清除
	if status.IsFinished() {
		return
	}

	// 检测 Pod 状态是否需要转换到终止
    ...
	
	// 终于走到核心流程了
	// 如果 Pod 不存在，就启动一个 goroutine 创建
	podUpdates, exists := p.podUpdates[uid]
	if !exists {
		podUpdates = make(chan struct{}, 1)
		p.podUpdates[uid] = podUpdates

        ...
		
		// 单独的 goroutine 创建 Pod
		go func() {
			// 调用 podWorkerLoop 方法
			p.podWorkerLoop(uid, outCh)
		}()
	}

	...
}

func (p *podWorkers) podWorkerLoop(podUID types.UID, podUpdates <-chan struct{}) {
	// 遍历更新的 Pod channel
	for range podUpdates {
		// 小技巧: 将复杂的 switch 条件分支语句放入一个匿名函数执行
		// 匿名方法是 Pod 同步操作的核心部分
		err := func() error {
            ...
			
			switch {
			case update.WorkType == TerminatedPod:
				// Pod 正在终止中

			case update.WorkType == TerminatingPod:
				// Pod 已经终止

			default:
				// Pod 创建
				// 调用 Kubelet.SyncPod 方法创建
				isTerminal, err = p.podSyncer.SyncPod(ctx, ...)
			}
			
			return err
		}()

		...
	}
}

func (kl *Kubelet) SyncPod(ctx context.Context, ...) (isTerminal bool, err error) {
	...

	// 将 Pod 的状态同步到 statusManager 对象
	kl.statusManager.SetPodStatus(pod, apiPodStatus)

	// 如果 Pod 没有达到运行条件
	// 直接返回错误
	// Pods that are not runnable must be stopped - return a typed error to the pod worker
	if !runnable.Admit {
        ...
		return false, syncErr
	}

	// 如果 CNI 插件未就绪
	// 那么只有 Pod 的网络模式为 Host 时，才可以创建 (Pod 使用宿主机的 Network Namespace)
	//   其他情况直接返回错误
	if err := kl.runtimeState.networkErrors(); err != nil && !kubecontainer.IsHostNetworkPod(pod) {
		return false, fmt.Errorf("%s: %v", NetworkNotReadyErrorMsg, err)
	}

	// 如果 kubelet 启动时开启了 cgroups-per-qos 
	//   如果 Pod 还未创建过对应的 Cgroups 资源控制
	//     创建对应的 Cgroups 资源控制
	//   对于已经创建过 Cgroups 资源控制，但是已经终止的 Pod
	//     直接复用之前的 Cgroups 资源控制即可
	pcm := kl.containerManager.NewPodContainerManager()
	if !kl.podWorkers.IsPodTerminationRequested(pod.UID) {
        ...
	}

	...

	// 创建 Pod 对应的数据目录
	if err := kl.makePodDataDirs(pod); err != nil {
        ...
	}

	// 等待卷目录挂载完成
	if err := kl.volumeManager.WaitForAttachAndMount(ctx, pod); err != nil {
        ...
	}

	// 拉取 Pod 对应的 Secrets
	pullSecrets := kl.getPullSecretsForPod(pod)

	// 添加 Pod 的探针检测
	// 探针实现细节请参考之前的文章: https://dbwu.tech/posts/k8s/source_code/prober/
	kl.probeManager.AddPod(pod)
	
	// 调用 CRI 创建 Pod
	// CRI 设计可以参考之前的文章: https://dbwu.tech/posts/k8s/source_code/cri/
	result := kl.containerRuntime.SyncPod(todoCtx, pod, podStatus, pullSecrets, kl.backOff)
	
	...

	return false, nil
}