Skip to end of metadata
Go to start of metadata

Introduction

The Repose system-model.cfg.xml is the main configuration file for Repose. It outlines the entire deployment layout for the service cluster.  Repose must be aware of this in order to configure itself and correctly coordinate routing if necessary.  Additionally, the system model lets Repose know where the other Repose nodes reside. Using this information, Repose can coordinate its own clustering to help load balance or share data among nodes that share common filters.

Configurable parameters

System model XSD

ElementsAttributes

Required/

Optional

DescriptionVersion
<system-model>-RequiredTop level container.  Clusters (repose and service) are defined within this element
tracing-headerOptional

Default value is set to true.

See Tracing for more information. See the "tracing-header" element below for configuring this in Repose 8+.

7.1.2.0 – 7.3.5.0
rewrite-tracing-headerOptional

Determines if Repose will rewrite the X-Trans-ID header or adopt the one provided in the request.

If set to true, Repose will rewrite the X-Trans-ID header.
If set to false, Repose will pass the value that is received as the value for the x-trans-id header and use the value for the UUID in the logs.

Default value is set to false.

See Tracing  for more information. See the "rewrite-header" attribute below for configuring this in Repose 8+.

7.1.4.0 – 7.3.5.0
<repose-cluster>-RequiredDefines a cluster of Repose nodes.  Multiple Repose clusters can be defined within a system model.
idRequiredA unique id for this cluster within the system model.
rewrite-host-headerOptional

Determines if the Repose nodes in this cluster will rewrite the host header to contain the host and port of the origin service.

If set to true, Repose will rewrite the host header.

If set to false, Repose will pass the value that is received as the value for the host header.

Default is true.


<nodes>-RequiredSpecifies a list of nodes with attributes.
<node>-RequiredDefines a single node in the system model.
idRequiredDefines the service cluster's id which may be referenced elsewhere in various configuration files.
hostnameRequiredDefines the host name of this cluster member.
http-portOptional

Defines the port on which this node is listening for HTTP requests.

If the port is 0, Repose will not listen to the HTTP port.

Default is set to 0.


https-portOptional

Defines the port on which this node is listening for HTTPS requests.

If the port is 0, Repose will not listen to the HTTPS port.

Default is set to 0.


<filters>-OptionalSpecifies a list of filters that the proxy will execute in order of definition.

bypass-uri-regexOptionalRequests that match this regex will not go through the filter chain as presented. Anticipated usage is for health checks and monitoring of the origin service.8.2.0.0
<filter>-Required if using <filter>Defines a filter that is used to process and route requests.
nameRequired if using <filter>Defines the system context specific name of the filter module that is loaded.
idOptionalDefines the filter id.
uri-regexOptionalSpecifies the regular expression of which URI is allowed access.
configurationOptionalThe system context specific name of the filter's configuration.
<services>-OptionalLists the services that the proxy will execute in order of definition.
<service>-Required if using <service>Defines a sequence of services that are used to process and route requests.
nameRequired if using <service>The system context specific name of the service that is used.
<destinations>-RequiredDefines a list of target destinations reachable from a cluster.
<endpoint>-Required if using <destination>Defines a single node that is a target destination reachable from a cluster.
idRequired if using <destination>Defines the endpoint's id which will be referenced elsewhere in different configs
protocolOptional

Defines the endpoint's protocol. The current protocols that are permitted are HTTP and HTTPS.

If the protocol is not specified, internal dispatch is assumed.


hostnameOptional

Defines the endpoint's host name.

Default is set to localhost.


root-pathOptionalDefines the endpoint's base path element. This is used in building the URI or path to connect to the service. Any additional URI information will be appended to this.
portOptional

Defines the endpoint's port.

Default is set to 0. (internal dispatch)


defaultOptional

Specifies if this is the default endpoint destination if no applicable filter in the chain is fired.

Exactly one default endpoint destination must be identified.

Default is set to false.


<target>-OptionalDefines a cluster as a destination.  Repose uses a round robin algorithm to dispatch requests to the nodes in this target cluster.  The target cluster can be another Repose cluster or a service cluster.
idRequired if using <target>Defines the endpoint's id which will be referenced elsewhere in different configs
clusterRequired if using <target>Defines the destination cluster. Repose chooses a host from this cluster to handle a request.
protocolOptional

Defines the endpoint's protocol. The current protocols that are permitted are HTTP and HTTPS.

If the protocol is not specified, internal dispatch is assumed.


root-pathOptionalDefines the endpoint's base path element. This is used in building the URI or path to connect to the service. Any additional URI information will be appended to this.
portOptional

Defines the endpoint's port.

