Cline

# Component Design Standards for Kubernetes This document outlines the coding standards for component design within the Kubernetes ecosystem. It aims to provide clear, actionable guidance for developers to create reusable, maintainable, performant, and secure components. These standards apply to new development and should guide refactoring efforts. ## 1. Architectural Principles ### 1.1. Modularity and Abstraction **Standard:** Design components with well-defined interfaces and minimal dependencies to enhance reusability and reduce coupling. * **Do This:** * Define clear API boundaries using interfaces in Go. * Use dependency injection to decouple components. * Favor composition over inheritance. * **Don't Do This:** * Create monolithic components with intertwined functionalities. * Introduce circular dependencies. * Expose internal implementation details through interfaces. **Why:** Modularity isolates changes, simplifies testing, and improves code reuse. Abstraction reduces complexity by hiding implementation details, allowing for easier maintenance and evolution. **Example:** """go // Good: Defined interface type PodLister interface { ListPods(namespace string) ([]*v1.Pod, error) } type cachedPodLister struct { informer cache.SharedIndexInformer } func (c *cachedPodLister) ListPods(namespace string) ([]*v1.Pod, error) { // Implementation using cached data return nil, nil //Placeholder removal breaks code } // Bad: Direct dependency on concrete type type PodReconciler struct { podLister *cachedPodLister // Concrete type, limits testability } //Good: Dependency on interface type BetterPodReconciler struct { podLister PodLister } func NewBetterPodReconciler(lister PodLister) *BetterPodReconciler { return &BetterPodReconciler{podLister: lister} } """ ### 1.2. Separation of Concerns **Standard:** Divide responsibilities into distinct components with single, well-defined purposes. * **Do This:** * Separate data access logic from business logic. * Isolate API handling from core functionality. * Design controllers to manage specific resources or aspects of the system. * **Don't Do This:** * Combine unrelated functionalities into a single component. * Write controllers that manage multiple, unrelated resource types. * Mix presentation logic with business logic. **Why:** Separation of concerns simplifies debugging, reduces the impact of changes, and enables parallel development. **Example:** """go //Bad: Combining API handling and business logic func HandlePodCreation(w http.ResponseWriter, r *http.Request) { //Parse request //Validate Request //Create Pod in etcd //Write Response } //Good: Separate API handling and business logic func HandlePodCreation(w http.ResponseWriter, r *http.Request, podCreator podCreator) { // Parse request // Validate Request err := podCreator.CreatePod(r.Context(), r.Body) if err != nil { //Handle error return } // Write Response } type podCreator interface { CreatePod(ctx context.Context, body io.ReadCloser) error } """ ### 1.3. Loose Coupling **Standard:** Minimize dependencies between components to improve independence and flexibility. * **Do This:** * Use asynchronous communication patterns (e.g., events, queues) to decouple components. * Define clear interfaces for service interaction. * Use versioned APIs to allow independent evolution of components. * **Don't Do This:** * Create tightly coupled dependencies that require simultaneous updates. * Expose internal data structures between components. * Rely on shared global state. **Why:** Loose coupling simplifies testing, allows for independent scaling, and reduces the risk of cascading failures. **Example:** """go //Bad: Direct function call resulting in tight coupling func ComponentA() { result := ComponentB() // Direct call // use result } //Good: Decoupled using a message queue // Component A publishes a message func ComponentA(queue MessageQueue) { message := Message{Type: "ComponentBRequest", Data: ...} queue.Publish("componentb.requests", message) } // Component B subscribes to the queue and processes messages func ComponentB(queue MessageQueue, processor BProcessor) { queue.Subscribe("componentb.requests", func(message Message) { processor.process(message) }) } """ ### 1.4. Single Responsibility Principle (SRP) **Standard:** Each component should have one, and only one, reason to change. * **Do This:** * Decompose complex components into smaller, focused units. * Ensure each component has a clear and specific purpose. * Refactor components that violate SRP. * **Don't Do This:** * Create "god" classes that handle multiple, unrelated responsibilities. * Add new responsibilities to existing components without careful consideration. **Why:** SRP improves maintainability, reduces complexity, and enhances testability. """go // Bad: A single struct handles both fetching and processing data. type DataHandler struct { Source string } func (dh *DataHandler) FetchData() ([]byte, error) { // Fetches data from dh.Source } func (dh *DataHandler) ProcessData(data []byte) (string, error) { // Processes the fetched data } // Good: Separate structs for fetching and processing data type DataFetcher struct { Source string } func (df *DataFetcher) FetchData() ([]byte, error) { // Fetches data from df.Source } type DataProcessor struct {} func (dp *DataProcessor) ProcessData(data []byte) (string, error) { // Processes the fetched data } """ ## 2. Kubernetes-Specific Considerations ### 2.1. Controller Design **Standard:** Kubernetes controllers should follow the "informer" pattern for efficient resource monitoring and reconciliation. * **Do This:** * Use "SharedIndexInformer" for caching and event handling of Kubernetes resources. * Implement the "Reconcile" function to manage the desired state. * Use work queues to manage events asynchronously. * Leverage client-go library features for interacting with the Kubernetes API. * **Don't Do This:** * Poll the Kubernetes API directly for changes. * Block the reconciliation loop with long-running operations. * Ignore error conditions during reconciliation. **Why:** The informer pattern provides efficient change notifications, reduces API load, and ensures eventual consistency. **Example:** """go // Basic Kubernetes controller structure import ( "context" "fmt" batchv1 "k8s.io/api/batch/v1" corev1 "k8s.io/api/core/v1" "k8s.io/apimachinery/pkg/api/errors" metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" utilruntime "k8s.io/apimachinery/pkg/util/runtime" "k8s.io/apimachinery/pkg/util/wait" batchinformers "k8s.io/client-go/informers/batch/v1" "k8s.io/client-go/kubernetes" "k8s.io/client-go/kubernetes/scheme" batchlisters "k8s.io/client-go/listers/batch/v1" "k8s.io/client-go/tools/cache" "k8s.io/client-go/tools/record" "k8s.io/client-go/util/workqueue" // Import workqueue "k8s.io/klog/v2" "time" ) const controllerAgentName = "sample-controller" const ( // SuccessSynced is used as part of the Event 'reason' when a Foo is synced SuccessSynced = "Synced" // ErrResourceExists is used as part of the Event 'reason' when a Foo fails // to sync due to a Job of the same name already existing. ErrResourceExists = "ErrResourceExists" // MessageResourceExists is the message used for Events when a resource // fails to sync due to a Job already existing MessageResourceExists = "Resource %q already exists and is not managed by Foo" // MessageResourceSynced is the message used for an Event fired when a Foo // is synced successfully MessageResourceSynced = "Foo %q synced successfully" ) // Controller is the controller implementation for Foo resources type Controller struct { // kubeclientset is a standard kubernetes clientset kubeclientset kubernetes.Interface // jobLister is lister for Jobs jobLister batchlisters.JobLister // jobsSynced is a sync for jobs jobsSynced cache.InformerSynced // workqueue is a rate limited work queue. This is used to queue work to be // processed instead of performing it as soon as a change happens. This // means we can ensure we only process a fixed amount of resources at a // time, and makes it easy to ensure we are never overwhelming the system. workqueue workqueue.RateLimitingInterface // recorder is an event recorder for recording Event resources to the // Kubernetes API. recorder record.EventRecorder } // NewController returns a new sample controller func NewController( kubeclientset kubernetes.Interface, jobInformer batchinformers.JobInformer, recorder record.EventRecorder) *Controller { controller := &Controller{ kubeclientset: kubeclientset, jobLister: jobInformer.Lister(), jobsSynced: jobInformer.Informer().HasSynced, workqueue: workqueue.NewNamedRateLimitingQueue(workqueue.DefaultControllerRateLimiter(), "Jobs"), recorder: recorder, } klog.V(4).Info("Setting up event handlers") // Set up event handlers for when Job resources change jobInformer.Informer().AddEventHandler(cache.ResourceEventHandlerFuncs{ AddFunc: controller.enqueueJob, UpdateFunc: func(old, new interface{}) { controller.enqueueJob(new) }, DeleteFunc: controller.enqueueJob, }) return controller } // Run will set up the event handlers for types we are interested in, as well // as syncing informer caches and starting workers. It will block until stopCh // is closed, at which point it will shutdown the workqueue and wait for // workers to finish processing their current work items. func (c *Controller) Run(ctx context.Context, workers int) error { defer utilruntime.HandleCrash() defer c.workqueue.ShutDown() // Start the informer factories to begin populating the informer caches klog.Info("Starting Job controller") // Wait for the caches to be synced before starting workers klog.Info("Waiting for informer caches to sync") if ok := cache.WaitForCacheSync(ctx.Done(), c.jobsSynced); !ok { return fmt.Errorf("failed to wait for caches to sync") } klog.Info("Starting workers") // Launch two workers to process Job resources for i := 0; i < workers; i++ { go wait.Until(c.runWorker, time.Second, ctx.Done()) } klog.Info("Started workers") <-ctx.Done() klog.Info("Shutting down workers") return nil } // runWorker is a long-running function that will continually pull new items // off the workqueue and process them. func (c *Controller) runWorker() { for c.processNextWorkItem() { } } // processNextWorkItem will read a single work item off the workqueue and // attempt to process it. func (c *Controller) processNextWorkItem() bool { // Fetch the next item off the workqueue. obj, shutdown := c.workqueue.Get() if shutdown { return false } // We wrap this block in a func so we can defer c.workqueue.Done. err := func(obj interface{}) error { // We call Done here so the workqueue knows we have finished // processing this item. We also must remember to call Forget if we // do not want this work item being re-queued. For example, we do // not call Forget if a transient error occurs, instead the item is // put back on the workqueue and attempted again after a back-off // period. defer c.workqueue.Done(obj) var key string var ok bool // We expect strings to come off the workqueue. These are of the // form namespace/name. if key, ok = obj.(string); !ok { // As the item in the workqueue is actually invalid, we call // Forget here else we'd go into a loop of attempting to // process a work item that is invalid. c.workqueue.Forget(obj) utilruntime.HandleError(fmt.Errorf("expected string in workqueue but got %#v", obj)) return nil } // Run the syncHandler, passing it the namespace/name string of the // Foo resource to be synced. if err := c.syncHandler(key); err != nil { // Put the item back on the workqueue to handle any transient errors. c.workqueue.AddRateLimited(key) return fmt.Errorf("error syncing '%s': %s, requeuing", key, err.Error()) } // Finally, if no error occurs we Forget this item so it does not // get queued again until another change happens. c.workqueue.Forget(obj) klog.Infof("Successfully synced '%s'", key) return nil }(obj) if err != nil { utilruntime.HandleError(err) return true } return true } // syncHandler compares the actual state with the desired, and attempts to // converge the two. It then updates the Status block of the Foo resource // with the current status of the resource. func (c *Controller) syncHandler(key string) error { // Convert the namespace/name string into a distinct namespace and name namespace, name, err := cache.SplitMetaNamespaceKey(key) if err != nil { utilruntime.HandleError(fmt.Errorf("invalid resource key: %s", key)) return nil } // Get the Job with this namespace/name job, err := c.jobLister.Jobs(namespace).Get(name) if err != nil { // The Job resource may no longer exist, in which case we stop // processing. if errors.IsNotFound(err) { utilruntime.HandleError(fmt.Errorf("job '%s' in work queue no longer exists", key)) return nil } return err } //TODO: Replace with actual controller code klog.Infof("Found job %s/%s", job.Namespace, job.Name) c.recorder.Event(job, corev1.EventTypeNormal, SuccessSynced, MessageResourceSynced) return nil } // enqueueJob takes any resource, converts it into a key formatted string, and // adds the string to the workqueue. func (c *Controller) enqueueJob(obj interface{}) { key, err := cache.MetaNamespaceKeyFunc(obj) if err != nil { utilruntime.HandleError(err) return } c.workqueue.Add(key) } // TODO: Consider alternatives to rate limiting. Discuss implications of exponential backoff in high-volume scenarios (potential for long delays) //AddRateLimited(item interface{}) //Forget(item interface{}) //NumRequeues(item interface{}) int """ ### 2.2. CRD (Custom Resource Definition) Design **Standard:** Design CRDs with clear and well-defined schemas, validation rules, and versioning strategies. * **Do This:** * Use OpenAPI v3 schema for validation of resources. * Implement webhook-based validation for complex business logic that cannot be expressed via OpenAPI. * Implement webhook-based mutation to enforce immutability or set defaults. * Define default values for optional fields. * Use semantic versioning for API changes. * Provide conversion webhooks for migrating resources between API versions. * **Don't Do This:** * Define overly complex or deeply nested schemas. * Introduce breaking changes without a smooth migration path. * Omit validation rules, leading to inconsistent or invalid data. **Why:** Well-designed CRDs provide a consistent and reliable extension mechanism for Kubernetes, improving user experience and reducing operational risks. **Example:** """yaml # Example CRD definition with validation apiVersion: apiextensions.k8s.io/v1 kind: CustomResourceDefinition metadata: name: myresources.example.com spec: group: example.com versions: - name: v1alpha1 schema: openAPIV3Schema: type: object properties: spec: type: object properties: size: type: integer minimum: 1 maximum: 10 image: type: string pattern: "^[a-z0-9-.]*/[a-z0-9-.]*:[a-z0-9-.]*$" served: true storage: true scope: Namespaced names: plural: myresources singular: myresource kind: MyResource shortNames: - mr """ """go // Example Validation Webhook import ( "encoding/json" "net/http" "k8s.io/api/admission/v1" metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" "k8s.io/klog/v2" ) func (wh *WebhookServer) validateMyResource(ar *v1.AdmissionReview) *v1.AdmissionResponse { klog.V(4).Info("Validating MyResource") req := ar.Request var myResource MyResource if err := json.Unmarshal(req.Object.Raw, &myResource); err != nil { klog.Errorf("Could not unmarshal raw object: %v", err) return &v1.AdmissionResponse{ Result: &metav1.Status{ Message: err.Error(), Code: http.StatusBadRequest, }, } } if myResource.Spec.Size > 100 { return &v1.AdmissionResponse{ Allowed: false, Result: &metav1.Status{ Message: "Size cannot be greater than 100", Code: http.StatusForbidden, }, } } return &v1.AdmissionResponse{ Allowed: true, } } """ ### 2.3. Operator Pattern **Standard:** Use the operator pattern to automate complex operational tasks, such as deployments, upgrades, backups, and scaling. * **Do This:** * Encapsulate operational knowledge within the operator. * Use CRDs to define and manage application-specific resources. * Implement reconciliation loops to ensure desired state. * Leverage existing operator frameworks (e.g., Operator SDK, Kubebuilder) to simplify development. * **Don't Do This:** * Create overly complex operators that manage too many unrelated aspects. * Omit comprehensive error handling and logging. * Rely on manual intervention for common operational tasks. **Why:** Operators automate complex tasks, reduce human error, and improve overall system reliability. **Example:** Operator framework such as Kubebuilder and the Operator SDK provides code generation tools to minimize boilerplate. Example uses and generated code are too lengthy to fit here. Please refer to: [https://sdk.operatorframework.io/](https://sdk.operatorframework.io/) [https://kubebuilder.io/](https://kubebuilder.io/) ### 2.4. API Versioning and Compatibility **Standard:** Follow semantic versioning principles for API changes and provide compatibility layers for older versions. * **Do This:** * Increment the major version number for breaking changes. * Increment the minor version number for new features. * Increment the patch version number for bug fixes. * Provide conversion webhooks for seamless migration between API versions. * Deprecate old APIs gradually with proper warnings and migration guides. * **Don't Do This:** * Introduce breaking changes without incrementing the major version number. * Remove deprecated APIs without proper notice. * Omit compatibility layers for older API consumers. **Why:** Proper API versioning ensures smooth upgrades, reduces compatibility issues, and minimizes disruption for existing users. ## 3. Implementation Details ### 3.1. Error Handling **Standard:** Implement robust error handling with clear and informative error messages. * **Do This:** * Use Go's error interface and the "errors" package for custom error types. * Wrap errors with context using "%w" verb in "fmt.Errorf". * Log errors with sufficient context for debugging. * Handle errors gracefully and avoid panics. * **Don't Do This:** * Ignore errors silently. * Use generic error messages without context. * Propagate errors without handling or logging them. **Why:** Proper error handling simplifies debugging, improves system resilience, and provides better operational insights. **Example:** """go // Good: Error wrapping with context func doSomething(ctx context.Context) error { err := someFunc() if err != nil { return fmt.Errorf("failed to do something: %w", err) } return nil } // Bad: Ignoring error func doSomething(ctx context.Context) { someFunc() // potentially ignoring an error condition } """ ### 3.2. Logging **Standard:** Implement structured logging with appropriate levels and contextual information. * **Do This:** * Use a structured logging library (e.g., "klog/v2") for consistent formatting and metadata. * Choose appropriate log levels (e.g., "Info", "Warning", "Error", "Debug") based on severity. * Include relevant context in log messages (e.g., request ID, user ID, resource name). * Avoid logging sensitive information. * **Don't Do This:** * Use unstructured logging with inconsistent formatting. * Log excessive amounts of debug information in production. * Omit contextual information from log messages. **Why:** Structured logging simplifies analysis, improves operational visibility, and facilitates troubleshooting. **Example:** """go // Good: Structured logging with klog import ( "k8s.io/klog/v2" ) func doSomething(name string) error { klog.InfoS("doing something", "name", name) err := someFunc() if err != nil { klog.ErrorS(err, "failed to do something", "name", name) return fmt.Errorf("failed to do something: %w", err) } return nil } // Bad: Unstructured logging func doSomething(name string) error { fmt.Printf("Doing Somethign %s", name) err := someFunc() if err != nil { fmt.Printf("Error: %v", err) return fmt.Errorf("failed to do something: %w", err) } return nil } """ ### 3.3. Concurrency **Standard:** Use Go's concurrency primitives (goroutines, channels, mutexes) to manage concurrent operations safely and efficiently. * **Do This:** * Use goroutines for parallel execution. * Use channels for communication and synchronization between goroutines. * Use mutexes or other synchronization primitives to protect shared resources. * Use the "context" package for cancellation and timeouts. * **Don't Do This:** * Introduce race conditions by accessing shared resources without protection. * Create goroutine leaks by failing to wait for goroutines to complete. * Use global variables for shared state. **Why:** Proper concurrency management improves performance, prevents data corruption, and ensures program stability. **Example:** """go // Good: Using goroutines and channels func processData(data []string) <-chan string { results := make(chan string) go func() { defer close(results) for _, item := range data { result := doSomeWork(item) results <- result } }() return results } // Bad: Race condition on shared variable (DO NOT USE) var counter int func incrementCounter() { for i := 0; i < 1000; i++ { counter++ // Race condition! } } """ ### 3.4. Resource Management **Standard:** Manage system resources (CPU, memory, file descriptors) efficiently to prevent resource exhaustion and improve performance. * **Do This:** * Limit resource usage with appropriate quotas and limits. * Release resources promptly when no longer needed. * Use profiling tools to identify resource bottlenecks. * Avoid memory leaks. * **Don't Do This:** * Allocate excessive amounts of memory without justification. * Leak file descriptors or other system resources. * Ignore resource constraints defined by the Kubernetes environment. **Why:** Efficient resource management reduces costs, improves performance, and enhances system stability. ## 4. Security Best Practices ### 4.1. Input Validation **Standard:** Validate all user inputs to prevent injection attacks and other vulnerabilities. * **Do This:** * Use appropriate validation libraries and frameworks. * Sanitize inputs to remove potentially harmful characters or sequences. * Enforce strict input length and format constraints. * Use parameterized queries to prevent SQL injection. * **Don't Do This:** * Trust user inputs without validation. * Allow arbitrary code execution based on user inputs. * Hardcode sensitive data into the code. **Why:** Input validation prevents exploits that could compromise the system's integrity and security. ### 4.2. Authentication and Authorization **Standard:** Implement robust authentication and authorization mechanisms to control access to sensitive resources. * **Do This:** * Use Kubernetes RBAC (Role-Based Access Control) to define access permissions. * Authenticate users using secure protocols (e.g., OAuth 2.0, OpenID Connect). * Enforce the principle of least privilege. * Regularly review and update access control policies. * **Don't Do This:** * Grant unnecessary permissions to users or services. * Store credentials in plaintext. * Bypass authentication or authorization checks. **Why:** Authentication and authorization protect sensitive resources from unauthorized access. ### 4.3. Secrets Management **Standard:** Store and manage sensitive data (e.g., passwords, API keys, certificates) securely. * **Do This:** * Use Kubernetes Secrets to store sensitive data. * Encrypt secrets at rest using KMS (Key Management Service). * Rotate secrets regularly. * Avoid committing secrets to source control. * **Don't Do This:** * Store secrets in environment variables or configuration files. * Share secrets unnecessarily. * Hardcode secrets into the code or container images. **Why:** Secure secrets management prevents sensitive data from being exposed, reducing the risk of unauthorized access. ### 4.4. Container Security **Standard:** Secure container images and runtime environments to prevent vulnerabilities and exploits. * **Do This:** * Use minimal base images with only necessary dependencies. * Scan container images for vulnerabilities using tools like Trivy or Clair. * Run containers with non-root users. * Apply security contexts to restrict container capabilities. * Regularly update container images and dependencies. * **Don't Do This:** * Use outdated or vulnerable base images. * Run containers as root without justification. * Expose sensitive ports or services unnecessarily. **Why:** Container security prevents exploits that could compromise the container or the underlying host. ## 5. Testing ### 5.1. Unit Tests **Standard:** Write comprehensive unit tests for all components to ensure correctness and prevent regressions. * **Do This:** * Use Go's testing package for unit tests. * Aim for high code coverage. * Mock dependencies to isolate units under test. * Write clear and concise test cases. * **Don't Do This:** * Omit unit tests for critical components. * Write tests that are too complex or brittle. * Ignore failing tests. **Why:** Unit tests provide confidence in the correctness of individual components and prevent regressions during development. ### 5.2. Integration Tests **Standard:** Write integration tests to verify the interaction between different components. * **Do This:** * Use Ginkgo and Gomega for BDD-style testing. * Test the integration of components with the Kubernetes API. * Verify the end-to-end behavior of the system. * **Don't Do This:** * Rely solely on unit tests. * Skip testing the integration of critical components. * Write integration tests that are too slow or unreliable. **Why:** Integration tests ensure that different components work together correctly and that the system as a whole behaves as expected. ### 5.3. End-to-End (E2E) Tests **Standard:** Write end-to-end tests to validate the system's overall functionality in a realistic environment. * **Do This:** * Deploy the system to a test Kubernetes cluster. * Simulate real-world user scenarios. * Verify the system's behavior under load. * Monitor performance and resource usage. * **Don't Do This:** * Skip E2E tests. * Test only basic functionality. * Ignore performance or scalability issues revealed by E2E tests. **Why:** End-to-end tests provide confidence that the system functions correctly in a production-like environment and meets performance and scalability requirements. ## 6. Continuous Integration and Continuous Delivery (CI/CD) ### 6.1. Automated Builds **Standard:** Automate the build process to ensure consistent and reliable builds. * **Do This:** * Use a CI/CD system (e.g., Jenkins, GitLab CI, GitHub Actions) to automate builds. * Trigger builds on code commits and pull requests. * Run unit tests and integration tests as part of the build process. * Generate build artifacts (e.g., container images, binaries) automatically. * **Don't Do This:** * Rely on manual builds. * Skip automated testing in the build process. * Fail to track build provenance and dependencies. ### 6.2. Automated Deployments **Standard:** Automate the deployment process to ensure consistent and reliable deployments. * **Do This:** * Use a CI/CD system to automate deployments. * Use declarative deployment configurations (e.g., Kubernetes manifests, Helm charts). * Implement blue-green deployments or canary releases for minimal downtime. * Monitor deployments for errors and roll back automatically if necessary. * **Don't Do This:** * Rely on manual deployments. * Deploy directly to production without testing in a staging environment. * Fail to monitor deployments for errors. ## 7. Documentation ### 7.1. Code Comments **Standard:** Write clear and concise comments to explain the purpose and functionality of the code. * **Do This:** * Comment complex or non-obvious code. * Explain the purpose of functions, methods, and classes. * Document API interfaces and data structures. * Use Go's commenting conventions. If reviewers ask questions about why the code is the way it is, that’s a sign that comments might be helpful. * **Don't Do This:** * Write redundant or obvious comments. * Comment every line of code. * Let comments become outdated. ### 7.2. API Documentation **Standard:** Generate API documentation automatically from code comments. * **Do This:** * Follow the conventions of documentation generators (e.g., GoDoc). * Document all API endpoints, data structures, and parameters. * Provide examples of API usage. * **Don't Do This:** * Omit API documentation. * Write API documentation manually. * Let API documentation become outdated. # Modern Approaches, Patterns, and Technologies for Component Design in Kubernetes: * **Controller-Runtime:** Leveraging controller-runtime, part of Kubebuilder, for building controllers simplifies many aspects like leader election, metrics, and health probes. It’s favored over vanilla client-go informers for new controller development. * **Server-Side Apply:** Use server-side apply to manage resources more effectively, merging changes from multiple actors without conflict. * **Composition Functions (kustomize):** With tools such as kustomize, configure Kubernetes resources via composition rather than duplication. This allows for patching and overriding standard configurations in a non-destructive manner. * **eBPF for Networking and Security:** Adopt eBPF (extended Berkeley Packet Filter) for advanced networking, observability, and security policies (e.g., Cilium CNI). * **Policy Engines (OPA, Kyverno):** Use policy engines like OPA (Open Policy Agent) or Kyverno to implement fine-grained policies to manage resource creation and configuration. * **Gatekeeper:** Use Gatekeeper to enforce CRD-based policies in your cluster. * **Service Mesh (Istio, Linkerd):** Employ service meshes for features like mTLS, traffic management, and advanced observability with minimal code changes. By incorporating these best practices, you can build Kubernetes components that are robust, scalable, secure, and easy to maintain. This document serves as a living guide that should be updated regularly to reflect the latest developments in the Kubernetes ecosystem.

