walkthrough

Deployment Walk-through

The following walk-through explains how to run the lbAPI.

Compiling Source

• Clone this project
• If you are running Windows or Linux and have the Go libraries installed, you can run go build . inside of the project. This will create the lbapi binary.
• If you are running MacOS or Linux and have the build-essentials and Go libraries installed, you can run make build-all. All binaries will be saved inside of ./target
• If you are running Docker, you can use the Dockerfile located under the root of this project. There is also a docker-compose.yml file if you want to run that instead.

Environment Configuration

Application Ports (These ports can be re-mapped, using Docker)

• TCP 8080 HTTP
• TCP 8443 HTTPS (optional)

Files and Directories

• lbAPI requires an etc directory inside of the same directory where the binary is located.
• Inside of etc, the user must configure six files:
• config.toml (required)
• authentication.yaml (required)
• sign.key (required for LDAP and set in authentication.yaml)
• sign.crt (required for LDAP and set in authentication.yaml)
• lbm.key (required for HTTPS, and set in config.toml or ENV)
• lbm.crt (required for HTTPS, and set in config.toml or ENV)

Back-end Database

The back-end database is Postgres. All routes interact with the database in one form or another. Users can configure the database client by populating the [Database] fields inside of config.toml.

The database is meant to be ephemeral, and can dynamically be populated using the source API route. The only risk of data loss are the recycle and status tables. If a VIP is migrated, a status record is created, noting that it was migrated. If the database suffers a catastrophic loss or is re-created, that "migrated" status is lost, and it reverts to "deployed" if the VIP still lives on the load balancer. This will not change the actual "state" of the VIP, but how it's tracked at the API level.

The database must be present before running the binary. To quick start, you can use the following docker-compose.yaml file to create the database instance. Please note that this requires a custom docker network.

version: '3.3'
services:
  db:
    image: postgres
    restart: always
    environment:
      POSTGRES_DATABASE: lbmanagement
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: "MYSUPERSECRETPASSWORD"
    ports:
    - "5432:5432"
    volumes:
    - data:/var/lib/postgresql/data
networks:
  default:
    external:
      name: lbapi-net
volumes:
  data: {}

Infoblox Integration

This is an optional setting within config.toml. Infoblox is a network appliance that serves DNS, IPAM, DHCP, NTP services. The lbAPI was written to interact with Infoblox, allowing users to dynamically assign IPs and set DNS records for VIPs.

Git Integration

This is an optional setting within config.toml. This feature serves as a backup repository for vip changes.

LDAP Integration

LDAP authentication and authorization is handled by the authentication package. Details on how to configure the authentication.yaml file are listed there. The provided authentication.yaml file includes default route definitions. Please set fields accordingly.

Cross-Origin Resource Sharing (CORS)

This is an optional setting within config.toml. Populate this list with authorized domain origins for AJAX queries. If you plan to deploy the lbAPI-UI, you will need to set this value to permit AJAX calls from the UI.

Environmental Variables

The API supports both environmental variables and static config (.toml). Environmental variables are defined inside of config.config.go. The logic first checks to see if ./etc/config.toml exists. If this file is missing, it will fallback and check to see if the environmental variables are set.

Netscaler and AVI Integration

These sections are defined in the the config.toml. Please populate the credentials with the proper credentials for logging into the appliances. This should be a service account - not a user. This account will also need Administrator access on the appliances.

Audit Logging

Any changes made on the load balancer uses the service account set in config.toml. The authentication package, in conjunction with glog, captures which users performed the change. An admin can forward these logs to a SYSLOG collector for storage and analysis.

Start Up

• The lbAPI binary will run on Linux, Windows or MacOS.
• Prior to executing the binary, be sure to configure the files under ./etc (see above). The etc directory and required configuration files must reside in the same directory as the binary.
• For quick deployments, use the Dockerfile or Docker-Compose. The Docker file is defined to run the API as a non-root user.
• Following execution, the application will check to see if the required fields are set in the config.toml file.
• If debugging is enabled on main.go, you will see the following:

