Amundsen Search Service

Amundsen Search service serves a Restful API and is responsible for searching metadata. The service leverages Elasticsearch for most of it's search capabilites.

For information about Amundsen and our other services, visit the main repository README.md. Please also see our instructions for a quick start setup of Amundsen with dummy data, and an overview of the architecture.

Requirements

Python >= 3.6
elasticsearch 6.x (currently it doesn't support 7.x)

Doc

https://www.amundsen.io/amundsen

Instructions to start the Search service from distribution

$ venv_path=[path_for_virtual_environment]
$ python3 -m venv $venv_path
$ source $venv_path/bin/activate
$ pip3 install amundsen-search
$ python3 search_service/search_wsgi.py

# In a different terminal, verify the service is up by running
$ curl -v http://localhost:5001/healthcheck

Instructions to start the Search service from source

$ git clone https://github.com/amundsen-io/amundsensearchlibrary.git
$ cd amundsensearchlibrary
$ venv_path=[path_for_virtual_environment]
$ python3 -m venv $venv_path
$ source $venv_path/bin/activate
$ pip3 install -r requirements.txt
$ python3 setup.py install
$ python3 search_service/search_wsgi.py

# In a different terminal, verify the service is up by running
$ curl -v http://localhost:5001/healthcheck

Instructions to start the service from Docker

$ docker pull amundsendev/amundsen-search:latest
$ docker run -p 5001:5001 amundsendev/amundsen-search
# - alternative, for production environment with Gunicorn (see its homepage link below)
$ ## docker run -p 5001:5001 amundsendev/amundsen-search gunicorn --bind 0.0.0.0:5001 search_service.search_wsgi

# In a different terminal, verify the service is up by running
$ curl -v http://localhost:5001/healthcheck

Production environment

By default, Flask comes with a Werkzeug webserver, which is used for development. For production environments a production grade web server such as Gunicorn should be used.

$ pip3 install gunicorn
$ gunicorn search_service.search_wsgi

# In a different terminal, verify the service is up by running
$ curl -v http://localhost:8000/healthcheck

For more imformation see the Gunicorn configuration documentation.

Configuration outside local environment

By default, Search service uses LocalConfig that looks for Elasticsearch running in localhost. In order to use different end point, you need to create a Config suitable for your use case. Once a config class has been created, it can be referenced by an environment variable: SEARCH_SVC_CONFIG_MODULE_CLASS

For example, in order to have different config for production, you can inherit Config class, create Production config and passing production config class into environment variable. Let's say class name is ProdConfig and it's in search_service.config module. then you can set as below:

SEARCH_SVC_CONFIG_MODULE_CLASS=search_service.config.ProdConfig

This way Search service will use production config in production environment. For more information on how the configuration is being loaded and used, here's reference from Flask doc.

Developer guide

Code style

PEP 8: Amundsen Search service follows PEP8 - Style Guide for Python Code.
Typing hints: Amundsen Search service also utilizes Typing hint for better readability.

API documentation

We have Swagger documentation setup with OpenApi 3.0.2. This documentation is generated via Flasgger. When adding or updating an API please make sure to update the documentation. To see the documentation run the application locally and go to localhost:5001/apidocs/. Currently the documentation only works with local configuration.

Code structure

Amundsen Search service consists of three packages, API, Models, and Proxy.

API package

A package that contains Flask Restful resources that serves Restful API request. The routing of API is being registered here.

Proxy package

Proxy package contains proxy modules that talks dependencies of Search service. There are currently two modules in Proxy package, Elasticsearch and Statsd.

Elasticsearch proxy module

Elasticsearch proxy module serves various use case of searching metadata from Elasticsearch. It uses Query DSL for the use case, execute the search query and transform into model.

Atlas proxy module

Apache Atlas proxy module uses Atlas to serve the Atlas requests. At the moment the Basic Search REST API is used via the Python Client.

Statsd utilities module

Statsd utilities module has methods / functions to support statsd to publish metrics. By default, statsd integration is disabled and you can turn in on from Search service configuration. For specific configuration related to statsd, you can configure it through environment variable.

Models package

Models package contains many modules where each module has many Python classes in it. These Python classes are being used as a schema and a data holder. All data exchange within Amundsen Search service use classes in Models to ensure validity of itself and improve readability and maintainability.

Dee-Pac/amundsensearchlibrary