Uso de Karpenter Provider para OCI (KPO)

Requisitos

Antes de instalar KPO, confirme que la configuración de cluster y red admite nodos de trabajador aprovisionados por Karpenter. Tenga en cuenta que es posible que la instalación se realice correctamente, pero que el aprovisionamiento posterior de nodos de trabajador falle debido a que faltan requisitos.

• Versión de Kubernetes que se ejecuta en el cluster: utilice una versión de KPO compatible con la versión de Kubernetes que se ejecuta en el cluster, como se muestra en la tabla:

  Versión de Kubernetes	Versión de KPO
  Kubernetes version 1.31	v1.0.0 or later
  Versión de Kubernetes 1.32	v1.0.0 o posterior
  Versión de Kubernetes 1.33	v1.0.0 o posterior
  Versión de Kubernetes 1.34	v1.0.0 o posterior
  Versión de Kubernetes 1.35	v1.1.0 o posterior

• Capacidad de nodo de trabajador: ejecute al menos un pool de nodos gestionado existente o nodos de trabajador autogestionados para que KPO se pueda ejecutar en el plano de datos.

• Complemento de cluster de CNI de plugin de red de pod nativo de VCN de OCI (también conocido como complemento de CNI nativo de IP de VCN de OCI): si el cluster está utilizando el complemento de CNI nativo de IP de VCN de OCI, el complemento debe ser de la versión 3.0.0 o posterior. Recomendamos encarecidamente el uso de la versión 3.2.0 o posterior. Si el cluster utiliza una versión del complemento anterior a la versión 3.2.0, las VNIC secundarias admiten un máximo de 16 direcciones IP (ipCount no debe superar las 16).

• Cliente de Helm instalado: instale el cliente de Helm en el entorno donde desea ejecutar los comandos de Helm.

Agregar el repositorio de Helm de KPO

Para agregar el repositorio de KPO Helm, introduzca:

helm repo add karpenter-provider-oci https://oracle.github.io/karpenter-provider-oci/charts

Descargue el último índice para el repositorio karpenter-provider-oci introduciendo:

helm repo update karpenter-provider-oci

Para mostrar las versiones de historia clínica disponibles, escriba:

helm search repo karpenter-provider-oci/karpenter --versions

Revisión y configuración de valores de Helm

Revise los valores de configuración de Helm (a menudo simplemente denominados valores de Helm) para la versión de gráfico que sea compatible con la versión de Kubernetes que se ejecuta en el cluster introduciendo:

helm show values karpenter-provider-oci/karpenter --version <chart-version>

En la siguiente tabla se muestran los valores de Helm más importantes:

repairPolicies:
  - conditionType: Ready
    conditionStatus: "False"
    tolerationDuration: 600000000000

Debe definir los valores de Helm necesarios para permitir que KPO resuelva los recursos de OCI y los nodos de trabajador de inicialización de datos. También puede definir los valores opcionales de Helm para que coincidan con el modelo de red y la estrategia de nodo de trabajador.

Los valores de Helm se definen en un archivo de configuración (denominado archivo de valores de Helm).

Instalar KPO

Despliegue el controlador de KPO en el plano de datos de OKE. Instale KPO en un espacio de nombres que pueda gestionar y supervisar con las herramientas de operaciones del cluster.

1. Seleccione el espacio de nombres en el que desea desplegar KPO.

2. Cree un archivo de valores de Helm en formato YAML que incluya los valores necesarios y los valores opcionales que desee sustituir. Por ejemplo:

   settings:
     clusterCompartmentId: "<cluster-compartment-id>"
     vcnCompartmentId: "<cluster-vcn-compartment-id>"
     ociVcnIpNative: false
     apiserverEndpoint: 10.0.0.14
   
   # Optional: override image location/tag (example for OCIR)
   image:
     registry: "<registry>"
     repositoryName: "<repository-name>"
     tag: "<version>"

3. Instale el gráfico introduciendo:

   helm install karpenter karpenter-provider-oci/karpenter \
     --version <chart-version> \
     --values <path-to-helm-values-file> \
     --namespace <karpenter-namespace> \
     --create-namespace

   Si no especifica un espacio de nombres en el que desplegar KPO, se utiliza el espacio de nombres default.

Para obtener más información sobre la instalación de KPO, consulte la documentación de instalación de KPO en Github.

Comprobación de la Instalación

Una vez instalado el KPO, confirme que el controlador de KPO se inicie correctamente antes de crear los recursos OCINodeClass y NodePool.

1. Confirme que los pods se están ejecutando introduciendo:

   kubectl get pods --namespace <karpenter-namespace>

2. Si los pods no se están ejecutando, inspeccione los eventos y logs de pod introduciendo:

   kubectl describe pod --namespace <karpenter-namespace> <pod-name>

   kubectl logs --namespace <karpenter-namespace> <pod-name>

Patrón de Política de Identidad de Carga de Trabajo

Utilice el siguiente patrón para especificar las condiciones de identidad de la carga de trabajo en las políticas de IAM, de modo que los permisos de OCI solo se apliquen a la carga de trabajo de KPO del cluster:

Allow any-user to <verb> <resource> in <location> where all {
  request.principal.type = 'workload',
  request.principal.namespace = '<namespace-name>',
  request.principal.service_account = '<service-account-name>',
  request.principal.cluster_id = '<cluster-ocid>'
}

Políticas básicas necesarias para la operación de KPO

Otorgue permisos a KPO para gestionar los recursos informáticos, de almacenamiento y de red necesarios para los nodos de trabajador mediante la inclusión de sentencias de política similares a las siguientes en una política de IAM (mediante el patrón que se muestra en Patrón de política de identidad de carga de trabajo):

