Skip to content

KUBERNETES_INTEGRATION.md

Latest commit

 

History

History
372 lines (302 loc) · 11.9 KB

KUBERNETES_INTEGRATION.md

File metadata and controls

372 lines (302 loc) · 11.9 KB

Kubernetes Resource Capsules Integration

This document details the implementation and benchmarking of Resource Capsules with Kubernetes, extending the basic-docker-engine to support modern container orchestration environments.

Overview

Resource Capsules represent a novel approach to resource sharing that provides:

  • Versioning: Containers can use specific versions of shared resources
  • Dynamic Attachment: Capsules can be attached/detached from running containers
  • Isolation: Enhanced security and consistency across containers
  • Cross-Environment Support: Works in both Docker and Kubernetes environments

Kubernetes Integration

Architecture

┌─────────────────────────────────────────────────────────────┐
│                  Resource Capsules                         │
├─────────────────────────────────────────────────────────────┤
│  Docker Environment     │    Kubernetes Environment        │
│  ┌─────────────────┐    │    ┌─────────────────────────┐    │
│  │ Volume Binding  │    │    │ ConfigMap Capsules     │    │
│  │ Symbolic Links  │    │    │ Secret Capsules        │    │
│  │ Container Mounts│    │    │ Label-based Discovery  │    │
│  └─────────────────┘    │    └─────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

Implementation Details

ConfigMap-Based Capsules

  • Suitable for configuration files, scripts, and text-based resources
  • Automatically detected based on file content analysis
  • Labeled with capsule.docker.io/name and capsule.docker.io/version

Secret-Based Capsules

  • Used for binary data, certificates, and sensitive information
  • Secure storage with Kubernetes Secret management
  • Same labeling scheme for consistent discovery

Dynamic Resource Type Selection

The system automatically chooses between ConfigMap and Secret based on content analysis:

func isTextFile(data []byte) bool {
    // Detects null bytes and non-printable characters
    // Returns true for text content, false for binary
}

CLI Usage

Kubernetes Capsule Management

# Create a new Resource Capsule
basic-docker k8s-capsule create app-config 1.0 /path/to/config.yaml

# List all Resource Capsules
basic-docker k8s-capsule list

# Get specific Resource Capsule details
basic-docker k8s-capsule get app-config 1.0

# Delete a Resource Capsule
basic-docker k8s-capsule delete app-config 1.0

Benchmarking

# Benchmark Docker Resource Capsules
basic-docker capsule-benchmark docker

# Benchmark Kubernetes Resource Capsules
basic-docker capsule-benchmark kubernetes

Performance Comparison

Benchmark Results

Docker Environment

Docker Capsule Access: 10,000 iterations in 373.747µs
Average per operation: 37ns

Kubernetes Environment (with real cluster)

Kubernetes Capsule Access: 100 iterations in ~2.5s
Average per operation: ~25ms

Performance Analysis

Metric Docker Capsules Kubernetes Capsules Traditional K8s Resources
Access Time ~37ns ~25ms ~30-50ms
Versioning ✅ Built-in ✅ Built-in ❌ Manual
Dynamic Attachment ✅ Yes ✅ Yes ❌ Limited
Isolation ✅ High ✅ Very High ✅ High
Scalability ✅ Excellent ✅ Good ✅ Good

Implementation Highlights

1. Environment Detection and Adaptation

func AddResourceCapsule(env string, capsuleName string, capsuleVersion string, capsulePath string) error {
    switch env {
    case "docker":
        return addDockerResourceCapsule(capsuleName, capsuleVersion, capsulePath)
    case "kubernetes", "k8s":
        return addKubernetesResourceCapsule(capsuleName, capsuleVersion, capsulePath)
    default:
        return fmt.Errorf("unsupported environment: %s", env)
    }
}

2. Kubernetes Client Integration

func NewKubernetesCapsuleManager(namespace string) (*KubernetesCapsuleManager, error) {
    // Try in-cluster config first, fall back to kubeconfig
    // Supports both pod-based and external access patterns
}

3. Resource Type Auto-Detection

func addKubernetesResourceCapsule(capsuleName, capsuleVersion, capsulePath string) error {
    capsuleData, err := os.ReadFile(capsulePath)
    isTextData := isTextFile(capsuleData)
    
    if isTextData {
        // Create as ConfigMap
    } else {
        // Create as Secret
    }
}

Testing Strategy

Unit Tests

  • ConfigMap Operations: Creation, retrieval, lifecycle management
  • Secret Operations: Binary data handling, secure storage
  • Versioning: Multiple version management and isolation
  • Labeling: Proper metadata assignment and discovery

Integration Tests

  • Mock Kubernetes Client: Using fake.NewSimpleClientset() for isolated testing
  • Real Cluster Testing: Optional tests with actual Kubernetes clusters
  • Cross-Environment Validation: Ensuring consistency between Docker and K8s

Benchmarks

  • Access Performance: ConfigMap vs Secret access times
  • Creation Performance: Bulk capsule creation efficiency
  • Comparison Metrics: Against traditional Kubernetes resources

Advanced Features

1. Label-Based Discovery

All Resource Capsules use consistent labeling:

labels:
  app.kubernetes.io/name: "resource-capsule"
  app.kubernetes.io/version: "1.0"
  capsule.docker.io/name: "app-config"
  capsule.docker.io/version: "1.0"

