pangolin_mirror/docs-v2
1
0
Fork 0
mirror of https://github.com/fosrl/docs-v2.git synced 2026-10-21 03:59:16 +02:00
Code Issues Packages Projects Releases Wiki Activity

chore(self-host/manual/kubernetes): Refactor documentation for Pangolin and Newt Kubernetes deployment

Browse Source 
- Updated titles and descriptions for clarity and consistency across Helm, Kustomize, and troubleshooting guides.
- Enhanced the overview section to better describe deployment options and components.
- Revised prerequisites to streamline requirements for deploying Pangolin and Sites (Newt).
- Improved clarity on storage, networking, and security requirements, including detailed RBAC and NetworkPolicy considerations.
- Removed deprecated sections and added new information regarding Gerbil and proxy protocol handling.
- Adjusted resource planning guidelines to reflect best practices for Kubernetes deployments.

Signed-off-by: Marc Schäfer <git@marcschaeferger.de>
This commit is contained in:
Marc Schäfer
2026-05-14 18:06:01 +02:00
parent 792c5d8a23
commit e3d14a6cb0
17 changed files with 285 additions and 1138 deletions
Download Patch File Download Diff File Expand all files Collapse all files
self-host/manual/kubernetes/gitops/argocd.mdx
-44
View File
@@ -10,50 +10,6 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
Argo CD is a declarative GitOps tool that continuously syncs your cluster state to your Git repository. This guide covers installing Pangolin and Newt using Argo CD.
## Argo CD overview
Argo CD watches your Git repository (or Helm chart repository) and automatically reconciles Kubernetes resources to match the desired state defined in Git.
**Key concepts**:
- **Application**: Argo CD custom resource that defines what to deploy, where, and how
- **Helm source**: Argo CD uses Helm to render charts; you provide values
- **Kustomize source**: Argo CD uses Kustomize to build manifests
- **Sync**: Process of applying desired state to the cluster
- **Drift**: When cluster state diverges from Git (Argo CD can detect and correct)
## Prerequisites
- Argo CD installed in your cluster (in `argocd` namespace, typically)
- Helm repo configured: `helm repo add fossorial https://charts.fossorial.io`
- Git repository with Argo CD configuration (optional, can use chart repo as source)
- Newt auth secret (if installing Newt)
## Install Argo CD
If you don't have Argo CD yet:
```bash
# Create namespace
kubectl create namespace argocd
# Install Argo CD
helm repo add argo https://argoproj.github.io/argo-helm
helm repo update argo
helm install argocd argo/argo-cd -n argocd
```
Access the Argo CD UI:
```bash
# Port-forward
kubectl port-forward -n argocd svc/argocd-server 8080:443
# Visit https://localhost:8080
# Default username: admin
# Password: kubectl get secret -n argocd argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d
```
## Install Pangolin with Argo CD using Helm
### Step 1: Create Pangolin namespace
self-host/manual/kubernetes/gitops/flux.mdx
-42
View File
@@ -10,22 +10,6 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
Flux is a declarative GitOps tool that uses Kubernetes-native Custom Resources to manage deployments. This guide covers installing Pangolin and Newt using Flux.
## Flux overview
Flux watches your Git repository and continuous reconciles cluster state using Kubernetes CRDs:
- **HelmRepository**: Defines a Helm chart repository
- **HelmRelease**: Declaratively manages a Helm chart deployment
- **GitRepository**: References a Git repository
- **Kustomization**: Reconciles Kustomize overlays
- **OCIRepository**: References an OCI-based container registry (for Helm charts)
**Key benefits**:
- Native Kubernetes reconciliation (no separate UI needed, though one exists)
- Lightweight footprint
- Excellent for multi-cluster deployments
- Declarative everything: sources, releases, dependencies
## Flux prerequisites
@@ -523,32 +507,6 @@ clusters/
Each environment's HelmRelease uses environment-specific values.
## Important notes
### CRD management
When using Flux with Helm charts that include CRDs:
```yaml
spec:
install:
crds: Create # Create CRDs on first install
upgrade:
crds: CreateReplace # Update CRDs on upgrade
```
### Namespace creation
Flux automatically creates namespaces if they don't exist. Ensure appropriate RBAC.
### GitOps best practices
- Use branches for different environments
- Protect production branches with review requirements
- Store secrets using sealed-secrets or external-secrets
- Track all changes in Git
- Use consistent naming conventions
## Next steps
<CardGroup cols={2}>
self-host/manual/kubernetes/gitops/overview.mdx
+45 -320
View File
@@ -1,351 +1,76 @@
---
title: "GitOps Overview"
description: "Git-driven Kubernetes deployments for Pangolin and Newt using Argo CD or Flux."
description: "Deploy Pangolin and Sites (Newt) with GitOps workflows such as Argo CD or Flux."
---
import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
<PangolinCloudTocCta />
Use GitOps when Pangolin and Sites (Newt) should be reconciled from Git instead of being installed manually from a local shell.
Can be used together with Blueprints — see [Blueprint config reference](/self-host/advanced/config-file) for details.
GitOps is a declarative approach to infrastructure management where your Git repository is the single source of truth for cluster state. Changes go through Git; the GitOps tool automatically reconciles the cluster to match.
These guides assume you already use, or plan to use, a GitOps controller such as Argo CD or Flux.
General GitOps concepts such as reconciliation, desired state, and Git-driven workflows are outside the scope of this documentation. Refer to your GitOps controller's documentation for those concepts.
## What is GitOps?
## Supported GitOps paths
GitOps reconciliation loop:
<CardGroup cols={2}>
<Card title="Argo CD Guide" href="/self-host/manual/kubernetes/gitops/argocd" icon="code-branch">
Deploy Pangolin or Sites (Newt) with Argo CD Applications.
</Card>
<Card title="Flux Guide" href="/self-host/manual/kubernetes/gitops/flux" icon="code-branch">
Deploy Pangolin or Sites (Newt) with Flux HelmRelease or Kustomization resources.
</Card>
</CardGroup>
<Steps>
<Step title="Declare desired state in Git">
**Git repository** contains desired state (manifests, Helm values, Kustomize overlays).
</Step>
<Step title="GitOps controller watches source">
**GitOps tool** (Argo CD or Flux) watches the Git repository.
</Step>
<Step title="Detect changes and drift">
The controller detects new commits or drift between Git and the live cluster.
</Step>
<Step title="Reconcile cluster">
The controller syncs cluster state to match Git state.
</Step>
<Step title="Continuous convergence">
**Result**: Cluster stays aligned with the declared Git configuration.
</Step>
</Steps>
## What GitOps manages
## Benefits
A GitOps workflow can reconcile the same deployment inputs used by the other Kubernetes guides:
- **Version control**: All infrastructure changes tracked in Git
- **Audit trail**: See who changed what and when
- **Rollback**: Revert to previous state by reverting Git commits
- **Automation**: No manual `kubectl apply` commands needed
- **Drift detection**: Automatic alerts if cluster diverges from Git
| Input | Used for |
| --- | --- |
| Helm chart values | Configure Pangolin, controller mode, database mode, ingress, Sites, and related components. |
| Kustomize overlays | Patch or compose rendered manifests for environment-specific deployments. |
| Kubernetes Secrets | Provide credentials, TLS material, database connection details, or Site connector credentials. |
| Custom resources | Manage Argo CD Applications, Flux HelmReleases, Flux Kustomizations, or related controller resources. |
## GitOps tools for Kubernetes
## Recommended layout
### Argo CD
Keep the Pangolin and Site configuration close to the cluster or environment that owns it.
- **UI**: Web-based dashboard for monitoring and manual syncs
- **Approach**: External reconciler (watches Git, applies to cluster)
- **Supports**: Helm charts, Kustomize overlays, raw YAML
- **Best for**: Teams who want GitOps with a UI, hybrid manual/automated workflows
**Use Argo CD if**:
- You want a visual dashboard
- You need frequent manual sync capabilities
- You're already using Argo CD for other workloads
See: [Argo CD Install Guide](/self-host/manual/kubernetes/gitops/argocd)
### Flux
- **CRDs**: Kubernetes-native Custom Resources (HelmRelease, Kustomization, GitRepository)
- **Approach**: Declarative reconciliation using Kubernetes resources
- **Supports**: Helm charts, Kustomize overlays, raw YAML, OCI registries
- **Best for**: Teams who want declarative Kubernetes-way GitOps, lightweight controllers
**Use Flux if**:
- You prefer Kubernetes-native CRDs
- You want a lightweight, modern GitOps tool
- You're already using Flux for other workloads
See: [Flux Install Guide](/self-host/manual/kubernetes/gitops/flux)
## Recommended repository structure
For multi-environment Pangolin/Newt deployments, organize your Git repository like this:
```
my-org/infrastructure/
```text
infrastructure/
├── clusters/
│ ├── production/
│ │ ├── pangolin/
│ │ │ ├── values.yaml
│ │ │ └── kustomization.yaml (if using Kustomize)
│ │ └── newt/
│ │ ├── values.yaml
│ │ └── kustomization.yaml
│ │ └── sites/
│ ├── staging/
│ │ ├── pangolin/
│ │ └── newt/
│ │ └── sites/
│ └── dev/
│ ├── pangolin/
│ └── newt/
├── apps/
│ ├── pangolin/
│ │ ├── helm/
│ │ │ ├── values-base.yaml
│ │ │ ├── values-prod.yaml
│ │ │ └── values-staging.yaml
│ │ └── kustomize/
│ │ ├── base/
│ │ └── overlays/
│ └── newt/
│ ├── helm/
│ └── kustomize/
└── .gitignore
│ └── sites/
└── shared/
├── pangolin/
└── sites/
```
**Pattern**:
- `clusters/` → environment-specific configuration
- `apps/` → shared, reusable application configuration
- Environment overlays layer on top of app definitions
## Secrets in GitOps
<Warning>
**Never commit plaintext secrets to Git.** Use secret management tools instead.
</Warning>
Options for managing secrets in GitOps:
### Sealed Secrets
- **Tool**: [sealed-secrets](https://github.com/bitnami-labs/sealed-secrets)
- **How**: Encrypt secrets with cluster-specific key; safe to commit encrypted secrets
- **Decrypt**: Only the cluster can decrypt (uses private key)
```bash
# Encrypt a secret
echo -n mypassword | kubeseal -f - > secret.yaml
# Git tracks encrypted secret.yaml
# Cluster auto-decrypts on apply
```
### External Secrets Operator
- **Tool**: [external-secrets](https://external-secrets.io/)
- **How**: Reference secrets stored in external vault (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault)
- **Git**: Stores reference only, not secret values
```yaml
apiVersion: external-secrets.io/v1beta1
kind: SecretStore
metadata:
name: vault-backend
spec:
provider:
vault:
server: "https://vault.example.com"
```
### SOPS (Secrets Operations)
- **Tool**: [SOPS](https://github.com/mozilla/sops)
- **How**: Encrypt YAML files; decrypt at deploy time
- **Git**: Stores encrypted files
```bash
sops --encrypt secrets.yaml > secrets.enc.yaml
# Commit secrets.enc.yaml; tool decrypts on apply
```
### Cloud Provider Secrets
- **AWS**: Use AWS Secrets Manager or Parameter Store with IRSA (IAM Roles for Service Accounts)
- **Azure**: Use Azure Key Vault with pod identity
- **GCP**: Use Google Secret Manager with workload identity
<Tip>
Choose a secret management strategy **before** setting up GitOps. Seal secrets once; keep approach consistent.
</Tip>
## GitOps workflow example
### 1. Set up Git repository
```bash
git clone https://github.com/my-org/infrastructure.git
cd infrastructure
mkdir -p clusters/production/pangolin
cd clusters/production/pangolin
```
### 2. Create configuration
```bash
# values.yaml with Pangolin config
cat > values.yaml <<EOF
deployment:
type: controller
mode: multi
database:
mode: cloudnativepg
pangolin:
config:
app:
dashboard_url: https://pangolin.example.com
domains:
domain1:
base_domain: example.com
gerbil:
base_endpoint: vpn.example.com
EOF
git add values.yaml
git commit -m "Add production Pangolin config"
git push
```
### 3. Install GitOps tool
```bash
# For Argo CD
kubectl create namespace argocd
helm repo add argo https://argoproj.github.io/argo-helm
helm install argocd argo/argo-cd -n argocd
# For Flux
flux bootstrap github \
--owner=my-org \
--repo=infrastructure \
--personal \
--path=clusters/production
```
### 4. Create Application/HelmRelease
**With Argo CD**:
```yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: pangolin
namespace: argocd
spec:
project: default
source:
repoURL: https://github.com/my-org/infrastructure
targetRevision: main
path: clusters/production/pangolin
helm:
values: values.yaml
destination:
server: https://kubernetes.default.svc
namespace: pangolin
syncPolicy:
automated:
prune: true
selfHeal: true
```
**With Flux**:
```yaml
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
name: pangolin
namespace: pangolin
spec:
interval: 10m
chart:
spec:
chart: pangolin
sourceRef:
kind: HelmRepository
name: fossorial
namespace: flux-system
values:
deployment:
type: controller
mode: multi
```
### 5. Push to Git
```bash
git add pangolin-app.yaml
git commit -m "Add Argo CD Application for Pangolin"
git push
```
**Result**: GitOps tool automatically detects the new Application and begins reconciliation.
### 6. Monitor
**Argo CD**:
```bash
# Port-forward to UI
kubectl port-forward -n argocd svc/argocd-server 8080:443
# Visit https://localhost:8080
```
**Flux**:
```bash
# Check reconciliation status
flux get all
# View logs
flux logs --all-namespaces --follow
```
## Common use cases
### Multi-environment deployments
Use Git branches, directories, or environments to manage dev, staging, production:
```
clusters/dev/pangolin → helm values for dev
clusters/staging/pangolin → helm values for staging
clusters/production/pangolin → helm values for production
```
Each environment syncs independently.
### Automatic deployments on chart update
Flux or Argo CD can watch a Helm repository and auto-update when a new chart version is released:
```yaml
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
name: pangolin
spec:
chart:
spec:
chart: pangolin
version: ">=0.1.0" # auto-upgrade to latest 0.1.x
```
### Drift detection and remediation
Argo CD and Flux both support continuous drift detection:
- **Argo CD**: Detects drift on demand or continuously; can auto-sync on drift
- **Flux**: Reconciles on interval; rolls back manual cluster changes
Use environment-specific directories for values, patches, and secrets that differ between clusters. Use shared directories only for reusable configuration that should stay the same across environments.
## Next steps
<CardGroup cols={2}>
<Card title="Argo CD Install" href="/self-host/manual/kubernetes/gitops/argocd" icon="code-branch" />
<Card title="Flux Install" href="/self-host/manual/kubernetes/gitops/flux" icon="code-branch" />
<Card title="Helm Quick-Start" href="/self-host/manual/kubernetes/helm" icon="box" />
<Card title="Kustomize Quick-Start" href="/self-host/manual/kubernetes/kustomize" icon="layer-group" />
<Card title="Argo CD Guide" href="/self-host/manual/kubernetes/gitops/argocd" icon="code-branch">
Create Argo CD Applications for Pangolin and Sites (Newt).
</Card>
<Card title="Flux Guide" href="/self-host/manual/kubernetes/gitops/flux" icon="code-branch">
Create Flux sources, HelmReleases, or Kustomizations for Pangolin and Sites (Newt).
</Card>
<Card title="Choose an Installation Path" href="/self-host/manual/kubernetes/choose-method" icon="route">
Compare the supported Kubernetes deployment paths.
</Card>
<Card title="Prerequisites" href="/self-host/manual/kubernetes/prerequisites" icon="list-check">
Review cluster, networking, storage, RBAC, and resource requirements.
</Card>
</CardGroup>