Mantra Networking Mantra Networking

Kubernetes: Controller Manager

Kubernetes: Controller Manager
Created By: Lauren R. Garcia

Table of Contents

  • Overview
  • Core Components
  • Controller Manager Types
  • Configuration
  • Best Practices
  • Useful Commands
  • Troubleshooting
  • Conclusion

Kubernetes: Controller Manager Overview

What Is the Controller Manager?

The Controller Manager is a central component of the Kubernetes control plane. Its primary role is to run controller processes that continuously regulate the state of the cluster, ensuring that actual conditions match the specifications defined in Kubernetes objects. Instead of having separate processes for each controller, Kubernetes consolidates them within the Controller Manager, simplifying management and improving efficiency.

Why You Need to Know About It

  • Cluster Health & Automation: The Controller Manager automates routine cluster maintenance tasks, responding automatically to changes and failures—like replacing failed pods or nodes—helping maintain desired workloads without manual intervention.
  • Reliability: Understanding how the Controller Manager functions is critical for diagnosing issues, tuning performance, and designing robust, highly available environments.
  • Customization & Scaling: Knowledge of this component allows operators to customize controller behavior, implement advanced automation, and scale workloads in line with business needs.

How It Works

  • Continuous Reconciliation: The Controller Manager runs numerous controllers. Each controller watches the Kubernetes API server for changes and strives to ensure the current state matches the desired state as defined in resource specifications.
  • Types of Controllers: Examples include the Replication Controller (ensuring a specified number of pods are running), Node Controller (monitoring node health), Job Controller (managing batch jobs), and others.
  • Event-Driven Response: Whenever a change or discrepancy is detected (e.g., a pod crash, a node failure, or a scaling event), the Controller Manager initiates corrective actions to restore the cluster to its intended state.
  • High Availability: For production clusters, multiple Controller Manager instances can be run with leader election to ensure continuity in case one instance fails.

By acting as the automation engine behind the scenes, the Controller Manager keeps Kubernetes clusters self-healing, robust, and easy to operate, making it an indispensable part of modern cloud-native infrastructure.

Core Components

These are the essential building blocks that enable Kubernetes to orchestrate, schedule, and manage containerized workloads in a cluster:

  • API Server: Exposes the Kubernetes API, acting as the cluster’s front end. It processes both internal and external REST requests, validates them, and communicates with other components to enforce the desired state of the cluster.
  • etcd: Provides a reliable and highly available distributed key-value store that securely stores all cluster configuration data, state, and metadata for Kubernetes.
  • Controller Manager: Runs controllers that monitor the cluster and drive changes to move current state toward the desired state, handling tasks like node management, replication, and resource tracking.
  • Scheduler: Watches for newly created pods and assigns them to optimal nodes in the cluster based on resource requirements, policies, and constraints.
  • Kubelet: An agent that runs on each node, ensuring containers defined in pod specifications are running and healthy. It acts as the bridge between the control plane and the actual containers.
  • Kube-proxy: Maintains network rules on nodes, facilitating seamless communication for pods and services by managing traffic routing within and outside the cluster.
  • Container Runtime: Software on each node responsible for running and managing containers. Common examples include containerd and CRI-O.

Controller Manager Types

Kubernetes uses different controller managers to handle various aspects of cluster management by running multiple controllers in a single process or separately:

  • Node Controller: Monitors the health of nodes, detects when nodes go down, and takes necessary actions like marking them unavailable.
  • Replication Controller: Ensures the desired number of pod replicas are running at any given time, creating or deleting pods as needed to match the specified count.
  • Endpoints Controller: Manages service endpoints by keeping track of which pods are matched to a service and updating the endpoint objects accordingly.
  • Service Account & Token Controllers: Automate the creation of default service accounts and API access tokens within namespaces for pod authentication.
  • DaemonSet Controller: Ensures that a copy of a specific pod runs on all or selected nodes, typically used for cluster-wide services like logging or monitoring.
  • StatefulSet Controller: Manages the deployment and scaling of pods with unique identities and stable storage for workloads requiring persistent identity.
  • Job Controller: Handles batch or finite task workloads by running one or more pods until successful completion.
  • CronJob Controller: Schedules Jobs to run periodically at specified times, similar to a traditional cron job system.

Configuration

The Controller Manager in Kubernetes is configured to manage the controllers it runs and control their behavior. Configuration is typically done through command-line flags, API objects, and configuration files:

  • Command-line Flags: The Controller Manager binary accepts various flags to enable or disable specific controllers, adjust operation parameters, and configure leader election to ensure high availability.
  • Leader Election: When running multiple instances for redundancy, the Controller Manager uses leader election to ensure only one instance is actively managing controllers at a time.
  • Controller-specific Settings: Some controllers have customizable parameters such as sync periods and retry intervals that can be set to optimize their performance for the cluster’s needs.
  • Configuration via ConfigMaps: In some deployments, additional Controller Manager configurations can be supplied using Kubernetes ConfigMaps, allowing dynamic updates without restarting the process.
  • Run Location: Often deployed as a static pod on the master node(s), the Controller Manager may also run externally with appropriate API access and permissions.

