diegolnasc/kubernetes-best-practices: A Practical Kubernetes Cookbook

What diegolnasc/kubernetes-best-practices Covers

diegolnasc/kubernetes-best-practices is a cookbook for engineers who work with Kubernetes and need a structured set of operational recommendations. The README describes its purpose as helping readers climb the Kubernetes learning curve and prepare environments that are stable, reliable, and functional. Its likely audience includes developers, platform engineers, and teams reviewing how applications are organized within a cluster.

The repository is not an application that installs a cluster, deploys workloads, or manages infrastructure by itself. Its value comes from documenting decisions that affect cluster usage and application behavior. The table of contents covers container practices, cluster infrastructure, namespaces, security, RBAC, labels, probes, resources, scalability, Pod Disruption Budgets, affinity, taints and tolerations, deployments, shutdown behavior, network policies, service meshes, secrets management, observability, GitOps, and deployment review.

That scope makes the project a review aid rather than a complete operating manual. The README does not document a one-command installation, cluster provisioning procedure, or complete example for every listed topic. It also says that the repository has no GitHub releases. A team can use its recommendations to identify missing configuration, but it still needs Kubernetes documentation and provider documentation to turn those checks into production procedures.

How the Kubernetes Cookbook Is Organized

The repository uses Markdown files arranged by operational area. The README table of contents points to a container section and groups the remaining material under cluster, basics, networking, secrets management, observability, and deployment and review. This structure follows a Kubernetes environment from infrastructure and object organization toward workload behavior and operational review.

The namespace example illustrates the intended level of specificity. A namespace is described as a way to organize objects, products, and teams. The guide recommends namespaces for separating teams or products in larger organizations, while also noting that logical separation should match the organization's size and cost constraints. Its example creates a namespace and pairs it with a ResourceQuota containing CPU and memory requests and limits. That combination connects organizational separation with a resource control.

The infrastructure section adds another layer. It recommends calculating CIDR ranges from the expected number of pods per node and maximum node count, restricting access to nodes and the Kubernetes API, and versioning infrastructure changes with tools such as Terraform, CloudFormation, or Ansible. The README does not turn those recommendations into an end-to-end infrastructure-as-code project. The adopting team must still choose its network ranges, deployment stages, and automation boundaries.

Installing the Repository and Creating a Namespace

The project does not document a package installation command or a containerized distribution. It is a documentation repository, so the Markdown files are the usable artifact. The README links to `CONTRIBUTING.md` and displays a contributions-welcome badge, but it does not define a build command, published package, or container image for the cookbook.

The first concrete Kubernetes action shown in the README is namespace creation. The example uses `kubectl`, so the reader needs a configured Kubernetes context before applying it. This command creates a namespace named `my-first-namespace`.

kubectl create namespace my-first-namespace

After the command completes, the README suggests applying a ResourceQuota where possible. The following manifest sets CPU and memory requests and limits for the namespace. The quota values are an example from the repository, not universal defaults.

apiVersion: v1
kind: ResourceQuota
metadata:
  name: my-first-namespace
spec:
  hard:
    requests.cpu: "10"
    requests.memory: 10Gi
    limits.cpu: "20"
    limits.memory: 20Gi

The manifest controls aggregate requests and limits for resources in the namespace. The README does not show the command used to apply the YAML or explain whether these exact values will be accepted in another cluster. Readers should inspect their current quota policy, workload requests, and available capacity before copying the example.

How the README Frames Cluster Networking and Cost

The infrastructure guidance starts with capacity and network planning. The README says to estimate pods per node and calculate CIDR ranges around the expected node and service counts. It gives a GCP example in which a `/19` pod range supports 256 nodes when each node permits a maximum of 16 pods, while the associated subnetwork needs at least a `/24`. That example is tied to the linked GCP guidance and should not be reused without checking the provider's current allocation rules.

The same section recommends restricting internet access to nodes and the Kubernetes API. It also advises separating accounts, projects, private networks, or VPCs for development and production when the organization is large enough. This is guidance rather than an implemented architecture. The README does not define cloud accounts, firewall rules, cluster endpoints, or environment promotion pipelines.

