Kinc – Kubernetes in a Container

kinc is a rootless, single-container Kubernetes distribution designed for development, testing, and edge deployments. It provides a complete Kubernetes cluster running entirely in userspace without requiring root privileges or complex multi-container orchestration.

kinc packages a complete Kubernetes v1.33.5 cluster into a single container image, featuring:

• Rootless Operation: Runs entirely in userspace without root privileges
• Single Container: All components (etcd, API server, kubelet, etc.) in one container
• Multi-Cluster Support: Deploy multiple isolated clusters concurrently
• Podman Quadlet Integration: Native systemd service management
• Dynamic Resource Allocation: Automatic port and CIDR management

• Base OS: Fedora 42
• Container Runtime: CRI-O 1.33 with rootless configuration
• Low-Level Runtime: crun with custom wrapper for rootless compatibility
• Init System: systemd for service orchestration

• Kubernetes: v1.33.5 (kubeadm, kubelet, kubectl)
• CNI: kincnet (custom bridge-based networking)
• Storage: local-path-provisioner for dynamic PV provisioning
• DNS: CoreDNS for service discovery

kinc includes a sophisticated crun wrapper (/usr/local/bin/crun-wrapper.sh) that:

• Removes oomScoreAdj settings that fail in rootless environments
• Strips problematic user settings to avoid capset issues
• Handles helper container capability restrictions
• Uses jq for safe JSON manipulation of OCI specs

Automated cgroup v2 setup via kinc-cgroup-setup.service:

• Enables necessary cgroup controllers (cpu, memory, pids, io)
• Configures cgroup delegation for rootless operation
• Handles systemd slice configuration

• Custom CNI plugin (kincnet) optimized for rootless containers
• Automatic IP forwarding validation and setup
• Dynamic CIDR allocation to prevent cluster conflicts

kinc uses environment inspection for deterministic resource allocation:

Network subnets are derived from API server ports:

Each cluster gets:

• Unique container name: kinc-{cluster-name}-control-plane
• Dedicated Podman volumes: kinc-{cluster-name}-var-data, kinc-{cluster-name}-config
• Isolated systemd services: kinc-{cluster-name}-control-plane.service
• Separate network namespaces with non-overlapping IP ranges

• Podman 4.0+ with rootless configuration
• systemd user services enabled
• IP forwarding enabled: echo 1 | sudo tee /proc/sys/net/ipv4/ip_forward

• CLUSTER_NAME: Cluster identifier (default: "default")
• FORCE_PORT: Override automatic port allocation
• CACHE_BUST: Force package updates during build

kinc uses Podman Quadlet for systemd integration:

• Volume Files: runtime/quadlet/*.volume - Define persistent storage
• Container File: runtime/quadlet/kinc-control-plane.container - Container specification
• Config Volume: Runtime-mounted kubeadm.conf for cluster-specific configuration

Each cluster uses a dynamically generated kubeadm.conf:

• Cluster-specific naming and endpoints
• Dynamic CIDR allocation
• Container IP address templating

1. OOM Score Adjustment: crun wrapper removes problematic oomScoreAdj settings
2. Capability Management: Dynamic capability stripping for helper containers
3. User Namespace Mapping: Proper UID/GID handling in rootless environments
4. Cgroup Delegation: Automated cgroup controller setup for systemd
5. Network Isolation: CNI plugin optimized for rootless networking

• Bridge-based networking with NAT
• Automatic IP address management
• DNS integration with CoreDNS
• Support for NetworkPolicies

• API Server: Dynamic allocation starting from 6443
• Service NodePorts: 30000-32767 (standard Kubernetes range)
• Host Network: Isolated per cluster

• Provisioner: local-path-provisioner
• Storage Class: standard (default)
• Backend: Host filesystem via Podman volumes
• Access Modes: ReadWriteOnce (RWO)

• Data Volume: /var mount for kubelet, etcd, logs
• Config Volume: /etc/kinc/config for cluster configuration
• Container Storage: Shared with host for image management

• No root privileges required
• User namespace isolation
• Seccomp and AppArmor integration
• Limited capability sets

• Isolated network namespaces per cluster
• Configurable NetworkPolicies
• No privileged network operations

1. IP Forwarding: Ensure net.ipv4.ip_forward=1
2. Systemd Services: Check systemctl --user status kinc-*
3. Container Logs: Use podman logs kinc-{cluster}-control-plane
4. Resource Conflicts: Verify unique ports with podman ps

kinc is designed for extensibility:

• CNI Plugins: Add custom networking solutions
• Storage Providers: Integrate additional storage backends
• Monitoring: Extend observability capabilities
• Multi-Architecture: Support ARM64 and other platforms

THE SOFTWARE IS AI GENERATED AND PROVIDED “AS IS”, WITHOUT CLAIM OF COPYRIGHT OR WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

kinc - Kubernetes simplified, containerized, and democratized for rootless environments.