README
¶
API Scout :: Finding Your APIs In Kubernetes
What is API Scout
API Scout, helps you get up-to-date API docs to your developers by simply annotating your services in K8s.
What are the components of API Scout
The docker image that is deployed to Kubernetes has several components:
- The container itself is based on nginx:1.15-alpine
- The webapp is a staticly generated site by Hugo using the Learn theme and Swagger UI
- A server app that connects to the Kubernetes cluster using a default role to watch for services that need to be indexed
Hugo is downloaded and embedded during the build of the container
Build and run
API Scout has a Makefile that can be used for most of the operations. Make sure you have installed Go Programming Language, set GOPATH variable and added $GOPATH/bin in your PATH
usage: make [target]
| Makefile targets | Description |
|---|---|
| build-all | Performs clean-all and executes all build targets |
| build-docker | Builds a docker image from the dist directory |
| build-server | Builds the server app in dist |
| build-site | Builds the Hugo distribution in dist |
| clean-all | Removes the dist directory |
| clean-docker | Stops and removes all containers and images for apiscout |
| clean-kube | Removes the apiscout service and deployment from Kubernetes |
| deps | Get dependencies to build the server |
| minikube-delete | Delete the Minikube installation |
| minikube-install | Install Minikube on this machine |
| minikube-show | Show the API Scout UI that is deployed to Minikube |
| minikube-start | Start Minikube with default configuration |
| minikube-stop | Stop Minikube |
| run-docker | Runs a docker container with default settings |
| run-docs | Runs the embedded Hugo server on port 1313 for the documentation |
| run-hugo | Runs the embedded Hugo server on port 1313 |
| run-kube | Deploys apiscout to Kubernetes |
| run-server | Builds the in the server directory and runs it with default settings |
| stop-docker | Stop and remove the running apiscout container |
Requirements for Kubernetes
To be able to view the services, apiscout needs access to the Kubernetes cluster using the default service account. By default (pun intended) this account doesn't have access to view services so during deployment a new rolebinding is created. After starting, it will poll the Kubernetes API server every 10 seconds, or at the timeinterval specified by the environment variable INTERVAL.
apiscout looks for two annotations to be able to index a service:
apiscout/index: 'true'This annotation ensures that apiscout indexes the serviceapiscout/swaggerUrl: '/swaggerspec'This is the URL from where apiscout will read the OpenAPI document
Environment variables for the docker container
apiscout has a few environment variables that the docker container (and thus the deployment to Kubernetes) can use:
- SWAGGERSTORE: The location where to store the swaggerdocs
- HUGOSTORE: The location where to store content for Hugo
- MODE: The mode in which apiscout is running (can be either KUBE or LOCAL)
- EXTERNALIP: The external IP address of the Kubernetes cluster in case of LOCAL mode
- HUGODIR: The base directory for Hugo
License
See the LICENSE file
The logo made by Freepik from www.flaticon.com is licensed by CC 3.0 BY
Directories
¶
| Path | Synopsis |
|---|---|
|
samples
|
|
|
Package server implements the server of APIScout Package server implements the server of APIScout Package server implements the server of APIScout Package server implements the server of APIScout
|
Package server implements the server of APIScout Package server implements the server of APIScout Package server implements the server of APIScout Package server implements the server of APIScout |
|
util
Package util implements utility methods Package util implements utility methods Package util implements utility methods
|
Package util implements utility methods Package util implements utility methods Package util implements utility methods |