Allow any-user to manage instance-family in compartment <compartment-name> where all { ... }
Allow any-user to manage volumes in compartment <compartment-name> where all { ... }
Allow any-user to manage volume-attachments in compartment <compartment-name> where all { ... }
Allow any-user to manage virtual-network-family in compartment <compartment-name> where all { ... }
Allow any-user to inspect compartments in compartment <compartment-name> where all { ... }

Tenga en cuenta que si activa las funciones opcionales en OCINodeClass, también tiene que definir políticas adicionales (consulte Políticas opcionales (específicas de funciones)).

Políticas opcionales (específicas de funciones)

Además de las sentencias de política que se muestran en Políticas básicas necesarias para la operación de KPO, si activa las funciones opcionales en OCINodeClass, también tiene que definir políticas adicionales.

Agregue solo las políticas necesarias para las funciones que active en OCINodeClass.

Especificación de Clase de OCINode

Configuración de volumen

Utilice volumeConfig para controlar cómo KPO crea el volumen de inicio para cada nodo de trabajador.

Configuración de volumen de inicio

Utilice bootVolumeConfig para seleccionar la imagen y configurar el tamaño y el rendimiento del volumen de inicio.

Configuración de imagen

Utilice imageConfig para seleccionar la imagen de OKE para los nodos de trabajador. Seleccione una imagen por OCID o por filtro. Para obtener más información sobre las imágenes de OKE, consulte Imágenes de OKE.

Configuración de KmsKey

Utilice kmsKeyConfig para cifrar los volúmenes de inicio con su propia clave.

Término del selector de imágenes

Utilice ImageSelectorTerm para seleccionar una imagen por sistema operativo, versión, compartimento y etiquetas.

Configuración de Red

Utilice networkConfig para colocar las VNIC del nodo de trabajador en las subredes correctas y conectar los NSG cuando sea necesario.

Configuración de VNIC principal

Utilice primaryVnicConfig para definir la subred principal y los NSG opcionales para el nodo de trabajador.

Configuración de subred

Seleccione una subred por OCID o por selector.

NetworkSecurityGroupConfigs

Seleccione un NSG por OCID o por selector.

Ipv6DirecciónIpv6SubredCidrPairDetails

Utilice este campo cuando necesite controlar la asignación de CIDR de la subred IPv6.

OciResourceSelectorTerm

Utilice campos de selector cuando desee seleccionar una subred o NSG por nombre o por etiquetas, en lugar de por OCID.

Configuración de VNIC secundaria

Utilice secondaryVnicConfigs cuando el cluster utilice el complemento CNI nativo de IP de la VCN de OCI y necesite una VNIC secundaria para las direcciones IP de pod. Tiene todos los campos PrimaryVnicConfig y algunos campos adicionales.

Configuración de unidades

Utilice shapeConfigs para definir el tamaño de las unidades flexibles y las configuraciones ampliables.

Configuración de CapacityReservation

Utilice capacityReservationConfigs cuando desee que los nodos de trabajador se ejecuten en la capacidad reservada en OCI.

ClusterPlacementGroupConfigs

Utilice clusterPlacementGroupConfigs cuando necesite que los nodos de trabajador se coloquen juntos para redes de baja latencia.

Configuración de ComputeCluster

Utilice computeClusterConfig cuando desee que los nodos de trabajador se ejecuten en un cluster de recursos informáticos.

KubeletConfig

Utilice kubeletConfig para sustituir la configuración de kubelet en los nodos de trabajador aprovisionados por Karpenter. Karpenter Provider for OCI (KPO) aplica esta configuración durante el aprovisionamiento de nodos.

IniciarOpciones

Utilice launchOptions para definir las opciones de inicio de instancia.

Estado de Clase de OCINode

Utilice los campos status para solucionar problemas de validación y configuración resuelta.

Etiquetas de programación

Utilice etiquetas de nodo en NodePool.spec.template.spec.requirements y en reglas de programación de carga de trabajo (por ejemplo, selectores de nodos y afinidad de nodos). Utiliza etiquetas estándar de Kubernetes y etiquetas específicas de OCI. KPO agrega etiquetas específicas de OCI a los nodos que aprovisiona.

shapename.<X>o.<Y>g.<burstableRatio>b

VM.Standard.E5.Flex.2o.32g.1_1b

Tolerancias y contaminantes necesarios

Utilice contaminantes y tolerancias para controlar dónde se ejecutan las cargas de trabajo. Configure los contaminantes en NodePool para que Karpenter ofrezca la capacidad correspondiente y, a continuación, configure las tolerancias en las cargas de trabajo que se deben ejecutar en esos nodos de trabajador.

Tenga en cuenta los siguientes escenarios especiales:

• Nodos de trabajador preferentes (al contado):

  Los nodos de trabajador iniciados como capacidad puntual utilizan el mantenimiento oci.oraclecloud.com/oke-is-preemptible.

  Para utilizar la capacidad puntual:

  1. Agregue la mancha a NodePool para que Karpenter ofrezca formas puntuales.

  2. Agregue la tolerancia correspondiente a las cargas de trabajo que se deben ejecutar en nodos preferentes.

  Ejemplo de mantenimiento de NodePool:

  template:
    spec:
      taints:
        - effect: NoSchedule
          key: oci.oraclecloud.com/oke-is-preemptible
          value: present

  Si NodePool no incluye el tinte oci.oraclecloud.com/oke-is-preemptible, Karpenter no ofrece formas preferentes.

• Nodos de trabajo de GPU:

  Los nodos de trabajador iniciados con unidades de GPU utilizan contaminantes específicos del proveedor:

  • Unidades de GPU de NVIDIA: nvidia.com/gpu

  • Unidades de GPU AMD: amd.com/gpu

  Para utilizar unidades de GPU:

  1. Agregue la pintura adecuada a NodePool para que Karpenter ofrezca formas de GPU.

  2. Agregue la tolerancia correspondiente a las cargas de trabajo de GPU.

  Ejemplo de mantenimiento de NodePool (NVIDIA):

  template:
    spec:
      taints:
        - effect: NoSchedule
          key: nvidia.com/gpu
          value: present

  Si el NodePool no incluye la pintura adecuada, Karpenter no ofrece las formas correspondientes.

