Skip to content

About

A Kubernetes operator designed to intelligently manage resource overcommit on pod resource requests.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

152 stars

Watchers

3 watching

Forks

Latest commit

Β 

History

71 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

πŸš€ k8s-overcommit Operator

Intelligent resource overcommit management for Kubernetes clusters

GitHub License GitHub Release Go Version Build Status

Kubernetes Operator SDK Go Helm REUSE Compliance

GitHub Issues GitHub Pull Requests GitHub Stars GitHub Forks

πŸš€ Quick Start β€’ πŸ“– Documentation β€’ 🀝 Contributing β€’ πŸ“ License

Logo

🎯 Overview

The k8s-overcommit Operator is a Kubernetes operator designed to intelligently manage resource overcommit on pod resource requests. It automatically adjusts CPU and memory requests based on configurable overcommit classes, enabling better cluster resource utilization while maintaining workload performance.

✨ Key Features

  • πŸŽ›οΈ Flexible Overcommit Classes: Define different overcommit policies for different workload types
  • 🏷️ Label-Based Configuration: Apply overcommit using pod or namespace labels
  • πŸ›‘οΈ Namespace Exclusions: Protect critical namespaces from overcommit policies
  • πŸ“Š Default Policies: Fallback overcommit values when no specific class is defined
  • πŸ”’ Admission Webhooks: Seamless integration with Kubernetes admission controllers
  • πŸ“ˆ Resource Optimization: Improve cluster resource utilization efficiency

πŸ“¦ Where to find it

The operator is published in the community OLM catalogs, so it can be installed without cloning this repository:

Catalog Where it is available Package Channels
OperatorHub.io Any Kubernetes cluster running OLM k8s-overcommit stable (default), alpha
OpenShift community operators OpenShift 4.15 and later, through the embedded OperatorHub k8s-overcommit stable (default), alpha
Project catalog Any Kubernetes cluster running OLM, catalog published from this repository k8s-overcommit stable (default), alpha

On a disconnected cluster, mirror the catalog image into your own registry before installing; the operator image and cert-manager have to be mirrored as well.


πŸš€ Quick Start

🎯 Method 1: Helm Installation (Recommended)

1️⃣ Clone the Repository

Clone the repository to your local machine:

git clone https://github.com/InditexTech/k8s-overcommit-operator.git
cd k8s-overcommit-operator

2️⃣ Configure Values

Edit the values.yaml file to customize your deployment. Below is an example configuration:

# Example configuration
deployment:
  image:
    registry: ghcr.io
    image: inditextech/k8s-overcommit-operator
    tag: 1.3.6

3️⃣ Install with Helm

Install the operator using Helm:

helm install k8s-overcommit-operator chart

πŸ”§ Method 2: OLM Installation

Option A: From the community catalogs (recommended)

The operator is published in the community OLM catalogs, so there is nothing to clone: on OpenShift 4.15 or later it is part of the embedded OperatorHub, and on upstream OLM clusters it comes from OperatorHub.io.

Create the Subscription:

apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: k8s-overcommit
  namespace: openshift-operators
spec:
  channel: stable
  name: k8s-overcommit
  source: community-operators
  sourceNamespace: openshift-marketplace

community-operators in openshift-marketplace is the OpenShift catalog. On clusters that consume OperatorHub.io instead, use source: operatorhubio-catalog and sourceNamespace: olm. In the web console it is the same thing through Operators β†’ OperatorHub, searching for "K8s Overcommit".

Option B: From this repository's own catalog

Use this when you want the catalog published by this project instead of the community one.

1. Install the CatalogSource

kubectl apply -f https://raw.githubusercontent.com/InditexTech/k8s-overcommit-operator/refs/heads/main/deploy/catalog_source.yaml

2. Apply the OperatorGroup

kubectl apply -f https://raw.githubusercontent.com/InditexTech/k8s-overcommit-operator/refs/heads/main/deploy/operator_group.yaml

3. Create the Subscription

The repository ships a working Subscription in deploy/subscription.yaml; apply it with:

kubectl apply -f https://raw.githubusercontent.com/InditexTech/k8s-overcommit-operator/refs/heads/main/deploy/subscription.yaml

Validation

After installation, check that the CSV reached Succeeded and that the operator pod is running (the namespace is openshift-operators with Option A and k8s-overcommit with Option B):

kubectl get csv -A | grep k8s-overcommit
kubectl get pods -A | grep k8s-overcommit

πŸ“ Configuration

🎯 Overcommit Resource

Important

It's a singleton CRD: only can exist one, and it has to be called cluster

First, deploy the main Overcommit resource named "cluster":

apiVersion: overcommit.inditex.dev/v1alphav1
kind: Overcommit
metadata:
  name: cluster
spec:
  overcommitLabel: inditex.com/overcommit-class
  labels:
    environment: production
  annotations:
    description: "Main overcommit configuration"

🏷️ OvercommitClass Resource

Define overcommit classes for different workload types:

apiVersion: overcommit.inditex.dev/v1alphav1
kind: OvercommitClass
metadata:
  name: high
spec:
  cpuOvercommit: 0.2        # 20% of limits as requests
  memoryOvercommit: 0.8     # 80% of limits as requests
  excludedNamespaces: ".*(^(openshift|k8s-overcommit|kube).*).*"
  isDefault: true
  failurePolicy: Fail       # Fail (default) | Ignore
  labels:
    workload-type: batch
  annotations:
    description: "High-density workloads with aggressive overcommit"

πŸ’‘ How It Works

πŸ” Label Resolution Priority

  1. Pod Level: Check if pod has the overcommit class label
  2. Namespace Level: If not found, check namespace labels
  3. Default Class: Apply default overcommit class if configured

πŸ“Š Calculation Example

Original Pod Specification:

apiVersion: v1
kind: Pod
metadata:
  name: test
  labels:
    inditex.com/overcommit-class: high
spec:
  resources:
    limits:
      cpu: "2"
      memory: "2Gi"

With OvercommitClass (cpuOvercommit: 0.2, memoryOvercommit: 0.8):

apiVersion: v1
kind: Pod
metadata:
  name: test
  labels:
    inditex.com/overcommit-class: high
spec:
  resources:
    limits:
      cpu: "2"           # Unchanged
      memory: "2Gi"      # Unchanged
    requests:
      cpu: "400m"        # 2 * 0.2 = 0.4 cores
      memory: "1638Mi"   # 2Gi * 0.8 = 1.6GiB

πŸ›‘οΈ Namespace Exclusions

Protect critical namespaces using regex patterns:

excludedNamespaces: ".*(^(openshift|k8s-overcommit|kube).*).*"

This excludes:

  • openshift-*
  • k8s-overcommit-*
  • kube-*

🚦 Webhook Failure Policy

failurePolicy decides what happens to a pod when the mutating webhook cannot be reached (timeout, network error, 5xx):

Value Behaviour
Fail (default) The pod creation is rejected until the webhook answers again. Loud, and it can block workloads cluster-wide during an operator outage.
Ignore The pod is admitted without the overcommit mutation. Scheduling never blocks, but pods created during the outage get no overcommit applied.

The value is per OvercommitClass and is reconciled into the MutatingWebhookConfiguration the operator generates for that class, so editing it on a running cluster takes effect without reinstalling anything.

spec:
  failurePolicy: Ignore   # keep the cluster schedulable if the webhook goes down

Only Fail and Ignore are valid; the CRD enforces the enum, so a typo such as fail fails on kubectl apply instead of at reconcile time.


πŸ“š Documentation

Topic Description Link
πŸ—οΈ Architecture Detailed architecture overview Architecture Guide
πŸ§ͺ E2E Testing End-to-end testing guide E2E Testing
🎯 Helm Configuration Helm chart configuration options Helm Values
🀝 Contributing How to contribute to the project Contributing Guide
πŸ“‹ Code of Conduct Community guidelines Code of Conduct

🀝 Contributing

We welcome contributions! Please see our Contributing Guide for details on how to:

  • πŸ› Report bugs
  • πŸ’‘ Request features
  • πŸ”§ Submit pull requests
  • πŸ“ Improve documentation

πŸš€ Development Quick Start

# Generate the manifests
make generate manifests

# Install the CRDs
make install

# Run locally
make run

# Run tests
make test

# Build image
make docker-build

πŸš€ Develop with Tilt

Tilt is a tool that streamlines Kubernetes development by automating build, deploy, and live-update workflows.

./hack/tilt/run_tilt.sh

πŸ“„ License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.


πŸ™ Acknowledgments

  • Built with ❀️ by the Inditex Tech team
  • Powered by Operator SDK
  • Inspired by Kubernetes community best practices

⭐ Star this project if you find it useful!

Made with ❀️ for the Kubernetes community


πŸ—οΈ Architecture

Architecture Diagram

πŸ”„ Kubernetes API Flow

flowchart LR
    subgraph "Main Flow"
    A[πŸ“ API Request] --> B[πŸ”§ API HTTP Handler]
    B --> C[πŸ” Authentication & Authorization]
    C --> D[πŸ”„ Mutating Admission]
    D --> E[βœ… Object Schema Validation]
    E --> F[πŸ›‘οΈ Validating Admission]
    F --> G[πŸ’Ύ Persisted to etcd]
    end

    subgraph "Mutating Webhooks"
    direction LR
    D --> MW1[πŸ”„ Overcommit Webhook]
    D --> MW2[πŸ”„ Other Webhooks]
    end

    subgraph "Validating Webhooks"
    direction LR
    F --> VW1[βœ… Validation Webhook 1]
    F --> VW2[βœ… Validation Webhook 2]
    F --> VW3[βœ… Validation Webhook 3]
    end
Loading

About

A Kubernetes operator designed to intelligently manage resource overcommit on pod resource requests.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

152 stars

Watchers

3 watching

Forks

Releases

Packages

Used by

Contributors

Languages