Service profiles and service tokens

Finding and publishing service profiles, optimistic concurrency on replace, and delegating access with service tokens.

Service profiles#

A service profile describes a service that can be the Z-side of a connection. The cloud on-ramps are public profiles owned by the providers. A network service provider or an enterprise publishes private profiles for its own customers or business units.

Discovery#

Java

import com.eqixiac.equinix.fabric.model.ServiceProfile;
import com.eqixiac.equinix.fabric.model.implementation.filter.FilterPropertyList;
import com.eqixiac.equinix.fabric.model.implementation.filter.FilterType;

for (ServiceProfile profile : fabric.serviceProfiles()
        .search(new FilterPropertyList(FilterType.AND).equals("/visibility", "PUBLIC")).loadAll()) {
    System.out.println(profile.getUuid() + " " + profile.getName() + " " + profile.getType());
}

fabric.serviceProfiles().getMetros(profileUuid)
    .forEach(metro -> System.out.println(metro.getCode() + " " + metro.getName()));

The Metro Optimizer uses the same data to decide which metros reach which providers.

Update and concurrency#

PUT /serviceProfiles/{id} requires an If-Match header with the ETag of a preceding GET. The live service returns a quoted version number such as "5". In 4.0 the SDK reads the ETag and sends the header. Release 3.0.0 sent no header, and the service rejected the replace.

Java

fabric.serviceProfiles().update(profileUuid)
    .description("Layer 2 hand-off to the payments platform, 1G and 10G")
    .save();

If another client changes the profile between the read and the replace, the call fails with EquinixConflictException or with a 412 mapped to EquinixServiceException, and the caller reads the profile again before repeating the change.

Provider environments Beta#

getEnvironments(profileUuid) and validateActivationKey(...) are the two Beta operations on an IC_PROFILE service profile, described under Cloud-to-cloud.

Service tokens#

A service token lets another party create a connection to or from a resource you own without access to your account. With an A-side token the other party's connection starts on your port, and with a Z-side token it ends on your port.

Java

import com.eqixiac.equinix.fabric.enums.ConnectionType;
import com.eqixiac.equinix.fabric.enums.ServiceTokenType;
import com.eqixiac.equinix.fabric.enums.Side;
import com.eqixiac.equinix.fabric.model.ServiceToken;

ServiceToken token = fabric.serviceTokens().define(Side.Z_Side)
    .ofType(ServiceTokenType.VC_TOKEN)
    .withName("partner-acme-handoff")
    .withDescription("Acme Corp, production hand-off, DC6")
    .withExpirationDateTime(LocalDateTime.now().plusDays(14))
    .inProject(projectId)
    .forConnectionType(ConnectionType.EVPL_VC)
    .onPortUuid(portUuid)
    .usingProtocolDot1q(2100)
    .withSupportedBandwidths(List.of(100, 500, 1000))      // Mbps the partner may choose
    .withNotificationEmail("partner-noc@example.com")
    .dryRun()                                              // remove to issue the token
    .create();

The other party passes the token UUID when it creates the connection.

Java

import com.eqixiac.equinix.fabric.model.Connection;
import com.eqixiac.equinix.fabric.model.implementation.LinkProtocol;

Connection viaToken = fabric.connections()
    .define(ConnectionType.EVPL_VC)
    .name("acme-to-provider")
    .bandwidth(500)
    .aSideAccessPointPort(portUuid, LinkProtocol.dot1q().vlanTag(300).create())
    .zSideServiceToken(tokenUuid)
    .notification("noc@example.com")
    .create();

Tokens can also target a Network Edge virtual device (onVirtualDeviceUuid, withNetworkInterfaceId) or a network (onNetworkUuid).

Lifecycle#

Java

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

fabric.serviceTokens().update(tokenUuid)
    .expirationDateTime(LocalDateTime.now().plusDays(30))
    .dryRun()
    .save();

fabric.serviceTokens().createAction(tokenUuid, ServiceTokenAction.RESEND_EMAIL_NOTIFICATION);

Anyone who holds the token UUID can create a billable connection to your port within the limits of the token, so the UUID should be handled as a credential. withExpirationDateTime limits how long it is valid, and withSupportedBandwidths or withBandwidthLimit limits the bandwidth.

ServiceToken.getChangeLog() is populated in 4.0. The service sends the property as lowercase changelog, which 3.0.0 did not read.