[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
 - using env:	export GIN_MODE=release
 - using code:	gin.SetMode(gin.ReleaseMode)

[GIN-debug] POST   /login                    --> git.tmaws.io/tmnet/authentication/gin.Login (4 handlers)
[GIN-debug] HEAD   /                         --> main.main.func1 (5 handlers)
[GIN-debug] GET    /                         --> main.main.func2 (5 handlers)
[GIN-debug] GET    /api/v1/loadbalancer      --> git.tmaws.io/tmnet/tools/lbapi/handler.Handler.Fetch-fm (5 handlers)
[GIN-debug] GET    /api/v1/loadbalancer/:id  --> git.tmaws.io/tmnet/tools/lbapi/handler.Handler.FetchByID-fm (5 handlers)
[GIN-debug] PUT    /api/v1/loadbalancer      --> git.tmaws.io/tmnet/tools/lbapi/handler.Handler.Modify-fm (5 handlers)
[GIN-debug] POST   /api/v1/loadbalancer      --> git.tmaws.io/tmnet/tools/lbapi/handler.Handler.Create-fm (5 handlers)
[GIN-debug] DELETE /api/v1/loadbalancer/:id  --> git.tmaws.io/tmnet/tools/lbapi/handler.Handler.Delete-fm (5 handlers)
[GIN-debug] POST   /api/v1/source/loadbalancer --> git.tmaws.io/tmnet/tools/lbapi/handler.Handler.ImportAll-fm (5 handlers)
[GIN-debug] GET    /api/v1/virtualserver     --> git.tmaws.io/tmnet/tools/lbapi/handler.Handler.Fetch-fm (5 handlers)
[GIN-debug] GET    /api/v1/virtualserver/:id --> git.tmaws.io/tmnet/tools/lbapi/handler.Handler.FetchByID-fm (5 handlers)
[GIN-debug] PUT    /api/v1/virtualserver     --> git.tmaws.io/tmnet/tools/lbapi/handler.Handler.Modify-fm (5 handlers)
[GIN-debug] POST   /api/v1/virtualserver     --> git.tmaws.io/tmnet/tools/lbapi/handler.Handler.Create-fm (5 handlers)
[GIN-debug] DELETE /api/v1/virtualserver/:id --> git.tmaws.io/tmnet/tools/lbapi/handler.Handler.Delete-fm (5 handlers)
[GIN-debug] POST   /api/v1/source/virtualserver --> git.tmaws.io/tmnet/tools/lbapi/handler.Handler.ImportAll-fm (5 handlers)
[GIN-debug] GET    /api/v1/simple/virtualserver --> git.tmaws.io/tmnet/tools/lbapi/handler.Handler.FetchVs-fm (5 handlers)
[GIN-debug] POST   /api/v1/backup/virtualserver --> git.tmaws.io/tmnet/tools/lbapi/handler.Handler.Backup-fm (5 handlers)
[GIN-debug] POST   /api/v1/migrate/virtualserver/:id --> git.tmaws.io/tmnet/tools/lbapi/handler.Handler.StageMigration-fm (5 handlers)
[GIN-debug] PUT    /api/v1/migrate/virtualserver/:id --> git.tmaws.io/tmnet/tools/lbapi/handler.Handler.Migrate-fm (5 handlers)
[GIN-debug] GET    /api/v1/migrate/virtualserver/:id --> git.tmaws.io/tmnet/tools/lbapi/handler.Handler.FetchStaged-fm (5 handlers)
[GIN-debug] GET    /api/v1/recycle           --> git.tmaws.io/tmnet/tools/lbapi/handler.Handler.Fetch-fm (5 handlers)
[GIN-debug] GET    /api/v1/recycle/:id       --> git.tmaws.io/tmnet/tools/lbapi/handler.Handler.FetchByID-fm (5 handlers)
[GIN-debug] PUT    /api/v1/recycle           --> git.tmaws.io/tmnet/tools/lbapi/handler.Handler.Modify-fm (5 handlers)
[GIN-debug] POST   /api/v1/recycle           --> git.tmaws.io/tmnet/tools/lbapi/handler.Handler.Create-fm (5 handlers)
[GIN-debug] DELETE /api/v1/recycle/:id       --> git.tmaws.io/tmnet/tools/lbapi/handler.Handler.Delete-fm (5 handlers)
[GIN-debug] Listening and serving HTTPS on :8443