Topology VIM setup

After the Topology creation (step described in Topology creation), VIMs must be added in order for NFVCL to be able to deploy VMs.

There are three types of VIMs currently supported by NFVCL:

Supported VIM Types
Name (Doc Link)	`vim_type` value	Description
OpenStack (OpenStack VIM)	`openstack`	https://www.openstack.org/
Proxmox (Proxmox VIM)	`proxmox`	https://proxmox.com/
External REST (External REST VIM)	`external_rest`	Provider REST Server

Every Blueprint that require VMs should be deployable on any VIM type if configured correctly. There are some limitation and known problems described in the dedicated VIM type documentation chapter.

Adding a VIM to the Topology

To create a new VIM in the Topology, you can use the POST /v1/topology/vim API endpoint.

Warning

The topology must be created before adding any VIM.

There are some fields that are common to all VIM types, described here:

name: Name of your vim
vim_url: API URL
vim_user: Username to access VIM
vim_password: Password to access VIM
vim_type: Any between the supported VIM types (see table above)
vim_timeout: Operations timeout, in second, if not provided default is 180
ssh_keys: A list of SSH public keys that will be injected in the VMs created on this VIM
networks: List with the names of the networks registered in the topology that are connected to this VIM.
areas: List of area id covered by this VIM, should not overlap with other VIMs, can be any integer value >= 1

OpenStack VIM

Example request body for OpenStack VIM creation:

{
  "name": "oslab",
  "vim_type": "openstack",
  "vim_url": "http://os-lab.maas:5000/v3",
  "vim_user": "user01",
  "vim_password": "password01",
  "vim_timeout": null,
  "ssh_keys": [
  ],
  "vim_openstack_parameters": {
    "region_name": "RegionOne",
    "project_name": "user01-project",
    "user_domain_name": "Default",
    "project_domain_name": "Default"
  },
  "config": {
    "insecure": true,
    "APIversion": "v3.3",
    "use_floating_ip": false
  },
  "networks": [
    "dmz-internal",
    "data-net"
  ],
  "routers": [],
  "areas": [
    1,
    2,
  ]
}

For Openstack there is field vim_openstack_parameters :

region_name
project_name: OpenStack project, visible from web-ui
user_domain_name
project_domain_name

The fields region_name, user_domain_name, project_domain_name must be set according to your Openstack configuration, if your Openstack use default values then you can avoid to set them and use default values set by NFVCL.

Warning

If NFVCL is running outside of the OpenStack network you neet to ensure that NFVCL is able to reach the VMs that it creates. If the VMs need a floating IP to be reachable, you need to set the use_floating_ip field in the config section to true.

Proxmox VIM

Example request body for Proxmox VIM creation:

{
  "name": "proxmoxtest",
  "vim_type": "proxmox",
  "vim_url": "192.168.17.100",
  "vim_user": "user01",
  "vim_password": "password01",
  "vim_timeout": null,
  "ssh_keys": [],
  "vim_proxmox_parameters": {
    "proxmox_realm": "pam",
    "proxmox_node": null,
    "proxmox_images_volume": "local",
    "proxmox_vm_volume": "local-lvm",
    "proxmox_token_name": "",
    "proxmox_token_value": "",
    "proxmox_otp_code": "",
    "proxmox_privilege_escalation": "sudo_without_password"
  },
  "config": {
    "insecure": true,
    "APIversion": "v3.3",
    "use_floating_ip": false
  },
  "networks": [],
  "routers": [],
  "areas": [
    100
  ]
}

Warning

The vim_url is currently the Proxmox IP and it is assumed that the API server is running on the default port. This is needed to also establish an SSH connection to the Proxmox host (see limitations below).

For Proxmox there is field vim_proxmox_parameters :

proxmox_realm: Authentication realm, only pam is supported since we also need SSH access
proxmox_node: Name of the node, visible from web-ui, can be left to null to auto-select the first node
proxmox_images_volume: Name of the storage where VM images are stored
proxmox_vm_volume: Name of the storage where VM disks will be created
proxmox_token_name:
proxmox_token_value:
proxmox_otp_code:
proxmox_privilege_escalation: Method used to escalate privilege for commands requiring root access, can be one of:
- none: The user is already root
- sudo_without_password: Use sudo without password (requires proper sudoers configuration)
proxmox_resource_pool: Name of the resource pool where you want to deploy the resources
proxmox_sdn_zone: Name of the sdn zone where the vnets needed to deploy the VMs are located. If not specified, NFVCL assumes there is one called nfvcl.

Limitations

Proxmox VE < 9.0.17

Proxmox VIM require that NFVCL has SSH access to the Proxmox host, this is needed to perform some operations that are not available through the Proxmox API. Therefore the vim_user must be a valid user for SSH access.
The SSH user must be root or a user with sudo privileges without password.
Only the pam authentication realm is supported since we need SSH access.

This limitations is due to the lack of qcow2 and cloud-init custom script upload from the Proxmox API, see the following issues:

