Merge pull request #27229 from pmorie/pod-manager-godoc

Automatic merge from submit-queue

Godoc for kubelet pod manager

Improve godoc for pod manager and mirror client.

@kubernetes/sig-node

pkg/kubelet/pod/manager.go

@@ -24,49 +24,79 @@ import (
 	"k8s.io/kubernetes/pkg/types"
 )
 
-// Pod manager stores and manages access to the pods.
+// Manager stores and manages access to pods, maintaining the mappings
+// between static pods and mirror pods.
 //
-// Kubelet discovers pod updates from 3 sources: file, http, and apiserver.
+// The kubelet discovers pod updates from 3 sources: file, http, and
-// Pods from non-apiserver sources are called static pods, and API server is
+// apiserver. Pods from non-apiserver sources are called static pods, and API
-// not aware of the existence of static pods. In order to monitor the status of
+// server is not aware of the existence of static pods. In order to monitor
-// such pods, kubelet creates a mirror pod for each static pod via the API
+// the status of such pods, the kubelet creates a mirror pod for each static
-// server.
+// pod via the API server.
 //
 // A mirror pod has the same pod full name (name and namespace) as its static
 // counterpart (albeit different metadata such as UID, etc). By leveraging the
-// fact that kubelet reports the pod status using the pod full name, the status
+// fact that the kubelet reports the pod status using the pod full name, the
-// of the mirror pod always reflects the actual status of the static pod.
+// status of the mirror pod always reflects the actual status of the static
-// When a static pod gets deleted, the associated orphaned mirror pod will
+// pod. When a static pod gets deleted, the associated orphaned mirror pod
-// also be removed.
+// will also be removed.
-
 type Manager interface {
+	// GetPods returns the regular pods bound to the kubelet and their spec.
 	GetPods() []*api.Pod
+	// GetPodByName returns the (non-mirror) pod that matches full name, as well as
+	// whether the pod was found.
 	GetPodByFullName(podFullName string) (*api.Pod, bool)
+	// GetPodByName provides the (non-mirror) pod that matches namespace and
+	// name, as well as whether the pod was found.
 	GetPodByName(namespace, name string) (*api.Pod, bool)
+	// GetPodByUID provides the (non-mirror) pod that matches pod UID, as well as
+	// whether the pod is found.
 	GetPodByUID(types.UID) (*api.Pod, bool)
+	// GetPodByMirrorPod returns the static pod for the given mirror pod and
+	// whether it was known to the pod manger.
 	GetPodByMirrorPod(*api.Pod) (*api.Pod, bool)
+	// GetMirrorPodByPod returns the mirror pod for the given static pod and
+	// whether it was known to the pod manager.
 	GetMirrorPodByPod(*api.Pod) (*api.Pod, bool)
+	// GetPodsAndMirrorPods returns the both regular and mirror pods.
 	GetPodsAndMirrorPods() ([]*api.Pod, []*api.Pod)
-
 	// SetPods replaces the internal pods with the new pods.
 	// It is currently only used for testing.
 	SetPods(pods []*api.Pod)
-
+	// AddPod adds the given pod to the manager.
-	// Methods that modify a single pod.
 	AddPod(pod *api.Pod)
+	// UpdatePod updates the given pod in the manager.
 	UpdatePod(pod *api.Pod)
+	// DeletePod deletes the given pod from the manager.  For mirror pods,
+	// this means deleting the mappings related to mirror pods.  For non-
+	// mirror pods, this means deleting from indexes for all non-mirror pods.
 	DeletePod(pod *api.Pod)
-
+	// DeleteOrphanedMirrorPods deletes all mirror pods which do not have
+	// associated static pods. This method sends deletion requests to the API
+	// server, but does NOT modify the internal pod storage in basicManager.
 	DeleteOrphanedMirrorPods()
+	// TranslatePodUID returns the UID which is the mirror pod or static pod
+	// of the pod with the given UID.  If the UID belongs to a mirror pod,
+	// returns the UID of its static pod.  If the UID belongs to a static pod,
+	// returns the UID of its mirror pod.  Otherwise, returns the original UID.
+	//
+	// All public-facing functions should perform this translation for UIDs
+	// because user may provide a mirror pod UID, which is not recognized by
+	// internal Kubelet functions.
 	TranslatePodUID(uid types.UID) types.UID
+	// GetUIDTranslations returns the mappings of static pod UIDs to mirror pod
+	// UIDs and mirror pod UIDs to static pod UIDs.
 	GetUIDTranslations() (podToMirror, mirrorToPod map[types.UID]types.UID)
+	// IsMirrorPodOf returns true if mirrorPod is a correct representation of
+	// pod; false otherwise.
 	IsMirrorPodOf(mirrorPod, pod *api.Pod) bool
+
 	MirrorClient
 }
 
