(This document is still Work In Progress!)
Performance test tool design
The general goal is to have an extendable performance test framework that will drive the Knox Gateway configured by different use cases.
Some initial requirements of this framework:
- easy to extend with new use-cases
- has the ability to execute long-running jobs
- has the ability to connect to it and query different metrics
- generate meaningful and easy-to-read reports of those metrics automatically (in configurable time periods)
In the first phase, the task was to conduct and codify performance testing for scalability and performance benchmarking with concurrent clients, with long-running jobs that stress the backend of the token state server store:
- use different token state server implementations
- turn on/off the token state service mechanism
- use concurrent clients who dealing with tokens (make sure they actually use the tokens and periodically renew them)
The tool itself is fed by its own configuration file located in $YOUR_KNOX_PROJECT_ROOT/gateway-performance-test/src/test/resources/performance.test.configuration.properties
:
# Gateway connection related properties perf.test.gateway.url.protocol=https perf.test.gateway.url.host=localhost perf.test.gateway.url.port=8443 perf.test.gateway.jmx.port=8888 # report generation related properties perf.test.report.generation.periodInSecs=30 perf.test.report.generation.json.enabled=true perf.test.report.generation.yaml.enabled=true # Knox Token use case related properties perf.test.usecase.knoxtoken.enabled=true perf.test.usecase.knoxtoken.topology.gateway=sandbox perf.test.usecase.knoxtoken.topology.tokenbased=tokenbased perf.test.usecase.knoxtoken.numOfThreads=3 perf.test.usecase.knoxtoken.testDurationInSecs=60 perf.test.usecase.knoxtoken.requestDelayLowerBoundInSecs=5 perf.test.usecase.knoxtoken.requestDelayUpperBoundInSecs=10
Knox gateway requisites
The performance test tool tries to connect to a Knox instance to
- acquire/renew/use Knox delegation tokens using its token API (/knoxtoken/api/v1/token)
- fetch useful metrics via JMX
To be able to execute the last item, before running the Knox gateway you are testing against, the following configuration should be done:
- Set
KNOX_GATEWAY_DBG_OPTS
environment variable as follows:
export KNOX_GATEWAY_DBG_OPTS="$KNOX_GATEWAY_DBG_OPTS -Dcom.sun.management.jmxremote.port=8888 -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false"
2. Enable JMX reporting in gateway-site.xml:
<property> <name>gateway.metrics.enabled</name> <value>true</value> </property> <property> <name>gateway.jmx.metrics.reporting.enabled</name> <value>true</value> </property>
How to run
Running the performance tool is as simple as running the following Maven command in the project root:
mvn -DskipTests -Dcheckstyle.skip=true -Dfindbugs.skip=true -Dpmd.skip=true -Drat.skip -Pgateway-performance-test package -am -pl gateway-performance-test
The tool will pick up the above-mentioned configuration file and execute all enabled use-case runners (currently there is only one implementation). You can make the desired changes in that properties file before executing your performance test rounds as your requirements needs. For instance, increasing the number of parallel threads to 10 and the test duration to 6 hours you need to update
perf.test.usecase.knoxtoken.numOfThreads=10 perf.test.usecase.knoxtoken.testDurationInSecs=21600