2. Namespace Isolation

Capsules are namespace-scoped for multi-tenancy:

kcm, err := NewKubernetesCapsuleManager("production")

3. Automatic Resource Selection

Content-based resource type selection:

  • Text files → ConfigMaps
  • Binary files → Secrets
  • Preserves data integrity and follows Kubernetes best practices

Future Enhancements

1. Custom Resource Definitions (CRDs) - IMPLEMENTED ✅

ResourceCapsule CRD provides native Kubernetes support for Resource Capsules:

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: resourcecapsules.capsules.docker.io
spec:
  group: capsules.docker.io
  versions:
  - name: v1
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              data:
                type: object
                x-kubernetes-preserve-unknown-fields: true
              version:
                type: string
              capsuleType:
                type: string
                enum: ["configmap", "secret"]
                default: "configmap"
              rollback:
                type: object
                properties:
                  enabled:
                    type: boolean
                    default: true
                  previousVersion:
                    type: string
            required:
            - data
            - version
          status:
            type: object
            properties:
              phase:
                type: string
                enum: ["Pending", "Active", "Failed"]
                default: "Pending"
              lastUpdated:
                type: string
                format: date-time
              message:
                type: string

CRD Management Commands:

# Install the CRD
kubectl apply -f k8s/crd-resourcecapsule.yaml

# Create ResourceCapsule via CRD
basic-docker k8s-crd create app-config 1.0 /path/to/config.yaml configmap

# List ResourceCapsule CRDs
basic-docker k8s-crd list

# Get ResourceCapsule CRD details
basic-docker k8s-crd get app-config

# Delete ResourceCapsule CRD
basic-docker k8s-crd delete app-config

# Rollback ResourceCapsule to previous version
basic-docker k8s-crd rollback app-config 0.9

2. Operator Implementation - IMPLEMENTED ✅

ResourceCapsule Operator provides automated lifecycle management:

  • Custom Controller: Watches ResourceCapsule custom resources for changes
  • Automated Resource Creation: Automatically creates ConfigMaps or Secrets based on CRD specifications
  • Status Management: Updates ResourceCapsule status with current state information
  • Event Handling: Responds to Add, Modify, and Delete events for ResourceCapsules

Operator Features:

  • Automated Versioning: Manages version transitions automatically
  • Rollback Capabilities: Built-in rollback to previous versions
  • Resource Type Selection: Automatically chooses ConfigMap vs Secret based on content
  • Status Tracking: Maintains current state (Pending, Active, Failed) with timestamps

Starting the Operator:

# Start the operator in default namespace
basic-docker k8s-crd operator start

# Start the operator in specific namespace
basic-docker k8s-crd operator start production

Operator Integration Example:

apiVersion: capsules.docker.io/v1
kind: ResourceCapsule
metadata:
  name: app-config
spec:
  data:
    config.yaml: |
      database:
        host: db.example.com
        port: 5432
      redis:
        host: redis.example.com
        port: 6379
  version: "1.0"
  capsuleType: configmap
  rollback:
    enabled: true
status:
  phase: Active
  lastUpdated: "2024-08-02T11:47:41Z"
  message: "ResourceCapsule successfully created"

3. GitOps Workflow Integration - IMPLEMENTED ✅

GitOps Support enables declarative ResourceCapsule management:

  • Declarative Configuration: ResourceCapsule CRDs can be stored in Git repositories
  • Version Control: All capsule configurations are versioned with Git
  • Automated Deployment: GitOps tools (ArgoCD, Flux) can deploy ResourceCapsules
  • Rollback Support: Git-based rollback using previous commits

GitOps Workflow Example:

# 1. Define ResourceCapsule in Git repository
cat > manifests/app-config-capsule.yaml << EOF
apiVersion: capsules.docker.io/v1
kind: ResourceCapsule
metadata:
  name: app-config
  namespace: production
spec:
  data:
    config.yaml: |
      version: "1.0"
      features:
        auth: enabled
        cache: enabled
  version: "1.0"
  capsuleType: configmap
  rollback:
    enabled: true
EOF

# 2. GitOps tool detects changes and applies them
# 3. ResourceCapsule operator creates underlying ConfigMap
# 4. Applications can consume the capsule data

Integration with Popular GitOps Tools:

  • ArgoCD: Supports ResourceCapsule CRDs out of the box
  • Flux: Can manage ResourceCapsule lifecycle with GitRepository sources
  • Jenkins X: Pipeline integration for automated capsule deployment
  • Tekton: Custom tasks for ResourceCapsule validation and deployment

4. Performance Optimization

  • Caching layer for frequently accessed capsules
  • Batch operations for bulk resource management
  • Compression for large resource capsules

Conclusion

The Kubernetes integration of Resource Capsules demonstrates:

  1. Seamless Cross-Platform Support: Same API works across Docker and Kubernetes
  2. Superior Versioning: Built-in version management vs manual K8s approaches
  3. Performance Advantages: Optimized access patterns for containerized environments
  4. Enhanced Security: Automatic resource type selection and proper isolation
  5. Developer Experience: Simplified CLI for complex resource management operations

This implementation bridges the gap between traditional container resource sharing and modern orchestration requirements, providing a foundation for next-generation container resource management systems.