### Complete Karpenter Deployment Example

Source: https://context7.com/sergelogvinov/karpenter-provider-proxmox/llms.txt

A full example deploying all required resources for Karpenter on Proxmox. It includes the Proxmox configuration secret and a cloud-init template secret for Ubuntu.

```yaml
---
# 1. Proxmox configuration secret
apiVersion: v1
kind: Secret
metadata:
  name: karpenter-provider-proxmox
  namespace: kube-system
stringData:
  config.yaml: |
    clusters:
      - url: "https://proxmox.example.com:8006/api2/json"
        insecure: false
        token_id: "kubernetes@pve!karpenter"
        token_secret: "your-token-secret"
        region: datacenter-1
---
# 2. Cloud-init templates
apiVersion: v1
kind: Secret
metadata:
  name: ubuntu-cloud-init
  namespace: kube-system
stringData:
  user-data: |
    #cloud-config
    hostname: {{ .Metadata.Hostname }}
    users:
      - name: ubuntu
        sudo: ALL=(ALL) NOPASSWD:ALL
        ssh_authorized_keys:
          {{- toYaml (split (get .Values "SSHKeys") ",") | nindent 10 }}
    runcmd:
      - kubeadm join --token {{ .Kubernetes.BootstrapToken }} --discovery-token-ca-cert-hash sha256:{{ get .Values "CAHash" }} {{ get .Values "APIServer" }}:6443
---
```

--------------------------------

### Helm Values Example (YAML)

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/charts/karpenter-provider-proxmox/README.md

This is an example of a Helm values file for deploying the karpenter-provider-proxmox. It configures cluster connection details, including URL, token, and region, and specifies node selectors and tolerations to ensure the controller runs on control-plane nodes.

```yaml
# karpenter-provider-proxmox.yaml

config:
  clusters:
    - url: https://cluster-api-1.exmple.com:8006/api2/json
      insecure: false
      token_id: "kubernetes@pve!karpenter"
      token_secret: "key"
      region: cluster-1

# Deploy controller only on control-plane nodes
nodeSelector:
  node-role.kubernetes.io/control-plane: ""
tolerations:
  - key: node-role.kubernetes.io/control-plane
    effect: NoSchedule
```

--------------------------------

### Install Proxmox Karpenter Provider (Helm)

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/docs/install.md

Deploys or upgrades the Proxmox Karpenter Provider using Helm, referencing a custom values file (`karpenter-proxmox.yaml`) for configuration. This command installs the provider into the `kube-system` namespace.

```shell
helm upgrade -i -n kube-system -f karpenter-proxmox.yaml karpenter-provider-proxmox oci://ghcr.io/sergelogvinov/charts/karpenter-provider-proxmox
```

--------------------------------

### Proxmox VM IP Configuration Example

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/docs/ipam.md

Example of a Proxmox virtual machine configuration snippet demonstrating IPAM settings for both IPv4 and IPv6. It specifies IP address pools and gateways for network interfaces.

```conf
ipconfig0: ip=192.168.0.0/24,gw=192.168.0.1,ip6=fd00:1::0/64,gw6=fd00:1::1
```

--------------------------------

### Install Karpenter Proxmox Provider via Helm

Source: https://context7.com/sergelogvinov/karpenter-provider-proxmox/llms.txt

Deploys the Karpenter Proxmox Provider using a Helm chart. Requires a values file to configure cluster details, settings, node selectors, and tolerations. The chart is installed using `helm upgrade -i`.

```yaml
# karpenter-proxmox-values.yaml
config:
  clusters:
    - url: "https://cluster-api-1.example.com:8006/api2/json"
      insecure: false
      token_id: "kubernetes@pve!karpenter"
      token_secret: "secret-token-value"
      region: Region-1

settings:
  batchMaxDuration: 10s
  batchIdleDuration: 1s
  vmMemoryOverheadPercent: 0.075

nodeSelector:
  node-role.kubernetes.io/control-plane: ""

tolerations:
  - key: node-role.kubernetes.io/control-plane
    effect: NoSchedule

```

```bash
# Install the Helm chart
helm upgrade -i -n kube-system -f karpenter-proxmox-values.yaml \
  karpenter-provider-proxmox oci://ghcr.io/sergelogvinov/charts/karpenter-provider-proxmox

```

--------------------------------

### Install Proxmox Karpenter Provider (kubectl)

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/docs/install.md

Applies the Kubernetes manifest to install the latest release version of the Proxmox Karpenter Provider. This command deploys the provider into the cluster, enabling Proxmox node provisioning.

```shell
kubectl apply -f https://raw.githubusercontent.com/sergelogvinov/karpenter-provider-proxmox/main/docs/deploy/karpenter-provider-proxmox.yml
```

--------------------------------

### Node Topology Configuration Example

Source: https://context7.com/sergelogvinov/karpenter-provider-proxmox/llms.txt

A JSON configuration file defining node topology settings for resource allocation. It specifies CPU and memory configurations for specific Proxmox nodes within different regions, including reserved resources.

