GitOps z Argo CD na Kubernetes – architektura, wdrożenie i dobre praktyki

Konteneryzacja i Kubernetes rozwiązały problem uruchamiania aplikacji w sposób powtarzalny i w dużej skali, ale stworzyły nowy: jak w kontrolowany sposób zarządzać dziesiątkami manifestów, w kilku środowiskach, w wielu zespołach naraz? Ręczne kubectl apply, pipeline z dostępami do środowiska produkcyjnego i konfiguracja, której nikt nie potrafi odtworzyć — to codzienność wielu zespołów. Odpowiedzią na ten chaos jest GitOps, a jednym z przodujących narzędzi, które go realizują — Argo CD.

W tym artykule wyjaśnię, czym jest GitOps, jak różni się od klasycznego CI/CD w modelu push, jak zbudowana jest architektura Argo CD i jak wdrożyć je w praktyce — od pierwszej aplikacji, przez dwa główne wzorce App of Apps i ApplicationSet, aż po sekrety, RBAC i najczęstsze pułapki.

Czym jest GitOps?

GitOps to model operacyjny, w którym repozytorium Git jest jedynym źródłem prawdy (ang. single source of truth) o pożądanym stanie systemu. Nie zarządzasz klastrem, wydając mu polecenia — zarządzasz nim, opisując, jak ma wyglądać, i pozwalając, by dedykowany agent doprowadził rzeczywistość do tego stanu.

Inicjatywa OpenGitOps (część CNCF) definiuje cztery zasady GitOps:

1. Deklaratywność — cały system jest opisany deklaratywnie. Mówisz „chcę 3 repliki tej usługi", a nie „uruchom trzy kontenery".
2. Wersjonowanie i niezmienność — pożądany stan jest przechowywany w sposób zapewniający niezmienność, wersjonowanie i zachowanie kompletnej historii wersji.
3. Automatyczne pobieranie (ang. pulled automatically) — agenci automatycznie pobierają pożądany stan z repozytorium.
4. Ciągłe uzgadnianie (ang. continuously reconciled) — agenci nieustannie obserwują rzeczywisty stan i korygują go do stanu pożądanego.

Konsekwencje są bardzo praktyczne: Git staje się dziennikiem audytowym (kto, co i kiedy zmienił), rollback to zwykły revert commita, a środowisko można odtworzyć od zera, mając jedynie dostęp do repozytorium i pusty klaster.

GitOps vs DevOps i Infrastructure as Code

GitOps nie jest konkurencją dla DevOps — to konkretny sposób realizacji jego idei. Często pada też pytanie o relację do IaC (Infrastructure as Code). Różnica jest subtelna, ale istotna: IaC (np. Terraform) zwykle opisuje stan, który aplikujesz świadomie, ręcznie lub z pipeline’u. GitOps dokłada do tego ciągłą, automatyczne uzgadnianie stanu — agent nie czeka, aż ktoś uruchomi apply, tylko sam pilnuje, by stan klastra zawsze odpowiadał repozytorium.

GitOps vs klasyczny CI/CD – model pull kontra push

To najważniejsza różnica, którą trzeba zrozumieć.

W klasycznym CI/CD (model push) pipeline (np. Jenkins) po zbudowaniu obrazu wykonuje kubectl apply lub helm upgrade bezpośrednio na klastrze. Oznacza to, że:

• pipeline musi mieć dostęp do środowiska z możliwością dokonywania zmian na klastrze— te dane wychodzą poza granice klastra i są przechowywane w systemie CI,
• po wdrożeniu nikt nie pilnuje, czy stan jest zgodny z tym co było ustalone — jeśli ktoś zmieni coś ręcznie przez kubectl edit, ta zmiana przetrwa,
• odtworzenie stanu wymaga wiedzy, który pipeline i z jakiego commita był ostatnio uruchomiony.
• trzeba otworzyć dostęp do API Kubernetesa ze środowiska CI/CD co jest dodatkowym ryzykiem.

W GitOps modelu pull to agent działający wewnątrz klastra sam pobiera pożądany stan z Git i go wdraża:

• poświadczenia do klastra nigdy nie opuszczają jego granic — to klaster sięga na zewnątrz po manifesty, a nie odwrotnie,
• drift konfiguracji jest wykrywany i korygowany automatycznie,
• źródłem prawdy jest jedno repozytorium, niezależne od narzędzia CI.
• nie ma potrzeby otwierania firewalla do API klastra ze środowiska CI/CD.

Ważne: GitOps nie zastępuje CI. Etap budowania obrazu, testów i skanowania bezpieczeństwa dalej realizujesz w swoim narzędziu CI. GitOps przejmuje wyłącznie etap CD — dostarczenie zmiany do klastra. Typowy przepływ wygląda tak: CI buduje i taguje obraz → CI aktualizuje wersję obrazu w repozytorium manifestów → Argo CD wykrywa zmianę w Git i synchronizuje klaster.

Czym jest Argo CD i jak działa

Argo CD to deklaratywne narzędzie GitOps dla Kubernetes, projekt CNCF na poziomie Graduated. Działa jako kontroler wewnątrz klastra i nieustannie porównuje stan opisany w Git ze stanem rzeczywistym.

Na Argo CD składa się kilka komponentów:

• API Server — udostępnia API oraz webowe UI i CLI; obsługuje uwierzytelnianie, RBAC i zarządzanie aplikacjami.
• Repository Server — pobiera repozytoria Git i renderuje z nich finalne manifesty (Helm, Kustomize, lub czysty YAML).
• Application Controller — serce systemu; uruchamia reconciliation loop, czyli pętlę, która cyklicznie porównuje stan pożądany ze stanem klastra i wykonuje synchronizację.

Reconciliation loop, stany Sync i Health

Każda aplikacja w Argo CD ma dwa kluczowe statusy:

• Sync status — czy stan klastra odpowiada Git: Synced lub OutOfSync.
• Health status — czy zasoby faktycznie działają: Healthy, Progressing, Degraded, Missing.

Gdy ktoś ręcznie zmieni zasób w klastrze, Argo CD wykryje różnicę i oznaczy aplikację jako OutOfSync. Przy włączonej opcji self-heal automatycznie przywróci stan z Git — to skuteczny mechanizm eliminowania różnic konfiguracji i „ręcznych poprawek".

Argo CD vs Flux

Drugim wiodącym narzędziem GitOps jest Flux. Oba są projektami CNCF Graduated i realizują te same zasady. W skrócie:

• Argo CD — rozbudowane UI z wizualizacją drzewa zasobów, model wielodostępny (Projects, RBAC, SSO), wygodny dla wielu zespołów na współdzielonej platformie.
• Flux — lżejszy, w całości sterowany przez API Kubernetes (zestaw kontrolerów), bez własnego UI; często wybierany do podejścia czysto deklaratywnego i integracji z Terraform.

Dla zespołów, które cenią wgląd w stan i kontrolę dostępu, zwykle rekomendujemy Argo CD. Dla minimalistycznych, w pełni zautomatyzowanych platform (np. Cluster as a Service) — Flux. Oba są dobrymi wyborami.

Instalacja Argo CD

Najprostsza instalacja sprowadza się do utworzenia namespace’u i zaaplikowania oficjalnego manifestu:

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

Na środowiska produkcyjne lepszy jest jednak oficjalny Helm chart, który pozwala zarządzać konfiguracją Argo CD w sposób deklaratywny (HA, SSO, zasoby, ingress):

helm repo add argo https://argoproj.github.io/argo-helm
helm install argocd argo/argo-cd -n argocd --create-namespace

Po instalacji warto zainstalować argocd CLI i zalogować się do API serwera. Początkowe hasło administratora znajdziesz w sekrecie:

kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" | base64 -d

Pierwszą rzeczą, którą należy zrobić po zalogowaniu, jest zmiana tego hasła i skonfigurowanie logowania przez SSO — o bezpieczeństwie piszę niżej.

