Metal Billed Fabric Virtual Connections¶

To request a Fabric Virtual Connection, open the Project's Interconnections page. Click + Request New Interconnection.

In the Interconnection Type section, click the drop-down under Fabric VC, and select Metal Billed.

• Select the location for the new connection from the drop-down. You will want to select the metro where both your Equinix Metal infrastructure lives and the metro where the CSP you are connecting to on Fabric is: these interconnections are metro-bound.
• Give a name to your connection.
• Choose whether you want a set of redundant ports. Redundant ports are highly recommended. Selecting a single port may result in significant downtime due to planned and unplanned outages.
• Set the connection speed by selecting it from the drop-down. Note: the speed cannot be changed after a service token is issued. A new request and service token is required to change the speed.

Next, select whether you are attaching your ports to a VLAN or to a VRF.

• If you are using just VLANs, select the VLAN or VLANs that will be connected to your ports. The VLANs need to be in the same project and location as your Fabric VC. If you do not have any eligible VLANs, you can click + Create a VLAN to create them. The same VLAN can't be connected to two or more virtual circuits, so if you are requesting redundant ports, select a VLAN for each. Note: You will not be able to update or change the VLAN after the Fabric VC is created.

• If you are using VRF, select the VRF for your ports. There is additional documentation on the VRF for Interconnections page.

Review the summary of your request. Click Submit Request to receive your a-side service tokens.

Tokens expire in 7 days. You should also receive an email with your tokens and expiration information. On the Interconnections page, your newly requested Fabric Virtual Connection will be listed on the Pending Requests tab.

To request a Metal-billed Fabric VC in the CLI, use the metal interconnections create command.

metal interconnections create -p <project_id> -n <name> -m <metro> -r redundant -t shared -T z_side [--vlans <vlan_id>, <vlan_id> | --vrfs <vrf_uuid>, <vrf_uuid>]

Options:

• -p, --project-id (required) - Your Project's UUID.
• -r, --redundancy - Select primary or redundant. If you select a redundant connection, you will get a primary and secondary port to attach VLANs or VRFs to, increasing the connection's redundancy and high availability.
• -T, --service-token-type (required) - This parameter is required when requesting a Metal-billed Fabric Virtual Connection. Set the value to a_side.
• -t, --type (required) - This parameter is required when requesting a Fabric-billed Fabric Virtual Connection. Set the value to "shared".
• --vlan" - A list of VLAN IDs that will be used for the connection. If you select a redundant connection, the first VLAN in the list will be used for the primary port, and the second VLAN listed will be used for the secondary port. You can not connect the same VLAN to both ports; specify a different VLAN for each. Note: The vlan option is required if you are using VLANs. If you are using VRF, this field is NOT required. You will not be able to modify the VLANs after Fabric VC creation.
• --vrfs - A list of VRFs that will be used for the connection. If you select a redundant connection, the first VRF in the list will be used for the primary port, and the second VRF listed will be used for the secondary port. The two VRFs can be the same if both the primary and secondary ports will be in the same VRF. Note: The vrfs option is required if you are using VRFs. If you are using VLANs, this field is NOT required.

Note: Use either the "vlans" field or the "vrfs" field. They are mutually exclusive, and at least one or the other is required.

Sending the request creates generates your z-side service tokens. The tokens are included in the response object. If you requested a redundant connection, you will receive two tokens.

To request a connection through the API, send a POST request to the /projects/{project_id}/connections endpoint. If you are attaching VLANs to this Fabric VC, then use the "vlans" parameter in the request body. If you are using VRF, then use the "vrfs" parameter in the request body.

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/projects/{project_id}/connections" \
-d '{
    "name": "<string>",
    "description": "<string>",
    "contact_email": "<string>",
    "metro": "<metro_slug>",
    "type": "shared",
    "service_token_type": "a_side",
    "redundancy": "<redundant>",
    "speed": "<string>",
    "vlans": [ <integer>, <integer> ]  
}'

Body Parameters:

