A tree view of the `holos-tutorial/` directory should give readers a
quick, high-level understanding of the folder structure of a typical
Holos platform project.
Add a helm values tutorial which is a cut down version of the v1alpha4
helm guide. The httpbin kustomize will immediately follow building on
the prometheus and blackbox charts.
The docs for v1alpha4 have the right information, but in the wrong
places. The most important bits are tucked away in the Core API docs.
One of our first users entirely missed the `holos generate platform`
command mentioned in the Helm guide.
We'll fix this by organizing the docs into two distinct categories.
First, a tutorial written as a series progressively building up the
minimum knowledge to use holos effectively and gain the benefits. Think
of it as a tour of the essential bits.
The second category are focused topics which stand alone. They're the
things most people using holos will need to know eventually, but aren't
essential for everyone to know. For example, Clusters and Fleets will
move from the Author API to stand alone examples of how to implement
these features if necessary.
Then there's a Glossary which serves as the place to describe our
concepts and domain specific language.
Finally there's the API documentation which should be cut down to the
specific version. The next release version will be v1alpha5.
Attribution: We're copying the Tokio docs structure, it's concise and a
similar size and complexity to our own project.
The Go docs are also an inspiration, but the project is much larger so
not directly comparable. The organization of https://go.dev/doc/ feels
complete at first glance, despite the size and age of the project. The
site also makes clear who each section is for without needing to come
right out and say it. Getting started, Using and understanding Go,
Writing modules, using databases, etc...
Instead of tutorials. The goal is to refine Try Holos Locally down to a
minimal number of steps and then branch out to deeper use cases like
ArgoCD, Backstage, etc...
This patch moves the ArgoCD related sections to a separate "dive deeper"
guide to trim down the length of the try holos guide.
When someone is trying holos locally but has not signed up, ArgoCD needs
to be configured to allow anonymous access. This patch enables
anonymous access and gives the admin role.
With this patch the Try Holos Locally guide can be completed without
signing up or signing in.
Nate gave the feedback the Try Holos Locally doesn't work with Orb.
This patch makes the input form accept *.local domains so we can use the
default Orb managed domain of *.k8s.orb.local
I haven't tested this, but we at least need to allow the domain to
test it.
[1]: https://docs.orbstack.dev/kubernetes/#loadbalancer-ingress
Remove side comments about the reference platform. Move the in-line
exploration of ArgoCD and CUE to the end once the reader has completed
their goal. Other minor edits.
Previously CUE paniced when holos tried to unify values originating from
two different cue runtimes. This patch fixes the problem by
initializaing cue.Value structs from the same cue context.
Log messages are also improved after making one complete pass through
the Try Holos Locally guide.
Previously, the Tiltfile was hard-wired to Jeff's development
environment on the k2 cluster on-prem. This doesn't work for other
contributors.
This patch fixes the problem by re-using the [Try Holos Locally][1]
documentation to create a local development enironment. This has a
number of benefits. The evaluation documentation will be kept up to
date because it doubles as our development environment. Developing
locally is preferrable to developing in a remote cluster. Hostnames and
URL's can be constant, e.g. https://app.holos.localhost/ for local dev
and https://app.holos.run/ for production. We don't need to push to a
remote container registry, k3d has a local registry built in that works
with Tilt.
The only difference presently between evaluation and development when
following the local/k3d doc is the addition of a local registry.
With this patch holos starts up and is accessible at
https://app.holos.localhost/
[1]: https://holos.run/docs/tutorial/local/k3d/
This applies various grammar, formatting, and flow improvements to the
local k3d tutorial steps based on running through it from start to
finish.
This also removes the Go code responsible for embedding the website into
`holos`, which isn't needed since the site is hosted on Cloudflare
Pages.
This patch fixes up the link colors and mermaid diagrams to look better
in both light and dark mode. This may not be the final result but it
moves in the right direction.
Links are now blue with a visible line on hover.
Previously the guide did not cover reconciling holos platform components
with GitOps. This patch adds instructions on how to apply the
application resources, review the diff, sync manually, and finally
enable automatic sync using CUE's struct merge feature.
Previously there is no web app except httpbin in the k3d platform. This
commit adds ArgoCD with an httproute and authorization policy at the
mesh layer. The application layer authenticates against a separate
oidc client id in the same issuer the mesh uses to demonstrate zero
trust and compatibility between the application and platform layers.
With this patch the user can authenticate and log in, but applications
are not configured. The user has no roles in ArgoCD either, rbac needs
to be configured properly for the getting started guide.
This patch adds the authproxy and authpolicy holos components to the k3d
platform for local evaluation. This combination implements a basic Zero
Trust security model. The httpbin backend service is protected with
authenication and authorization at the platform level without any
changes to the backend service.
The client id and project are static because they're defined centrally
in https://login.holos.run to avoid needing to setup a full identity
provider locally in k3d.
With this patch authentication and authorization work from both the web
browser and from the command line with curl using the token provided by
the holos cli.
Previously the local k3d tutorial doesn't expose any services to verify
the local certificate and the local dns changes work as expected.
This patch adds instructions and modifies the k3d platform to work with
a local mkcert certificate. A ClusterIssuer is configured to issue
Certificate resources using the ca private key created my mkcert.
With this patch, following the instructions results in a working and
trusted httpbin resource at https://httpbin.holos.localhost This works
both in Chrome and curl on the command line.
This patch adds a script to install a local CA and configure cert
manager to issue certs similar to how it issues certs using LetsEncrypt
in a real cluster.
Previously there is no way to evaluate Holos on local host. This is a
problem because it's a high barrier to entry to setup a full blown GKE
and EKS cluster to evaluate the reference platform.
This patch adds a minimal, but useful, k3d platform which deploys to a
single local k3d cluster. The purpose is to provide a shorter on ramp
to see the value of ArgoCD integrated with Istio to provide a zero trust
auth proxy.
The intentional trade off is to provide a less-holistic k3d platform
with a faster on-ramp to learn about the value the more-holistic holos
platform.
With this patch the documentation is correct and the platform renders
fully. The user doesn't need to provide any Platform Model values, the
default suffice.
For the ArgoCD client ID, we'll use https://login.holos.run as the
issuer instead of building a new OIDC issuer inside of k3d, which would
create significant friction.
This patch adds a diagram that gives an overview of the holos rendering
pipeline. This is an importantn concept to understand when working with
holos components.
Note this probably should not go in the Overview, which is intended only
to give a sense of what getting started looks like. Move it to the
render page when we add it.
