Skip to content

VPN gateways

All operations require authentication.

5 operationsv2/publicCloud/project
View as Markdown (opens in a new tab)
Agent setup

List VPN gatewaysAlpha

GET
/v2/publicCloud/project/{projectId}/vpn/gateway

Returns the VPN gateways of the project, in every region.

Path parameters

projectId
required
string

Project ID

Headers

X-Pagination-Cursor
string

Pagination cursor

X-Pagination-Size
integer

Pagination size

Response

200Gateway[]successful operation
checksum
read-only
string

Hash of the current target specification. Send it back in the update payload to detect concurrent changes.

createdAt
read-only
stringdate-time

Date and time the VPN gateway was created

currentState
read-only
GatewayCurrentState

Observed state of the VPN gateway. Null while the VPN gateway is being created.

currentTasks
read-only
CurrentTask[]

Asynchronous operations ongoing on the VPN gateway

id
read-only
stringuuid

Unique identifier of the VPN gateway

resourceStatus
read-only
ResourceStatusEnum

Readiness of the VPN gateway: whether its observed state has converged to its target specification

ValuesCREATINGCREATION_PLANNEDDELETINGERROROUT_OF_SYNCREADYSUSPENDEDUNKNOWNUPDATING
targetSpec
read-only
GatewayTargetSpec

Last target specification requested for the VPN gateway

updatedAt
read-only
stringdate-time

Date and time the VPN gateway was last updated

Example uses projectId = string

$ curl https://api.eu.ovhcloud.com/v2/publicCloud/project/{projectId}/vpn/gateway \
  -H "authorization: Bearer $OVH_TOKEN"
