See https://github.com/akkeris/contributing/blob/master/akkeris%20systems.pdf for a visual overview of the architecture of akkeris. The lines represent dependencies between systems. This is fairly high level but should give enough information to see how components are interdependent.

This article does not intend to give a road map but explain where current state of Akkeris architecture is circa mid-2018.

Each kubernetes runtime is considered a stack in Akkeris. There may be multiple kube "stacks" running in any one region.

The controller api is contained at akkeris/controller-api. The controller should only exist once for all regions and all stacks. It is the one "source of truth" on what should be running in (or on) any region or stack. It is NOT the source of truth on what IS running however.

The purpose of a controller is to:

1. Build code and produce an image on the appropriate image store.
2. Coordinate deployments of code (e.g., create groupings of processes into one app).
3. Provide workflow to promote code to one or more stacks in any region necessary (e.g., pipelines).
4. Provide a single API for clients to integrate with and abstract away regional and stack complexities.
5. Serve as a catalog of services among a variety of regions for end users to provision resources
6. Provide authentication and compliance controls (in addition to audit logging).
7. Integrate with source control systems to listen for changes and create build.
8. Fire web hooks and notifications to inform other systems of changes.
9. Provide cross "Soft services" such as twilio and papertrail integrations.

The repo akkeris/region-api contains the API that manages the following. A region must have the following properties:

1. Low latency connections between all elements in the region including service brokers.
2. Ability to address each other as if they are on a private network (not necessarily the same subnets, but not firewalled).
3. Have the same ingress controllers and ingress controllers which can route to any address over MUTLIPLE kube stacks.
4. Ability to broker or provision services for underlying stack's processes (think provision databases).
5. Instruct the ingress on how to route traffic to one-or-more process running on a stack in its region.
6. Provision and install certificates and domains as necessary.

The purpose of a region is to:

1. Support clusters in different zones (not just different availability zones)
2. Different legal or compliance requirements
3. Promote SOME specific types of resource reuse among zones
4. Easy multi-regional development promotion and deployments.

Stacks are just kubernetes instances, that said a stack must have the following property:

1. It must have a concept of a space that can support direct (real low latency) communication between apps, via http or other fast (albeit potentially un-secure) connections
2. A runtime capable of running dockerized images
3. Support one-off process runs
4. Support crontab process runs
5. Support networked processes
6. Support of quality of service mechanisms across nodes.

The purpose of multiple stacks is:

1. Allow future support of clusters as cattle, not pets (e.g., we don't upgrade, we just kill the old cluster and move to a new version of it).
2. Support ability for hybrid clouds where scalable/experimental apps may be placed on AWS or cloud systems, and stable or more well known processes can run on cheaper commodity on-prem hardware.
3. Future proof as part of the foundation to support potentially more than just kubernetes.

Brokers provide services to external services and (if they dont now, they should) register with the regional api. They can be anything from physical services to external credentials. Broker services should probably use the open broker API standard.

Watchers can include: node, service and app watchers. Node watchers watch for physical resources to become available and add those into the kubernetes systems (in addition to any ingress systems which need to load balance to a physical node port). Services watchers will watch for kubernetes services, create appropriate domains as necessary and create pools within ingress systems. Finally, app watchers will watch for application changes such as releases that have completed, crashes or other events of interest and report them to the controller.