Ejemplo 1: Unidades flexibles con un OCID de imagen de OKE explícito

Utilice este ejemplo cuando desee una NodePool que permita unidades flexibles específicas y desee una OCINodeClass que defina el tamaño de esas unidades flexibles y seleccione una imagen de OKE por OCID.

---
apiVersion: karpenter.sh/v1
kind: NodePool
metadata:
  name: my-nodepool
spec:
  template:
    spec:
      expireAfter: Never
      nodeClassRef:
        group: oci.oraclecloud.com
        kind: OCINodeClass
        name: my-ocinodeclass
      requirements:
        - key: karpenter.sh/capacity-type
          operator: In
          values:
            - on-demand
        - key: oci.oraclecloud.com/instance-shape #expand this list as needed
          operator: In
          values:
            - VM.Standard.E3.Flex
            - VM.Standard.E4.Flex
            - VM.Standard.E5.Flex
      terminationGracePeriod: 120m
  disruption:
    budgets:
      - nodes: 5%
    consolidateAfter: 60m
    consolidationPolicy: WhenEmpty
  limits:
    cpu: 64
    memory: 256Gi 
---
apiVersion: oci.oraclecloud.com/v1beta1
kind: OCINodeClass
metadata:
  name: my-ocinodeclass
spec:
  shapeConfigs:
    - ocpus: 2  
      memoryInGbs: 8
    - ocpus: 4
      memoryInGbs: 16
  volumeConfig:
    bootVolumeConfig:
      imageConfig:
        imageType: OKEImage
        imageId: <OKE-Image-OCID> 
  networkConfig:
    primaryVnicConfig:
      subnetConfig:
        subnetId: <Subnet-OCID> 

Ejemplo 2: Selección de filtro de imagen con sustitución de deriva

Utilice este ejemplo cuando desee que KPO utilice un filtro para seleccionar una imagen automáticamente y desee que Karpenter sustituya los nodos de trabajador cuando se desvíen de la imagen seleccionada.

La imagen seleccionada depende de la versión de Kubernetes del cluster y de las imágenes de OKE disponibles. Cuando se actualiza el plano de control de cluster o se liberan nuevas imágenes de OKE, también cambiará la imagen de nodo de trabajador deseada. Los nodos lanzados con una imagen obsoleta se consideran "desplazados". Para minimizar la interrupción inesperada durante dichos eventos, le recomendamos que configure un presupuesto de interrupción adecuado en el pool de nodos de Karpenter, especificando los motivos, el porcentaje de interrupción y el programa (para obtener más información, consulte Disruption en la documentación de Karpenter).

---
apiVersion: karpenter.sh/v1
kind: NodePool
metadata:
  name: my-nodepool
spec:
  template:
    spec:
      expireAfter: Never
      nodeClassRef:
        group: oci.oraclecloud.com
        kind: OCINodeClass
        name: my-ocinodeclass
      requirements:
        - key: karpenter.sh/capacity-type
          operator: In
          values:
            - on-demand
        - key: oci.oraclecloud.com/instance-shape #expand this list as needed
          operator: In
          values:
            - VM.Standard.E3.Flex
            - VM.Standard.E4.Flex
            - VM.Standard.E5.Flex
      terminationGracePeriod: 120m
  disruption:
    budgets:
      - nodes: 5%
        reasons: 
          - Drifted
        schedule: "@daily" #customize schedule for your own needs, following https://karpenter.sh/docs/concepts/disruption/#schedule 
        duration: 10m
    consolidateAfter: 60m
    consolidationPolicy: WhenEmpty
  limits:
    cpu: 64
    memory: 256Gi 
---
apiVersion: oci.oraclecloud.com/v1beta1
kind: OCINodeClass
metadata:
  name: my-ocinodeclass
spec:
  shapeConfigs:
    - ocpus: 2  
      memoryInGbs: 8
    - ocpus: 4
      memoryInGbs: 16
  volumeConfig:
    bootVolumeConfig:
      imageConfig:
        imageType: OKEImage
        imageFilter: 
          osFilter: "Oracle Linux"
          osVersionFilter: "8"
  networkConfig:
    primaryVnicConfig:
      subnetConfig:
        subnetId: <Subnet-OCID> 

Ejemplo 3: VNIC secundaria para CNI nativo de IP de la VCN de OCI

Utilice este ejemplo cuando el cluster utilice el complemento CNI nativo de IP de la VCN de OCI y los pods necesiten direcciones IP de una subred de VNIC secundaria. Configure secondaryVnicConfigs para asociar una VNIC secundaria y asignar capacidad de IP de pod.

---
apiVersion: oci.oraclecloud.com/v1beta1
kind: OCINodeClass
metadata:
  name: my-ocinodeclass
spec:
  shapeConfigs:
    - ocpus: 2  
      memoryInGbs: 8
    - ocpus: 4
      memoryInGbs: 16
  volumeConfig:
    bootVolumeConfig:
      imageConfig:
        imageType: OKEImage
        imageFilter: 
          osFilter: "Oracle Linux"
          osVersionFilter: "8"  
  networkConfig:
    primaryVnicConfig:
      subnetConfig:
        subnetId: <Subnet-OCID> 
    secondaryVnicConfigs:
      - subnetConfig:
          subnetId: <Subnet-OCID>  #pod subnet
        ipCount: 16

Casos de uso adicionales

Utilice la siguiente tabla para asignar funciones comunes de OCI a los requisitos de NodePool o a los campos OCINodeClass.

requirements:
  - key: karpenter.sh/capacity-type
    operator: In
    values: ["spot"]

capacityReservationConfigs:
  - capacityReservationId: "<capacity-reservation-ocid>"

shapeConfigs:
  - ocpus: 2
    memoryInGbs: 16
    baselineOcpuUtilization: BASELINE_1_2

clusterPlacementGroupConfigs:
  - clusterPlacementGroupId: "<cluster-placement-group-ocid>"

computeClusterConfig:
  computeClusterId: "<compute-cluster-ocid>"

spec:
  replicas: 3

spec:
  requirements:
  - key: karpenter.sh/nodepool
    operator: In
    values:
    - general-purpose
  priceAdjustment: "-15%"
  weight: 100

Identificar nodos de trabajador gestionados por Karpenter

Karpenter aplica la etiqueta karpenter.sh/nodepool a los nodos que crea. Para mostrar los nodos creados por Karpenter y el recurso NodePool al que pertenece cada nodo, introduzca:

kubectl get nodes -L karpenter.sh/nodepool

Para averiguar si Karpenter está creando recursos NodeClaim o si los recursos NodeClaim están bloqueados por algún motivo (por ejemplo, si no se inicia, si no se registra o si se espera la capacidad), introduzca:

kubectl get nodeclaims

kubectl describe nodeclaim <nodeclaim-name>

Identificar las instancias de OCI (y los recursos relacionados) creadas para los nodos de Karpenter

Utilice herramientas de búsqueda de OCI (como Resource Explorer) y las siguientes etiquetas de formato libre de OCI para buscar instancias y recursos relacionados que KPO ha creado:

• karpenterNodepool

• orcl-containerengine/cluster-id (cuando proceda)

Para obtener más información sobre la localización de recursos de OCI, consulte Consulta de recursos.

Limpiar recursos

Antes de suprimir un cluster, elimine la capacidad gestionada por Karpenter para que las instancias no permanezcan en ejecución después de suprimir el cluster.

1. Suprima los recursos NodePool de Karpenter que crean capacidad mediante kubectl delete y el nombre NodePool de la siguiente manera:

   1. Enumere los recursos NodePool introduciendo:

      kubectl get nodepools

   2. Suprima un recurso NodePool introduciendo:

      kubectl delete nodepool <nodepool-name>

   3. (Opcional) Confirme que el recurso NodePool se ha suprimido introduciendo:

      kubectl get nodepools

2. Confirme que se han eliminado los recursos y nodos NodeClaim.

   1. Observe los recursos NodeClaim hasta que se supriman introduciendo:

      kubectl get nodeclaims --watch

   2. Observe los nodos creados para los pools de nodos de Karpenter hasta que se eliminan:

      kubectl get nodes -l karpenter.sh/nodepool --watch

   3. Si NodeClaim no termina, compruebe su estado, condiciones y eventos introduciendo:

      kubectl describe nodeclaim <nodeclaim-name>

3. Utilice la consola, la CLI o el SDK de OCI para confirmar que se han suprimido las instancias de OCI y los recursos asociados.

   1. Localice las instancias que KPO creó con la etiqueta de formato libre karpenterNodepool (y la etiqueta orcl-containerengine/cluster-id, cuando corresponda).
   2. Confirme que no hay tales instancias presentes o que se encuentran en un estado terminado y, a continuación, desaparecen.
   3. Confirme que no quedan asociaciones de VNIC para la instancia y que las VNIC que se crearon para la instancia ya no existen.
   4. Confirme que no quedan asociaciones de volumen para la instancia y que el volumen de inicio creado para la instancia se suprime (o se termina y, a continuación, se elimina).

   Si alguno de los recursos permanece después de terminar la instancia, trátelos como posibles recursos huérfanos e investigue si:

   • el controlador de KPO se está ejecutando y tiene permisos de IAM para limpiar los recursos
   • hay finalizadores de supresión o errores en los logs del controlador de KPO

Qué puede solucionar y dónde buscar

Cuando una carga de trabajo no se puede programar o un nodo de trabajador no se une al cluster, compruebe los recursos y los archivos log y las métricas, y aumente el registro, de la siguiente manera:

• Utilice kubectl para comprobar los recursos de Kubernetes (consulte Comprobación de recursos de Kubernetes).

• Utilice la consola, la CLI o el SDK de OCI para confirmar que KPO ha creado las instancias, las VNIC, los NSG y los volúmenes de inicio esperados para los nodos de trabajador.

• Use kubectl para comprobar los logs del controlador de KPO (consulte Check KPO controller logs).

• Aumentar el registro (consulte Activación del registro de depuración).

Comprobar recursos de Kubernetes

Utilice los comandos de kubectl para mostrar los recursos clave, de la siguiente manera:

kubectl get nodepools

kubectl get ocinodeclasses

kubectl get nodeclaims

kubectl get nodes -l karpenter.sh/nodepool

Utilice los comandos de kubectl para revisar los detalles y las condiciones, de la siguiente manera:

kubectl describe ocinodeclass <name>

kubectl describe nodeclaim <name>

Comprobar logs de controlador de KPO

Utilice los comandos de kubectl para revisar el estado de los pods de KPO y los logs, de la siguiente manera:

kubectl get pods --namespace <karpenter-namespace>

kubectl logs --namespace <karpenter-namespace> <pod-name>

Activar Registro de Depuración

Aumente el registro temporalmente cuando necesite más detalles en la salida del controlador KPO, de una o ambas de las siguientes maneras:

• Defina logLevel: debug en el archivo de valores de Helm y actualice el despliegue de KPO (consulte Cómo Cambiar y Volver a Aplicar Valores de Helm para Actualizar el Despliegue de KPO). Por defecto, el registro está en el nivel info.

• Defina OCI_GO_SDK_DEBUG=1 como una variable de entorno en el despliegue de KPO para activar el registro de depuración del SDK de OCI Go.

¿Se aplican las manchas especiales agregadas por el bootstrapping de OKE a los nodos gestionados por Karpenter?

Sí. Algunos tipos de nodos de trabajador requieren daños específicos. Configure las manchas en NodePool para que Karpenter ofrezca la capacidad correspondiente. A continuación, configure tolerancias en cargas de trabajo que se deben ejecutar en esos nodos de trabajador.

Para obtener más información sobre los contaminantes especiales, consulte Required Taints and Tolerations.

¿Cómo se configuran las VNIC secundarias?

Cuando un cluster utiliza el complemento CNI nativo de IP de la VCN de OCI, puede conectar VNIC secundarias a nodos de trabajador para que los pod reciban direcciones IP enrutables de la VCN de la subred de pod. Planifique cuidadosamente la capacidad de la subred para que no agote las direcciones disponibles.

Si el cluster utiliza el complemento CNI nativo de IP de la VCN de OCI, el complemento debe tener la versión 3.0.0 o posterior. Recomendamos encarecidamente el uso de la versión 3.2.0 o posterior. En el complemento CNI nativo de IP de la VCN de OCI versión 3.2.0 (y posterior), las VNIC secundarias admiten un máximo de 256 direcciones IP. Si el cluster utiliza una versión del complemento anterior a la versión 3.2.0, las VNIC secundarias admiten un máximo de 16 direcciones IP. Si el cluster tiene que utilizar una versión del complemento anterior a la versión 3.2.0, debe definir explícitamente ipCount en un valor no mayor que 16.

Además del número máximo de direcciones IP admitidas, las VNIC secundarias están sujetas a las siguientes restricciones:

• La cantidad de direcciones IP asignadas debe ser una potencia de dos, por lo que configure ipCount con una potencia de dos.

• Para las VNIC secundarias de solo IPv6 (pila única), solo se admiten 1, 16 o 256 direcciones IP asignadas, de modo que establezca ipCount en 1, 16 o 256.

• El total agregado de todas las direcciones IP asignadas en todas las VNIC secundarias de un nodo no debe superar los 256.

• Si ipCount no está definido para una VNIC secundaria, se define por defecto en 32 para clusters IPv4 y clusters de doble pila IPv6, y en 256 para clusters de pila única IPv6.

Tenga en cuenta las siguientes recomendaciones y directrices:

• Recomendamos configurar dos bloques CIDR para la subred de pod que utilizan las VNIC secundarias.
• Si la subred de pod utilizada por las VNIC secundarias tiene un único bloque CIDR, asegúrese de que la subred tenga un número suficiente de direcciones IP contiguas para alojar el número necesario de asignaciones de IP.

¿Cómo programa las cargas de trabajo en un pool de nodos de Karpenter específico?

Para forzar cargas de trabajo en un pool de nodos Karpenter específico, dirija la etiqueta del pool de nodos karpenter.sh/nodepool. Utilice la afinidad de nodos o un selector de nodos, según lo estricto que desee que sea la ubicación.

• Ejemplo de afinidad de nodos:

  affinity:
    nodeAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
        nodeSelectorTerms:
          - matchExpressions:
              - key: karpenter.sh/nodepool
                operator: In
                values:
                  - <nodepool-name>

  Para obtener más información sobre la afinidad de nodos, consulte Afinidad de nodos en la documentación de Kubernetes.

• Ejemplo de selector de nodos:

  nodeSelector:
    karpenter.sh/nodepool: <nodepool-name>

  Para obtener más información sobre los selectores de nodos, consulte nodeSelector en la documentación de Kubernetes.

¿Cómo distribuye las cargas de trabajo entre los dominios de disponibilidad y los dominios de errores con Karpenter Provider for OCI?

Karpenter Provider for OCI (KPO) respeta el nivel de pod topologySpreadConstraints cuando topologyKey coincide con una etiqueta de programación que soporta KPO. Normalmente, utilizará estas claves de topología con mayor frecuencia en OCI:

• topology.kubernetes.io/zone para distribuirlo entre dominios de disponibilidad (AD)
• oci.oraclecloud.com/fault-domain para distribuir entre dominios de errores (FD) en un dominio de disponibilidad

Para distribuir la capacidad aprovisionada por Karpenter, dirija el pool de nodos deseado mediante la etiqueta karpenter.sh/nodepool y asegúrese de que el NodePool seleccionado permite los AD o FD que desea que utilice el programador. Si define whenUnsatisfiable en DoNotSchedule, los pods que no pueden cumplir la restricción de distribución permanecen pendientes, lo que da a Karpenter la oportunidad de aprovisionar nodos que cumplan el requisito de distribución:

Recomendamos las siguientes prácticas:

• Defina replicas en un valor igual o mayor que el número de dominios de topología que desea utilizar.
• Utilice la expansión de AD cuando la carga de trabajo deba permanecer disponible en varios AD.
• Utilice la difusión de FD en una región de un solo AD.
• Asegúrese de que los requisitos de NodePool incluyen todos los valores de topología que utiliza topologySpreadConstraints.

Ejemplo: configuración de NodePool para permitir tres AD

apiVersion: karpenter.sh/v1
kind: NodePool
metadata:
  name: example-ad-nodepool
spec:
  template:
    spec:
      requirements:
      - key: topology.kubernetes.io/zone
        operator: In
        values:
        - <AVAILABILITY_DOMAIN_1>
        - <AVAILABILITY_DOMAIN_2>
        - <AVAILABILITY_DOMAIN_3>

Ejemplo: Distribuya un Deployment en los tres dominios de disponibilidad

apiVersion: apps/v1
kind: Deployment
metadata:
  name: example-ad-spread
spec:
  replicas: 3
  selector:
    matchLabels:
      app: example-ad-spread
  template:
    metadata:
      labels:
        app: example-ad-spread
    spec:
      affinity:
        nodeAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            nodeSelectorTerms:
            - matchExpressions:
              - key: karpenter.sh/nodepool
                operator: In
                values:
                - example-ad-nodepool
      topologySpreadConstraints:
      - maxSkew: 1
        minDomains: 3
        topologyKey: topology.kubernetes.io/zone
        whenUnsatisfiable: DoNotSchedule
        labelSelector:
          matchLabels:
            app: example-ad-spread
        matchLabelKeys:
        - pod-template-hash
        nodeAffinityPolicy: Honor
        nodeTaintsPolicy: Honor
      containers:
      - name: app
        image: registry.k8s.io/pause:3.9
        imagePullPolicy: IfNotPresent
        resources:
          requests:
            cpu: "1"

Ejemplo: configuración de NodePool para permitir tres FD en un único AD

apiVersion: karpenter.sh/v1
kind: NodePool
metadata:
  name: example-fd-nodepool
spec:
  template:
    spec:
      requirements:
      - key: topology.kubernetes.io/zone
        operator: In
        values:
        - <AVAILABILITY_DOMAIN>
      - key: oci.oraclecloud.com/fault-domain
        operator: In
        values:
        - FAULT-DOMAIN-1
        - FAULT-DOMAIN-2
        - FAULT-DOMAIN-3

Ejemplo: distribuya un Deployment entre esos tres documentos financieros

apiVersion: apps/v1
kind: Deployment
metadata:
  name: example-fd-spread
spec:
  replicas: 3
  selector:
    matchLabels:
      app: example-fd-spread
  template:
    metadata:
      labels:
        app: example-fd-spread
    spec:
      affinity:
        nodeAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            nodeSelectorTerms:
            - matchExpressions:
              - key: karpenter.sh/nodepool
                operator: In
                values:
                - example-fd-nodepool
      topologySpreadConstraints:
      - maxSkew: 1
        minDomains: 3
        topologyKey: oci.oraclecloud.com/fault-domain
        whenUnsatisfiable: DoNotSchedule
        labelSelector:
          matchLabels:
            app: example-fd-spread
        matchLabelKeys:
        - pod-template-hash
        nodeAffinityPolicy: Honor
        nodeTaintsPolicy: Honor
      containers:
      - name: app
        image: registry.k8s.io/pause:3.9
        imagePullPolicy: IfNotPresent
        resources:
          requests:
            cpu: "1"

Notas

• Utilice whenUnsatisfiable: DoNotSchedule cuando desee que Karpenter aprovisione capacidad que satisfaga la restricción de distribución.
• Asegúrese de que labelSelector coincida con las etiquetas de pod. Si no coincide, el programador no calcula el sesgo para el conjunto de pod previsto.
• Para obtener más información sobre las etiquetas de programación admitidas, consulte Programación, Etiquetas y Manchas.

¿Cómo enumera las imágenes de OKE compatibles para un cluster?

Utilice la CLI de OCI para recuperar las opciones del pool de nodos y filtrar los orígenes de imagen devueltos. Este enfoque permite identificar los OCID de imagen que son compatibles con la versión de Kubernetes del cluster.

1. Definir variables de entorno que especifiquen la región y el OCID del cluster, y que definan filtros para la versión de Kubernetes, la versión principal del sistema operativo y cualquier arquitectura o tipo de imagen que excluir:

   REGION="<region>"
   CLUSTER_OCID="<cluster-ocid>"
   OKE_VERSION="<kubernetes-version>"
   OS_MAJOR="<os-major-version>"
   EXCLUDE_PATTERN="<architecture-pattern>"

   donde:

   • <cluster-ocid> es el OCID del cluster.
   • <kubernetes-version> es la cadena de versión secundaria de Kubernetes que debe coincidir en el nombre de origen de imagen (por ejemplo, 1.31).
   • <os-major-version> es la versión principal del sistema operativo que debe coincidir en el nombre del origen de imagen (por ejemplo, 8 para Oracle Linux 8). Defina esta opción en una cadena vacía para evitar el filtrado por versión del sistema operativo.
   • <architecture-pattern> es un patrón de expresión regular que se utiliza para excluir nombres de origen de imagen (por ejemplo, aarch64|arm64|GPU para excluir imágenes de ARM o GPU). Establezca esta opción en una cadena vacía para evitar exclusiones.

   Por ejemplo:

   REGION="us-phoenix-1"
   CLUSTER_OCID="ocid1.cluster.oc1.phx.aaaaaaaa______w5q"
   OKE_VERSION="1.31"
   OS_MAJOR="8"
   EXCLUDE_PATTERN="aarch64|arm64|GPU"

2. Ejecute el siguiente comando de la CLI de OCI para obtener los OCID de las imágenes compatibles:

   oci ce node-pool-options get --region "${REGION}" --node-pool-option-id "${CLUSTER_OCID}" --output json | jq -r --arg ver "${OKE_VERSION:-}" --arg os "${OS_MAJOR:-}" --arg ex "${EXCLUDE_PATTERN:-}" '.data.sources[] | . as $src | ($src["source-name"] // "") as $name | select( ($ver == "" or ($name | test($ver))) and ($os == "" or ($name | test($os; "i"))) and ($ex == "" or ($name | test($ex; "i") | not)) ) | {id: $src["image-id"], source_name: $name}'

Qué hacer si no se aprovisiona un pool de nodos de unidad flexible y se ve: "omitiendo, los requisitos del pool de nodos filtran todos los tipos de instancias".

Las formas flexibles requieren una configuración de tamaño para que KPO pueda traducir los requisitos de forma en una oferta de concreto. Para solucionarlo, defina shapeConfigs en el OCINodeClass al que se hace referencia o defina los valores por defecto en el archivo de valores de Helm en settings.flexibleShapeConfigs.

