---
name: transit-gateway-adding-gateway
title: Adding a connection
description: You can add a connection to a transit gateway by using the UI, CLI, API, and Terraform.
last-updated: 2026-08-06
---

> ## Documentation Index
> The table of contents for this documentation set is at https://cloud.ibm.com/docs/transit-gateway?format=markdown
> The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt
> Use these files to discover more information as needed.

# Adding a connection
{: #adding-connections}

You can add a connection to a transit gateway by using the UI, CLI, API, and Terraform.
{: shortdesc}

 

## Adding a connection in the UI
{: #tg-ui-adding-connection-transit-gateway}
{: ui}

To add a connection to a transit gateway, follow these steps:
1. Open the [IBM Cloud console](https://cloud.ibm.com/login){: external} and log in to your account.
1. Select the Navigation Menu icon ![Navigation Menu icon](../../icons/icon_hamburger.svg) from the upper left, then click **Infrastructure** > **Network** > **Transit Gateway**.
1. Click the name of the transit gateway where you want to add a connection.

   If you are in the expanded view, click **View full details**.
   {: tip}

1. In the Connections view, click **Add connection**.
1. Choose and configure the specific network connections that you want to add to your transit gateway. Choices include:

   * **Classic infrastructure** networks allow you to connect to IBM Cloud classic resources. Only one classic infrastructure connection is allowed per account.

   * **Direct Link** creates a network connection to and from Direct Link gateways so that there is a secure connection to on-premises networks and other resources that are connected to the transit gateway.

      If you select **Direct Link**, you must also log in to the [Direct Link console](https://cloud.ibm.com/interconnectivity/direct-link){: external} and specify **Transit Gateway** as the type of network connection for your direct link.
      {: important}

   * **Power Virtual Server** - Creates a network connection to and from a Power Virtual Server workspace to access the resources in a Power Virtual Server colocation.

      If you select **Power Virtual Server**, a Power Virtual Server workspace must be created in a PER-enabled data center. For a list of PER-enabled data centers, see [Getting started with the Power Edge Router](https://cloud.ibm.com/docs/power-iaas?topic=power-iaas-per&format=markdown).
      {: note}

   * **Redundant GRE tunnel** allows unbound GRE tunnels to connect to endpoints in either VPC or classic infrastructure networks, thus allowing you to build in redundancy for GRE tunnels. For more information, see [Creating a redundant GRE tunnel](https://cloud.ibm.com/docs/transit-gateway?topic=transit-gateway-redundant-gre-connection&format=markdown).

   * **Unbound GRE tunnel** allows a transit gateway to connect to overlay networks hosted on classic infrastructure resources. For more information, see [Creating an unbound GRE tunnel](https://cloud.ibm.com/docs/transit-gateway?topic=transit-gateway-unbound-gre-connection&format=markdown).

   * **VPC** networks can contain compute resources, allowing you to connect to your account's VPC resources, or, with approval, another account's VPC resources.

   

   * **VPN gateway** connections link on-premises or external networks with IBM Cloud by attaching a VPN gateway as a spoke to a transit gateway. These connections use redundant GRE tunnels and dynamic routing with eBGP to enable efficient and scalable network integration. For more information, see [Creating a VPN gateway](https://cloud.ibm.com/docs/vpc?topic=vpc-vpn-create-gateway&interface=ui&format=markdown).

1. Optionally, create prefix filters to set an ordered list of filters that determine the routes your transit gateway accepts or denies. For more information, see [Adding and deleting prefix filters](https://cloud.ibm.com/docs/transit-gateway?topic=transit-gateway-adding-prefix-filters&interface=ui&format=markdown).

1. After you select a network connection, choose a connection reach option:

   * **Add new connection in this account** - Enter a connection name and any other required information for your connection.

      * For **Power Virtual Server**, select a location for the Power Virtual Server workspace. Then, select from the list of  Power Virtual Server workspaces that are enabled for Transit Gateway. Keep in mind that not all Power Virtual Server workspaces show in this menu.

      * For **VPN gateway**, first select the region where your VPN gateway is deployed. Then, select from the available VPN gateways that support dynamic routing.

         You must specify a custom CIDR block for the connection. The CIDR defines the IP range that is used to allocate addresses on the redundant GRE tunnels and must use [RFC 1918](https://datatracker.ietf.org/doc/html/rfc1918){: external} private address space, be at least a `/27` subnet, and must not overlap with other connection CIDRs on the transit gateway.

         Only VPN gateways with dynamic routing enabled are shown in the Available connections list. The selected region and zone determine which Transit Gateway routers the VPN gateway connects to.
         {: note}

         Specifying a zone is optional if the VPN gateway and the transit gateway are in the same multi-zone region (MZR). In this case, the connection uses the VPN gateway’s zone.
         {: attention}

   * **Request connection to a network in another account** - Enter either the IBM Cloud ID or Cloud Resource Name (CRN) of the account that manages the network where you want to connect. Then, complete any remaining information. All resources connected to that transit gateway will be accessible from the other network. For more information, including how to obtain the Cloud ID or CRN, see [Adding a cross-account connection](https://cloud.ibm.com/docs/transit-gateway?topic=transit-gateway-adding-cross-account-connections&interface=ui&format=markdown).

      * IBM Cloud ID - Required by **Classic infrastructure** and **Unbound GRE tunnel**.
      * CRN - Required by all other connections.

      To find out whether your Power Systems Virtual Server workspace is set up correctly, go to the Power Systems Virtual Server UI and check the navigation for a Cloud connections page. If there isn't a Cloud connections page, the workspace leverages Transit Gateway. Otherwise, you must configure virtual connections with Cloud connections on the Power Systems Virtual Server.
      {: important}

1. After you complete your network connection information, click **Add** to create a connection.

## Adding a connection from the CLI
{: #tg-cli-adding-connection-transit-gateway}
{: cli}

### Before you begin
{: #cli-prereqs-before-you-begin}

Complete these prerequisites to use the Transit Gateway CLI, which is implemented as an IBM Cloud CLI plug-in.

1. Install the [IBM Cloud CLI](https://cloud.ibm.com/docs/cli?topic=cli-install-ibmcloud-cli&format=markdown#install-ibmcloud-cli){: external}.
1. Install the `tg-cli/tg` CLI plug-in to the IBM Cloud CLI.

   To install:

   ```sh
   ibmcloud plugin install tg
   ```
   {: pre}

If you are going to use the CLI with a Virtual Private Endpoint (VPE), you must set the following variable:

```bash
export IBMCLOUD_TG_API_ENDPOINT=private.transit.cloud.ibm.com
```
{: pre}

To add a connection on the transit gateway from the CLI, enter the following command:

```sh
ibmcloud tg connection-create|cc GATEWAY_ID --name NAME --network-id NETWORK_ID --network-type NETWORK_TYPE --network-account-id ACCOUNT_ID [--zone ZONE] [--default-prefix-filter DEFAULT_PREFIX_FILTER] [--cidr CIDR] [--output json]
```
{: pre}

#### Command options
{: #connection-create-parameters}

`GATEWAY_ID`
:   ID of the gateway that the new connection is on.

`--name`
:   Name for the new connection.

`--network-id`
:   ID of the network connection. For `classic`, don't set a value. Use the CRN for all other network types. For example, to find the CRN of a VPC:

   ```sh
   ibmcloud is vpc VPC_ID --json
   ```
   {: pre}

`--network-type`
:   Network type of the connection. Values are `classic`, `directlink`, `power_virtual_server`, `vpn_gateway`, and `vpc`.

`--network-account-id`
:   ID of the IBM Cloud account to use for creating a classic connection. Only used with `classic` type, when the account of the connection is different than the gateway's account.

`--zone`
:   Optional: Availability zone where a GRE tunnel or VPN connection is deployed. Only applicable to the `vpn_gateway` network type.

`--default-prefix-filter`
:   Optional: Default prefix filter of the connection (`permit` | `deny`).

`--cidr`
:   Optional: CIDR block to use for the connection. Only applicable to the `vpn_gateway` network type.

`--output json`
:   Optional: Specify whether you want the output displayed in JSON format.

`--help | -h`
:   Optional: Get help on this command.

#### Examples
{: #connection-create-examples}

This example illustrates creating a VPC connection named `vpc-connection` using `vpcCRN="crn:v1:bluemix:public:is:us-south:a/3aa0a9999a1a46258064d84f7f447920::vpc:r134-f87014d5-87d2-46d1-9999-24683082f6bc"`:

```sh
ibmcloud tg cc $gateway --name vpc-connection --network-id $vpcCRN --network-type vpc
```
{: pre}

Create classic connection named `classic-conn`.

```sh
ibmcloud tg cc $gateway --name classic-conn --network-type classic
```
{: pre}

## Adding a connection with the API
{: #tg-api-adding-connection-transit-gateway}
{: api}

To add a connection with the API, follow these steps:

1. Set up your [API environment](https://cloud.ibm.com/docs/vpc?topic=vpc-set-up-environment&interface=api&format=markdown#api-prerequisites-setup).
1. Store any additional variables to be used in the API commands.
1. Add a connection to the transit gateway. For example:

   ```sh
   curl -X POST --location --header "Authorization: Bearer {iam_token}" \
     --header "Accept: application/json" \
     --header "Content-Type: application/json" \
     --data '{ "network_type": "vpc" }'
     "
   {base_url}/transit_gateways/{transit_gateway_id}/connections?version={version}"
   ```
   {: pre}

For more information, see [Adds a connection to a transit gateway](https://cloud.ibm.com/docs/apis/transit-gateway?code=java#create-transit-gateway-connection) in the Transit Gateway API reference.
{: note}

## Adding a connection with Terraform
{: #tg-terraform-adding-connection-transit-gateway}
{: terraform}

Review the following argument references that you can specify for your resource when you create a connection for a transit gateway using Terraform:

|Argument|Details|
|--|--|
|**base_connection_id**  \n Optional  \n Forces new resource \n string | The ID of a `classic` `network_type` connection a tunnel is configured over. \n This field applies only to network type `gre_tunnel` connections.|
|**base_network_type**  \n Optional  \n Forces new resource  \n string | The base network type. Allowed values are `classic`.  \n This field applies only to `unbound_gre_tunnel` type connections.
|**gateway**  \n Required  \n Forces new resource  \n string | Enter the transit gateway identifier.|
|**local_gateway_ip**  \n Optional  \n Forces new resource  \n string | The local gateway IP address. \n This field is required for, and only applicable to, `gre_tunnel` and `unbound_gre_tunnel` type connections. |
|**local_tunnel_ip**  \n Optional  \n Forces new resource  \n string | The local tunnel IP address. \n This field is required for, and only applicable to, `gre_tunnel` and `unbound_gre_tunnel` type connections.|
|**name**  \n Optional  \n string | The connection name. If the name is not given, a default name is provided based on the network type, such as `vpc` for network type VPC and `classic` for network type classic.|
|**network_account_id**  \n Optional  \n Forces new resource  \n string|The ID of the network connected account. This field is used if the network is in a different account than the gateway.|
|**network_type**  \n Required  \n Forces new resource  \n string | The network type. Allowed values are `classic`, `directlink`, `gre_tunnel`, `unbound_gre_tunnel`, `vpn_gateway`, and `vpc`. |
|**network_id**  \n Optional  \n Forces new resource  \n string | The ID of the network that is being connected to through this connection. \n This parameter is required for network type `vpc` and `directlink`, the CRN of the VPC or direct link gateway to be connected.  \n This field is required to be unspecified for network type `classic`.  \n **Example**:`crn:v1:bluemix:public:is:us-south:a/123456::vpc:4727d842-f94f-4a2d-824a-9bc9b02c523b`|
|**remote_bgp_asn**  \n Optional  \n Forces new resource  \n integer | The remote network BGP ASN (will be generated for the connection if not specified).  \n This field applies only to `gre_tunnel` and `unbound_gre_tunnel` type connections.|
|**remote_gateway_ip**  \n Optional  \n Forces new resource  \n string | The remote gateway IP address. This field applies only to `gre_tunnel` and `unbound_gre_tunnel` type connections.|
|**remote_tunnel_ip**  \n Optional  \n Forces new resource  \n string | The remote tunnel IP address. This field applies only to `gre_tunnel` and `unbound_gre_tunnel` type connections.|
|**zone**  \n Optional  \n Forces new resource  \n string | The location of the GRE tunnel. This field applies only to `gre_tunnel` and `unbound_gre_tunnel` type connections. |
{: caption="Terraform argument references for creating a connection" caption-side="bottom"}

### Example
{: #tg-terraform-adding-connection-transit-gateway-example}

This example illustrates creating a transit gateway connection that uses Terraform:

```terraform
resource "ibm_tg_connection" "test_ibm_tg_connection" {
  gateway      = ibm_tg_gateway.test_tg_gateway.id
  network_type = "vpc"
  name         = "myconnection"
  network_id   = ibm_is_vpc.test_tg_vpc.resource_crn
}
```
{: codeblock}