From faaf96cd8c098a8c52f8b896064dc92115b2174f Mon Sep 17 00:00:00 2001 From: Adam Dyess Date: Thu, 4 Apr 2024 09:45:12 -0500 Subject: [PATCH] Create Charm Architecture Reference (#270) * Add Charms Architecture C4 Model * Addition of charm architecture to the docs * Apply suggestions from code review Co-authored-by: Nick Veitch --------- Co-authored-by: Mateo Florido Co-authored-by: Nick Veitch --- docs/src/assets/charms-architecture.puml | 36 +++++++++++++++++++++ docs/src/reference/architecture.md | 41 ++++++++++++++++++++++-- 2 files changed, 75 insertions(+), 2 deletions(-) create mode 100644 docs/src/assets/charms-architecture.puml diff --git a/docs/src/assets/charms-architecture.puml b/docs/src/assets/charms-architecture.puml new file mode 100644 index 000000000..372518235 --- /dev/null +++ b/docs/src/assets/charms-architecture.puml @@ -0,0 +1,36 @@ +@startuml +set separator none +title Juju - Containers + +top to bottom direction + +!include +!include +!include + +Person(Administrator, "Administrator", $descr="", $tags="", $link="") + +System_Boundary("Juju_boundary", "Juju", $tags="") { + Container(Juju.JujuController, "Juju Controller", $techn="Snap Package", $descr="", $tags="", $link="") + Container(Juju.JujuClient, "Juju Client", $techn="Snap Package", $descr="", $tags="", $link="") + Container(Juju.CompatibleCharms, "Compatible Charms", $techn="", $descr="Other Compatible Canonical Charms", $tags="", $link="") + Container(Juju.K8s, "K8s", $techn="Charmed Operator", $descr="K8s Charm", $tags="", $link="") + Container(Juju.K8sRelationData, "K8s Relation Data", $techn="", $descr="", $tags="", $link="") + Container(Juju.K8sWorker, "K8s Worker", $techn="Charmed Operator", $descr="K8s Worker Charm", $tags="", $link="") + Container(Juju.K8sWorkerRelationData, "K8s Worker Relation Data", $techn="Juju Relation Databag", $descr="", $tags="", $link="") +} + +Rel(Juju.K8sWorker, Juju.K8sWorkerRelationData, "Reads from and writes to", $techn="", $tags="", $link="") +Rel(Juju.K8sWorkerRelationData, Juju.K8sWorker, "Retrieves Peer Data", $techn="", $tags="", $link="") +Rel(Juju.JujuController, Juju.K8s, "Manages", $techn="", $tags="", $link="") +Rel(Juju.JujuController, Juju.K8sWorker, "Manages", $techn="", $tags="", $link="") +Rel(Administrator, Juju.JujuClient, "Uses", $techn="", $tags="", $link="") +Rel(Juju.JujuClient, Juju.JujuController, "Manages", $techn="", $tags="", $link="") +Rel(Juju.K8s, Juju.CompatibleCharms, "Integrates with", $techn="", $tags="", $link="") +Rel(Juju.K8sWorker, Juju.CompatibleCharms, "Integrates with", $techn="", $tags="", $link="") +Rel(Juju.K8s, Juju.K8sRelationData, "Reads from and writes to", $techn="", $tags="", $link="") +Rel(Juju.K8sRelationData, Juju.K8s, "Retrieves Peer Data", $techn="", $tags="", $link="") +Rel(Juju.K8s, Juju.K8sWorkerRelationData, "Share Cluster Data", $techn="", $tags="", $link="") + +SHOW_LEGEND(true) +@enduml diff --git a/docs/src/reference/architecture.md b/docs/src/reference/architecture.md index a2ca71754..3d494c57c 100644 --- a/docs/src/reference/architecture.md +++ b/docs/src/reference/architecture.md @@ -102,6 +102,43 @@ This functionality is exposed via the following interfaces: - The **API**: The API over HTTP serves the CLI and is also used to programmatically drive the Kubernetes cluster. +## Canonical K8s charms + +Canonical `k8s` Charms encompass two primary components: the [`k8s` charm][K8s charm] and the [`k8s-worker` charm][K8s-worker charm]. + +```{kroki} ../assets/charms-architecture.puml +``` + +Charms are instantiated on a machine as a Juju unit, and a collection of units +constitutes an application. Both `k8s` and `k8s-worker` units are responsible +for installing and managing its machine's `k8s` snap, however the charm type determines +the node's role in the Kubernetes cluster. The `k8s` charm manages `control-plane` nodes, +whereas the `k8s-worker` charm manages Kubernetes `worker` nodes. The administrator manages +the cluster via the `juju` client, directing the `juju` controller to reach the model's +eventually consistent state. For more detail on Juju's concepts, see the [Juju docs][]. + +The administrator may choose any supported cloud-types (Openstack, MAAS, AWS, GCP, Azure...) on +which to manage the machines making up the Kubernetes cluster. Juju selects a single leader unit +per application to act as a centralised figure with the model. The `k8s` leader oversees Kubernetes +bootstrapping and enlistment of new nodes. Follower `k8s` units will join the cluster using +secrets shared through relation data from the leader. The entire lifecycle of the deployment +is orchestrated by the `k8s` charm, with tokens and cluster-related information being exchanged +through Juju relation data. + +Furthermore, the `k8s-worker` unit functions exclusively as a worker within the cluster, establishing +a relation with the `k8s` leader unit and requesting tokens and cluster-related information through +relation data. The `k8s` leader is responsible for issuing these tokens and revoking them if +a unit administratively departs the cluster. + +The `k8s` charm also supports the integration of other compatible charms, enabling integrations +such as connectivity with an external `etcd` datastore and the sharing of observability data with the +[`Canonical Observability Stack (COS)`][COS docs]. This modular and integrated approach facilitates +a robust and flexible Canonical Kubernetes deployment managed through Juju. + + -[C4 model]: https://c4model.com/ -[K8s charm]: https://charmhub.io/k8s +[C4 model]: https://c4model.com/ +[K8s charm]: https://charmhub.io/k8s +[K8s-Worker charm]: https://charmhub.io/k8s-worker +[Juju docs]: https://juju.is/docs/juju +[COS docs]: https://ubuntu.com/observability \ No newline at end of file