ResponseExample
[ { "checksum": "string", "createdAt": "2024-01-01T12:00:00Z", "currentState": { "description": "string", "externalGateway": { "enabled": true }, "externalIpv4": "192.0.2.0", "externalIpv6": "192.0.2.0", "location": { "region": "string" }, "name": "string", "operatingStatus": "DISABLED", "provisioningStatus": "ACTIVE", "subnets": [ { "id": "00000000-0000-0000-0000-000000000000", "ip": "192.0.2.0", "network": { "id": "00000000-0000-0000-0000-000000000000" }, "status": "CREATING" } ] }, "currentTasks": [ { "errors": [ { "message": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "link": "string", "status": "ERROR", "type": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "resourceStatus": "CREATING", "targetSpec": { "description": "string", "externalGateway": { "enabled": true }, "location": { "region": "string" }, "name": "string", "subnets": [ { "id": "00000000-0000-0000-0000-000000000000" } ] }, "updatedAt": "2024-01-01T12:00:00Z" }]

Create a VPN gatewayAlpha

POST
/v2/publicCloud/project/{projectId}/vpn/gateway

Creates a VPN gateway: a router dedicated to IPsec, running on a managed instance. When targetSpec.externalGateway.enabled is true, it gets its public addresses automatically. It is plugged into the subnets of targetSpec.subnets. Creation is asynchronous: follow resourceStatus and currentTasks, then currentState.externalIpv4 and externalIpv6 for the addresses to give to the peers.

Path parameters

projectId
required
string

Project ID

Request body (required)

targetSpec
required
GatewayTargetSpec

Desired specification of the VPN gateway to create

Response

200Gatewaysuccessful operation
checksum
read-only
string

Hash of the current target specification. Send it back in the update payload to detect concurrent changes.

createdAt
read-only
stringdate-time

Date and time the VPN gateway was created

currentState
read-only
GatewayCurrentState

Observed state of the VPN gateway. Null while the VPN gateway is being created.

currentTasks
read-only
CurrentTask[]

Asynchronous operations ongoing on the VPN gateway

id
read-only
stringuuid

Unique identifier of the VPN gateway

resourceStatus
read-only
ResourceStatusEnum

Readiness of the VPN gateway: whether its observed state has converged to its target specification

ValuesCREATINGCREATION_PLANNEDDELETINGERROROUT_OF_SYNCREADYSUSPENDEDUNKNOWNUPDATING
targetSpec
read-only
GatewayTargetSpec

Last target specification requested for the VPN gateway

updatedAt
read-only
stringdate-time

Date and time the VPN gateway was last updated

400objectError 400 response
403objectError 403 response
404objectError 404 response
409objectError 409 response

Example uses projectId = string

$ curl https://api.eu.ovhcloud.com/v2/publicCloud/project/{projectId}/vpn/gateway \
  -H "authorization: Bearer $OVH_TOKEN"
ResponseExample
{ "checksum": "string", "createdAt": "2024-01-01T12:00:00Z", "currentState": { "description": "string", "externalGateway": { "enabled": true }, "externalIpv4": "192.0.2.0", "externalIpv6": "192.0.2.0", "location": { "region": "string" }, "name": "string", "operatingStatus": "DISABLED", "provisioningStatus": "ACTIVE", "subnets": [ { "id": "00000000-0000-0000-0000-000000000000", "ip": "192.0.2.0", "network": { "id": "00000000-0000-0000-0000-000000000000" }, "status": "CREATING" } ] }, "currentTasks": [ { "errors": [ { "message": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "link": "string", "status": "ERROR", "type": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "resourceStatus": "CREATING", "targetSpec": { "description": "string", "externalGateway": { "enabled": true }, "location": { "region": "string" }, "name": "string", "subnets": [ { "id": "00000000-0000-0000-0000-000000000000" } ] }, "updatedAt": "2024-01-01T12:00:00Z"}

Get a VPN gatewayAlpha

GET
/v2/publicCloud/project/{projectId}/vpn/gateway/{gatewayId}

Returns the VPN gateway and its observed state.

Path parameters

gatewayId
required
stringuuid

Gateway ID

projectId
required
string

Project ID

Response

200Gatewaysuccessful operation
checksum
read-only
string

Hash of the current target specification. Send it back in the update payload to detect concurrent changes.

createdAt
read-only
stringdate-time

Date and time the VPN gateway was created

currentState
read-only
GatewayCurrentState

Observed state of the VPN gateway. Null while the VPN gateway is being created.

currentTasks
read-only
CurrentTask[]

Asynchronous operations ongoing on the VPN gateway

id
read-only
stringuuid

Unique identifier of the VPN gateway

resourceStatus
read-only
ResourceStatusEnum

Readiness of the VPN gateway: whether its observed state has converged to its target specification

ValuesCREATINGCREATION_PLANNEDDELETINGERROROUT_OF_SYNCREADYSUSPENDEDUNKNOWNUPDATING
targetSpec
read-only
GatewayTargetSpec

Last target specification requested for the VPN gateway

updatedAt
read-only
stringdate-time

Date and time the VPN gateway was last updated

404objectError 404 response

Example uses gatewayId = 00000000-0000-0000-0000-000000000000, projectId = string

$ curl https://api.eu.ovhcloud.com/v2/publicCloud/project/{projectId}/vpn/gateway/{gatewayId} \
  -H "authorization: Bearer $OVH_TOKEN"
ResponseExample
{ "checksum": "string", "createdAt": "2024-01-01T12:00:00Z", "currentState": { "description": "string", "externalGateway": { "enabled": true }, "externalIpv4": "192.0.2.0", "externalIpv6": "192.0.2.0", "location": { "region": "string" }, "name": "string", "operatingStatus": "DISABLED", "provisioningStatus": "ACTIVE", "subnets": [ { "id": "00000000-0000-0000-0000-000000000000", "ip": "192.0.2.0", "network": { "id": "00000000-0000-0000-0000-000000000000" }, "status": "CREATING" } ] }, "currentTasks": [ { "errors": [ { "message": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "link": "string", "status": "ERROR", "type": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "resourceStatus": "CREATING", "targetSpec": { "description": "string", "externalGateway": { "enabled": true }, "location": { "region": "string" }, "name": "string", "subnets": [ { "id": "00000000-0000-0000-0000-000000000000" } ] }, "updatedAt": "2024-01-01T12:00:00Z"}

Update a VPN gatewayAlpha

PUT
/v2/publicCloud/project/{projectId}/vpn/gateway/{gatewayId}

The target specification replaces the previous one as a whole: a field left null goes back to its default. Send the checksum of the last GET to reject the update with a checksum mismatch when someone changed the resource in between. Subnets added to targetSpec.subnets are plugged and subnets removed are unplugged, which is asynchronous: follow resourceStatus and currentState.subnets. Likewise, setting targetSpec.externalGateway.enabled to true attaches the VPN gateway to the external network: follow resourceStatus. Once enabled, it cannot be disabled: create another VPN gateway instead. Refused while the VPN gateway is being created, updated or deleted: follow its resourceStatus and retry once it is READY or ERROR.

Path parameters

gatewayId
required
stringuuid

Gateway ID

projectId
required
string

Project ID

Request body (required)

checksum
string

Optional concurrency-control checksum. When supplied, it must match the resource's current checksum or the request is rejected with a 409 checksum-mismatch conflict. When omitted or empty, the concurrency check is skipped and the write is forced (last-write-wins).

targetSpec
required
GatewayUpdateTargetSpec

Desired specification of the VPN gateway. It replaces the previous one as a whole.

Response

200Gatewaysuccessful operation
checksum
read-only
string

Hash of the current target specification. Send it back in the update payload to detect concurrent changes.

createdAt
read-only
stringdate-time

Date and time the VPN gateway was created

currentState
read-only
GatewayCurrentState

Observed state of the VPN gateway. Null while the VPN gateway is being created.

currentTasks
read-only
CurrentTask[]

Asynchronous operations ongoing on the VPN gateway

id
read-only
stringuuid

Unique identifier of the VPN gateway

resourceStatus
read-only
ResourceStatusEnum

Readiness of the VPN gateway: whether its observed state has converged to its target specification

ValuesCREATINGCREATION_PLANNEDDELETINGERROROUT_OF_SYNCREADYSUSPENDEDUNKNOWNUPDATING
targetSpec
read-only
GatewayTargetSpec

Last target specification requested for the VPN gateway

updatedAt
read-only
stringdate-time

Date and time the VPN gateway was last updated

400objectError 400 response
404objectError 404 response
409objectError 409 response

Example uses gatewayId = 00000000-0000-0000-0000-000000000000, projectId = string

$ curl https://api.eu.ovhcloud.com/v2/publicCloud/project/{projectId}/vpn/gateway/{gatewayId} \
  -H "authorization: Bearer $OVH_TOKEN"
ResponseExample
{ "checksum": "string", "createdAt": "2024-01-01T12:00:00Z", "currentState": { "description": "string", "externalGateway": { "enabled": true }, "externalIpv4": "192.0.2.0", "externalIpv6": "192.0.2.0", "location": { "region": "string" }, "name": "string", "operatingStatus": "DISABLED", "provisioningStatus": "ACTIVE", "subnets": [ { "id": "00000000-0000-0000-0000-000000000000", "ip": "192.0.2.0", "network": { "id": "00000000-0000-0000-0000-000000000000" }, "status": "CREATING" } ] }, "currentTasks": [ { "errors": [ { "message": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "link": "string", "status": "ERROR", "type": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "resourceStatus": "CREATING", "targetSpec": { "description": "string", "externalGateway": { "enabled": true }, "location": { "region": "string" }, "name": "string", "subnets": [ { "id": "00000000-0000-0000-0000-000000000000" } ] }, "updatedAt": "2024-01-01T12:00:00Z"}

Delete a VPN gatewayAlpha

DELETE
/v2/publicCloud/project/{projectId}/vpn/gateway/{gatewayId}

Deletes the VPN gateway, with its IPsec connections and their tunnels, and releases its public addresses. Refused while the VPN gateway is being created, updated or deleted: follow its resourceStatus and retry once it is READY or ERROR. Deletion is asynchronous: the VPN gateway stays listed with resourceStatus DELETING until it is gone.

Path parameters

gatewayId
required
stringuuid

Gateway ID

projectId
required
string

Project ID

Response

200Gatewaysuccessful operation
checksum
read-only
string

Hash of the current target specification. Send it back in the update payload to detect concurrent changes.

createdAt
read-only
stringdate-time

Date and time the VPN gateway was created

currentState
read-only
GatewayCurrentState

Observed state of the VPN gateway. Null while the VPN gateway is being created.

currentTasks
read-only
CurrentTask[]

Asynchronous operations ongoing on the VPN gateway

id
read-only
stringuuid

Unique identifier of the VPN gateway

resourceStatus
read-only
ResourceStatusEnum

Readiness of the VPN gateway: whether its observed state has converged to its target specification

ValuesCREATINGCREATION_PLANNEDDELETINGERROROUT_OF_SYNCREADYSUSPENDEDUNKNOWNUPDATING
targetSpec
read-only
GatewayTargetSpec

Last target specification requested for the VPN gateway

updatedAt
read-only
stringdate-time

Date and time the VPN gateway was last updated

404objectError 404 response
409objectError 409 response

Example uses gatewayId = 00000000-0000-0000-0000-000000000000, projectId = string

$ curl https://api.eu.ovhcloud.com/v2/publicCloud/project/{projectId}/vpn/gateway/{gatewayId} \
  -H "authorization: Bearer $OVH_TOKEN"
ResponseExample
{ "checksum": "string", "createdAt": "2024-01-01T12:00:00Z", "currentState": { "description": "string", "externalGateway": { "enabled": true }, "externalIpv4": "192.0.2.0", "externalIpv6": "192.0.2.0", "location": { "region": "string" }, "name": "string", "operatingStatus": "DISABLED", "provisioningStatus": "ACTIVE", "subnets": [ { "id": "00000000-0000-0000-0000-000000000000", "ip": "192.0.2.0", "network": { "id": "00000000-0000-0000-0000-000000000000" }, "status": "CREATING" } ] }, "currentTasks": [ { "errors": [ { "message": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "link": "string", "status": "ERROR", "type": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "resourceStatus": "CREATING", "targetSpec": { "description": "string", "externalGateway": { "enabled": true }, "location": { "region": "string" }, "name": "string", "subnets": [ { "id": "00000000-0000-0000-0000-000000000000" } ] }, "updatedAt": "2024-01-01T12:00:00Z"}