Working with subnets

Subnets help your network traffic travel more efficient paths from origin to destination. You can use network 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 subnets

You can create subnets by using the console, CLI, or API.

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

Creating subnets in the console

To create a subnet in the console, follow these steps:

From your browser, open the IBM Cloud console.
Select the Navigation menu , then click Infrastructure > Network > Subnets.
Click Create on the Subnets for VPC list table.
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.
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.
In the IP range selection section, provide the following information:
- IP range: 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.
- Address prefix: Select the base network prefix for your subnet. This determines the larger IP range from which your subnet’s IP addresses is allocated. Choose from available prefixes within your VPC.
- Total IP addresses: Select the total number of IPv4 addresses required.
- Address space: Displays the full IP address range of the selected prefix in your VPC. This range defines the boundaries within which you can allocate subnet IP ranges.
- 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.
In the Summary panel, click Create subnet.

Attached resources tab

The Attached Resources tab lists all resources attached to the subnet and allows creation of:

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're taken to the respective create resource workflow where you can begin the process of creating the resource.

Reserved IPs tab

The Reserved IPs tab lists all reserved IP addresses for the subnet. For more information, see Managing IP addresses.

Creating subnets from the CLI

To create subnets from 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, it must be a power of 2 and the 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 with the API

Follow these instructions to create subnets by using the API:

Set up your API environment.
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 can be provided. Specify the current date to request the most recent 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 that this subnet resides in. One of: `VPCIdentityById`, `VPCIdentityByCRN`, `VPCIdentityByHref`
`ip_version` `string`	The IP version 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 is going to 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 is not going to 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` for the subnet to be created in.

When all the variables are initiated, submit the request.

See the following 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:

API response 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 are not reserved by the user or the provider. Example: `15`
`created_at` Always included `date-time`	The date and time that this 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) that are supported by this subnet. Possible values: `[ipv4]`
`ipv4_cidr_block` Always included `string`	The IPv4 range of the subnet, which is 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 that this subnet resides in.
`zone` Always included `ZoneReference`	The zone that this subnet resides in.
`public_gateway` `PublicGatewayReference`	The public gateway to use for internet-bound traffic for this subnet.

Create status codes
Status Code	Meaning
`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 the create a subnet method in the VPC API reference.

Viewing subnets

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

Viewing subnets in the console

After the subnet is created, it appears in the Subnets for VPC list.

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

Viewing subnets from the CLI

To view the details about a subnet in VPC from 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 with 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:

Set up your API environment.
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 can be provided. Specify the current date to request the most recent 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`

When all variables are initiated, run the command.

See the following 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 are not reserved by the user or the provider. Example: `15`
`created_at` Always included date-time	The date and time that this 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 that this subnet resides in.
`zone` Always included ZoneReference	The zone that this subnet resides in.
`public_gateway` PublicGatewayReference	The public gateway to use for internet-bound traffic for this subnet.

Retrieve status codes
Status Code	Meaning
`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.