Bootstrap GitOps avec k3s¶
2025
đ ProcĂ©dure dâinstallation GitOps avec ArgoCD sur k3s¶
Voici la procédure complÚte pour mettre en place un environnement GitOps sur k3s en utilisant ArgoCD, avec Gitea comme source de vérité (dépÎt GitOps).
Ătape |
Outil principal |
RĂŽle |
|---|---|---|
0. Préparation |
Git, clé SSH |
Sâassurer que tout est prĂȘt sur la machine hĂŽte. |
1. Kubernetes minimal |
k3s |
Installer le cluster le plus rapidement possible. |
2. DépÎt GitOps temporaire (Bootstrapping) |
Gitea (manuel) |
PrĂ©parer un serveur Git opĂ©rationnel pour le bootstrapping dâArgoCD. |
3. Moteur GitOps |
ArgoCD (manuel) |
Installer ArgoCD et le configurer pour surveiller le dépÎt Gitea temporaire. |
4. Intégration de Gitea dans GitOps |
Application ArgoCD |
Placer les manifests ArgoCD pour Gitea dans le dĂ©pĂŽt Git afin quâArgoCD en assure la gestion complĂšte. |
5. Finalisation |
Test, validation |
Vérifier que GitOps fonctionne et gÚre Gitea. |
6. Intégration de MetalLB dans GitOps |
Application ArgoCD |
Déployer MetalLB via GitOps pour fournir des services LoadBalancer. |
7. Intégration de HashiCorp Vault |
Application Argo CD, Vault |
DĂ©ployer Vault via GitOps (Helm) et effectuer lâinitialisation/dĂ©scellement manuel. |
8. Intégration de Harbor dans GitOps |
Application Argo CD |
DĂ©ployer Harbor, en sâappuyant potentiellement sur Vault pour la gestion sĂ©curisĂ©e des secrets. |
Ătape 0 : PrĂ©paration de la machine hĂŽte (5 min)¶
Cette étape consiste à installer tous les outils nécessaires sur votre machine locale.
Installer Git
Installer le CLI Kubernetes (
kubectl) : Il est essentiel pour interagir avec le cluster.curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl" chmod +x ./kubectl sudo mv ./kubectl /usr/local/bin/kubectl
Installer helm :
sudo apt-get install curl gpg apt-transport-https --yes curl -fsSL https://packages.buildkite.com/helm-linux/helm-debian/gpgkey | gpg --dearmor | sudo tee /usr/share/keyrings/helm.gpg > /dev/null echo "deb [signed-by=/usr/share/keyrings/helm.gpg] https://packages.buildkite.com/helm-linux/helm-debian/any/ any main" | sudo tee /etc/apt/sources.list.d/helm-stable-debian.list sudo apt-get update sudo apt-get install helm
Installer le CLI ArgoCD :
curl -sSL -o argocd-linux-amd64 https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64 sudo install -m 555 argocd-linux-amd64 /usr/local/bin/argocd rm argocd-linux-amd64
Ătape 1 : Installation de k3s¶
Nous déployons le cluster Kubernetes léger.
Installation de k3s :
curl -sfL https://get.k3s.io | sh -
Configuration de
kubectl:mkdir -p ~/.kube sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config sudo chown $(id -u):$(id -g) ~/.kube/config
Vérification :
kubectl get nodes # The status should be 'Ready'
Ătape 2 : DĂ©ploiement du dĂ©pĂŽt GitOps temporaire (Bootstrapping)¶
Nous installons manuellement Gitea afin quâil puisse hĂ©berger le code gĂ©rĂ© par GitOps.
Déployer Gitea avec Helm (manuellement) :
helm repo add gitea-charts https://dl.gitea.io/charts/ kubectl create namespace gitea helm install gitea gitea-charts/gitea -n gitea
GĂ©nĂ©rer une clĂ© SSH : Cette clĂ© permettra Ă ArgoCD dâaccĂ©der Ă votre dĂ©pĂŽt Gitea.
ssh-keygen -t ed25519 -C "argocd-key" -f ~/.ssh/argocd_id
Accéder à Gitea et créer le dépÎt :
Port-forward pour Gitea (par exemple,
kubectl port-forward svc/gitea-http 3000:3000 -n gitea).AccĂ©der Ă
http://localhost:3000, configurer un compte administrateur, et créer un nouveau dépÎt vide, par exemple,infrastructure.Et pour le SSH de Gitea, faire un port-forward du service SSH :
kubectl port-forward svc/gitea-ssh 2222:22 -n gitea --address 0.0.0.0Ajouter la clé SSH publique (
~/.ssh/argocd_id.pub) aux Deploy Keys de ce dépÎt Gitea.
Ătape 3 : Installation et configuration dâArgoCD¶
1. Installation dâArgoCD¶
Nous installons le moteur GitOps et le connectons au dépÎt Gitea.
Installer ArgoCD dans le cluster :
kubectl create namespace argocd kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
AccĂ©der Ă lâinterface web et rĂ©cupĂ©rer le mot de passe administrateur :
kubectl port-forward svc/argocd-server 8080:443 -n argocd ARGOCD_PASS=$(kubectl get secret argocd-initial-admin-secret -n argocd -o jsonpath="{.data.password}" | base64 -d) echo "Admin password: $ARGOCD_PASS"
Se connecter Ă
https://localhost:8080avecadminet le mot de passe.
2. RĂ©cupĂ©rer la clĂ© dâhĂŽte depuis lâintĂ©rieur du cluster¶
Vous devez exĂ©cuter la commande ssh-keyscan Ă lâintĂ©rieur dâun pod temporaire dans votre cluster Kubernetes afin de rĂ©soudre correctement le FQDN et rĂ©cupĂ©rer la clĂ©.
Démarrer un shell temporaire dans votre cluster :
kubectl run -it --rm temp-keyscan --image=alpine:latest --restart=Never -- /bin/sh
Installer
ssh-keyscan(dans le shell du pod temporaire) :apk add --no-cache openssh-client
ExĂ©cuter la commande keyscan en utilisant le FQDN et le port dâĂ©coute rĂ©el de lâapplication (
2222) :# Inside the temp-keyscan pod: ssh-keyscan -p 2222 gitea-ssh.gitea.svc.cluster.local
Copiez la ou les lignes de sortie complĂštes, qui devraient ressembler Ă ceci :
[gitea-ssh.gitea.svc.cluster.local]:2222 ssh-rsa AAAAB3NzaC1yc2EAAAADAQ...
Quitter le pod en tapant
exit.
3. Mettre Ă jour la ConfigMap des Known Hosts dâArgoCD¶
Utilisez la sortie que vous avez copiĂ©e pour mettre Ă jour la ConfigMap quâArgoCD utilise pour les known hosts.
Créer ou mettre à jour la ConfigMap (par exemple, dans
argocd-ssh-known-hosts-cm.yaml). Assurez-vous que ce fichier est appliqué à votre namespace ArgoCD (par exemple,argocd).apiVersion: v1 kind: ConfigMap metadata: name: argocd-ssh-known-hosts-cm namespace: argocd # Use your ArgoCD namespace data: ssh_known_hosts: | # Paste the complete key line(s) from Step 1 here [gitea-ssh.gitea.svc.cluster.local]:2222 ssh-rsa AAAAB3NzaC1yc2EAAAADAQ...
Appliquer la ConfigMap :
kubectl apply -f argocd-ssh-known-hosts-cm.yamlVérifier que la
argocd-cmprincipale (la ConfigMap de configuration principale dâArgoCD) pointe bien vers la nouvelle map de known hosts.kubectl edit cm argocd-cm -n argocd
Assurez-vous que la section
datainclut :data: # ... other settings ... ssh.knownHostsConfigMap: argocd-ssh-known-hosts-cm
RedĂ©marrer lâArgoCD Repo Server : Ceci est obligatoire pour que les changements prennent effet.
kubectl rollout restart deployment argocd-repo-server -n argocd
4. Enregistrer le dépÎt Gitea¶
Enregistrer le dépÎt Gitea dans ArgoCD (via CLI) :
argocd login localhost:8080 # Replace <GITEA_IP>, <YOUR_USER> and <YOUR_REPO> argocd repo add ssh://git@<GITEA_IP>:2222/<YOUR_USER>/<YOUR_REPO>.git \ --name gitea-gitops-repo \ --ssh-private-key-path "${HOME}/.ssh/argocd_id"
Exemple :
argocd repo add ssh://git@gitea-ssh.gitea.svc.cluster.local:2222/${USER}/infrastructure.git \ --name gitea-gitops-repo \ --ssh-private-key-path /home/${USER}/.ssh/id_ed25519
CrĂ©er lâapplication racine (Auto-Bootstrapping) :
# ArgoCD will monitor the 'clusters/my-cluster' folder in your Git repository argocd app create argocd-root \ --repo ssh://git@<GITEA_IP>:2222/<YOUR_USER>/<YOUR_REPO>.git \ --path clusters/my-cluster \ --dest-server https://kubernetes.default.svc \ --dest-namespace argocd \ --sync-policy automated \ --auto-prune
Ătape 4 : IntĂ©gration de Gitea dans GitOps¶
Nous faisons en sorte quâArgoCD gĂšre Gitea, remplaçant ainsi lâinstallation manuelle de lâĂ©tape 2.
CrĂ©er la structure de lâapplication :
mkdir -p gitops-repo/apps/gitea mkdir -p gitops-repo/clusters/my-cluster
CrĂ©er lâapplication Gitea (fichier de dĂ©finition) : CrĂ©er un fichier
gitea-app.yamlpour quâArgoCD dĂ©ploie Gitea via Helm.# gitops-repo/apps/gitea/gitea-app.yaml apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: gitea namespace: argocd spec: destination: namespace: gitea server: https://kubernetes.default.svc project: default source: repoURL: https://dl.gitea.io/charts/ targetRevision: 12.4.0 chart: gitea syncPolicy: automated: prune: true selfHeal: true syncOptions: - CreateNamespace=true
Mettre Ă jour la configuration de lâapplication racine : Modifier le fichier
gitops-repo/clusters/my-cluster/kustomization.yaml(ou le crĂ©er) pour que lâapplication racine gĂšre lâapplication Gitea.# gitops-repo/clusters/my-cluster/kustomization.yaml apiVersion: kustomize.config.k8s.io/v1beta1 kind: Kustomization resources: - ../../apps/gitea/gitea-app.yaml
Commit et push :
git add . git commit -m "Integrate Gitea into ArgoCD management" git push origin main
Ătape 5 : Validation¶
VĂ©rifier le statut de lâapplication dans lâinterface ArgoCD : Lâapplication
argocd-rootdevrait synchroniser les ressources du dĂ©pĂŽt.VĂ©rifier lâapplication Gitea : Lâapplication Gitea devrait apparaĂźtre automatiquement et passer aux statuts
HealthyetSynced, confirmant quâArgoCD gĂšre dĂ©sormais Gitea.
Ătape 6 : IntĂ©gration de MetalLB dans GitOps đ¶
Nous allons maintenant utiliser ArgoCD pour déployer et configurer MetalLB, la solution LoadBalancer pour les environnements bare-metal.
1. Préparer les manifests MetalLB¶
Ajoutez une nouvelle structure pour lâapplication MetalLB dans votre gitops-repo local.
cd gitops-repo
mkdir -p apps/metallb
a. CrĂ©er lâapplication ArgoCD pour MetalLB (metallb-app.yaml)¶
Ce manifest indique à ArgoCD de déployer MetalLB via son Helm Chart.
# gitops-repo/apps/metallb/metallb-app.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: metallb
namespace: argocd
spec:
project: default
destination:
namespace: metallb-system
server: https://kubernetes.default.svc
source:
repoURL: https://metallb.github.io/metallb
targetRevision: v0.13.12 # (Use a stable version)
chart: metallb
syncPolicy:
automated:
prune: true
selfHeal: true
syncOptions:
- CreateNamespace=true
- ApplyOutOfSyncOnly=true
b. Créer la configuration des adresses IP (metallb-config.yaml)¶
DĂ©finissez une plage dâadresses IP libres sur votre rĂ©seau local que MetalLB pourra attribuer aux services LoadBalancer. Remplacez lâexemple ci-dessous par votre plage rĂ©elle.
# gitops-repo/apps/metallb/metallb-config.yaml
apiVersion: metallb.io/v1beta1
kind: IPAddressPool
metadata:
name: first-pool
namespace: metallb-system
spec:
# REPLACE this range with a range of FREE IPs from your network
addresses:
- 192.168.1.240-192.168.1.250
---
apiVersion: metallb.io/v1beta1
kind: L2Advertisement
metadata:
name: example
namespace: metallb-system
spec:
ipAddressPools:
- first-pool
2. Mettre Ă jour lâapplication racine (Kustomization)¶
Modifiez gitops-repo/clusters/my-cluster/kustomization.yaml pour inclure les manifests MetalLB. Ajoutez-les avant Gitea.
# gitops-repo/clusters/my-cluster/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
# 1. MetalLB Application Deployment
- ../../apps/metallb/metallb-app.yaml
# 2. MetalLB CRD Configuration
- ../../apps/metallb/metallb-config.yaml
# 3. Gitea Application (already existing)
- ../../apps/gitea/gitea-app.yaml
3. Exposer Gitea via LoadBalancer¶
Mettez Ă jour la dĂ©finition de lâapplication Gitea pour utiliser le type de service LoadBalancer, que MetalLB prendra en charge.
Modifiez gitops-repo/apps/gitea/gitea-app.yaml :
# gitops-repo/apps/gitea/gitea-app.yaml (Modifications)
# ...
helm:
repository: https://dl.gitea.io/charts/
# Adding values to set the LoadBalancer service type
values: |
service:
type: LoadBalancer
http:
type: LoadBalancer
ssh:
type: LoadBalancer
# ...
4. Commit et push¶
git add .
git commit -m "Step 6: Integrate MetalLB into GitOps and configure Gitea LoadBalancers"
git push origin main
5. Vérification finale¶
VĂ©rifiez lâinterface ArgoCD pour vous assurer que lâapplication
metallbestSyncedetHealthy.Vérifiez le statut du service de Gitea (il devrait désormais avoir une IP externe issue de votre plage MetalLB) :
kubectl get svc gitea-http -n gitea # The EXTERNAL-IP should now show an IP from your MetalLB range (e.g., 192.168.1.240)
đ Ătape 7 : IntĂ©gration de HashiCorp Vault dans GitOps¶
Nous allons dĂ©ployer HashiCorp Vault en utilisant son Helm Chart officiel et le Vault Agent Injector, essentiel pour injecter de maniĂšre sĂ©curisĂ©e des secrets dans les Pods (comme les futurs Gitea Runners ou lâapplication Harbor). Cette Ă©tape sâappuie sur Argo CD pour gĂ©rer le dĂ©ploiement via GitOps.
1. Préparation du dépÎt GitOps (ajout du chart Vault)¶
Naviguez vers votre gitops-repo local et crĂ©ez la structure de dossiers pour lâapplication Argo CD de Vault.
cd gitops-repo
mkdir -p apps/vault
2. CrĂ©er lâapplication Argo CD pour Vault (vault-app.yaml)¶
Ce manifest indique à Argo CD de déployer Vault via Helm. Pour un environnement de lab, nous utilisons une configuration minimale, non hautement disponible, avec un stockage fichier intégré pour plus de simplicité.
â ïž REMARQUE IMPORTANTE : Cette configuration est destinĂ©e Ă un environnement de lab/dĂ©veloppement et nâest PAS sĂ©curisĂ©e ni hautement disponible pour une utilisation en production. Pour la production, vous devez configurer un backend de stockage rĂ©silient (par exemple, Consul, PostgreSQL, ou un stockage Cloud).
# gitops-repo/apps/vault/vault-app.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: vault
namespace: argocd
spec:
project: default
destination:
namespace: vault
server: https://kubernetes.default.svc
source:
repoURL: https://helm.releases.hashicorp.com
targetRevision: v0.28.0 # Use a recent stable version
chart: vault
helm:
# Configurations for the k3s/lab environment
values: |
# Vault Server Configuration
server:
# Use File storage for simple persistence (requires a functional StorageClass, which k3s has by default)
standalone:
enabled: true
config: |
listener "tcp" {
tls_disable = 1
address = "[::]:8200"
cluster_address = "[::]:8201"
}
storage "file" {
path = "/vault/data"
}
disable_mlock = true
ui = true # Enable the user interface
# Configuration for the Vault Agent Injector
injector:
enabled: true
resources:
requests:
memory: 256Mi
cpu: 100m
# Resource requests for the server to run on k3s
server:
resources:
requests:
memory: 512Mi
cpu: 250m
syncPolicy:
automated:
prune: true
selfHeal: true
syncOptions:
- CreateNamespace=true
3. Mettre Ă jour lâapplication racine (Kustomization)¶
Modifiez gitops-repo/clusters/my-cluster/kustomization.yaml pour inclure lâapplication Vault. Nous la plaçons avant Gitea et Harbor, car ils pourraient en dĂ©pendre pour les secrets.
# gitops-repo/clusters/my-cluster/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
# 1. MetalLB Application Deployment
- metallb-app.yaml
# 2. MetalLB CRD Configuration
- metallb-config.yaml
# 3. Vault Application Deployment (NEW)
- vault-app.yaml
# 4. Gitea Application (existing)
- gitea-app.yaml
# 5. Harbor Application Deployment (Now Step 8)
- harbor-app.yaml
4. Commit et push¶
git add .
git commit -m "Step 7: Deploy HashiCorp Vault via GitOps"
git push origin main
đ 5. ProcĂ©dure post-installation de Vault (manuelle)¶
Une fois que lâapplication vault est Healthy et Synced dans Argo CD, Vault doit ĂȘtre initialisĂ© et dĂ©scellĂ©. Ce processus est manuel et ne peut pas ĂȘtre gĂ©rĂ© par Argo CD sans opĂ©rateurs spĂ©cialisĂ©s.
Initialiser Vault : ExĂ©cutez lâinitialisation depuis le Pod du serveur Vault (cela crĂ©e les clĂ©s) :
# Run initialization (only the first time) kubectl exec -ti -n vault vault-0 -- vault operator init \ -key-shares=1 -key-threshold=1 \ -format=json > vault-keys.json # KEEP this 'vault-keys.json' file in an EXTREMELY SECURE place! # It contains the Unseal Key and the Root Token.
DĂ©sceller Vault : Vault dĂ©marre dans un Ă©tat scellĂ©. Vous devez le desceller manuellement Ă lâaide de la clĂ© obtenue Ă lâĂ©tape prĂ©cĂ©dente.
UNSEAL_KEY=$(cat vault-keys.json | jq -r ".unseal_keys_b64[0]") # Run the unseal command kubectl exec -ti -n vault vault-0 -- vault operator unseal $UNSEAL_KEY
Connexion et configuration : Une fois descellĂ©, Vault est prĂȘt pour la configuration.
Port-forwarding pour lâinterface :
kubectl port-forward svc/vault 8200:8200 -n vault
AccĂ©dez Ă
http://localhost:8200, connectez-vous avec le Root Token (issu devault-keys.json).Configurer la mĂ©thode dâauthentification Kubernetes : Ceci est requis pour que le Vault Agent Injector puisse authentifier les Pods de votre cluster.
đ ïž Ătape 8 : IntĂ©gration de Harbor dans GitOps đąÂ¶
Cette Ă©tape Ă©tend votre procĂ©dure GitOps pour inclure lâinstallation de Harbor, fournissant le Container Registry nĂ©cessaire Ă votre workflow CI/CD.
Prérequis¶
Stockage persistant : Harbor nécessite des Persistent Volume Claims (PVCs) pour sa base de données, son cache Redis et le stockage des images. Assurez-vous que votre
StorageClassKubernetes par dĂ©faut (ou celle que vous avez choisie) fonctionne correctement dans k3s.IP externe : MetalLB (installĂ© Ă lâĂ©tape 6) doit ĂȘtre opĂ©rationnel pour attribuer une IP externe au service Harbor Core.
1. Préparer le dépÎt GitOps (ajout du chart Harbor)¶
Naviguez vers votre gitops-repo et crĂ©ez une structure de dossiers pour lâapplication ArgoCD de Harbor.
cd gitops-repo
mkdir -p apps/harbor
2. CrĂ©er lâapplication ArgoCD pour Harbor (harbor-app.yaml)¶
Ce manifest indique Ă ArgoCD de dĂ©ployer Harbor en utilisant son Helm Chart officiel. Il est crucial de configurer ici le type dâIP exposĂ©e et le mot de passe administrateur.
# gitops-repo/apps/harbor/harbor-app.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: harbor
namespace: argocd
spec:
project: default
destination:
namespace: harbor # Harbor will be installed in its own namespace
server: https://kubernetes.default.svc
source:
repoURL: https://helm.goharbor.io # Official Harbor Helm Repository
targetRevision: 1.18.0 # Use a recent stable version (cf. https://github.com/goharbor/harbor-helm/releases)
chart: harbor
helm:
# Crucial configurations for a k3s/MetalLB environment
values: |
# 1. Access Configuration (Exposition)
expose:
type: loadBalancer # Use MetalLB to assign an IP
tls:
enabled: false # Simplification for lab environment (NOT RECOMMENDED FOR PROD!)
# 2. Admin Configuration
# !!! CHANGE THIS PASSWORD !!!
harborAdminPassword: YourSecureHarborPassword123
# 3. Persistence (Storage)
# Ensures Harbor uses the default k3s StorageClass for persistent volumes
persistence:
enabled: true
imageChartStorage:
type: filesystem
filesystem:
rootDirectory: /data
# 4. Create Namespace
# Ensure the Harbor namespace is created
syncPolicy:
automated:
prune: true
selfHeal: true
syncOptions:
- CreateNamespace=true
3. Mettre Ă jour lâapplication racine (Kustomization)¶
Modifiez le fichier gitops-repo/clusters/my-cluster/kustomization.yaml pour inclure la dĂ©finition de lâapplication Harbor.
# gitops-repo/clusters/my-cluster/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
# 1. MetalLB Application Deployment
- ../../apps/metallb/metallb-app.yaml
# 2. MetalLB CRD Configuration
- ../../apps/metallb/metallb-config.yaml
# 3. Harbor Application Deployment (NEW)
- ../../apps/harbor/harbor-app.yaml
# 4. Gitea Application (already existing)
- ../../apps/gitea/gitea-app.yaml
4. Commit et push¶
git add .
git commit -m "Step 7: Integrate Harbor Container Registry into GitOps"
git push origin main
5. Vérification et accÚs¶
Statut ArgoCD : Surveillez lâinterface ArgoCD. Lâapplication
harborapparaßtra et finira par passer aux statutsSyncedetHealthy(cela peut prendre plusieurs minutes en raison du nombre de composants).IP du service : Vérifiez que le service principal Harbor Core a bien reçu une IP externe de MetalLB.
kubectl get svc harbor-harbor-core -n harbor # The EXTERNAL-IP column should display an IP from your MetalLB range.
AccĂšs : Vous pouvez dĂ©sormais accĂ©der Ă lâinterface web Harbor Ă lâadresse
http://<EXTERNAL-IP>en utilisant les identifiants : Nom dâutilisateur :admin, Mot de passe :YourSecureHarborPassword123.
Votre cluster dispose dĂ©sormais dâun registre de conteneurs robuste, gĂ©rĂ© par GitOps, prĂȘt pour votre pipeline CI.