- Notifications
You must be signed in to change notification settings - Fork6
lunar.dev: Ground Control for 3rd Party APIs
License
TheLunarCompany/lunar
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Lunar.dev's mission is to enable optimization and control of third-party API consumption in production environments. Lunar is a lightweight tool that empowers Software architects, DevOps and engineering teams to centralize consumption, gain insight and visibility into usage patterns and costs, and utilize out-of-the-box policies.
We've released a new version dedicated to production environments including advanced management and metric enhancement capabilities for companies. To gain access you will need a guided, hands-on experience to utilize the Lunar.dev platform as offered on our different tiers - via the website or reach out to us at Lunar.dev.
This project was born out of the need to have a better, and stable solution to managing 3rd party API consumption, and we're proud to keep it open-source at its core. It will remain free for personal use (not in production) Detailed information and documentation on the lunar.dev website.
Welcome to the lunar.dev quickstart guide! This tutorial is designed to cover the basic steps of installing the two key components - Lunar Gatway 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
:::cautionNote that theTENANT_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 beproxy is up.
curl http://localhost:8000/fact -H"x-lunar-host: catfact.ninja" -H"x-lunar-scheme: https"
Then, use theDiscover command to validate that the requests were passed through Lunar Proxy.
dockerexec lunar-proxy discoverhelm 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 thetenantName is set to the name of your organization, for example:Acme orGoogle.
helmtest lunar-proxycurl http://localhost:8000/fact -H"x-lunar-host: catfact.ninja" -H"x-lunar-scheme: https"
Then, use thediscover command to validate that the requests were passed through Lunar Proxy.
kubectlexec<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 ourExample 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.jarexport 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".
importlunar_interceptor# imports ...# your codedefmain():
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 theDiscover command to validate that the requests were passed through Lunar Proxy, and that your installed interceptor is correctly listed.
dockerexec lunar-proxy discoverkubectlexec<lunar-proxy-pod-name> -- discover
After confirming successful installation of lunar.dev, enhance your API consumption with a Lunar Flow.Think of it as a customizable tool that simplifies problem-solving and smoothens API interactions by establishing rules for different scenarios.
/etc/lunar-proxy/flows/flow.yaml
name:ClientSideLimitingFlowfilter:url:api.website.com/*processors:Limiter:processor:Limiterparameters: -key:quota_idvalue:MyQuotaGenerateResponseLimitExceeded:processor:GenerateResponseparameters: -key:statusvalue:429 -key:bodyvalue:"Quota Exceeded. Please try again later." -key:Content-Typevalue:text/plainflow:request: -from:stream:name:globalStreamat:startto:processor:name:Limiter -from:processor:name:Limitercondition:blockto:processor:name:GenerateResponseLimitExceeded -from:processor:name:Limitercondition:allowto:stream:name:globalStreamat:endresponse: -from:processor:name:GenerateResponseLimitExceededto:stream:name:globalStreamat:end -from:stream:name:globalStreamat:startto:processor:name:end
/etc/lunar-proxy/quotas/quota.yaml
quotas: -id:MyQuotafilter:url:api.website.com/*strategy:fixed_window:max:100interval:1interval_unit:minute
In the above example, the plugin will enforce a limit of 100 requests per minute theapi.website.com/* API endpoint. If the limit is exceeded, the plugin will return a Lunar-generated API response with 429 HTTP status code.
After you have alteredflow.yaml andquota.yaml according to your needs, run the load_flows command:
docker exec lunar-proxy load_flowsCheck out our demo video for a quick starthere.
To try out Lunar without installing anything, check out oursandbox.
For any questions, feel free to reach out to us atinfo@lunar.dev.
To run tests:
cd proxy/integration-testspipenv install --devpipenv run behaveLinting is describedhere.
To run tests:
cd interceptors/integration-testspipenv install --devexport CLIENT_LANGUAGE=python CLIENT_VERSION=3.10 # For Python tests# ORexport CLIENT_LANGUAGE=java # For Java testspipenv run behaveAbout
lunar.dev: Ground Control for 3rd Party APIs