Pierwsza aplikacja – obiekt Application

W Argo CD jednostką wdrożenia jest własny zasób (CRD) o nazwie Application. Opisuje on: skąd brać manifesty (source), dokąd je wdrażać (destination) i jak się synchronizować (syncPolicy).

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: testowe-api
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/twoje-repo/manifesty.git
    targetRevision: main
    path: apps/testowe-api
  destination:
    server: https://kubernetes.default.svc
    namespace: testowe
  syncPolicy:
    automated:
      prune: true        # usuwa zasoby skasowane z Git
      selfHeal: true     # cofa ręczne zmiany w klastrze
    syncOptions:
      - CreateNamespace=true

Trzy opcje, które definiują zachowanie GitOps:

• automated — Argo CD synchronizuje automatycznie po wykryciu zmiany w Git (bez tego synchronizacja jest ręczna).
• prune — gdy usuniesz zasób z repozytorium, zostanie też usunięty z klastra. Bez tego zasoby nie są kasowane automatycznie. Czasami warto ustawić na “false”.
• selfHeal — przywraca stan z Git, gdy ktoś zmieni zasób ręcznie.

source może wskazywać na czysty YAML, katalog Kustomize albo Helm chart.

Skalowanie GitOps – App of Apps i ApplicationSet

Jedna aplikacja to prosty przypadek. Problem zaczyna się, gdy masz kilkadziesiąt usług i trzy środowiska (dev/staging/prod). Ręczne tworzenie setek obiektów Application jest niewykonalne. Argo CD oferuje dwa wzorce.

App of Apps

Wzorzec App of Apps polega na utworzeniu jednej „nadrzędnej" aplikacji, która jako swoje manifesty wskazuje katalog z definicjami kolejnych obiektów Application. Bootstrap całej platformy sprowadza się wtedy do zaaplikowania jednego manifestu — reszta wdraża się kaskadowo. To prosty sposób na zarządzanie zestawem aplikacji jako całością.

ApplicationSet

ApplicationSet to bardziej zaawansowany mechanizm — generuje obiekty Application na podstawie generatorów. Zamiast ręcznie pisać identyczne definicje dla każdego środowiska, opisujesz szablon raz, a generator wypełnia go danymi. Najczęściej używane generatory:

• Git — generuje aplikację dla każdego katalogu lub pliku w repozytorium (np. nowy mikroserwis = nowy katalog),
• List — z jawnej listy parametrów (np. lista klastrów lub środowisk),
• Cluster — automatycznie dla każdego zarejestrowanego w Argo CD klastra.

Dzięki temu dodanie nowego środowiska albo wdrożenie tej samej aplikacji na 20 klastrów to zmiana kilku linii, a nie kopiowanie manifestów.

Kolejność wdrożeń – Sync Waves i Hooks

Nie wszystko można wdrożyć jednocześnie. Migracje bazy danych muszą wykonać się przed startem aplikacji, a CRD przed zasobami, które z nich korzystają. Argo CD steruje kolejnością przez sync waves — adnotację określającą „falę", w której zasób ma zostać zaaplikowany:

metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "1"

Zasoby z niższym numerem fali wdrażają się jako pierwsze; Argo CD czeka, aż będą Healthy, zanim przejdzie do kolejnej. Dodatkowo resource hooks (PreSync, Sync, PostSync) pozwalają uruchamiać zadania w określonym momencie synchronizacji — np. Job z migracją bazy w fazie PreSync.

Zarządzanie sekretami

To najczęstsze pytanie i najczęstszy błąd początkujących. Argo CD samodzielnie nie szyfruje sekretów — a trzymanie haseł w jawnym Secret w Git jest dużym ryzykiem. Stosuje się jeden z trzech wzorców:

• External Secrets Operator — sekret żyje w zewnętrznym magazynie (AWS Secrets Manager, SSM Parameter Store, HashiCorp Vault), a operator wstrzykuje go do klastra jako natywny Secret. W Git trzymasz tylko referencję.
• Argo CD Vault Plugin — podmienia placeholdery w manifestach na wartości pobrane z HashiCorp Vault podczas renderowania.

