Use Enterprise-Only OCI Features

This topic describes how to use the enterprise-only OCI features of Smart Karpenter.

Increase Pod Capacity with multiVnic

The multiVnic feature increases the number of secondary Virtual Network Interface Cards (VNICs) assigned to each node when using VCN-Native Pod Networking. Each secondary VNIC provides 31 additional pod IP addresses, enabling nodes to support a higher pod density, up to the Kubernetes default maximum of 110 pods per node.

This feature is applicable only when:

• The cluster is configured to use VCN-Native Pod Networking.
• The OciNodeClass specifies a pod subnet for VCN-Native Pod Networking.

Enable multiVnic in the Helm Values File

Set oci.controller.multiVnic to true in your Helm values file as shown in the YAML snippet below:

oci:
  controller:
    multiVnic: true

This sets the ENABLE_MULTI_VNIC environment variable for the Smart Karpenter controller. The default is false.

Secondary VNICs and Maximum Pods

The number of secondary VNICs available for pod networking is calculated based on the OCPU (vCPU) count of the node, using the following rules:

• Formula: numSecondaryVnics = OCPUs - 1, with a minimum of 1 and a maximum of 4
• Pods per VNIC: 31 (OKE VCN-Native default)
• Maximum pods per node: min(numSecondaryVnics x 31, 110) (capped at Kubernetes default)

Reference Table

note

The number of secondary VNICs is capped at 4. The maximum pods per node is capped at 110.

vCPUs (OCPUs)	Secondary VNICs for Pods	Maximum Pods per Node
2	1	31
3	2	62
4	3	93
5	4	110
6+	4	110

Reference OKE Worker Node Images with Display Names

Smart Karpenter allows you to reference Oracle Kubernetes Engine (OKE) worker node images using a display name rather than providing the full OCI image OCID. When you specify the image display name in spec.imageName, Smart Karpenter automatically resolves it to the corresponding OCID through Oracle Cloud Infrastructure (OCI) APIs. This simplifies configuration management and ensures that the correct image identifier is applied during node provisioning.

OCI Image Name Requirements

The OCI Image name must meet the requirements described in the following table.

Requirement	Description
Correct and exact	The name must match exactly the display name of an available OCI image in your compartment (or Oracle's OKE images compartment). Typos or partial names will cause resolution to fail.
x86 architecture	The image must be an x86 (amd64) image. ARM (aarch64) images are not supported and will be rejected.
OKE node image	The image must be an OKE Kubernetes worker node image. The display name must contain "OKE". Non-OKE images are rejected.

You can copy the exact image display name from Oracle's published OKE worker node image catalogs:

• OKE Worker Node Oracle Linux 8.x images
• OKE Worker Node Oracle Linux 7.x images

Example OCI Display Name for Worker Node Image

apiVersion: karpenter.multicloud.sh/v1alpha1
kind: OciNodeClass
metadata:
  name: default
spec:
  imageName: "Oracle-Linux-8.8-OKE-1.28.2-2024.01.16-0"
  # Other configurations...

Understanding the Webhook Behavior for Image Name Resolution

When the OciNodeClass admission webhook is enabled (enabled by default), Kubernetes invokes the Smart Karpenter webhook each time an OciNodeClass resource containing spec.imageName is created or updated.

Validation

During validation, the webhook queries the Oracle Cloud Infrastructure (OCI) API to ensure that the specified image meets all required criteria. The webhook verifies that:

• The image exists and its display name matches exactly.
• The image is an Oracle Kubernetes Engine (OKE) worker node image, indicated by the presence of "OKE" in the display name.
• The image is not an ARM-based (aarch64) image.

If any validation check fails, the create or update request is denied with a clear and actionable error message.

Mutation

If validation is successful, the mutating webhook resolves the provided imageName to the corresponding image OCID and automatically populates spec.imageOCID in the persisted OciNodeClass resource. This ensures that the cluster consistently records the exact OCID required for accurate drift detection and node provisioning.

Resolution Workflow

The webhook performs the following resolution flow:

• imageName → OCI API lookup → imageOCID (stored in spec) and population of status.resolvedImageOCID and status.resolvedImageName for operational visibility.

Ensurer Smart Karpenter Service Accessibility

For the webhook to work, the Kubernetes control plane must be able to call the Smart Karpenter service on the webhook port (9443). Ensure that:

• The Smart Karpenter controller pod is running and reachable from the API server.
• Network policies, firewalls, or security groups do not block traffic from the control plane to the Smart Karpenter service.
• When running on OKE, the default setup typically satisfies this. For custom or air-gapped environments, verify connectivity.

If the control plane cannot reach the webhook, admission requests for OciNodeClass will fail (for example, timeout), and create/update operations may be rejected or delayed.

Disable the OciNodeClass Webhook

To disable the OciNodeClass webhook, add the following properties in the values.yaml file:

oci:
  controller:
    webhook:
      enabled: false

Understanding the Behavior of the Disabled OciNodeClass Webhook

Aspect	Behavior
Create/Update	No validation occurs at apply time. Invalid imageName values are accepted without error.
Resolution	Resolution occurs during provisioning when Smart Karpenter attempts to launch a new node. The cloud provider invokes ResolveImageNameToOCID and ValidateOKEImage.
Invalid imageName	The OciNodeClass is marked with Ready=False and the InvalidImageName condition. Smart Karpenter cannot provision new nodes, and no immediate feedback is provided when applying the YAML.
Recommendation	Keep the webhook enabled for immediate validation and clear error messages. Disable only when necessary (for example, air-gapped clusters or restricted network environments).