Skip to content

Latest commit

 

History

History
96 lines (78 loc) · 3.8 KB

README.md

File metadata and controls

96 lines (78 loc) · 3.8 KB

GeoIP WebAPI on Kubernetes

Objective

Deploy followings on Kubernetes:

  • geoipserver -- a simple web API server that reads a GeoLite2 database binary and echoes out latitude and longitude information for a given IP address
  • geoipupdate -- an updater that downloads a new version of the GeoLite2 database

Software requirement

  • Docker for Desktop with a local Kubernetes cluster
  • Go version 1.11+ (for Go modules support)
  • Tested on:
    • MacOS Docker Desktop Community version 2.1.0.5 (40693) stable
    • Kubernetes version 1.14.8
    • Go version 1.13.5

Quickstart

  • Deploy: make deploy or make all.
  • Destroy all deployed resources: make destroy-all

Simple test

  • To check if the service is properly running:
    • Go to localhost:8080 on browser, or
    • Run curl localhost:8080
    • Example: 
      $ curl localhost:8080
GeoIP WebAPI Server v0.1 on port 8080
Description: A simple web API server that reads GeoIP2/GeoLite2 database binary and echoes out latitude and longitude information for a given IP address

Database info:
  Type: GeoLite2-City
  Format Version: 2.0
  Build Timestamp: 2019-12-24T17:41:41Z

Usage:
  To get all fields: /api/{ipAddress}
  To get "location" fields: /api/{ipAddress}/location
  To get GPS coordinates: /api/{ipAddress}/location/coords
  • To obtain GPS coordinates of an IP address:
    • Go to localhost:8080/api/{ipAddress}/location/coords on browser, or
    • Run curl localhost:8080/api/{ipAddress}/location/coords
    • Example: 
      $ curl localhost:8080/api/72.36.89.1/location/coords
{"lat":40.1047,"lon":-88.2062}

Configuration

conf/cluster.conf

This file contains parameters used to generate Kubernetes manifests to be deployed.

  • DATABASE_DIR: an absolute path to a directory on local host where GeoIP database files will be downloaded to and read from
    • Current value: /tmp/GeoIP
    • Note: make sure this directory is allowed for file sharing on Docker for Desktop.
  • LOCALHOST_PORT: port to bind on localhost
    • Current value: 8080
  • NUM_SERVER_REPLICA: number of API server replicas
    • Current value: 3

conf/updater.conf

This file contains configuration for GeoIP database updater.

For our purpose, the configured parameters (i.e. AccountID, LicenseKey, EditionIDs) should be left as-is.

Deployment details

Resources are deployed in 3 steps:

  1. Make local persistent volumes: make makePV
  2. Create a cronjob for regularly updating the GeoLite2 database binary: make scheduleUpdates
    • To start the initial download, 1 job is manually created based on the scheduled cronjob.
  3. Deploy the GeoIP API server: make deployServer

Expected behaviors (assumptions)

  • Database binary updates run every 3 hours on Tuesdays starting at 00:00 in UTC.
    • See templates/scheduleUpdates.yml.tpl:L20.
  • The updater currently downloads updates with a default (invalid) AccountID/LicenseKey combination.
    • As of December 25th, 2019, this is still working. MaxMind update server may require a valid license in near future.
  • The updater keeps old versions of database binaries.
  • TERM signal is sent to GeoIP API server every 3 hours on Tuesdays starting at 00:30 in UTC.
    • See misc/server-entrypoint.sh:L14.
  • The server opens the database file using memory map or loads it into memory; changes to the database file or the symlink that points to the file (during updates) should not affect the server's operations.
  • GeoLite2 City database is used to obtain GPS coordinates.
    • The updater downloads the City database.
    • The server reads (and is intended to work only with) the City database.