-// All maps in basicManager should be set by calling UpdatePods();
+// basicManager is a functional Manger.
-// individual arrays/maps are not immutable and no other methods should attempt
+//
-// to modify them.
+// All fields in basicManager are read-only and are updated calling SetPods,
+// AddPod, UpdatePod, or DeletePod.
 type basicManager struct {
 	// Protects all internal maps.
 	lock sync.RWMutex
@@ -87,6 +117,7 @@ type basicManager struct {
 	MirrorClient
 }
 
+// NewBasicPodManager returns a functional Manager.
 func NewBasicPodManager(client MirrorClient) Manager {
 	pm := &basicManager{}
 	pm.MirrorClient = client
@@ -118,6 +149,9 @@ func (pm *basicManager) UpdatePod(pod *api.Pod) {
 	pm.updatePodsInternal(pod)
 }
 
+// updatePodsInternal replaces the given pods in the current state of the
+// manager, updating the various indices.  The caller is assumed to hold the
+// lock.
 func (pm *basicManager) updatePodsInternal(pods ...*api.Pod) {
 	for _, pod := range pods {
 		podFullName := kubecontainer.GetPodFullName(pod)
@@ -151,14 +185,12 @@ func (pm *basicManager) DeletePod(pod *api.Pod) {
 	}
 }
 
-// GetPods returns the regular pods bound to the kubelet and their spec.
 func (pm *basicManager) GetPods() []*api.Pod {
 	pm.lock.RLock()
 	defer pm.lock.RUnlock()
 	return podsMapToPods(pm.podByUID)
 }
 
-// GetPodsAndMirrorPods returns the both regular and mirror pods.
 func (pm *basicManager) GetPodsAndMirrorPods() ([]*api.Pod, []*api.Pod) {
 	pm.lock.RLock()
 	defer pm.lock.RUnlock()
@@ -172,8 +204,6 @@ func (pm *basicManager) getAllPods() []*api.Pod {
 	return append(podsMapToPods(pm.podByUID), podsMapToPods(pm.mirrorPodByUID)...)
 }
 
-// GetPodByUID provides the (non-mirror) pod that matches pod UID, as well as
-// whether the pod is found.
 func (pm *basicManager) GetPodByUID(uid types.UID) (*api.Pod, bool) {
 	pm.lock.RLock()
 	defer pm.lock.RUnlock()
@@ -181,15 +211,11 @@ func (pm *basicManager) GetPodByUID(uid types.UID) (*api.Pod, bool) {
 	return pod, ok
 }
 
-// GetPodByName provides the (non-mirror) pod that matches namespace and name,
-// as well as whether the pod was found.
 func (pm *basicManager) GetPodByName(namespace, name string) (*api.Pod, bool) {
 	podFullName := kubecontainer.BuildPodFullName(name, namespace)
 	return pm.GetPodByFullName(podFullName)
 }
 
-// GetPodByName returns the (non-mirror) pod that matches full name, as well as
-// whether the pod was found.
 func (pm *basicManager) GetPodByFullName(podFullName string) (*api.Pod, bool) {
 	pm.lock.RLock()
 	defer pm.lock.RUnlock()
@@ -197,10 +223,6 @@ func (pm *basicManager) GetPodByFullName(podFullName string) (*api.Pod, bool) {
 	return pod, ok
 }
 
-// If the UID belongs to a mirror pod, maps it to the UID of its static pod.
-// Otherwise, return the original UID. All public-facing functions should
-// perform this translation for UIDs because user may provide a mirror pod UID,
-// which is not recognized by internal Kubelet functions.
 func (pm *basicManager) TranslatePodUID(uid types.UID) types.UID {
 	if uid == "" {
 		return uid
@@ -239,9 +261,6 @@ func (pm *basicManager) getOrphanedMirrorPodNames() []string {
 	return podFullNames
 }
 
-// Delete all mirror pods which do not have associated static pods. This method
-// sends deletion requets to the API server, but does NOT modify the internal
-// pod storage in basicManager.
 func (pm *basicManager) DeleteOrphanedMirrorPods() {
 	podFullNames := pm.getOrphanedMirrorPodNames()
 	for _, podFullName := range podFullNames {
@@ -249,7 +268,6 @@ func (pm *basicManager) DeleteOrphanedMirrorPods() {
 	}
 }
 
-// Returns true if mirrorPod is a correct representation of pod; false otherwise.
 func (pm *basicManager) IsMirrorPodOf(mirrorPod, pod *api.Pod) bool {
 	// Check name and namespace first.
 	if pod.Name != mirrorPod.Name || pod.Namespace != mirrorPod.Namespace {

pkg/kubelet/pod/mirror_client.go

@@ -25,23 +25,30 @@ import (
 	kubetypes "k8s.io/kubernetes/pkg/kubelet/types"
 )
 
-// Mirror client is used to create/delete a mirror pod.
+// MirrorClient knows how to create/delete a mirror pod in the API server.
 type MirrorClient interface {
-	CreateMirrorPod(*api.Pod) error
+	// CreateMirrorPod creates a mirror pod in the API server for the given
-	DeleteMirrorPod(string) error
+	// pod or returns an error.  The mirror pod will have the same annotations
+	// as the given pod as well as an extra annotation containing the hash of
+	// the static pod.
+	CreateMirrorPod(pod *api.Pod) error
+	// DeleteMirrorPod deletes the mirror pod with the given full name from
+	// the API server or returns an error.
+	DeleteMirrorPod(podFullName string) error
 }
 
+// basicMirrorClient is a functional MirrorClient.  Mirror pods are stored in
+// the kubelet directly because they need to be in sync with the internal
+// pods.
 type basicMirrorClient struct {
-	// mirror pods are stored in the kubelet directly because they need to be
-	// in sync with the internal pods.
 	apiserverClient clientset.Interface
 }
 
+// NewBasicMirrorClient returns a new MirrorClient.
 func NewBasicMirrorClient(apiserverClient clientset.Interface) MirrorClient {
 	return &basicMirrorClient{apiserverClient: apiserverClient}
 }
 
-// Creates a mirror pod.
 func (mc *basicMirrorClient) CreateMirrorPod(pod *api.Pod) error {
 	if mc.apiserverClient == nil {
 		return nil
@@ -65,7 +72,6 @@ func (mc *basicMirrorClient) CreateMirrorPod(pod *api.Pod) error {
 	return err
 }
 
-// Deletes a mirror pod.
 func (mc *basicMirrorClient) DeleteMirrorPod(podFullName string) error {
 	if mc.apiserverClient == nil {
 		return nil