```json
// Node topology configuration file (node-settings.json)
{
  "Region-1": {
    "pve-node-1": {
      "sockets": 2,
      "threads": 2,
      "uncorecaches": 2,
      "nodes": {
        "0": {
          "cpus": "0-15",
          "memory": 34359738368
        },
        "1": {
          "cpus": "16-31",
          "memory": 34359738368
        }
      },
      "reservedcpus": [0, 16],
      "reservedmemory": 4294967296
    },
    "*": {
      "reservedcpus": [0, 1],
      "reservedmemory": 2147483648
    }
  },
  "Region-2": {
    "pve-node-3": {
      "reservedcpus": [0],
      "reservedmemory": 1073741824
    }
  }
}
```

--------------------------------

### Proxmox Permissions Setup (Shell)

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/charts/karpenter-provider-proxmox/README.md

This snippet demonstrates how to set up the necessary Proxmox VE permissions for Karpenter. It includes creating a custom role 'Karpenter' with specific privileges and then assigning this role to a Proxmox user, finally generating an API token for authentication.

```shell
# Create role Karpenter
pveum role add Karpenter -privs "Datastore.Allocate Datastore.AllocateSpace Datastore.AllocateTemplate Datastore.Audit Mapping.Audit Mapping.Use Sys.Audit Sys.AccessNetwork SDN.Audit SDN.Use VM.Audit VM.Allocate VM.Clone VM.Config.CDROM VM.Config.CPU VM.Config.Memory VM.Config.Disk VM.Config.Network VM.Config.HWType VM.Config.Cloudinit VM.Config.Options VM.PowerMgmt"

# Create user and grant permissions
pveum user add kubernetes@pve
pveum aclmod / -user kubernetes@pve -role Karpenter
pveum user token add kubernetes@pve Karpenter -privsep 0 --comment "Kubernetes Karpenter"
```

--------------------------------

### Install Proxmox Karpenter Provider (kubectl - Edge)

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/docs/install.md

Applies the Kubernetes manifest to install the latest stable (edge) version of the Proxmox Karpenter Provider. This is useful for testing the newest features or fixes before they are officially released.

```shell
kubectl apply -f https://raw.githubusercontent.com/sergelogvinov/karpenter-provider-proxmox/main/docs/deploy/karpenter-provider-proxmox-edge.yml
```

--------------------------------

### JSON Configuration for Node Topology

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/docs/noderesource.md

Example JSON configuration file to customize node topology. This file defines region-specific settings for CPU and memory reservations, and NUMA topology. The top-level keys are region names, followed by node names or a wildcard '*'. Each node can have reserved CPUs and memory, and optional NUMA settings like sockets, threads, uncore caches, and detailed NUMA node configurations.

```json
{
  "region-1": {
    "node1": {
      "sockets": 1,
      "threads": 2,
      "uncorecaches": 1,
      "nodes": {
        "0": {
          "cpus": "0-15",
          "memory": 4294967296
        },
        "1": {
          "cpus": "16-31",
          "memory": 4294967296
        }
      },

      "reservedcpus": [0,4],
      "reservedmemory": 1073741824
    },
    "node2": {
      "reservedcpus": [1,5],
      "reservedmemory": 4294967296
    },
    "*": {
      "reservedcpus": [1,5],
      "reservedmemory": 4294967296
    }
  },
  "region-2": {
    "node3": {
      "reservedcpus": [0,1],
      "reservedmemory": 1073741824
    }
  }
}
```

--------------------------------

### Install Karpenter Proxmox Provider via kubectl

Source: https://context7.com/sergelogvinov/karpenter-provider-proxmox/llms.txt

Installs the Karpenter Proxmox Provider directly using Kubernetes manifests. This method involves creating a Kubernetes Secret for Proxmox configuration and then applying the provider's deployment manifest. It supports configuring multiple Proxmox clusters.

```yaml
# proxmox-config-secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: karpenter-provider-proxmox
  namespace: kube-system
stringData:
  config.yaml: |
    clusters:
      - url: "https://cluster-api-1.example.com:8006/api2/json"
        insecure: false
        token_id: "kubernetes@pve!karpenter"
        token_secret: "secret-token-value"
        region: Region-1
      - url: "https://cluster-api-2.example.com:8006/api2/json"
        token_id: "kubernetes@pve!karpenter"
        token_secret: "another-secret"
        region: Region-2

```

```bash
# Apply the secret and deploy the provider
kubectl apply -f proxmox-config-secret.yaml
kubectl apply -f https://raw.githubusercontent.com/sergelogvinov/karpenter-provider-proxmox/main/docs/deploy/karpenter-provider-proxmox.yml

```

--------------------------------

### Cloud-Init User Data Template (YAML)

Source: https://context7.com/sergelogvinov/karpenter-provider-proxmox/llms.txt

This Kubernetes Secret defines a cloud-init user-data template using Go templating. It configures the node's hostname, installs packages, sets up users, and prepares Kubernetes join configuration.

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: cloud-init-templates
  namespace: kube-system