Default is set to 0. (internal dispatch)


defaultOptional

Specifies if this is the default endpoint destination if no applicable filter in the chain is fired.

  • Only one default endpoint destination can be identified.
  • The one exception to this rule is if there is only one endpoint destination defined, then it is assumed to be the default even if not configured as such.

Default is set to false.


<service-cluster>-OptionalA collection of nodes that provide equivalent functionality. If a service cluster represents a Repose cluster, it will contain a filter list and a destination list.
idRequiredA unique id for this cluster within the system model.
<nodes>-RequiredSpecifies a list of nodes with attributes.
<node>-RequiredDefines a single node in the system model.


idRequiredDefines the service cluster's id which may be referenced elsewhere in various configuration files.
hostname
Defines the host name of this cluster member.
http-portOptional

Defines the port on which this node is listening for HTTP requests.

If the port is 0, Repose will not listen to the HTTP port.

Default is set to 0.


https-portOptional

Defines the port on which this node is listening for HTTPS requests.

If the port is 0, Repose will not listen to the HTTPS port.

Default is set to 0.


<phone-home>-OptionalThe Phone Home service can report back to the Repose development team the list of filters configured in the System Model, the version of Repose being used, and the version of Java being used.  This enables the development team to focus on improving the features that get used the most.  Please consider enabling this service. 7.1.5.1

enabledRequired if using <phone-home>Whether or not to send the data to the Repose development team.  The contents of the message will be logged in your Repose logs whether or not the message is sent to the development team. 7.1.5.1

origin-service-idOptionalAn identifier we can use for your team or project (e.g. "Cloud Monitoring" or "Identity - Staging"). 7.1.5.1

contact-emailOptionalAn e-mail address the Repose development team can use to contact you with stakeholder questions from time to time. 7.1.5.1
<tracing-header>-Optional

Allows configuration of the tracing header.

If this element is not present, the tracing-header functionality will default to enabled and the rewrite-header will be disabled.

See Tracing for more information.

 8.0.0.0


enabledOptional

Configures whether or not to include the tracing header. Default value is set to true.

See Tracing for more information.

8.0.0.0 


rewrite-headerOptional

Determines if Repose will rewrite the X-Trans-ID header or adopt the one provided in the request.

If set to true, Repose will rewrite the X-Trans-ID header.
If set to false, Repose will pass the value that is received as the value for the x-trans-id header and use the value for the UUID in the logs.

Default value is set to false.

See Tracing for more information.

8.0.0.0 

secondary-plain-textOptionalDetermines if repose will write another header (X-Request-Id) with a plain text version of the request id that is contained within the X-Trans-Id header. This will overwrite any existing value in this header. This header is not considered a source of truth, but just a convenience for human readability.8.2.0.0

NOTE: Since port numbers below 1024 are privileged, Repose typically can NOT connect directly to them. There are several ways to go about getting around this, but one of the most generally accepted ways is to execute the following commands with root privilege (e.g. sudo):

redirect privileged ports
/sbin/iptables -t nat -I PREROUTING -p tcp --dport  80 -j REDIRECT --to-port 8080
/sbin/iptables -t nat -I PREROUTING -p tcp --dport 443 -j REDIRECT --to-port 8443

System model example

Repose 8

example system-model.cfg.xml - Repose 8
<?xml version="1.0" encoding="UTF-8"?>

<system-model xmlns="http://docs.openrepose.org/repose/system-model/v2.0">
  <repose-cluster id="repose">

    <nodes>
      <node id="node1" hostname="localhost" http-port="8088"/> <!-- localhost service instance will be started on specified port -->
      <!-- node id="node2" hostname="other-host" http-port="8088"/--> <!-- other hosts are not started, only commmunicated with -->
    </nodes>

    <filters>
      <filter name="http-logging" configuration="my-http-logging.xfg.xml"/>
      <filter name="client-auth" uri-regex=".*/servers/([-|\w]+)/?.*" />
      <!--filter name="api-validator" /-->
    </filters>
	
	<services>
	  <service name="dist-datastore" />
	</services>

     <destinations>
      <endpoint id="openrepose" protocol="http" hostname="www.openrepose.org" root-path="/" port="80" default="true"/>
      <target id="mocks" cluster="mocks-cluster" protocol="http" root-path="/" default="false"/>
    </destinations>

  </repose-cluster>
  
  <service-cluster id="mocks-cluster">
    <nodes>
      <node id="mock-node" hostname="50.57.189.15" http-port="8080" />      
    </nodes>
  </service-cluster>
 
  <phone-home enabled="true"
              origin-service-id="your-service"
              contact-email="your@service.com"/>
 
  <tracing-header rewrite-header="true"/>
