Browse Source

Add: Docs

drone
nold 9 months ago
parent
commit
4dee161505
  1. 1
      .gitignore
  2. 11
      Makefile
  3. 35
      docs/appconfig.md
  4. 2
      docs/generators/index.md
  5. 36
      docs/generators/vault.md
  6. 30
      docs/index.md
  7. 111
      docs/k3s.md
  8. 95
      docs/vault.md
  9. 55
      manifests/argocd-helm.yaml
  10. 24
      mkdocs.yml

1
.gitignore

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

11
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

35
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.

2
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.

36
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
```

30
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.

111
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.

95
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 \
kubernetes_ca_cert=@/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
```

55
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

24
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
Loading…
Cancel
Save