Best Practices

Following best practices helps ensure the Controller Manager operates reliably and efficiently within a Kubernetes cluster:

  • Enable Leader Election: Run multiple instances with leader election enabled to provide high availability and avoid conflicts in controller execution.
  • Limit Controllers as Needed: Disable controllers that are not required for your environment to reduce resource consumption and simplify management.
  • Monitor Controller Health: Continuously track controller performance and status using metrics and logs to detect issues early and maintain cluster stability.
  • Use ConfigMaps for Dynamic Configuration: Supply configuration updates via ConfigMaps wherever possible to avoid downtime caused by restarts after changes.
  • Secure API Access: Ensure the Controller Manager has proper authentication and authorization when interacting with the API server to safeguard cluster operations.
  • Adjust Sync Periods Thoughtfully: Tune controller sync intervals based on workload needs to balance responsiveness and system load.
  • Run on Dedicated Nodes if Possible: Hosting the Controller Manager on master or control plane nodes minimizes interference and improves performance.

Useful Commands

These commands help you interact with and troubleshoot the Controller Manager in a Kubernetes cluster:

  • Check Controller Manager Pods: kubectl get pods -n kube-system -l component=kube-controller-manager Lists the Controller Manager pods running in the kube-system namespace.
  • View Controller Manager Logs: kubectl logs -n kube-system -c kube-controller-manager Shows the logs of a specific Controller Manager pod for debugging and monitoring.
  • Describe Controller Manager Pod: kubectl describe pod -n kube-system Provides detailed information about the Controller Manager pod, including events and status.
  • Check Component Health: kubectl get componentstatuses Reports the health status of critical control plane components, including the Controller Manager.
  • Verify Leader Election Status: Check Controller Manager logs for messages indicating leader election outcomes to confirm which instance is active.
  • Edit Controller Manager Configuration: Depending on your setup, update the static pod manifest file (usually under /etc/kubernetes/manifests) or modify the ConfigMap controlling Controller Manager parameters.
  • Restart Controller Manager: Normally done by restarting the pod or service hosting the Controller Manager to apply configuration changes.

Troubleshooting

Systematic troubleshooting helps you identify and resolve issues with the Controller Manager in Kubernetes clusters. Follow these steps to investigate common problems:

  • Check Controller Manager Status: Use kubectl get pods -n kube-system -l component=kube-controller-manager to verify if the pods are running as expected. Investigate any pods in a non-Running state.
  • Review Logs: Gather detailed logs using kubectl logs -n kube-system <pod-name> -c kube-controller-manager. Look for error messages such as leader election losses, configuration errors, or resource conflicts.
  • Diagnose Health Issues: Run kubectl get componentstatuses to check if the Controller Manager is reporting as healthy. A status of "Unhealthy" may indicate connectivity or resource issues.
  • Examine Leader Election: In high availability clusters, inspect the leader election process. Use kubectl -n kube-system get lease and kubectl -n kube-system describe lease/kube-controller-manager to see recent changes and leadership transitions. Lost leadership can result in restarts and downtime.
  • Resource Constraints: Controller Manager instability can occur if resource limits are too low. Check resource allocations and consider increasing CPU or memory as needed.
  • Port Conflicts: If the pod or process won't start, verify that the required port (such as 10252 or 6443) is not in use by another process on the node. Adjust configuration or stop the conflicting process if needed.
  • Configuration Validation: Review static pod manifests or ConfigMaps to ensure there are no formatting mistakes or invalid field values. Misconfiguration can cause crash loops or prevent updates.
  • Force Pod Restart: When configuration or state appears stuck, delete the affected Controller Manager pod. Kubernetes will automatically recreate it. This can resolve temporary or update-related issues.
  • Monitor via Metrics: Integrate with Prometheus or similar tools to track reconciliation latency, error rates, and resource usage for ongoing insight and early detection of problems.

Conclusion

Throughout this blog post, we've explored the essential role and function of the Controller Manager in Kubernetes. We started by breaking down its core components and how these building blocks work together to maintain cluster health and orchestrate container workloads effectively. We then examined the different types of controllers that the Controller Manager runs to manage nodes, pods, services, and jobs, ensuring the cluster operates according to its desired state.

We also looked at how the Controller Manager is configured through command-line flags, leader election, ConfigMaps, and placement within the cluster to optimize performance and reliability. Best practices were highlighted to help maintain a stable and efficient control plane, from enabling leader election for high availability to monitoring controller health and carefully tuning synchronization intervals.

To assist ongoing cluster management, useful commands were shared to check Controller Manager status, view logs, and update configurations. Lastly, troubleshooting strategies were outlined to identify and resolve common issues such as pod failures, configuration errors, resource constraints, and leader election problems.

Thank you for following along this deep dive into Kubernetes Controller Manager. Understanding and managing this component well is crucial for running resilient and scalable Kubernetes clusters. Happy cluster managing, and may your workloads always stay healthy and responsive!