Adding a cross-account connection
You can request connections to networks in other IBM Cloud accounts, by using the UI, CLI, and API.
Planning considerations
Before you add a cross-account connection, review these considerations:
-
After you connect a transit gateway to a network in another account, all resources that are connected to that transit gateway are accessible from the other network. Make sure that you use a trusted account. The following network connections are permitted as cross-account connections:
- Classic infrastructure
- VPC
- Unbound GRE Tunnel
- Direct Link
- Power System Virtual Server
-
Only 10 pending requests are allowed per gateway. To create more requests, you can cancel the pending connection request, or wait for it to be approved. Connection requests expire if not approved within 72 hours.
-
Use of security controls, such as ACLs, security groups, or other network services to control traffic flow are highly recommended. IBM Cloud Transit Gateway does not provide security groups or ACLs, but the networks they attach to might and can affect transit gateway communications. For more information on ACLs and security groups, refer to the following topics:
Adding a cross-account connection in the UI
To connect networks that different accounts own by using the UI, follow these steps:
-
From your browser, open the IBM Cloud console and log in to your account.
-
Select the Menu icon from the upper left, then click Interconnectivity.
-
Click Transit Gateway from the left navigation window.
-
Click the name of the transit gateway where you want to add a connection. Then, click Add connection.
-
Choose your network connection type. Then, select Request connection to a network in another account.
-
Type the CRN of the cross-account network, or if Classic infrastructure or Unbound GRE, enter the IBM Cloud account ID that you want to connect to.
- To get the IBM Cloud account ID for a Classic infrastructure or Unbound GRE tunnel connection, select Manage > Account from the IBM Cloud console and choose Account Settings. Your account ID shows in the Account section of the Account settings page.
- To get the CRN of a VPC, Direct Link, or Power Systems Virtual Server, select the Menu icon from the upper left, then click Resource list. Expand Networking (for VPC and Direct Link) or Computing (for Power Systems Virtual Server) to list your networking resources, then locate the service that you are looking for. Next, click anywhere in the service's table row (except for the Name link). From the side window that appears, copy the CRN and paste it into the Add connection pane.
-
Complete any remaining fields, then click Add. The network connection now shows the Pending approval status in the gateway owner's account.
For the Classic infrastructure connection, the ID number is for your IBM Cloud account, not for a SoftLayer account.
The network owner's account then receives a notification of the request. If the network owner rejects the cross-account connection, no connectivity is established and the connection shows a status of Rejected. You can now delete this connection. If the cross-account connection is not explicitly approved, it expires after 72 hours.
Connection requests can be resubmitted if they expire or are rejected.
-
A user with the necessary IAM permissions in the network owner's account can see the gateway and the details of all other connections that are attached to it in View only mode. From the network owner's account, go to the Transit Gateway page and click the gateway name in the table.
-
In the Connections section, see Action required to view the incoming network connection request. A user with the necessary additional IAM permissions can then click Approve to approve the request.
After the network owner's account ensures that the connection request is from a legitimate source and approves it, the system establishes routes to and from all other networks that are connected to the same transit gateway. Use of network ACLs and/or security groups within networks that are accessible across accounts are highly recommended to control the network traffic flows. You can unilaterally detach cross-account connections by either account through users who have the appropriate permissions.
Click Approve to confirm. The status of the network connection indicates Attaching.
-
When you change back to the original account, the status of the connection changes to Attached, indicating that the network request was approved.
The gateway owner's account (or the network owner's account) can delete the connection. If the network owner deletes the connection, the gateway owner sees the connection status as Detached.
Adding a cross-account connection from the CLI
Creating a cross-account connection consists of the following steps:
- Request connection to communicate with other account.
- Approve/Reject connection on other account.
For example, to request a connection to communicate with another account, run the following command:
ibmcloud tg connection-create|cc GATEWAY_ID --name NAME --network-type NETWORK-TYPE --network-id NETWORK_ID [-h, --help]
Where:
GATEWAY_ID
-
ID of the gateway that the new connection is on.
--name
-
Name of the new connection.
--network-type
-
Network type of the connection. Values are
classic
,vpc
,directlink
, orpower_virtual_server
.To create an unbound GRE tunnel connection, see the
ibmcloud tg connection-create-gre
command. --network-id
-
ID of the network connection. For
classic
connections, do not set a value. Use the CRN for all other network types. --output json
-
Optional. Specify whether you want the output to display in JSON format.
--help | -h
-
Optional. Get help on this command.
Examples
This example illustrates creating a VPC connection named vpc-connection
that 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
To create a classic connection named classic-conn
.
ibmcloud tg cc $gateway --name classic-conn --network-account-id 67123579566843320188712647902101 --network-type classic
To approve a connection from another account as the network owner, run the following command:
ibmcloud tg connection-approve|ca GATEWAY_ID CONNECTION_ID [-h, --help]
To reject a connection from another account as the network owner, run the following command:
ibmcloud tg connection-reject|cr GATEWAY_ID CONNECTION_ID [-h, --help]
For more information about available commands and options, see Connections in the Transit Gateway command reference.
Adding a cross-account connection with the API
To add a cross-account connection, follow these steps:
- Request a connection to communicate between other accounts.
- Perform actions on a requested connection. This must be completed.
For classic cross-account connections, be sure that the network-account-id
is set to the account you are requesting to communicate with. For VPC cross-account connections, be sure that the network-id
is set to the account
that you are requesting to communicate with.
Request cross-account connection
The original account must request a connection to communicate with the other account.
Request
To request a cross-account connection, set the following parameters:
Path parameters | Details |
---|---|
transit_gateway_id Required string |
The transit gateway identifier |
Query parameters | Details |
---|---|
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 latest version.Possible values: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ |
Request Body Required TransitGatewayConnectionTemplate |
The connection template |
network_type Required string |
Defines what type of network is connected using this connection. Allowable values: classic , vpc , unbound_gre_tunnel , directlink , or power_virtual_server Example: vpc |
name Name |
The user-defined name for this transit gateway connection. Network type vpc connections are defaulted to the name of the VPC. Network type classic connections are named Classic .Possible values: 1 ≤ length ≤ 63 , Value must match regular expression ^([a-zA-Z]-[a-zA-Z][-_a-zA-Z0-9]*[a-zA-Z0-9])$ Example: Transit_Service_BWTN_SJ_DL |
network_account_id AccountID |
The ID of the account, which owns the network that is being connected. Generally only used if the network is in a different account than the gateway. This field is used when gateway connection is in network type classic .This field is required to be unspecified for network type gre_tunnel .Example: 28e4d90ac7504be694471ee66e70d0d5 |
network_id string |
The ID of the network that is being connected using this connection. This field is required for vpc and directlink . This is the target CRN for network type vpc or directlink .This field is required to be unspecified for network type classic , gre_tunnel , and unbound_gre_tunnel connections.Example: crn:v1:bluemix:public:is:us-south:a/123456::vpc:4727d842-f94f-4a2d-824a-9bc9b02c523b |
Example request
This example illustrates the original account requesting a cross-account connection:
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}"
"name": "Transit_Service_BWTN_SJ_DL",
"network_id": "crn:v1:bluemix:public:is:us-south:a/123456::vpc:4727d842-f94f-4a2d-824a-9bc9b02c523b",
"network_type": "vpc",
"prefix_filters": [
{
"action": "permit",
"ge": 0,
"le": 32,
"prefix": "192.168.100.0/24"
}
],
"prefix_filters_default": "permit",
Response
The following response details show once you initiate the request:
Response Body | Details |
---|---|
name Always included* Name |
The user-defined name for this transit gateway connection. Possible values: 1 ≤ length ≤ 63 , Value must match regular expression ^([a-zA-Z]-[a-zA-Z][-_a-zA-Z0-9]*[a-zA-Z0-9])$ .Example: Transit_Service_BWTN_SJ_DL |
network_type Always included* string |
Defines what type of network is connected using this connection. The list of enumerated values for this property might expand in the future. Code and processes that use this field must tolerate unexpected values. Possible values: [ classic , directlink , vpc ]Example: vpc |
id Always included* string |
The unique identifier for this Transit Gateway Connection Example: 1a15dca5-7e33-45e1-b7c5-bc690e569531 |
created_at Always included* date-time |
The date and time that this connection was created |
network_id string |
The ID of the network that is being connected using this connection. This field is required for some types, such as vpc , power_virtual_server , and directlink .This is the target CRN for network type vpc Example: crn:v1:bluemix:public:is:us-south:a/123456::vpc:4727d842-f94f-4a2d-824a-9bc9b02c523b |
network_account_id AccountID |
The ID of the account, which owns the connected network. Generally only used if the network is in a different IBM Cloud account than the gateway. This value is used for network type classic .Example: 28e4d90ac7504be694471ee66e70d0d5 |
request_status string |
Only visible for cross-account connections, this field represents the status of a connection request between IBM Cloud accounts. The list of enumerated values for this property might expand in the future. Code and processes that use
this field must tolerate unexpected values. Possible values: [ pending ,approved ,rejected ,expired ,detached ] |
status string |
Connection's current configuration state. The list of enumerated values for this property might expand in the future. Code and processes that use this field must tolerate unexpected values. Possible values: [ attached ,failed ,pending ,deleting ,detaching ,detached ] |
updated_at date-time |
The date and time that this connection was last updated |
Status code | |
---|---|
201 | The transit gateway connection was created successfully. |
400 | An invalid connection template was provided. |
404 | The specified Transit Gateway cannot be found, the specified resource group cannot be found, or the default resource group cannot be found (if the resource group was not specified in the template). |
409 | The network that is being connected must either be in a location that is considered "local" to the specified Transit Gateway, or the specified Transit Gateway must be global. The network that is being connected cannot already be connected to another Transit Gateway. |
Example response
This example illustrates the response from a request for a cross-account connection:
{
"created_at": "2020-03-31T12:08:05Z",
"id": "1a15dca5-7e33-45e1-b7c5-bc690e569531",
"name": "example-connection",
"network_id": "crn:[...]",
"network_type": "vpc",
"status": "pending",
"updated_at": "2020-03-31T12:08:05Z"
}
Perform actions on a requested connection
After the original account requests a cross-account connection, the other account must perform actions on a requested connection.
Request
To perform actions on a requested cross-account connection, set the following parameters:
Query parameters | Details |
---|---|
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 latest version.Possible values: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ |
Request Body Required TransitGatewayConnectionActions |
The action template |
action Required string |
The action that is to be performed against the connection request Allowable values: [ approve ,reject ]Example: approve |
Example request
This example illustrates approving a cross-account connection:
"
{base_url}/transit_gateways/{transit_gateway_id}/connections/{id}/actions?version={version}"
{
"action": "approve"
}
Response
The following response results show once you initiate the request:
Status code | |
---|---|
204 | The connection approval/rejection was successful. |
403 | The caller is not authorized to perform the requested action, or the action was called by the gateway owning account. |
404 | A transit gateway or transit gateway connection with the specified identifier might not be found. |
409 | Attempted to approve a classic_access VPC connection. |
Example response
This example illustrates a Status 403 response in which the caller is not authorized to perform the requested action:
{
"errors": [
{
"code": "missing_field",
"message": "The `location` field is required.",
"more_info": "https://transitservice.cloud.ibm.com/",
"target": {
"name": "location",
"type": "field"
}
}
],
"trace": "86780a34-e651-4b47-9fb0-184a169cc9af"
}
For more information (including Java, Node, Python, and Go examples), see "Add Connection to a Transit Gateway" and "Perform actions on a connection for a Transit Gateway" in the Transit Gateway API reference.