stringData:
  user-data: |
    #cloud-config
    hostname: {{ .Metadata.Hostname }}
    manage_etc_hosts: true
    package_update: true
    packages:
      - qemu-guest-agent
      - curl

    users:
      - name: karpenter
        gecos: Kubernetes Node User
        sudo: ALL=(ALL) NOPASSWD:ALL
        groups: [users, docker]
        shell: /bin/bash
        {{- with get .Values "SSHAuthorizedKeys" }}
        ssh_authorized_keys:
          {{- toYaml (split . ",") | nindent 10 }}
        {{- end }}

    write_files:
      - path: /etc/kubernetes/bootstrap-kubelet.conf
        permissions: '0600'
        content: |
          apiVersion: v1
          kind: Config
          clusters:
          - cluster:
              certificate-authority-data: {{ .Kubernetes.RootCA | b64enc }}
              server: https://{{ get .Values "KubernetesAPI" }}:6443
            name: kubernetes
          contexts:
          - context:
              cluster: kubernetes
              user: kubelet-bootstrap
            name: kubelet-bootstrap@kubernetes
          current-context: kubelet-bootstrap@kubernetes
          users:
          - name: kubelet-bootstrap
            user:
              token: {{ .Kubernetes.BootstrapToken }}

      - path: /etc/kubernetes/kubelet-config.yaml
        permissions: '0644'
        content: |
          apiVersion: kubelet.config.k8s.io/v1beta1
          kind: KubeletConfiguration
          clusterDNS:
            {{- range .Kubernetes.KubeletConfiguration.ClusterDNS }}
            - {{ . }}
            {{- end }}
          maxPods: {{ .Kubernetes.KubeletConfiguration.MaxPods }}
          {{- if .Kubernetes.KubeletConfiguration.CPUManagerPolicy }}
          cpuManagerPolicy: {{ .Kubernetes.KubeletConfiguration.CPUManagerPolicy }}
          {{- end }}

    runcmd:
      - systemctl enable --now qemu-guest-agent
      - kubeadm join --config /etc/kubernetes/kubeadm-join.yaml

  meta-data: |
    hostname: {{ .Hostname }}
    instance-id: {{ .InstanceID }}
    instance-type: {{ .InstanceType }}
    provider-id: {{ .ProviderID }}
    region: {{ .Region }}
    zone: {{ .Zone }}

  network-config: |
    version: 1
    config:
      - type: physical
        name: eth0
        mac_address: {{ .Network.MAC }}
        subnets:
          {{- if .Network.IPv4 }}
          - type: static
            address: {{ .Network.IPv4.Address }}
            gateway: {{ .Network.IPv4.Gateway }}
            dns_nameservers:
              {{- range .Network.IPv4.DNS }}
              - {{ . }}
              {{- end }}
          {{- else }}
          - type: dhcp
          {{- end }}
```

--------------------------------

### Helm Deployment Command (Shell)

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/charts/karpenter-provider-proxmox/README.md

This shell command installs or upgrades the karpenter-provider-proxmox Helm chart. It specifies the namespace, the values file to use, and the chart's OCI repository.

```shell
# Install Karpenter
helm upgrade -i --namespace=kube-system -f karpenter-provider-proxmox.yaml \
  karpenter-provider-proxmox oci://ghcr.io/sergelogvinov/charts/karpenter-provider-proxmox
```

--------------------------------

### Install Karpenter Proxmox Helm Chart

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/README.md

This shell command deploys the Karpenter Proxmox Helm chart into the 'kube-system' namespace. It ensures the Karpenter provider is installed and configured to manage Proxmox nodes within the Kubernetes cluster.

```shell
helm upgrade -i -n kube-system karpenter-proxmox oci://ghcr.io/sergelogvinov/charts/karpenter-proxmox
```

--------------------------------

### Map and List Value Retrieval Functions

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/docs/functions.md

These functions allow for accessing values within data structures. `get` retrieves a value from a map using its key. `getValue` extracts a specific value from a query string based on a key-value pair format.

```yaml
{{ get (dict "a" 1 "b" 2) "a" }} -> 1
{{ getValue "ds=nocloud;i=1234" "i" }} -> 1234
```

--------------------------------

### Get Host IP from CIDR Notation (YAML)

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/docs/functions.md

The `cidrhost` function returns the IP address of a host within a given CIDR block. It can optionally take an integer to specify the host's IP address within the subnet.

```yaml
{{ cidrhost "192.168.1.5/24" }} -> 192.168.1.5
```

```yaml
{{ cidrhost "192.168.1.5/24" 15 }} -> 192.168.1.15
```

--------------------------------

### String Content Check Functions

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/docs/functions.md

These functions perform boolean checks on string content. `empty` returns true if a string is empty. `contains` checks if a string includes a substring. `hasPrefix` and `hasSuffix` verify if a string starts or ends with a specific sequence.

```yaml
{{ empty "" }} -> true
{{ contains "hello" "lo" }} -> true
{{ hasPrefix "hello" "he" }} -> true
{{ hasSuffix "hello" "lo" }} -> true
```

--------------------------------

### Talos Worker Node Cloud-init Configuration

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/examples/talos/README.md

Defines the cloud-init configuration for a Talos worker node. This YAML includes machine-specific settings, Kubelet configurations, and installation details. Secrets are omitted for brevity.

```yaml
version: v1alpha1
debug: false
persist: true
machine:
    type: worker
    token: ...
    ca:
        crt: ...
    kubelet:
        image: ghcr.io/siderolabs/kubelet:v1.33.4
        defaultRuntimeSeccompProfileEnabled: true
        disableManifestsDirectory: true
    network: {}
    install:
        disk: /dev/sda
        image: ghcr.io/siderolabs/installer:v1.10.7
        wipe: false
    features:
        rbac: true
        stableHostname: true
        apidCheckExtKeyUsage: true
        diskQuotaSupport: true
