IBM Cloud Docs
Working with subnets in VPC

Working with subnets in VPC

Subnets help your network traffic travel more efficient paths from origin to destination. You can use access control lists (ACLs) with subnets to protect your resources within each subnet.

Before you begin

Before you begin, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.subnet.subnet.create
  • is.public-gateway.public-gateway.operate Required when public_gateway is specified
  • is.network-acl.network-acl.operate

Creating a subnet in VPC

You can create a subnet in VPC by using the UI, CLI, or API.

If you use an IP range outside of the ranges RFC 1918 defines (10.0.0.0/8, 172.16.0.0/12, or 192.168.0.0/16) for a subnet, the instances attached to that subnet might be unable to reach parts of the public internet. If you plan to configure VPCs that use both non-RFC-1918 addresses and also have public connectivity (floating IPs or public gateways), make sure to use a custom route that contains the Delegate-VPC action.

Creating subnets in VPC using the UI

To create a subnet in your VPC instance, take the following steps:

  1. From your browser, open the IBM Cloud console.

  2. Select the Navigation Menu navigation menu, then click Infrastructure > Network > Subnets.

  3. Click Create + on the Subnets for VPC list table.

  4. In the Location section, provide the following information:

    • Geography: Indicate the general area where you want the subnet to be created.
    • Region: Indicate the region where you want the subnet to be created.
    • Zone: Indicate the zone where you want the subnet to be created.

  5. In the Details section, provide the following information:

    • Name: Enter a unique identifier for the subnet, such as my-subnet.
    • Resource group: Select a resource group for the subnet.
    • Tags: Optionally, add any relevant tags to help group your subnets.
    • Access management tags: Optionally, add access management tags to resources to help organize access control relationships. The only supported format for access management tags is key:value. For more information, see Controlling access to resources by using tags.
    • Virtual private cloud: Select the VPC in which you want the subnet to be created.
    • IP range selection: The most efficient location for your IP range is calculated automatically. If you want to customize the IP range instead of accepting the default selection, select a different address prefix, change the number of addresses, or enter your IP range manually.
    • Routing table: Select which routing table that you want the new subnet to use.
    • Subnet access control list: Select which access control list you want the new subnet to use.
    • Public gateway: Indicate whether you want the subnet to communicate with the public internet by toggling the switch to Attached. Attaching a public gateway creates a Floating IP and incurs a cost.

  6. In the Summary panel, click Create subnet to create the subnet.

Attached resources tab

The Attached resources tab lists all resources attached to your subnet, and provides a method of creating and attaching new resources. You can create the following resources from this tab:

  • Instances
  • Bare metal servers
  • Instance templates
  • Instance groups
  • Load balancers
  • VPN gateways
  • Virtual endpoint gateways
  • VPN servers

Click Create+ in the resource list table of the resource you want to create. You'll be taken to the respective create resource workflow where you can begin the process of creating the resource.

Reserved IPs tab

The Reserved IPs tab is a list of all reserved IPs associated with the subnet. For more information about Reserved IPs, see Managing IP addresses.

Creating subnets in VPC using the CLI

To create a subnet by using the CLI, run the following command:

ibmcloud is subnet-create SUBNET_NAME VPC ((--zone ZONE_NAME --ipv4-address-count ADDR_COUNT) | --ipv4-cidr-block CIDR_BLOCK) [--acl ACL] [--pgw PGW] [--rt RT] [--resource-group-id RESOURCE_GROUP_ID | --resource-group-name RESOURCE_GROUP_NAME] [--output JSON] [-q, --quiet]

Where:

SUBNET_NAME
Name of the subnet.
VPC
ID or name of the VPC.
--ipv4-cidr-block
The IPv4 range of the subnet. This option is mutually exclusive with --ipv4-address-count.
--ipv4-address-count
The total number of IPv4 addresses required, must be a power of 2 and minimum value is 8. This option is mutually exclusive with --ipv4-cidr-block.
--zone
Name of the zone.
--acl
The ID or name of the network ACL.
--pgw
The ID or name of the public gateway.
--rt
The ID or name of the routing table. This option also supports the cloud resource name (CRN) of the routing table.
--resource-group-id
The ID of the resource group. This ID is mutually exclusive with --resource-group-name.
--resource-group-name
Name of the resource group. This name is mutually exclusive with --resource-group-id.
--output
Specify output format, only JSON is supported. One of: JSON.
-q, --quiet
Suppress verbose output.

Creating subnets in VPC using the API

Follow these instructions to create a subnet in your VPC by using the API:

  1. Set up your API environment.
  2. Store any additional variables to be used in API commands.
Parameters for creating a subnet
Query parameters Information
version
Required
string 		Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.
Possible values: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
generation
Required
int32 		The infrastructure generation.
Possible values: 2
Request Body
Required 		The subnet prototype object.
vpc
Required
string 		The VPC the subnet will reside in.
One of: VPCIdentityById, VPCIdentityByCRN, VPCIdentityByHref
ip_version
string 		The IP version(s) to support for this subnet. Allowable values: [ipv4]
name
Required
string 		The name for this subnet. The name must not be used by another subnet in the VPC. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression ^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example: my-subnet
network_acl
string 		The network ACL to use for this subnet. If unspecified, the default network ACL for the VPC is used.
One of: NetworkACLIdentityById, NetworkACLIdentityByCRN, NetworkACLIdentityHref
public_gateway
string 		The public gateway to use for internet-bound traffic for this subnet. If unspecified, the subnet will not be attached to a public gateway.
One of: PublicGatewayIdentityById, PublicGatewayIdentityByCRN, PublicGatewayIdentityByHref
resource_group
ResourceGroupIdentityById 		The resource group to use. If unspecified, the account’s default resource group is used.
routing_table
string 		The routing table to use for this subnet. If unspecified, the default routing table for the VPC is used. The routing table properties route_direct_link_ingress, route_internet_ingress, route_transit_gateway_ingress, and route_vpc_zone_ingress must be false.
One of: RoutingTableIdentityById, RoutingTableIdentityByCRN, RoutingTableIdentityByHref
SubnetByTotalCount
int 64
or
SubnetByCIDR
string 		For SubnetByTotalCount, specify the total number of IPv4 addresses required. For SubnetByCIDR, specify the IPv4 range of the subnet, expressed in CIDR format. Both options require a zone that the subnet will reside in.

When all the variables are initiated, submit the request.

For example:

curl -X POST
"$vpc_api_endpoint/v1/subnets?version=2022-10-31&generation=2"
-H "Authorization: Bearer $iam_token"
-d '{
      "name": "my-subnet-1",
      "ipv4_cidr_block": "10.0.1.0/24",
      "ip_version": "ipv4",
      "zone": { "name": "us-south-1" },
      "vpc": { "id": "a0819609-0997-4f92-9409-86c95ddf59d3" }
    }'

The following response shows after you initiate the request:

