Fleet Manager Golang Template

This project is an example fleet management service. Fleet managers govern service instances across a range of cloud provider infrastructure and regions. They are responsible for service placement, service lifecycle including blast radius aware upgrades,control of the operators handling each service instance, DNS management, infrastructure scaling and pre-flight checks such as quota entitlement, export control, terms acceptance and authorization. They also provide the public APIs of our platform for provisioning and managing service instances.

To help you while reading the code the example service implements a simple collection of dinosaurs and their provisioning, so you can immediately know when something is infrastructure or business logic. Anything that talks about dinosaurs is business logic, which you will want to replace with your our concepts. The rest is infrastructure, and you will probably want to preserve without change.

For a real service written using the same fleet management pattern see the kas-fleet-manager.

To contact the people that created this template go to zulip.

Prerequisites

• Golang 1.17+
• Docker - to create database
• ocm cli - ocm command line tool
• Node.js v12.20+ and npm

Using the template for the first time

The implementation talks about the main components of this template. To bootstrap your application, after cloning the repository.

1. Replace dinosaurs placeholder with your own business entity / objects
2. Implement code that have TODO comments

   // TODO

Running Fleet Manager for the first time in your local environment

Please make sure you have followed all of the prerequisites above first.

1. Follow the populating configuration guide to prepare Fleet Manager with its needed configurations

2. Compile the Fleet Manager binary

make binary

1. Create and setup the Fleet Manager database

   • Create and setup the database container and the initial database schemas

   make db/setup && make db/migrate
   

   • Optional - Verify tables and records are created

   # Login to the database to get a SQL prompt
   make db/login
   

   # List all the tables
   serviceapitests# \dt
   

   # Verify that the `migrations` table contains multiple records
   serviceapitests# select * from migrations;
   

2. Start the Fleet Manager service in your local environment

   ./fleet-manager serve
   

   This will start the Fleet Manager server and it will expose its API on port 8000 by default

   NOTE: The service has numerous feature flags which can be used to enable/disable certain features of the service. Please see the feature flag documentation for more information.

3. Verify the local service is working

   curl -H "Authorization: Bearer $(ocm token)" http://localhost:8000/api/dinosaurs_mgmt/v1/dinosaurs
   {"kind":"DinosaurRequestList","page":1,"size":0,"total":0,"items":[]}
   

   NOTE: Change dinosaur to your own rest resource

   NOTE: Make sure you are logged in to OCM through the CLI before running this command. Details on that can be found here

Using the Fleet Manager service

Interacting with Fleet Manager's API

See the Interacting with the Fleet Manager API subsection in the Populating Configuration documentation

Viewing the API docs

# Start Swagger UI container
make run/docs

# Launch Swagger UI and Verify from a browser: http://localhost:8082

# Remove Swagger UI conainer
make run/docs/teardown

Running additional CLI commands

In addition to starting and running a Fleet Manager server, the Fleet Manager binary provides additional commands to interact with the service (i.e. cluster creation/scaling, Dinosaur creation, Errors list, etc.) without having to use a REST API client.

To use these commands, run make binary to create the ./fleet-manager binary.

Then run ./fleet-manager -h for information on the additional available commands.

Fleet Manager Environments

The service can be run in a number of different environments. Environments are essentially bespoke sets of configuration that the service uses to make it function differently. Environments can be set using the OCM_ENV environment variable. Below are the list of known environments and their details.

• development - The staging OCM environment is used. Sentry is disabled. Debugging utilities are enabled. This should be used in local development. This is the default environment used when directly running the Fleet Manager binary and the OCM_ENV variable has not been set.
• testing - The OCM API is mocked/stubbed out, meaning network calls to OCM will fail. The auth service is mocked. This should be used for unit testing.
• integration - Identical to testing but using an emulated OCM API server to respond to OCM API calls, instead of a basic mock. This can be used for integration testing to mock OCM behaviour.
• production - Debugging utilities are disabled, Sentry is enabled. environment can be ignored in most development and is only used when the service is deployed.

The OCM_ENV environment variable should be set before running any Fleet Manager binary command or Makefile target

Additional documentation

• Adding new endpoint
• Adding new CLI flag
• Automated testing
• Deploying fleet manager via Service Delivery
• Requesting credentials and accounts
• Data Plane Setup
• Access Control
• Quota Management
• Running the Service on an OpenShift cluster
• Explanation of JWT token claims used across the fleet-manager

Contributing

See the contributing guide for general guidelines on how to contribute back to the template.