cluster:
    id: ...
    secret: ...
    controlPlane:
        endpoint: https://api.example.com:6443
    clusterName: proxmox
    network:
        dnsDomain: cluster.local
        podSubnets:
            - 10.244.0.0/16
        serviceSubnets:
            - 10.96.0.0/12
    token: ...
    ca:
        crt: ...
```

--------------------------------

### Proxmox User and Token Creation for Karpenter

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/docs/install.md

Creates a dedicated Proxmox user 'kubernetes@pve' and generates an API token for Karpenter. It demonstrates two methods: one with full role privileges and another with restricted token privileges for enhanced security.

```shell
pveum user add kubernetes@pve
pveum aclmod / -user kubernetes@pve -role Karpenter
pveum user token add kubernetes@pve karpenter -privsep 0 --comment "Kubernetes Karpenter"
pveum user add kubernetes@pve
pveum aclmod / -user kubernetes@pve -role Karpenter
pveum user token add kubernetes@pve karpenter -privsep 1 --comment "Kubernetes Karpenter"
pveum aclmod / --token 'kubernetes@pve!karpenter' -role Karpenter
```

--------------------------------

### Define Tolerations for Controller Assignment

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/charts/karpenter-provider-proxmox/README.md

Configures tolerations for the controller pods, allowing them to be scheduled on nodes with specific taints. This is crucial for ensuring the controller can run on control-plane nodes or nodes with specific cloud provider taints. The example includes tolerations for control-plane and uninitialized cloud provider nodes.

```json
[
  {
    "effect": "NoSchedule",
    "key": "node-role.kubernetes.io/control-plane",
    "operator": "Exists"
  },
  {
    "effect": "NoSchedule",
    "key": "node.cloudprovider.kubernetes.io/uninitialized",
    "operator": "Exists"
  }
]
```

--------------------------------

### Proxmox Karpenter Provider Configuration (YAML)

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/docs/install.md

Defines the configuration for the Proxmox Karpenter Provider, specifying connection details for Proxmox clusters, including API URL, token, and region. This YAML file is used to establish communication between Karpenter and Proxmox.

```yaml
clusters:
  # List of Proxmox clusters
  - url: https://cluster-api-1.exmple.com:8006/api2/json
    # Skip the certificate verification, if needed
    insecure: false
    # Proxmox api token
    token_id: "kubernetes@pve!karpenter"
    token_secret: "secret"
    # Region name, which is cluster name
    region: Region-1
```

--------------------------------

### Cloud-Init Template Functions Reference

Source: https://context7.com/sergelogvinov/karpenter-provider-proxmox/llms.txt

Demonstrates various helper functions available in Cloud-init templates for dynamic configuration, including logic, string manipulation, JSON/YAML conversion, network functions, and conditionals.

```yaml
# Logic functions
{{ default "default-value" .Values.OptionalKey }}  # Returns default if empty
{{ coalesce "" "" "first-non-empty" "ignored" }}   # Returns "first-non-empty"
{{ ternary "yes" "no" (eq .Metadata.Region "prod") }}  # Conditional value

# String functions
{{ upper .Metadata.Hostname }}           # HOSTNAME
{{ lower .Metadata.Region }}             # region-1
{{ trim "  spaced  " }}                  # "spaced"
{{ replace .Metadata.Zone "-" "_" }}     # zone_1
{{ quote .Values.Password }}             # "password-value"

# JSON/YAML conversion
{{ .Kubernetes.KubeletConfiguration | toJson }}
{{ .Values.CustomConfig | toYaml | nindent 4 }}
{{ . | toPrettyJson }}

# String manipulation
{{ split "a,b,c" "," }}                  # [a b c]
{{ join (list "a" "b") "," }}            # a,b
{{ regexFind "[0-9]+" "node-123-abc" }}  # 123
{{ regexReplaceAll "\s+" .Input "-" }}  # Replace whitespace with dashes

# Network functions
{{ cidrhost "192.168.1.0/24" 10 }}       # 192.168.1.10
{{ cidrslaac "2001:db8::/64" "00:1A:2B:3C:4D:5E" }}  # SLAAC IPv6 address

# Encoding
{{ b64enc "plain-text" }}                # cGxhaW4tdGV4dA==
{{ b64dec "cGxhaW4tdGV4dA==" }}          # plain-text

# Conditionals
{{ if hasKey .Values "Feature" }}enabled{{ end }}
{{ if hasTag .Metadata.Tags "production" }}prod-config{{ end }}
{{ if contains .Metadata.Zone "gpu" }}gpu-node{{ end }}
```

--------------------------------

### Helm Values for Proxmox Karpenter Provider

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/docs/install.md

Defines the Helm values for deploying the Proxmox Karpenter Provider, specifically configuring the Proxmox cluster connection details. This file is used in conjunction with the Helm chart for installation.

```yaml
config:
  clusters:
    - url: https://cluster-api-1.exmple.com:8006/api2/json
      insecure: false
      token_id: "kubernetes@pve!karpenter"
      token_secret: "secret"
      region: Region-1
