Most Polygraph workloads use lots of IP and domain addresses. Some of those addresses are created specifically for the test; some are external to the test setup. The number of addresses and their complex dependencies/interactions can be overwhelming. Information below describes some of addressing principles used by Polygraph. Knowing these principles helps interpret and write PGL configurations correctly. We also show how to tell Polygraph to do the hard work for you.
1. Dependencies
1.1 Server Side
1.2 Client Side
1.3 Routing
2. Address creation
2.1 What needs to be created?
2.2 Run-time address creation
2.3 Prenatal address creation
Let's start with looking at how various addresses are used by Polygraph.
1.1 Server Side
Polygraph server agents listen on addresses specified in the addresses field of their configuration objects. Those addresses must have IP:port format. The addresses must exist at the time of agent creation, but may not exist at the time polysrv process starts up. In the latter case, you have to provide Polygraph with enough information to create the required address aliases run-time.
Servers know nothing about client-side IP addresses and address mappings described below. In other words, servers do not expect requests to come from certain addresses and do not check that requests are coming from those certain addresses.
1.2 Client Side
Polygraph robot agents bind to addresses specified in the addresses field of their configuration objects. Robots ignore port numbers in address specifications and addresses do not have to be unique. The addresses must exist at the time of agent creation, but may not exist at the time polyclt process starts up. In the latter case, you have to provide Polygraph with enough information to create the required address aliases run-time.
Robots send HTTP requests to the servers specified in the origins array, possibly via a proxy. An origin address may be a domain name (rather than an IP address) and/or can point to a ``virtual'' server. For example, robots' origin array contains VIPs in L4 server load balancing tests.
The important rule to remember is that if an origin name is not a member of any Server.addresses array, you must map that name into one or more server addresses using an AddrMap object. This mapping has nothing to do with TCP/IP connectivity, but it helps a robot to understand which servers are "behind" the names in the origins array, so that the robot can use proper URL extensions, for example.
By default, an IP address maps into itself. Thus, AddrMap is required only when using domain names or one-to-many IP mapping.
If forward proxies are used, a TCP connection will be established to the proxy. Otherwise, a robot will resolve the origin name (if needed) and then connect directly to the origin address. In both cases, HTTP request will be for a server at an origin address. Once again, that origin address might not be the IP:port address of a server agent but rather an address mapped into one or more of the server agent addresses.
1.3 Routing
Polygraph knows nothing about routing. Depending on your workload configuration, you may need to configure appropriate routes to direct traffic flow from robots to servers and back. These routes are created outside of Polygraph PGL configuration.
A common example where routing is required is when robots.addresses and server.addresses are not on the same network and no explicit proxying is used.
Most decent workloads require a lot of IP addresses. This section discusses two primary ways of creating a large number of IP addresses based on the workload description.
2.1 What needs to be created?
Polygraph processes bind individual robot and server agents to IP addresses specified in agent's addresses configuration field. Those addresses must exist at the time of binding. It is relatively easy to track what IP addresses need to be created by examining the addresses field and, if needed, the fields/expressions it depends on.
In the simplest case, the addresses field will be set to a constant array of IP addresses.
S.addresses = [ '10.13.129.1-250:80' ]; R.addresses = [ '10.13.1-4.1-250' ];The situation may become less transparent if a function call is used to compute the IP addresses based on the addressing scheme and the bench configuration. In this case, the description of the addressing scheme is necessary to figure out what addresses need to be created.
S.addresses = serverAddrs(asSpread, TheBench); R.addresses = robotAddrs(asPolyMix4, TheBench);Finally, it may be necessary to track dependencies from the addresses initialization to the original place of addresses calculation.
AddrMap map = { addresses = serverAddrs(asWebAxe4, TheBench); // calculated here name = TheVIP; }; S.addresses = map.addresses; // used hereIn all cases, the actual addresses used by Polygraph can be derived from PGL specification.
2.2 Run-time address creation
The simplest way to create the required IP addresses is to let Polygraph do it. By default, Polygraph will collect IPs from the addresses field of Robot and Server definitions use()d in the workload. These addresses must have a network interface name (e.g., fxp0::) and subnet (e.g., /32) so that Polygraph can create an IP alias on the right interface, with the right network mask.
The second required piece of information is the hosts array of the corresponding use()d Bench side. This array must contain primary (already existing) unique IP addresses, one per host.
Bench TheBench = { client_side = { hosts = [ '172.16.13.61-65' ]; addresses = ... // use to overwrite the default; optional }; }; use(TheBench); Robot R1 = { addresses = ... // aliases to create by default; required }; Robot R2 = { addresses = ... // more aliases to create by default; required }; use(R1, R2);The hosts field has two purposes. First, it tells Polygraph how many physical machines are available for the test. All agent IP addresses must be distributed evenly (and sequentially) across all hosts for the alias creation routine to proceed. Let's assume i-th host gets i-th group of N addresses. Second, it lets Polygraph process decide which group of N IP aliases need to be created on the host where the process is running.
Sometimes, individual agent addresses fields contain the right IPs in the wrong order. To tell Polygraph what the right order is, you can use the addresses field of the bench side. If that field is specified, Polygraph will ignore agent addresses fields and use the explicitly configured alias array instead.
After the future aliases are computed, Polygraph deletes all old aliases from the interface and creates new ones.
At the time of writing, Polygraph does not delete aliases after the test, but that behavior may change.
If Polygraph lacks the required info to create aliases, it logs a warning message and proceeds under the assumption that correct aliases already exist. The message should tell you what info is missing in case you want to fix the problem.
2.3 Prenatal address creation
The run-time alias creation algorithm has several hard-coded assumptions. Moreover, it relies on highly unportable code to create aliases. Thus, it is sometimes necessary to disable the algorithm and to create aliases manually.
To disable run-time alias creation, omit the information required for the creation algorithm (see above; for example, network interface name or hosts addresses can be omitted). If Polygraph lacks the required info, it displays a warning and proceeds under the assumption that correct aliases already exist.
For fast manual alias creation, use Polygraph's aka tool, if it works on your platform. Otherwise, use whatever tools came with your OS.
# aka lo0 10.13.1-4.1-250/22 lo0: reseting aliases to 10.13.1-4.1-250 lo0: primary address is 127.0.0.1 lo0: deleted 1000 old aliases lo0: created 1000 new aliases ( 1000 total ) # aka lo0 lo0: no new alias specified; will just delete old ones. lo0: primary address is 127.0.0.1 lo0: deleted 1000 old aliases