• "name" (required) - The name of your new Fabric Virtual Connection.
• "description" (optional) - A user-friendly description for your Fabric Virtual Connection.
• "contact_email" - The preferred email used for communication and notifications about the Interconnection. Required when using a Project API key. Optional and defaults to your user email address when using a User API key.
• "metro" (required) - Select the metro where both your Equinix Metal infrastructure and the CSP destination on Fabric is: these interconnections are metro-bound.
• "type" (required) - This parameter is required when requesting a Metal-billed Fabric Virtual Connection. Set the value to "shared".
• "service_token_type" (required) - This parameter is required when requesting a Metal-billed Fabric Virtual Connection. Set the value to a_side.
• "redundancy" (required) - Select "primary" or "redundant". If you select a redundant connection, you will get a primary and secondary port to attach VLANs or VRFs to, increasing the connection's redundancy and high availability.
• "vlans" - A list of VLAN IDs that will be used for the connection. If you select a redundant connection, the first VLAN in the list will be used for the primary port, and the second VLAN listed will be used for the secondary port. You can not connect the same VLAN to both ports; specify a different VLAN for each. Note: The "vlans" field is required if you are using VLANs. If you are using VRF, this field is NOT required. You will not be able to modify the VLANs after Fabric VC creation.
• "vrfs" - A list of VRFs that will be used for the connection. If you select a redundant connection, the first VRF in the list will be used for the primary port, and the second VRF listed will be used for the secondary port. The two VRFs can be the same if both the primary and secondary ports will be in the same VRF. Note: The "vrfs" field is required if you are using VRFs. If you are using VLANs, this field is NOT required.

Note: Use either the "vlans" field or the "vrfs" field. They are mutually exclusive, and at least one or the other is required.

Sending the request creates the Fabric VC on Equinix Medal and generates your Fabric tokens. The tokens are included in the response in the "service_tokens" object. If you requested a redundant connection, you will receive two tokens.

"service_tokens": [ 
    {
    “id”: "ff0cf4dc-a897-426d-9621-13e5b975058c",
    “role”: "primary",
    “state”: "inactive",
        “max_allowed_speed”: 50000000,
    “service_token_type”: "a_side",
    “expires_at”: "2019-09-30T20:22:20",
    }
],

Tokens expire in 7 days. You should also receive an email with your service tokens and expiration information. You can check on your request and retrieve the tokens during this window by sending a GET request to the /connections/{connection_id} endpoint.

curl -X GET -H 'X-Auth-Token: $API_TOKEN' \
"https://api.equinix.com/metal/v1/connections/{connection_id}"

Once the Interconnection is established between Fabric and Equinix Metal, it will appear on your Project's Interconnections page, in the Fabric VC section, with Active as the status. Billing starts when the status becomes Active on the the Fabric Virtual Connection.

• Fabric Billed Fabric Virtual Connections have type Fabric Billed.
• Metal Billed Fabric Virtual Connections have type Metal Billed.
• Interconnections that were set up as Shared Ports are indicated with type Legacy.

Note that Dedicated Ports are managed at the organization level, so if there are any Dedicated Ports in your organization, they will also appear in the Dedicated Ports section.

Clicking on the Interconnection's name brings you to its Overview page, which contains a detail view as well as a summary of the primary port and secondary port configurations.

Clicking either Primary Port or Secondary Port pulls up the port's status and configuration.

List all the Interconnections for your Project, including Metal-billed Fabric Virtual Connections, with the metal interconnections get command. Specify the Project with -p, or --project_id.

metal interconnections get -p <project_id>

Note: Dedicated Ports are managed at the organization level, and shared across Projects in the organization. If there are any Dedicated Ports in your organization, they will also appear in the response.

Get the details of a specific Fabric Virtual Connection with the metal interconnections get command, specifying the Fabric Virtual Connection by its UUID and -i or --connID.

metal interconnections get -i <fabric_vc_uuid>

To update a Fabric Virtual Connection, use the metal interconnections update command. The UUID of the Fabric Virtual Connection is required. All other fields are optional so they can be updated independently.

metal interconnections update -i <fabric_vc_uuid> -n <name> -d <description> -r <redundant|primary> -e <e-mail> --tags="<tag1>,<tag2>"

Options:

• -i, --id (required) - The UUID of the interconnection.
• -e, --contactEmail - Adds or updates the email contact for the Fabric Virtual Connection.
• -n, --name - Updates the name.
• -d, --description - Adds or updates the description.
• -r, --redundancy - Updating to primary will remove a secondary port, while updating to redundant will add a secondary port.
• -t, --tags - Adds or updates the tags.