Features

In Proxmox VE >= 9.0.17, the qcow2 and file upload has been added. NFVCL does not need anymore SSH access to the Proxmox host, this also allow the pve authentication realm. It’s now possible to use a non-administrator user. However, certain permissions must be assigned for NFVCL to work. NFVCL automatically determines which version of Proxmox it’s connecting to. This way, it knows whether it can use the new features or not.

PVE auth

The roles with associated privileges required by NFVCL:

NFVCL_VM: VM.Allocate, VM.Audit, VM.Backup, VM.Config.CDROM, VM.Config.CPU, VM.Config.Cloudinit, VM.Config.Disk, VM.Config.HWType, VM.Config.Memory, VM.Config.Network, VM.Config.Options, VM.GuestAgent.Audit, VM.GuestAgent.FileRead, VM.GuestAgent.FileSystemMgmt, VM.GuestAgent.FileWrite, VM.GuestAgent.Unrestricted, VM.PowerMgmt
NFVCL_Datastore: Datastore.AllocateSpace, Datastore.Allocate, Datastore.AllocateTemplate, Datastore.Audit
NFVCL_Sdn: SDN.Audit, SDN.Use, SDN.Allocate
NFVCL_Sys: Sys.AccessNetwork or Sys.Modify, Sys.Audit

The path with associated role required by NFVCL:

/vms -> NFVCL_VM
/storage/YOUR_STORAGE -> NFVCL_Datastore
/sdn -> NFVCL_Sdn
/nodes/YOUR_NODES -> NFVCL_Sys if Sys.AccessNetwork
/ -> NFVCL_Sys if Sys.Modify, Sys.Audit

To limit permissions and isolate user environments, you can use Resource Pools. Each user or user group can be associated with a resource pool, where they are the administrator. Users will not be able to see VMs in pools that don’t belong to them. The permissions required by NFVCL on storage do not allow for separation of environments between users. However, there are several systems that prevent users from accessing resources on storage that do not belong to them. The first method is to create storage in directory mode. The second, however, is only possible if you have Ceph available, because it allows you to create a pool for each user. Roles and paths with this system change as follows. NFVCL in two blueprints: UERanSim and Simple5G if they are not specified in the payload, it creates them. To limit permissions it is recommended to already provide all the networks in the creation payload.

NFVCL creates them in two blueprints: UERanSim and Simple5G. If they aren’t specified in the payload, it creates them. To limit permissions, it’s recommended to pre-provided all networks in the creation payload. It’s recommended to create an SDN zone per user or user group and create the necessary networks in each. Then, set that as the SDN zone to use in the topology.

The roles:

NFVCL_Datastore: Datastore.AllocateSpace, Datastore.Allocate, Datastore.AllocateTemplate, Datastore.Audit
NFVCL_Sdn: SDN.Audit, SDN.Use, SDN.Allocate
NFVCL_Sdn_USE: SDN.Use
NFVCL_Sys: Sys.AccessNetwork
NFVCL_Group: Group.Allocate

The path :

/storage/YOUR_STORAGE -> NFVCL_Datastore
/node/YOUR_NODE -> NFVCL_Sys
/sdn/zone/YOUR_ZONE -> NFVCL_Sdn
/sdn/localnetwork -> NFVCL_Sdn_USE
/pool/YOUR_POOL -> Administrator
/access/group -> NFVCL_Group

External REST VIM

This VIM type allows to connect to an external REST API server that will act as a VIM or as a proxy.

There is a built-in REST server in NFVCL that can be used as remote VIM, see Provider REST Server for more information.

Example request body for External REST VIM creation:

{
  "name": "extrestvim",
  "vim_type": "external_rest",
  "vim_url": "http://192.168.254.242:5003/v1",
  "vim_user": "",
  "vim_password": "",
  "vim_timeout": null,
  "ssh_keys": [],
  "vim_rest_parameters": {
    "remote_vim_name": "oslab",
    "local_agent_uuid": "eca604d4-626a-408e-bc54-a9ef11d421a0"
  },
  "config": {
    "insecure": false,
    "APIversion": "",
    "use_floating_ip": false
  },
  "networks": [],
  "routers": [],
  "areas": [
    1001
  ]
}

If the remote REST VIM requires authentication you can provide it in the vim_user and vim_password fields.

For Proxmox there is field vim_rest_parameters :

remote_vim_name: Name of the remote VIM registered on the REST server
local_agent_uuid: Name of the node, visible from web-ui, can be left to null to auto-select the first node

Warning

The local_agent_uuid is used to prevent a NFVCL instance from interacting with resources of another instance, this UUID MUST be different for each instance using the same remote REST server.

VM base images

To create VMs on a VIM, NFVCL will automatically download the required image from a given URL (That can be found in the blueprint source code). For most of the default blueprints, images will be downloaded from https://images.tnt-lab.unige.it/ so ensure that this URL is reachable from the VIM.