Merge pull request #141 from axivo/doc/k3s-apps

Implement K3s Applications documentation

docs/content/_index.md

@@ -40,9 +40,18 @@ layout: hextra-home
     title="K3s Cluster"
     subtitle="High Availability cluster deployed with Ansible."
     class="hx-aspect-auto md:hx-aspect-[1.1/1] max-md:hx-min-h-[340px]"
-    image="images/card-k3s-cluster.webp"
+    image="/images/card-k3s-cluster.webp"
     imageClass="hx-top-[20%] hx-left-[24px] hx-w-[180%] sm:hx-w-[110%] dark:hx-opacity-80"
-    link="k3s-cluster"
+    link="/k3s-cluster/"
+    style="background: radial-gradient(ellipse at 50% 80%,rgba(194,97,254,0.15),hsla(0,0%,100%,0));"
+  >}}
+  {{< hextra/feature-card
+    title="K3s Applications"
+    subtitle="Project for applications deployed with ArgoCD."
+    class="hx-aspect-auto md:hx-aspect-[1.1/1] max-md:hx-min-h-[340px]"
+    image="/images/card-k3s-apps.webp"
+    imageClass="hx-top-[20%] hx-left-[24px] hx-w-[180%] sm:hx-w-[110%] dark:hx-opacity-80"
+    link="/k3s-cluster/tutorials/handbook/argocd/"
     style="background: radial-gradient(ellipse at 50% 80%,rgba(194,97,254,0.15),hsla(0,0%,100%,0));"
   >}}
 {{< /hextra/feature-grid >}}

k3s-cluster/content/_index.md

@@ -4,7 +4,7 @@ layout: hextra-home
 ---
 
 {{< hextra/hero-container
-  image="images/logo-services.svg"
+  image="/images/logo-services.svg"
   imageLink="https://github.com/axivo/k3s-cluster"
   imageTitle="Kubernetes Services"
 >}}
@@ -37,7 +37,7 @@ layout: hextra-home
     title="K3s"
     subtitle="Certified Kubernetes distribution built for IoT and Edge computing, running on Ubuntu Server LTS."
     class="hx-aspect-auto md:hx-aspect-[1.1/1] max-md:hx-min-h-[340px]"
-    image="images/card-k3s.webp"
+    image="/images/card-k3s.webp"
     imageClass="hx-top-[20%] hx-left-[24px] hx-w-[180%] sm:hx-w-[110%] dark:hx-opacity-80"
     link="https://k3s.io"
     style="background: radial-gradient(ellipse at 50% 80%,rgba(221,210,59,0.15),hsla(0,0%,100%,0));"
@@ -46,7 +46,7 @@ layout: hextra-home
     title="Cilium"
     subtitle="eBPF-based project, providing networking, security, and observability for Kubernetes clusters."
     class="hx-aspect-auto md:hx-aspect-[1.1/1] max-md:hx-min-h-[340px]"
-    image="images/card-cilium.webp"
+    image="/images/card-cilium.webp"
     imageClass="hx-top-[20%] hx-left-[24px] hx-w-[180%] sm:hx-w-[110%] dark:hx-opacity-80"
     link="https://cilium.io"
     style="background: radial-gradient(ellipse at 50% 80%,rgba(194,97,254,0.15),hsla(0,0%,100%,0));"
@@ -55,7 +55,7 @@ layout: hextra-home
     title="Prometheus Stack"
     subtitle="Kubernetes cluster monitoring and Grafana dashboards, using Prometheus Operator."
     class="hx-aspect-auto md:hx-aspect-[1.1/1] max-md:hx-min-h-[340px]"
-    image="images/card-prometheus.webp"
+    image="/images/card-prometheus.webp"
     imageClass="hx-top-[20%] hx-left-[24px] hx-w-[180%] sm:hx-w-[110%] dark:hx-opacity-80"
     link="https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack"
     style="background: radial-gradient(ellipse at 50% 80%,rgba(142,53,74,0.15),hsla(0,0%,100%,0));"

