diff --git a/content/product/operation_references/hypervisor_configuration/_index.md b/content/product/operation_references/hypervisor_configuration/_index.md index e7f0ee3c..0e582583 100644 --- a/content/product/operation_references/hypervisor_configuration/_index.md +++ b/content/product/operation_references/hypervisor_configuration/_index.md @@ -2,7 +2,7 @@ title: "Hypervisor Configuration" linkTitle: "Virtualization Drivers" date: "2025-03-05" -description: "Configure KVM and LXC hypervisor nodes." +description: "Configure KVM, LXC, and NICo hypervisor nodes." categories: pageintoc: "" hide_feedback: true @@ -10,7 +10,6 @@ tags: weight: "1" --- -These pages contain explanations and configuration for configuring hypervisor nodes with the KVM and LXC drivers. - +These pages contain explanations and configuration for configuring hypervisor nodes with the KVM, LXC, and NICo drivers. diff --git a/content/product/operation_references/hypervisor_configuration/nico_driver.md b/content/product/operation_references/hypervisor_configuration/nico_driver.md new file mode 100644 index 00000000..7123b347 --- /dev/null +++ b/content/product/operation_references/hypervisor_configuration/nico_driver.md @@ -0,0 +1,130 @@ +--- +title: "NICo Driver (EE)" +date: "2026-06-03" +description: "Configure OpenNebula hosts and VM templates for NVIDIA NICo instances." +categories: +pageintoc: "177" +tags: +weight: "4" +--- + + + +## Overview + +The NICo VMM and IM drivers let OpenNebula deploy and monitor NVIDIA NICo instances through the NICo REST API. A NICo Host in OpenNebula does not represent a KVM or LXC hypervisor node. Instead, it represents a NICo allocation and the API connection settings used to create, inspect, and delete NICo instances. + +The NICo VMM driver stores the NICo instance UUID as the VM `DEPLOY_ID`. Later operations, such as shutdown and monitoring, use this value to call the NICo API. + +OpenNebula keeps a NICo VM in the `RUNNING` state during a NICo reboot request. The monitor data includes `NICO_STATUS`, so transient NICo states such as `Rebooting` can be inspected without changing the OpenNebula lifecycle state. + +## Creating a NICo Host + +Create a dedicated Host using the NICo IM and VMM drivers: + +```shell +onehost create nico --im nico --vm nico +``` + +After creating the Host, add the NICo connection and allocation attributes: + +```shell +onehost update nico +``` + +Example Host template: + +```default +NICO_CARBIDE_PROXY = "https://ncp-isv-carbide-proxy.nvidia.com/v1/carbide/proxy" +NICO_SSA_ISSUER = "https://issuer.example/token-provider" +NICO_NGC_ORG = "example-org" +NICO_ISV_CLIENT_ID = "client-id" +NICO_ISV_CLIENT_SECRET = "client-secret" +NICO_TARGET_SCOPES = "scope1 scope2" +NICO_ALLOCATION = "allocation-id" +NICO_API_TIMEOUT = "60" +NICO_FORCE_DESTROY = "NO" +``` + +Required Host attributes: + +- `NICO_CARBIDE_PROXY`: base URL for the CARBIDE proxy. +- `NICO_SSA_ISSUER`: issuer URL used to obtain the JWT token. +- `NICO_NGC_ORG`: NGC organization used in NICo API paths. +- `NICO_ISV_CLIENT_ID`: client ID for the `client_credentials` flow. +- `NICO_ISV_CLIENT_SECRET`: client secret for the `client_credentials` flow. +- `NICO_TARGET_SCOPES`: scopes requested when acquiring the JWT token. +- `NICO_ALLOCATION`: NICo allocation ID represented by this OpenNebula Host. + +Optional Host attributes: + +- `NICO_API_TIMEOUT`: API timeout in seconds. The default is `60`. +- `NICO_FORCE_DESTROY`: set to `YES` to request forced deletion on cancel operations. The default is `NO`. + +The IM driver uses `NICO_ALLOCATION` to query `GET /allocation/` and report Host capacity from `allocationConstraints[0].constraintValue`. + +## Creating a NICo VM Template + +Create a VM template with the NICo instance attributes required by the allocation and operating system you want to deploy. + +Example VM template: + +```default +NAME = "nico-instance" +CPU = "1" +MEMORY = "1" + +NICO_INSTANCE_TYPE_ID = "instance-type-id" +NICO_OS_ID = "operating-system-id" +NICO_VPC_ID = "vpc-id" + +NICO_NETWORK_SECURITY_GROUP_ID = "security-group-id" +NICO_SSH_KEY_GROUP_IDS = "ssh-key-group-1,ssh-key-group-2" +NICO_USER_DATA = "cloud-init-or-user-data" +NICO_LABELS = "{\"environment\":\"test\"}" + +NIC = [ + NETWORK = "nico-network", + NICO_VPC_PREFIX_ID = "vpc-prefix-id" +] + +SCHED_REQUIREMENTS = "ID = 123" +``` + +Required VM attributes: + +- `CPU`: Must be `1`, as it represents a single instance to the OpenNebula scheduler. +- `MEMORY`: Must be `1`, same as with CPU. +- `NICO_INSTANCE_TYPE_ID`: NICo instance type to deploy. +- `NICO_OS_ID`: operating system ID. +- `NICO_VPC_ID`: VPC used by the instance. This attribute must be defined in the VM template. +- `NIC`: network interface used by the instance. +- `NIC/NICO_VPC_PREFIX_ID`: VPC prefix used by the instance interface. This attribute must be defined in the NIC section. +- `SCHED_REQUIREMENTS`: scheduling expression used to place the VM on the NICo Host. + +`NICO_VPC_ID` is read only from the VM template. `NICO_VPC_PREFIX_ID` is read only from the first NIC section. + +Common optional VM attributes: + +- `NICO_NETWORK_SECURITY_GROUP_ID`: network security group ID. +- `NICO_SSH_KEY_GROUP_IDS`: comma-separated list of SSH key group IDs. +- `NICO_USER_DATA`: user data passed to the NICo instance. +- `NICO_LABELS`: JSON object with labels to attach to the NICo instance. + +## Scheduling to the NICo Host + +NICo instances must be scheduled to the OpenNebula Host configured with the NICo drivers and the corresponding NICo allocation attributes. Use `SCHED_REQUIREMENTS` in the VM template to force placement on that Host. + +Pin by Host ID: + +```default +SCHED_REQUIREMENTS = "ID = 123" +``` + +Alternatively, place the VM on any Host using the NICo VMM driver: + +```default +SCHED_REQUIREMENTS = "VM_MAD = \"nico\"" +``` + +Using explicit scheduling prevents the NICo template from being placed on regular KVM or LXC Hosts. diff --git a/content/solutions/ai_factory_blueprints/infrastructure_integration/_index.md b/content/solutions/ai_factory_blueprints/infrastructure_integration/_index.md new file mode 100644 index 00000000..aa8f640e --- /dev/null +++ b/content/solutions/ai_factory_blueprints/infrastructure_integration/_index.md @@ -0,0 +1,6 @@ +--- +title: "Infrastructure Integration" +description: "Integrate OpenNebula with external infrastructure services for AI Factory deployments." +weight: 5 +tags: ['AI'] +--- diff --git a/content/solutions/ai_factory_blueprints/infrastructure_integration/bare_metal_nico.md b/content/solutions/ai_factory_blueprints/infrastructure_integration/bare_metal_nico.md new file mode 100644 index 00000000..d08e89e0 --- /dev/null +++ b/content/solutions/ai_factory_blueprints/infrastructure_integration/bare_metal_nico.md @@ -0,0 +1,163 @@ +--- +title: "Bare Metal as a Service with NICo" +date: "2026-06-24" +description: "Integrate OpenNebula with NVIDIA NICo to offer multi-tenant bare metal instances as a service." +weight: 1 +tags: ['AI'] +--- + + + +This guide describes how to integrate an existing OpenNebula cloud with NVIDIA NICo to offer basic multi-tenant Bare Metal as a Service. OpenNebula represents each NICo allocation as a Host and uses the NICo VMM and IM drivers to create, monitor, and delete bare metal instances through the NICo REST API. + +The integration is intended for environments where OpenNebula provides the cloud management, user, group, quota, and template controls, while NICo provides the bare metal capacity and the lifecycle operations for each instance. + +This guide focuses on the service integration model. For the complete driver attribute reference, see the [NICo Driver]({{% relref "product/operation_references/hypervisor_configuration/nico_driver" %}}) documentation. + +## Assumptions + +Before you start, make sure that: + +- OpenNebula is already installed and running. +- The NICo service is already deployed and reachable from the OpenNebula Front-end. +- The NICo VMM and IM drivers are installed in the OpenNebula Front-end. +- You have a NICo allocation ID for the capacity you want to expose through OpenNebula. +- You have the NICo API credentials and connection details required by your environment. +- The NICo VPC, VPC prefix, operating system, instance type, network security group, and SSH key group identifiers have been created in NICo. +- OpenNebula users, groups, and Virtual Data Centers (VDCs) are already planned for the tenants that will consume the service. + +## Integration Model + +The NICo integration maps OpenNebula objects to NICo resources as follows: + +| OpenNebula object | NICo resource | +| --- | --- | +| Host using the `nico` IM and VMM drivers | NICo allocation and API connection | +| VM template | Bare metal instance definition | +| VM | NICo bare metal instance | +| VM `DEPLOY_ID` | NICo instance UUID | +| NIC section in the VM template | NICo VPC prefix selection | + +In this model, the OpenNebula Host does not represent a physical hypervisor. It represents a NICo allocation that OpenNebula can consume. The NICo IM driver reports capacity from that allocation, and the NICo VMM driver performs the instance lifecycle operations. + +For multi-tenancy, create one or more service templates and publish them only to the groups or VDCs that should consume each NICo allocation. Use OpenNebula quotas to limit how many bare metal instances each tenant can deploy. + +## Create the NICo Host + +Create a dedicated Host that uses the NICo information manager and virtualization drivers: + +```shell +onehost create nico --im nico --vm nico +``` + +Update the Host template with the NICo connection details and the allocation that this Host represents. The required and optional Host attributes are described in the [NICo Driver]({{% relref "product/operation_references/hypervisor_configuration/nico_driver" %}}) reference. + +```shell +onehost update nico +``` + +After the next monitoring cycle, verify that OpenNebula can monitor the allocation: + +```shell +onehost show nico +``` + +If different tenants must consume different NICo allocations, create one OpenNebula Host per allocation and restrict the corresponding VM templates with `SCHED_REQUIREMENTS`. + +## Create a Tenant Network Placeholder + +NICo uses its own VPC and VPC prefix identifiers to attach the bare metal instance to the requested network. OpenNebula still requires a VM template `NIC` section, so create or reuse a Virtual Network that acts as the tenant-facing network object. + +The NICo driver reads `NICO_VPC_PREFIX_ID` from the first `NIC` section of the VM template. Define one VM template per tenant network, or clone the template and change the `NICO_VPC_PREFIX_ID` for each published service. + +## Create the Bare Metal Service Template + +Create a VM template that describes the NICo instance type, operating system, VPC, and networking attributes to use for the bare metal instance. Use the attribute set documented in the [NICo Driver]({{% relref "product/operation_references/hypervisor_configuration/nico_driver" %}}) reference. + +At the service level, pay special attention to the scheduling expression and the tenant network mapping. For example, pin a service template to the intended NICo Host: + +```default +NIC = [ + NETWORK = "nico-network", + NICO_VPC_PREFIX_ID = "vpc-prefix-id" +] + +SCHED_REQUIREMENTS = "ID = 123" +``` + +Use `CPU = "1"` and `MEMORY = "1"` in the VM template because each OpenNebula VM represents one NICo instance. Capacity control comes from the NICo allocation reported by the Host and from OpenNebula quotas, not from the CPU and memory values in the template. + +If a template can be placed on any NICo Host, schedule by VMM driver instead: + +```default +SCHED_REQUIREMENTS = "VM_MAD = \"nico\"" +``` + +For production services, pinning by Host ID is usually safer because it prevents a tenant template from consuming the wrong NICo allocation. + +## Publish the Service to Tenants + +Use OpenNebula groups, VDCs, and template permissions to expose the service to the right tenants. + +Recommended model: + +- Create a group for each tenant or service tier. +- Add the tenant users to the corresponding group. +- Create a VDC that includes the NICo Host, the tenant Virtual Network, and the service template. +- Publish only the VM templates that match the tenant entitlement. +- Apply VM quotas to limit how many bare metal instances each tenant can run. + +Example quota for a tenant group that can run up to two NICo bare metal instances: + +```shell +onegroup quota tenant-a +``` + +```default +VM = [ + RUNNING_VMS = "2" +] +``` + +This keeps the service multi-tenant at the OpenNebula layer while delegating the physical bare metal provisioning to NICo. + +## Instantiate and Operate Bare Metal Instances + +Tenants can instantiate the published service template from Sunstone or with the CLI: + +```shell +onetemplate instantiate nico-bare-metal --name tenant-a-bm-01 +``` + +OpenNebula sends the create request to NICo and stores the returned NICo instance UUID as the VM `DEPLOY_ID`. You can inspect the mapping with: + +```shell +onevm show tenant-a-bm-01 +``` + +Use standard OpenNebula lifecycle actions for tenant operations: + +- `onevm terminate` deletes the NICo instance. +- `onevm reboot` requests a NICo reboot. +- `onevm show` displays the monitored state and NICo attributes reported by the driver. + +During a NICo reboot request, OpenNebula keeps the VM in `RUNNING`. Check the monitored `NICO_STATUS` value to inspect transient NICo states such as `Rebooting`. + +## Validation Checklist + +After the integration is complete, validate the service with the following checks: + +1. The NICo Host is monitored successfully in OpenNebula. +2. The Host capacity matches the expected NICo allocation. +3. A tenant can see only the published bare metal service templates. +4. A tenant can instantiate a template and obtain a running NICo instance. +5. The OpenNebula VM `DEPLOY_ID` matches the NICo instance UUID. +6. Tenant quotas prevent deploying more instances than allowed. +7. Terminating the OpenNebula VM removes the corresponding NICo instance. + +## Troubleshooting + +- If the Host is in an error state, verify the NICo API endpoint, issuer URL, organization, client credentials, target scopes, and allocation ID. +- If instantiation fails before reaching NICo, check that the VM template includes `NICO_INSTANCE_TYPE_ID`, `NICO_OS_ID`, `NICO_VPC_ID`, a `NIC` section, and `NIC/NICO_VPC_PREFIX_ID`. +- If the VM is scheduled to the wrong infrastructure, tighten `SCHED_REQUIREMENTS` to the NICo Host ID. +- If tenants can see the wrong service templates, review template ownership, permissions, groups, and VDC membership. diff --git a/content/solutions/ai_factory_blueprints/overview.md b/content/solutions/ai_factory_blueprints/overview.md index 63f54b69..3b74b208 100644 --- a/content/solutions/ai_factory_blueprints/overview.md +++ b/content/solutions/ai_factory_blueprints/overview.md @@ -32,7 +32,13 @@ Configuring, deploying and validating a high-performance AI infrastructure using

-3. Perform Validation: As a prerequisite, you must have an AI Factory ready to be validated after completing the above installation procedures. These are the options to validate your AI Factory: +3. Integrate external infrastructure services when required: + * [Infrastructure Integration]({{% relref "solutions/ai_factory_blueprints/infrastructure_integration" %}}): Connect OpenNebula with services such as NVIDIA NICo. + * [Bare Metal as a Service with NICo]({{% relref "solutions/ai_factory_blueprints/infrastructure_integration/bare_metal_nico" %}}): Offer multi-tenant bare metal instances from an existing OpenNebula cloud. +
+
+ +4. Perform Validation: As a prerequisite, you must have an AI Factory ready to be validated after completing the above installation procedures. These are the options to validate your AI Factory: * [Direct AI execution]({{% relref "solutions/ai_factory_blueprints/direct_ai_execution" %}}): * [LLM Inferencing with vLLM]({{% relref "solutions/ai_factory_blueprints/direct_ai_execution/llm_inference_certification" %}}): Using vLLM with two different models and two model sizes, running across both H100 and L40S GPUs. @@ -43,4 +49,4 @@ Configuring, deploying and validating a high-performance AI infrastructure using * [Containerized AI Execution]({{% relref "solutions/ai_factory_blueprints/containerized_ai_execution/ai_ready_k8s" %}}): * [Deployment of AI-Ready Kubernetes]({{% relref "solutions/ai_factory_blueprints/containerized_ai_execution/ai_ready_k8s" %}}): Use H100 and L40S deployment to run Kubernetes. * [LLM Inferencing with NVIDIA Dynamo]({{% relref "solutions/ai_factory_blueprints/containerized_ai_execution/nvidia_dynamo" %}}): Integrating the GPU-powered Kubernetes cluster with the NVIDIA Dynamo Cloud Platform to provision and manage AI workloads through the Dynamo framework for your AI workloads on top of the NVIDIA Dynamo framework. - * [Scheduling with NVIDIA KAI Scheduler]({{% relref "solutions/ai_factory_blueprints/containerized_ai_execution/nvidia_kai_scheduler" %}}): Use the NVIDIA KAI Scheduler to share GPU resources across different workloads within the AI-ready Kubernetes cluster. \ No newline at end of file + * [Scheduling with NVIDIA KAI Scheduler]({{% relref "solutions/ai_factory_blueprints/containerized_ai_execution/nvidia_kai_scheduler" %}}): Use the NVIDIA KAI Scheduler to share GPU resources across different workloads within the AI-ready Kubernetes cluster.