Cost guidance covers committed-use discounts, machine selection, monitoring expense, workload-specific node pools, spot or preemptible capacity, and autoscaling. Batch jobs that do not need low latency may run in a less expensive region, according to the guide, but data-transfer and job-lifecycle costs must also be considered. The README's example of 31% savings for GCP E2 types compared with default N1 is a provider-specific pricing statement, not a general performance or cost promise.

Reliability Topics in the Kubernetes Basics

The basics section covers controls that affect workload behavior after a pod has been scheduled. Its security material points to Kubernetes Pod Security Standards. A note in the README states that Pod Security Policy, or PSP, was deprecated in Kubernetes 1.21 and removed in 1.25, and directs readers toward Pod Security Admission. This version boundary matters because configurations referring to PSP cannot be treated as current recommendations.

The README also lists RBAC, probes, resources, scalability, Pod Disruption Budgets, affinity and anti-affinity, taints and tolerations, deployments, and shutdown behavior. These topics address different operational decisions. RBAC controls permissions. Probes communicate workload state to Kubernetes. Resource requests and limits define capacity expectations. Scheduling rules affect node placement, while Pod Disruption Budgets and shutdown behavior influence voluntary disruptions.

These concerns cannot be evaluated independently. A workload with resource requests may remain unscheduled if its affinity rules do not match available nodes. Incorrect probe definitions may affect restarts or traffic handling. Strong RBAC restrictions may also conflict with automation accounts. The README identifies each topic, but the available text does not include enough manifests to implement a complete policy across all of them. It functions as a checklist that points engineers toward the corresponding Kubernetes documentation.

Networking, Secrets, Observability, and GitOps Gaps

The networking section names Network Policies and service meshes, but it does not supply a policy manifest, mesh installation guide, or traffic example. These mechanisms have different purposes. Network Policies restrict selected connections between workloads, while a service mesh adds infrastructure and configuration for service-to-service communication. The table of contents alone does not tell readers which implementation or adoption level the author recommends.

Secrets management is another listed area with little detail in the README. It does not name an external secret store, prescribe a Kubernetes Secret layout, describe encryption at rest, or document a rotation process. That leaves a significant operational decision unresolved. The section can prompt an engineer to review secret handling, but it does not establish how secrets should be delivered, consumed, rotated, or revoked in production.

Observability and GitOps appear in the later sections, yet the README does not identify a specific logging system, metrics stack, dashboard, alerting tool, or GitOps controller in the documented text. It connects operational configuration with deployment and review, which makes it useful as a topic map. However, teams should not treat the repository as a ready-made observability platform or continuous delivery implementation. The linked Kubernetes and provider documentation remain necessary for feature-specific configuration.

Maintenance, Upgrades, and the Apache-2.0 License

The repository is not archived, and the last push was on 2026-04-27. It has no GitHub releases. The README therefore does not establish a release history, semantic-version contract, or documented compatibility range for each recommendation. This matters because Kubernetes itself changes over time, as illustrated by the README's note about PSP deprecation and removal. Readers should check whether linked Kubernetes features and provider examples still match their cluster version.

The project is licensed under Apache-2.0, and the README displays a badge identifying that license. The `LICENSE` file contains the repository's license terms. Teams adapting or redistributing documentation should inspect that file for attribution, notice, and modification requirements. This is a technical review of repository licensing implications, not legal advice.

Compared with Kubernetes reference documentation, the cookbook is narrower and more selective. The official documentation explains APIs and platform behavior, while this repository gathers review points across infrastructure and application configuration. Compared with a complete infrastructure-as-code project, it names Terraform, CloudFormation, and Ansible but does not provide a ready-to-apply cluster implementation. Its adoption cost is primarily the work required to translate recommendations into organization-specific controls.

Editorial conclusion

Engineers and platform teams can use this repository as a practical review guide, particularly when organizing a cluster or assessing Kubernetes configuration. It is not sufficient for teams that need complete API references, version-specific procedures, or provider-specific production instructions. Verify the linked Kubernetes documentation, cluster version, resource limits, and provider constraints before applying its recommendations. For an initial configuration, the README provides a namespace command and a ResourceQuota manifest, which are its two concrete starting points.

Frequently asked questions

Official sources

1. diegolnasc/kubernetes-best-practices on GitHub
2. Issues
3. License: Apache-2.0
4. README