# API Integration Standards for Kubernetes This document outlines coding standards specifically for integrating with APIs within the Kubernetes ecosystem. It covers patterns for connecting with backend services and external APIs, with a focus on maintainability, performance, and security. These standards are designed to be used by developers and interpreted by AI code generation tools. ## 1. Architectural Considerations ### 1.1 API Gateway Pattern **Standard:** Employ an API Gateway for external-facing services. This allows for a single point of entry, managing authentication, authorization, rate limiting, and request routing. **Do This:** Implement an API Gateway using tools like Ambassador, Kong, or ingress-nginx with annotations for advanced configurations. Consider service meshes like Istio for more complex traffic management and observability. **Don't Do This:** Expose backend services directly to the internet without a gateway. This increases the attack surface and complicates management. **Why:** An API Gateway provides a critical layer of abstraction, decoupling internal services from external clients. It centralizes common concerns, making the system more secure and maintainable. **Example:** """yaml # Ingress resource for Ambassador API Gateway apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: external-api-gateway annotations: kubernetes.io/ingress.class: ambassador getambassador.io/config: | --- apiVersion: getambassador.io/v3alpha1 kind: Mapping metadata: name: backend-service-mapping spec: prefix: /api/v1/ service: backend-service:8080 rewrite: / """ ### 1.2 Backend for Frontends (BFF) Pattern **Standard:** Utilize the BFF pattern for complex UI interactions. This involves creating API endpoints tailored to specific client needs, reducing the need for complex orchestration on the client-side. **Do This:** Create separate BFFs for web and mobile clients if their data requirements are significantly different. Use technologies like Node.js, Go, or Python for BFF implementation. **Don't Do This:** Force clients to consume generic API endpoints requiring significant data transformation or orchestration on the client. **Why:** The BFF pattern simplifies client-side development and improves performance by tailoring responses to the specific needs of each client. It reduces the burden on the backend and allows for more flexibility in UI design. **Example:** """go // Go implementation of a BFF endpoint package main import ( "encoding/json" "fmt" "log" "net/http" ) type UserProfile struct { ID int "json:"id"" Name string "json:"name"" Email string "json:"email"" } func getUserProfile(w http.ResponseWriter, r *http.Request) { // Simulate fetching data from multiple backend services userID := r.URL.Query().Get("user_id") if userID == "" { http.Error(w, "user_id is required", http.StatusBadRequest) return } // In a real-world scenario, you'd fetch data from different services profile := UserProfile{ ID: 123, Name: "John Doe", Email: "john.doe@example.com", } // Marshal the data into JSON jsonData, err := json.Marshal(profile) if err != nil { http.Error(w, err.Error(), http.StatusInternalServerError) return } // Set the content type to JSON w.Header().Set("Content-Type", "application/json") // Write the JSON data to the response w.WriteHeader(http.StatusOK) w.Write(jsonData) fmt.Printf("Responding to /userprofile\n") } func main() { http.HandleFunc("/userprofile", getUserProfile) fmt.Printf("Starting BFF server\n") log.Fatal(http.ListenAndServe(":8081", nil)) } """ ### 1.3 Service Mesh Considerations **Standard:** Evaluate a service mesh (Istio, Linkerd) for advanced features like mutual TLS, traffic shaping, and observability within the cluster. **Do This:** Implement mTLS using a service mesh to encrypt inter-service communication. Use traffic shifting features like canary deployments to safely roll out new API versions. **Don't Do This:** Rely solely on network policies for inter-service security. A service mesh provides an additional layer of defense. **Why:** Service meshes enhance security, reliability, and observability within a Kubernetes cluster. They provide features difficult to implement manually. **Example:** """yaml # Istio VirtualService for traffic shifting apiVersion: networking.istio.io/v1alpha3 kind: VirtualService metadata: name: backend-service-vs spec: hosts: - "backend-service" gateways: - mesh http: - route: - destination: host: backend-service subset: v1 weight: 90 - destination: host: backend-service subset: v2 weight: 10 """ ## 2. Implementation Standards ### 2.1 API Client Libraries **Standard:** Use idiomatic client libraries for interacting with external APIs. Generate client libraries from OpenAPI specifications (Swagger) whenever possible. **Do This:** Use tools like "openapi-generator" to create client libraries in your preferred language. Maintain consistent error handling. **Don't Do This:** Manually construct HTTP requests for every API call. This is error-prone and difficult to maintain. **Why:** Client libraries provide a type-safe, well-documented interface to external APIs. They encapsulate the complexity of HTTP requests and error handling. **Example:** """bash # Generate a Go client library from an OpenAPI specification openapi-generator generate -i openapi.yaml -g go -o ./client """ """go // Example Usage after you import the generated Go client library package main import ( "context" "fmt" "log" "github.com/myorg/my-api-client/client" // Replace with your generated client library path ) func main() { // Assuming you have the openapi.yaml file and the go client library exists cfg := client.NewConfiguration() cfg.Host = "api.example.com" // replace with specific host endpoint from Yaml apiClient := client.NewAPIClient(cfg) // Example API call (assuming an API method exists called GetUser) user, _, err := apiClient.DefaultApi.GetUser(context.Background()).UserId("123").Execute() if err != nil { log.Fatalf("Error getting user: %v", err) } fmt.Printf("User Name: %s\n", *user.Name) fmt.Printf("User Email: %s\n", *user.Email) } """ ### 2.2 Error Handling **Standard:** Implement robust error handling, including retries, circuit breakers, and detailed logging. **Do This:** Use libraries like "go-retryablehttp" (Go) or Resilience4j (Java) for retry logic and circuit breaker patterns. Implement structured logging with correlation IDs. **Don't Do This:** Ignore errors or simply log "error" without context. **Why:** Resilient error handling is crucial for maintaining application availability in a distributed environment. Detailed logging aids in debugging and identifying root causes. **Example:** """go // Go implementation employing retryablehttp package main import ( "context" "fmt" "log" "net/http" "os" "time" retryablehttp "github.com/hashicorp/go-retryablehttp" ) func main() { // Create a retryable HTTP client retryClient := retryablehttp.NewClient() retryClient.RetryMax = 3 // Maximum number of retries retryClient.RetryWaitMin = 1 * time.Second // Minimum wait time between retries retryClient.RetryWaitMax = 5 * time.Second // Maximum wait time between retries // Set up a logger retryClient.Logger = log.New(os.Stdout, "[retryablehttp] ", log.LstdFlags) // Define the URL you want to request url := "https://your-api-endpoint.com/resource" // Replace with your actual API endpoint // Create an HTTP request req, err := retryablehttp.NewRequest("GET", url, nil) if err != nil { log.Fatalf("Failed to create new request: %s", err) } // Optionally, set headers req.Header.Set("Content-Type", "application/json") req.Header.Set("Authorization", "Bearer your-api-token") // replace with API token // Perform the request with retry logic resp, err := retryClient.Do(req) if err != nil { log.Fatalf("Failed to perform request: %s", err) } defer resp.Body.Close() // Check the status code if resp.StatusCode >= 200 && resp.StatusCode < 300 { fmt.Printf("Request was successful with status code: %d\n", resp.StatusCode) // Process the response body // body, err := io.ReadAll(resp.Body) // if err != nil { // log.Fatalf("Failed to read response body: %s", err) // } //fmt.Printf("Response body: %s\n", string(body)) } else { fmt.Printf("Request failed with status code: %d\n", resp.StatusCode) } // Simulate an exponential backoff using context ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) defer cancel() backoff := time.Second maxBackoff := 8 * time.Second for attempt := 0; attempt <3; attempt++ { select { case <-time.After(backoff): fmt.Printf("Attempt %d at : %s\n", attempt, time.Now().String()) backoff *= 2 // exponential backoff if backoff > maxBackoff{ backoff = maxBackoff } //Simulate failed API call if attempt == 2 { fmt.Printf("API Call Sucessful") return } case <-ctx.Done(): fmt.Println("Context cancelled") return } } fmt.Printf("Calling fallback\n") } """ ### 2.3 Authentication and Authorization **Standard:** Secure API endpoints using industry-standard authentication and authorization mechanisms. **Do This:** Implement OAuth 2.0 or OpenID Connect for authentication. Use Kubernetes RBAC for authorizing access to in-cluster resources. Consider using JSON Web Tokens (JWTs) for passing user identity information. **Don't Do This:** Store sensitive information in plain text or use weak hashing algorithms. **Why:** Strong authentication and authorization are critical for protecting sensitive data and preventing unauthorized access. **Example:** """yaml # Kubernetes RoleBinding for authorizing access to a ConfigMap apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: name: configmap-reader namespace: my-namespace roleRef: apiGroup: rbac.authorization.k8s.io kind: Role name: configmap-reader subjects: - kind: ServiceAccount name: my-service-account namespace: my-namespace """ """go // Example of JWT verification in Go package main import ( "fmt" "log" "net/http" "github.com/golang-jwt/jwt/v5" ) var jwtKey = []byte("secretkey") //Replace me with an actual key type Claims struct { Username string "json:"username"" jwt.RegisteredClaims } func SecureEndpoint(w http.ResponseWriter, r *http.Request) { jwtToken := r.Header.Get("Authorization") // Parsing the JWT token claims := &Claims{} tkn, err := jwt.ParseWithClaims(jwtToken, claims, func(token *jwt.Token) (interface{}, error) { return jwtKey, nil }) if err != nil { if err == jwt.ErrSignatureInvalid { w.WriteHeader(http.StatusUnauthorized) return } w.WriteHeader(http.StatusBadRequest) return } if !tkn.Valid { w.WriteHeader(http.StatusUnauthorized) return } // Get the Username from the claim and return to client context := fmt.Sprintf("Welcome %s",claims.Username) println(context) w.Write([]byte("Welcome to the Secure Endpoint")) } func main() { http.HandleFunc("/secureEndpoint", SecureEndpoint) log.Fatal(http.ListenAndServe(":8082", nil)) } """ ### 2.4 Rate Limiting and Throttling **Standard:** Implement rate limiting and throttling to protect backend services from abuse and prevent resource exhaustion. **Do This:** Use rate limiting mechanisms provided by the API Gateway or service mesh. Implement adaptive rate limiting based on server load. **Don't Do This:** Allow unlimited requests to backend services. **Why:** Rate limiting prevents denial-of-service attacks and ensures fair resource allocation. **Example:** """yaml # Ambassador RateLimitPolicy apiVersion: getambassador.io/v3alpha1 kind: RateLimitPolicy metadata: name: api-rate-limit spec: domain: ambassador limits: - pattern: [{source_cluster: '*'}] rate: 10 unit: second """ ### 2.5 Data Validation **Standard:** Validate all incoming data to prevent security vulnerabilities and ensure data integrity. **Do This:** Use schema validation libraries to validate request bodies. Implement input sanitization to prevent injection attacks. **Don't Do This:** Trust that client-provided data is always valid. **Why:** Data validation prevents common security vulnerabilities like SQL injection and cross-site scripting (XSS). **Example:** """go //Example of data validation and sanitization within Go package main import ( "fmt" "log" "net/http" "net/url" "github.com/asaskevich/govalidator" //Ensure you install this govalidator package ) type InputData struct { Name string "valid:"required,alpha"" // Name must contain only letters and is a required parameter Email string "valid:"required,email"" // Email must be a valid email format and is a required paarameter URL string "valid:"url"" // URL must be a valid URL } func sanitizeString(input string) string { // Using QueryEscape to sanitize against common web injection attacks return url.QueryEscape(input) } func validateData(w http.ResponseWriter, r *http.Request) { err := r.ParseForm() if err != nil { http.Error(w, "Error parsing form", http.StatusBadRequest) return } data := InputData{ Name: r.FormValue("name"), Email: r.FormValue("email"), URL: r.FormValue("url"), } // Validate the data valid, err := govalidator.ValidateStruct(data) //Utilizing ValidateStruct if err != nil { http.Error(w, fmt.Sprintf("Validation error: %s", err.Error()), http.StatusBadRequest) return } //Sanitize the Data data.Name = sanitizeString(data.Name) data.Email = sanitizeString(data.Email) data.URL = sanitizeString(data.URL) // Response if valid { w.WriteHeader(http.StatusOK) w.Write([]byte("Data is valid and sanitized")) } else { log.Print("Struct is not valid") } } func main() { http.HandleFunc("/validateData", validateData) log.Fatal(http.ListenAndServe(":8083", nil)) } """ ## 3. Kubernetes Specific Considerations ### 3.1 Service Discovery **Standard:** Use Kubernetes service discovery for communication between services within the cluster. **Do This:** Use service names directly as DNS names within the cluster. For example, "backend-service.my-namespace.svc.cluster.local". **Don't Do This:** Hardcode IP addresses or use external DNS for internal service resolution. **Why:** Kubernetes service discovery makes the application more resilient and adaptable to changes in the cluster. **Example:** """go // Go code using service discovery to connect to another service package main import ( "fmt" "net/http" "io/ioutil" ) func callBackendService(w http.ResponseWriter, r *http.Request) { // The backend-service is accessible via DNS name within the cluster url := "http://backend-service:8080/api/data" // Assuming the endpoint being called is /api/data resp, err := http.Get(url) if err != nil { http.Error(w, fmt.Sprintf("Error calling backend service: %v", err), http.StatusInternalServerError) return } defer resp.Body.Close() body, err := ioutil.ReadAll(resp.Body) if err != nil { http.Error(w, fmt.Sprintf("Error reading response body: %v", err), http.StatusInternalServerError) return } w.WriteHeader(http.StatusOK) w.Write(body) } func main() { http.HandleFunc("/callBackend",callBackendService) fmt.Printf("starting the service\n") http.ListenAndServe(":8084",nil) } """ ### 3.2 Configuration Management **Standard:** Use Kubernetes ConfigMaps and Secrets for managing configuration data and sensitive information. **Do This:** Mount ConfigMaps and Secrets as volumes or environment variables in your Pods. Use SealedSecrets to encrypt sensitive information stored in Git. **Don't Do This:** Hardcode configuration values or store sensitive information in container images. **Why:** ConfigMaps and Secrets make it easier to manage and update application configuration without rebuilding images. **Example:** """yaml # Pod definition mounting a ConfigMap as a volume apiVersion: v1 kind: Pod metadata: name: my-pod spec: containers: - name: my-container image: my-image volumeMounts: - name: config-volume mountPath: /etc/config volumes: - name: config-volume configMap: name: my-configmap """ ### 3.3 Liveness and Readiness Probes **Standard:** Implement liveness and readiness probes to ensure that Kubernetes can properly manage the application lifecycle. **Do This:** Use HTTP, TCP, or exec probes to check the application's health. Ensure readiness probes only return success when the application is ready to serve traffic. **Don't Do This:** Omit liveness and readiness probes. **Why:** Liveness and readiness probes allow Kubernetes to automatically restart unhealthy pods and prevent traffic from being routed to pods that are not ready to serve requests. **Example:** """yaml # Pod definition with liveness and readiness probes apiVersion: v1 kind: Pod metadata: name: my-pod spec: containers: - name: my-container image: my-image livenessProbe: httpGet: path: /healthz port: 8080 initialDelaySeconds: 3 periodSeconds: 3 readinessProbe: httpGet: path: /readyz port: 8080 initialDelaySeconds: 5 periodSeconds: 5 """ ## 4. Performance Optimization ### 4.1 Connection Pooling **Standard:** Use connection pooling to reduce latency and improve throughput when connecting to backend services. **Do This:** Use libraries like "pgxpool" (PostgreSQL) or connection pool implementations in your preferred language. **Don't Do This:** Create a new connection for every API call. **Why:** Connection pooling reduces the overhead of establishing new connections. ### 4.2 Caching **Standard:** Implement caching to reduce the load on backend services and improve response times. **Do This:** Use in-memory caches (e.g., Redis, Memcached) or HTTP caching (e.g., using "Cache-Control" headers). **Don't Do This:** Cache sensitive information without proper security measures. **Why:** Caching reduces the number of requests to backend services and improves application performance. ### 4.3 Minimize Data Transfer **Standard:** Only transfer the data that you need. **Do This:** Use techniques like field selection (GraphQL) or projection to retrieve only the required fields. Compress responses using gzip or Brotli. **Don't Do This:** Transfer large amounts of unnecessary data. **Why:** Minimizing data transfer reduces network bandwidth consumption and improves application performance. These standards provide a comprehensive guide for API integration in Kubernetes, focusing on architectural patterns, implementation details, and Kubernetes-specific considerations. Following these guidelines will result in more maintainable, performant, and secure applications.