k3s-cluster/content/tutorials/handbook/ansible/_index.md

@@ -46,7 +46,7 @@ ansible_password: !vault |
   Use the above defined `my-Gl0bal-Passw0rd` global password example, for all encrypted settings, into your configuration files.
 {{< /callout >}}
 
-Insert the `ansible_password` encrypted output into [`all.yaml`](https://{{< param variables.repository >}}/blob/main/inventory/cluster/group_vars/all.yaml) configuration file, while respecting the output indentation.
+Insert the `ansible_password` encrypted output into [`all.yaml`](https://{{< param variables.repository.cluster >}}/blob/main/inventory/cluster/group_vars/all.yaml) configuration file, while respecting the output indentation.
 
 ### Decryption
 

k3s-cluster/content/tutorials/handbook/argocd/_index.md

@@ -0,0 +1,73 @@
+---
+title: ArgoCD
+prev: /tutorials/handbook
+next: /tutorials/handbook/cilium
+---
+
+This repository uses [ArgoCD](https://argoproj.github.io/cd) to deploy applications, based on Helm charts. We encourage the community contributing to the [official project](https://{{< param variables.repository.applications >}}).
+
+<!--more-->
+
+## Repository Setup
+
+Navigate to `ArgoCD Settings` > `Repositories` and connect to official project repository:
+
+| Key     | Value                                                         |
+| :------ | :------------------------------------------------------------ |
+| Method  | `HTTPS` <tr></tr>                                             |
+| Type    | `git` <tr></tr>                                               |
+| Project | `default` <tr></tr>                                           |
+| URL     | `https://{{< param variables.repository.applications >}}.git` |
+
+## Applications Provisioning
+
+Application charts are released with version control, based on repository tags. See below an example of application provisioning in ArgoCD.
+
+### Application Resource
+
+In this example, we will create an [Ubuntu Server pod](https://{{< param variables.repository.applications >}}/tree/main/argo/ubuntu), deployed into `default` namespace. Navigate to `Applications` and create an application, then edit the resource manifest as `YAML` and paste the following content:
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: ubuntu
+  namespace: kube-system
+spec:
+  destination:
+    name: ''
+    namespace: default
+    server: 'https://kubernetes.default.svc'
+  source:
+    path: argo/ubuntu
+    repoURL: 'https://{{< param variables.repository.applications >}}.git'
+    targetRevision: ubuntu/v1.0.0
+    helm:
+      valueFiles:
+        - values.yaml
+  sources: []
+  project: default
+  syncPolicy:
+    automated:
+      prune: true
+      selfHeal: true
+```
+
+#### Metadata
+
+This repository uses the `kube-system` namespace for ArgoCD role provisioning. Adjust the `metadata.namespace` value accordingly, if you deploy ArgoCD in a different namespace.
+
+The `spec.destination.name` is inherited from `metadata.name` value.
+
+### Shell Login
+
+Example of pod shell login:
+
+```shell
+$ kubectl get pods -n default -o go-template \
+  --template='{{range .items}}{{.metadata.name}}{{"\n"}}{{end}}'
+ubuntu-6589cf5fb4-p9z2b
+
+$ kubectl exec -itn default ubuntu-6589cf5fb4-p9z2b -- bash
+root@ubuntu-6589cf5fb4-p9z2b:/#
+```

k3s-cluster/content/tutorials/handbook/cilium/_index.md

@@ -24,9 +24,9 @@ See below the required Cilium dependencies, used into chart configuration.
 
 During chart post-install provisioning, Cilium Hubble is configured to take advantage of CertManager auto-renewed certificates, instead of default Helm expiring certificates. This requires the creation of three resources:
 
-- CertManager `ClusterIssuer` resource template, see [`cluster_issuer.j2`](https://{{< param variables.repository >}}/blob/main/roles/certmanager/templates/cluster_issuer.j2)
-- Hubble `Certificate` resource template, see [`certificate.j2`](https://{{< param variables.repository >}}/blob/main/roles/cilium/templates/certificate.j2)
-- Hubble `ClusterIssuer` resource template, see [`cluster_issuer.j2`](https://{{< param variables.repository >}}/blob/main/roles/cilium/templates/cluster_issuer.j2)
+- CertManager `ClusterIssuer` resource template, see [`cluster_issuer.j2`](https://{{< param variables.repository.cluster >}}/blob/main/roles/certmanager/templates/cluster_issuer.j2)
+- Hubble `Certificate` resource template, see [`certificate.j2`](https://{{< param variables.repository.cluster >}}/blob/main/roles/cilium/templates/certificate.j2)
+- Hubble `ClusterIssuer` resource template, see [`cluster_issuer.j2`](https://{{< param variables.repository.cluster >}}/blob/main/roles/cilium/templates/cluster_issuer.j2)
 
 {{< callout type="warning" >}}
 Cilium details the following instructions into their installation steps:
@@ -46,8 +46,8 @@ Refer to Cilium [documentation](https://docs.cilium.io/en/stable/gettingstarted/
 
 This is an example of `Gateway` and `HTTPRoute` resources usage for Longhorn frontend, as replacement for deprecated `Ingress` resource:
 
-- `Gateway` resource template, see [`gateway.j2`](https://{{< param variables.repository >}}/blob/main/roles/longhorn/templates/gateway.j2)
-- `HTTPRoute` insecure resource template, see [`http_route.j2`](https://{{< param variables.repository >}}/blob/main/roles/longhorn/templates/http_route.j2)
-- `HTTPRoute` secure resource template, see [`https_route.j2`](https://{{< param variables.repository >}}/blob/main/roles/longhorn/templates/https_route.j2)
+- `Gateway` resource template, see [`gateway.j2`](https://{{< param variables.repository.cluster >}}/blob/main/roles/longhorn/templates/gateway.j2)
+- `HTTPRoute` insecure resource template, see [`http_route.j2`](https://{{< param variables.repository.cluster >}}/blob/main/roles/longhorn/templates/http_route.j2)
+- `HTTPRoute` secure resource template, see [`https_route.j2`](https://{{< param variables.repository.cluster >}}/blob/main/roles/longhorn/templates/https_route.j2)
 
 Refer to Cilium [documentation](https://docs.cilium.io/en/stable/network/servicemesh/gateway-api/gateway-api/), for further details.

k3s-cluster/content/tutorials/handbook/cloudflare/_index.md

@@ -20,7 +20,7 @@ Generate the domain [API token](https://developers.cloudflare.com/fundamentals/a
 {{< /filetree/container >}}
 
 Encrypt the `token.value` with [`ansible-vault`](/k3s-cluster/tutorials/handbook/ansible/#vault) and insert it into 
-[`main.yaml`](https://{{< param variables.repository >}}/blob/main/roles/cloudflare/defaults/main.yaml) defaults file.
+[`main.yaml`](https://{{< param variables.repository.cluster >}}/blob/main/roles/cloudflare/defaults/main.yaml) defaults file.
 
 ## Front-Ends
 
@@ -33,4 +33,4 @@ The following front-ends are available, once the cluster is provisioned successf
 - Grafana, `https://grafana.domain.com`
 - Prometheus, `https://prometheus.domain.com`
 
-Update the `gateway.domain` setting into [`main.yaml`](https://{{< param variables.repository >}}/blob/main/roles/cloudflare/defaults/main.yaml) defaults file.
+Update the `gateway.domain` setting into [`main.yaml`](https://{{< param variables.repository.cluster >}}/blob/main/roles/cloudflare/defaults/main.yaml) defaults file.

k3s-cluster/content/tutorials/handbook/kured/_index.md

@@ -31,7 +31,7 @@ https://hooks.slack.com/services/<token>/<token>/<token>
 ### Notify URL
 
 Encrypt the `slack.notify_url` value with [`ansible-vault`](/k3s-cluster/tutorials/handbook/ansible/#vault) and insert it into 
-[`main.yaml`](https://{{< param variables.repository >}}/blob/main/roles/kured/defaults/main.yaml) defaults file. Notify URL pre-encrypted format:
+[`main.yaml`](https://{{< param variables.repository.cluster >}}/blob/main/roles/kured/defaults/main.yaml) defaults file. Notify URL pre-encrypted format:
 
 ```yaml
 notify_url: slack://<token>/<token>/<token>

k3s-cluster/content/tutorials/handbook/renovate/_index.md

@@ -9,6 +9,6 @@ This repository uses [Renovate](https://docs.renovatebot.com), to track any new
 
 ## Configuration
 
-Follow the Renovate [onboarding instructions](https://docs.renovatebot.com/getting-started/installing-onboarding/) and once the `k3s-cluster` forked repository is configured, review the [`renovate.json5`](https://{{< param variables.repository >}}/blob/main/.github/renovate.json5) configuration file, for current Renovate implementation.
+Follow the Renovate [onboarding instructions](https://docs.renovatebot.com/getting-started/installing-onboarding/) and once the `k3s-cluster` forked repository is configured, review the [`renovate.json5`](https://{{< param variables.repository.cluster >}}/blob/main/.github/renovate.json5) configuration file, for current Renovate implementation.
 
 See a [PR example](https://github.com/axivo/k3s-cluster/pull/73) with a new release version generated by Renovate.

k3s-cluster/content/wiki/guide/_index.md

@@ -9,7 +9,7 @@ The cluster inventory, user, role configuration settings and provisioning playbo
 <!--more-->
 
 {{< callout type="info" >}}
-  Prior adjusting any settings, [fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) the [`k3s-cluster`](https://{{< param variables.repository >}}) repository.
+  Prior adjusting any settings, [fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) the [`k3s-cluster`](https://{{< param variables.repository.cluster >}}) repository.
 {{< /callout >}}
 
 ## Next

k3s-cluster/content/wiki/guide/configuration/_index.md

@@ -11,7 +11,7 @@ The configuration guides present in this section allow you to configure the K3s
 <!--more-->
 
 {{< callout type="info" >}}
-  Prior adjusting any settings, [fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) the [`k3s-cluster`](https://{{< param variables.repository >}}) repository.
+  Prior adjusting any settings, [fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) the [`k3s-cluster`](https://{{< param variables.repository.cluster >}}) repository.
 {{< /callout >}}
 
 ## OS Installation

k3s-cluster/content/wiki/guide/configuration/inventory.md

@@ -41,7 +41,7 @@ The `serial` structure has the following pattern:
 {{% /details %}}
 
 {{< callout type="info" >}}
-  Update the `serial` structure into [`provisioning.yaml`](https://{{< param variables.repository >}}/blob/main/provisioning.yaml) playbook file.
+  Update the `serial` structure into [`provisioning.yaml`](https://{{< param variables.repository.cluster >}}/blob/main/provisioning.yaml) playbook file.
 {{< /callout >}}
 
 Example of `serial` structure with 3 `server` type nodes and 5 `agent` type nodes, used into [Reset](/k3s-cluster/wiki/guide/playbooks/reset) playbook:
@@ -62,22 +62,22 @@ The `serial` structure has the following pattern:
 {{% /details %}}
 
 {{< callout type="info" >}}
-  Update the `serial` structure into [`reset.yaml`](https://{{< param variables.repository >}}/blob/main/reset.yaml) playbook file.
+  Update the `serial` structure into [`reset.yaml`](https://{{< param variables.repository.cluster >}}/blob/main/reset.yaml) playbook file.
 {{< /callout >}}
 
 ### `k3s_vars.server.controlplane.tainted`
 
 The setting allows the end-user to control where the Kubernetes pods will be deployed. In a scenario where there is only a single or no `agent` type nodes deployed, setting the value to `false` will allow pods to be deployed into any cluster node type.
 
 {{< callout type="info" >}}
-  Update the setting into K3s role [`main.yaml`](https://{{< param variables.repository >}}/blob/main/roles/k3s/defaults/main.yaml) variables file.
+  Update the setting into K3s role [`main.yaml`](https://{{< param variables.repository.cluster >}}/blob/main/roles/k3s/defaults/main.yaml) variables file.
 {{< /callout >}}
 
 {{% /steps %}}
 
 ## Configuration
 
-The [`hosts.yaml`](https://{{< param variables.repository >}}/blob/main/inventory/cluster/hosts.yaml) inventory file contains the list of `server` and `agent` cluster node types.
+The [`hosts.yaml`](https://{{< param variables.repository.cluster >}}/blob/main/inventory/cluster/hosts.yaml) inventory file contains the list of `server` and `agent` cluster node types.
 
 {{< callout type="info" >}}
   Please review the [K3s Architecture](https://docs.k3s.io/architecture), for further details.
@@ -93,7 +93,7 @@ Example of a HA cluster inventory with 4 nodes:
 
 {{% details title="Inventory Details" closed="true" %}}
 
-Inventory, set into [`hosts.yaml`](https://{{< param variables.repository >}}/blob/main/inventory/cluster/hosts.yaml) inventory file:
+Inventory, set into [`hosts.yaml`](https://{{< param variables.repository.cluster >}}/blob/main/inventory/cluster/hosts.yaml) inventory file:
 
 ```yaml
 server:
@@ -112,7 +112,7 @@ cluster:
     agent:
 ```
 
-Batch size, set into [`provisioning.yaml`](https://{{< param variables.repository >}}/blob/main/provisioning.yaml) playbook file:
+Batch size, set into [`provisioning.yaml`](https://{{< param variables.repository.cluster >}}/blob/main/provisioning.yaml) playbook file:
 
 ```yaml
 serial:
@@ -121,7 +121,7 @@ serial:
   - 1
 ```
 
-Batch size, set into [`reset.yaml`](https://{{< param variables.repository >}}/blob/main/reset.yaml) playbook file:
+Batch size, set into [`reset.yaml`](https://{{< param variables.repository.cluster >}}/blob/main/reset.yaml) playbook file:
 
 ```yaml
 serial:
@@ -137,7 +137,7 @@ serial:
   The above detailed configuration will introduce a SPOF, since Kubernetes pods are deployed to a single or no `agent` type nodes.
 {{< /callout >}}
 
-To address this issue, set the `k3s_vars.server.controlplane.tainted` option to `false` into K3s role [`main.yaml`](https://{{< param variables.repository >}}/blob/main/roles/k3s/defaults/main.yaml) variables file.
+To address this issue, set the `k3s_vars.server.controlplane.tainted` option to `false` into K3s role [`main.yaml`](https://{{< param variables.repository.cluster >}}/blob/main/roles/k3s/defaults/main.yaml) variables file.
 
 ### Non High Availability
 
@@ -151,7 +151,7 @@ Example of a Non HA cluster inventory with 2 nodes:
 
 {{% details title="Inventory Details" closed="true" %}}
 
-Inventory, set into [`hosts.yaml`](https://{{< param variables.repository >}}/blob/main/inventory/cluster/hosts.yaml) inventory file:
+Inventory, set into [`hosts.yaml`](https://{{< param variables.repository.cluster >}}/blob/main/inventory/cluster/hosts.yaml) inventory file:
 
 ```yaml
 server:
@@ -168,14 +168,14 @@ cluster:
     agent:
 ```
 
-Batch size, set into [`provisioning.yaml`](https://{{< param variables.repository >}}/blob/main/provisioning.yaml) playbook file:
+Batch size, set into [`provisioning.yaml`](https://{{< param variables.repository.cluster >}}/blob/main/provisioning.yaml) playbook file:
 
 ```yaml
 serial:
   - 1
 ```
 
-Batch size, set into [`reset.yaml`](https://{{< param variables.repository >}}/blob/main/reset.yaml) playbook file:
+Batch size, set into [`reset.yaml`](https://{{< param variables.repository.cluster >}}/blob/main/reset.yaml) playbook file:
 
 ```yaml
 serial: