API ReferenceOperating System

Create Operating System

View as Markdown
Create an Operating System for the org. Ownership is derived from the caller's role: - Tenant admin (`TENANT_ADMIN`): creates a Tenant-owned Operating System of any type (Image, iPXE, or Templated iPXE). - Provider admin (`PROVIDER_ADMIN`): may only create Provider-owned Operating Systems of type `Templated iPXE`. The `tenantId` field in the request body is deprecated; if provided, it must match the org's Tenant.

Authentication

AuthorizationBearer
``` export JWT_BEARER_TOKEN="<jwt-bearer-token>" # Example org name: "acme-inc export ORG_NAME=<org-name> # Use the JWT bearer token in your API request auth header: curl -v -X GET -H "Content-Type: application/json" -H "Authorization: Bearer $JWT_BEARER_TOKEN" https://nico-rest-api.nico.svc.cluster.local/v2/org/$ORG_NAME/nico/user/current ```

Path parameters

orgstringRequired
Name of the Org

Request

This endpoint expects an object.
namestringRequired2-256 characters
Name of the Operating System
descriptionstring or nullOptional
Optional description of the Operating System
siteIdslist of stringsOptional

Target Site for the Operating System. For image-based and Templated iPXE Operating Systems exactly one Site is required, even though this field is an array. The list is fixed at creation and cannot be changed on update. Not applicable to raw iPXE OS.

imageUrlstring or nullOptionalformat: "uri"

Original URL from which the Operating System image can be retrieved; required for image-based OS. Cannot be specified if ipxeScript is specified

imageShastring or nullOptional

SHA hash of the image file, required for image-based OS

imageAuthTypestring or nullOptional

Authentication type for image URL, if needed, e.g., basic/bearer/token; required if imageAuthToken is specified

imageAuthTokenstring or nullOptional
Auth token to retrieve the image from image URL, required if imageAuthType is specified
imageDiskstring or nullOptionalformat: "^(|smallest|/dev/(nvme[0-9]+n[0-9]+|[sv]d[a-z]+|disk/by-id/[^/\s]+))$"

Optional whole-disk target that will be overwritten with the image. Accepts smallest, /dev/nvme<controller>n<namespace>, /dev/sd<letters>, /dev/vd<letters>, or /dev/disk/by-id/<identifier>. smallest selects the smallest enumerated whole disk, preferring one with an EFI partition to break a size tie. Partition aliases ending in -part<digits> are rejected. When omitted, null, or empty on creation, the Site prefers a disk with an EFI partition, then falls back to /dev/nvme0n1 or /dev/sda.

rootFsIdstring or nullOptional

Root filesystem UUID; this or rootFsLabel is required for image-based OS

rootFsLabelstring or nullOptional

Root filesystem label; this or rootFsId is required for image-based OS

phoneHomeEnabledboolean or nullOptional
Indicates whether the Phone Home service should be enabled or disabled for Operating System
userDatastring or nullOptional

User data for the Operating System. Limited to 32768 bytes (32 KiB), measured on the effective value NICo stores rather than the text submitted. Operating System defaults are inherited first, and when phone-home is configured the document is re-serialized with a phone_home block added. Re-serialization normalizes indentation and can grow the document, so a request just under the limit may still be rejected.

allowOverridebooleanOptional
Indicates if the user data can be overridden at Instance creation time
ipxeTemplateIdstring or nullOptional

ID of the iPXE template to use; identifies a Templated iPXE Operating System. Mutually exclusive with ipxeScript and imageUrl.

ipxeTemplateParameterslist of objectsOptional

Parameters passed to the iPXE template (Templated iPXE only).

ipxeTemplateArtifactslist of objectsOptional

Artifacts (kernel, initrd, ISO, …) for the iPXE OS definition (Templated iPXE only).

infrastructureProviderIdstring or nullOptionalformat: "uuid"Deprecated

Deprecated: Infrastructure Provider is now inferred from org membership.

tenantIdstring or nullOptionalformat: "uuid"Deprecated

Deprecated: Tenant is now inferred from org membership.

ipxeScriptstring or nullOptionalDeprecated

Deprecated: raw iPXE Operating Systems are superseded by Templated iPXE (ipxeTemplateId). iPXE script or URL, only applicable for iPXE-based OS. Cannot be specified if imageUrl is specified.

isCloudInitbooleanOptionalDeprecated

Deprecated and ignored: whether the Operating System is cloud-init based. Value now derived from userData.

Response

Created
idstringOptionalRead-onlyformat: "uuid"
ID of the Operating System
namestringOptional2-256 characters
Name of the Operating System
descriptionstring or nullOptional
Optional description of the Operating System
infrastructureProviderIdstring or nullOptionalformat: "uuid"
Specified if a Provider owns the Operating System
tenantIdstring or nullOptionalformat: "uuid"
Specified if a Tenant owns the Operating System
typeenumOptional
Type of the Operating System
imageUrlstring or nullOptionalformat: "uri"
Original URL from which the Operating System image can be retrieved
imageShastring or nullOptional

SHA hash of the image file, only present for image-based OS

imageAuthTypestring or nullOptional
Authentication type for image URL, e.g., 'Basic' or 'Bearer'
imageAuthTokenstring or nullOptional
Auth token to retrieve the image from image URL
imageDiskstring or nullOptionalformat: "^(|smallest|/dev/(nvme[0-9]+n[0-9]+|[sv]d[a-z]+|disk/by-id/[^/\s]+))$"

Whole-disk target that will be overwritten with the image. Accepts smallest, /dev/nvme<controller>n<namespace>, /dev/sd<letters>, /dev/vd<letters>, or /dev/disk/by-id/<identifier>. smallest selects the smallest enumerated whole disk, preferring one with an EFI partition to break a size tie. Partition aliases ending in -part<digits> are rejected. An empty stored value means the Site prefers a disk with an EFI partition, then falls back to /dev/nvme0n1 or /dev/sda.

rootFsIdstring or nullOptional

Root filesystem UUID, only applicable for image-based Operating System

rootFsLabelstring or nullOptional

Root filesystem label, only applicable for image-based Operating System

ipxeScriptstring or nullOptional

iPXE script or URL, only applicable for iPXE-based Operating System

ipxeTemplateIdstring or nullOptional
ID of the iPXE template used, only present for Templated iPXE Operating System
ipxeTemplateParameterslist of objectsOptional

Parameters passed to the iPXE template (Templated iPXE only)

ipxeTemplateArtifactslist of objectsOptional

Artifacts for the iPXE OS definition (Templated iPXE only). authToken is redacted.

userDatastring or nullOptional
User data for the Operating System
isCloudInitbooleanOptional

Whether the Operating System is cloud-init based; true if there is non-empty userData, false otherwise.

phoneHomeEnabledbooleanOptional
Indicates whether the Phone Home service should be enabled or disabled for Operating System
isActivebooleanOptional
Indicates if the Operating System is active
deactivationNotestring or nullOptional
Optional deactivation note if OS is inactive
allowOverridebooleanOptional
Indicates if the user data can be overridden at Instance creation time
siteAssociationslist of objectsOptional
Sites the Operating System is synced to
statusenumOptional
Status of the Operating System
statusHistorylist of objectsOptional
History of status changes over time
createddatetimeOptionalRead-only

Date/time when the Operating System was created

updateddatetimeOptionalRead-only

Date/time when the Operating System was updated

Errors

400
Bad Request Error
403
Forbidden Error