# Testing Methodologies Standards for Kubernetes This document outlines the testing methodologies standards for Kubernetes development. It provides guidance on unit, integration, and end-to-end testing strategies, specifically geared towards Kubernetes components. The principles described here emphasize maintainability, performance, security, and leverage the latest available Kubernetes features. ## 1. Unit Testing Unit tests verify the functionality of individual code units (functions, methods, classes) in isolation. For Kubernetes, this often involves testing internal logic within controllers, schedulers, or API server components. ### 1.1. Standards * **Do This:** * Write focused unit tests that cover all significant code paths in a single unit. * Use mock objects and test doubles to isolate the unit under test from its dependencies. * Aim for high code coverage (80% or higher) within each tested unit. * Clearly name test cases to reflect the tested functionality and expected behavior. * Use table-driven tests for handling multiple input/output scenarios. * Make sure to test error conditions and edge cases. * **Don't Do This:** * Write large, monolithic unit tests that test multiple units simultaneously. This makes debugging and maintenance significantly more difficult. * Use real dependencies (e.g., connecting to a real Kubernetes API server) in unit tests. This defeats the purpose of isolation and creates brittle tests. * Ignore error handling or edge cases. * Write tests that depend on external state or unpredictable factors. ### 1.2. Rationale * **Maintainability:** Well-written unit tests provide a safety net for refactoring and code changes. If a change breaks a unit test, it's a clear indication of a regression. * **Performance:** Unit tests run quickly and efficiently, allowing for rapid feedback during development. * **Security:** Unit tests can help identify potential security vulnerabilities within individual code units by simulating malicious input or unexpected conditions. ### 1.3. Code Examples (Go) """go // Example function to test (pod_util.go) package podutil import ( corev1 "k8s.io/api/core/v1" "k8s.io/apimachinery/pkg/util/validation" ) // IsValidPodName checks if a pod name is valid. func IsValidPodName(name string) bool { errs := validation.IsDNS1123Label(name) return len(errs) == 0 } // Example unit test (pod_util_test.go) package podutil import ( "testing" ) func TestIsValidPodName(t *testing.T) { testCases := []struct { name string expected bool }{ {"valid-pod-name", true}, {"invalid_pod_name", false}, {"a-very-long-pod-name-that-exceeds-63-characters", false}, {"", false}, } for _, tc := range testCases { t.Run(tc.name, func(t *testing.T) { actual := IsValidPodName(tc.name) if actual != tc.expected { t.Errorf("IsValidPodName(%q) = %v, expected %v", tc.name, actual, tc.expected) } }) } } """ **Explanation:** * The "IsValidPodName" function checks if a pod name is valid according to Kubernetes naming conventions. * The "TestIsValidPodName" function uses table-driven testing to verify the function's behavior with different inputs. * Each test case includes the input "name" and the expected output "expected". * The "t.Run()" function executes each test case in a separate subtest, making it easier to identify failing test cases. * The "k8s.io/apimachinery/pkg/util/validation" package provides validation functions used in the test. This is a standard Kubernetes dependency. ### 1.4. Anti-Patterns * **Ignoring Errors:** Failing to test error handling paths can lead to unexpected behavior and vulnerabilities in production. * **Using Real Dependencies:** Relying on live Kubernetes API servers or other external services makes unit tests slow, flaky, and difficult to maintain. Use mocking libraries like "gomock" to simulate dependencies. * **Writing "Integration Tests in Disguise":** If your unit test requires complex setup or interacts with multiple components, it's probably an integration test and should be refactored accordingly. ### 1.5. Mocking Dependencies """go // Example of using gomock for mocking (example_test.go) package main import ( "testing" "github.com/golang/mock/gomock" ) //go:generate mockgen -destination=mocks/service.go -package=mocks . ServiceInterface // ServiceInterface defines the interface for a service. type ServiceInterface interface { DoSomething(input string) (string, error) } // MyComponent depends on the ServiceInterface type MyComponent struct { Service ServiceInterface } // NewMyComponent creates a new MyComponent. func NewMyComponent(service ServiceInterface) *MyComponent { return &MyComponent{Service: service} } // UseService calls the service and returns the result. func (c *MyComponent) UseService(input string) (string, error) { return c.Service.DoSomething(input) } func TestMyComponent(t *testing.T) { ctrl := gomock.NewController(t) defer ctrl.Finish() mockService := NewMockServiceInterface(ctrl) // Define expectations for the mock service mockService.EXPECT(). DoSomething("test_input"). Return("mocked_output", nil). Times(1) component := NewMyComponent(mockService) result, err := component.UseService("test_input") if err != nil { t.Fatalf("Unexpected error: %v", err) } if result != "mocked_output" { t.Errorf("Expected 'mocked_output', but got '%s'", result) } } """ **Explanation:** * The example defines an interface "ServiceInterface" that "MyComponent" depends on. * "gomock" generates a mock implementation of "ServiceInterface" (run "go generate" in the directory). This requires installing "mockgen": "go install github.com/golang/mock/mockgen@v1.6.0 * The test creates a "MockServiceInterface" and defines expectations using "EXPECT()". These expectations specify which methods will be called, with what arguments, and what values they should return. * The "Times(1)" assertion ensures that the "DoSomething" method is called exactly once. ## 2. Integration Testing Integration tests verify the interaction between multiple components or services. In a Kubernetes context, this might involve testing the interaction between a custom controller and the Kubernetes API server, or between multiple custom controllers. ### 2.1. Standards * **Do This:** * Focus on testing the "seams" between components—the points where they interact. * Use a realistic but lightweight test environment, such as "kind" or "minikube". * Deploy test resources (e.g., custom resource definitions, custom resources) to the test environment. * Verify that components correctly process events and update the state of Kubernetes resources. * Clean up test resources after each test to avoid contaminating subsequent tests. * Use Ginkgo for creating structured integration tests (described below). * **Don't Do This:** * Attempt to test the entire Kubernetes cluster in an integration test. This is the domain of end-to-end tests. * Use mocks excessively. Integration tests are meant to test real interactions. * Leave test resources lingering in the cluster, which can lead to resource exhaustion and test conflicts. * Write integration tests that are overly sensitive to timing or ordering of events. Kubernetes is an eventually consistent system. * Assume that components have perfect knowledge of each other's internal state.. Test observable outputs/side effects. ### 2.2. Rationale * **Maintainability:** Integration tests provide confidence that different parts of the system work together correctly, reducing the risk of integration issues after code changes. * **Performance:** Integration tests are generally slower than unit tests but faster than end-to-end tests. * **Security:** Integration tests can help identify security vulnerabilities that arise from interactions between components, such as privilege escalation flaws or data leakage. ### 2.3. Code Examples (Go + Ginkgo) """go // Example integration test using Ginkgo (controller_test.go) package controllers import ( "context" "time" . "github.com/onsi/ginkgo/v2" . "github.com/onsi/gomega" appsv1 "k8s.io/api/apps/v1" corev1 "k8s.io/api/core/v1" metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" "k8s.io/apimachinery/pkg/types" "sigs.k8s.io/controller-runtime/pkg/client" ) var _ = Describe("MyController", func() { const ( timeout = time.Second * 10 interval = time.Millisecond * 250 ) var ( ctx context.Context ns *corev1.Namespace ) BeforeEach(func() { ctx = context.Background() // Create a namespace for the test ns = &corev1.Namespace{ ObjectMeta: metav1.ObjectMeta{ GenerateName: "test-ns-", }, } Expect(k8sClient.Create(ctx, ns)).Should(Succeed()) }) AfterEach(func() { // Clean up the namespace and all resources within Expect(k8sClient.Delete(ctx, ns)).Should(Succeed()) }) It("Should create a Deployment", func() { By("Creating a Deployment") deployment := &appsv1.Deployment{ ObjectMeta: metav1.ObjectMeta{ Name: "test-deployment", Namespace: ns.Name, }, Spec: appsv1.DeploymentSpec{ Selector: &metav1.LabelSelector{ MatchLabels: map[string]string{"app": "test-app"}, }, Replicas: int32Ptr(1), Template: corev1.PodTemplateSpec{ ObjectMeta: metav1.ObjectMeta{ Labels: map[string]string{"app": "test-app"}, }, Spec: corev1.PodSpec{ Containers: []corev1.Container{ { Name: "test-container", Image: "nginx:latest", }, }, }, }, }, } Expect(k8sClient.Create(ctx, deployment)).Should(Succeed()) By("Checking if the Deployment exists") deploymentLookupKey := types.NamespacedName{Name: "test-deployment", Namespace: ns.Name} createdDeployment := &appsv1.Deployment{} Eventually(func() bool { err := k8sClient.Get(ctx, deploymentLookupKey, createdDeployment) return err == nil }, timeout, interval).Should(BeTrue()) By("Checking if the Deployment has the correct number of replicas") Expect(*createdDeployment.Spec.Replicas).Should(Equal(int32(1))) }) }) func int32Ptr(i int32) *int32 { return &i } """ **Explanation:** * **Ginkgo:** The test uses the Ginkgo testing framework for a structured and readable test format. Install Ginkgo with: "go install github.com/onsi/ginkgo/v2/ginkgo" and then "go install github.com/onsi/gomega/gomega" * **"Describe":** Defines a test suite for the "MyController". * **"BeforeEach":** Sets up the test environment by creating a Kubernetes namespace. * **"AfterEach":** Cleans up the test environment by deleting the namespace. This is crucial for preventing test pollution. * **"It":** Defines a specific test case (e.g., "Should create a Deployment"). * **"By":** Provides commentary within the test, making it easier to understand the steps being performed. * **"Eventually":** Handles the eventual consistency of Kubernetes. The test waits until the deployment is created, with a timeout and interval. This allows for the controller to reconcile the state. * **"k8sClient":** A client for interacting with the Kubernetes API server in the test environment. This is typically injected into the controller being tested. Look into controller-runtime's "envtest" package to set this up. * Gomega matchers (e.g., "Expect(...).Should(Succeed())", "Expect(...).Should(Equal(...))") are used to make assertions about the state of the Kubernetes resources. ### 2.4. Anti-Patterns * **Flaky Tests:** Integration tests are prone to flakiness due to the inherent complexities of distributed systems. Use "Eventually" and other techniques to handle eventual consistency and timing issues. Add retries only when absolutely necessary and unavoidable * **Over-Reliance on Mocks:** Excessive mocking can mask real integration issues. Use mocks sparingly, focusing on simulating external services or dependencies that are not directly under test. * **Ignoring Cleanup:** Failing to clean up test resources can lead to resource exhaustion and test conflicts. Always delete the resources you create, typically in an "AfterEach" block. * **Assuming Immediate Consistency:** Kubernetes is eventually consistent. Don't assume that changes will be immediately reflected in the API server. Use "Eventually" to wait for the desired state to be reached. ### 2.5. Using Kind for Local Kubernetes Clusters Kind (Kubernetes in Docker) is a popular tool for creating lightweight Kubernetes clusters for integration testing. It allows you to run Kubernetes locally without the overhead of a full-fledged cluster. """bash # Create a Kind cluster kind create cluster --name my-test-cluster # Configure kubectl to connect to the Kind cluster kubectl config use-context kind-my-test-cluster # Deploy your controller to the Kind cluster (e.g., using kubectl apply) kubectl apply -f config/samples/my-controller.yaml # Run your integration tests go test ./controllers -v -integration """ ## 3. End-to-End (E2E) Testing End-to-end (E2E) tests verify the entire system from end to end, simulating real user interactions. In Kubernetes, this means deploying applications and services to a cluster and verifying that they function as expected under various conditions. These are generally meant for the entire Kubernetes distribution being healthy, and often run against entire managed Kubernetes environments. ### 3.1. Standards * **Do This:** * Focus on testing high-level user scenarios. * Use a real Kubernetes cluster for testing (e.g., a managed Kubernetes service). * Deploy applications and services to the cluster using standard Kubernetes manifests. * Verify that the applications and services are accessible and function correctly. * Run tests in parallel to speed up execution. * Use a framework like Sonobuoy to ensure conformance to Kubernetes standards. * Incorporate chaos engineering principles to test resilience. * Tag E2E tests appropriately to indicate their scope and purpose. * **Don't Do This:** * Write E2E tests that are too granular or test implementation details. These are better suited for unit or integration tests. * Rely on specific node configurations or cluster settings unless absolutely necessary. * Run E2E tests against a local development environment. The environment needs to approximate a real production environment. * Ignore performance or scalability concerns. E2E tests should measure the performance of the system under realistic load. ### 3.2. Rationale * **Maintainability:** E2E tests provide confidence that the entire system works correctly after changes, reducing the risk of introducing regressions into production. * **Performance:** E2E tests can identify performance bottlenecks and scalability issues in the system. * **Security:** E2E tests can help identify security vulnerabilities that arise from interactions between different parts of the system, such as unauthorized access or data breaches. ### 3.3. Code Examples (Go + Kubetest2) """go //Kubernetes requires a separate tool called Kubetest2 for E2E tests. // This tool provides a way to create and manage Kubernetes clusters for testing purposes. // You'll need to install Kubetest2 and configure it to work with your Kubernetes environment. // Example E2E test using Kubetest2 (e2e_test.go) package e2e import ( "context" "fmt" "os" "os/exec" "testing" "time" . "github.com/onsi/ginkgo/v2" . "github.com/onsi/gomega" ) var ( kubeconfigPath string ) func TestE2E(t *testing.T) { RegisterFailHandler(Fail) RunSpecs(t, "E2E Suite") } var _ = BeforeSuite(func() { // Get the path to the kubeconfig file kubeconfigPath = os.Getenv("KUBECONFIG") if kubeconfigPath == "" { Fail("KUBECONFIG environment variable not set") } // Verify that the kubeconfig file exists _, err := os.Stat(kubeconfigPath) if os.IsNotExist(err) { Fail(fmt.Sprintf("kubeconfig file not found: %s", kubeconfigPath)) } // Verify that kubectl is installed and configured correctly cmd := exec.Command("kubectl", "get", "nodes") cmd.Env = append(os.Environ(), fmt.Sprintf("KUBECONFIG=%s", kubeconfigPath)) err = cmd.Run() if err != nil { Fail(fmt.Sprintf("kubectl is not configured correctly: %v", err)) } fmt.Println("Kubectl config valid.") }) var _ = Describe("Deployment", func() { It("Should create a deployment and scale it", func() { ctx := context.Background() deploymentName := "test-deployment" namespace := "default" replicas := 3 // Define the deployment manifest deploymentManifest := fmt.Sprintf(" apiVersion: apps/v1 kind: Deployment metadata: name: %s namespace: %s spec: selector: matchLabels: app: nginx replicas: %d template: metadata: labels: app: nginx spec: containers: - name: nginx image: nginx:latest ", deploymentName, namespace, replicas) // Apply the deployment manifest using kubectl cmd := exec.Command("kubectl", "apply", "-f", "-", "-n", namespace) cmd.Stdin = []byte(deploymentManifest) cmd.Env = append(os.Environ(), fmt.Sprintf("KUBECONFIG=%s", kubeconfigPath)) output, err := cmd.CombinedOutput() Expect(err).NotTo(HaveOccurred(), "Failed to apply deployment: %s", string(output)) // Verify that the deployment is created and the correct number of replicas are running Eventually(func() int { cmd := exec.Command("kubectl", "get", "deployment", deploymentName, "-n", namespace, "-o", "jsonpath='{.status.availableReplicas}'") cmd.Env = append(os.Environ(), fmt.Sprintf("KUBECONFIG=%s", kubeconfigPath)) output, err := cmd.CombinedOutput() Expect(err).NotTo(HaveOccurred(), "Failed to get deployment status: %s", string(output)) var availableReplicas int fmt.Sscan(string(output), &availableReplicas) return availableReplicas }, 2*time.Minute, 10*time.Second).Should(Equal(replicas), "Deployment should have the correct number of replicas") // Clean up the deployment cmd = exec.Command("kubectl", "delete", "deployment", deploymentName, "-n", namespace) cmd.Env = append(os.Environ(), fmt.Sprintf("KUBECONFIG=%s", kubeconfigPath)) output, err = cmd.CombinedOutput() Expect(err).NotTo(HaveOccurred(), "Failed to delete deployment: %s", string(output)) fmt.Println("Successfully ran E2E deployment apply, check and delete") }) }) """ **Explanation:** * **Kubetest2**: Kubetest2 is required within the Kubernetes repository, but the above code shows a rough approach as if it were being implemented outside of the Kubernetes repo. * **KUBECONFIG**: The test relies on the "KUBECONFIG" environment variable to locate the kubeconfig file for the target cluster. It verifies that the file exists and that "kubectl" is configured correctly. * **Deployment Manifest**: The test defines the deployment manifest as a string and uses "kubectl apply" to deploy it to the cluster. This enables the full creation of the deployment. * **Verification**: The test verifies that the deployment is created and that the correct number of replicas are running by using "kubectl get". * **Cleanup**: The test cleans up the deployment using "kubectl delete". * **Eventual Consistency**: The "Eventually" block accounts for Kubernetes' eventual consistency. ### 3.4. Anti-Patterns * **Overly Complex Setup:** E2E tests should focus on high-level scenarios and avoid complex setup. Use simpler deployment manifests and rely on standard Kubernetes features. * **Ignoring Performance:** E2E tests should measure the performance of the entire system. Monitor latency, throughput, and resource consumption to identify performance bottlenecks. * **Lack of Isolation:** E2E tests should run in an isolated environment to avoid interference from other applications or services. Use separate namespaces or dedicated clusters for E2E testing. ### 3.5. Chaos Engineering Chaos engineering is the practice of intentionally injecting faults into a system to test its resilience. In Kubernetes, this can involve deleting pods, disrupting network connectivity, or stressing resources. These tests should not be taken lightly and need to be scoped appropriately so that the entire cluster system is not affected abruptly. """go // Example injecting chaos into the cluster (pseudo-code) // Simulate node failure by draining a node func SimulateNodeFailure(nodeName string) error { //Cordon the node to prevent new pods from being scheduled cmd := exec.Command("kubectl", "cordon", nodeName) err := cmd.Run() if err != nil { return fmt.Errorf("failed to cordon node: %w", err) } // Drain the node to evict existing pods cmd = exec.Command("kubectl", "drain", nodeName, "--ignore-daemonsets", "--force") err = cmd.Run() if err != nil { return fmt.Errorf("failed to drain node: %w", err) } fmt.Printf ("Simulated Node Failure on %s", nodeName) return nil } """ **Explanation:** * Tests must use tools like "kubectl" to simulate real-world failures. * Tests must be scoped appropriately. Make sure to cordon/uncordon nodes. Reenable the scheduling on the node after the test. * "--ignore-daemonsets" avoids evicting daemonset pods, which are typically critical for cluster functionality. * "--force" allows evicting pods even if they are not managed by a controller. Use with caution. * The resilience of the application must be verified as a result of the failure. By adhering to these testing methodologies and standards, Kubernetes developers can ensure the quality, reliability, and security of their components, contributing to a more robust and maintainable platform.

