Skip to content

Services

All operations require authentication.

4 operationsv2/vrackServices/resource
View as Markdown (opens in a new tab)
Agent setup

List vRack ServicesProduction

GET
/v2/vrackServices/resource

Returns the vRack Services of the account, each with its requested and current configuration.

Query parameters

dedicatedServerInterface
string

Filter on a dedicatedServerInterface

iamTags
object

Filter resources on IAM tags

Headers

X-Pagination-Cursor
string

Pagination cursor

X-Pagination-Size
integer

Pagination size

Response

200VrackServicesWithIAM[]successful operation
checksum
read-only
string

Computed hash used to control concurrent modification requests. Here, it represents the current target specification value.

createdAt
read-only
stringdate-time

Date of the vRack Services delivery

currentState
read-only
VrackServicesCurrentState

Current configuration applied to the vRack Services

currentTasks
read-only
CurrentTask[]

Asynchronous operations ongoing on the vRack Services

iam
read-only
ResourceMetadata

IAM resource metadata

id
read-only
string

Unique identifier

resourceStatus
read-only
ResourceStatusEnum

Reflects the readiness of the vRack Services. A new target specification request will be accepted only in READY status.

ValuesCREATINGDELETINGERRORREADYUPDATING
targetSpec
read-only
VrackServicesTargetSpec

Last target specification of the vRack Services

updatedAt
read-only
stringdate-time

Date of the Last vRack Services update

Reads your token from $OVH_TOKEN

$ curl https://api.eu.ovhcloud.com/v2/vrackServices/resource \
  -H "authorization: Bearer $OVH_TOKEN"