To list all the Interconnections in a project, send a GET request to the /organizations/{organization_id}/connections endpoint, filtering the response to your project in the path of the request.

Note: Dedicated Ports are managed at the organization level, and shared across Projects in the organization. If there are any Dedicated Ports in your organization, they will also appear in the response.

curl -X GET -H 'X-Auth-Token: <API_TOKEN>' \
https://api.equinix.com/metal/v1/organizations/{organization_id}/connections?project={project_id}

To get the details of a Metal-billed Fabric VC, send a GET request to the /connections/{connection_id} endpoint, specifying the UUID in the request path.

curl -X GET -H 'X-Auth-Token: <API_TOKEN>' \
https://api.equinix.com/metal/v1/connections/{connection_id}

You can use this information to manage and update the Fabric Billed Fabric VC by sending a PUT request to the /connections/{connection_id} endpoint. Specify what you want changed in the body of the request. All fields are optional so they can be updated independently.

curl -X PUT \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/connections/{connection_id}" \
-d '{
    "contact_email": "<string>",
    "description": "<string>",
    "name": "<string>",
    "redundancy": "<string>",
    "tags": [
        "<string>"
    ]
}'

Body Parameters:

• "contact_email" - Adds or updates the email contact for the Fabric Virtual Connection.
• "name" - Updates the name.
• "description" - Adds or updates the description.
• "redundancy" - Updating to "primary" will remove a secondary port, while updating to "redundant" will add a secondary port.
• "tags" - Adds or updates the tags.

You can also get the port information of your Interconnections.

To get a list of a Metal Billed Fabric VC's ports, send a GET request to the /connections/{connection_id}/ports endpoint.

curl -X GET -H 'X-Auth-Token: <API_TOKEN>' \
https://api.equinix.com/metal/v1/connections/{connection_id}/ports

And to get one of the port's details, send a GET request to the /connections/{connection_id}/ports/{id} endpoint.

curl -X GET -H 'X-Auth-Token: <API_TOKEN>' \
https://api.equinix.com/metal/v1/connections/{connection_id}/ports/{id}

If you are using VRF on your Virtual Circuits, click on the three-bar menu to open the Manage Peering Details pane. Fill in the fields with the requested information.

This is where you specify the subnet from the VRF IP address range that will be used to address the VRF and the remote side of the virtual circuit. The IP address reservation for this subnet will be created automatically.

More detailed documentation is available on the VRF for Interconnections page.

Click Update Virtual Circuit.

If you have redundant ports, repeat this process on the Secondary Port.

To update your Virtual Circuit with the peering details for your VRF. Send a PUT request to the /virtual-circuits/{vrf_virtual_circuit_id} endpoint.

This is where you specify the subnet from the VRF IP address range that will be used to address the VRF and the remote side of the virtual circuit. The IP address reservation for this subnet will be created automatically.

For IPv4 subnets:

curl -X PUT \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/virtual-circuits/{vrf_virtual_circuit_id}" \
-d '{
    "peer_asn": <integer>,
    "subnet": "<subnet>",
    "metal_ip": "<ip_address>",
    "customer_ip": "<ip_address>”,
    "md5": "<string>"
}'

For IPv6 subnets:

curl -X PUT \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/virtual-circuits/{vrf_virtual_circuit_id}" \
-d '{
    "peer_asn": <integer>,
    "subnet_ipv6": "<subnet>",
    "metal_ipv6": "<ip_address>",
    "customer_ipv6": "<ip_address>”,
    "md5": "<string>"
}'

More detailed documentation is available on the VRF for Interconnections page.

From the list of connections on the Interconnections page, click the name of the Fabric Virtual Connection you want to delete.

Click Delete Interconnection to delete the Fabric Virtual Connection permanently.

To delete a Fabric Virtual Connection, use the metal interconnections delete command. Specify the UUID of the Fabric Virtual Connection with -i or --id. To skip the confirmation step, use -f or --force.

metal interconnections delete -i <uuid> -f

To delete a Fabric Virtual Connection from the API, send a DELETE request to the /connections/{connection_id} endpoint, specifying the ID of the port in the path.

curl -X DELETE -H 'X-Auth-Token: <API_TOKEN>' \
https://api.equinix.com/metal/v1/connections/{id}

Sending the request will delete the connection permanently. Usage/billing stops when the Metal Billed connection is deleted.