Initiate response create example
Response Body Details
available_ipv4_address_count
Always included
int64 		The number of IPv4 addresses in this subnet that are not in-use, and have not been reserved by the user or the provider.
Example: 15
created_at
Always included
date-time 		The date and time that the subnet was created
crn
Always included
string 		The CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example: crn:v1:bluemix:public:is:us-south-1:a/123456::subnet:7ec86020-1c6e-4889-b3f0-a15f2e50f87e
  • href
    Always included*
    string
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression ^http(s)?://([^/?#]*)([^?#]*)(?([^#]*))?(#(.*))?$
Example: https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e
  • id
    Always included
    string
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$
Example: 7ec86020-1c6e-4889-b3f0-a15f2e50f87e
ip_version
Always included
string 		The IP version(s) supported by this subnet.
Possible values: [ipv4]
ipv4_cidr_block
Always included
string 		The IPv4 range of the subnet, expressed in CIDR format.
Possible values: 9 ≤ length ≤ 18, Value must match regular expression ^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5]).){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(/(3[0-2]|[1-2][0-9]|[0-9]))$
Example: 10.0.0.0/24
name
Always included
string 		The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression ^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example: my-subnet
network_acl Always included
NetworkACLReference
resource_group
Always included
ResourceGroupReference 		The resource group for this subnet.
resource_type
Always included
string 		The resource type.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example: subnet
routing_table
Always included
RoutingTableReference 		The routing table for this subnet.
status
Always included
string 		The status of the subnet.
Possible values: available,deleting,failed, pending
total_ipv4_address_count
Always included
int64
vpc
Always included
VPCReference 		The VPC this subnet resides in.
zone
Always included
ZoneReference 		The zone this subnet resides in.
public_gateway
PublicGatewayReference 		The public gateway to use for internet-bound traffic for this subnet.
Create status codes
Status Code
201 The subnet was created successfully.
400 An invalid subnet prototype object was provided.
409 The subnet prototype object conflicts with another subnet in the VPC, or specifies a CIDR block outside of the VPC's address prefixes.

For more information (including Java, Node, Python and Go examples), see "Create a subnet" in the VPC API reference.

Viewing subnets in VPC

You can view the details of a subnet in your VPC by using the UI, API, or CLI.

Viewing subnets in VPC using the UI

After you have created a subnet, it appears in the Subnets for VPC list.

To view the details about a subnet in the list using the UI, click the link of the subnet in the Name column. The Overview tab shows the information you used in the subnet creation.

Viewing subnets in VPC using the CLI

To view the details about a subnets in VPC by using the CLI, run the following command:

ibmcloud is subnet SUBNET [--vpc VPC] [--show-attached] [--output JSON] [-q, --quiet]

Where:

SUBNET
ID or name of the subnet.
--vpc
ID or name of the VPC. It is only required to specify the unique resource by name inside this VPC.
--show-attached
View details of resources (instances, load balancers, VPN gateways) attached to the subnet.
--output
Specify output format, only JSON is supported. One of: JSON.
-q, --quiet
Suppress verbose output.

Viewing subnets in VPC using the API

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access

  • is.subnet.subnet.read

Follow these instructions to retrieve a subnet in your VPC by using the API:

  1. Set up your API environment.
  2. Store any additional variables to be used in API commands.
Parameters for retrieving a subnet
Query parameters Information
id
Required
string 		The subnet identifier.
Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$
version
Required
string 		Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.
Possible values: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
generation
Required
int32 		The infrastructure generation.
Allowable values: 2
  1. When all variables are initiated, run the command.

For example:

curl -X GET "$vpc_api_endpoint/v1/subnets/$subnet_id?version=2022-10-31&generation=2"
-H "Authorization: Bearer $iam_token"

The following response shows after you initiate the request:

Initiate response retrieve example
Response Body Details
available_ipv4_address_count
Always included
int64 		The number of IPv4 addresses in this subnet that are not in-use, and have not been reserved by the user or the provider.
Example: 15
created_at
Always included
date-time 		The date and time that the subnet was created
crn
Always included
string 		The CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example: crn:v1:bluemix:public:is:us-south-1:a/123456::subnet:7ec86020-1c6e-4889-b3f0-a15f2e50f87e
  • href
    Always included*
    string
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression ^http(s)?://([^/?#]*)([^?#]*)(?([^#]*))?(#(.*))?$
Example: https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e
  • id
    Always included
    string
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$
Example: 7ec86020-1c6e-4889-b3f0-a15f2e50f87e
ip_version
Always included
string 		The IP versions supported by this subnet.
Possible values: [ipv4]
ipv4_cidr_block
Always included
string|The IPv4 range of the subnet, expressed in CIDR format.
Possible values: 9 ≤ length ≤ 18, Value must match regular expression ^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5]).){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(/(3[0-2]|[1-2][0-9]|[0-9]))$
Example: 10.0.0.0/24
name
Always included
string 		The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression ^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example: my-subnet
network_acl Always included
NetworkACLReference
resource_group
Always included
ResourceGroupReference 		The resource group for this subnet.
resource_type
Always included
string 		The resource type.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example: subnet
routing_table
Always included
RoutingTableReference 		The routing table for this subnet.
status
Always included
string 		The status of the subnet.
Possible values: available,deleting,failed, pending
total_ipv4_address_count
Always included
int64
vpc
Always included
VPCReference 		The VPC this subnet resides in.
zone
Always included
ZoneReference 		The zone this subnet resides in.
public_gateway
PublicGatewayReference 		The public gateway to use for internet-bound traffic for this subnet.
Retrieve status codes
Status Code
200 The subnet was retrieved successfully.
404 A subnet with the specified identifier could not be found.

For more information (including Java, Node, Python and Go examples), see "Retrieve a subnet" in the VPC API reference.