ResponseExample
[ { "checksum": "string", "createdAt": "2024-01-01T12:00:00Z", "currentState": { "bgp": { "allowedPrefixes": { "ipv4": [ "192.0.2.0/24" ], "ipv6": [ "2001:41d0::/128" ] }, "bandwidth": 0, "bgpRange": [ { "cidr": "192.0.2.0/24", "clientPeers": [ null ], "infrastructurePeers": [ null ], "subnetCidr": "192.0.2.0/24" } ], "clientAsn": 0, "configurationStatus": { "reason": "MISSING_ALLOWED_PREFIX", "status": "DRAFT" }, "iam": { "displayName": "string", "id": "00000000-0000-0000-0000-000000000000", "state": "EXPIRED", "tags": { "key": "string" }, "urn": "string" }, "id": "string", "infrastructureAsn": 0 }, "configurationStatus": { "reason": "MISSING_VRACK_ASSOCIATION", "status": "DRAFT" }, "region": "string", "services": { "serviceRange": [ { "cidr": "192.0.2.0/24", "dhcp": { "dedicatedServerInterfaceAssociations": null, "displayName": null }, "dhcpConfigurationStatus": { "reason": null, "status": null }, "remainingIps": 0, "remainingReservedIps": 0, "serviceEndpoints": [ null ], "serviceEndpointsConfigurationStatus": { "reason": null, "status": null }, "subnetCidr": "192.0.2.0/24", "usedIps": 0, "usedReservedIps": 0 } ] }, "subnets": [ { "az": "string", "cidr": "192.0.2.0/24", "displayName": "string", "vlan": 0 } ], "vrackId": "string" }, "currentTasks": [ { "errors": [ { "message": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "link": "string", "status": "ERROR", "type": "string" } ], "iam": { "displayName": "string", "id": "00000000-0000-0000-0000-000000000000", "state": "EXPIRED", "tags": { "key": "string" }, "urn": "string" }, "id": "string", "resourceStatus": "CREATING", "targetSpec": { "bgp": { "allowedPrefixes": { "ipv4": [ "192.0.2.0/24" ], "ipv6": [ "2001:41d0::/128" ] }, "bgpRange": [ { "cidr": "192.0.2.0/24", "clientPeers": [ null ], "infrastructurePeers": [ null ], "subnetCidr": "192.0.2.0/24" } ], "clientAsn": 0, "infrastructureAsn": 0 }, "services": { "serviceRange": [ { "cidr": "192.0.2.0/24", "dhcp": { "dedicatedServerInterfaceAssociations": null, "displayName": null }, "serviceEndpoints": [ null ], "subnetCidr": "192.0.2.0/24" } ] }, "subnets": [ { "az": "string", "cidr": "192.0.2.0/24", "displayName": "string", "vlan": 0 } ] }, "updatedAt": "2024-01-01T12:00:00Z" }]

Get a vRack ServicesProduction

GET
/v2/vrackServices/resource/{vrackServicesId}

Returns the requested and current configuration of the vRack Services: region, associated vRack, subnets with their Service Endpoints, status and running tasks.

Path parameters

vrackServicesId
required
string

Vrack services ID

Response

200VrackServicesWithIAMsuccessful operation
checksum
read-only
string

Computed hash used to control concurrent modification requests. Here, it represents the current target specification value.

createdAt
read-only
stringdate-time

Date of the vRack Services delivery

currentState
read-only
VrackServicesCurrentState

Current configuration applied to the vRack Services

currentTasks
read-only
CurrentTask[]

Asynchronous operations ongoing on the vRack Services

iam
read-only
ResourceMetadata

IAM resource metadata

id
read-only
string

Unique identifier

resourceStatus
read-only
ResourceStatusEnum

Reflects the readiness of the vRack Services. A new target specification request will be accepted only in READY status.

ValuesCREATINGDELETINGERRORREADYUPDATING
targetSpec
read-only
VrackServicesTargetSpec

Last target specification of the vRack Services

updatedAt
read-only
stringdate-time

Date of the Last vRack Services update

404objectError 404 response

Example uses vrackServicesId = string

$ curl https://api.eu.ovhcloud.com/v2/vrackServices/resource/{vrackServicesId} \
  -H "authorization: Bearer $OVH_TOKEN"
ResponseExample
{ "checksum": "string", "createdAt": "2024-01-01T12:00:00Z", "currentState": { "bgp": { "allowedPrefixes": { "ipv4": [ "192.0.2.0/24" ], "ipv6": [ "2001:41d0::/128" ] }, "bandwidth": 0, "bgpRange": [ { "cidr": "192.0.2.0/24", "clientPeers": [ "192.0.2.0" ], "infrastructurePeers": [ "192.0.2.0" ], "subnetCidr": "192.0.2.0/24" } ], "clientAsn": 0, "configurationStatus": { "reason": "MISSING_ALLOWED_PREFIX", "status": "DRAFT" }, "iam": { "displayName": "string", "id": "00000000-0000-0000-0000-000000000000", "state": "EXPIRED", "tags": { "key": "string" }, "urn": "string" }, "id": "string", "infrastructureAsn": 0 }, "configurationStatus": { "reason": "MISSING_VRACK_ASSOCIATION", "status": "DRAFT" }, "region": "string", "services": { "serviceRange": [ { "cidr": "192.0.2.0/24", "dhcp": { "dedicatedServerInterfaceAssociations": [ null ], "displayName": "string" }, "dhcpConfigurationStatus": { "reason": "MISSING_DEDICATED_SERVER_INTERFACE_ASSOCIATIONS", "status": "DRAFT" }, "remainingIps": 0, "remainingReservedIps": 0, "serviceEndpoints": [ { "endpoints": null, "managedServiceURN": null } ], "serviceEndpointsConfigurationStatus": { "reason": "string", "status": "DRAFT" }, "subnetCidr": "192.0.2.0/24", "usedIps": 0, "usedReservedIps": 0 } ] }, "subnets": [ { "az": "string", "cidr": "192.0.2.0/24", "displayName": "string", "vlan": 0 } ], "vrackId": "string" }, "currentTasks": [ { "errors": [ { "message": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "link": "string", "status": "ERROR", "type": "string" } ], "iam": { "displayName": "string", "id": "00000000-0000-0000-0000-000000000000", "state": "EXPIRED", "tags": { "key": "string" }, "urn": "string" }, "id": "string", "resourceStatus": "CREATING", "targetSpec": { "bgp": { "allowedPrefixes": { "ipv4": [ "192.0.2.0/24" ], "ipv6": [ "2001:41d0::/128" ] }, "bgpRange": [ { "cidr": "192.0.2.0/24", "clientPeers": [ "192.0.2.0" ], "infrastructurePeers": [ "192.0.2.0" ], "subnetCidr": "192.0.2.0/24" } ], "clientAsn": 0, "infrastructureAsn": 0 }, "services": { "serviceRange": [ { "cidr": "192.0.2.0/24", "dhcp": { "dedicatedServerInterfaceAssociations": [ null ], "displayName": "string" }, "serviceEndpoints": [ { "managedServiceURN": null } ], "subnetCidr": "192.0.2.0/24" } ] }, "subnets": [ { "az": "string", "cidr": "192.0.2.0/24", "displayName": "string", "vlan": 0 } ] }, "updatedAt": "2024-01-01T12:00:00Z"}

Update a vRack ServicesProduction

PUT
/v2/vrackServices/resource/{vrackServicesId}

Beta: BGP (bgp) and DHCP/netboot (services.serviceRange[].dhcp) are Beta features: their behaviour and payload may still change.

Replaces the target specification of the vRack Services, subnets and Service Endpoints, and applies it asynchronously.

It is the unique route handling any update on the vRack Services configuration. It works as following:

  1. You define a new target specification in the request payload,
  2. If this specification is validated, you get the resource with updated targetSpec and checksum values in return,
  3. The request is processed by one or several asynchronous tasks that aims to reconciliate the currentState with the targetSpec

Asynchronous processing

  • To follow this processing, the VrackServices resource can be polled with GET /vrackServices/resource/{vrackServicesId}
    As soon as its resourceStatus is READY, the requested specification can be considered as applied to the vRack Services.
  • The checksum helps on detecting concurrency cases on update requests. If the polled checksum value differs from the one returned in response of your initial request, it means that processing of your request is completed and another request is being processed.
  • In case of processing error (that is resourceStatus in ERROR), the current vRack Services configuration is still active, but modification requests will be refused until the intervention of the support.
  • An overview on the asynchronous task(s) is available via the currentTasks attribute.
    More details on a task are provided by the route GET /vrackServices/resource/{vrackServicesId}/task/{taskId}

DHCP / netboot limits

  • Untagged subnet only (vlan: null): a DHCP block on a tagged subnet is rejected
  • Service range required: the DHCP block is declared on services.serviceRange[]
  • vRack association required to bind a dedicatedServerInterface
  • Maximum 200 dedicatedServerInterface associations per subnet
  • netboot is read-only, derived from the subnet VLAN: always true today, since only untagged subnets accept a DHCP block

Seamless configuration actions

The request can combine any of the following seamless actions (meaning there won't be any cut of the service while updating):

  • create a Subnet
  • delete a Subnet without any Service Endpoint
  • update a Subnet:
    • create one or several Service Endpoints
    • add or remove dedicatedServerInterface associations in its DHCP block

Note that a Subnet with several Service Endpoints can be created in the same payload

Not seamless configuration actions

The modification of the Subnet characteristics listed below will result in a service cut while processing the update as they are interpreted as the deletion of the existing Subnet and creation of a new Subnet with provided characteristics. The IPs that were given to the Managed Services will be reelected and may as a result change:

  • modifications on the Subnet ServiceRange
  • modifications on the Subnet Vlan
  • modifications on the Subnet CIDR

The embedded Service Endpoints will be also deleted and re-created which implies a flapping accessibility in the vRack for every related managed services.
Note that deleting a Subnet will also delete embedded Service Endpoints

Note that omitting dhcp on a Service Range that carries one WILL remove its DHCP/netboot configuration (netboot stops for every bound dedicatedServerInterface): always resend the dhcp block returned by GET.

The vrackId is a read-only attribute as the association vRack/vRackServices is handled by the vRack API

Path parameters

vrackServicesId
required
string

Vrack services ID

Request body (required)

checksum
required
string

Computed hash used to control concurrent modification requests. Here, it represents the target specification value the request is based on.

targetSpec
required
VrackServicesTargetSpec

Requested target specification

Response

200VrackServicessuccessful operation
checksum
read-only
string

Computed hash used to control concurrent modification requests. Here, it represents the current target specification value.

createdAt
read-only
stringdate-time

Date of the vRack Services delivery

currentState
read-only
VrackServicesCurrentState

Current configuration applied to the vRack Services

currentTasks
read-only
CurrentTask[]

Asynchronous operations ongoing on the vRack Services

id
read-only
string

Unique identifier

resourceStatus
read-only
ResourceStatusEnum

Reflects the readiness of the vRack Services. A new target specification request will be accepted only in READY status.

ValuesCREATINGDELETINGERRORREADYUPDATING
targetSpec
read-only
VrackServicesTargetSpec

Last target specification of the vRack Services

updatedAt
read-only
stringdate-time

Date of the Last vRack Services update

400objectError 400 response
404objectError 404 response
412objectError 412 response
423objectError 423 response

Example uses vrackServicesId = string

$ curl https://api.eu.ovhcloud.com/v2/vrackServices/resource/{vrackServicesId} \
  -H "authorization: Bearer $OVH_TOKEN"
ResponseExample
{ "checksum": "string", "createdAt": "2024-01-01T12:00:00Z", "currentState": { "bgp": { "allowedPrefixes": { "ipv4": [ "192.0.2.0/24" ], "ipv6": [ "2001:41d0::/128" ] }, "bandwidth": 0, "bgpRange": [ { "cidr": "192.0.2.0/24", "clientPeers": [ "192.0.2.0" ], "infrastructurePeers": [ "192.0.2.0" ], "subnetCidr": "192.0.2.0/24" } ], "clientAsn": 0, "configurationStatus": { "reason": "MISSING_ALLOWED_PREFIX", "status": "DRAFT" }, "iam": { "displayName": "string", "id": "00000000-0000-0000-0000-000000000000", "state": "EXPIRED", "tags": { "key": "string" }, "urn": "string" }, "id": "string", "infrastructureAsn": 0 }, "configurationStatus": { "reason": "MISSING_VRACK_ASSOCIATION", "status": "DRAFT" }, "region": "string", "services": { "serviceRange": [ { "cidr": "192.0.2.0/24", "dhcp": { "dedicatedServerInterfaceAssociations": [ null ], "displayName": "string" }, "dhcpConfigurationStatus": { "reason": "MISSING_DEDICATED_SERVER_INTERFACE_ASSOCIATIONS", "status": "DRAFT" }, "remainingIps": 0, "remainingReservedIps": 0, "serviceEndpoints": [ { "endpoints": null, "managedServiceURN": null } ], "serviceEndpointsConfigurationStatus": { "reason": "string", "status": "DRAFT" }, "subnetCidr": "192.0.2.0/24", "usedIps": 0, "usedReservedIps": 0 } ] }, "subnets": [ { "az": "string", "cidr": "192.0.2.0/24", "displayName": "string", "vlan": 0 } ], "vrackId": "string" }, "currentTasks": [ { "errors": [ { "message": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "link": "string", "status": "ERROR", "type": "string" } ], "id": "string", "resourceStatus": "CREATING", "targetSpec": { "bgp": { "allowedPrefixes": { "ipv4": [ "192.0.2.0/24" ], "ipv6": [ "2001:41d0::/128" ] }, "bgpRange": [ { "cidr": "192.0.2.0/24", "clientPeers": [ "192.0.2.0" ], "infrastructurePeers": [ "192.0.2.0" ], "subnetCidr": "192.0.2.0/24" } ], "clientAsn": 0, "infrastructureAsn": 0 }, "services": { "serviceRange": [ { "cidr": "192.0.2.0/24", "dhcp": { "dedicatedServerInterfaceAssociations": [ null ], "displayName": "string" }, "serviceEndpoints": [ { "managedServiceURN": null } ], "subnetCidr": "192.0.2.0/24" } ] }, "subnets": [ { "az": "string", "cidr": "192.0.2.0/24", "displayName": "string", "vlan": 0 } ] }, "updatedAt": "2024-01-01T12:00:00Z"}

List eligible server interfacesBeta

GET
/v2/vrackServices/resource/{vrackServicesId}/eligibleDedicatedServerInterfaces

Returns, by availability zone, the dedicated server interfaces that can be added to the vRack Services, with the server each one belongs to.

Path parameters

vrackServicesId
required
string

Vrack services ID

Headers

X-Pagination-Cursor
string

Pagination cursor

X-Pagination-Size
integer

Pagination size

Response

200EligibleDedicatedServerInterface[]successful operation
availabilityZone
read-only
string

The availabilityZone where the dedicatedServerInterfaces are located

dedicatedServerInterfaces
read-only
EligibleDedicatedServerInterfaceItem[]

List of eligible dedicatedServerInterfaces

400objectError 400 response
404objectError 404 response

Example uses vrackServicesId = string

$ curl https://api.eu.ovhcloud.com/v2/vrackServices/resource/{vrackServicesId}/eligibleDedicatedServerInterfaces \
  -H "authorization: Bearer $OVH_TOKEN"
ResponseExample
[ { "availabilityZone": "string", "dedicatedServerInterfaces": [ { "serverName": "string", "uuid": "string" } ] }]