{"id":30351584,"url":"https://github.com/zoom/karpenter-oci","last_synced_at":"2025-08-18T23:09:48.809Z","repository":{"id":294379433,"uuid":"982505825","full_name":"zoom/karpenter-oci","owner":"zoom","description":"the oracle cloud provider of karpenter","archived":false,"fork":false,"pushed_at":"2025-08-06T06:56:14.000Z","size":488,"stargazers_count":35,"open_issues_count":9,"forks_count":9,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-08-06T07:24:24.652Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zoom.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-13T01:52:11.000Z","updated_at":"2025-08-06T06:01:55.000Z","dependencies_parsed_at":"2025-06-19T04:22:43.926Z","dependency_job_id":"86644239-1252-4b32-aedf-ffaed595f806","html_url":"https://github.com/zoom/karpenter-oci","commit_stats":null,"previous_names":["zoom/karpenter-oci"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/zoom/karpenter-oci","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoom%2Fkarpenter-oci","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoom%2Fkarpenter-oci/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoom%2Fkarpenter-oci/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoom%2Fkarpenter-oci/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zoom","download_url":"https://codeload.github.com/zoom/karpenter-oci/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoom%2Fkarpenter-oci/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271073387,"owners_count":24694538,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-18T02:00:08.743Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-18T23:09:48.180Z","updated_at":"2025-08-18T23:09:48.796Z","avatar_url":"https://github.com/zoom.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# karpenter-oci\n\n## Description\nkarpenter-oci is the oracle cloud implement of karpenter, it depends on [karpenter](https://github.com/kubernetes-sigs/karpenter). It supports OKE cluster, and self-managed cluster on oracle cloud.\nAnd you are interested in contribution, you can find the project from [karpenter-oci](https://github.com/zoom/karpenter-oci)\n## Arch Overview\n![Arch](designs/images/karpenter-oci-arch.png)\n\n## Feature\n1. Automatically scale up node capacity when available resources are insufficient\n2. Decommission idle nodes when no workload is present\n3. Support multi authenticate Method: resource principle, instance principle, api key, session\n4. Image is configurable\n5. Subnet is configurable\n6. Supports configuration of none or multiple security groups\n7. Support VM and Bare Metal\n8. Support attachment of additional disk\n9. Support specifying the kubelet configuration\n\n## Installation\n\n### prepare\n-  create a compartment, karpenter-oci will launch instance in this compartment \n- create an OKE cluster under the above compartment \n- create policy in oracle console, the name could like karpenter-oke-policy, the statements as below\n```\nAllow any-user to manage instance-family in tenancy where all {request.principal.type = 'workload',request.principal.namespace = 'karpenter',request.principal.service_account = 'karpenter'}\nAllow any-user to manage instances in tenancy where all {request.principal.type = 'workload',request.principal.namespace = 'karpenter',request.principal.service_account = 'karpenter'}\nAllow any-user to read instance-images in tenancy where all {request.principal.type = 'workload',request.principal.namespace = 'karpenter',request.principal.service_account = 'karpenter'}\nAllow any-user to read app-catalog-listing in tenancy where all {request.principal.type = 'workload',request.principal.namespace = 'karpenter',request.principal.service_account = 'karpenter'}\nAllow any-user to manage volume-family in tenancy where all {request.principal.type = 'workload',request.principal.namespace = 'karpenter',request.principal.service_account = 'karpenter'}\nAllow any-user to manage volume-attachments in tenancy where all {request.principal.type = 'workload',request.principal.namespace = 'karpenter',request.principal.service_account = 'karpenter'}\nAllow any-user to use volumes in tenancy where all {request.principal.type = 'workload',request.principal.namespace = 'karpenter',request.principal.service_account = 'karpenter'}\nAllow any-user to use virtual-network-family in tenancy where all {request.principal.type = 'workload',request.principal.namespace = 'karpenter',request.principal.service_account = 'karpenter'}\nAllow any-user to inspect vcns in tenancy where all {request.principal.type = 'workload',request.principal.namespace = 'karpenter',request.principal.service_account = 'karpenter'}\nAllow any-user to use subnets in tenancy where all {request.principal.type = 'workload',request.principal.namespace = 'karpenter',request.principal.service_account = 'karpenter'}\nAllow any-user to use network-security-groups in tenancy where all {request.principal.type = 'workload',request.principal.namespace = 'karpenter',request.principal.service_account = 'karpenter'}\nAllow any-user to use vnics in tenancy where all {request.principal.type = 'workload',request.principal.namespace = 'karpenter',request.principal.service_account = 'karpenter'}\nAllow any-user to use tag-namespaces in tenancy where all {request.principal.type = 'workload',request.principal.namespace = 'karpenter',request.principal.service_account = 'karpenter'}\n```\n- create tag namespace, the namespace name could like `oke-karpenter-ns`, the required keys show in below sheet, if you want to attach more customer tags, you also can add them in the namespace.\n\n| key                               | description                                   |\n|:----------------------------------|:----------------------------------------------|\n| karpenter_k8s_oracle/ocinodeclass | the name of nodeclass used to crate instance  |\n| karpenter_sh/managed-by           | the OKE cluster name                          |\n| karpenter_sh/nodepool             | the name of nodepool used to create instance  |\n| karpenter_sh/nodeclaim            | the name of nodeclaim used to create instance |\n\n### install\nreplace the clusterName, clusterEndpoint, clusterDns, compartmentId, ociResourcePrincipalRegion with yours.\n```\nkubectl apply -f ./pkg/apis/crds/\nhelm upgrade --install karpenter ./charts/karpenter --namespace \"karpenter\" --create-namespace --set \"settings.clusterName=karpenter-oci-test\" --set \"settings.clusterEndpoint=https://10.0.0.8:6443\" --set \"settings.clusterDns=10.96.5.5\" --set \"settings.compartmentId=ocid1.compartment.oc1..aaaaaaaa\" --set \"settings.ociResourcePrincipalRegion=us-ashburn-1\"\n```\n\n#### or you can install from helm git repo \n```\nhelm repo add karpenter-oci https://zoom.github.io/karpenter-oci\n```\nIf you had already added this repo earlier, run `helm repo update` to retrieve the latest versions of the packages.\nYou can then run `helm search repo karpenter-oci` to see the charts.\n\nTo install the karpenter chart, also replace the clusterName, clusterEndpoint, clusterDns, compartmentId, ociResourcePrincipalRegion with yours:\n```\nhelm install karpenter karpenter-oci/karpenter --version 1.4.1 --namespace \"karpenter\" --create-namespace --set \"settings.clusterName=karpenter-oci-test\" --set \"settings.clusterEndpoint=https://10.0.0.8:6443\" --set \"settings.clusterDns=10.96.5.5\" --set \"settings.compartmentId=ocid1.compartment.oc1..aaaaaaaa\" --set \"settings.ociResourcePrincipalRegion=us-ashburn-1\"\n```\nTo uninstall the chart:\n```\nhelm uninstall karpenter\n```\nsetting details\n\n| setting                    | description                                                                                                                                | default                      |\n|----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------|------------------------------|\n| clusterName                | cluster name                                                                                                                               |                              |\n| clusterEndpoint            | api server private endpoint                                                                                                                |                              |\n| clusterDns                 | IP addresses for the cluster DNS server, general is core dns ip                                                                            |                              |\n| compartmentId              | the compartment id or your worker nodes                                                                                                    |                              |\n| ociResourcePrincipalRegion | the region your cluster belong to, refer [issue](https://github.com/oracle/oci-go-sdk/issues/489)                                                                                      |                              |\n| ociAuthMethods             | API_KEY, OKE, SESSION, INSTANCE_PRINCIPAL                                                                                                  | OKE                          |\n| flexCpuConstrainList       | to constrain the ocpu cores of flex instance, instance create in this cpu size list, ocpu is twice of vcpu                                 | \"1,2,4,8,16,32,48,64,96,128\" |\n| flexCpuMemRatios           | the ratios of vcpu and mem, eg. FLEX_CPU_MEM_RATIOS=2,4, if create flex instance with 2 cores(1 ocpu), mem should be 4Gi or 8Gi            | \"2,4,8\"                      |\n| tagNamespace               | The tag namespace used to create and list instances by karpenter-oci, karpenter-oci will attach nodepool and nodeclass tag on the instance | oke-karpenter-ns             |\n| vmMemoryOverheadPercent    | he VM memory overhead as a percent that will be subtracted from the total memory for all instance types                                    | 0.075                        |\n## Usage\n### nodepool\nnodepool use to specify the disruption strategy, cpu and memory limits and requirements. The oracle feature requirement include the below labels:\n\n| label                                    | description                                                                                                           | example             |\n|------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|---------------------|\n| karpenter.k8s.oracle/instance-shape-name | the shape name                                                                                                        | VM.Standard.E4.Flex |\n| karpenter.k8s.oracle/instance-cpu        | the vcpu count of the instance shape, for flex shape, karpenter-oci will strictly create instance in these vcpu sizes | 4,8                 |\n| karpenter.k8s.oracle/instance-memory     | the memory size of the instance shape, the unit is MB                                                                 | 2048,4096           |\n| karpenter.k8s.oracle/instance-gpu        | the gpu card count of the instance shape                                                                              | 1                   |\n| karpenter.k8s.oracle/is-flexible         | the instance shape is flexible or not                                                                                 | \"true\"              |\n\n[example](docs/sample/nodepool_sample.yaml)\n```yaml\napiVersion: karpenter.sh/v1\nkind: NodePool\nmetadata:\n  name: karpenter-test\nspec:\n  disruption:\n    budgets:\n      - nodes: 10%\n    consolidateAfter: 30m0s\n    consolidationPolicy: WhenEmpty\n  limits:\n    cpu: 64\n    memory: 300Gi\n  template:\n    metadata:\n      labels:\n        servicegroup: karpenter-test\n    spec:\n      expireAfter: Never\n      nodeClassRef:\n        group: karpenter.k8s.oracle\n        kind: OciNodeClass\n        name: karpenter-test\n      requirements:\n        - key: karpenter.sh/capacity-type\n          operator: In\n          values:\n            - on-demand\n            ### if you wanna enable preemptible instances creation for lower cost, add below line.\n            - preemptible\n        - key: karpenter.k8s.oracle/instance-shape-name\n          operator: In\n          values:\n            - VM.Standard.E4.Flex\n        - key: karpenter.k8s.oracle/instance-cpu\n          operator: In\n          values:\n            - '4'\n            - '8'\n            - '16'\n        - key: kubernetes.io/os\n          operator: In\n          values:\n            - linux\n      terminationGracePeriod: 30m\n```\n### ocinodeclass\nthe ocinodeclass is used for config the oracle cloud related resource, like OS image, subnet, security group, and also kubelet config.\n\n| spec                           | description                                                                                                                | required | example                                                                                                              |\n|--------------------------------|----------------------------------------------------------------------------------------------------------------------------|----------|----------------------------------------------------------------------------------------------------------------------|\n| bootConfig.bootVolumeSizeInGBs | The size of the boot volume in GBs. Minimum value is 50 GB and maximum value is 32,768 GB (32 TB).                         | yes      | 100                                                                                                                  |\n| bootConfig.bootVolumeVpusPerGB | The number of volume performance units (VPUs) that will be applied to this volume per GB                                   | yes      | 10                                                                                                                   |\n| imageSelector[i].compartmentId | the compartment id of the image                                                                                            | yes      | ocid1.compartment.oc1..aaaaaaaab4u67dhgtj5gpdpp3z42xqqsdnufxkatoild46u3hb67vzojfmzq                                  |\n| imageSelector[i].name          | the image name                                                                                                             | yes      | Oracle-Linux-8.10-2025.02.28-0-OKE-1.30.1-760                                                                        |\n| launchOptions                  | LaunchOptions Options for tuning the compatibility and performance of VM shapes                                            | no       | [detail](https://docs.oracle.com/en-us/iaas/tools/python/2.150.3/api/core/models/oci.core.models.LaunchOptions.html) |\n| blockDevices                   | The details of the volume to create for CreateVolume operation.                                                            | no       | `sizeInGBs: 100` `vpusPerGB: 10`                                                                                     |\n| imageFamily                    | support OracleOKELinux and Ubuntu2204, for OKE cluster use `OracleOKELinux` and for self-managed cluster use `Ubuntu2204`  | yes      | OracleOKELinux                                                                                                       |\n| vcnId                          | the vcnId of the cluster                                                                                                   | yes      |                                                                                                                      |\n| subnetSelector                 | the name of the subnet which you want to create the worker nodes instance in                                               | yes      | oke-nodesubnet-quick-test                                                                                            |\n| securityGroupSelector          | the security groups you want to attach to the instance                                                                     | no       |                                                                                                                      |\n| tags                           | the tags you want to attach to the instance                                                                                | no       |                                                                                                                      |\n| metaData                       | specify for native cni cluster                                                                                             | no       | `{\"oke-native-pod-networking\":\"true\"}`                                                                               |\n| userData                       | customer userdata you want to run in the cloud-init script, it will execute before the kubelet start                       | no       |                                                                                                                      |\n| kubelet                        | customer kubelet config                                                                                                    | no       | [KubeletConfiguration](pkg/apis/v1alpha1/ocinodeclass.go)                                                            |\n\n- if your cluster use flannel as the cni, you can refer:\n[example](docs/sample/oke_ocinodeclasses_sample.yaml)\n```yaml\napiVersion: karpenter.k8s.oracle/v1alpha1\nkind: OciNodeClass\nmetadata:\n  name: karpenter-test\nspec:\n  bootConfig:\n    bootVolumeSizeInGBs: 100\n    bootVolumeVpusPerGB: 10\n  imageSelector:\n    - name: Oracle-Linux-8.10-2025.02.28-0-OKE-1.30.1-760\n      compartmentId: ocid1.compartment.oc1..aaaaaaaab4u67dhgtj5gpdpp3z42xqqsdnufxkatoild46u3hb67vzojfmzq\n  imageFamily: OracleOKELinux\n  kubelet:\n    evictionHard:\n      imagefs.available: 15%\n      imagefs.inodesFree: 10%\n      memory.available: 750Mi\n      nodefs.available: 10%\n      nodefs.inodesFree: 5%\n    systemReserved:\n      memory: 100Mi\n  subnetSelector: \n    - name: {{ .subnetName }}\n  vcnId: {{ .vcnId }}\n```\n- if your cluster use the native cni, you should set `oke-native-pod-networking` in the metadata as `true`, you can refer: [example](docs/sample/oke_ocinodeclasses_native_cni_sample.yaml)\n```yaml\napiVersion: karpenter.k8s.oracle/v1alpha1\nkind: OciNodeClass\nmetadata:\n  name: karpenter-test\nspec:\n  bootConfig:\n    bootVolumeSizeInGBs: 100\n    bootVolumeVpusPerGB: 10\n  imageSelector:\n    - name: Oracle-Linux-8.10-2025.02.28-0-OKE-1.30.1-760\n      compartmentId: ocid1.compartment.oc1..aaaaaaaab4u67dhgtj5gpdpp3z42xqqsdnufxkatoild46u3hb67vzojfmzq\n  imageFamily: OracleOKELinux\n  metaData:\n    oke-native-pod-networking: \"true\"\n  kubelet:\n    evictionHard:\n      imagefs.available: 15%\n      imagefs.inodesFree: 10%\n      memory.available: 750Mi\n      nodefs.available: 10%\n      nodefs.inodesFree: 5%\n    systemReserved:\n      memory: 100Mi\n  subnetSelector: \n    - name: {{ .subnetName }}\n  vcnId: {{ .vcnId }}\n```\n\n## Support\nIf you meet any problem, welcome to raise a issue.\n## Roadmap\n| item                          | date      |\n|-------------------------------|-----------|\n| update karpenter core to v1.4 | 2025.June |\n\n## Contributing\nContributing is welcome, you can raise a PR to add new feature or fix bugs. We use `envtest` to run the test suite, better add the related test case in your commit.\n\n## License\nhttp://www.apache.org/licenses/LICENSE-2.0","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzoom%2Fkarpenter-oci","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzoom%2Fkarpenter-oci","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzoom%2Fkarpenter-oci/lists"}