# Code Style and Conventions Standards for Kubernetes This document outlines the code style and conventions standards for contributing to the Kubernetes project. Adhering to these standards ensures consistency, readability, maintainability, and security across the codebase. These guidelines apply to all languages used in Kubernetes, with a primary focus on Go and YAML, and take into account the most recent versions of Kubernetes. ## 1. General Principles * **Consistency:** Maintain a consistent style across all files and packages. Use linters and formatters to enforce style rules automatically. * **Readability:** Write code that is easy to understand. Use meaningful names, keep functions short, and add comments when necessary. * **Maintainability:** Design code that is easy to modify and extend. Follow SOLID principles and avoid code duplication. * **Testability:** Ensure all code is easily testable. Write unit tests, integration tests, and end-to-end tests. * **Security:** Write secure code. Follow security best practices, such as input validation, output encoding, and least privilege. Use static analysis tools to identify potential vulnerabilities. * **Error Handling:** Implement robust error handling. Return errors, log errors, and handle errors gracefully. Never ignore errors. ## 2. Go Coding Standards ### 2.1. Formatting * **Use "go fmt":** All Go code *must* be formatted with "go fmt". This tool automatically formats Go code according to the standard style. **Do This:** """bash go fmt ./... """ **Don't Do This:** """go // non-standard formatting func main () { println("Hello, World!") } //messy """ * **Line Length:** Keep lines reasonably short (ideally under 120 characters). This improves readability in most editors and IDEs. **Do This:** """go // Properly wrapped line for readability err := client.Create(context.Background(), &corev1.Pod{ ObjectMeta: metav1.ObjectMeta{ Name: "my-pod", Namespace: "default", }, Spec: corev1.PodSpec{ Containers: []corev1.Container{{ Name: "nginx", Image: "nginx:latest", }}, }, }) if err != nil { klog.Error(err, "Failed to create pod") return err } """ **Don't Do This:** """go err := client.Create(context.Background(), &corev1.Pod{ObjectMeta: metav1.ObjectMeta{Name: "my-pod", Namespace: "default",}, Spec: corev1.PodSpec{ Containers: []corev1.Container{{ Name: "nginx", Image: "nginx:latest",}},},}) // Very long line. Hard to read if err != nil { klog.Error(err, "Failed to create pod"); return err; } // hard to read single line """ * **Imports:** Use grouped imports with standard library imports first, followed by external imports, and then internal imports (separated by blank lines). **Do This:** """go import ( "context" "fmt" "time" "github.com/go-logr/logr" corev1 "k8s.io/api/core/v1" metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" "sigs.k8s.io/controller-runtime/pkg/client" ) """ **Don't Do This:** """go import ( "fmt" "sigs.k8s.io/controller-runtime/pkg/client" "context" corev1 "k8s.io/api/core/v1" "time" metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" "github.com/go-logr/logr" ) """ **Why:** Grouped imports and ordering make dependencies clearer and easier to track. ### 2.2. Naming Conventions * **Packages:** Use short, descriptive, and lowercase package names. Avoid abbreviations and underscores. The package name should reflect the purpose of the code within the package. **Do This:** "pkg/controller", "pkg/webhook" **Don't Do This:** "pkg/K8s_Controller", "pkg/kube-controller" **Why:** Clarity and avoid confusion. Package names are used in import statements, so keeping them readable helps. * **Variables and Functions:** Use camelCase for variable and function names. Shorter names are preferred for local variables, while longer, more descriptive names are suitable for global variables and exported functions/methods. **Do This:** "podName", "createPod", "ReconcileResource" **Don't Do This:** "Pod_Name", "CreatePOD", "reconcile_resource" * **Constants:** Use PascalCase (CamelCase starting with an uppercase letter) for named constants. **Do This:** "DefaultRequeueTime", "MaxRetries" **Don't Do This:** "defaultRequeueTime", "max_retries" * **Interfaces:** Name interfaces using PascalCase, typically ending with "er" or "Interface". Avoid redundancy. For example, "storage.Interface" is preferred over "storage.StorageInterface". **Do This:** "ResourceHandler", "ClientInterface" **Don't Do This:** "IResourceHandler", "ClientIntf" * **Types:** Use PascalCase for type names. **Do This:** "PodSpec", "DeploymentStatus" **Don't Do This:** "podSpec", "deployment_status" ### 2.3. Error Handling * **Explicit Error Checks:** Always check errors explicitly. Don't use the blank identifier ("_") to discard errors without handling. **Do This:** """go pod, err := client.Get(context.TODO(), client.ObjectKey{Namespace: "default", Name: "my-pod"}, &corev1.Pod{}) if err != nil { if errors.IsNotFound(err) { klog.Info("Pod not found") return nil } klog.Error(err, "Failed to get pod") return err } """ **Don't Do This:** """go pod, _ := client.Get(context.TODO(), client.ObjectKey{Namespace: "default", Name: "my-pod"}, &corev1.Pod{}) // ignoring the error """ * **Error Wrapping:** Use "%w" to wrap errors to preserve the original error context. This allows for easier debugging and error analysis. **Do This:** """go err := someFunction() if err != nil { return fmt.Errorf("failed in someFunction: %w", err) } """ **Don't Do This:** """go err := someFunction() if err != nil { return fmt.Errorf("failed in someFunction: %s", err) // Losing error context } """ * **Error Types:** Use the "errors" package for creating and checking specific error types. **Do This:** """go var ErrInvalidInput = errors.New("invalid input") func validateInput(input string) error { if input == "" { return ErrInvalidInput } return nil } func main() { err := validateInput("") if errors.Is(err, ErrInvalidInput) { fmt.Println("Input is invalid") } } """ **Don't Do This:** """go func validateInput(input string) error { if input == "" { return fmt.Errorf("invalid input") // String comparison is brittle } return nil } func main() { err := validateInput("") if err.Error() == "invalid input" { // Brittle string comparison fmt.Println("Input is invalid") } } """ **Why:** Provides more robust error checking using "errors.Is()" and "errors.As()". ### 2.4. Concurrency * **Context:** Always pass a "context.Context" as the first argument to functions that perform I/O operations or may block. Use context for cancellation and deadlines. **Do This:** """go func createResource(ctx context.Context, client client.Client, obj runtime.Object) error { return client.Create(ctx, obj) } """ **Don't Do This:** """go func createResource(client client.Client, obj runtime.Object) error { // Missing context return client.Create(context.Background(), obj) //avoid creating new context in API methods } """ * **Goroutine Management:** Use "sync.WaitGroup" or channels to manage goroutines and prevent leaks. **Do This:** """go var wg sync.WaitGroup for i := 0; i < 5; i++ { wg.Add(1) go func(i int) { defer wg.Done() fmt.Println("Worker", i) }(i) } wg.Wait() """ **Don't Do This:** """go for i := 0; i < 5; i++ { go func(i int) { // Potential goroutine leak fmt.Println("Worker", i) }(i) } """ * **Mutexes:** Use mutexes ("sync.Mutex") to protect shared resources from concurrent access. **Do This:** """go var mu sync.Mutex var counter int func incrementCounter() { mu.Lock() defer mu.Unlock() counter++ } """ **Don't Do This:** """go var counter int func incrementCounter() { // Possible data race counter++ } """ ### 2.5. Logging * **Structured Logging:** Use structured logging with "klog" for log messages. **Do This:** """go import ( "k8s.io/klog/v2" ) klog.InfoS("Pod created", "namespace", pod.Namespace, "name", pod.Name) klog.ErrorS(err, "Failed to create pod", "namespace", pod.Namespace, "name", pod.Name) """ **Don't Do This:** """go fmt.Printf("Pod created in namespace %s with name %s\n", pod.Namespace, pod.Name) // unstructured logging """ * **Log Levels:** Use appropriate log levels (e.g., Info, Warning, Error) based on the severity of the message. **Do This:** """go klog.V(2).InfoS("Detailed information for debugging") // Verbose logging klog.WarningS("Something unexpected happened, but the program can continue") klog.ErrorS(err, "A critical error occurred") """ **Don't Do This:** """go klog.InfoS("Everything is fine") // Using Info for debug messages """ **Why:** Structured logging enables better filtering, analysis, and integration with monitoring tools. * **Contextual Logging:** Include relevant context in log messages, such as resource names, namespaces, and operation IDs. ### 2.6. Comments * **Godoc Comments:** Write godoc comments for all exported types, functions, and methods. These comments should explain what the code does and how to use it. **Do This:** """go // ReconcileResource reconciles a resource. // It fetches the resource, checks its status, and updates it if necessary. func (r *Reconciler) ReconcileResource(ctx context.Context, req ctrl.Request) (ctrl.Result, error) { // ... } """ **Don't Do This:** """go func (r *Reconciler) ReconcileResource(ctx context.Context, req ctrl.Request) (ctrl.Result, error) { // reconciles // ... } """ * **Internal Comments:** Use comments to explain complex or non-obvious logic within functions. Focus on *why* the code does what it does, not just *what* the code does. ### 2.7. Kubernetes Specific Considerations * **API Machinery Types:** When working with Kubernetes API types (e.g., Pod, Deployment), use the types defined in the "k8s.io/api" and "k8s.io/apimachinery" packages. *Avoid* creating custom types that duplicate or shadow these. Ensure API groups and versions are correct. **Do This:** """go import ( corev1 "k8s.io/api/core/v1" metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" ) pod := &corev1.Pod{ ObjectMeta: metav1.ObjectMeta{ Name: "my-pod", Namespace: "default", }, Spec: corev1.PodSpec{ Containers: []corev1.Container{{ Name: "nginx", Image: "nginx:latest", }}, }, } """ **Don't Do This:** """go type MyPod struct { // Avoid custom type for Pod Name string Image string } """ * **Clients and Informers:** Use "client-go" to interact with the Kubernetes API. Use informers for caching and event handling. Use the controller-runtime library for building controllers. Ensure clients are properly configured and authenticated. When using a "dynamic" client, ensure the GVR (GroupVersionResource) is properly specified. **Do This:** """go import ( "sigs.k8s.io/controller-runtime/pkg/client" ) // Assume client is a properly configured controller-runtime client.Client err := client.Get(context.TODO(), client.ObjectKey{Namespace: "default", Name: "my-pod"}, &corev1.Pod{}) if err != nil { // ... } """ **Don't Do This:** """go // Avoid direct HTTP calls to the Kubernetes API server """ * **Controllers:** Follow the controller pattern for managing Kubernetes resources. Use the "controller-runtime" library to simplify controller development. Implement reconciliation logic that is idempotent and handles errors gracefully. Use finalizers to ensure proper cleanup of resources. * **Webhooks**: Implement webhooks following the Kubernetes API guidelines for admission controllers. Ensure webhooks are properly secured with TLS and RBAC. ### 2.7.1. Controller Pattern Enhancements (Latest Kubernetes) * **Using Builder Pattern:** Use the "Builder" pattern from "controller-runtime" for declarative controller setup. This provides clear resource ownership, filtering events, and more refined control over reconciliation triggers. **Do This:** """go func (r *MyReconciler) SetupWithManager(mgr ctrl.Manager) error { return ctrl.NewControllerManagedBy(mgr). For(&myappv1.MyResource{}). Owns(&corev1.Pod{}). // Reconcile when owned Pods change WithEventFilter(predicate.GenerationChangedPredicate{}). // Only reconcile on spec changes Complete(r) } """ **Why**: Improves readability and maintainability of controller setup. * **Managing Informers:** Employ informer factories for optimal shared informer use across multiple controllers. This reduces pressure on the API server and reduces memory consumption. * **Predicate Filtering:** Use Predicates to filter events to reduce unnecessary reconciliations. Use resource version predicates to reduce reconcile frequency and optimize performance. ### 2.8. Testing * **Unit Tests:** Write unit tests for all functions and methods. Use table-driven tests for parameterized testing. **Do This:** """go func TestMyFunction(t *testing.T) { testCases := []struct { name string input int expected int }{ { name: "Positive input", input: 5, expected: 10, }, { name: "Negative input", input: -5, expected: -10, }, } for _, tc := range testCases { t.Run(tc.name, func(t *testing.T) { actual := myFunction(tc.input) if actual != tc.expected { t.Errorf("Expected %d, but got %d", tc.expected, actual) } }) } } """ **Don't Do This:** """go func TestMyFunction(t *testing.T) { result := myFunction(5) if result != 10 { t.Errorf("Expected 10, but got %d", result) } } """ * **Integration Tests:** Write integration tests to verify the interaction between different components. * **End-to-End Tests:** Write end-to-end tests to verify the overall system behavior. Use tools like Ginkgo and Gomega for writing BDD-style tests. Follow the guidance provided in the "test-infra" repository for writing and running E2E tests in Kubernetes. ## 3. YAML Coding Standards ### 3.1. Formatting * **Indentation:** Use 2 spaces for indentation. *Never* use tabs. **Do This:** """yaml apiVersion: v1 kind: Pod metadata: name: my-pod spec: containers: - name: nginx image: nginx:latest """ **Don't Do This:** """yaml apiVersion: v1 kind: Pod metadata: name: my-pod # Incorrect indentation spec: containers: # Incorrect indentation - name: nginx # Incorrect indentation image: nginx:latest # Incorrect indentation """ * **Line Length:** Keep lines reasonably short (ideally under 80 characters). * **Spacing:** Use a single space after colons and commas. **Do This:** """yaml name: my-pod ports: [80, 443] """ **Don't Do This:** """yaml name:my-pod ports:[80,443] """ ### 3.2. Structure and Content * **API Version and Kind:** Always specify the "apiVersion" and "kind" fields at the beginning of each YAML file. Ensure the version is correct for the target Kubernetes cluster. Use the latest stable API versions. **Do This:** """yaml apiVersion: apps/v1 kind: Deployment """ **Don't Do This:** """yaml apiVersion: apps/v1beta1 # Deprecated API version kind: Deployment """ * **Metadata:** Include meaningful metadata, such as "name", "namespace", and "labels". Use labels consistently for selecting and managing resources. Use annotations to store non-identifying metadata. **Do This:** """yaml metadata: name: my-deployment namespace: production labels: app: my-app tier: backend """ * **Comments:** Use comments to explain the purpose of specific configurations and settings. **Do This:** """yaml # This deployment manages the backend API servers apiVersion: apps/v1 kind: Deployment metadata: name: my-deployment """ ### 3.3. Naming Conventions * **Resource Names:** Use lowercase letters, numbers, and hyphens for resource names. Start with a letter and end with a letter or number. Keep names short and descriptive. **Do This:** "my-pod", "backend-service" **Don't Do This:** "MyPod", "Backend_Service", "my_super_long_and_unnecessary_pod_name" * **Label Keys:** Use a DNS subdomain prefix for custom labels to avoid collisions with other applications or systems. **Do This:** "example.com/my-label", "app.kubernetes.io/name" (for standard Kubernetes labels) **Don't Do This:** "my-label" (without a domain prefix) ### 3.4. Best Practices * **Immutability:** Treat YAML files as immutable configuration. Use Git or other version control systems to track changes. * **Separation of Concerns:** Separate YAML files for different environments (e.g., development, staging, production). Use templating tools like Helm or Kustomize to manage environment-specific configurations. * **Security Contexts:** Always define security contexts for Pods and Containers to enforce security policies. Use "runAsUser", "runAsGroup", "capabilities", and other security-related fields. * **Resource Requests and Limits:** Define resource requests and limits for Containers to ensure proper resource allocation and prevent resource starvation. ### 3.5. Using Kustomize * **Base and Overlays:** Employ Kustomize's base and overlay system. Define a base configuration with common settings and create overlays for environment-specific customizations. **Base (base/kustomization.yaml):** """yaml resources: - deployment.yaml - service.yaml commonLabels: app: my-app """ **Overlay (overlays/production/kustomization.yaml):** """yaml bases: - ../../base patches: - path: deployment-patch.yaml target: kind: Deployment name: my-app """ **Deployment Patch (overlays/production/deployment-patch.yaml):** """yaml apiVersion: apps/v1 kind: Deployment metadata: name: my-app spec: replicas: 3 """ **Why:** Provides a structured way to manage configuration variations without duplicating entire files. ## 4. General Tips and Anti-Patterns * **Avoid Hardcoding Values:** Use environment variables, config maps, or secrets to externalize configuration values. Never hardcode sensitive information in code or YAML files. * **Don't Repeat Yourself (DRY):** Abstract common functionality into reusable functions or modules. Avoid duplicating code across multiple files or packages. * **Single Responsibility Principle (SRP):** Each function, method, or class should have a single, well-defined purpose. * **Keep Functions Short:** Keep functions short and focused (ideally under 50 lines of code). Break down complex logic into smaller, more manageable functions. * **Avoid Global Variables:** Minimize the use of global variables. If you need to use a global variable, protect it with a mutex to prevent concurrent access. Consider dependency injection to pass dependencies explicitly. * **Use Linters and Static Analysis Tools:** Use linters (e.g., "golangci-lint", "yamale") and static analysis tools (e.g., "staticcheck", "kube-linter") to identify potential issues in your code and YAML files. Configure these tools in your CI/CD pipeline for automated code review. * **Keep Up-to-Date:** Stay up-to-date with the latest Kubernetes features, best practices, and security advisories. Regularly review and update your code to take advantage of new features and address potential vulnerabilities. * **Address Code Smells Early:** Pay attention to code smells (e.g., long methods, duplicate code, feature envy) and address them early in the development process. Refactoring code regularly can prevent technical debt from accumulating. By adhering to these standards and guidelines, developers can contribute to a more consistent, readable, maintainable, and secure Kubernetes codebase. These standards should be considered a living document, subject to change and refinement as the Kubernetes project evolves. Regular review and updates are encouraged to keep these standards aligned with the latest best practices and technologies.

