Skip to content

Commit

Permalink
update README with clearer background on the problem horizon is solving
Browse files Browse the repository at this point in the history
  • Loading branch information
@jlarfors
jlarfors committed Mar 16, 2024
1 parent 5d23d74 commit 8d4bb1c
Show file tree
Hide file tree
Showing 2 changed files with 50 additions and 22 deletions.
64 changes: 42 additions & 22 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,44 +1,42 @@
# Horizon 🌅 - Build your Internal Developer Platform

> Horizon provides essential building blocks and patterns for creating a minimal internal platform that enables developer self-service and autonomy.
When building an internal developer platform it is very important to define a Platform API.
The API should model your end users' domain and decouple them from the underlying platform technologies (such as Kubernetes, AWS, GCP, Azure).
On top of the platform API we can build user interfaces, such as web portals and command-line tools.

## Why Horizon?

Building internal platforms that enable developer self-service and improve the developer experience is hard.
Horizon offers a Kubernetes-like API and libraries to help you build internal developer platforms with significantly less complexity and overhead, whilst focusing on developer experience for the platform developers. It is a thin wrapper written in Go on top of [NATS](https://nats.io/).

At Verifa we have seen two common approaches from platform teams (also known as DevOps teams or DevEx teams):
Learn more about [Platform Engineering](./docs/learning.md#platform-engineering) to understand the use cases for Horizon.

1. Exposing tools like Terraform and Helm directly to the end users.
## Why Horizon?

Those abstractions (i.e. Terraform modules and Helm charts) are [leaky](https://en.wikipedia.org/wiki/Leaky_abstraction) and expose the underlying technology (i.e. Terraform and Kubernetes).
This negatively impacts developers' flow and cognitive load.
Building internal platforms that enable developer self-service and improve the developer experience is hard.

2. Deploy an Internal Developer Platform / Portal (IdP), like [Backstage](https://backstage.io/).
Traditional "DevOps Teams" typically expose tools like Terraform and Helm directly to the end users.
Those abstractions are [leaky](https://en.wikipedia.org/wiki/Leaky_abstraction) and do not decouple your users from the underlying technology (i.e. Terraform and Kubernetes).
This negatively impacts developers' flow and cognitive load and also makes maintaining a stable platform API very difficult.

This provides a very elegant UI for developers, but does not take care of provisioning anything.
For provisioning you still need something like Kubernetes + some infrastructure provisioner (like CrossPlane or a Terraform controller).
Also this is a very complex stack of tools to maintain and requires significant development to be useful.
Modern "Platform Teams" typically deploy an Internal Developer Platform / Portal, like [Backstage](https://backstage.io/).
This provides a very elegant UI for developers, but does not take care of provisioning anything.
For provisioning you still need something like Kubernetes + some infrastructure provisioner (like CrossPlane or a Terraform controller).
This is a very complex stack of tools to maintain and requires significant platform development to be useful.

Horizon is an attempt to get the best of both worlds without a complex stack to maintain.
Horizon's only hard dependency is [NATS](https://nats.io/), and it makes heavy use of it!

Horizon is not "off the shelf". In fact the idea is that you build and own the Horizon extensions you need.
Do not expect a big ecosystem or lots of plugins you can install or lots of pretty graphs and UI elements: expect a thin layer on top of NATS to help you build only what you need.

> [!WARNING]
> Horizon is still a Proof of Concept.
>
> If you have come here please be gentle and do not expect the APIs to be stable.
> If you think Horizon could be useful for your internal platform then please give it a try, and feel free to start a discussion with your use case and we will try to help.
Horizon is not "off the shelf".
In fact the idea is that you build and own the Horizon extensions you need.
Do not expect an ecosystem of plugins you can install or lots of pretty graphs and UI elements: expect a thin layer on top of NATS to help you build only what you need.

## How it works

As the platform team building this for your end users (i.e. the software development teams) you are creating **an interface** on top of your **underlying platform**. This interface is incredibly important because it can **decouple your end users** away from the **platform technologies**.
As the platform team building this for your end users (i.e. the software development teams) you are creating **an interface** on top of your **underlying platform**. This interface is incredibly important because it **decouples your end users** away from the **platform technologies**.
The interface should be designed to enable your developers in thier domain, not to mirror the API on top of the underlying platform (e.g. Kubernetes, AWS, GCP, Azure).

> [!WARNING]
> If you want to use Horizon you will need to write and maintain code.
>
> At this time, Go is the only supported language. If the concept of building a platform with Go worries you, I suggest you turn around now :)
> At this time, Go is the only supported language.
Below is a high-level overview of the different Horizon components. For a more detailed explanation of the components, see the [Architecture](#architecture) section.

Expand All @@ -53,6 +51,20 @@ For provisioning "resources" (e.g. cloud infrastructure, Git repositories, artif

For running operations across different nodes, actors can be called via the broker and actors are selected based on their labels. More on [actors](./docs/architecture.md#platform---actors).

## Project status

> [!WARNING]
> Horizon is still a Proof of Concept.
>
> We are piloting Horizon with a few projects at the moment.
> If you think Horizon could be useful for your internal platform then please give it a try, and feel free to start a discussion with your use case and we will try to help.
**Store and Controllers:** should be considered fairly stable. This is the foundations of Horizon and is where most of the effort has been spent.

**Gateway and Portals:** we are not sure if the abstraction is correct. It might be easier to provide the gateway as a library allowing teams to fully customise and build their own version. There are so many opinions about developing web servers and styling with CSS.

If you try Horizon please give us your feedback via [GitHub discussions](https://github.com/verifa/horizon/discussions)!

## Architecture

Check the [architecture](./docs/architecture.md) document for some more information on the different components.
Expand Down Expand Up @@ -84,6 +96,14 @@ Check the [debugging with nats](./docs/debugging_nats.md) page.

Check the [learning](./docs/learning.md) for some material to help you learn NATS and generally about platform engineering.

## Who is behind Horizon?

[Verifa](https://verifa.io/) is a Nordic-based niche consultancy company who have developed Horizon to solve problems for our customers.

Our business model is based on consulting services and we are happy to help you build internal platforms with Horizon.

If you would like help with developer experience and platform engineering topics, please [contact us](https://verifa.io/contact/)!

## License

This code is released under the [Apache-2.0 License](./LICENSE).
8 changes: 8 additions & 0 deletions docs/learning.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,3 +20,11 @@
2. [DevOps Toolkit - Developer Platform Consoles Should Be Dumb](https://youtu.be/Qy2QmJkwkP0?si=3dnYcPx0BjOX-e5Y)

We dive deep into the world of developer platform consoles, exploring the importance of simplicity, API-based architectures, and the crucial role these elements play in discoverability, operations, and observability. We argue that developer platform consoles should aim for a 'dumb' design philosophy - one that emphasizes straightforward interfaces and leverages APIs to interact with underlying services and data. By stripping down the complexity traditionally found in these consoles, developers can achieve greater efficiency and enhance the maintainability of their systems.

3. [From toolbox to platform product your developers love - Henrik Høegh](https://youtu.be/m8-O7yEWoE8?si=oDS9Br5KnqrzBeFV)

Building a platform is not a "let's install many awesome tools" exercise. Presenting developers with these toolboxes only increases the mental load. We need to take DevOps to the next level by creating tools our developers love to use and hide all the tools they don't care about. But how do you hide Kubernetes, GitHub actions, etc., and how do your developers release software?

4. [Tips For Building Successful Platform Teams - Dave Farley](https://youtu.be/_zH7TIXcjEs?si=cBGYeUI9rMl3GW3d)

What is a platform team, and how do you build effective platforms? Platforms are often an important part of the strategy to scale software development beyond small single teams. Dividing work up so that common behaviours and services can be shared, rather than every service team implementing their own version, is a big gain, but it can also be a big cost. Coupling between teams is one of the biggest causes of problems when trying to build software on larger scales.

0 comments on commit 8d4bb1c

Please sign in to comment.