This is a small demo of fine grained services and their security properties. Code is written in JavaScript/Node.js. Similar demos with Python and R are planned.
TBS has been pushing hard to modernize IT practices. It's Enterprise Architecture Framework explains:
Application architecture practices must evolve significantly for the successful implementation of the GC Enterprise Ecosystem Target Architecture. Transitioning from legacy systems based on monolithic architectures to architectures that oriented around business services and based on re‑useable components implementing business capabilities, is a major shift.
This mandatory policy is aggressively modern and directs departments to
- "design systems as highly modular and loosely coupled services"
- "use distributed architectures"
- "support zero-downtime deployments"
- "expose services, including existing ones, through APIs"
- "ensure automated testing occurs"
- "design for cloud mobility"
- validate APIs by consuming what you build
The shift to highly available and evolvable distributed systems is strategically important to support modern service delivery, but it's easy to overlook that building and supporting such systems is very different from the 3-tier architecture that most departments have standardized on. Distributed systems are complex and hard and building them requires different structures, tools and patterns.
What's missing to help departments adapt to this "major shift" are working examples of how to build this type of architecture. That is the aim of this project.
A distributed system is made of many small (micro even!) parts (services) that collaborate to deliver some funtionality, deployed across a series of machines. The most basic verion of this architecture comes from splitting a classic MVC-style monolith in two. The result: An API developed together with an application that consumes it. Just like Treasury Board requires.
The basic idea behind this demo is to show an example of this way of building and deploying applications and demonstrate how it allows for better security boundaries, and more granular security decisions. It also allows for higher levels of observability, as can been seen when we visualize traffic flowing through these services with Kiali.
Visualizations like the above are a powerful way to make security visible: you can see that the system has distinct components (with their own security settings), and communications between them is encrypted with mTLS.
This is a zero trust microcosm, and systems built like this have security properties and compliance implications that security teams need to be learning about.
As is common with microservices projects, this repository is organized in the monorepo style keeping services in it's own folder (code that changes together stays together).
All code embeds opinions, and this repo and the code within are no exception. There are other options worth exploring, but the patterns and technologies here come from balancing a lot of tradeoffs specific to service delivery in the Government of Canada.
The code and readme files make special note of the security properties that emerge from this style of architecture.
Since APIs are mandatory, the API forms a core part of this service. Living in the API folder, this is a GraphQL API written in low-risk JavaScript that reads from/writes to tables in the database, and produces only JSON as an output. The library used to talk to the database is safe by default, and leverages modern language features to systemically solve SQL injection attacks. It's narrow scope allows for tightly scoped database permissions, and makes security profiling of "normal" behaviour tractable.
While The TBS Standard on APIs says that APIs should use REST "by default", this demo extercises the latitude to go beyond the default (it's been confirmed with TBS this is allowed) and use GraphQL because it allows for composition. Services built with composition in mind turn themselves into building blocks that can be combined in various ways to allow the organization as a whole to quickly adapt to shifting demands (hence calls for a "composable enterprise").
See the API documentation for more details.
Found in the ui folder, this service queries the API and is focused on safely encoding the data received into accessible HTML using React. This approach means that teams with varying skill levels can reliably produce UI that is free from Cross Site-Scripting vulnerabilities (aka XSS). Using React also makes it possible to leverage accessible-by-default components created by others (such as Microsoft's Fluent UI components, Adobe's React Aria, or community-led projects like Radix-UI). When devs are building with components that are both secure and accessible by default, organizations have the option of implementing lighter, faster process without worry that these requirements will not be met.
See the UI documentation for more details.
This lives in the migrations folder and exists to move the database schema from one known state to the next. The requirement to "support zero-downtime deployments" means teams will need to look carefully at how to do this with their choosen database and web framework (and possibly choose ones that make this easy to do).
The powerful permissions needed to alter a database schema (ie create/drop tables) are required only once at startup, and it's the job of the migration service to create/verify the schema needed and then exit. This design leverages the plumbing provided by modern container orchestrators like ECS or Kubernetes to achieve "least privilege".
See the Migrations documentation for more details.
Distributed architectures require an orchestrator, and Kubernetes is a vendor neutral open source orchestrator available in many form factors from many vendors with security sufficient for the US Air Force.
You can run a local version of it using Minikube. Minikube requires a lot of resources... so throw everything you can at it.
For reference, this is what was used to develop this.
$ minikube config view
- cpus: 16
- memory: 40G
You'll also need Kustomize and istioctl installed. Once you're all set run the following commands:
minikube start
make credentials
make demoThen launch the Kiali dashboard:
istioctl dashboard kialiRefresh the application several times to see traffic flow on the dashboard. The url can be found with:
minikube service istio-ingressgateway -n istio-system --url