W projektach opartych o AWS najczęściej rekomendujemy External Secrets Operator z AWS Secrets Manager — sekret w czystej postaci nigdy nie trafia do repozytorium, a rotacja odbywa się po stronie chmury.

Bezpieczeństwo Argo CD – RBAC i SSO

Argo CD w zależności od konfiguracji może mieć dostęp nawet do całego klastra, więc samo w sobie jest celem o wysokiej wartości. Kluczowe praktyki:

• Wyłącz lokalne konto admin po skonfigurowaniu SSO (OIDC, np. Google, Entra ID, Keycloak) — uwierzytelnianie powinno przechodzić przez Twojego dostawcę tożsamości.
• Skonfiguruj RBAC — mapuj grupy z dostawcy tożsamości na role Argo CD. Zespół A nie powinien synchronizować aplikacji zespołu B.
• Używaj Projects — AppProject ogranicza, z jakich repozytoriów, do jakich klastrów i namespace’ów oraz jakie typy zasobów dana grupa aplikacji może wdrażać. To podstawa modelu wielodostępnego.
• Ogranicz ekspozycję UI — API serwer nie powinien być publicznie dostępny bez potrzeby.

Błędna konfiguracja narzędzia GitOps to realna ścieżka ataku na cały klaster.

Najczęstsze błędy i pułapki

W projektach najczęściej spotykamy:

• Sekrety w Git — Base64 mylony z szyfrowaniem.
• prune wyłączony „dla bezpieczeństwa" — efekt odwrotny: klaster zapełnia się zasobami, których nikt już nie pilnuje.
• Ręczne kubectl apply obok Argo CD. Trzeba zdecydować: albo GitOps, albo ręcznie.
• Brak ustawionych requestów i limitów zasobów dla samego Argo CD na większych instalacjach — repo server i kontroler bywają zasobożerne przy setkach aplikacji.
• Jedno repozytorium na wszystko — warto rozdzielić repozytorium z kodem aplikacji od repozytorium z manifestami (config repo).

Kiedy wdrożyć GitOps?

GitOps zwraca się najszybciej, gdy:

• zarządzasz wieloma środowiskami lub klastrami i synchronizacja konfiguracji między nimi jest bolesna,
• kilka zespołów współdzieli platformę i potrzebujesz kontroli dostępu oraz audytu zmian,
• zależy Ci na szybkim, przewidywalnym rollbacku i pełnej historii zmian,
• chcesz ograniczyć dostępy do środowisk Kubernetes w pipeline’ach CI ze względów bezpieczeństwa.

Dla pojedynczej, małej aplikacji na jednym klastrze narzut wdrożenia GitOps może być nieproporcjonalny do korzyści — wtedy prosty pipeline push bywa wystarczający. Jak zwykle w Kubernetes: to zależy od skali i kontekstu.

Podsumowanie

GitOps to nie kolejne narzędzie, lecz zmiana modelu operacyjnego — z imperatywnego „wydawania poleceń" klastrowi na deklaratywne opisywanie pożądanego stanu i pozwalanie, by klaster sam się do niego doprowadzał. Argo CD realizuje ten model w sposób dojrzały: z wizualizacją stanu, modelem wielodostępnym, RBAC i bogatym ekosystemem (ApplicationSet, Image Updater, integracja z sekretami).

Poprawne wdrożenie wymaga jednak przemyślanej struktury repozytoriów, świadomego zarządzania sekretami i właściwej konfiguracji bezpieczeństwa — błędy na tym etapie potrafią zamienić narzędzie zwiększające kontrolę w nową powierzchnię ataku.

Jeśli chcesz wdrożyć GitOps i Argo CD w swojej organizacji, uporządkować zarządzanie klastrami albo zweryfikować bezpieczeństwo istniejącego środowiska — mój zespół oferuje audyt i wsparcie Kubernetes oraz konsultacje oparte na realnych metrykach i dobrych praktykach.