```

--------------------------------

### Deploy Karpenter with Custom Instance Types (Bash)

Source: https://context7.com/sergelogvinov/karpenter-provider-proxmox/llms.txt

This bash command deploys or upgrades the Karpenter provider for Proxmox using Helm, specifying a custom instance types configuration file. The `--set-file` flag mounts the JSON file into the pod.

```bash
# Deploy with custom instance types
helm upgrade -i -n kube-system karpenter-provider-proxmox \
  oci://ghcr.io/sergelogvinov/charts/karpenter-provider-proxmox \
  --set extraArgs="{--instance-types-file=/etc/karpenter/instance-types.json}" \
  --set-file extraVolumes[0].configMap.data.instance-types\\.json=instance-types.json
```

--------------------------------

### Configure Proxmox Role and API Token for Karpenter

Source: https://context7.com/sergelogvinov/karpenter-provider-proxmox/llms.txt

Sets up the necessary Proxmox role, user, and API token with specific privileges required for Karpenter to manage VMs. This includes granting permissions for datastore, VM operations, and potentially pool management, along with privilege separation for the API token.

```bash
# Create the Karpenter role with required privileges
pveum role add Karpenter -privs "Datastore.Allocate Datastore.AllocateSpace Datastore.AllocateTemplate Datastore.Audit Mapping.Audit Mapping.Use Sys.Audit Sys.AccessNetwork SDN.Audit SDN.Use VM.Audit VM.Allocate VM.Clone VM.Config.CDROM VM.Config.CPU VM.Config.Memory VM.Config.Disk VM.Config.Network VM.Config.HWType VM.Config.Cloudinit VM.Config.Options VM.PowerMgmt"

# Add pool privileges if using resource pools
pveum role modify Karpenter --append --privs "Pool.Audit Pool.Allocate"

# Create user and assign role
pveum user add kubernetes@pve
pveum aclmod / -user kubernetes@pve -role Karpenter

# Create API token with privilege separation
pveum user token add kubernetes@pve karpenter -privsep 1 --comment "Kubernetes Karpenter"
pveum aclmod / --token 'kubernetes@pve!karpenter' -role Karpenter

```

--------------------------------

### Node QEMU VM Permissions

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/docs/permission.md

This section details the permissions required to audit QEMU virtual machines on a node.

```APIDOC
## GET /nodes/{node_id}/qemu

### Description
Audits QEMU virtual machines running on a specific node.

### Method
GET

### Endpoint
/nodes/%s/qemu

### Parameters
#### Path Parameters
- **node_id** (string) - Required - The ID of the node.

### Response
#### Success Response (200)
- **vm_list** (array) - A list of QEMU virtual machines.

#### Response Example
```json
{
  "vm_list": [
    {
      "vmid": 100,
      "name": "my-vm-1"
    },
    {
      "vmid": 101,
      "name": "my-vm-2"
    }
  ]
}
```
```

--------------------------------

### Deploy Karpenter Provider using Helm

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/examples/talos/README.md

Deploys the Karpenter Proxmox provider using Helm. This command upgrades or installs the Helm chart for the Proxmox provider into the kube-system namespace.

```shell
helm upgrade -i -n kube-system karpenter-proxmox oci://ghcr.io/sergelogvinov/charts/karpenter-proxmox
```

--------------------------------

### Regular Expression String Matching Functions

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/docs/functions.md

These functions utilize regular expressions for pattern matching within strings. `regexFind` returns the first matching substring. `regexFindString` returns a specific captured group from the first match. `regexReplaceAll` replaces all matches with a specified string.

```yaml
{{ regexFind "[a-zA-Z][1-9]" "abcd1234" }} -> d1
{{ regexFindString "^type-([a-z0-9]+)-(.*)$" "type-metal1-asz" 1 }} -> metal1
{{ regexReplaceAll "a(x*)b" "-ab-axxb-" "${1}W" }} -> -W-xxW-
```

--------------------------------

### Generate Talos Machine Configurations

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/examples/talos/README.md

Generates Talos machine configurations for Proxmox. This command assumes you have Talos CLI installed and configured. It outputs configuration files to the specified directory.

```shell
talosctl gen config --output-dir _cfgs --with-docs=false --with-examples=false proxmox https://api.example.com:6443
```

--------------------------------

### YAML Conversion Functions

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/docs/functions.md

These functions convert data structures into YAML format. `toYaml` produces a compact YAML string, while `toPrettyYaml` generates a human-readable, indented YAML string. They are useful for generating YAML-formatted configuration data.

```yaml
# Example usage for toYaml and toPrettyYaml would go here, assuming they operate on a variable or literal.
# For instance:
# {{ toYaml (dict "key" "value") }} -> key: value
# {{ toPrettyYaml (dict "key" "value") }} ->
# key: value
```

--------------------------------

### Create Kubernetes Secret for Proxmox Configuration

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/docs/install.md

Uploads the Proxmox cluster configuration (defined in `config.yaml`) to the Kubernetes cluster as a secret named `karpenter-provider-proxmox` in the `kube-system` namespace. This makes the configuration accessible to the Karpenter provider.

```shell
kubectl -n kube-system create secret generic karpenter-provider-proxmox --from-file=config.yaml
```

--------------------------------

### String Splitting and Joining Functions

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/docs/functions.md

These functions handle the conversion between strings and lists of strings. `split` breaks a string into a list based on a delimiter. `join` concatenates a list of strings into a single string using a specified separator.

```yaml
{{ split "a,b,c" "," }} -> [a b c]
{{ join (list "a" "b" "c") "," }} -> a,b,c
```

--------------------------------

### Node Resource Allocation Configuration

Source: https://context7.com/sergelogvinov/karpenter-provider-proxmox/llms.txt

Configures node resource allocation modes for optimal VM placement and CPU pinning. It shows how to set the allocation mode via environment variables or flags, with 'static' mode enabling CPU pinning and NUMA affinity.

```bash
# Set allocation mode via environment variable or flag
# Options: simple (default), static

