Updating to the 2022-03-29 version (network interfaces, security groups)

Migrating use of IP addresses

Before you migrate a client to API version 2022-03-29 or later, review your code for any use of the primary_ipv4_address property. As shown in the examples, as of version 2022-03-29, the primary_ipv4_address string property is replaced by the primary_ip object property, which includes an address sub-property. Therefore, you need to change all instances of primary_ipv4_address to primary_ip.address in the manner appropriate for your programming language.

While primary_ipv4_address appears only in the NetworkInterface, NetworkInterfaceReference, and NetworkInterfacePrototype schemas (and their closely related BareMetalNetworkInterface schemas), those schemas are used extensively in the VPC API. Therefore, even though the incompatible change is limited to the primary_ipv4_address property, many operations have been affected. See Changed operations for a complete list.

Migrating use of security group associations

As part of the 2021-02-23 release, security group target methods were made available, and the original methods specific to network interfaces were deprecated. API version 2022-03-29 removes support for those deprecated methods. As shown in the examples, the security group target methods include the capabilities of the deprecated methods. Security group targets also allow security groups to be associated with other VPC resources, such as endpoint gateways and load balancers.

The deprecated GET and PUT methods returned NetworkInterface response schemas, but the new GET and PUT methods return NetworkInterfaceReference response schemas. If your client was accessing properties beyond the properties in NetworkInterfaceReference, your client needs to call GET /instances/{instance_id}/network_interfaces/{id} to retrieve those properties separately.

Additionally, if your client was previously accessing the network_interfaces[] property that is returned by GET /security_groups, it needs to access the targets[] property instead. If your client was accessing properties in network_interfaces[] beyond the properties in NetworkInterfaceReference, your client needs to call GET /instances/{instance_id}/network_interfaces/{id} to retrieve those properties separately.

IP address examples

The following examples compare how to make a POST /instances call to provision an instance with a specific IP address on its primary network interface before and after the 2022-03-29 versioned change, and how to retrieve that IP address.

Specifying API version 2022-03-28 or earlier:

curl -X POST \
  "$vpc_api_endpoint/v1/instances?version=2022-03-28&generation=2" \
  -H "Authorization: Bearer $iam_token" \
  -d '{
        "image": {"id": "'"$image_id"'"},
        "keys": [{"id": "'"$key_id"'"}],
        "primary_network_interface": {
          "primary_ipv4_address": "10.240.0.5",
          "subnet": {"id": "'"$subnet_id"'"}
        },
        "zone": {"name": "'"$zone"'"}
      }'

To retrieve the address:

curl -X GET \
  "$vpc_api_endpoint/v1/instances/$instance_id?version=2022-03-28&generation=2" \
  -H "Authorization: Bearer $iam_token" | jq '.primary_network_interface.primary_ipv4_address'

Specifying API version 2022-03-29 or later:

curl -X POST \
  "$vpc_api_endpoint/v1/instances?version=2022-03-29&generation=2" \
  -H "Authorization: Bearer $iam_token" \
  -d '{
        "image": {"id": "'"$image_id"'"},
        "keys": [{"id": "'"$key_id"'"}],
        "primary_network_interface": {
          "primary_ip": {
            "address": "10.240.0.5"
          },
          "subnet": {"id": "'"$subnet_id"'"}
        },
        "zone": {"name": "'"$zone"'"}
      }'

To retrieve the address:

curl -X GET \
  "$vpc_api_endpoint/v1/instances/$instance_id?version=2022-03-29&generation=2" \
  -H "Authorization: Bearer $iam_token" | jq '.primary_network_interface.primary_ip.address'

The following examples compare how to make a POST /instances/{id}/network_interface call to create a new network interface on an existing instance with a specific IP address before and after the 2022-03-29 versioned change, and how to retrieve the address.

Specifying API version 2022-03-28 or earlier:

curl -X POST \
  "$vpc_api_endpoint/v1/instances/$instance_id/network_interfaces?version=2022-03-28&generation=2" \
  -H "Authorization: Bearer $iam_token" \
  -d '{
        "primary_ipv4_address": "10.240.0.5",
        "subnet": {"id": "'"$subnet_id"'"}
      }'

To retrieve the address:

curl -X GET \
  "$vpc_api_endpoint/v1/instances/$instance_id/network_interfaces/$network_interface_id?version=2022-03-28&generation=2" \
  -H "Authorization: Bearer $iam_token" | jq '.primary_ipv4_address'

Specifying API version 2022-03-29 or later:

curl -X POST \
  "$vpc_api_endpoint/v1/instances/$instance_id/network_interfaces?version=2022-03-29&generation=2" \
  -H "Authorization: Bearer $iam_token" \
  -d '{
        "primary_ip": {
          "address": "10.240.0.5"
        },
        "subnet": {"id": "'"$subnet_id"'"}
      }'

To retrieve the address:

curl -X GET \
  "$vpc_api_endpoint/v1/instances/$instance_id/network_interfaces/$network_interface_id?version=2022-03-29&generation=2" \
  -H "Authorization: Bearer $iam_token" | jq '.primary_ip.address'

Security group association examples

The following examples compare how to place a network interface into a security group before and after the 2022-03-29 versioned change.

Specifying API version 2022-03-28 or earlier:

curl -X PUT \
  "$vpc_api_endpoint/v1/security_groups/$security_group_id/network_interfaces/$id?version=2022-03-28&generation=2" \
  -H "Authorization: Bearer $iam_token"

Specifying API version 2022-03-29 or later:

curl -X PUT \
  "$vpc_api_endpoint/v1/security_groups/$security_group_id/targets/$id?version=2022-03-29&generation=2" \
  -H "Authorization: Bearer $iam_token"

The following examples compare how to remove a network interface from a security group before and after the 2022-03-29 versioned change.

Specifying API version 2022-03-28 or earlier:

curl -X DELETE \
  "$vpc_api_endpoint/v1/security_groups/$security_group_id/network_interfaces/$id?version=2022-03-28&generation=2" \
  -H "Authorization: Bearer $iam_token"

Specifying API version 2022-03-29 or later:

curl -X DELETE \
  "$vpc_api_endpoint/v1/security_groups/$security_group_id/targets/$id?version=2022-03-29&generation=2" \
  -H "Authorization: Bearer $iam_token"

IP addresses

The following table lists the operations where primary_ipv4_address changed to primary_ip in the request bodies, response bodies, or both. A period (.) indicates that primary_ipv4_address was changed to primary_ip in the top-level response schema.

Security group associations

The following table lists the methods or properties that were removed as part of completing the migration to security group targets.