Connections

Virtual connection types, access points on each side, cloud provider adapters, redundancy, updates and deletion.

Connection types#

A Fabric virtual connection joins an A-side access point to a Z-side access point, and the connection type determines which kinds of access point are valid on each side.

`ConnectionType`	Typical use	A-side	Z-side
`EVPL_VC`	Layer 2, VLAN-based	Port, virtual device, service token	Port, service profile (cloud or provider), service token
`EPL_VC`	Layer 2, whole port	Port	Port
`IP_VC`	Layer 3 from a Cloud Router	Cloud Router	Service profile, port, virtual device, network
`EVPLAN_VC`, `EPLAN_VC`, `EVPTREE_VC`, `EPTREE_VC`, `IPWAN_VC`	Attach to a Fabric network	Port, virtual device or Cloud Router	Network
`IA_VC`, `EIA_VC`	Internet Access	Port or virtual device	Internet Access service

Fabric accepts only IP_VC for a connection whose A-side is a Cloud Router.

Search and read#

Java

import com.eqixiac.equinix.core.http.response.PaginatedFilteredList;
import com.eqixiac.equinix.fabric.model.Connection;
import com.eqixiac.equinix.fabric.model.implementation.filter.FilterPropertyList;
import com.eqixiac.equinix.fabric.model.implementation.filter.FilterType;

PaginatedFilteredList<Connection> inProject = fabric.connections().search(
    new FilterPropertyList(FilterType.AND).equals("/project/projectId", projectId));

for (Connection c : inProject.loadAll()) {
    System.out.println(c.getUuid() + " " + c.getName() + " " + c.getBandwidth() + " Mbps " + c.getState());
}

Connection one = fabric.connections().getByUuid(connectionUuid);

Port to port#

Java

import com.eqixiac.equinix.fabric.enums.ConnectionType;
import com.eqixiac.equinix.fabric.enums.RedundancyPriority;
import com.eqixiac.equinix.fabric.model.implementation.LinkProtocol;

Connection evpl = fabric.connections()
    .define(ConnectionType.EVPL_VC)
    .name("dc-to-ny-primary")
    .bandwidth(1000)                                               // Mbps
    .redundancy("dc-ny", RedundancyPriority.PRIMARY)               // group name, priority
    .aSideAccessPointPort(portUuid, LinkProtocol.dot1q().vlanTag(1200).create())
    .zSideAccessPointPort(secondaryPortUuid, LinkProtocol.dot1q().vlanTag(1200).create())
    .project(projectId)
    .notification("noc@example.com")
    .create();

LinkProtocol.dot1q(), LinkProtocol.qinq() and LinkProtocol.untagged() build the three encapsulations. The tag must be free on the port, see VLAN usage.

Port to a cloud provider#

The Z-side of a cloud connection is the provider's service profile plus an authentication key that the provider issues. A cloud adapter carries those values, the provider region and the Equinix metro where the provider is reached.

Adapter	Authentication key	Region	Factory arguments
`AwsDirectConnectAdapter`	12-digit AWS account ID	`us-east-1`	account ID, region, profile UUID, metro
`AzureExpressRouteAdapter`	ExpressRoute service key (GUID)	none; the service key fixes it	service key, profile UUID, peering type, metro
`GoogleCloudInterconnectAdapter`	Partner Interconnect pairing key	`us-east4`	pairing key, region, profile UUID, metro
`OracleFastConnectAdapter`	FastConnect virtual circuit OCID	`us-ashburn-1`	OCID, region, profile UUID, metro

Java

import com.eqixiac.equinix.fabric.enums.PeeringType;
import com.eqixiac.equinix.fabric.model.implementation.cloud.AwsDirectConnectAdapter;
import com.eqixiac.equinix.fabric.model.implementation.cloud.AzureExpressRouteAdapter;
import com.eqixiac.equinix.fabric.model.implementation.cloud.GoogleCloudInterconnectAdapter;
import com.eqixiac.equinix.fabric.model.implementation.cloud.OracleFastConnectAdapter;

var aws    = AwsDirectConnectAdapter.of("123456789012", "us-east-1", awsProfileUuid, "DC");
var azure  = AzureExpressRouteAdapter.of("00000000-0000-0000-0000-000000000000", azureProfileUuid, PeeringType.PRIVATE, "DC");
var google = GoogleCloudInterconnectAdapter.of("pairing-key/us-east4/2", "us-east4", gcpProfileUuid, "DC");
var oracle = OracleFastConnectAdapter.of("ocid1.virtualcircuit.oc1.iad.example", "us-ashburn-1", oracleProfileUuid, "DC");

Connection toAws = fabric.connections()
    .define(ConnectionType.EVPL_VC)
    .name("dc-port-to-aws")
    .bandwidth(500)
    .aSideAccessPointPort(portUuid, LinkProtocol.dot1q().vlanTag(1000).create())
    .zSideCloudProvider(aws)                 // profile, key, region and metro come from the adapter
    .notification("noc@example.com")
    .dryRun()                                // validate first; remove to create
    .create();