# Static mode enables CPU pinning and NUMA affinity (requires root@pam)
helm upgrade -i -n kube-system karpenter-provider-proxmox \
  oci://ghcr.io/sergelogvinov/charts/karpenter-provider-proxmox \
  --set extraArgs="{--node-policy=static}"
```

--------------------------------

### Proxmox Role Creation and Modification

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/docs/install.md

Defines the 'Karpenter' role in Proxmox with essential privileges for VM management and optionally adds privileges for updating VM pool membership. This ensures the Karpenter provider has the necessary permissions to interact with Proxmox.

```shell
pveum role add Karpenter -privs "Datastore.Allocate Datastore.AllocateSpace Datastore.AllocateTemplate Datastore.Audit Mapping.Audit Mapping.Use Sys.Audit Sys.AccessNetwork SDN.Audit SDN.Use VM.Audit VM.Allocate VM.Clone VM.Config.CDROM VM.Config.CPU VM.Config.Memory VM.Config.Disk VM.Config.Network VM.Config.HWType VM.Config.Cloudinit VM.Config.Options VM.PowerMgmt"
pveum role modify Karpenter --append --privs "Pool.Audit Pool.Allocate"
```

--------------------------------

### Meta-data Configuration for Proxmox VMs

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/docs/nodeclass.md

Provides default meta-data for Proxmox VMs, including hostname, instance ID, and provider-specific information. It utilizes Go templating to dynamically populate these fields based on the VM's attributes.

```yaml
hostname: {{ .Hostname }}
local-hostname: {{ .Hostname }}
instance-id: {{ .InstanceID }}
{{- if .InstanceType }}
instance-type: {{ .InstanceType }}
{{- end }}
{{- if .ProviderID }}
provider-id: {{ .ProviderID }}
{{- end }}
region: {{ .Region }}
zone: {{ .Zone }}
availability-zone: {{ .Zone }}

```

--------------------------------

### Proxmox Instance Type Families

Source: https://context7.com/sergelogvinov/karpenter-provider-proxmox/llms.txt

Karpenter for Proxmox provides predefined instance families with varying CPU-to-memory ratios to cater to different workload needs. The naming convention follows '<family>.<vCPU>VCPU-<memory>GB', allowing users to select appropriate instance types.

```text
# Instance family naming convention: <family>.<vCPU>VCPU-<memory>GB
# Available families:
# - c1: Compute-optimized (1:2 ratio) - c1.2VCPU-4GB, c1.4VCPU-8GB, c1.8VCPU-16GB
# - t1: General purpose (1:3 ratio) - t1.2VCPU-6GB, t1.4VCPU-12GB, t1.8VCPU-24GB
# - s1: Standard (1:4 ratio) - s1.2VCPU-8GB, s1.4VCPU-16GB, s1.8VCPU-32GB
# - m1: Memory-optimized (1:8 ratio) - m1.2VCPU-16GB, m1.4VCPU-32GB, m1.8VCPU-64GB

```

--------------------------------

### Proxmox VM IP Configuration (Manual Templates)

Source: https://context7.com/sergelogvinov/karpenter-provider-proxmox/llms.txt

Equivalent Proxmox VM ipconfig0 setting for manual templates, specifying IPv4 and IPv6 addresses and gateways for network configuration.

```conf
ipconfig0: ip=192.168.100.0/24,gw=192.168.100.1,ip6=fd00:100::/64,gw6=fd00:100::1
```

--------------------------------

### Configure Default Proxmox Virtual Machine Template Spec

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/charts/karpenter-provider-proxmox/README.md

Defines the raw specification for the default Proxmox Virtual Machine Template. This includes the name of the underlying Proxmox template to be used for creating new VMs. References external documentation for detailed options.

```json
{
  "templateName": "talos"
}
```

--------------------------------

### Update Helm Chart and Documentation

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/docs/release.md

Automates the update of the Helm chart version and project documentation. It involves checking out a specific branch, exporting release tags, executing a script to bump chart versions, and generating documentation. Finally, it stages all changes and amends the previous commit.

```shell
git branch -D release-please--branches--main
git checkout release-please--branches--main
export `jq -r '"TAG=v"+.[]' .github/release-please-manifest.json`

sh hack/bump-chart-version.sh karpenter-provider-proxmox false false true
make helm-unit docs

