Add: Docs

.gitignore

@@ -2,3 +2,4 @@
 .terraform
 secrets
 .env
+site

Makefile

@@ -0,0 +1,11 @@
+
+default: build
+
+build:
+ docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material build
+
+deploy:
+ docker run --rm -it -v ~/.ssh:/root/.ssh -v ${PWD}:/docs squidfunk/mkdocs-material gh-deploy
+
+dev:
+ docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material

docs/appconfig.md

@@ -0,0 +1,35 @@
+## Application Definition
+
+Here is a list of available configuration options inside the `apps` array.o
+
+### Required
+
+| Parameter | Type | Example | Description |
+|-----------|--------|---------|-------------|
+| name | string | `"argocd"` | Name of your application & namespace [if not specified] | 
+| repoURL | string | `"https://github.com/nold360/heqet"` | URL to git or Helmchart repo | 
+| path | string | `"charts/heqet"` | Path to chart if using git in `repoURL` |
+| chart | string | `"heqet"` | Chart name [ only use either `path` or `chart` ] |
+| targetRevision | string | `"1.2.3"` or `"master"` | Version of Helm-Chart or Branch/Tag of git |
+
+### Optional 
+
+| Parameter | Type | Default | Example | Description |
+|-----------|--------|---------|---------|-------------|
+| disabled | bool | false | `true` | Disable App |
+| noCreateNamespace | bool | false | `true` | Don't create namespace for app |
+| namespace | string | .Values.name | `"superns"` | Name of application namespace |
+| annotations | hash | | `my.anno.org/stuff: is-awesome` | Namespace annotations |
+| syncWave | string | `"0"` | `"-2" | ArgoCD SyncWave | 
+| project | string | `"default"` | `"myproject"` | Name of ArgoCD Project |
+| server | string | `"https://kubernetes.default.svc"` | `https://my.external.cluster:8443` | K8s Cluster to deploy to |
+| prune | bool | `false` | `true` | ArgoCD automatic prune app |
+| selfHeal | bool | `false` | `true` | ArgoCD automatic self-heal app |
+| ignoreDiff | array | | See ArgoCD docs | ArgoCD [ignoreDifferences](https://argoproj.github.io/argo-cd/user-guide/diffing/)
+| parameters | array | |- name: ingress.host<br>value: awesome.url | Parameters override values of app |
+
+## Custom Resource Definitions
+CRDs might be required before applying application configuration. If so, copy the `crd.yaml` into heqets `templates/crds`-Directory.
+
+## Full Example
+Check out the `test`-Branch of this repo for my current testing setup.

docs/generators/index.md

@@ -0,0 +1,2 @@
+# Generators
+Heqet contains a "generators" feature which will create additional resources for you. Currently only one generator is implemented. 

docs/generators/vault.md

@@ -0,0 +1,36 @@
+# VaultSecret Generator
+The VaultSecret generator will create a `VaultSecret` for every secret specified in the `secrets`-hash. It's based on the [vault-secret-operator](https://github.com/ricoberger/vault-secrets-operator). 
+
+## Values
+Here is an example for a simple secret:
+``` yaml
+apps:
+ - name: myapp
+ secrets:
+ - name: my-secret
+ keys: 
+ - username
+ - password
+ # default:
+ type: Opaque 
+```
+
+This will result in following resource. Notice that the path inside of Vault is `/heqet/<name-of-app>/<name-of-secret>`.
+``` yaml
+apiVersion: ricoberger.de/v1alpha1
+kind: VaultSecret
+metadata:
+ name: vpn-config
+ namespace: "myapp"
+ labels:
+ app: myapp
+ annotations:
+ argocd.argoproj.io/sync-wave: "-1"
+spec:
+ keys:
+ - username
+ - password
+ path: heqet/myapp/my-secret
+ type: Opaque
+```
+

docs/index.md

@@ -0,0 +1,30 @@
+# Heqet
+
+*Heqet (Egyptian ḥqt, also ḥqtyt "Heqtit") is an Egyptian goddess of fertility.*
+
+Heqet is my attempt to make Kubernetes GitOps Deployments as easy as possible. It reduces the need of configuration by generating the required Application definitions for you. Heqet heavily relies on a Helm-Chart which will generate all applications, namespaces & more using ArgoCDs [App-of-Apps-Pattern](https://argoproj.github.io/argo-cd/operator-manual/cluster-bootstrapping/).
+
+## Keyfeatures
+ * Easy Setup [Sane Kubernetes cluster + PVC-StorageClass]
+ * Easy application definition & configuration
+ * Follows the GitOps principles
+ * Deploy a whole application environment or cluster from a singe git-repo
+
+**This project is still in a very early stage of development, but feel free to try it out & contribute!**
+
+## Components & Configuration
+
+Core component is `ArgoCD` which will deploy Heqet & also your apps! All you need is a git-repo & k8s cluster.
+
+The heqet Helm-Chart will generate ArgoCD Applications, namespaces and if required vault Secrets. All you need to do if add your Helm-Application to heqet's `values.yaml`. 
+
+If more configuration values are required, simply throw your applications `values.yaml` into heqets `values.d` folder, named as the application [e.g. `values.d/argocd.yaml`.
+
+## Installation
+
+Installing heqet can't be simpler, after configuring your apps, argocd and pushing it to your git repo:
+1. Configure `manifests/heqet-apps.yaml` to match your Setup
+2. `kubectl apply -f manifests/argocd.yaml`
+3. `kubectl apply -f manifests/heqet-apps.yaml`
+ 
+ArgoCD will start and bootstrap heqet. 

docs/k3s.md

@@ -0,0 +1,111 @@
+# Heqet on K3s
+
+## Bootstrap K3s
+See: [K3s Install Options](https://rancher.com/docs/k3s/latest/en/installation/install-options/)
+
+Or simply run:
+``` shellsession
+curl -sfL https://get.k3s.io | sh -
+```
+
+## Bootstrap ArgoCD using Helm
+
+`kubectl apply -f manifests/argocd-helm.yaml` 
+
+``` yaml
+---
+apiVersion: v1
+kind: Namespace
+metadata:
+ name: argocd
+---
+apiVersion: helm.cattle.io/v1
+kind: HelmChart
+metadata:
+ name: argocd
+ namespace: kube-system
+spec:
+ chart: argo-cd
+ repo: https://argoproj.github.io/argo-helm
+ targetNamespace: argocd
+ set:
+ configs.secret.argocdServerAdminPassword: "$2y$10$IuaM9Ad1mPMycjnStOdNc.wjRlLtI8448F/hS.eA0XJLH9r/ZwRv."
+ valuesContent: |-
+ controller:
+ containerSecurityContext:
+ capabilities:
+ drop:
+ - all
+ readOnlyRootFilesystem: true
+ dex:
+ containerSecurityContext:
+ capabilities:
+ drop:
+ - all
+ readOnlyRootFilesystem: true
+ redis:
+ containerSecurityContext:
+ capabilities:
+ drop:
+ - all
+ readOnlyRootFilesystem: true
+ server:
+ containerSecurityContext:
+ capabilities:
+ drop:
+ - all
+ readOnlyRootFilesystem: true
+ ingress:
+ enabled: true
+ hosts:
+ - argocd.k3s
+ extraArgs:
+ - --insecure
+ reposerver:
+ containerSecurityContext:
+ capabilities:
+ drop:
+ - all
+ readOnlyRootFilesystem: true
+```
+
+The Password should be `admin`.
+
+
+## Bootstrap Heqet
+
+`kubectl apply -f manifests/heqet-apps.yaml`
+
+``` yaml
+---
+apiVersion: v1
+kind: Namespace
+metadata:
+ name: heqet
+---
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+ name: heqet
+ namespace: argocd
+spec:
+ destination:
+ namespace: heqet
+ server: 'https://kubernetes.default.svc'
+ source:
+ path: .
+ repoURL: 'https://github.com/nold360/heqet'
+ targetRevision: test
+ helm:
+ valueFiles:
+ - values.yaml
+ project: default
+ syncPolicy:
+ automated:
+ prune: true
+ selfHeal: false
+```
+
+## Profit!
+
+Now K3s should be setup. ArgoCD should be deployed by K3s-Helm-Operator. The Heqet-Application will bootstrap ArgoCD & hand over the control of all Application configuration to ArgoCD.

docs/vault.md

@@ -0,0 +1,95 @@
+# Vault
+
+This are some quick notes I took on how to setup a simple Vault for usage with heqet. For a more detailed documentation on how to configure Vault, check out the [Official Vault Docs](https://www.vaultproject.io/docs).
+
+Note: Most of this commands can be executed either using the `vault` command on your local device or the inside the vault pod itself.
+
+## Init Vault using GPG
+
+### Copy GPG Public Key
+``` shellsession
+cat > nold.pub << EOF
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+
+mQENBGBXTjkBCAC7qZU1cz7RWYbAb838ypRLJZKLWfVBvry4XYwWPN0Rcj55dPN+
+...
+5of4H66FzNwJxYrunmM5KTeUxZiLPC1JoKMF5uvKoo59TD0IuAPq735QDjWbS4vb
+dMtSqTCinZSd
+=wuZw
+-----END PGP PUBLIC KEY BLOCK-----
+EOF
+```
+
+### Init Vault
+``` shellsession
+vault operator init -key-shares=1 -key-threshold=1 -pgp-keys="nold.pub"
+```
+
+
+### Save Unseal Key somewhere sage e.g. Keepass
+
+### Decode Unseal Key
+``` shellsession
+$ echo $unseal-key | base64 -d | gpg -dq
+```
+
+### Unseal Vault
+``` shellsession
+vault operator unseal
+```
+
+
+## Enable Kubernetes Auth
+
+```shellsession
+vault auth enable kubernetes
+
+vault write auth/kubernetes/config \
+ token_reviewer_jwt="$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)" \
+ kubernetes_host=https://${KUBERNETES_PORT_443_TCP_ADDR}:443 \
+ [email protected]/var/run/secrets/kubernetes.io/serviceaccount/ca.crt
+```
+
+ 
+
+## Create Secret Store
+
+```
+vault secrets enable -path=heqet kv-v2
+```
+
+## Add Secrets-Operator Role & Policy
+
+### Create Policy
+```json
+cat > app-policy.hcl << EOF
+path "heqet/+/*" {
+ capabilities = ["read"]
+}
+EOF
+
+vault policy write heqet-app ./app-policy.hcl
+```
+
+
+### Add Auth Role
+
+```shellsession
+
+vault write auth/kubernetes/role/heqet-app \
+ bound_service_account_names=vault-secrets-operator \
+ bound_service_account_namespaces=vault-secrets-operator \
+ policies=heqet-app \
+ ttl=6h
+```
+
+## Add Secrets
+
+Remember, Secret path: `heqet/<APP-NAME>/<SECRET-NAME>`
+
+```shellsession	
+vault kv put heqet/argocd/argocd-secret admin.password='$2y$12$FP8OlsVj5pOOqRAhI4XPoev1STaW01uUEZGcNPQtVZmpacebNhj9i' server.secretkey="pDYAWK2mHa68GwwVPAsQOsG/SUT8iIo3S3FXYUWf2qM="
+vault kv put heqet/loki-stack/loki-stack-grafana admin-user=admin admin-password='grafana'
+vault kv put heqet/pihole/pihole-admin password=pihole
+vault kv put heqet/minio/minio-secret secret-key=secret access-key=access
+```

manifests/argocd-helm.yaml

@@ -0,0 +1,55 @@
+---
+apiVersion: v1
+kind: Namespace
+metadata:
+ name: argocd
+---
+apiVersion: helm.cattle.io/v1
+kind: HelmChart
+metadata:
+ name: argocd
+ namespace: kube-system
+spec:
+ chart: argo-cd
+ repo: https://argoproj.github.io/argo-helm
+ targetNamespace: argocd
+ set:
+ # Password: Admin
+ configs.secret.argocdServerAdminPassword: "$2y$10$IuaM9Ad1mPMycjnStOdNc.wjRlLtI8448F/hS.eA0XJLH9r/ZwRv."
+ valuesContent: |-
+ controller:
+ containerSecurityContext:
+ capabilities:
+ drop:
+ - all
+ readOnlyRootFilesystem: true
+ dex:
+ containerSecurityContext:
+ capabilities:
+ drop:
+ - all
+ readOnlyRootFilesystem: true
+ redis:
+ containerSecurityContext:
+ capabilities:
+ drop:
+ - all
+ readOnlyRootFilesystem: true
+ server:
+ containerSecurityContext:
+ capabilities:
+ drop:
+ - all
+ readOnlyRootFilesystem: true
+ ingress:
+ enabled: true
+ hosts:
+ - argocd.k3s
+ extraArgs:
+ - --insecure
+ reposerver:
+ containerSecurityContext:
+ capabilities:
+ drop:
+ - all
+ readOnlyRootFilesystem: true

mkdocs.yml

@@ -0,0 +1,24 @@
+site_name: Heqet - Simple ArgoCD Bootstrapping
+repo_url: https://github.com/nold360/heqet
+remote_branch: gh-deploy
+theme:
+ features:
+ - navigation.top
+ name: material
+ palette:
+ - media: "(prefers-color-scheme: light)"
+ scheme: default
+ primary: teal
+ toggle:
+ icon: material/toggle-switch-off-outline
+ name: Switch to dark mode
+ - media: "(prefers-color-scheme: dark)"
+ scheme: slate
+ primary: teal
+ toggle:
+ icon: material/toggle-switch
+ name: Switch to light mode
+
+markdown_extensions:
+ - toc:
+ permalink: true