Transit Gateway CLI
The IBM Cloud® Transit Gateway command line provides an interface into the Transit Gateway service. You can use the CLI to create and manage gateways and connections and list available locations for gateways.
Before you begin
Follow these instructions to use the Transit Gateway Command Line Interface, which is implemented as an IBM Cloud CLI plug-in.
-
Install the IBM Cloud CLI.
-
Install the
tg-cli/tg
CLI plug-in to the IBM Cloud CLI.To install:
ibmcloud plugin install tg
If you are going to use the CLI with a Virtual Private Endpoint (VPE), you must set the following variable:
export IBMCLOUD_TG_API_ENDPOINT=private.transit.cloud.ibm.com
ibmcloud plugin show tg
Show Transit Gateway CLI plug-in information.
ibmcloud plugin show tg
ibmcloud tg --help
Get help on Transit Gateway commands.
ibmcloud tg -h|--help
Locations
This section provides information about CLI commands for location functions.
ibmcloud tg locations
Use this command to list possible locations to create a gateway.
ibmcloud tg locations|locs [--output json] [-h, --help]
Command options
--output json
- Optional: Specify whether you want the output that is displayed in JSON format.
--help | -h
- Optional: Get help on this command.
ibmcloud tg location
Retrieves specific information for this location.
ibmcloud tg location|loc NAME [--output json] [-h, --help]
Command options
NAME
- Name of the location you want details for.
--output json
- Optional: Specify whether you want the output that is displayed in JSON format.
--help | -h
- Optional: Get help on this command.
Example
Request details for location us-south
.
ibmcloud tg location us-south
Gateways
This section provides information about CLI commands for gateway functions.
ibmcloud tg gateways
List transit gateways.
ibmcloud tg gateways|gws [--output json] [-h, --help]
Command options
--output json
- Optional: Specify whether you want the output that is displayed in JSON format.
--help | -h
- Optional: Get help on this command.
Other commands require a gateway ID. Save the ID as an environment variable so you can use it later, for example:
gateway="bdf8fa2b-c518-9999-9028-f3c9ece86159"
ibmcloud tg gateway
Retrieve details about a specific gateway.
ibmcloud tg gateway|gw GATEWAY_ID [--output json] [-h, --help]
Command options
GATEWAY_ID
- ID of the gateway you want details for.
--output json
- Optional: Specify whether you want the output that is displayed in JSON format.
--help | -h
- Optional: Get help on this command.
Example
Request details for gateway.
ibmcloud tg gw $gateway
ibmcloud tg gateway-create
Create a transit gateway.
ibmcloud tg gateway-create|gwc --name NAME --location LOCATION [--routing ROUTING] [--resource-group-id RES_GROUP_ID] [--output json] [-h, --help]
Command options
--name
- Name for the new gateway.
--location
- Location of the gateway (see possible values by using
ibmcloud tg locations
) --routing
- Gateway routing of resources (
global
|local
). Selectglobal
to connect resources across regions. The default value islocal
. --resource-group-id
- Optional: Gateway resource group ID. Uses default resource group, if not specified.
--output json
- Optional: Specify whether you want the output that is displayed in JSON format.
--help | -h
- Optional: Get help on this command.
Example
Create a gateway that is named myGateway
in us-south
with local
routing and that uses default resource group.
ibmcloud tg gwc --name myGateway --location us-south
ibmcloud tg gateway-update
Update properties on an existing gateway.
ibmcloud tg gateway-update|gwu GATEWAY_ID [--name NAME] [--routing ROUTING] [--output json] [-h, --help]
Command options
GATEWAY_ID
- ID of the gateway you want to update.
--name
- Optional: New name of the gateway.
--routing
- Optional: Gateway routing of resources (
global
|local
). Select global to connect resources across regions. Changing routing fromglobal
tolocal
requires all existing connections to belocal
. --output json
- Optional: Specify whether you want the output that is displayed in JSON format.
--help | -h
- Optional: Get help on this command.
Example
Update the gateway with a routing value of global
.
ibmcloud tg gwu $gateway --routing global
ibmcloud tg gateway-delete
Delete an existing gateway.
ibmcloud tg gateway-delete|gwd GATEWAY_ID [-f, --force] [-h, --help]
Command options
GATEWAY_ID
- ID of the gateway you want to delete.
--force | -f
- Optional: Force the delete without confirmation.
--help | -h
- Optional: Get help on this command.
Example
Delete gateway with no confirmation.
ibmcloud tg gwd $gateway -f
Connections
This section provides information about CLI commands for connection functions.
ibmcloud tg connections
List connections on the transit gateway.
ibmcloud tg connections|cs GATEWAY_ID [--all-pages] [--limit NUMERIC_VALUE] [--output json] [-h, --help]
Command options
GATEWAY_ID
- ID of the gateway you want connections for.
--all-pages
(Select availability at this time)- Lists all connections regardless of whether a
--limit
size is specified. --limit
(Select availability at this time)- The maximum number of resources to return per page. The default limit is
100
. Possible values:1
≤ value ≤500
--output json
- Optional: Specify whether you want the output that is displayed in JSON format.
--help | -h
- Optional: Get help on this command.
Example
List the connections on the gateway.
ibmcloud tg cs $gateway
Other commands require a connection ID. Save the ID as an environment variable so you can use it later, for example:
connection="4892849f-368e-9999-bb58-8888fb21e513"
ibmcloud tg connection
Retrieve details about a specific connection.
ibmcloud tg connection|c GATEWAY_ID CONNECTION_ID [--output json] [-h, --help]
Command options
GATEWAY_ID
- ID of the gateway the connection is on.
CONNECTION_ID
- ID of the connection you want details for.
--output json
- Optional: Specify whether you want the output that is displayed in JSON format.
--help | -h
- Optional: Get help on this command.
Example
Request details for a specific connection ID.
ibmcloud tg c $gateway $connection
ibmcloud tg connection-create
Create a connection on the transit gateway.
ibmcloud tg connection-create|cc GATEWAY_ID --name NAME --network-type NETWORK_TYPE --network-id NETWORK_ID --network-account-id NETWORK_ACCOUNT_ID [--output json] [-h, --help]
Command options
GATEWAY_ID
-
ID of the gateway that the new connection is on.
--name
-
Name for the new connection.
--network-type
-
Network type of the connection. Values are
classic
,vpc
,directlink
, orpower_virtual_server
. --network-id
-
ID of the network connection. For
classic
, do not set a value. Use the CRN for all other network types. For example, to find the CRN of a VPC:ibmcloud is vpc VPC_ID --json
--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. --default-prefix-filter
-
Optional: Default prefix filter of the connection (
permit
|deny
). --output json
-
Optional: Specify whether you want the output that is displayed in JSON format.
--help | -h
-
Optional: Get help on this command.
Example
Create a VPC connection that is named vpc-connection
and uses vpcCRN="crn:v1:bluemix:public:is:us-south:a/3aa0a9999a1a46258064d84f7f447920::vpc:r134-f87014d5-87d2-46d1-9999-24683082f6bc"
ibmcloud tg cc $gateway --name vpc-connection --network-id $vpcCRN --network-type vpc
Create a Classic connection named classic-conn
.
ibmcloud tg cc $gateway --name classic-conn --network-type classic
ibmcloud tg connection-create-gre
Create a Generic Routing Encapsulation (GRE) tunnel or unbound GRE connection on the transit gateway.
ibmcloud tg connection-create-gre|ccgre GATEWAY_ID --name NAME --zone ZONE --local-gateway-ip LOCAL_GATEWAY_IP --local-tunnel-ip LOCAL_TUNNEL_IP --remote-gateway-ip REMOTE_GATEWAY_IP --remote-tunnel-ip REMOTE_TUNNEL_IP [--base-connection-id BASE_CONNECTION_ID] [--base-network-type BASE_NETWORK_TYPE] [--network-type NETWORK_TYPE] [--network-account-id NETWORK_ACCOUNT_ID] [--remote-bgp-asn REMOTE_BGP_ASN] [--default-prefix-filter DEFAULT_PREFIX_FILTER] [--output json]
Command options
GATEWAY_ID
ID of the gateway where the new connection is bound.
--name
- Name of the new connection.
--zone
- Availability zone for the GRE tunnel. Example:
us-south-1
--local-gateway-ip
- Local gateway IP address for the GRE tunnel connection.
--local-tunnel-ip
- Local tunnel IP address for the GRE tunnel connection.
--remote-gateway-ip
- Remote gateway IP address for the GRE tunnel connection.
--remote-tunnel-ip
- Remote tunnel IP address for the GRE tunnel connection.
--base-connection-id
- Optional: ID of the classic network connection that is the underlay for the GRE tunnel. This option is for use only with the
gre_tunnel
network type. --base-network-type
- Network type of the base connection (
classic
). This option is for use only with theunbound_gre_tunnel
network type. --network-type
- Optional: Network type of the GRE connection. Values are
gre_tunnel
orunbound_gre_tunnel
. The default value isgre_tunnel
. --network-account-id
- Optional: ID of account to connect to a classic connection. Use only with
classic
type when the account of the connection is different than gateway's account. --remote-bgp-asn
- Optional: If the remote BGP ASN is not specified, one is generated.
--output json
- Optional: Specify whether you want the output that is displayed in JSON format.
--help | -h
- Optional: Get help on this command.
Examples
Create a GRE tunnel connection that is named gre-connection
and uses classic connection 9037f710-8dfb-4948-a2bd-847c8dde96d3
as the base connection.
ibmcloud tg connection-create-gre $gateway --name gre-connection --base-connection-id 9037f710-8dfb-9999-a2bd-847c8dde96d3 --zone us-south-2 --local-gateway-ip 192.168.100.1 --local-tunnel-ip 192.168.101.1 --remote-gateway-ip 10.242.63.12 --remote-tunnel-ip 192.168.101.2
ibmcloud tg connection-update
Update properties on an existing connection.
ibmcloud tg connection-update|cu GATEWAY_ID CONNECTION_ID --name NAME [--output json] [-h, --help]
Command options
GATEWAY_ID
- ID of the gateway that the connection is being updated is on.
CONNECTION_ID
- ID of the connection to update.
--name
- New name of the connection.
--default-prefix-filter
- Optional: Default prefix filter of the connection (
permit
|deny
). --output json
- Optional: Specify whether you want the output that is displayed in JSON format.
--help | -h
- Optional: Get help on this command.
Example
Update name of connection to MyConn2
.
ibmcloud tg cu $gateway $connection --name MyConn2
ibmcloud tg connection-approve
Approve a connection from another account as the network owner.
ibmcloud tg connection-approve|ca GATEWAY_ID CONNECTION_ID [-h, --help]
Command options
GATEWAY_ID
- ID of the gateway the connection is on.
CONNECTION_ID
- ID of the connection you are approving.
--help | -h
- Optional: Get help on this command.
Example
Approve the connection request.
ibmcloud tg ca $gateway $connection
ibmcloud tg connection-reject
Reject a connection from another account as the network owner.
ibmcloud tg connection-reject|cr GATEWAY_ID CONNECTION_ID [-h, --help]
Command options
GATEWAY_ID
- ID of the gateway the connection is on.
CONNECTION_ID
- ID of the connection you are rejecting.
--help | -h
- Optional: Get help on this command.
Example
Reject the connection request.
ibmcloud tg cr $gateway $connection
ibmcloud tg connection-delete
Delete an existing connection.
ibmcloud tg connection-delete|cd GATEWAY_ID CONNECTION_ID [-f, --force] [-h, --help]
Command options
GATEWAY_ID
- ID of the gateway of the connection that is being deleted.
CONNECTION_ID
- ID of the connection that is being deleted.
--force | -f
- Optional: Force the delete without confirmation.
--help | -h
- Optional: Get help on this command.
Example
Delete connection without confirmation.
ibmcloud tg cd $gateway $connection -f
Route reports
This section provides information about CLI commands for route report functions.
ibmcloud tg route-reports
Use this command to list route reports available on a gateway.
ibmcloud tg route-reports|rrs GATEWAY_ID [--output json] [-h, --help]
Command options
GATEWAY_ID
- ID of the gateway to list route reports for.
--output json
- Optional: Specify whether you want the output that is displayed in JSON format.
--help | -h
- Optional: Get help on this command.
Example
List the route reports on the gateway.
ibmcloud tg rrs $gateway
Other commands require a route report ID. Save the ID as an environment variable so you can use it later, for example:
report="4892849f-368e-9999-4444-8888fb21e513"
ibmcloud tg route-report
Retrieve details about a specific route report.
ibmcloud tg route-report|rr GATEWAY_ID REPORT_ID [--output json] [-h, --help]
Command options
GATEWAY_ID
- ID of the gateway the route report is from.
REPORT_ID
- ID of the route report you want details for.
--output json
- Optional: Specify whether you want the output that is displayed in JSON format.
--help | -h
- Optional: Get help on this command.
Example
Request details for a route report.
ibmcloud tg rr $gateway $report
ibmcloud tg route-report-create
Create a route report.
ibmcloud tg route-report-create|rrc GATEWAY_ID [--output json] [-h, --help]
Command options
GATEWAY_ID
- ID of the gateway the route report is created for.
--output json
- Optional: Specify whether you want the output that is displayed in JSON format.
--help | -h
- Optional: Get help on this command.
Example
Create a route report for a gateway.
ibmcloud tg rrc $gateway
ibmcloud tg route-report-delete
Delete an existing route report.
ibmcloud tg route-report-delete|rrd GATEWAY_ID REPORT_ID [-f, --force] [-h, --help]
Command options
GATEWAY_ID
- ID of the gateway the report is for.
REPORT_ID
- ID of the report you want to delete.
--force | -f
- Optional: Force the delete without confirmation.
--help | -h
- Optional: Get help on this command.
Example
Delete route report with no confirmation.
ibmcloud tg rrd $gateway $report -f
ibmcloud tg prefix-filter-create
Add prefix filter to connection.
ibmcloud tg prefix-filter-create GATEWAY_ID CONNECTION_ID --prefix PREFIX --action ACTION [--le LE] [--ge GE] [--before BEFORE] [--output json]
Command options
GATEWAY_ID
- ID of the gateway the prefix filter is being applied to.
CONNECTION_ID
- ID of the connection the prefix filter is being applied to.
--prefix
- Network prefix that the filter is applied to.
--action
- Action to take on the specified prefix (
permit
|deny
). --le
- Optional: Prefix filter that is applied to a subnet mask less than or equal to this value.
--ge
- Optional: Prefix filter that is applied to a subnet mask greater than or equal to this value.
--before
- Optional: Identifier of the prefix filter this filter should be applied before. If empty, this filter is applied last.
--output
- Optional: Specify output format; Only
json
is supported.
Examples
Add prefix filter for 10.0.250.0/24
to gateway 9f559c43-63f4-4da5-b312-b525a8dce185
, connection 6c1bdc19-4adb-4760-8cdc-ef3b74b626f7
with the action permit
.
ibmcloud tg pfc 9f559c43-63f4-4da5-b312-b525a8dce185 6c1bdc19-4adb-4760-8cdc-ef3b74b626f7 --prefix 10.0.250.0/24 --action permit
ibmcloud tg prefix-filter-delete
Delete prefix filter from connection.
ibmcloud tg prefix-filter-delete GATEWAY_ID CONNECTION_ID FILTER_ID [-f, --force]
Command options
GATEWAY_ID
- ID of the gateway that the prefix filter is deleted from.
CONNECTION_ID
- ID of the connection that the prefix filter is deleted from.
FILTER_ID
- ID of the prefix filter being deleted.
--force, -f
- Force the deletion operation without confirmation.
Examples
Delete prefix filter ID b4dbe0a6-c52d-4128-cc32-6f53d86bc82b
from gateway 9f559c43-63f4-4da5-b312-b525a8dce185
and connection 6c1bdc19-4adb-4760-8cdc-ef3b74b626f7
ibmcloud tg pfd 9f559c43-63f4-4da5-b312-b525a8dce185 6c1bdc19-4adb-4760-8cdc-ef3b74b626f7 b4dbe0a6-c52d-4128-cc32-6f53d86bc82b