zSideCloudProvider(adapter) sends no Z-side link protocol, which matches the cloud examples in the Fabric specification. zSideCloudProvider(adapter, linkProtocol) adds one, and the three-argument form overrides the adapter's metro.

The following block finds the service profile UUID of a provider by name and lists the metros in which the profile is offered.

Java

import com.eqixiac.equinix.fabric.model.ServiceProfile;

for (ServiceProfile profile : fabric.serviceProfiles().search().loadAll()) {
    if (profile.getName().contains("AWS Direct Connect")) {
        System.out.println(profile.getUuid() + " " + profile.getName());
        fabric.serviceProfiles().getMetros(profile.getUuid())
            .forEach(metro -> System.out.println("  " + metro.getCode()));
    }
}

Adapter for another provider#

Implement CloudProviderConnectionAdapter<T> for a provider without a built-in adapter. T is the type of the provider SDK object the adapter wraps, or Void.

Java

import com.eqixiac.equinix.fabric.model.implementation.cloud.CloudProviderConnectionAdapter;
import com.eqixiac.equinix.fabric.model.implementation.cloud.CloudProviderType;

public class IbmDirectLinkAdapter implements CloudProviderConnectionAdapter<Void> {
    private final String serviceKey, region, profileUuid, metro;

    public IbmDirectLinkAdapter(String serviceKey, String region, String profileUuid, String metro) {
        this.serviceKey = serviceKey; this.region = region; this.profileUuid = profileUuid; this.metro = metro;
    }
    @Override public String getServiceProfileUuid() { return profileUuid; }
    @Override public String getAuthenticationKey()  { return serviceKey; }
    @Override public String getSellerRegion()       { return region; }
    @Override public String getMetroCode()          { return metro; }
    @Override public Void getSource()               { return null; }
    @Override public CloudProviderType getProviderType() { return CloudProviderType.IBM_CLOUD; }
}

An adapter makes no call to the provider. Accepting the hosted connection in AWS, creating the ExpressRoute circuit and creating the VLAN attachment in Google Cloud are done with the provider's own tooling.

Cloud Router to a provider#

Java

import com.eqixiac.equinix.fabric.model.CloudRouter;

CloudRouter router = fabric.cloudRouters().getByUuid(routerUuid);
var azureDc = AzureExpressRouteAdapter.of("00000000-0000-0000-0000-000000000000", azureProfileUuid, PeeringType.PRIVATE, "DC");

Connection fcrToAzure = fabric.connections()
    .define(ConnectionType.IP_VC)
    .name("fcr-dc-to-azure")
    .bandwidth(1000)
    .aSideAccessPointCloudRouter(router)
    .zSideCloudProvider(azureDc)
    .notification("noc@example.com")
    .create();

A Cloud Router connection needs routing protocols before it carries traffic, see Cloud Routers and routing.

Redundancy#

Fabric models redundancy as two connections in one redundancy group, one PRIMARY and one SECONDARY. Create the primary with redundancy(group, RedundancyPriority.PRIMARY) and the secondary with the same group name and SECONDARY. The two connections take physically separate paths only when their A-side ports are on different Fabric devices, which is decided when the ports are ordered.

Update#

connection.update() returns an updater that sends JSON Patch operations, and dryRun() on the updater validates the change without applying it.

Java

import com.eqixiac.equinix.fabric.enums.Side;

Connection connection = fabric.connections().getByUuid(connectionUuid);

connection.update().bandwidth(2000).dryRun().save();     // validate
connection.update().bandwidth(2000).save();              // apply

connection.update().name("dc-to-ny-primary-v2").save();
connection.update().vlanTag(Side.A_Side, 1300).save();   // migrate the A-side VLAN

The provider side limits a bandwidth change on a cloud connection. For example, an Azure ExpressRoute circuit cannot be reduced below its provisioned size.

Routes on a connection#

Java

import com.eqixiac.equinix.fabric.model.RouteTableEntry;

for (RouteTableEntry route : fabric.connections().searchReceivedRoutes(connectionUuid)) {
    System.out.println(route.getPrefix() + " via " + route.getNextHop() + " AS path " + route.getAsPath());
}
fabric.connections().searchAdvertisedRoutes(connectionUuid);

Delete#

Java

Connection gone = fabric.connections().getByUuid(connectionUuid);
gone.delete();

The service deletes a connection asynchronously, and refresh() reads the current state. A teardown that may run twice should catch EquinixNotFoundException for a connection that is already gone.

Beta access-point properties Beta#

SimpleAccessPoint.define(...).activationKey(...) and .environment(...) set the two access-point properties that the Fabric catalog added for provider-to-provider links, and ConnectionBuilder.zSideAccessPoint(SimpleAccessPoint) accepts the result. The catalog publishes no connection-create example that sets either property, so send such a request with dryRun() first. Cloud-to-cloud describes the related operations.