</system-model>

Repose 7

 Click here to expand example config for Repose 7
example system-model.cfg.xml - Repose 7
<?xml version="1.0" encoding="UTF-8"?>

<system-model xmlns="http://docs.openrepose.org/repose/system-model/v2.0">
  <repose-cluster id="repose" rewrite-host-header="true">

    <nodes>
      <node id="node1" hostname="localhost" http-port="8088"/> <!-- localhost service instance will be started on specified port -->
      <!-- node id="node2" hostname="other-host" http-port="8088"/--> <!-- other hosts are not started, only commmunicated with -->
    </nodes>

    <filters>
      <filter name="http-logging" configuration="my-http-logging.xfg.xml"/>
      <filter name="client-auth" uri-regex=".*/servers/([-|\w]+)/?.*" />
      <!--filter name="api-validator" /-->
    </filters>
	
	<services>
	  <service name="dist-datastore" />
	</services>

     <destinations>
      <endpoint id="openrepose" protocol="http" hostname="www.openrepose.org" root-path="/" port="80" default="true"/>
      <target id="mocks" cluster="mocks-cluster" protocol="http" root-path="/" default="false"/>
    </destinations>

  </repose-cluster>
  
  <service-cluster id="mocks-cluster">
    <nodes>
      <node id="mock-node" hostname="50.57.189.15" http-port="8080" />      
    </nodes>
  </service-cluster>
</system-model>

Model definitions

cluster (service or Repose)

An entity that defines a collection of nodes, all of which provide equivalent functionality.  This element also defines service's scope within the system model. The service hosted on each node must be functionally equivalent at the API level.

A filter chain may be attached to a Repose cluster to identify the Repose HTTP message interception logic that must be performed by each node within the cluster.

endpoint

An endpoint is a special type of destination. An endpoint destination can specify an exact node to which requests can be routed. This element can contain protocol, hostname, root-path, and port elements that are used in constructing a route.  If the endpoint is within the same container as Repose, protocol, hostname and port are not specified.  

destinations

A Repose cluster must enumerate eligible routes to which HTTP messages can be forwarded. These are listed in the destinations section of the repose-cluster. If a destination is requested that is not listed in this section, a "service not available" code is returned. A valid destination can either be an endpoint or a target cluster. All nodes within the target cluster of a destination are considered eligible for routing and by default, Repose forwards to each node in round-robin order, starting at the top of the node sequence.

filter

An HTTP message interceptor that provides a specific piece of business functionality. A filter contains a Repose specific named reference.

filters

A sequence of filters that will intercept the request from the first filter of the sequence to the last enumerated filter in the sequence.

node (cluster node)

A named reference that may be used to locate a network endpoint. The hostname may be the human readable, string representation of an IPv4 or IPv6 address or a named reference that an IPv4 or IPv6 address.

service

A service is any served REST API bound to a TCP/IP address and port. A service is considered served and available so long as it is addressable and accessible to a separate processes (local or remote).

services

A sequence of services that will be loaded into the servlet context to be available for filters in the cluster.

target cluster

A target cluster is a type of destination that specifies another cluster (Repose or service) as a routing destination.  The target cluster element can contain cluster, protocol, root-path attributes.  Repose will choose a node from the target cluster as the target of the dispatch in a round-robin manner.

Repose deployment scenarios

Simple Pass-Through Proxy

<?xml version="1.0" encoding="UTF-8"?>

<!-- To configure Repose see: http://wiki.openrepose.org/display/REPOSE/Configuration -->
<system-model xmlns="http://docs.openrepose.org/repose/system-model/v2.0">
  <repose-cluster id="repose_cluster1">
    <nodes>
      <node id="repose_node1" hostname="localhost" http-port="8080"/>
    </nodes>

    <filters/>

    <services/>

    <destinations>
      <endpoint id="open_repose" protocol="http" hostname="openrepose.org" root-path="/" port="80" default="true"/>
    </destinations>
  </repose-cluster>
</system-model>

Nova-API localhost deployment

NOVA power-proxy.cfg.xml
<system-model xmlns="http://docs.openrepose.org/repose/power-api/system-model/v2.0">
   <repose-cluster id="nova-repose">
      <nodes>
         <node id="nova-n01" hostname="nova-n01.ord.internal.rackspace.corp" http-port="8080" https-port="8443" />
         <node id="nova-n02" hostname="nova-n02.ord.internal.rackspace.corp" http-port="8080" https-port="8443" />
      </nodes>
      
      <filters>
         <filter name="client-authentication" />
         <filter name="client-authorization" />
         <filter name="rate-limiting" />
      </filters>
 
      <services>
         <service name="dist-datastore" />
      </services>
 
      <destinations>
         <!-- hostname will default to localhost if not specified -->
         <endpoint id="local" protocol="http" port="8774" default="true"/>
      </destinations>
   </repose-cluster>
