Updating to the 2024-04-30
version (VPN gateway connection)
As described in the VPC API reference versioning policy, most changes to the VPC APIs are fully backward compatible and are made available to all clients, regardless of
the API version the client requests. However, the 2024-04-30
release of the VPC API necessitated incompatible changes in support of VPN gateway connections.
Before you adopt the release version 2024-04-30
or later, review the changes described in this migration guidance that might require you to update your client.
Changed VPN gateway connection properties
The following VPN gateway connection properties have changed for API requests that use a version
query parameter of 2024-04-30
or later.
When creating a connection for a VPN gateway (POST /vpn_gateways/{vpn_gateway_id}/connections
):
Old property | New property |
---|---|
peer_address |
peer.address |
peer_cidrs |
peer.cidrs |
local_cidrs |
local.cidrs |
When updating a VPN gateway connection (PATCH /vpn_gateways/{vpn_gateway_id}/connections/{id}
):
Old property | New property |
---|---|
peer_address |
peer.address |
When making the following requests for policy-based VPN gateways, the properties have changed in the response:
- Creating (
POST /vpn_gateways/{vpn_gateway_id}/connections
) - Retrieving (
GET /vpn_gateways/{vpn_gateway_id}/connections/{id}
) - Updating a VPN gateway connection (
PATCH /vpn_gateways/{vpn_gateway_id}/connections/{id}
) - Listing all connections of a VPN gateway (
GET /vpn_gateways/{vpn_gateway_id}/connections
) - Listing all VPN gateway connections that use a specified IKE policy (
GET /ike_policies/{id}/connections
) - Listing all VPN gateway connections that use a specified IPsec policy (
GET /ipsec_policies/{id}/connections
)
Old property | New property |
---|---|
local_cidrs |
local.cidrs |
peer_cidrs |
peer.cidrs |
peer_address |
peer.address or peer.fqdn (described below) |
Property peer_address
is replaced by peer.address
or peer.fqdn
, depending on whether an IPv4 address or a FQDN was used to specify the peer when the connection was created. Update your code to check peer.type
in the response. If peer.type
is address
, then the response has peer.address
. If peer.type
is fqdn
, then the response has peer.fqdn
.
If peer.fqdn
was specified when the connection was created, and a version
query parameter of 2024-04-29
or earlier is specified, peer_address
will have the IP address associated with peer.fqdn
.
Old VPN gateway connection properties and methods remain supported for API requests that use a version
query parameter of 2024-04-29
or earlier.
Changed VPN gateway connection API paths
The following table lists the methods and their changed paths for API requests that use a version
query parameter of 2024-04-30
or later.
Method | Old path | New path |
---|---|---|
GET |
/vpn_gateways/{vpn_gateway_id}/connections/{id}/local_cidrs |
/vpn_gateways/{vpn_gateway_id}/connections/{id}/local/cidrs |
GET |
/vpn_gateways/{vpn_gateway_id}/connections/{id}/peer_cidrs |
/vpn_gateways/{vpn_gateway_id}/connections/{id}/peer/cidrs |
DELETE |
/vpn_gateways/{vpn_gateway_id}/connections/{id}/local_cidrs/{cidr_prefix}/{prefix_length} |
/vpn_gateways/{vpn_gateway_id}/connections/{id}/local/cidrs/{cidr} |
GET |
/vpn_gateways/{vpn_gateway_id}/connections/{id}/local_cidrs/{cidr_prefix}/{prefix_length} |
/vpn_gateways/{vpn_gateway_id}/connections/{id}/local/cidrs/{cidr} |
PUT |
/vpn_gateways/{vpn_gateway_id}/connections/{id}/local_cidrs/{cidr_prefix}/{prefix_length} |
/vpn_gateways/{vpn_gateway_id}/connections/{id}/local/cidrs/{cidr} |
DELETE |
/vpn_gateways/{vpn_gateway_id}/connections/{id}/peer_cidrs/{cidr_prefix}/{prefix_length} |
/vpn_gateways/{vpn_gateway_id}/connections/{id}/peer/cidrs/{cidr} |
GET |
/vpn_gateways/{vpn_gateway_id}/connections/{id}/peer_cidrs/{cidr_prefix}/{prefix_length} |
/vpn_gateways/{vpn_gateway_id}/connections/{id}/peer/cidrs/{cidr} |
PUT |
/vpn_gateways/{vpn_gateway_id}/connections/{id}/peer_cidrs/{cidr_prefix}/{prefix_length} |
/vpn_gateways/{vpn_gateway_id}/connections/{id}/peer/cidrs/{cidr} |
Changed HTTP response codes when setting VPN gateway connection CIDRs
When setting a local CIDR or setting a peer CIDR on a VPN gateway connection, the response now includes
a 201
HTTP success code if the CIDR was successfully set or a 204
HTTP success code if the CIDR is already set.
Action needed
Before you specify the version
query parameter of 2024-04-30
or later, follow these actions to avoid regressions in client functionality.
If your clients continue to specify version 2023-04-29
or earlier, no changes are required.
Client migration
Before you migrate a client to API version 2024-04-30
or later, review your code that uses the following methods:
POST /vpn_gateways/{vpn_gateway_id}/connections
PATCH /vpn_gateways/{vpn_gateway_id}/connections/{id}
GET /vpn_gateways/{vpn_gateway_id}/connections
GET /vpn_gateways/{vpn_gateway_id}/connections/{id}
GET /vpn_gateways/{vpn_gateway_id}/connections/{id}/local_cidrs
DELETE /vpn_gateways/{vpn_gateway_id}/connections/{id}/local_cidrs/{cidr_prefix}/{prefix_length}
GET /vpn_gateways/{vpn_gateway_id}/connections/{id}/local_cidrs/{cidr_prefix}/{prefix_length}
PUT /vpn_gateways/{vpn_gateway_id}/connections/{id}/local_cidrs/{cidr_prefix}/{prefix_length}
GET /vpn_gateways/{vpn_gateway_id}/connections/{id}/peer_cidrs
DELETE /vpn_gateways/{vpn_gateway_id}/connections/{id}/peer_cidrs/{cidr_prefix}/{prefix_length}
GET /vpn_gateways/{vpn_gateway_id}/connections/{id}/peer_cidrs/{cidr_prefix}/{prefix_length}
PUT /vpn_gateways/{vpn_gateway_id}/connections/{id}/peer_cidrs/{cidr_prefix}/{prefix_length}
GET /ike_policies/{id}/connections
GET /ipsec_policies/{id}/connections
Review the changes that were announced in the API change log, and verify that your code adopts these changes in a manner that is appropriate for your programming language.
Examples
These examples compare differences between before and after the 2024-04-30
versioned change.
Creating a VPN connection
The following example uses API version 2024-04-29
or earlier to create a VPN connection. The -d
option specifies the peer_address
, local_cidrs
, and peer_cidrs
properties.
curl -X POST "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections?version=2024-04-29&generation=2"
-H "Authorization: $iam_token"
-d '{
"name": "my-vpn-connection-1",
"psk": "lkj14b1oi0alcniejkso",
"peer_address": "1.2.3.4",
"local_cidrs": ["192.168.0.0/24"],
"peer_cidrs": ["192.168.210.0/24"]
}'
The following example uses API version 2024-04-30
or later to create a VPN connection. The -d
option specifies the peer.address
, local.cidrs
, and peer.cidrs
properties.
curl -X POST "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections?version=2024-04-30&generation=2"
-H "Authorization: $iam_token"
-d '{
"name": "my-vpn-connection-1",
"psk": "lkj14b1oi0alcniejkso",
"local": {
"cidrs": ["192.168.0.0/24"]
},
"peer": {
"cidrs": ["192.168.210.0/24"],
"address": "1.2.3.4"
}
}'
Updating a VPN connection
The following example uses API version 2024-04-29
or earlier to update a VPN connection. The -d
option specifies the peer_address
property.
curl -X PATCH "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$id?version=2024-04-29&generation=2"
-H "Authorization: $iam_token"
-d '{
"peer_address": "1.2.3.4"
}'
The following example uses API version 2024-04-30
or later to update a VPN connection. The -d
option specifies the peer.address
property.
curl -X PATCH "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$id?version=2024-04-30&generation=2"
-H "Authorization: $iam_token"
-d '{
"peer": {
"address": "1.2.3.4"
}
}'
Listing a VPN connection
The following example uses API version 2024-04-29
or earlier to list a VPN connection.
curl -X GET "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections?version=2024-04-29&generation=2"
-H "Authorization: $iam_token"
The response includes the peer_address
, local_cidrs
, and peer_cidrs
properties:
{
"connections": [
{
"admin_state_up": true,
"authentication_mode": "psk",
"created_at": "2018-12-13T19:40:12.124082Z",
"dead_peer_detection": {
"action": "none",
"interval": 15,
"timeout": 30
},
"href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/a7d258d5-be1e-491d-83db-526d8d9a2ce9/connections/52f69dc3-6a5c-4bcf-b264-e7fae279b15c",
"id": "52f69dc3-6a5c-4bcf-b264-e7fae279b15c",
"local_cidrs": [
"192.0.2.50/24"
],
"mode": "policy",
"name": "my-vpn-connection-1",
"peer_address": "192.0.2.5",
"peer_cidrs": [
"192.0.2.40/24"
],
"psk": "lkj14b1oi0alcniejkso",
"resource_type": "vpn_gateway_connection",
"status": "down",
"status_reasons": []
},
{
"admin_state_up": true,
"authentication_mode": "psk",
"created_at": "2018-12-13T19:39:47.938464Z",
"dead_peer_detection": {
"action": "none",
"interval": 15,
"timeout": 30
},
"href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/a7d258d5-be1e-491d-83db-526d8d9a2ce9/connections/b67efb2c-bd17-457d-be8e-7b46404062dc",
"id": "b67efb2c-bd17-457d-be8e-7b46404062dc",
"ike_policy": {
"href": "https://us-south.iaas.cloud.ibm.com/v1/ike_policies/e98f46a3-1e4e-4195-b4e5-b8155192689d",
"id": "e98f46a3-1e4e-4195-b4e5-b8155192689d",
"name": "my-ike-policy",
"resource_type": "ike_policy"
},
"ipsec_policy": {
"href": "https://us-south.iaas.cloud.ibm.com/v1/ipsec_policies/43c2f663-3960-4289-9253-f6eab23a6cd7",
"id": "43c2f663-3960-4289-9253-f6eab23a6cd7",
"name": "my-ipsec-policy",
"resource_type": "ipsec_policy"
},
"local_cidrs": [
"192.0.2.50/24"
],
"mode": "policy",
"name": "my-vpn-connection-2",
"peer_address": "192.0.2.5",
"peer_cidrs": [
"192.0.2.40/24"
],
"psk": "lkj14b1oi0alcniejkso",
"resource_type": "vpn_gateway_connection",
"status": "down",
"status_reasons": []
}
]
}
The following example uses API version 2024-04-30
or later to list a VPN connection.
curl -X GET "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections?version=2024-04-30&generation=2"
-H "Authorization: $iam_token"
The response includes the peer.address
, local.cidrs
, and peer.cidrs
properties:
{
"connections": [
{
"admin_state_up": true,
"authentication_mode": "psk",
"created_at": "2018-12-13T19:40:12.124082Z",
"dead_peer_detection": {
"action": "none",
"interval": 15,
"timeout": 30
},
"establish_mode": "peer_only",
"href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/a7d258d5-be1e-491d-83db-526d8d9a2ce9/connections/52f69dc3-6a5c-4bcf-b264-e7fae279b15c",
"id": "52f69dc3-6a5c-4bcf-b264-e7fae279b15c",
"local": {
"cidrs": [
"192.0.2.0/24"
],
"ike_identities": [
{
"type": "ipv4_address",
"value": "192.0.2.4"
}
]
},
"mode": "policy",
"name": "my-vpn-connection-1",
"peer": {
"address": "192.0.2.5",
"cidrs": [
"192.0.3.0/24"
],
"ike_identity": {
"type": "ipv4_address",
"value": "192.0.2.5"
},
"type": "address"
},
"psk": "lkj14b1oi0alcniejkso",
"resource_type": "vpn_gateway_connection",
"status": "down",
"status_reasons": []
},
{
"admin_state_up": true,
"authentication_mode": "psk",
"created_at": "2018-12-13T19:39:47.938464Z",
"dead_peer_detection": {
"action": "none",
"interval": 15,
"timeout": 30
},
"establish_mode": "bidirectional",
"href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/a7d258d5-be1e-491d-83db-526d8d9a2ce9/connections/b67efb2c-bd17-457d-be8e-7b46404062dc",
"id": "b67efb2c-bd17-457d-be8e-7b46404062dc",
"ike_policy": {
"href": "https://us-south.iaas.cloud.ibm.com/v1/ike_policies/e98f46a3-1e4e-4195-b4e5-b8155192689d",
"id": "e98f46a3-1e4e-4195-b4e5-b8155192689d",
"name": "my-ike-policy",
"resource_type": "ike_policy"
},
"ipsec_policy": {
"href": "https://us-south.iaas.cloud.ibm.com/v1/ipsec_policies/43c2f663-3960-4289-9253-f6eab23a6cd7",
"id": "43c2f663-3960-4289-9253-f6eab23a6cd7",
"name": "my-ipsec-policy",
"resource_type": "ipsec_policy"
},
"local": {
"cidrs": [
"192.0.2.0/24"
],
"ike_identities": [
{
"type": "ipv4_address",
"value": "192.0.2.4"
}
]
},
"mode": "policy",
"name": "my-vpn-connection-2",
"peer": {
"address": "192.0.2.5",
"cidrs": [
"192.0.3.0/24"
],
"ike_identity": {
"type": "ipv4_address",
"value": "192.0.2.5"
},
"type": "address"
},
"psk": "lkj14b1oi0alcniejkso",
"resource_type": "vpn_gateway_connection",
"status": "down",
"status_reasons": []
}
]
}
Getting a VPN connection
The following example uses API version 2024-04-29
or earlier to get a VPN connection.
curl -X GET "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$id?version=2024-04-29&generation=2"
-H "Authorization: $iam_token"
The response includes the peer_address
, local_cidrs
, and peer_cidrs
properties:
{
"admin_state_up": true,
"authentication_mode": "psk",
"created_at": "2018-12-13T19:40:12.124082Z",
"dead_peer_detection": {
"action": "none",
"interval": 15,
"timeout": 30
},
"href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/a7d258d5-be1e-491d-83db-526d8d9a2ce9/connections/52f69dc3-6a5c-4bcf-b264-e7fae279b15c",
"id": "52f69dc3-6a5c-4bcf-b264-e7fae279b15c",
"local_cidrs": [
"192.0.2.50/24"
],
"mode": "policy",
"name": "my-vpn-connection-1",
"peer_address": "192.0.2.5",
"peer_cidrs": [
"192.0.2.40/24"
],
"psk": "lkj14b1oi0alcniejkso",
"resource_type": "vpn_gateway_connection",
"status": "down",
"status_reasons": []
}
The following example uses API version 2024-04-30
or later to get a VPN connection.
curl -X GET "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$id?version=2024-04-30&generation=2"
-H "Authorization: $iam_token"
The response includes the peer.address
, local.cidrs
, and peer.cidrs
properties:
{
"admin_state_up": true,
"authentication_mode": "psk",
"created_at": "2018-12-13T19:40:12.124082Z",
"dead_peer_detection": {
"action": "none",
"interval": 15,
"timeout": 30
},
"establish_mode": "bidirectional",
"href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/a7d258d5-be1e-491d-83db-526d8d9a2ce9/connections/52f69dc3-6a5c-4bcf-b264-e7fae279b15c",
"id": "52f69dc3-6a5c-4bcf-b264-e7fae279b15c",
"local": {
"cidrs": [
"192.0.2.0/24"
],
"ike_identities": [
{
"type": "ipv4_address",
"value": "192.0.2.4"
}
]
},
"mode": "policy",
"name": "my-vpn-connection-1",
"peer": {
"address": "192.0.2.5",
"cidrs": [
"192.0.3.0/24"
],
"ike_identity": {
"type": "ipv4_address",
"value": "192.0.2.5"
},
"type": "address"
},
"psk": "lkj14b1oi0alcniejkso",
"resource_type": "vpn_gateway_connection",
"status": "down",
"status_reasons": []
}
Listing local CIDRs
The following example uses API version 2024-04-29
or earlier to list local CIDRs.
curl -X GET "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$id/local_cidrs?version=2024-04-29&generation=2"
-H "Authorization: $iam_token"
The response has the local_cidrs
property:
{
"local_cidrs": [
"192.168.19.0/24"
]
}
The following example uses API version 2024-04-30
or later to list local CIDRs.
curl -X GET "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$id/local/cidrs?version=2024-04-30&generation=2"
-H "Authorization: $iam_token"
The response has the cidrs
property:
{
"cidrs": [
"192.168.19.0/24"
]
}
Removing a local CIDR
The following example uses API version 2024-04-29
or earlier to remove a local CIDR.
curl -X DELETE "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$id/local_cidrs/$cidr_prefix/$prefix_length?version=2024-04-29&generation=2"
-H "Authorization: $iam_token"
The following example uses API version 2024-04-30
or later to remove a local CIDR.
curl -X DELETE "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$id/local/cidrs/$cidr?version=2024-04-30&generation=2"
-H "Authorization: $iam_token"
Getting a local CIDR
The following example uses API version 2024-04-29
or earlier to get a local CIDR.
curl -X GET "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$id/local_cidrs/$cidr_prefix/$prefix_length?version=2024-04-29&generation=2"
-H "Authorization: $iam_token"
The success response code is 204
.
The following example uses API version 2024-04-30
or later to get a local CIDR.
curl -X GET "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$id/local/cidrs/$cidr?version=2024-04-30&generation=2"
-H "Authorization: $iam_token"
The success response code is 204
.
Setting a local CIDR
The following example uses API version 2024-04-29
or earlier to set a local CIDR.
curl -X PUT "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$id/local_cidrs/$cidr_prefix/$prefix_length?version=2024-04-29&generation=2"
-H "Authorization: $iam_token"
The success response code is 204
.
The following example uses API version 2024-04-30
or later to set a local CIDR.
curl -X PUT "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$id/local/cidrs/$cidr?version=2024-04-30&generation=2"
-H "Authorization: $iam_token"
The response code is 201
if set successfully or 204
if the CIDR exists already.
Listing peer CIDRs
The following example uses API version 2024-04-29
or earlier to list peer CIDRs.
curl -X GET "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$id/peer_cidrs?version=2024-04-29&generation=2"
-H "Authorization: $iam_token"
The response has the peer_cidrs
property:
{
"peer_cidrs": [
"192.0.2.40/24"
]
}
The following example uses API version 2024-04-30
or later to list peer CIDRs.
curl -X GET "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$id/peer/cidrs?version=2024-04-30&generation=2"
-H "Authorization: $iam_token"
The response has the cidrs
property:
{
"cidrs": [
"192.168.20.0/24"
]
}
Removing a peer CIDR
The following example uses API version 2024-04-29
or earlier to remove a peer CIDR.
curl -X DELETE "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$id/peer_cidrs/$cidr_prefix/$prefix_length?version=2024-04-29&generation=2"
-H "Authorization: $iam_token"
The following example uses API version 2024-04-30
or later to remove a peer CIDR.
curl -X DELETE "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$id/peer/cidrs/$cidr?version=2024-04-30&generation=2"
-H "Authorization: $iam_token"
Getting a peer CIDR
The following example uses API version 2024-04-29
or earlier to get a peer CIDR.
curl -X GET "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$id/peer_cidrs/$cidr_prefix/$prefix_length?version=2024-04-29&generation=2"
-H "Authorization: $iam_token"
The success response code is 204
.
The following example uses API version 2024-04-30
or later to get a peer CIDR.
curl -X GET "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$id/peer/cidrs/$cidr?version=2024-04-30&generation=2"
-H "Authorization: $iam_token"
The success response code is 204
.
Setting a peer CIDR
The following example uses API version 2024-04-29
or earlier to set a peer CIDR.
curl -X PUT "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$id/peer_cidrs/$cidr_prefix/$prefix_length?version=2024-04-29&generation=2"
-H "Authorization: $iam_token"
The success response code is 204
.
The following example uses API version 2024-04-30
or later to set a peer CIDR.
curl -X PUT "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$id/peer/cidrs/$cidr?version=2024-04-30&generation=2"
-H "Authorization: $iam_token"
The response code is 201
if set successfully or 204
if the CIDR exists already.