git add .
git commit -s --amend
```

--------------------------------

### String Indentation Functions

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/docs/functions.md

The `indent` and `nindent` functions are used to format strings by adding leading spaces to each line. `indent` adds spaces directly, while `nindent` also prepends a newline character before the indentation. These are useful for structuring multi-line output.

```yaml
{{ indent 4 "hello\nworld" }} -> "    hello\n    world"
{{ nindent 4 "hello\nworld" }} -> "\n    hello\n    world"
```

--------------------------------

### Configure Deployment Update Strategy

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/charts/karpenter-provider-proxmox/README.md

Defines the update strategy for the controller deployment. This includes settings like maxUnavailable pods during a rolling update and the overall update type. It references Kubernetes Deployment documentation for detailed options.

```json
{
  "rollingUpdate": {
    "maxUnavailable": 1
  },
  "type": "RollingUpdate"
}
```

--------------------------------

### Configure Default Proxmox Node Class Spec

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/charts/karpenter-provider-proxmox/README.md

Defines the raw specification for the default Proxmox Node Class. This includes details like the boot device size, the instance template reference, security group configurations, and tags. References external documentation for detailed options.

```json
{
  "bootDevice": {
    "size": "30Gi"
  },
  "instanceTemplateRef": {
    "kind": "ProxmoxUnmanagedTemplate",
    "name": "default"
  },
  "securityGroups": [
    {
      "interface": "net0",
      "name": "kubernetes"
    }
  ],
  "tags": [
    "karpenter"
  ]
}
```

--------------------------------

### String Trimming Functions

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/docs/functions.md

The `trim`, `trimSuffix`, and `trimPrefix` functions are used to remove whitespace or specific characters from the beginning and end of strings. `trim` removes leading/trailing whitespace, `trimSuffix` removes a specified suffix, and `trimPrefix` removes a specified prefix.

```yaml
{{ trim "  hello  " }} -> hello
{{ trimSuffix "hello" "lo" }} -> hel
{{ trimPrefix "hello" "he" }} -> llo
```

--------------------------------

### Define VM Template Resource (ProxmoxTemplate)

Source: https://context7.com/sergelogvinov/karpenter-provider-proxmox/llms.txt

This ProxmoxTemplate resource defines the specifications for a VM image to be used by Karpenter, including the source image URL, storage, machine type, and network configuration. It allows for custom VM templates tailored for Kubernetes nodes.

```yaml
apiVersion: karpenter.proxmox.sinextra.dev/v1alpha1
kind: ProxmoxTemplate
metadata:
  name: ubuntu-k8s
spec:
  sourceImage:
    url: https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img
    imageName: ubuntu-24.04-k8s.qcow2
  storageIDs:
    - local-lvm
  machine: q35
  agent:
    enabled: true
  cpu:
    type: host
  network:
    - name: net0
      bridge: vmbr0
      model: virtio
      firewall: true
  tags:
    - kubernetes
    - template
```

--------------------------------

### Configure Default Proxmox Virtual Machine Template Kind

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/charts/karpenter-provider-proxmox/README.md

Specifies the kind of the default Proxmox Virtual Machine Template. It can be either 'ProxmoxUnmanagedTemplate' for templates not managed by Proxmox VE's template feature, or 'ProxmoxTemplate' for standard Proxmox templates.

```json
"ProxmoxUnmanagedTemplate"
```

--------------------------------

### Custom Instance Types Configuration (JSON)

Source: https://context7.com/sergelogvinov/karpenter-provider-proxmox/llms.txt

This JSON configuration defines custom instance types for Karpenter, specifying their capacity (CPU, memory, storage, GPUs) and overhead (reserved resources for Kubernetes and system).

```json
[
  {
    "name": "gpu.4VCPU-32GB",
    "capacity": {
      "cpu": "4",
      "ephemeral-storage": "100Gi",
      "memory": "32Gi",
      "pods": "64",
      "nvidia.com/gpu": "1"
    },
    "overhead": {
      "KubeReserved": {
        "cpu": "100m",
        "memory": "1Gi"
      },
      "SystemReserved": {
        "cpu": "50m",
        "memory": "512Mi"
      },
      "EvictionThreshold": {
        "memory": "500Mi"
      }
    }
  },
  {
    "name": "highmem.8VCPU-128GB",
    "capacity": {
      "cpu": "8",
      "ephemeral-storage": "200Gi",
      "memory": "128Gi",
      "pods": "110",
      "hugepages-1Gi": "64Gi"
    },
    "overhead": {
      "KubeReserved": {
        "cpu": "200m",
        "memory": "2Gi"
      },
      "SystemReserved": {
        "cpu": "100m",
        "memory": "1Gi"
      },
      "EvictionThreshold": {
        "memory": "1Gi"
      }
    }
  }
]
```

--------------------------------

### Define Cloud-Init User Values for Templates (Kubernetes Secret)

Source: https://context7.com/sergelogvinov/karpenter-provider-proxmox/llms.txt

This Kubernetes Secret defines user-specific values for cloud-init, including SSH keys and API server details, which are used to bootstrap nodes. It is a standard Kubernetes resource used by the Proxmox provider.

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: cloud-init-values
  namespace: kube-system
stringData:
  SSHKeys: "ssh-rsa AAAAB3..."
  APIServer: "10.0.0.10"
  CAHash: "abcdef123456..."
```

