Enabling Peer Replication

Page last updated:

You can configure a Service Registry service instance to replicate service registrations with a peer Service Registry service instance. This functionality can allow access to services registered with a Service Registry service instance in another PCF foundation.

Note: Peer replication can be used with Service Registry service instances in different orgs or spaces within the same PCF foundation, but for best performance, Pivotal recommends using service instance sharing to access a Service Registry service instance in the same foundation.

For information about the configuration parameters used to enable peer replication for a Service Registry service instance, see the Configuration Parameters section.

Configuration Parameters

To enable peer replication for a Service Registry service instance, you must specify the peer Service Registry instance’s URI using the peers JSON array, which contains an object for each Service Registry peer. You can find a Service Registry service instance’s URI on its dashboard (see Using the Dashboard).

A Service Registry peer can be expressed as shown in the following JSON:

{
  "peers": [
    { "uri": "https://service-registry-e280160b-d3e3-41ad-93a6-479f9b298ca6.example.net" }
  ]
}

Peer URIs must use the HTTPS URI scheme (as https://) and must follow the format https://service-registry-GUID.APPLICATION_DOMAIN.TLD, where GUID is the GUID assigned to a Service Registry service instance and APPLICATION_DOMAIN.TLD is the application domain of the PCF foundation where that Service Registry service instance is running.

Spring Cloud Services will by default validate the SSL certificate on each peer. You can disable this validation for a given peer by setting the skipSslValidation parameter to true for that peer, as shown in the following JSON:

{
  "peers": [
    { "uri": "https://service-registry-41562ac7-b6a6-4dc2-8a34-c1f94e82c83d.example.net",
      "skipSslValidation": true }
  ]
}

Note: If you disable certificate validation for a Service Registry service instance’s peer, you may need to set the TRUST_CERTS environment variable on apps bound to that Service Registry service instance or to the peer. See the Service Registry Peers with Self-Signed Certificates section of Writing Client Applications for more information.

The parameters used to configure a peer for the Service Registry are listed below.

Parameter Function
peers[i].uri The URI of the peer
peers[i].skipSslValidation Whether to skip SSL validation for the peer. Valid values: true, false (default: false)
peers[i].peer-timeout In milliseconds, the timeout used when connecting to the peer

To create or update a Service Registry service instance to replicate a registry with a peer service instance, allowing for validation of the peer’s SSL certificate and setting a peer connection timeout of 2,000 milliseconds, run one of the following commands:

$ cf create-service p.service-registry standard my-service-registry -c '{ "peers": [ {"uri": "https://service-registry-e280160b-d3e3-41ad-93a6-479f9b298ca6.example.net", "peer-timeout": 2000 } ] }'

$ cf update-service my-service-registry -c '{ "peers": [ {"uri": "https://service-registry-e280160b-d3e3-41ad-93a6-479f9b298ca6.example.net", "peer-timeout": 2000 } ] }'

To create or update a Service Registry service instance to replicate a registry with a peer service instance, skipping validation of the peer’s SSL certificate, run one of the following commands:

$ cf create-service p.service-registry standard service-registry -c '{ "peers": [ {"uri": "https://service-registry-e280160b-d3e3-41ad-93a6-479f9b298ca6.example.net", "skipSslValidation": true} ] }'

$ cf update-service service-registry -c '{ "peers": [ {"uri": "https://service-registry-e280160b-d3e3-41ad-93a6-479f9b298ca6.example.net", "skipSslValidation": true} ] }'

For an example of configuring peer replication across two Service Registry service instances, see the Setting Up Peer Service Instances section.

Important: If you provide a peer URI which does not correspond to an available Service Registry service instance (for example if there is a typo in the URI) or do not disable SSL certificate validation for a peer whose certificate cannot be verified, the cf create-service or cf update-service command may run successfully and the service instance status may be set to create succeeded or update succeeded, but the peer will not be used by the Service Registry service instance. In such a case, an error will appear on the Service Registry dashboard. See the Error Conditions section for more information.

Configuration Validation

A peer service instance URI is expected to meet the following criteria:

  • Use the HTTPS URI scheme (begin with https://). You cannot create or update a Service Registry service instance with a peer URI which does not use the HTTPS URI scheme.
  • Follow the pattern https://service-registry-GUID.APPLICATION_DOMAIN.TLD, where GUID is the GUID belonging to the peer service instance and APPLICATION_DOMAIN.TLD is the application domain of the PCF foundation on which that service instance is hosted. You cannot create or update a Service Registry service instance with a peer URI which does not follow this pattern.
  • Correspond to an available Spring Cloud Services 3.1.x Service Registry service instance. If you create or update a Service Registry service instance with a peer URI which does not correspond to another available service instance, you will see an error message on the Service Registry dashboard.

A peer service instance is expected to meet the following criteria:

  • Be from the same minor version of Spring Cloud Services (3.1.x). You cannot use a Spring Cloud Services 2.0.x Service Registry service instance as a peer for a Spring Cloud Services 3.1.x Service Registry service instance.
  • Have a peer list equivalent to its peer service instance’s peer list. If you create or update a Service Registry service instance with a peer that does has not have an equivalent peer list, you will see a warning message on the Service Registry dashboard.

Setting Up Peer Service Instances

If you wish to have two Service Registry service instances replicate a registry, you must configure each to have the other as a peer. If one service instance Service Registry A has a Service Registry B configured as a peer and B has no peers configured, A will share service registrations with B but B will not share registrations with A.

To configure two-way peer replication for two Service Registry service instances, follow the steps below.

  1. Create a Service Registry service instance A, without peers.

    $ cf create-service p.service-registry standard service-registry
    
  2. Visit A’s dashboard and copy its server URL.

    Pr copy url

  3. In the other PCF foundation, org, or space, create a Service Registry service instance B, with A as a peer.

    $ cf create-service p.service-registry standard service-registry-2 -c '{ "peers": [ { "uri": "https://service-registry-dda7d2ac-8f9f-4d06-b8e3-9ce5b82b930e.example.com" } ] }'
    
  4. Visit B’s dashboard and copy its server URL. You will see a warning message on B’s dashboard, because B currently has A as a peer and A currently has no peers.

    Pr copy peer url

  5. Update A, providing B as a peer.

    $ cf update-service service-registry -c '{ "peers": [ { "uri": "https://service-registry-5b251b82-672f-467b-8171-68e7948e6964.example.org" } ] }'
    

    A and B are now configured to replicate service registrations with each other.

Error Conditions

The Service Registry dashboard may show error or warning messages depending on the configuration and status of the service instance’s peer configuration. See the below sections for more information.

Peer Service Instance Not Found (404)

If you have configured a Service Registry service instance with a peer service instance URI that does not correspond to an available Service Registry service instance, you may see the following error message on the dashboard:

Dashboard peer not found

Double-check the URI of the peer listed in the error message. This can occur (for example) when there is a mistyped URI or when the service instance corresponding to the URI has been deleted.

Peer Service Instance SSL Certificate Not Verified

If you have configured a Service Registry service instance with a peer service instance that uses a self-signed SSL certificate and have not disabled certificate validation for the peer service instance, you may see the following error message on the dashboard:

Dashboard cert not verified

To enable the Service Registry service instance to replicate a registry with this peer service instance without a secure connection, you can update the configuration for this Service Registry service instance to disable SSL certificate validation for the peer. See the Configuration Parameters section for more information about configuring peer replication without SSL certificate validation.

Peer Service Instance Peer List Difference

If you have configured a Service Registry service instance with a peer service instance and the two service instances have differing lists of peer service instances, you may see the following message on the dashboard:

Dashboard different peer list

Update the configuration for this Service Registry service instance or for the peer instance to give them consistent peer lists.