• Ejemplo: definición de shapeConfigs en el OCINodeClass al que se hace referencia:

  apiVersion: oci.oraclecloud.com/v1beta1
  kind: OCINodeClass
  metadata:
    name: example-nodeclass
  spec:
    shapeConfigs:
      - ocpus: 2
        memoryInGbs: 16
        baselineOcpuUtilization: BASELINE_1_2
  ...

• Ejemplo: definición global de los valores shapeConfigs por defecto en el archivo de valores de Helm:

  settings:
    flexibleShapeConfigs:
      ocpus: 2
      memoryInGbs: 16

  Puede sustituir un valor por defecto en el archivo de valores de Helm definiendo shapeConfigs en OCINodeClass.

Si utiliza una reserva de capacidad y se enfrenta a este problema, confirme que flexibleShapeConfigs en el archivo de valores de Helm (o shapeConfigs en OCINodeClass, si está presente) coincide exactamente con la reserva, con los mismos valores para ocpus, memoryInGbs y baselineOcpuUtilization.

¿Cómo se ejecuta el controlador KPO con el registro de depuración?

Aumente la salida del log para solucionar problemas de aprovisionamiento y llamadas de API de OCI de una o ambas formas:

• Defina logLevel: debug en el archivo de valores de Helm y actualice el despliegue de KPO (consulte Cómo Cambiar y Volver a Aplicar Valores de Helm para Actualizar el Despliegue de KPO).

• Defina OCI_GO_SDK_DEBUG=1 como una variable de entorno en el despliegue de KPO para activar el registro de depuración del SDK de OCI Go.

¿Cómo puede transferir un script cloud-init personalizado?

Puede ejecutar comandos o configuraciones específicos durante el proceso de inicio de un nodo mediante la inyección de scripts cloud-init personalizados mediante el recurso OCINodeClass.

Pruebe minuciosamente los scripts cloud-init personalizados antes de desplegarlos, para asegurarse de que los scripts se ejecutan como se esperaba y no interfieran con el proceso de inicialización de nodos estándar.

Hay dos métodos principales:

• Opción 1: utilice preBootstrapInitScript y postBootstrapInitScript en OCINodeClass (recomendado)

  Puede ejecutar scripts personalizados antes y después del script cloud-init por defecto mediante preBootstrapInitScript y postBootstrapInitScript en OCINodeClass para especificar los scripts personalizados, de la siguiente forma:

  1. Prepare los scripts personalizados de cloud-init:
     1. Cree las secuencias de comandos que desee ejecutar antes y después de la inicialización de nodos por defecto.
     2. Codifique cada script con Base64.

  2. Agregue los scripts codificados en base64 a los campos preBootstrapInitScript y/o postBootstrapInitScript del recurso OCINodeClass.

     Por ejemplo:

     apiVersion: oci.oraclecloud.com/v1beta1
     kind: OCINodeClass
     metadata:
       name: example-nodeclass
     spec:
       ...
       preBootstrapInitScript: "IyEvYmluL2Jhc2gKZWNobyAiSSBhbSBhIHByZSBib290c3RyYXAgc2NyaXB0Ig=="
       postBootstrapInitScript: "IyEvYmluL2Jhc2gKZWNobyAiSSBhbSBhIHBvc3QgYm9vdHN0cmFwIHNjcmlwdCI="

• Opción 2: especifique un script cloud-init completo codificado en base64 en metadata.user_data (flujo de trabajo avanzado)

  Puede proporcionar un script cloud-init personalizado completo definiendo el campo user_data en la sección metadata de OCINodeClass. Este método le proporciona un control total del proceso de inicialización, pero requiere una gestión cuidadosa para garantizar la compatibilidad con Kubernetes Engine.

  1. Prepare el script cloud-init personalizado:

     1. Cree el script cloud-init personalizado e incluya las configuraciones personalizadas y los comandos necesarios que unen el nodo al cluster.

        En el siguiente ejemplo, se leen los valores de configuración del servicio de metadatos de instancia (IMDS) de OCI, que solo está disponible desde la instancia y, a continuación, se ejecutan los comandos que unen el nodo al cluster.

        #!/usr/bin/env bash
        set -o errexit
        set -o nounset
        set -o pipefail
        # OCI Instance Metadata Service (IMDS): link-local, reachable only from within the instance.
        # Do not use IMDS URLs with untrusted input (SSRF risk).
        MD_URL="http://169.254.169.254/opc/v2/instance/metadata"
        AUTH_HDR="Authorization: Bearer Oracle"
        
        # Fetch a metadata key, returning empty on error/missing
        fetch_md() {
          local key="$1"
          curl -sfL --noproxy '*' -H "${AUTH_HDR}" --connect-timeout 2 --max-time 5 "${MD_URL}/${key}" 2>/dev/null || true
        }
        
        CLUSTER_DNS="$(fetch_md kubedns_svc_ip)"
        KUBELET_EXTRA_ARGS="$(fetch_md kubelet-extra-args)"
        APISERVER_ENDPOINT="$(fetch_md apiserver_host)"
        KUBELET_CA_CERT="$(fetch_md cluster_ca_cert)"
        
        # Export only when present to avoid surprising consumers with empty values
        [ -n "${CLUSTER_DNS}" ] && export CLUSTER_DNS
        [ -n "${KUBELET_EXTRA_ARGS}" ] && export KUBELET_EXTRA_ARGS
        [ -n "${APISERVER_ENDPOINT}" ] && export APISERVER_ENDPOINT
        [ -n "${KUBELET_CA_CERT}" ] && export KUBELET_CA_CERT
        
        # BEGIN OF CUSTOM SCRIPT BOOTSTRAP SCRIPT , REPLACE THIS SECTION WITH CUSTOM PRE BOOTSTRAP SCRIPT
        #echo "pre bootstrap script"
        #echo "CLUSTER_DNS: ${CLUSTER_DNS:-}"
        #echo "KUBELET_EXTRA_ARGS: ${KUBELET_EXTRA_ARGS:-}"
        #echo "APISERVER_ENDPOINT: ${APISERVER_ENDPOINT:-}"
        #echo "KUBELET_CA_CERT: ${KUBELET_CA_CERT:-}"
        # END OF CUSTOM SCRIPT BOOTSTRAP SCRIPT
        
        bash /etc/oke/oke-install.sh
        
        # BEGIN OF POST BOOTSTRAP SCRIPT, IF NEEDED
        #echo "post bootstrap script"
        #END OF POST BOOTSTRAP SCRIPT

        Si utiliza este ejemplo, solo inserte la lógica personalizada:

        • entre # BEGIN OF CUSTOM SCRIPT BOOTSTRAP SCRIPT , REPLACE THIS SECTION WITH CUSTOM PRE BOOTSTRAP SCRIPT y # END OF CUSTOM SCRIPT BOOTSTRAP SCRIPT

        • entre # BEGIN OF POST BOOTSTRAP SCRIPT, IF NEEDED y #END OF POST BOOTSTRAP SCRIPT

        Tenga en cuenta que los parámetros necesarios para los nodos de inicialización están disponibles en el servicio de metadatos de instancia (IMDS). Al crear un script personalizado, recomendamos definir las variables de entorno CLUSTER_DNS, KUBELET_EXTRA_ARGS, APISERVER_ENDPOINT y KUBELET_CA_CERT recuperando sus valores de IMDS, como se muestra en el script de ejemplo. La configuración de estas variables como se muestra es esencial para el correcto funcionamiento de KPO.

     2. Codifique el script en Base64.

  2. Agregue el script codificado en base64 al campo user_data de la sección metadata de OCINodeClass.

     Por ejemplo:

     apiVersion: oci.oraclecloud.com/v1beta1
     kind: OCINodeClass
     metadata:
       name: example-nodeclass
     spec:
      metadata:
         user_data: "IyEvdXNyL2Jpbi9lbnYgYmFzaAoKc2V0IC1vIGVycmV4aXQKc2V0IC1vIG5vdW5zZXQKc2V0IC1vIHBpcGVmYWlsCg=="
     ...