# State Management Standards for Kubernetes This document outlines coding standards for managing application state within Kubernetes. It provides guidelines for developers to ensure consistency, maintainability, performance, and security when building stateful applications on Kubernetes. These guidelines specifically address the unique challenges of state management in a distributed, containerized environment and leverages modern Kubernetes features and best practices. ## 1. Introduction to State Management in Kubernetes State management in Kubernetes revolves around persisting, accessing, and managing data across pod lifecycles. This is especially critical for stateful applications like databases, message queues, and caching systems. Unlike stateless applications, stateful apps need to retain data even when pods are rescheduled or updated. This document focuses on Kubernetes-native approaches and avoids relying on external solutions where possible to enhance portability and integration. ### 1.1. Key Considerations for State Management * **Persistence:** How data is stored and retrieved reliably. * **Data Access:** Efficient and secure methods for applications to interact with persistent data. * **Consistency:** Ensuring data remains consistent across different nodes and pods. * **High Availability:** Maintaining data availability even during failures. * **Scalability:** Adapting storage capacity to meet changing application demands. * **Security:** Protecting sensitive data at rest and in transit. ## 2. Persistent Volumes and Claims Kubernetes Persistent Volumes (PVs) and Persistent Volume Claims (PVCs) are fundamental for managing persistent storage. Follow best practices for defining and using PVs and PVCs effectively. ### 2.1. Defining Persistent Volumes * **Do This:** Use StorageClasses for dynamic provisioning of PVs. * **Don't Do This:** Manually create PVs unless absolutely necessary. Static provisioning reduces portability and increases administrative overhead. **Why:** StorageClasses allow admins to define different types of storage (e.g., SSD, HDD, cloud-provider specific) and allow users to dynamically request storage without needing to know the underlying infrastructure details. **Code Example (StorageClass):** """yaml apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: standard provisioner: kubernetes.io/aws-ebs # Or your provider's provisioner parameters: type: gp2 reclaimPolicy: Retain # Or Delete, depending on your requirements """ * **Do This:** Set appropriate "reclaimPolicy" ("Retain" or "Delete") based on your needs. "Retain" keeps the volume after the PVC is deleted, useful for debugging or data recovery. "Delete" removes the volume when the PVC is deleted. * **Don't Do This:** Leave "reclaimPolicy" unset. This might lead to unexpected data loss or orphaned volumes. **Why:** The "reclaimPolicy" dictates what happens to the underlying storage volume when a PVC is deleted. Choosing the correct setting is important for data lifecycle management. ### 2.2. Defining Persistent Volume Claims * **Do This:** Define "accessModes" that match your application's needs (ReadWriteOnce, ReadOnlyMany, ReadWriteMany). * **Don't Do This:** Request more storage than your application needs. This wastes resources. **Why:** "accessModes" control how the volume can be accessed by multiple pods. * "ReadWriteOnce": The volume can be mounted as read-write by a single node. * "ReadOnlyMany": The volume can be mounted as read-only by many nodes. * "ReadWriteMany": The volume can be mounted as read-write by many nodes. **Code Example (PVC):** """yaml apiVersion: v1 kind: PersistentVolumeClaim metadata: name: my-pvc spec: storageClassName: standard accessModes: - ReadWriteOnce resources: requests: storage: 10Gi """ * **Do This:** Use "resources.requests.storage" to specify the amount of storage needed. **Why:** This ensures your application gets the required storage and helps Kubernetes scheduler find a suitable Persistent Volume. ### 2.3. Anti-Patterns: PV/PVC * **Anti-Pattern:** Hardcoding specific PV names in pod definitions. * **Better:** Rely on PVCs and StorageClasses for dynamic volume provisioning, promoting environment portability. * **Anti-Pattern:** Ignoring "reclaimPolicy" leading to data loss after PVC deletion (or orphaned volumes after app deletion). * **Better:** Carefully consider and setting "reclaimPolicy" based on data lifecycle. ## 3. StatefulSets StatefulSets are the recommended way to manage stateful applications in Kubernetes. ### 3.1. Defining StatefulSets * **Do This:** Use "serviceName" to define a headless service for your StatefulSet pods. * **Don't Do This:** Use a regular Service with a selector that matches all pods in the StatefulSet. **Why:** Headless Services provide stable network identities for each pod in the StatefulSet, crucial for stateful applications that require peer-to-peer communication or predictable addressing. **Code Example (StatefulSet):** """yaml apiVersion: apps/v1 kind: StatefulSet metadata: name: my-statefulset spec: serviceName: my-headless-service replicas: 3 selector: matchLabels: app: my-app template: metadata: labels: app: my-app spec: containers: - name: my-container image: my-image volumeMounts: - name: data mountPath: /data volumeClaimTemplates: - metadata: name: data spec: accessModes: [ "ReadWriteOnce" ] storageClassName: "standard" resources: requests: storage: 10Gi """ * **Do This:** Use "volumeClaimTemplates" to automatically create PVCs for each pod. * **Don't Do This:** Manually create PVCs for each pod in the StatefulSet. **Why:** "volumeClaimTemplates" simplify managing persistent storage for StatefulSets. Kubernetes will automatically create a PVC for each pod, named "<volumeClaimTemplateName>-<statefulset-name>-<pod-name>". * **Do This:** Understand the ordering guarantees provided by StatefulSets for pod creation, update, and deletion. * Pods are created sequentially, in order "0, 1, 2, ...". * Pods are updated in reverse ordinal order. * Pods are terminated in reverse ordinal order ("2, 1, 0"). * **Don't Do This:** Assume pods within a StatefulSet are identical and interchangeable. **Why:** StatefulSets are designed for applications where order and identity matter(e.g., clustered databases). ### 3.2. Pod Management Policy * **Do This:** Use the "OrderedReady" pod management policy unless you have a specific reason to use "Parallel". * **Don't Do This:** Use the "Parallel" pod management policy without understanding its implications on stateful application behavior. **Why:** "OrderedReady" ensures that each pod is fully ready before the next pod is created or updated. This is crucial for maintaining data consistency and availability in stateful applications. "Parallel" starts all pods at once which could lead to issues if your different instances need to coordinate. Example (StatefulSet): """yaml apiVersion: apps/v1 kind: StatefulSet metadata: name: web spec: serviceName: "nginx" replicas: 2 podManagementPolicy: OrderedReady selector: matchLabels: app: nginx template: metadata: labels: app: nginx spec: containers: - name: nginx image: k8s.gcr.io/nginx-slim:0.8 ports: - containerPort: 80 name: web volumeMounts: - name: www mountPath: /usr/share/nginx/html updateStrategy: type: RollingUpdate volumeClaimTemplates: - metadata: name: www spec: accessModes: [ "ReadWriteOnce" ] storageClassName: "standard" resources: requests: storage: 1Gi """ ### 3.3. Anti-Patterns: StatefulSets * **Anti-Pattern:** Ignoring the ordered nature of StatefulSet deployments. This can lead to data corruption or inconsistent state in distributed systems. * **Better:** Design your application to handle ordered deployments and updates, and to leverage the pod ordinal index. * **Anti-Pattern:** Scaling down a StatefulSet without considering the impact on data distribution and consistency. * **Better:** Implement graceful shutdown procedures that redistribute data before terminating pods. * **Anti-Pattern:** Mounting the same persistent volume multiple times into the same pod. While Kubernetes will block ReadWriteOnce mounts, ReadOnlyMany and ReadWriteMany volumes have different considerations. * **Better:** Design container layouts and mounts with a 1-to-1 mapping from PV to directories intended for a single container. ## 4. Configuration Management Managing configuration is critical for stateful apps. Use Kubernetes ConfigMaps and Secrets. ### 4.1. ConfigMaps * **Do This:** Use ConfigMaps to store non-sensitive configuration data. * **Don't Do This:** Store sensitive information in ConfigMaps. **Why:** ConfigMaps are not encrypted and should not contain secrets like passwords or API keys. **Code Example (ConfigMap):** """yaml apiVersion: v1 kind: ConfigMap metadata: name: my-config data: my_config_key: "my_config_value" """ Then, access the ConfigMap from a container: """yaml apiVersion: apps/v1 kind: Deployment metadata: name: my-app spec: replicas: 1 selector: matchLabels: app: my-app template: metadata: labels: app: my-app spec: containers: - name: my-container image: my-image env: - name: MY_CONFIG_VAR valueFrom: configMapKeyRef: name: my-config key: my_config_key """ ### 4.2. Secrets * **Do This:** Use Secrets to store sensitive information such as passwords, API keys, and certificates. * **Don't Do This:** Hardcode secrets in your application code or configuration files. * **Consider:** Use SealedSecrets, HashiCorp Vault, or other secrets management solutions for enhanced security, especially in production. **Why:** Secrets are stored as base64 encoded strings and can be mounted as volumes or environment variables. **Code Example (Secret):** """yaml apiVersion: v1 kind: Secret metadata: name: my-secret type: Opaque # Optional, define the type of secret data: my_secret_key: $(echo -n 'my_secret_value' | base64) """ **Note:** Encode the secret value using base64. Don't store plain-text passwords. Access the Secret using environment variables: """yaml apiVersion: apps/v1 kind: Deployment metadata: name: my-app spec: replicas: 1 selector: matchLabels: app: my-app template: metadata: labels: app: my-app spec: containers: - name: my-container image: my-image env: - name: MY_SECRET_VAR valueFrom: secretKeyRef: name: my-secret key: my_secret_key """ ### 4.3. Projected Volumes * **Do This:** Use projected volumes to inject multiple ConfigMaps and Secrets into a pod as a single volume. * **Don't Do This:** Mount ConfigMaps and Secrets as individual volumes unless absolutely necessary. **Why:** Projected volumes simplify configuration management by providing a single point of access for multiple configuration sources. **Code Example (Projected Volume):** """yaml apiVersion: apps/v1 kind: Pod metadata: name: my-pod spec: containers: - name: my-container image: my-image volumeMounts: - name: config-volume mountPath: /etc/config readOnly: true volumes: - name: config-volume projected: sources: - configMap: name: my-config - secret: name: my-secret """ ### 4.4. Anti-Patterns: Configuration * **Anti-Pattern:** Storing secrets directly in ConfigMaps. * **Better:** Use Secrets for sensitive data, and consider a secrets management solution. * **Anti-Pattern:** Hardcoding configuration values into container images. * **Better:** Externalize configuration using ConfigMaps and Secrets. ## 5. Data Backup and Recovery Implementing robust backup and recovery strategies is crucial for stateful applications. ### 5.1. Backup Strategies * **Do This:** Regularly back up your persistent volumes using Kubernetes-aware backup solutions like Velero, Kopia, or cloud provider-specific tools. * **Don't Do This:** Rely solely on manual backups. Automate the backup process to minimize data loss. **Why:** Regular backups protect against data loss due to hardware failures, accidental deletions, or other disasters. ### 5.2. Recovery Procedures * **Do This:** Document your recovery procedures and test them regularly. * **Don't Do This:** Wait until a disaster occurs to figure out how to restore your data. **Why:** Practiced recovery procedures minimize downtime and ensure you can restore your application to a known good state. ### 5.3. Volume Snapshots * **Do This:** Utilize Volume Snapshots, if supported by your CSI driver and storage provider. * **Don't Do This:** Ignore snapshots if they are provided by your storage backend, as they improve backup and restore times significantly. **Why:** Volume snapshots can allow you to create a point-in-time copy of a volume, which can then be restored from quickly and easily. Backup solutions can be configured to use snapshots for even faster backup. **Code Example (VolumeSnapshotClass):** """yaml apiVersion: snapshot.storage.k8s.io/v1 kind: VolumeSnapshotClass metadata: name: csi-aws-vsc driver: ebs.csi.aws.com # Or your provider's CSI driver deletionPolicy: Delete # Or Retain, based on your disaster recovery plan parameters: csi.storage.k8s.io/snapshotter-secret-name: aws-secret csi.storage.k8s.io/snapshotter-secret-namespace: default """ **Code Example (VolumeSnapshot):** """yaml apiVersion: snapshot.storage.k8s.io/v1 kind: VolumeSnapshot metadata: name: my-snapshot spec: volumeSnapshotClassName: csi-aws-vsc source: persistentVolumeClaimName: my-pvc """ ### 5.4. Anti-Patterns: Backup and Recovery * **Anti-Pattern:** Infrequent backups. * **Better:** Schedule backups based on your application's RPO (Recovery Point Objective). * **Anti-Pattern:** Lack of tested recovery procedures. * **Better:** Regularly test your recovery procedures to ensure they work in a real disaster scenario. * **Anti-Pattern:** Storing backups in the same location as the primary data. * **Better:** Use offsite backups to protect against regional outages. ## 6. Advanced State Management Patterns Kubernetes offers several advanced patterns for state management, particularly for complex stateful applications. ### 6.1. Operators * **Do This:** Consider using Kubernetes Operators for managing complex stateful applications. * **Don't Do This:** Manually manage the lifecycle of complex applications in Kubernetes. **Why:** Operators encapsulate the operational knowledge of managing an application, automating tasks like provisioning, scaling, upgrades, and backups. * Operators use Custom Resource Definitions (CRDs) to extend the Kubernetes API. ### 6.2. Local Persistent Volumes * **Do This:** Use Local Persistent Volumes (Local PVs) for applications that require low-latency access to storage, such as distributed databases. * **Don't Do This:** Use Local PVs for applications that require high availability or data replication across multiple nodes. **Why:** Local PVs provide direct access to locally attached storage devices, improving performance but sacrificing some of the availability and portability of traditional PVs. ### 6.3. Data Locality Optimization * **Do This:** Strive to schedule pods needing data access to nodes where the data already resides, using node affinity or topology spread constraints. * **Don't Do This:** Ignore data locality as failing to optimize this can lead to significant performance degradation and increased network traffic. **Why:** Scheduling pods near their data can dramatically reduce latency and improve overall application performance. ### 6.4. Anti-Patterns: Advanced Patterns * **Anti-Pattern:** Overusing operators for simple applications. * **Better:** Operators are best suited for managing complex, stateful workloads. * **Anti-Pattern:** Ignoring the limitations of Local PVs. * **Better:** Understand the availability and portability trade-offs before using Local PVs. ## 7. Conclusion These standards provide a foundation for building robust and maintainable stateful applications in Kubernetes. By adhering to these guidelines, developers can ensure that applications manage state effectively, are highly available, and can be easily scaled and maintained. Remember to always consult the [official Kubernetes documentation](https://kubernetes.io/docs/home/) for the most up-to-date information. As Kubernetes evolves, so too will these best practices; continuous learning and adaptation are key to successful Kubernetes development.