Welcome to the lunar.dev quickstart guide! This tutorial is designed to cover the basic steps of installing the two key components - Lunar Proxy and Lunar Interceptor - that allow lunar.dev to do its magic. Then we'll create a basic policy that shows how easy it is to control and optimize your API consumption.
Below, you'll find a helpful video introduction followed by detailed setup instructions for Docker or Kubernetes, and programming language-specific installations. Let's dive in.
docker run -d --rm -p 8000:8000 -p 8081:8081 -p 8040:8040 -e TENANT_NAME="ORGANIZATION" -v $(pwd):/etc/lunar-proxy --name lunar-proxy lunarapi/lunar-proxy:latest
:::caution
Note that the TENANT_NAME
environment variable is required. This variable should be set to the name of your organization.
:::
curl http://localhost:8040/healthcheck
A correct result should be proxy is up
.
curl http://localhost:8000/fact -H "x-lunar-host: catfact.ninja" -H "x-lunar-scheme: https"
Then, use the Discover command to validate that the requests were passed through Lunar Proxy.
docker exec lunar-proxy discover
helm repo add lunar https://thelunarcompany.github.io/proxy-helm-chart/
helm repo update
helm install lunar-proxy lunar/lunar-proxy --set tenantName=<name> --namespace lunar-proxy --create-namespace
Before installing Lunar's Proxy, ensure that the tenantName
is set to the name of your organization, for example: Acme
or Google
.
helm test lunar-proxy
curl http://localhost:8000/fact -H "x-lunar-host: catfact.ninja" -H "x-lunar-scheme: https"
Then, use the discover
command to validate that the requests were passed through Lunar Proxy.
kubectl exec <lunar-proxy-pod-name> -- discover
Lunar Interceptor needs to be imported to your app. In case you don't have a relevant app in place, refer to our Example Apps
pip3 install 'lunar-interceptor==0.4.*'
npm install lunar-interceptor
wget -O lunarInterceptor.jar https://s01.oss.sonatype.org/content/repositories/releases/dev/lunar/interceptor/lunar-interceptor/0.1.1/lunar-interceptor-0.1.1.jar
export LUNAR_PROXY_HOST="lunar-proxy:8000"
Note: The value assigned to LUNAR_PROXY_HOST should only include the hostname and port, without the HTTP prefix. For example, use "lunar-proxy:8000" and not "http://lunar-proxy:8000".
import lunar_interceptor
# imports ...
# your code
def main():
require("lunar-interceptor")
# imports ...
# your code
Enable the instrumentation agent by using the -javaagent
flag with the JVM.
export JAVA_TOOL_OPTIONS="-javaagent:PATH/TO/lunarInterceptor.jar"
Run your app and consume API traffic. Then, use the Discover command to validate that the requests were passed through Lunar Proxy, and that your installed interceptor is correctly listed.
docker exec lunar-proxy discover
kubectl exec <lunar-proxy-pod-name> -- discover
After validaing the succussful installation of both Lunar Interceptor and Lunar Proxy, configure a remedy policy for optimizaing your current API consumption.
Edit your policies.yaml
file with the following strategy-based-throttling
plugin configuration.
global:
remedies:
- name: Strategy Based Throttling Quick Start
enabled: true
config:
strategy_based_throttling:
allowed_request_count: 100
window_size_in_seconds: 60
response_status_code: 429
In the above example, the plugin will enforce a limit of 100 requests per minute for all requests. If the limit is exceeded, the plugin will return a 429 HTTP status code.
After making changes to your local policies.yaml
file, use the apply_policies
command to apply the new policies.
docker exec lunar-proxy apply_policies
Check out our demo video for a quick start here.
To try out Lunar without installing anything, check out our sandbox.
For any questions, feel free to reach out to us at info@lunar.dev.
To run tests:
cd proxy/integration-tests
pipenv install --dev
pipenv run behave
Linting is described here.
To run tests:
cd interceptors/integration-tests
pipenv install --dev
export CLIENT_LANGUAGE=python CLIENT_VERSION=3.10 # For Python tests
# OR
export CLIENT_LANGUAGE=java # For Java tests
pipenv run behave