¿Qué debe considerar para KubeletConfig maxPods y podsPerCore?

Utilice kubeletConfig para controlar la densidad de pod de los nodos de trabajador y mantenerla alineada con la capacidad de red.

• Defina podsPerCore en un valor que no supere maxPods.

• Para los clusters que utilizan el complemento CNI nativo de IP de la VCN de OCI, defina maxPods en un valor inferior a la suma agregada de valores ipCount en las VNIC secundarias.

¿Cómo configura el OCID del compartimento de imagen predefinido de OKE en Karpenter Provider for OCI (KPO)?

Si desea que KPO utilice una imagen personalizada basada en una imagen de OKE (mediante la definición de imageType: OKEImage) y la imagen se encuentra en un compartimento diferente, puede activar KPO para detectar la imagen mediante el valor de Helm preBakedImageCompartmentId o el valor imageFilter de OCINodeClass.

Si solo utiliza imágenes de OKE publicadas por Oracle o hace referencia a imágenes directamente por OCID (imageId), esta configuración no es necesaria.

Requisitos previos

• Conoce el OCID del compartimento que contiene las imágenes que desea que detecte KPO.

• Existe una política adecuada para permitir que el controlador de KPO lea imágenes en el compartimento diferente. Por ejemplo:

  Allow any-user to read instance-images in compartment <compartment-name> where all { ...workload identity conditions... }

Opción 1: Configurar el compartimento para todos los recursos de OCINodeClass (mediante un valor de Helm)

1. Defina el valor de Helm preBakedImageCompartmentId:

   settings: 
     preBakedImageCompartmentId: "<compartment-ocid-containing-images>"

2. Aplique la configuración actualizada ejecutando helm upgrade para el despliegue de KPO (consulte Cómo Cambiar y Volver a Aplicar Valores de Helm para Actualizar el Despliegue de KPO).

Opción 2: Configurar el compartimento para un OCINodeClass específico (mediante imageFilter)

Defina compartmentId en imageFilter:

volumeConfig:
  bootVolumeConfig:
    imageConfig:
      imageType: OKEImage
      imageFilter:
        compartmentId: "<compartment-ocid-containing-images>"
        osFilter: "Oracle Linux"
        osVersionFilter: "8"

Imágenes personalizadas basadas en imágenes de OKE (requisito de k8s_version)

Cuando utilice una imagen personalizada basada en una imagen de OKE, asegúrese de que la imagen tenga una u otra de las siguientes opciones:

• una etiqueta de formato libre k8s_version
• un valor BaseImageId que apunta (directa o indirectamente) a una imagen de OKE ascendiente que tiene la etiqueta k8s_version

Si no hay ninguno, KPO no puede determinar la versión de Kubernetes para la imagen y la selección de imágenes puede fallar con un error missing k8s_version tag.

¿Cómo cambia y vuelve a aplicar los valores de Helm para actualizar el despliegue de KPO?

Para cambiar los valores de Helm después de la instalación, actualice el archivo de valores de Helm y, a continuación, aplique la nueva configuración.

1. Actualice el archivo de valores de Helm (por ejemplo, agregue o cambie logLevel: debug).

2. Descargue el último índice para el repositorio karpenter-provider-oci introduciendo:

   helm repo update karpenter-provider-oci

3. Aplique la configuración actualizada introduciendo:

   helm upgrade karpenter karpenter-provider-oci/karpenter \
     --version <chart-version> \
     --namespace <karpenter-namespace> \
     --values <path-to-helm-values-file>
   

4. Confirme que se haya aplicado la configuración actualizada y que los pods del controlador de KPO se reinicien correctamente:

   kubectl get pods --namespace <karpenter-namespace>