feat(documentation): add components and diagrams

Signed-off-by: Nicolas Lamirault <[email protected]>
portefaix · Sep 16, 2024 · a4b6352 · a4b6352
1 parent 6bf0976
commit a4b6352
Show file tree

Hide file tree

Showing 28 changed files with 3,470 additions and 235 deletions.
diff --git a/content/en/docs/_index.md b/content/en/docs/_index.md
@@ -2,27 +2,31 @@
 type: docs
 title: "Portefaix Documentation"
 linkTitle: "Home"
-description: "Portefaix enables developers and the platform engineers that support them to build cloud-native applications"
+description: ""
 weight: 1
 no_list: true
 ---
 
 Welcome to the Portefaix documentation! Here you'll find everything you need to know about Portefaix, from getting started to advanced topics.
 
-{{% alert color="primary" %}}
+<!-- {{% alert color="primary" %}}
 {{< image src="portefaix-logo.svg" alt="Portefaix logo" width="400px" >}} <br /><br />
 Portefaix is a project to ...
 [**Learn more**](https://portefaix.xyz/)
-{{% /alert %}}
+{{% /alert %}} -->
 
 {{< cardpane >}}
   {{< card header="**🎓 Tutorials**" footer="[**View available tutorials →**]({{< ref tutorials >}})" >}}
   Visit the tutorials for guided learning paths to try out Portefaix and pick up the main concepts.
   {{< /card >}}
+{{< /cardpane >}}
+
+{{< cardpane >}}
   {{< card header="**📘 How-to guides**" footer="[**Visit how-to guides →**]({{< ref guides >}})" >}}
   Check out the how-to guides for step-by-step instructions on how to use Portefaix and its features.
   {{< /card >}}
 {{< /cardpane >}}
+
 {{< cardpane >}}
   {{< card header="**🧾 Reference**" footer="[**Visit reference material →**]({{< ref reference >}})" >}}
   Refer to detailed information on Portefaix resources, repositories, FAQs, and more.

diff --git a/content/en/docs/guides/applications/argo-cd/_index.md b/content/en/docs/guides/applications/argo-cd/_index.md
@@ -27,7 +27,7 @@ To configure the Helm charts, we use YAML files :
 ### Argo-CD
 
 ```shell
-❯ make argocd-bootstrap ENV=<environment> CLOUD=<cloud provider> CHOICE=helm
+❯ make bootstrap-argocd ENV=<environment> CLOUD=<cloud provider> CHOICE=helm
 ```
 
 ### Stacks

diff --git a/content/en/docs/guides/applications/flux-cd/_index.md b/content/en/docs/guides/applications/flux-cd/_index.md
@@ -31,7 +31,7 @@ Flux components are deployed for each cluster on `clusters/<CLOUD>/<ENV>/` :
 ### FluxCD
 
 ```shell
-❯ make fluxcd-bootstrap ENV=<environment> CLOUD=<cloud provider> BRANCH=<git branch to use>
+❯ make bootstrap-fluxcd ENV=<environment> CLOUD=<cloud provider> BRANCH=<git branch to use>
 ```
 
 ### Stacks

diff --git a/content/en/docs/guides/applications/gitops/_index.md b/content/en/docs/guides/applications/gitops/_index.md
@@ -8,11 +8,13 @@ aliases  : ["/how-to/applications/"]
 categories: "HowTo"
 ---
 
-[OpenGitops principles](https://opengitops.dev):
+[OpenGitops](https://opengitops.dev)
 
+<img src="/img/opengitops/opengitops.png" alt="OpenGitops Principles" class="mt-3 mb-3 border border-info rounded">
+
+<!-- 
 * **Declarative**: A system managed by GitOps must have its desired state expressed declaratively.
 * **Versioned and Immutable**: Desired state is stored in a way that enforces immutability, versioning and retains a complete version history.
 * **Pulled Automatically**: Software agents automatically pull the desired state declarations from the source.
-* **Continuously Reconciled**: Software agents continuously observe actual system state and attempt to apply the desired state.
-
-## Tools
+* **Continuously Reconciled**: Software agents continuously observe actual system state and attempt to apply the desired state. 
+-->
diff --git a/content/en/docs/guides/infrastructure/aws/overview.md b/content/en/docs/guides/infrastructure/aws/overview.md
@@ -1,7 +1,7 @@
 ---
 type: docs
 title: "Overview"
-description: "Running Portefaix on Amazon Web Services"
+description: "Portefaix architecture on Amazon Web Services"
 weight: 10
 categories: "Explanation"
 tags: ["AWS"]
@@ -10,4 +10,3 @@ tags: ["AWS"]
 <img src="/img/aws/portefaix-aws-infra.svg" alt="Portefaix components" class="mt-3 mb-3 rounded">
 
 <img src="/img/aws/portefaix-aws.svg" alt="Portefaix components" class="mt-3 mb-3 rounded">
-
diff --git a/content/en/docs/guides/infrastructure/azure/overview.md b/content/en/docs/guides/infrastructure/azure/overview.md
@@ -1,7 +1,7 @@
 ---
 type: docs
 title: "Overview"
-description: "Running Portefaix on Microsoft Azure"
+description: "Portefaix architecture on Microsoft Azure"
 weight: 10
 categories: "Explanation"
 tags: ["Azure"]

diff --git a/content/en/docs/guides/infrastructure/civo/overview.md b/content/en/docs/guides/infrastructure/civo/overview.md
@@ -1,7 +1,7 @@
 ---
 type: docs
 title: "Overview"
-description: "Running Portefaix on Civo"
+description: "Portefaix architecture on Civo"
 weight: 10
 categories: "Explanation"
 tags: ["Civo"]

diff --git a/content/en/docs/guides/infrastructure/digitalocean/overview.md b/content/en/docs/guides/infrastructure/digitalocean/overview.md
@@ -1,7 +1,7 @@
 ---
 type: docs
 title: "Overview"
-description: "Running Portefaix on Digital Ocean"
+description: "Portefaix architecture on Digital Ocean"
 weight: 10
 categories: "Explanation"
 tags: ["Digital Ocean"]

diff --git a/content/en/docs/guides/infrastructure/exoscale/overview.md b/content/en/docs/guides/infrastructure/exoscale/overview.md
@@ -1,7 +1,7 @@
 ---
 type: docs
 title: "Overview"
-description: "Running Portefaix on Exoscale"
+description: "Portefaix architecture on Exoscale"
 weight: 10
 categories: "Explanation"
 tags: ["Exoscale"]

diff --git a/content/en/docs/guides/infrastructure/gcp/overview.md b/content/en/docs/guides/infrastructure/gcp/overview.md
@@ -1,7 +1,7 @@
 ---
 type: docs
 title: "Overview"
-description: "Running Portefaix on Google Cloud Platform"
+description: "Portefaix architecture on Google Cloud Platform"
 weight: 10
 categories: "Explanation"
 tags: ["GCP"]

diff --git a/content/en/docs/guides/infrastructure/homelab/_index.md b/content/en/docs/guides/infrastructure/homelab/_index.md
@@ -7,4 +7,6 @@ weight: 200
 
 <img src="/img/homelab/portefaix-homelab-infra.svg" alt="Portefaix components" class="mt-3 mb-3 rounded">
 
-<img src="/img/homelab/portefaix-homelab.svg" alt="Portefaix components" class="mt-3 mb-3 rounded">
+<img src="/img/homelab/portefaix-homelab.svg" alt="Portefaix components" class="mt-3 mb-3 rounded">
+
+<img src="/img/homelab/portefaix-stacks.svg" alt="Portefaix components" class="mt-3 mb-3 rounded">
diff --git a/content/en/docs/guides/infrastructure/homelab/deploy.md b/content/en/docs/guides/infrastructure/homelab/deploy.md
@@ -53,36 +53,45 @@ For each node, add it to the cluster, then add a label:
 
 ```shell
 ❯ make -f hack/build/k3s.mk k3s-join ENV=homelab SERVER_IP=x.x.x.x AGENT_IP=x.x.x.x EXTERNAL_IP=x.x.x.x
-
-❯ kubectl label node <NODE_NAME> node-role.kubernetes.io/worker=
 ```
 
-We add also these labels:
+Authentication and authorization
 
-* `portefaix.xyz/infra`, with values : `core` and `cheap`
+```shell
+❯ make kubernetes-credentials CLOUD=k3s ENV=homelab
+```
 
-Check Kubernetes cluster:
+Set labels:
 
 ```shell
-❯ make -f hack/build/k3s.mk k3s-kube-credentials ENV=homelab
+❯ kubectl label node <NODE_NAME> node-role.kubernetes.io/worker=true
 ```
 
+We add also these labels:
+
+| Label                                | Description                       |
+| ------------------------------------ | --------------------------------- |
+| node-role.kubernetes.io/infra=true   | For core components               |
+| node-role.kubernetes.io/lowcost=true | For pocs, small applications, ... |
+
 The nodes are in a `NotReady` state, due to the Pod Networking CNI plugin is not available.
 [Cilium](https://cilium.io/) must be installed:
 
 ```shell
-❯ make argocd-bootstrap ENV=<environment> CLOUD=<cloud provider> CHOICE=cilium
+❯ make bootstrap-crds ENV=homelab CLOUD=k3s
+❯ make bootstrap-cilium ENV=homelab CLOUD=k3s
 ```
 
 Then check nodes:
 
 ```shell
 ❯ kubectl get node -o wide
-NAME          STATUS   ROLES                  AGE   VERSION        INTERNAL-IP     EXTERNAL-IP      OS-IMAGE             KERNEL-VERSION      CONTAINER-RUNTIME
-portefaix-4   Ready    <none>                 24m   v1.26.1+k3s1   192.168.0.234   100.87.6.37      Ubuntu 22.04.2 LTS   5.15.0-1024-raspi   containerd://1.6.15-k3s1
-portefaix-3   Ready    <none>                 29m   v1.26.1+k3s1   192.168.0.252   100.86.135.11    Ubuntu 22.04.2 LTS   5.15.0-1024-raspi   containerd://1.6.15-k3s1
-portefaix     Ready    control-plane,master   87m   v1.26.1+k3s1   192.168.0.62    100.126.241.86   Ubuntu 22.04.2 LTS   5.15.0-60-generic   containerd://1.6.15-k3s1
-portefaix-1   Ready    <none>                 45m   v1.26.1+k3s1   192.168.0.208   100.115.34.57    Ubuntu 22.04.2 LTS   5.15.0-1024-raspi   containerd://1.6.15-k3s1
+NAME          STATUS     ROLES                       AGE     VERSION        INTERNAL-IP     EXTERNAL-IP      OS-IMAGE           KERNEL-VERSION     CONTAINER-RUNTIME
+portefaix     Ready      control-plane,etcd,master   3h37m   v1.30.2+k3s1   192.168.0.61    100.79.205.64    Ubuntu 24.04 LTS   6.8.0-36-generic   containerd://1.7.17-k3s1
+portefaix-1   NotReady   lowcost,worker              155m    v1.30.2+k3s1   192.168.0.208   100.115.34.57    Ubuntu 24.04 LTS   6.8.0-1005-raspi   containerd://1.7.17-k3s1
+portefaix-2   Ready      lowcost,worker              154m    v1.30.2+k3s1   192.168.0.116   100.126.100.42   Ubuntu 24.04 LTS   6.8.0-1005-raspi   containerd://1.7.17-k3s1
+portefaix-6   Ready      infra,worker                3h21m   v1.30.2+k3s1   192.168.0.233   100.111.218.32   Ubuntu 24.04 LTS   6.8.0-36-generic   containerd://1.7.17-k3s1
+portefaix-7   Ready      infra,worker                3h18m   v1.30.2+k3s1   192.168.0.250   100.86.220.99    Ubuntu 24.04 LTS   6.8.0-36-generic   containerd://1.7.17-k3s1
 ```
 
 and Cilium status:
@@ -105,11 +114,6 @@ Containers:       cilium             Running: 4
                   hubble-relay       Running: 1
                   hubble-ui          Running: 1
 Cluster Pods:     4/4 managed by Cilium
-Image versions    cilium             quay.io/cilium/cilium:v1.13.0@sha256:6544a3441b086a2e09005d3e21d1a4afb216fae19c5a60b35793c8a9438f8f68: 4
-                  cilium-operator    quay.io/cilium/operator-generic:v1.13.0@sha256:4b58d5b33e53378355f6e8ceb525ccf938b7b6f5384b35373f1f46787467ebf5: 1
-                  hubble-relay       quay.io/cilium/hubble-relay:v1.13.0@sha256:bc00f086285d2d287dd662a319d3dbe90e57179515ce8649425916aecaa9ac3c: 1
-                  hubble-ui          quay.io/cilium/hubble-ui:v0.10.0@sha256:118ad2fcfd07fabcae4dde35ec88d33564c9ca7abe520aa45b1eb13ba36c6e0a: 1
-                  hubble-ui          quay.io/cilium/hubble-ui-backend:v0.10.0@sha256:cc5e2730b3be6f117b22176e25875f2308834ced7c3aa34fb598aa87a2c0a6a4: 1
 ```
 
 ## Cloudflare
@@ -168,24 +172,6 @@ Creates the R2 buckets for Observability components:
 ❯ make terraform-apply SERVICE=terraform/k3s/observability ENV=homelab
 ```
 
-## Authentication and authorization
-
-### Configure kubectl
-
-```shell
-❯ make kubernetes-credentials CLOUD=k3s ENV=homelab
-```
-
-```shell
-❯ kubectl get nodes
-NAME          STATUS     ROLES    AGE     VERSION
-portefaix-1   Ready      master   3h2m    v1.18.17+k3s1
-portefaix-4   Ready      <none>   5m36s   v1.18.17+k3s1
-portefaix-3   Ready      <none>   5m36s   v1.18.17+k3s1
-portefaix-2   Ready      <none>   5m35s   v1.18.17+k3s1
-```
-
-
 ## Applications
 
 Next: [Gitops](/docs/gitops)
diff --git a/content/en/docs/guides/infrastructure/homelab/overview.md b/content/en/docs/guides/infrastructure/homelab/overview.md
@@ -1,7 +1,7 @@
 ---
 type: docs
 title: "Overview"
-description: "Running Portefaix on Homelab"
+description: "Portefaix architecture on Homelab"
 weight: 10
 categories: "Explanation"
 tags: ["Homelab"]

diff --git a/content/en/docs/guides/infrastructure/ibmcloud/overview.md b/content/en/docs/guides/infrastructure/ibmcloud/overview.md
@@ -1,7 +1,7 @@
 ---
 type: docs
 title: "Install on IBM Cloud"
-description: "Running Portefaix on IBM Cloud"
+description: "Portefaix architecture on IBM Cloud"
 weight: 50
 categories: "Explanation"
 tags: ["IBMCloud"]

diff --git a/content/en/docs/guides/infrastructure/oci/overview.md b/content/en/docs/guides/infrastructure/oci/overview.md
@@ -1,7 +1,7 @@
 ---
 type: docs
 title: "Overview"
-description: "Running Portefaix on Orange Cloud Infrastructure"
+description: "Portefaix architecture on Orange Cloud Infrastructure"
 weight: 10
 categories: "Explanation"
 tags: ["OCI"]

diff --git a/content/en/docs/guides/infrastructure/scaleway/overview.md b/content/en/docs/guides/infrastructure/scaleway/overview.md
@@ -1,7 +1,7 @@
 ---
 type: docs
 title: "Overview"
-description: "Running Portefaix on Scaleway"
+description: "Portefaix architecture on Scaleway"
 weight: 10
 categories: "Explanation"
 tags: ["Scaleway"]

diff --git a/content/en/docs/reference/components/_index.md b/content/en/docs/reference/components/_index.md
@@ -0,0 +1,46 @@
+---
+type: docs
+title: "Components"
+linkTitle: "Components"
+description: "The components used by Portefaix"
+weight: 10
+---
+
+### Infrastructure management
+
+- [Terraform](https://github.com/hashicorp/terraform): Bootstraps and manages the cloud provider infrastructure.
+- [Crossplane](https://crossplane.io): Kubernetes-native infrastructure management.
+
+### Cluster management
+
+- [Argo CD](https://github.com/argoproj/argo-cd): Reconciles kubernetes clusters with this repository.
+- [Kyverno](https://kyverno.io): Policy engine supporting validate, mutate, generate, and cleanup rules.
+- [Renovate](https://github.com/renovatebot/renovate): Automatic updates for applications via pull requests.
+
+### Secrets
+
+- [External Secrets](https://external-secrets.io): Synchronizes secrets from Doppler into Kubernetes.
+- [AKeyless](https://console.akeyless.io): A secrets management platform.
+
+### Networking
+
+- [Cilium](https://cilium.io): eBPF-based CNI & service mesh.
+- [Cert Manager](https://cert-manager.io): Automatic Let's Encrypt certificates.
+
+### Security
+
+- [Falco](https://falco.org): The Cloud Native Runtime Security
+- [Authentik](https://goauthentik.io): Identity Provider.
+- [Trivy](https://aquasecurity.github.io/trivy): Kubernetes and container vulnerability scanner.
+- [Tetragon](https://tetragon.io/): eBPF-based security observability and runtime enforcement.
+
+### Observability
+
+- [Grafana](https://grafana.com): Visualization platform.
+- [Prometheus](https://prometheus.io): Monitoring system.
+- [Loki](https://grafana.com/oss/loki/): Log aggregation system.
+- [Tempo](https://grafana.com/oss/tempo/): High-scale distributed tracing backend
+- [Mimir](https://grafana.com/oss/mimir/): Horizontally scalable TSDB for long-term storage for Prometheus
+- [Alloy](https://grafana.com/oss/alloy/): The OpenTelemetry Distribution from Grafana
+
+### Storage
diff --git a/content/en/docs/reference/hub/_index.md b/content/en/docs/reference/hub/_index.md
@@ -3,7 +3,7 @@ type: docs
 title: "Hub"
 linkTitle: "Hub"
 description: "The Portefaix Hub for Helm charts"
-weight: 10
+weight: 20
 ---
 
 ## Portefaix Hub

diff --git a/content/en/docs/reference/inspec/_index.md b/content/en/docs/reference/inspec/_index.md
@@ -3,7 +3,7 @@ type: docs
 title: "Inspec"
 linkTitle: "Inspec"
 description: "The Inspec profiles for Portefaix"
-weight: 40
+weight: 90
 ---
 
 ## GCP

diff --git a/content/en/docs/reference/krm/_index.md b/content/en/docs/reference/krm/_index.md
@@ -3,7 +3,7 @@ type: docs
 title: "KRM"
 linkTitle: "KRM"
 description: "The Kubernetes Resources Model deployed into Portefaix"
-weight: 30
+weight: 40
 ---
 
 ## Kubernetes Resources Model

diff --git a/content/en/docs/reference/policies/_index.md b/content/en/docs/reference/policies/_index.md
@@ -1,9 +1,9 @@
 ---
 type: docs
-title: "Hub"
+title: "Policies"
 linkTitle: "Policies"
 description: "The Portefaix policies"
-weight: 20
+weight: 30
 ---
 
 [Portefaix Policies](https://github.com/portefaix/portefaix-policies) contains Kubernetes policies for [Kyverno](https://kyverno.io/) or [Open Policy Agent](https://www.openpolicyagent.org/).