</system-model>

Logical


Root WAR (local servlet application-container routing) deployment

ROOT.war power-proxy.cfg.xml
<system-model xmlns="http://docs.openrepose.org/repose/power-api/system-model/v2.0">
   <repose-cluster id="root-war">
      <nodes>
         <node id="repose-n01" hostname="repose-n01.ord.internal.rackspace.corp" http-port="8080"/>
         <node id="repose-n02" hostname="repose-n02.ord.internal.rackspace.corp" http-port="8080"/>
      </nodes>

      <filters>
         <filter name="client-authentication" />
         <filter name="client-authorization" />
         <filter name="rate-limiting" />
      </filters>
      <services>
         <service name="dist-datastore" />
      </services>
   
      <destinations>
         <!-- hostname will default to localhost if not specified, port will default to 0 (internal dispatch) -->
         <endpoint id="internal" root-path="/somecontext" default="true" />
      </destinations>
   </repose-cluster>
</system-model>

Logical

Complex cluster layout with cluster routing

 
Complex power-proxy.cfg.xml
<system-model xmlns="http://docs.openrepose.org/repose/power-api/system-model/v2.0">
   
   <!-- REPOSE auth and versioning cluster. This will auth and determine which version of the request we are servicing -->
   <repose-cluster id="auth-vers">
      <nodes>
         <node id="av-n01" hostname="repose-nova-av-n01.ord.internal.rackspace.corp" http-port="8080" />
         <node id="av-n02" hostname="repose-nova-av-n02.ord.internal.rackspace.corp" http-port="8080" />
      </nodes>
      
      <filters>
         <filter name="client-authentication" />
         <filter name="client-authorization" />
         <filter name="versioning" />
      </filters>
      
      <!-- versioning will choose a destination based on uri rules. Must be one of these two -->
      <destinations>
         <target id="trans" cluster="legacy-translation" protocol="http"/>
         <target id="limiting" cluster="rate-limiting" protocol="http"/>
      </destinations>
   </repose-cluster>
   
   <!-- REPOSE translation cluster will translante 1.0 requests/responses to/from 2.0 -->
   <repose-cluster id="legacy-translation">
      <nodes>
         <node id="trans-n01" hostname="repose-csl-trans-n01.ord.internal.rackspace.corp" http-port="8080" />
         <node id="trans-n02" hostname="repose-csl-trans-n02.ord.internal.rackspace.corp" http-port="8080" />
      </nodes>

      <filters>
         <filter name="http-Logging" />
         <filter name="translation" />
      </filters>
   
      <!-- only destination available is rate limiting -->
      <destinations>
         <target id="limiting" cluster="rate-limiting" protocol="http" default="true" />
      </destinations>
   </repose-cluster>
   
   <!-- REPOSE rate limiting cluster -->
   <repose-cluster id="rate-limiting">
      <nodes>
         <node id="rl-n01" hostname="repose-nova-rl-n01.ord.internal.rackspace.corp" http-port="8080" />
         <node id="rl-n02" hostname="repose-nova-rl-n02.ord.internal.rackspace.corp" http-port="8080" />
      </nodes>
      
      <filters>
         <filter name="dist-datastore" />
         <filter name="rate-limiting" />
      </filters>
   
      <!-- only destination available is NOVA API -->
      <destinations>
         <target id="nova" cluster="nova-api" protocol="http" default="true"/>
      </destinations>
   </repose-cluster>

   <!-- NOVA service api cluster -->
   <service-cluster id="nova-api">
      <nodes>
         <node id="nova-n01" hostname="nova-n01.ord.internal.rackspace.corp" http-port="8080" />
         <node id="nova-n02" hostname="nova-n02.ord.internal.rackspace.corp" http-port="8080" />
      </nodes>
   </service-cluster>
</system-model>

Logical

  • No labels

3 Comments

  1. That ROOT.war power-proxy.cfg.xml example doesn't look to be a valid system-model.cfg.xml. Can you really embed another <system-model> element inside another <system-model> element?

    1. Shinta Smith

      You're absolutely correct – <system-model> elements cannot be nested. I'll correct that.

      To be honest, this page probably hasn't gotten the love it needs.

  2. I put this article on my list of updates. It will receive some love soon. 

    Thanks for pointing that out, Shinta.

    Thanks for fixing it, Damien.