# Karpenter IBM Cloud Provider

<div>
  <h2>Automatic Node Provisioning for Kubernetes on IBM Cloud VPC</h2>
  <p>
    <a href="https://github.com/pfeifferj/karpenter-provider-ibm-cloud/releases">
      <img src="https://img.shields.io/github/v/release/pfeifferj/karpenter-provider-ibm-cloud?style=flat-square" alt="Release">
    </a>
    <a href="https://github.com/pfeifferj/karpenter-provider-ibm-cloud/blob/main/LICENSE">
      <img src="https://img.shields.io/github/license/pfeifferj/karpenter-provider-ibm-cloud?style=flat-square" alt="License">
    </a>
    <a href="https://github.com/pfeifferj/karpenter-provider-ibm-cloud/actions">
      <img src="https://img.shields.io/github/actions/workflow/status/pfeifferj/karpenter-provider-ibm-cloud/ci.yml?style=flat-square" alt="CI Status">
    </a>
  </p>
</div>

## Overview

The Karpenter IBM Cloud Provider enables automatic node provisioning and scaling for Kubernetes clusters running on IBM Cloud VPC infrastructure. It implements the Karpenter provisioning APIs to provide just-in-time compute resources based on application demands.

<div class="grid cards" markdown>

- :rocket: **[Getting Started](getting-started.md)**  
  Get up and running with Karpenter on IBM Cloud in minutes

- :cloud: **[VPC Integration](vpc-integration.md)**  
  Deploy on self-managed Kubernetes clusters with full control

- :office: **[IKS Integration](iks-integration.md)**  
  Seamless integration with IBM Kubernetes Service

- :gear: **[Configuration](bootstrap-methods.md)**  
  Learn about bootstrap methods and configuration options

</div>

## Key Features

### Automatic Node Provisioning
- **Just-in-Time Compute**: Provisions nodes automatically when pods are unschedulable
- **Intelligent Instance Selection**: Chooses optimal instance types based on workload requirements
- **Multi-Zone Support**: Distributes nodes across availability zones for high availability

### Zero-Configuration Bootstrap
- **Automatic Cluster Discovery**: Detects cluster configuration without manual setup
- **Dynamic Bootstrap Scripts**: Generates appropriate initialization scripts
- **Multiple Bootstrap Modes**: Supports VPC, IKS, and automatic mode selection

### Enterprise-Ready
- **Production Tested**: Deployed in production environments
- **IBM Cloud Native**: Deep integration with VPC and IKS services
- **Security First**: Follows IBM Cloud security best practices

### Cost Optimization
- **Node Consolidation**: Automatically removes underutilized nodes
- **Right-Sizing**: Selects appropriate instance types to minimize costs
- **Spot Instance Ready**: Prepared for future IBM Cloud spot instance support

## Quick Start

### Prerequisites
- IBM Cloud account with VPC access
- Kubernetes cluster (IKS or self-managed)
- kubectl and Helm 3 installed

### Installation
```bash
# Add Helm repository
helm repo add karpenter-ibm https://pfeifferj.github.io/karpenter-provider-ibm-cloud
helm repo update

# Install Karpenter
helm install karpenter karpenter-ibm/karpenter \
  --namespace karpenter \
  --create-namespace \
  --set controller.env.IBM_REGION="us-south"
```

### Create Your First NodeClass
```yaml
apiVersion: karpenter.ibm.sh/v1alpha1
kind: IBMNodeClass
metadata:
  name: default
spec:
  region: us-south
  zone: us-south-1
  vpc: vpc-12345678
  image: r006-ubuntu-20-04
  securityGroups:
  - sg-12345678
```

### Create NodePool
```yaml
apiVersion: karpenter.sh/v1
kind: NodePool
metadata:
  name: default
spec:
  template:
    spec:
      nodeClassRef:
        name: default
      requirements:
      - key: node.kubernetes.io/instance-type
        operator: In
        values: ["bx2-2x8", "bx2-4x16"]
  limits:
    cpu: 1000
```

## Architecture

The Karpenter IBM Cloud Provider consists of several key components:

```mermaid
graph TB
    subgraph "Kubernetes Cluster"
        K[Karpenter Controller]
        NP[NodePool]
        NC[NodeClaim]
        INC[IBMNodeClass]
        P[Pending Pods]
    end
    
    subgraph "IBM Cloud"
        VPC[VPC Infrastructure]
        IKS[IKS Service]
        VSI[Virtual Server Instances]
    end
    
    P -->|Triggers| K
    K -->|Creates| NC
    K -->|Reads| NP
    K -->|Reads| INC
    NC -->|Provisions| VSI
    VSI -->|Joins| K
    INC -.->|Config| VPC
    INC -.->|Config| IKS
```

## Deployment Options

### VPC Self-Managed Clusters
- Full control over Kubernetes configuration
- Dynamic instance type selection
- Custom bootstrap configurations
- Ideal for specialized workloads

### IBM Kubernetes Service (IKS)
- Seamless integration with managed service
- Worker pool expansion
- Enterprise compliance
- Simplified operations

## Documentation

<div class="grid cards" markdown>

- **:material-book-open: User Guides**
    - [Getting Started](getting-started.md)
    - [Bootstrap Methods](bootstrap-methods.md)
    - [Security Considerations](security-considerations.md)

- **:material-wrench: Configuration**
    - [IBMNodeClass Reference](reference/ibmnodeclass.md)
    - [NodePool Examples](reference/nodepool.md)
    - [Environment Variables](reference/environment.md)

- **:material-puzzle: Integration**
    - [IKS Integration](iks-integration.md)
    - [VPC Integration](vpc-integration.md)
    - [CNI/CRI Support](supported-cni-cri.md)

- **:material-help-circle: Support**
    - [Troubleshooting](troubleshooting.md)
    - [Known Limitations](limitations.md)
    - [FAQ](faq.md)

</div>

## Community

- **GitHub**: [Report issues and contribute](https://github.com/pfeifferj/karpenter-provider-ibm-cloud)
- **Discussions**: [Ask questions and share experiences](https://github.com/pfeifferj/karpenter-provider-ibm-cloud/discussions)

## License

This project is licensed under the Apache License 2.0. See the [LICENSE](https://github.com/pfeifferj/karpenter-provider-ibm-cloud/blob/main/LICENSE) file for details.