--------------------------------

### User-data Configuration for Proxmox VMs

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/docs/nodeclass.md

Defines the user-data for Proxmox VMs, including hostname, package updates, service enablement, user creation, and file writes. It uses Go templating to dynamically inject values like SSH keys and Karpenter configuration.

```yaml
#cloud-config
hostname: {{ .Metadata.Hostname }}
manage_etc_hosts: true
package_update: true
packages:
  - qemu-guest-agent
runcmd:
  - [ systemctl, enable, --now, qemu-guest-agent.service ]

users:
  - name: karpenter
    gecos: Kubernetes User
    sudo: ALL=(ALL) NOPASSWD:ALL
    groups: [users]
    shell: /bin/bash
    {{- with get .Values "SSHAuthorizedKeys" }}
    ssh_authorized_keys:
      {{- toYaml (split . ",") | nindent 6 }}
    {{- end }}

write_files:
  - path: /etc/karpenter.yaml
    content: |
      {{- . | toYamlPretty | nindent 6  }}
    owner: root:root

```

--------------------------------

### Configure Default Proxmox Node Class Creation

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/charts/karpenter-provider-proxmox/README.md

Controls the creation of a default Proxmox Node Class named 'default'. When enabled, this allows Karpenter to provision nodes using the specified Proxmox configuration. Defaults to disabled.

```json
false
```

--------------------------------

### Proxmox Virtual Machine Template Configuration (YAML)

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/docs/nodetemplateclass.md

This YAML configuration outlines the parameters for a Proxmox Virtual Machine template. It includes settings for CPU, memory, disk, network, and cloud-init configuration, essential for creating a bootable VM image.

```yaml
acpi: 1
agent: enabled=0,fstrim_cloned_disks=0,type=virtio
arch: x86_64
bios: seabios
boot: order=scsi0
cicustom: user=local:snippets/common.yaml
cores: 1
cpu: cputype=host
cpuunits: 1024
ide2: local:1002/vm-1002-cloudinit.qcow2,media=cdrom
ipconfig0: ip=dhcp,ip6=auto
keyboard: en-us
machine: q35
memory: 512
meta: creation-qemu=9.2.0,ctime=1754811620
name: talos
nameserver: 1.1.1.1 2001:4860:4860::8888
net0: virtio=BC:24:11:7D:F3:15,bridge=vmbr0,firewall=1,mtu=1500
numa: 1
onboot: 0
ostype: l26
protection: 0
scsi0: local:1002/vm-1002-disk-0.raw,aio=io_uring,backup=1,cache=none,discard=ignore,iothread=1,replicate=1,size=3G
scsihw: virtio-scsi-single
serial0: socket
smbios1: uuid=e536baad-cf78-4543-9034-60295eed2b22
sockets: 1
tablet: 0
template: 1
vga: memory=16,type=serial0
vmgenid: 0f832f6f-eb15-4e94-a44f-03698adee947
```

--------------------------------

### Base64 Encoding and Decoding Functions

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/docs/functions.md

The `b64enc` and `b64dec` functions provide utilities for Base64 encoding and decoding strings. `b64enc` converts a string into its Base64 representation, and `b64dec` decodes a Base64 string back to its original form.

```yaml
{{ b64enc "hello" }} -> aGVsbG8=
{{ b64dec "aGVsbG8=" }} -> hello
```

--------------------------------

### Apply Karpenter Configuration using kubectl

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/examples/talos/README.md

Applies Karpenter configuration files to the Kubernetes cluster using kubectl. This command is used to deploy the defined NodeClass and NodePool resources.

```shell
kubectl apply -f examples/talos/karpenter-unmanaged.yaml
```

--------------------------------

### IP Address Management (IPAM) Configuration

Source: https://context7.com/sergelogvinov/karpenter-provider-proxmox/llms.txt

Configures automatic IP address allocation for VMs using simple IPAM mode within a ProxmoxTemplate. It defines IPv4 and IPv6 subnet pools and gateway information.

```yaml
# In ProxmoxTemplate or ProxmoxUnmanagedTemplate network configuration
apiVersion: karpenter.proxmox.sinextra.dev/v1alpha1
kind: ProxmoxTemplate
metadata:
  name: with-ipam
spec:
  sourceImage:
    url: https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img
    imageName: ubuntu-24.04.qcow2
  storageIDs:
    - local
  network:
    - name: net0
      model: virtio
      bridge: vmbr0
      firewall: true
      # IPAM: Define subnet pool, Karpenter allocates from available IPs
      address4: 192.168.100.0/24    # IPv4 pool (not a specific IP)
      gateway4: 192.168.100.1
      address6: fd00:100::/64       # IPv6 pool with SLAAC
      gateway6: fd00:100::1
      dnsServers:
        - 1.1.1.1
        - 8.8.8.8
```

--------------------------------

### Deploy Test Workload to Scale Cluster

Source: https://github.com/sergelogvinov/karpenter-provider-proxmox/blob/main/examples/talos/README.md

Deploys a test statefulset workload to the Kubernetes cluster. This action is intended to trigger Karpenter to provision new worker nodes based on the defined NodePool and NodeClass configurations.

```shell
kubectl apply -f examples/workloads/test-statefulset.yaml
```