Git jako narzędzie rozproszonego systemu kontroli wersji jest obecnie standardem ułatwiającym zespołom programistycznym rozwój oprogramowania, a jego znajomość jest w zasadzie niezbędna aby być efektywnym developerem. Skuteczne zarządzanie kodem przy użyciu tego narzędzia przyczynia się do zwiększenia jakości, wydajności i stabilności projektów programistycznych z wielu powodów:

• śledzenie zmian - możemy łatwo przejrzeć historię projektu, zrozumieć kto, kiedy i dlaczego wprowadził określoną zmianę
• współpraca - wielu programistów może jednocześnie pracować nad projektem niezależnie
• zarządzanie wersjami - utrzymanie wielu różnych wersji oprogramowania
• łatwe wycofywanie zmian - łatwe cofanie się do poprzednich stanów projektu
• bezpieczeństwo przed utratą danych

W tym artykule przybliżę trzy najpopularniejsze strategie zarządzania kodem:
GIT Flow, GitHub Flow i Trunk Based Development.

GIT Flow

Podejście zakłada, że pracujemy na wielu branchach:

• main (lub master) - powinien być zgodny z kodem, który jest na produkcji
• develop - kopia brancha main z wszystkimi innymi zmianami, które zostały dodane od ostatniego release
• feature - developerzy odbijają się od brancha develop tworząc brancha feature np. feature/new-auth-method lub bug/fix-some-bug w zależności od rodzaju zgłoszenia
• release - jak developerzy wykonali swoją pracę nowy branch jest tworzony od brancha develop aby stworzyć release np. release/1.2.3
• hotfix - jeżeli jest pilna potrzeba poprawienia buga na produkcji tworzymy brancha hotfix odbijając się od main np. hotfix/INC3458-xyz

Flow programisty:

1. Dla nowych projektów tworzony jest branch main (lub master)
2. Następnie branch develop jest odbijany od brancha main. Nie dokonujemy żadnych zmian bezpośrednio na branchu main czy też develop.
3. Programiści odbijają się od brancha develop tworząc feature branche i pracują nad swoimi zmianami. Czasem zajdzie potrzeba merga develop -> feature jeśli implementacja feature długo trwa i trzeba zintegrować się z innymi zmianami (rekomendowanym podejściem jest użycie rebase).
4. Gdy feature jest gotowy tworzymy pull requesta do developa. Inni członkowie zespołu robią code review zmian. Jeżeli są konflikty najpierw trzeba je rozwiązać zanim będziemy mogli zmergować zmiany do developa. Warto aby w ramach danego PR uruchamiał się jakiś proces automatyczny, który zweryfikuje czy nic nie popsuliśmy czy testy przechodzą itd.
5. Jak już wszystkie zmiany pod danego release zostaną wykonane release branch jest tworzony odbijając się od brancha develop. QA Team wykonuje testy tego release przed wdrożeniem na produkcje. W międzyczasie developerzy mogą kontynuować prace na developie jeżeli chodzi o funkcjonalności pod kolejny release.
6. Gdy jesteśmy pewni, że release został w pełni przetestowany tagujemy wydanie odpowiednią wersją i mergujemy release do main (master).
7. Po wydaniu wersji mergujemy main do develop aby upewnić się, że wszystkie zmiany wykonywane podczas testów są uwzględnione i spójne z branchem develop.
8. Jeżeli wystąpi pilny problem na produkcji tworzymy brancha hotfix naprawiamy wystawiamy PR następnie po code review mergujemy do main i develop i tagujemy wersje.

Dlaczego warto odbijać się od mastera?

Odbicie feature brancha od mastera pozwala nam na wdrożenie danego feature w oderwaniu od release'a. W momencie jak biznes się decyduje, że dany feature ma nie wejść unikamy wielu revert'ow. W takim przypadku tworzymy nowego release brancha z mastera i mergujemy wszystkie tylko interesujące nas feature branche. W takim podejściu ważne jest aby nie usuwać feature branchy od razu po mergu do release'a tylko w momencie wdrożenia zmian na produkcję. Wszystkie poprawki dotyczące funkcjonalności powinny trafiać na odpowiedni feature branch (nie powinno być commit'ow bezpośrednio do developa, release czy mastera).

Zalety:

• pozwala pracować na wielu release'ach jednocześnie
• łatwo śledzić poszczególne wydania gdyż jest wiele branchy i każdy ma swoje przeznaczenie
• pozwala na łatwe przełączanie się pomiędzy tym nad czym pracujemy a innymi wydaniami ponieważ "żyją" one w różnych branchach
• sprawdza się zwykle gdy rzadko wdrażamy zmiany na produkcje np. raz na kilka tygodni lub rzadziej
• sprawdza się gdy musimy wspierać wiele różnych wersji i robić fixy do tych wersji oraz zachować kompatybilność wsteczną

Wady:

• słabo się sprawdza w kontekście CI/CD
• wiele branchy, które trzeba utrzymywać i pamiętać aby zachowywały spójność mergować itd, mija sporo czasu zanim zmiany zostaną zmergowane do mastera i jeszcze więcej czasu zanim inni developerzy lub zespoły zintegrują swoje zmiany z zmianami innych nie wspominając o konfliktach po drodze
• z uwagi na to, że wydanie jest dość złożone dług technologiczny rośnie

GitHub Flow

Strategia używana przez Githuba. Podejście zakłada, że mamy tylko dwa branche:

• main (lub master) - podobnie jak w git flow, branch posiada wszystkie stabilne zmiany projektu
• feature - programiści odbijają się bezpośrednio od main aby pracować nad nowymi funkcjonalnościami

Flow programisty:

1. W przypadku nowego projektu tworzymy pusty branch master.
2. Aby wprowadzić zmianę odbijamy się od brancha master i tworzymy feature branch.
3. Gdy branch feature jest gotowy, przetestowany, a code review zrobione mergujemy do mastera.
4. Gdy branch feature został zmergowany do mastera powinien być od razu zrobiony release zmian na produkcje.

W przeciwieństwie do Git Flow nie ma tu koncepcji brancha release. Każdy feature tworzy swój własny "release" w związku z tym wszystko zmergowane do mastera powinno tworzyć stan stabilny i deployowalny. Dzięki temu zespoły mogą wdrażać zmiany na produkcje kilka razy dziennie zamiast na koniec sprintu. W celu tak szybkiego wdrażania zmian i robienia wydań należy mieć solidne testy automatyczne.

Zalety:

• pozwala na wdrożenie CI/CD
• zachęca zespoły do wdrażania często dzięki czemu szybko mogą uzyskać feedback z pracy, którą wykonali
• mniejsza szansa na wytworzenie długu technicznego

Wady:

• wymaga solidnych testów automatycznych i automatycznego procesu release'owego
• trzeba być ostrożnym ponieważ każdy błąd zmergowany do mastera pójdzie bezpośrednio na produkcje

Trunk Based Development

Trunk-Based development to praktyka, w której developerzy mergują często małe zmiany do jednego core'owego brancha trunk lub main (single source-of-truth) zamiast utrzymywać długotrwałe gałęzie. Pomaga to sprawnie wdrażać zmiany i osiągać CI/CD.

W przeciwieństwie do innych strategii, które używają oddzielnych branchy do release'owania zmian w TBD trunk jest tzw. jednym źródłem prawdy wszystkich release'ow na produkcje.

W TBD teoretycznie każdy commit nadaje się do wdrożenia na produkcję. Ta idea pozwala na bardziej elastyczne i częstsze wdrożenia zmian na produkcję i skrócenie time-to-market.

Stosując TBD zmiany są wdrażane na bieżąco, co minimalizuje czas w jakim kod różnych programistów jest oddzielony. Wdrożenia są częstsze,  co ułatwia śledzenie błędów i umożliwia dostarczanie funkcji szybciej.

W celu zastosowania TBD, zespoły programistyczne powinny często łączyć swoje zmiany z gałęzią główną. Wprowadza to zasady takie jak Feature Flags, które pozwalają na tymczasowe wyłączanie kodu, co umożliwia łączenie różnych funkcji niezależnie od ich gotowości do wdrożenia. Niezbędne jest również stosowanie praktyk takich jak automatyczne testy aby zapewnić, że łączone zmiany nie wprowadzają nowych błędów.

Podstawowe założenia TBD:

• ciągła integracja z głównym branchem trunk
• używanie short-term feature branchy
• bezpieczne techniki deploymentowe, częste release'owanie zmian na produkcję z trunk'a
• utrzymanie bardzo wysokiego pokrycia kodu aby zminimalizować ryzyko wdrożenia bugow na produkcję
• użycie feature flags jest niezbędne (commitujemy zmiany dot. feature, które jeszcze jest inprogress)
• silne nastawienie na automatyzacje, automatyczny deployment testy itd.
• częste merge do trunk'a zmuszają do wytwarzania małych zmian, kod powinien być zawsze gotowy do wdrożenia na produkcję
• częste wdrożenia

W przeciwieństwie do innych strategii gdzie branche mogą istnieć tygodnie lub nawet miesiące w TBD branche są tymczasowe co oznacza, że programiści tworzą branche typu feature lub fix i mergują je zwykle do trunk'a w ciągu jednego dnia i usuwają tego brancha. Ta metoda minimalizuje ryzyko napotkania na konflikty a codebase jest bardziej uporządkowany i zorganizowany.

CI & Testy

Continuous Integration jest bardzo istotne w TBD. Z uwagi na to, że programiści bardzo często commitują do trunk'a (mastera) zachodzi potrzeba ciągłej integracji tj. budowania i testowania zmian automatycznie i ogólnie sprawdzania jakości kodu aby upewnić się, że zmiana nie psuje mastera czy też nie ma konfliktu z innymi zmianami. Proces CI powinien automatycznie sprawdzać zmiany dokonane na masterze utrzymując głównego brancha w dobrej kondycji, zawsze gotowego do wdrożenia na produkcję. Każdy commit należy interpretować jako potencjalnie kolejny release. Dzięki temu mamy szybsze cykle wdrożeniowe i niski time-to-market.

Jaką strategię wybrać?

Wybów odpowiedniej strategii branchowania jest istotny, ponieważ wpływa na sposób, w jaki zespoły współpracują nad projektem, zarządzają kodem, wdrażają zmiany i zależy od charakterystyki projektu, wymagań biznesowych i preferencji zespołu. Git Flow jest bardziej skomplikowany ale zapewnia kontrolę nad procesem, nadaje się do projektów wymagających jasno określonych wydań, szczegółowego planowania i testowania. GitHub Flow jest prosty i dynamiczny, efektywny w projektach wymagających ciągłego wdrażania i szybkiego dostarczania nowych funkcji. TBD sprawdza się w projektach wymagających szybkiego wdrażania, minimalizuje konflikty i utrzymuje prostotę, jednak należy pamiętać, że wymaga całej otoczki automatyzacji, która pozwoli bezpiecznie wdrażać zmiany na produkcję.

Podsumowanie

Mam nadzieję, że w klarowny i zrozumiały sposób wyjaśniłem Tobie czym charakteryzują się rożne strategie branchowania i zarządzania kodem. Jeżeli ten artykuł był dla Ciebie wartościowy podziel się nim z innymi. Tymczasem zostawiam Cię w klimacie progresywnego house mojego autorstwa, do usłyszenia!

Jeśli to czytasz, zapewne słyszałeś już termin Kubernetes. Zapewne czytałeś już gdzieś, że jest to narzędzie do orkiestracji kontenerów, że ma jakieś powiązania z Dockerem, że używa się tego w chmurach, że ma super mechanizm automatycznego skalowania i że jest rozwiązaniem na wszelkie zło panujące przy ciągle rosnącym środowisku produkcyjnym.

Jednocześnie jednak masz świadomość, że nie jest to łatwa technologia, ponieważ prawie wszędzie czytasz, że próg wejścia w tę technologię jest wysoki, a gdy próbujesz ruszyć coś z dokumentacją Kubernetesa, ciężko Ci się zmierzyć z ogromem różnych nowych terminów.

Na dodatek gdy próbujesz uruchomić środowisko u siebie na komputerze, to ciągle coś nie działa, a oficjalna dokumentacja wydaje Ci się niejasna i zbyt ogólnikowa.

Zgadłem? Jeśli nie to bardzo przepraszam. Ale właściwie dlaczego zakładam, że jesteś taką osobą? Bo w rozmowach o Kubernetesie z innymi, właśnie z takimi osobami najczęściej się spotykałem. W tym artykule chcę udowodnić, że Kubernetes nie jest tak trudny jak się wydaje i można o nim opowiedzieć nieco... prościej.

Żeby jednak nie powtarzać wiedzy i ze względu na to, że Kubernetesa nie warto ruszać jeśli nie słyszałeś nigdy wcześniej o Dockerze, przed dalszą lekturą zalecam się zapoznać z artykułem o tym jak działa sam Docker:

Docker w praktyce. Dobre praktyki i przydatne polecenia

Docker [https://www.docker.com/] jest przydatnym narzędziem służącym do wirtualizacji na poziomie systemu operacyjnego. Oprogramowanie to pozwala na uruchamianie procesów aplikacji w “lekkich” kontenerach odizolowanych od systemu operacyjnego hosta. W pewnym sensie kontenery przypominają maszyny wir…

lsdev.plŁukasz

Jeśli przeczytałeś już artykuł powyżej i wiesz już wszystko o Dockerze to w takim razie teraz...

Zapomnij o Dockerze

Pewnie powiesz: "Zaraz chwila... Ale jak to zapomnij? Pierw kazałeś przeczytać artykuł o Dockerze i teraz mam o nim zapomnieć?".

W sumie tak, no może nie do końca. Ogólnie rzecz biorąc, kilka lat temu Kubernetes korzystał z Dockera. Jednak od wersji 1.24 Kubernetes przestał to robić i oficjalnie już nie wspiera Dockera (Is Your Cluster Ready for v1.24? | Kubernetes).

Czemu Kubernetes przestał wspierać Dockera? Bo nie miało to większego sensu. Docker wbrew temu co można przeczytać na niektórych portalach, samemu nie uruchamia kontenerów. Do uruchomienia kontenerów używa innego narzędzia, które nazywa się Containerd (containerd – An industry-standard container runtime with an emphasis on simplicity, robustness and portability).

Można powiedzieć, że Docker jest nakładką na Containerd, która sprawia, że uruchamianie kontenerów jest szybkie i proste.

Dlatego przed wersją 1.24 Kubernetesa:

Kubernetes przekazywał polecenia do Dockera -> Docker przekazywał polecenia do Containerd -> Containerd operował na kontenerach.

Od wersji 1.24 Kubernetesa:

Kubernetes przekazuje polecenia do Containerd -> Containerd operuje na kontenerach.

Oczywiście jest to bardzo uproszczony obraz, ale myślę, że wystarczający do tego aby zrozumieć wcześniejsze zależności z Dockerem.

Ale po co mi właściwie Kubernetes?

Sam Docker został stworzony głównie z myślą o programistach. Aplikacja umieszczona w kontenerze zadziała na każdym komputerze i to jest jedna z mocnych stron tego rozwiązania. Aplikację umieszczoną w Dockerze możemy przekazać innej osobie bez obaw o to, czy dana osoba ma na komputerze zainstalowane odpowiednie zależności, bo wiemy, że wszystko co potrzebne już jest obecne w kontenerze. Mamy więc pewność, że aplikacja zadziała zawsze, na każdym systemie z zainstalowanym jedynie Dockerem.

Takie rozwiązanie może wydawać się bardzo kuszące jeżeli chodzi o środowiska produkcyjne. W końcu nie musimy się martwić, czy nasza aplikacja zadziała w tak często stresującym momencie, którym jest wdrażanie aplikacji na produkcję. I co ciekawe Docker często jest również właśnie w taki sposób wykorzystywany.

Jednak pomimo tego, że Docker wiele spraw ułatwia, w większym środowisku produkcyjnym może być problematyczny w utrzymaniu. Żeby jednak lepiej to wyjaśnić, posłużę się przykładem.

Krótka Historia pewnej aplikacji

Załóżmy, że masz napisaną aplikację, która została umieszczona w kontenerze Dockerowym. Coś bardzo prostego, jakaś aplikacja napisana w PHP. Postanawiasz, że kupisz serwer, postawisz na tym jakiegoś Linuxa, zainstalujesz Dockera i opublikujesz stronę w internecie.

Strona okazuje się sukcesem, klientów przybywa i Twój serwer powoli niedomaga. Decydujesz się na kupno kolejnego serwera, na którym też instalujesz Dockera. Na pierwszym serwerze instalujesz usługę load balancer typu HAproxy, aby rozłożyć ruch na obu serwerach.

Sukces aplikacji jednak jest tak duży, że z czasem i drugi serwer zaczyna Ci nie wystarczać, dlatego dokładasz kolejne serwery i kolejne... Na każdym instalujesz Dockera i swoją aplikację. Każdy serwer dodajesz do backendu w HAproxy.

Aż w końcu kiedy dodajesz już 20 serwer uświadamiasz sobie, że trzeba zaktualizować aplikację. Dlatego logujesz się na każdy serwer i uruchamiasz nową wersję aplikacji w Dockerze. Żeby klienci nie odczuli zmian, przed aktualizacją każdego z serwerów, po kolei zatrzymujesz na HAproxy ruch do obecnie aktualizowanego serwera.

Niestety, okazuje się, że nowa wersja aplikacji ma błąd i szybko musisz wrócić do poprzedniej wersji. Dlatego znowu logujesz się na każdy serwer i przywracasz poprzednią wersję.

Żeby temu zaradzić na następny raz automatyzujesz sobie wdrażanie aplikacji pisząc odpowiedni Playbook do Ansible.

Pewnego dnia z jakiegoś powodu pierwszy serwer, na którym jest HAproxy, ulega uszkodzeniu. Aplikacja przestaje działać. Po jakimś czasie udaje Ci się ożywić serwer, ale klienci są niepocieszeni.

Żeby się przed tym uchronić na następny raz, postanawiasz zrobić drugi serwer z HAproxy i tworzysz pływający pomiędzy load balancerami adres IP, aby utrzymać usługę ciągle aktywną nawet w przypadku awarii.

Po tym incydencie napotykasz kolejny problem, szał na Twoją aplikację minął, jest już mniej eksploatowana i serwery się nudzą. Żeby zminimalizować koszty, rezygnujesz z kilku serwerów. Znowu wdrażasz odpowiednie zmiany w konfiguracji tym razem już na dwóch serwerach z HAproxy.

Po odłączeniu serwerów okazuje się, że jednak źle obliczyłeś obecne zużycie i zrezygnowałeś ze zbyt dużej liczby serwerów, więc znowu dokupujesz kilka serwerów, znowu instalujesz na nich Dockera, wgrywasz aplikację i znowu dodajesz serwery do konfiguracji w HAproxy.

Po jakimś czasie masz pomysł na inną aplikację, którą postanawiasz wrzucić na kilka serwerów jednak szybko okazuje się, że serwery z zainstalowanymi dwoma aplikacjami jednocześnie niedomagają. Postanawiasz więc, że jedna część serwerów będzie obsługiwać jedną aplikację, a druga część drugą aplikację.

W głowie masz już jednak pomysł na trzecią, niewielką aplikację i żeby sobie ułatwić sprawę, zatrudniasz kolejnych administratorów, żeby wdrożenia robiło kilka osób.

Niestety przy wdrożeniu trzeciej aplikacji na istniejące już serwery z poprzednimi aplikacjami, zaczynają szwankować dwie pierwsze, ze względu na to, że nowy administrator popełnił przypadkiem jakiś błąd.

Żeby temu zaradzić, ograniczasz dostęp dla innych administratorów do części serwerów i nowe osoby wykonują wdrożenia tylko na specjalnie wydzielonych do tego celu serwerach.

Podsumujmy. Żeby środowisko oparte o Dockery bez orkiestracji działało bez problemów przy dużej ilości serwerów, zarządzanych przez kilku administratorów, musisz samemu, za pomocą różnych odpowiednich technologii zadbać o:

1. odporność na awarię
2. automatyzację wdrożeń aplikacji ze strategią zachowania 100% dostępności
3. równoważenie ruchu i ewentualną migrację kontenerów
4. monitoring każdego serwera pod względem zużycia zasobów
5. ograniczanie dostępu do serwerów

I oczywiście wszystkie powyższe problemy można rozwiązać na kilka sposobów jednak...

Czy można prościej?

Oczywiście, i właśnie po to jest Kubernetes. Klaster Kubernetes:

1. Ma wbudowane mechanizmy, które odpowiadają za odporność na awarie (sprzętową jak i również awarię aplikacji w kontenerze)
2. Ma API, dzięki czemu wdrożenie aplikacji jest wykonywane poprzez połączenie do jednego API, które łączy wszystkie serwery połączone w jeden klaster Kubernetesa
3. Ma wbudowane mechnizmy do równoważenia obciążenia i automatycznej migracji kontenerów
4. Ma wbudowany monitoring (w tym monitoring obciążenia) oraz mechanizmy logowania błędów
5. Każde wdrożenie może mieć swoje wydzielone miejsce (namespace), z ograniczonym dostępem oraz zasobami, bez konieczności ograniczania go do konkretnych maszyn

W porządku, ale jak to działa?

Najczęściej w tym momencie wielu zaczyna tłumaczyć Ci czym są terminy takie jak: pod, service, ingress, deployment, daemonset, replicaset, persistent volume, persistent volume claim, horizontal pod autoscaler i... inne.

Oczywiście warto znać te terminy, jednak uważam, że zaczynanie nauki od studiowania definicji każdego z powyższych elementów, może zniechęcić do dalszego zdobywania wiedzy. Tak naprawdę, aby zrozumieć jak działa Kubernetes, najlepiej go po prostu użyć do czegoś prostego w praktyce.

Problem w tym, że jeśli chcemy użyć Kubernetesa w praktyce, korzystając z narzędzia kubectl i tak potrzebujemy znać powyższe terminy.

Poza tym, tworzenie nowych wdrożeń w Kubernetesie, zwykle wiąże się z pisaniem tak zwanych manifestów, czyli zestawu poleceń, które Kubernetes ma dla nas wykonać co dla niektórych może wydawać się ścianą nie do przeskoczenia.

Dlatego, żeby było prościej, posłużymy się czytelnym i łatwym w obsłudze Rancherem.

Czym jest Rancher?

Krótko mówiąc jest to bardzo zaawansowany i popularny panel do zarządzania klastrami Kubernetesa.

Z uwagi na bardzo prosty i przejrzysty interfejs, Rancher jest bardzo łatwy w użyciu. Poza tym jest darmowy i co najlepsze, Rancher potrafi napisać manifesty za nas. Użytkownik musi jedynie wpisać odpowiednie dane w bardzo prostym w użyciu formularzu.

Ciekawostką jest to, że Rancher działa w Kubernetesie. Postaram się jednak ułatwić proces instalacji lokalnego klastra Kubernetes oraz Ranchera do minimum.

Instalacja K3s i Ranchera

Rancher nie należy do najlżejszych, dlatego komputer na którym go uruchomimy, najlepiej żeby miał przynajmniej 16 GB RAM. Osobiście uruchomiłem go bez problemu na Surface Pro 8 na CPU i5 11 generacji od Intela i 16 GB RAM. Nie zalecam instalacji Ranchera w ten sposób przy mniejszej ilości dostępnej pamięci.

Jednak jeśli twój komputer ma mniejszą ilość pamięci, nadal możesz nauczyć się z tego poradnika jak zainstalować K3S w WSL v2 (i ewentualnie na własną rękę zainstalować coś lżejszego, np. Kubernetes Dashboard).

Czym jednak jest K3S? Jest to lekka ale jednocześnie bardzo potężna dystrybucja Kubernetesa. Jest bardzo prosta w instalacji i świetnie sprawdzi się w ewentualnym wysoko dostępnym środowisku produkcyjnym.

Statystycznie rzecz biorąc, większość osób korzysta z Windowsa, dlatego pokażę, jak zainstalować Ranchera używając:

Windows -> WSL (z systemem AlmaLinux 9) -> K3S

WSL (Windows Subsystem for Linux) pozwoli nam na szybką instalację lekkiego Linuxa, na którym będziemy mogli eksperymentować.

Oczywiście nic nie stoi na przeszkodzie, aby uruchomić inną dystrybucję Linuxa na VirtualBoxie, Hyper-V, Proxmoxie czy Vmware, a następnie na niej K3S. Jednak w tym poradniku użyjemy WSL v2 ponieważ wydaje się najwygodniejszą i najszybszą opcją.

Instalację WSL dla Windows 10 i 11 można znaleźć tutaj (będzie to niezbędne aby przejść dalej):

Install WSL

Install Windows Subsystem for Linux with the command, wsl --install. Use a Bash terminal on your Windows machine run by your preferred Linux distribution - Ubuntu, Debian, SUSE, Kali, Fedora, Pengwin, Alpine, and more are available.

Microsoft Learncraigloewen-msft

Jeśli masz już WSL, możemy zainstalować tam Linuxa. Osobiście proponuję AlmaLinux 9, który znajdziesz w Microsoft Store:

Po zainstalowaniu naszego nowego Linuxa pod WSL, uruchamiamy go i tworzymy nowego użytkownika:

Domyślnie, Linux uruchomiony w WSL nie obsługuje systemd, które jest potrzebne do instalacji K3S. Dlatego, żeby uruchomić systemd, musimy jako root edytować plik /etc/wsl.conf i dodać do niego następujące linie:

[boot]
systemd=true

Żeby powyższa zmiana została zastosowana w Linuxie, musimy go zrestartować. W tym celu zamykamy kartę z naszym Linuxem i otwieramy kartę z PowerShellem w którym uruchamiamy polecenie wsl --shutdown:

To polecenie zamyka wszystkie systemy uruchomione w WSL.

Teraz możemy ponownie uruchomić kartę z AlmaLinuxem i sprawdzić czy systemd działa prawidłowo:

Kiedy mamy już gotowy system do instalacji Kubernetesa, jako root uruchamiamy polecenie:

curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=v1.26.9+k3s1 sh -s - server --cluster-init

Jak widzimy, skrypt instalacyjny umieścił kilka plików w /usr/local/bin/. Dlatego dla ułatwienia dodajemy tę ścieżkę do PATH poleceniem:

export PATH=$PATH:/usr/local/bin

Żeby przy każdym uruchomieniu terminala nie musieć za każdym razem wykonywać tego polecenia, warto dodać je na końcu pliku /root/.bashrc.

Teraz powinniśmy mieć możliwość używania poleceń kubectl:

Nasz w pełni funkcjonalny Kubernetes jest już gotowy. Powyżej widzimy listę Podów w Namespace o nazwie kube-system, odpowiedzialnych za działanie Kubernetesa.

Tutaj możemy się na chwilę zatrzymać aby wytłumaczyć kilka terminów.

Pody to w zasadzie kontenery, w których są uruchomione aplikacje. Dlaczego więc nazywa się to Pod zamiast po prostu kontener? Przede wszystkim dlatego, że jeden Pod może zawierać w sobie więcej niż jeden kontener. Poza tym Pod oprócz tego, że zawiera w sobie kontenery, ma również logikę, która na przykład sprawdza czy kontener w Podzie jest aktywny. Pod pomimo tego że może zawierać kilka kontenerów, zawsze ma jeden adres IP, które kontenery wewnątrz współdzielą. Na powyższym zrzucie ekranu widzimy między innymi uruchomione Pody:

• coredns - wewnętrzna usługa DNS służąca do komunikacji pomiędzy Podami w sieci Kubernetesa
• metrics-server - serwer metryk zbierający dane o zużyciu CPU i pamięci przez kontenery. Potrzebny do działania polecenia kubectl top node czy autoskalowania.
• traefik - krótko mówiąc jest to proxy, które w nomenklaturze Kubernetesa nazywane jest Ingress Controllerem. Żeby zrozumieć jak działa posłużmy się przykładem bardzo popularnego serwera WWW, czyli Apache. W Apache tworzymy VirtualHosty (czyli jeszcze inaczej: podpięte domeny w np. cPanel), żeby przekierować użytkownika po wykrytej nazwie domenowej na jakiś plik lub inny serwer. W Kubernetesie tworzymy Ingressy aby przekierować użytkownika po wykrytej nazwie domenowej na daną usługę (Service), która końcowo, przekieruje nas na jakiś Pod.

Z kolei Namespace to przestrzeń w której tworzone są Pody. Możemy tworzyć kilka Namespace'ów, żeby uporządkować nasze Pody. Poza tym, jeśli chcemy na przykład, komuś udostępnić klaster Kubernetes, możemy ograniczyć dostęp do jednego Namespace, w którym ktoś będzie mógł wykonać deploy swojej aplikacji.

Wróćmy jednak do instalacji panelu Rancher. Przed instalacją potrzebujemy przygotować jakąś domenę, którą przekierujemy na IP naszego Linuxa. Żeby jednak poznać IP Linuxa uruchomionego w WSL, potrzebujemy zainstalować pakiet hostname:

Jak widać powyżej, po zainstalowaniu pakietu hostname i wykonaniu polecenia hostname -I możemy zobaczyć adres IP systemu uruchomionego w WSL (adres pierwszy od lewej).

Teraz uruchamiamy w Windowsie uruchamiamy notatnik jako administrator i edytujemy plik /etc/hosts

Po otwarciu tego pliku, dodajemy domenę np. rancher.local, którą przekierowujemy na adres IP Linuxa uruchomionego w WSL i zapisujemy plik

Teraz prawie jesteśmy gotowi do instalacji Ranchera. Prawie ponieważ będziemy potrzebować jeszcze narzędzia Helm.

Helm jest menedżerem pakietów. Jest to taki trochę yum/dnf/apt/zypper tylko dla Kubernetesa.

Żeby zainstalować Helma, wystarczy wykonać polecenie:

curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

Teraz mamy wszystko gotowe do tego, aby zainstalować Ranchera.

Dlatego teraz wykonujemy po kolei poniższe polecenia:

export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
helm repo add rancher-latest https://releases.rancher.com/server-charts/latest

kubectl create namespace cattle-system

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.11.0/cert-manager.crds.yaml

helm repo add jetstack https://charts.jetstack.io

helm repo update

helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --version v1.11.0

helm install rancher rancher-latest/rancher \
  --namespace cattle-system \
  --set hostname=rancher.local \
  --set replicas=1 \
  --set bootstrapPassword=Haslo_do_panelu_rancher

Po wykonaniu ostatniego polecenia, powinien przywitać nas następujący komunikat:

Teraz wykonując polecenie:

echo https://rancher.local/dashboard/?setup=$(kubectl get secret --namespace cattle-system bootstrap-secret -o go-template='{{.data.bootstrapPassword|base64decode}}')

Otrzymamy adres, którym możemy zalogować się do naszego panelu Rancher. Po uruchomieniu tego adresu IP w przeglądarce, powinien ukazać się nam komunikat o nieprawidłowym certyfikacie (który oczywiście pomijamy), a następnie panel Rancher:

Akceptujemy licencję i przechodzimy dalej.

Gotowe! Rancher jest gotowy do zarządzania naszym Kubernetesem.

Teraz klikamy na nazwę naszego klastra (local) i możemy zaczynać naszą zabawę z Kubernetesem.

Tworzymy pierwszy Deployment

Kiedy mamy już postawiony panel Rancher, możemy w prosty sposób spróbować coś umieścić w klastrze Kubernetes.

Dla przykładu spróbujemy na naszym klastrze Kubernetes uruchomić... WordPressa.

Jednak, żeby uruchomić WordPressa, potrzebujemy bazy danych MySQL. Oczywiście moglibyśmy zainstalować MySQL na naszym Linuxie, ale po co skoro w prosty i szybki sposób, możemy uruchomić ją na naszym Kubernetesie.

W tym celu przechodzimy do zakładki Workloads -> Deployments, a następnie klikamy Create.

W polu Name wpisujemy np. mariadb, a następnie w polu Container image wpisujemy mariadb. W polu Container image istotne, żebyśmy nie zrobili literówki, ponieważ tutaj decydujemy, jaki obraz ma zostać pobrany.

Przy tym polu warto też dodać, że możemy w nim wpisać nazwę dowolnego obrazu dostępnego w Docker Hub

Teraz musimy sprawić, aby nasz MySQL był dostępny w sieci klastra Kubernetes. W tym celu w sekcji Networking dodajemy Service typu Cluster IP o nazwie mariadb, i Private Container Port ustawiamy na 3306.

Teraz schodzimy niżej do sekcji Environment Variables i dodajemy następujące zmienne typu Key/Value Pair (zgodnie z dokumentacją Docker Hub):

MARIADB_RANDOM_ROOT_PASSWORD = 1
MARIADB_USER = wordpress
MARIADB_PASSWORD = password
MARIADB_DATABASE = wordpress

Całość będzie wyglądać następująco:

Po wypełnieniu powyższych pul, klikamy Create.

Jeśli wszystko wypełniliśmy prawidłowo, nasz kontener z MySQL powinien być aktywny.

Jeśli chcemy dla zabawy wejść do utworzonego kontenera, możemy kliknąć 3 kropki po prawej stronie i wybrać Execute Shell.

Skoro nasza baza danych jest już gotowa, możemy teraz uruchomić naszego WordPressa. Żeby to zrobić, tworzymy kolejny Deployment.

Tym razem w polu Name wpisujemy np. wordpress, następnie w polu Container image wpisujemy wordpress.

Następnie w sekcji Networking dodajemy Service typu Node Port o nazwie wordpress. Private Container Port ustawiamy na 80, z kolei Listening Port ustawiamy na 30001.

Teraz schodzimy niżej do sekcji Environment Variables i dodajemy następujące zmienne typu Key/Value Pair:

WORDPRESS_DB_HOST = mariadb
WORDPRESS_DB_USER = wordpress
WORDPRESS_DB_PASSWORD = password
WORDPRESS_DB_NAME = wordpress

Tutaj warto się zatrzymać przy zmiennej WORDPRESS_DB_HOST. Tutaj w standardowej instalacji np. na hostingu współdzielonym, podalibyśmy IP lub nazwę domenową serwera MySQL.

Jednak w Kubernetesie, musimy podać nazwę stworzonego Service, kierującego na Pod z serwerem MySQL. W naszym przypadku Service nazywa się po prostu mariadb. Jednak jeśli nie wiedzielibyśmy jaką nazwę ma nasz Service, można to sprawdzić w zakładce Service Discovery -> Services

Całość będzie więc wyglądać następująco:

Klikamy Create i po kilku chwilach powinniśmy zobaczyć taki oto widok:

W porządku, kontenery działają. Ale co z naszym WordPressem?

Otóż wystawiliśmy go na porcie 30001. Wchodzimy więc pod adres:

http://rancher.local:30001

Jeśli wszystko zrobiliśmy prawidłowo, powinniśmy ujrzeć instalator Wordpressa:

Prawda, że to było proste?

No tak, ale co my właściwie zrobiliśmy?

1. Utworzyliśmy Deployment, który utworzył nam Pod z kontenerem zwierającym MySQL, oraz Service nasłuchujący na porcie 3306 w sieci klastra Kubernetes (Cluster IP) i kierujący na ten Pod.
2. Utworzyliśmy drugi Deployment, który utworzył nam Pod z kontenerem zawierającym WordPressa, oraz Service typu Node Port nasłuchujący na zewnątrz na porcie 30001 i kierujący na ten Pod.

Gdybym napisałbym to na początku, można by było uznać powyższe słowa za jakąś czarną magię. Jednak użycie odpowiedniego narzędzia potrafi zmienić perspektywę.

Kiedy mamy już gotowy Deployment z WordPressem, zobaczmy jeszcze jak w bardzo prosty sposób, możemy skalować naszą aplikację.

Żeby to zrobić wystarczy, że w zakładce Health klikniemy strzałkę w dół, a następnie klikniemy znak +

Po kilku chwilach powinien się pojawić kolejny kontener z naszym WordPressem.

Możemy to zobaczyć w zakładce Workloads -> Pods

Teraz ruch na stronie http://rancher.local:30001 będzie rozłożony jednocześnie na dwóch kontenerach. Możesz oczywiście utworzyć więcej Podów, jeśli Twój komputer to udźwignie.

Przy skalowaniu ciekawą rzeczą, która może wydawać się nieintuicyjna jest to, że gdy spróbujesz usunąć dany Pod, zaraz po jego usunięciu na jego miejsce pojawi się drugi. Odpowiada za to tak zwany ReplicaSet jednak to już jest materiał na inny artykuł 😊

Podsumowanie

Jak widzisz, używając odpowiednich narzędzi, utworzenie czegoś w klastrze i zarządzanie klastrem Kubernetes nie musi być trudne.

Oczywiście to co opisałem wyżej to zaledwie kropla tego, co możemy zrobić w Kubernetesie. Na Kubernetesie złożonym z jednej maszyny, nie możemy w praktyce doświadczyć potęgi tego rozwiązania. Potraktuj jednak ten artykuł jako taki całkowicie podstawowy wstęp do nauki tej technologii.

Narzędzia takie jak K3S i Rancher skutecznie pozwalają pokonać stromą krzywą uczenia się Kubernetesa, a jednocześnie często są używane w środowiskach produkcyjnych, dlatego na pewno warto je znać.

Na koniec zachęcam Cię do eksperymentowania z Kubernetesem w panelu Rancher i próbowania różnych konfiguracji i obrazów kontenerów.

Mam nadzieję, że chociaż trochę pomogłem Ci się oswoić z tą technologią oraz oczywiście życzę powodzenia w nauce Kubernetesa 😊

Dokumentacja jest kluczowa dla skutecznego zarządzania, utrzymania i rozwijania systemu. Dobra dokumentacja ułatwia zrozumienie funkcji, interfejsów i ogólnej architektury systemu co ułatwia współpracę między zespołami a także usprawnia onboarding nowych pracowników. Dobra dokumentacja oznacza oszczędność czasu (i pieniędzy), który w innym przypadku musiałby być przeznaczony na spotkania, ustalenia itd.

Cechy dobrej dokumentacji

• zrozumiała - napisana w przystępny sposób bez zawiłych i skomplikowanych terminów technicznych.
• aktualna - regularnie aktualizowana.
• kompletna - wszystkie istotne funkcje i elementy systemu powinny być dokładnie opisane w dokumentacji, powinna zawierać informacje na temat instalacji, konfiguracji, używania, zwalczania problemów oraz utrzymania systemu.
• łatwo dostępna i dobrze zorganizowana - użytkownicy powinni mieć możliwość łatwego znalezienia potrzebnych informacji.

Co warto umieścić w dokumentacji

Dokumentacja powinna zawierać przede wszystkim wiedzę biznesową systemu. Zwykle tą część dokumentacji utrzymują analitycy biznesowi i product ownerzy, gdyż to oni wiedzą o zmianach jako pierwsi. Techniczne aspekty systemu również powinny znaleźć się w dokumentacji. Oczywiście można być zwolennikiem samo dokumentującego się kodu ale często może być to za mało. Dlatego warto aby zespół, głównie developerzy postarali się o aktualizowanie dokumentacji w tym kontekście np. w postaci ADR (Architecture Decision Record).

Przykładowe elementy, które warto umieścić w dokumentacji:

• Funkcje i odpowiedzialności (zarys biznesowy)‌‌
  Za co mikroserwis jest odpowiedzialny, jakie dane przetwarza i jakie pełni funkcje w kontekście całego systemu, kto jest opiekunem.
• Stack technologiczny‌‌
  Opis systemu w kontekście użytych technologii, aktualizowany na bieżąco wraz z wyjaśnieniem dlaczego wybraliśmy takie technologie a nie inne. Warto pomyśleć o utrzymywaniu ADR (Architecture Decision Record), który mógłby być nawet przechowywany w repozytorium kodu.
• Środowiska‌‌
  Spis środowisk (np. INT, PREP, PROD itd).
• Repozytorium‌‌
  Spis wszystkich repozytoriów git rozwijanych w ramach danego podsystemu.
• Dokumentacja API‌‌
  Zbiór informacji opisujących funkcje, zasady i sposoby korzystania z danego interfejsu programistycznego. Jej istotną rolą jest umożliwienie developerom zrozumienia jak prawidłowo korzystać z API, jakie są dostępne funkcje, jakie parametry przyjmują żądania oraz jakich odpowiedzi możemy się spodziewać.
  Powinna być możliwość pobrania aktualnej specyfikacji API w formacie yaml/json zgodnej z standardem openapi (wsdl w przypadku SOAP). Pomocnym narzędziem może się okazać swagger.
• Interakcje z innymi systemami
  Opis integracji z innymi systemami w tym wymagane protokoły komunikacyjne.
• Instrukcje instalacji i konfiguracji
  Instrukcja zawierająca ważne informacje o instalacji czy też uruchomieniu aplikacji w szczególności uruchomieniu na lokalnym środowisku developerskim co pozwoli szybko wdrożyć się w system nowemu developerowi. Idealnie aby każde repo posiadało README.md, w którym będzie opisane jak uruchomić system lokalnie.
• Instrukcje użytkowania
  Opis jak korzystać z różnych funkcji i narzędzi systemu.
• Proces CI/CD
  Chcemy tutaj opisać proces jaki zachodzi od zmiany kodu przez developera w ramach jakiejś funkcjonalności po wdrożenie zmian na produkcję.
• Changelog
  Chcemy dokumentować wszystkie zmiany w pliku changelog najlepiej przechowywanym w repozytorium kodu. Przykład pliku changelog.
• Testowanie
  W jaki sposób podchodzimy do testowania mikroserwisu, jakie testy wykonujemy.
• Konwencje
  Informacje dla developerów, jeżeli chodzi o konwencje kodowania (np. pliki checkstyle) lub inne ważne informacje.
• Awarie
  Rejestr awarii zawierający opis co się wydarzyło, kiedy, co było przyczyną i jak udało się naprawić oraz inne przydatne informacje.
• Inne
  Inne przydatne informacje np. informacje kontaktowe dla wsparcia technicznego.

Oczywiście jest to tylko ogólna propozycja tego co mogłoby się znaleźć w dokumentacji. W zależności od specyfiki projektu może wyglądać to inaczej.

Podsumowanie

Inwestycja w szczegółową i zrozumiałą dokumentację oprogramowania to inwestycja w przyszłość - oszczędza czas, zasoby i zwiększa efektywność pracy zespołu. Jeżeli masz jakieś ciekawe spostrzeżenia na ten temat komentarz będzie mile widziany 🙌.

Projektując złożone aplikacje często zachodzi potrzeba wykonania jakiejś funkcji w przyszłości - jednorazowo lub cyklicznie. Wystarczy wziąć na warsztat aplikację, która przypomina nam o różnych wydarzeniach, wysyła cyklicznie maile lub powiadomienia, czy też dokonuje płatności w modelu subskrypcyjnym.

Wymienione wyżej funkcjonalności wymagają implementacji jakiegoś mechanizmu, który pozwoli nam to zrealizować w tle czyli asynchronicznie. W tym artykule postaram się to omówić na przykładzie ekosystemu Java.

Dlaczego asynchronicznie?

Zadania w tle są przydatnym mechanizmem i możliwością dla systemu sprawdzenia swojego wewnętrznego stanu i na jego podstawie w razie potrzeby wykonania pewnych akcji np. wysłanie maila, przygotowanie raportu czy też innego rodzaju uspójnienie systemu.

Wyobraźmy sobie, że chcemy aby nasz system wygenerował jakiś skomplikowany raport analityczny. Wygenerowanie wspomnianego raportu może być dość czasochłonne gdyż system musi najpierw pobrać dane z jakichś zewnętrznych źródeł i je przetworzyć w sensowny sposób w odpowiednim formacie.

Bez względu na to czy jest to aplikacja desktopowa, webowa czy mobilna, nie byłoby dobrym pomysłem zmuszanie użytkownika do czekania aż wspomniany wyżej raport się wygeneruje. Lepszym sposobem byłoby umożliwienie użytkownikowi kontynuowanie korzystania z aplikacji po uprzednim wrzuceniu generowania raportu w tło czyli wykonanie tego procesu asynchronicznie. Następnie po ukończeniu tego procesu powiadomienie użytkownika o rezultacie i możliwości pobrania raportu.

Typowym technicznym rozwiązaniem tego problemu jest skorzystanie z kolejki, gdzie główny system przyjmujący żądania od użytkownika wrzuca zdarzenia na kolejkę a system raportowy je odbiera i podejmuje odpowiednie działania. Dzięki temu, że wykonamy to zadanie asynchronicznie, odciążymy nasz główny mikroserwis udostępniający API, które powinno działać szybko i niezawodnie - nieobciążone przez jakieś "ciężkie" zadania, które działają w tle.

Java / Async

W tej sekcji skupimy się na tym jakie mamy możliwości przetwarzania asynchronicznego w ekosystemie Java. Sprawdźmy najpierw jakie mamy możliwości pomijająć wykorzystanie zewnętrznych bibliotek i frameworków.

Pierwszym co może przyjść do głowy jest użycie wątków.

public static void main(String[] args) throws InterruptedException {
        var thread = new Thread(() -> {
                System.out.println("Process something in the background");
        });
        thread.start();
        thread.join();
}

Powyższe rozwiązanie, mimo że proste, ma istotne wady. Tworzenie wątków jest kosztowne pod względem zasobów, więc tworzenie ich na żądanie raczej nie jest dobrym pomysłem. Poza tym nie mamy kontroli nad ich ilością, więc w łatwy sposób moglibyśmy wysycić nasz system z zasobów.

Rozwiązaniem jest pula wątków, która może zwiększyć wydajność naszego systemu i pozwolić na nieco więcej kontroli.

public static void main(String[] args) throws InterruptedException {
        var pool = Executors.newFixedThreadPool(Runtime.getRuntime().availableProcessors());
        pool.execute(() -> {
                System.out.println("Process something in the background");
        });
        pool.shutdown();
        pool.awaitTermination(10, TimeUnit.SECONDS);
}

Jeżeli korzystamy z frameworków Spring i Spring Boot możemy wykorzystać do tego samego celu klasę TaskExecutor.

@Component
public class Foo {

    private final TaskExecutor taskExecutor;

    public Foo(TaskExecutor taskExecutor) {
        this.taskExecutor = taskExecutor;
    }

    public void bar() {
        taskExecutor.execute(() -> {
            System.out.println("Process something in the background");
        });
    }
}

Implementacja tej klasy jest dostarczana dzięki autokonfiguracji w TaskExecutionAutoConfiguration. Domyślnie na starcie otrzymamy pulę 8 wątków, która może rosnąć lub maleć w zależności od obciążenia (ilość zadań w kolejce).

Konfigurację możemy w łatwy sposób tuningować.

spring:
  task:
    execution:
      pool:
        max-size: 16
        queue-capacity: 100
        keep-alive: "10s"

Powyższa konfiguracja ustawia maksymalną liczbę wątków w puli na 16, w związku z tym jeżeli kolejka zadań do wykonania zapełni się (100 zadań), pula wątków zwiększy się do 16 wątków. Z kolei jeżeli wątki staną się bezczynne minimum przez 10 sekund, zostaną wyrzucone z puli (w przeciwieństwie do domyślnej wartości 60 sekund).

Możemy również ręcznie skonfigurować ten mechanizm dostarczając kawałek własnej klasy konfiguracyjnej.

@Configuration
public class AppConfig {

    @Bean
    public TaskExecutor taskExecutor() {
        var taskExecutor = new ThreadPoolTaskExecutor();
        taskExecutor.setCorePoolSize(4);
        taskExecutor.setMaxPoolSize(16);
        taskExecutor.setQueueCapacity(100);
        taskExecutor.setThreadNamePrefix("task-");
        return taskExecutor;
    }
}

Spring dostarcza również adnotację @Async, dzięki której w łatwy sposób możemy wywoływać dowolną metodę asynchronicznie korzystając z puli wątków, którą wcześniej utworzyliśmy.

Mechanizm ten trzeba najpierw włączyć adnotacją @EnableAsync co spowoduje zaimportowanie odpowiedniej autokonfiguracji.

@Configuration
@EnableAsync
public class AppConfig {

    @Bean
    public TaskExecutor taskExecutor() {
        var taskExecutor = new ThreadPoolTaskExecutor();
        taskExecutor.setCorePoolSize(4);
        taskExecutor.setMaxPoolSize(16);
        taskExecutor.setQueueCapacity(100);
        taskExecutor.setThreadNamePrefix("task-");
        return taskExecutor;
    }

    @Bean
    public Clock clock() {
        return Clock.system(ZoneId.of("Europe/Warsaw"));
    }
}

Następnie zamiast ręcznie wstrzykiwać TaskExecutor wykorzystamy wspomnianą adnotację @Async.

@Slf4j
@Component
public class Foo {

    @Async
    public void bar() {
        log.info("Hello world");
    }

    @Async
    public Future xyz() {
        return new AsyncResult<>("Hello world as a result");
    }
}

@SpringBootApplication
public class DemoApplication {

        public static void main(String[] args) {
                SpringApplication.run(DemoApplication.class, args);
        }

        @Autowired
        private Foo foo;

        @EventListener(ApplicationReadyEvent.class)
        public void ready() throws ExecutionException, InterruptedException {
                foo.bar();
                String result = foo.xyz().get();
                System.out.println(result);
        }
}

Scheduler

Wiemy już w jaki sposób możemy wrzucać zadania w tło. W tej sekcji poświęcimy czas jak takie zadania możemy planować i wykonywać w przyszłości jednorazowo lub cyklicznie.

Implementowanie takiego mechanizmu samodzielnie byłoby dość czasochłonne dlatego będziemy posiłkować się tym co dostarcza nam Spring. Istnieją również zewnętrzne alternatywy tj. Quartz, którymi możesz się zainteresować.

Analogicznie jak w przypadku TaskExecutor w celu planowania zadań mamy do dyspozycji klasę TaskScheduler. Spring dzięki autokonfiguracji w klasie TaskSchedulingAutoConfiguration dostarcza nam implementację tej klasy.

@SpringBootApplication
public class DemoApplication {

        public static void main(String[] args) {
                SpringApplication.run(DemoApplication.class, args);
        }

        @Autowired
        private MailSender mailSender;

        @Autowired
        private TaskScheduler taskScheduler;

        @EventListener(ApplicationReadyEvent.class)
        public void ready() {
                // 1
                taskScheduler.schedule(() -> {
                        mailSender.sendMail();
                }, Instant.now().plusSeconds(3600));

                // 2
                taskScheduler.scheduleAtFixedRate(() -> {
                        System.out.println("Hello world");
                }, 1000);
        }
}

Powyższy przykład pokazuje jak możemy dynamicznie zaplanować jednorazowe zadanie do wykonania na później, w tym przypadku wysyłka maila po upłynięciu godziny a także zadanie wykonywane cyklicznie.

Spring dostarcza nam również adnotację @Scheduled, dzięki której w łatwy sposób możemy wyrazić w jakich okolicznościach nasze job'y mają być uruchamiane i wykonywane. Mechanizm ten trzeba najpierw włączyć adnotacją @EnableScheduling co spowoduje zaimportowanie odpowiedniej autokonfiguracji.

@Configuration
@EnableAsync
@EnableScheduling
public class AppConfig {

    @Bean
    public Clock clock() {
        return Clock.system(ZoneId.of("Europe/Warsaw"));
    }
}

Następnie możemy przejść do stworzenia przykładowego job'a.

@Slf4j
@Component
public class JobExample {

    @Scheduled(fixedRate = 1000)
    public void hello() {
        log.info("Hello world");
    }
}

W tym przypadku po prostu wypisujemy na konsolę 'Hello world' co sekundę. Powyższa adnotacja ma więcej parametrów:

• zone - strefa czasowa, według której ma zostać uruchomione zadanie
• initialDelay - opóźnienie pierwszego uruchomienia w milisekundach (jednostkę można zmienić parametrem timeUnit)
• fixedDelay - czas pomiędzy zakończeniem ostatniego wykonania a rozpoczęciem kolejnego (wykorzystujemy do zadań zależnych od siebie)
• fixedRate - czas pomiędzy rozpoczęciem ostatniego i kolejnego wykonania (wykorzystujemy do zadań nieposiadających zasobów współdzielonych między sobą)
• fixedDelayString - liczba w formacie zrozumiałym przez Duration np. PT48H
• cron - wyrażenie cron w postaci ciągu znaków
  "a b c d e f" (cron expression)
  a - sekunda (0-59) b - minuta (0-59) c - godzina (0-23) d - dzien msca (1-31) e - miesiac (1-12) f - dzien tygodnia
  przykłady:
  9 12 * * * – co sekundę przez minutę od godz. 12:09:00 każdego dnia
  0 0 2-4 * * * – godz.2:00:00, 3:00:00 i 4:00:00 każdego dnia
  0 * 6,19 * * 2 – 6:00:00 i 19:00:00 w każdy wtorek
  0 0/30 10 * JAN * – 10:00:00, 10:30:00 każdego dnia stycznia
  0 0 12 * * MON-FRI – 12:00:00 od poniedziałku do piątku
  0 0 0 3 5 ? – każdego 3 maja o północy

Istnieje możliwość jednej metodzie przypisać wiele wywołań cyklicznych, które zgrupowane tworzą harmonogram. Należy do tego wykorzystać adnotacje @Schedules i w jej argumencie przekazać zadania do wykonania.

@Schedules({
        @Scheduled(cron = "0 30 10-13 ? * WED,FRI"),
        @Scheduled(fixedDelay = 10000)
})

Warto pamiętać o następujących regułach związanych z metodą pod adnotacją @Scheduled:

• powinna zwracać void
• nie powinna mieć żadnych parametrów w innym przypadku zostanie rzucony wyjątek typu IllegalStateException

Wielkość puli

Domyślnie w celu wykonania zadań Spring tworzy pulę wątków o wielkości 1. W związku z tym, jeżeli uruchomimy sekwencję kilku niezależnych zadań używając parametru fixedRate, implementacja zadziała podobnie jak fixedDelay ponieważ w tym przypadku w jednym momencie tylko jedno zadanie może być uruchomione.

Możemy w prosty sposób zmienić liczbę wątków w puli aby zmienić to zachowanie dodając odpowiednią konfigurację.

spring:
  task:
    scheduling:
      thread-name-prefix: "scheduling-"
      pool:
        size: 2

Oczywiście nic nie stoi na przeszkodzie aby dostarczyć dla frameworka własną implementację.

@Configuration
public class AppConfig {

    @Bean
    public ThreadPoolTaskScheduler threadPoolTaskScheduler() {
        ThreadPoolTaskScheduler threadPoolTaskScheduler = new ThreadPoolTaskScheduler();
        threadPoolTaskScheduler.setPoolSize(4);
        threadPoolTaskScheduler.setThreadNamePrefix("scheduling-");
        return threadPoolTaskScheduler;
    }
}

Synchronizacja

Zazwyczaj jeżeli system robi jakieś cykliczne operacje np. wysyłanie maila do klienta z fakturą raz na miesiąc, raczej chcielibyśmy uniknąć wielokrotnego wysyłania tych samych rzeczy (chyba, że mieliśmy jakieś problemy infrastrukturalne i chcemy ponowić wysyłkę). Problem ten może powstać jeżeli nasza aplikacja jest uruchomiona na kilku instancjach. Na szczęście istnieją rozwiązania tego problemu. Możemy np. skorzystać z biblioteki ShedLock, która pozwala na synchronizację zadań. Kolejnym rozwiązaniem może być wydzielenie funkcjonalności odpowiedzialnych za harmonogram zadań i planowanie do osobnego mikroserwisu i upewnienie się, że w klastrze istnieje tylko jedna jego instancja.

Praktyczne przykłady

Weźmy na warsztat 2 przykłady.

Załóżmy, że mamy aplikację, która działa w modelu subskrypcyjnym (np. Spotify). Obciążamy użytkownika co miesiąc za oferowane usługi. Jak technicznie podejść do tego tematu? W końcu każdy użytkownik mógł wykupić abonament dowolnego dnia miesiąca, więc kolejne pobranie środków powinno nastąpić dokładnie za miesiąc. Rozwiązaniem może być przygotowanie joba, który codziennie będzie się "budził" i przedłużał subskrypcję wszystkim użytkownikom, którym usługa już wygasła uprzednio pobierając środki.

Innym pomysłem, którego osobiście nie testowałem mogłoby być skorzystanie z opóźniania wiadomości na kolejce używając np. RabbitMq delayed message exchange lub innego podobnego mechanizmu.

Kolejny przykład. Wyobraźmy sobie, że chcemy wysyłać powiadomienia sms/mail/push do wszystkich użytkowników w naszym systemie o godzinie 10 rano biorąc pod uwagę to, że użytkownicy mogą być w różnych strefach czasowych (więc nie chcielibyśmy budzić niektórych o 3 w nocy). Jak moglibyśmy podejść do tematu? Jednym z rozwiązań może być job uruchamiany co godzinę, który za każdym razem wysyłałby powiadomienie tylko do użytkowników, u których aktualnie jest godzina 10. Oczywiście pamiętając o przechowywaniu strefy czasowej użytkownika w bazie danych aby móc stwierdzić wspomniany warunek.

Testowanie

Załóżmy, że mamy implementację joba, który codziennie od poniedziałku do piątku o godzinie 12 wysyła maila.

@Component
public class MailSenderJob {

    private final MailSender mailSender;

    public MailSenderJob(MailSender mailSender) {
        this.mailSender = mailSender;
    }

    @Scheduled(cron = "0 0 12 * * MON-FRI", zone = "Europe/Warsaw")
    public void sendMail() {
        mailSender.sendMail("Hello world");
    }
}

W jaki sposób możemy przetestować taką implementację? Adnotacja @Scheduled działa tylko w porozumieniu z springiem, więc koniecznym będzie podniesienie kontekstu springowego w testach tj. przygotowanie testu integracyjnego.

Zobaczmy najpierw jak może wyglądać poprawna konfiguracja schedulera.

@Configuration
@EnableScheduling
public class SchedulerConfig {

    @Bean
    public ThreadPoolTaskScheduler threadPoolTaskScheduler(Clock clock) {
        ThreadPoolTaskScheduler taskScheduler = new ThreadPoolTaskScheduler();
        taskScheduler.setPoolSize(5);
        taskScheduler.setClock(clock);
        taskScheduler.setWaitForTasksToCompleteOnShutdown(true);
        taskScheduler.setThreadNamePrefix("scheduling-");
        return taskScheduler;
    }

    @Profile("!it")
    @Bean
    public Clock clock() {
        return Clock.system(ZoneId.of("Europe/Warsaw"));
    }
}

Jak widać w powyższym przykładzie taskScheduler tworzony jest na podstawie wstrzykniętego obiektu klasy Clock. Dzięki temu w testach będziemy mogli w łatwy sposób podmienić tą implementację co pozwoli nam na przesuwanie się w czasie np. ustawiając czas kiedy job powinien wystartować, następnie wykonanie asercji czy faktycznie tak się stało. Odsyłam również do mojego poprzedniego artykułu gdzie także o tym pisałem.

Rozpocznijmy od stworzenia pomocnej implementacji Clock'a.

public class TestClock extends Clock {

    private final Clock baseClock;
    private Instant initializationTime;

    public TestClock(Instant fixed, ZoneId zone) {
        this(Clock.fixed(fixed, zone));
    }

    private TestClock(Clock baseClock) {
        this.baseClock = baseClock;
    }

    @Override
    public ZoneId getZone() {
        return baseClock.getZone();
    }

    @Override
    public Clock withZone(ZoneId zone) {
        return new TestClock(baseClock.withZone(zone));
    }

    @Override
    public long millis() {
        return instant().toEpochMilli();
    }

    @Override
    public Instant instant() {
        synchronized (this) {
            if (initializationTime == null) {
                initializationTime = Instant.now();
            }
        }
        long elapsedTime = ChronoUnit.MILLIS.between(initializationTime, Instant.now());
        return baseClock.instant().plusMillis(elapsedTime);
    }
}

Następnie przetestujmy naszą funkcjonalność.

@SpringBootTest
@ActiveProfiles("it")
class MailSenderJobTest {

    private static final Instant NOW = ZonedDateTime.parse("2023-04-12T11:59:57.000+02:00[Europe/Warsaw]").toInstant();

    @SpyBean
    private MailSender mailSender;

    @Test
    void shouldSendMailOnTime() {
        await().atMost(Duration.ofSeconds(5))
                .untilAsserted(() -> verify(mailSender).sendMail("Hello world"));
    }

    @TestConfiguration
    static class TestConfig {
        @Bean
        public Clock clock() {
            return new TestClock(NOW, ZoneId.of("Europe/Warsaw"));
        }
    }
}

Alternatywne podejście

Schedulery są silnym narzędziem, które pomagają w wykonywaniu cyklicznych operacji jednak rodzą też pewne problemy:

• hardcodowanie konfiguracji
• testowanie nie jest proste
• zmiana cykliczności wykonywanego zadania
  może spowodować przebudowanie znacznej części aplikacji

Lepszym rozwiązaniem z punktu widzenia utrzymania aplikacji może się okazać utworzenie metody webowej, która będzie przygotowana na wywołanie cykliczne. Wtedy środowisko CI/CD mogłoby pełnić rolę inicjatora i wywoływać metodę cykliczną w odpowiednich momentach w zależności od konfiguracji.

Podsumowanie

Mam nadzieję, że w pewnym stopniu przybliżyłem Tobie jak w praktyce możemy wykorzystywać narzędzia dostarczone w ekosystemie Java & Spring związane z planowaniem, tak aby ułatwić sobie pracę a zarazem zrobić to poprawnie. Jeżeli masz pytania lub chciałbyś podzielić się czymś ciekawym zostaw komentarz. Po więcej informacji odsyłam do dokumentacji. Do następnego! 👋

Przetwarzanie daty i czasu w aplikacjach zawsze sprawiało programistom wiele trudności gdyż trzeba wziąć wiele rzeczy pod uwagę. Wystarczy zerknąć na tę stronę aby uzmysłowić sobie ile potencjalnych błędnych założeń możemy popełnić. Mnogość różnych formatów zapisu daty i czasu, strefy czasowe, zmiany czasu z letniego na zimowy i odwrotnie oraz inne tego typu aspekty powodują, że łatwo jest strzelić sobie w stopę. Na domiar złego wszystko komplikuje ekosystem Javy, która udostępnia kilka różnych interfejsów i mechanizmów operacji na datach, przez co szczególnie początkujący mogą poczuć się zagubieni i nieświadomi potencjalnych problemów.

W tym artykule wyjaśnię w jaki sposób przetwarzać, zapisywać i testować czas w języku Java przy okazji wspominając o potencjalnych problemach, które możemy napotkać.

Legacy Api

W języku Java mamy do dyspozycji wiele klas i interfejsów wspierających przetwarzanie dat i czasu. Gdy Java wyszła na świat w pierwszej wersji otrzymaliśmy klasę java.util.Date, która reprezentuję punkt w czasie z milisekundową dokładnością.

Date now = new Date();
Date tomorrow = new Date(now.getTime() + 1000 * 3600 * 24);
System.out.println(now.getMonth() + 1); // print month
System.out.println(now.getYear() + 1900); // print year
if (now.before(tomorrow)) {
	System.out.println("now is before tomorrow");
}
if (tomorrow.after(now)) {
	System.out.println("tomorrow is after now");
}
if (now.compareTo(now) == 0) {
	System.out.println("now is equal to now");
}

Jak widać powyżej API nie jest intuicyjne i nie należy do najprostszych. Wyciąganie takich składowych jak rok czy miesiąc lub formatowanie jest nieporęczne nie wspominając o internacjonalizacji czy strefach czasowych. Obecnie większość metod tej klasy jest oznaczona jako @Deprecated a sama klasa nie jest zalecana do użycia.

Rozwiązaniem powyższych problemów miała być klasa Calendar, którą otrzymaliśmy w wersji 1.1 wraz z klasami odpowiedzialnymi za formatowanie (DateFormat, SimpleDateFormat) i strefy czasowe (TimeZone, SimpleTimeZone).

// Calendar with default timzone
Calendar calendar = Calendar.getInstance();

// Calendar with specific timezone
Calendar calendarWithZone = Calendar.getInstance(TimeZone.getTimeZone("Europe/Warsaw"));

// get date object
Date now = calendar.getTime();

// set time object
Date later = new Date();
calendar.setTime(later);

// get date components
int year = calendar.get(Calendar.YEAR);
int month = calendar.get(Calendar.MONTH);
int day = calendar.get(Calendar.DAY_OF_MONTH);
int hour = calendar.get(Calendar.HOUR);
int minute = calendar.get(Calendar.MINUTE);
int second = calendar.get(Calendar.SECOND);
int millis = calendar.get(Calendar.MILLISECOND);

// add 24 hours
calendar.add(Calendar.HOUR, 24);

// Internationalization
Locale locale = new Locale("pl", "PL");
DateFormat dateFormat = DateFormat.getDateInstance(DateFormat.FULL, locale);
System.out.println(dateFormat.format(later)); // czwartek, 3 listopada 2022

API jest bardziej czytelne i intuicyjne jednak obecnie również niezalecane do wykorzystywania. Interfejs był projektowany gdy w specyfikacji języka nie było jeszcze typu wyliczeniowego więc łatwo o błąd w przypadku stałych numerycznych - nie możemy liczyć na błąd kompilacji. Co więcej klasa Calendar jest narzutem na wydajność i zużywa sporo pamięci ponieważ wewnętrznie przechowuje stan na dwa różne sposoby.

Kolejnym problemem dla omówionych powyżej API jest bezpieczeństwo w przypadku przetwarzania współbieżnego tj. na wielu wątkach. Z uwagi na to, że klasy Date jak i Calendar mogą zmieniać stan (mutable) łatwo o błąd gdy dojdzie do wyścigu w związku z tym niezbędna jest synchronizacja lub używanie mechanizmu ThreadLocal.

Istnieją również klasy rozszerzające klasę java.util.Date (wrappery) m.in. java.sql.Date, java.sql.Time, java.sql.Timestamp stworzone na potrzeby jdbc-api. Mają one zastosowanie gdy integrujemy się z bazą danych w związku z tym nie powinniśmy ich używać w kodzie domenowym a jedynie do odczytu/zapisu czy też mapowania relacyjno-obiektowego.

Nowe API od Java 8

W wersji 8 doczekaliśmy się nowego API związanego z obsługą dat i czasu kojarzone również jako JSR-310. Nowa specyfikacja jest o wiele bardziej intuicyjna i pozwala zastąpić stare API omówione w poprzednim punkcie jak i inne zewnętrzne biblioteki usprawniające prace z czasem np. joda-time - najczęściej używana przed wydaniem tej wersji.

Nowe API zostało usytuowane w pakiecie java.time i zawiera m.in. następujące klasy:

Insant - Reprezentuje określony punkt w czasie z nanosekundową precyzją.

Duration - Odcinek czasu z nanosekundową precyzją np. 34.5 sekundy.

LocalDateTime - Data i czas bez strefy czasowej w standardzie ISO-8601 z nanosekundową precyzją
np. 2022-12-03T14:15:30.

LocalDate - Data bez strefy czasowej w standardzie ISO-8601 np. 2022-10-03.

LocalTime - Czas bez strefy czasowej w standardzie ISO-8601 z nanosekundową precycją np. 12:30:45.

ZonedDateTime - Data i czas z strefą czasową w standardzie ISO-8601 z nanosekundową precyzją
np. 2022-11-14T14:15:30+01:00 Europe/Warsaw.

ZoneId - Identyfikator strefy czasowej np. Europe/Warsaw.

Year - Rok w standardzie ISO-8601 np. 2022.

MonthDay - Miesiąc i dzień w standardzie ISO-8601 np. 11-28.

YearMonth - Rok i miesiąc w standardzie ISO-8601 np. 2022-12.

ZoneOffset - Offset od czasu Greenwich/UTC z sekundową precyzją np. +02:00.

OffsetDateTime - Data i czas z przesunięciem od czasu Greenwich/UTC w standardzie ISO-8601
z nanosekundową precyzją np. 2022-11-06T12:15:30+01:00.

OffsetTime - Czas z przesunięciem od czasu Greenwich/UTC w standardzie ISO-8601
z nanosekundową precyzją np. 11:15:30+01:00.

Period - Odcinek czasu jako ilość lat, miesięcy i dni w standardzie ISO-8601 np.
'2 years, 3 months and 4 days'.

Clock - Pozwala na dostęp do aktualnego czasu i strefy czasowej.

Klas jest dość sporo więc na początku może być trudno się zorientować, których użyć w jakim przypadku natomiast niebagatelną zaletą tego jest to, że każda klasa ma swoje przeznaczenie zgodnie z zasadą SRP w przeciwieństwie do omawianej wcześniej klasy Date. Warto również zwrócić uwagę na to, że każda z klas jest immutable & thread safe co z pewnością wpływa na bezpieczeństwo i jakość oprogramowania.

Zanim przejdę do omówienia najważniejszych klas bardziej szczegółowo warto zerknąć na obrazek poniżej, który jest pomocny w odnalezieniu się w tym gąszczu klas.

Instant

Reprezentuje określony moment w czasie. Początek został wyznaczony na północ 1 stycznia 1970 roku. Począwszy od tego punktu czas jest mierzony w sekundach po 86400 sekund na dobę w tył oraz w do przodu z dokładnością do nanosekund. Wartości klasy Instant mogą określać czas sięgający miliarda lat wstecz (Instant.MIN). Instant.MAX odpowiada dacie 31 grudnia 1 000 000 000, jeżeli przekroczymy tę wartość otrzymamy wyjątek DateTimeException.

@Test
void testInstant() {
	Instant now = Instant.now();
	Instant later = now.plusSeconds(3600);
	System.out.println(now + ", " + later); // 2022-11-05T17:56:40.669420Z, 2022-11-05T18:56:40.669420Z
	assertTrue(later.isAfter(now));
}

Instant idealnie nadaje się do rejestrowania czasu różnego rodzaju zdarzeń lub logów.

Duration

Reprezentuje odcinek czas pomiędzy dwoma punktami w sekundach z dokładnością do nanosekund gdzie 24h = 86400 sekund. Długość Duration możemy wygodnie pobierać używając takich metod jak toNanos, toMillis, toSeconds, toMinutes, toHours, toDays. Przydaje się w wyliczaniu różnego rodzaju odległości w czasie.

@Test
void testDuration() {
	Instant now = Instant.now();
	Instant later = now.plus(4, ChronoUnit.HOURS);
	var duration = Duration.between(now, later);
	assertEquals(4, duration.toHours());
}

Używając Duration można również w łatwy sposób „skakać”
w czasie definiując odpowiednią długość w czasie.

Instant now = Instant.now();
Instant tomorrow = now.plus(Duration.ofDays(1));

Warto wiedzieć, że klasa Duration obsługuje parsowanie w standardzie ISO-8601 w związku z tym można przekazać do metody odpowiedni łańcuch znaków. Dzięki temu możemy w łatwy sposób wyrazić odległość w czasie za pomocą jednej zmiennej, która może być wyniesiona do jakiejś zewnętrznej konfiguracji.

Duration duration = Duration.parse("P2DT3H4M"); // 2 days, 3 hours and 4 minutes

LocalDateTime

Zawiera informację o dacie oraz czasie z nanosekundową precyzją natomiast nie udostępnia żadnych informacji na temat strefy czasowej. Z tego względu czas wyrażony z użyciem LocalDateTime nie może być rozpatrywany jako bezwględny ponieważ może być inny w zależności od tego gdzie się znajdujemy w przeciwieństwie do Instant, który jest wyliczany bez względu na strefę czasową.

LocalDateTime now = LocalDateTime.now();

Domyślnie lokalna data jest wyliczana na podstawie domyślnej strefy czasowej ustawionej w systemie lub na maszynie wirtualnej. Warto pamiętać, że w przypadku LocalDateTime nie należy polegać na systemowej strefie czasowej
gdyż wyniki mogą być różne w zależności od tego gdzie zostanie zainstalowana nasza aplikacja. Na szczęście mamy nad tym kontrolę i możemy do metody statycznej przekazać strefę czasową, na podstawie której zostanie wygenerowana data.

LocalDateTime now = LocalDateTime.now(ZoneId.of("Europe/Warsaw"));

Jeżeli chcemy globalnie ustawić lokalną strefę czasową dla aplikacji możemy przekazać odpowiednią wartość do maszyny wirtualnej w następujący sposób.

java -Duser.timezone="Europe/Warsaw" -jar app.jar

LocalTime

Zawiera informację o lokalnym czasie z pominięciem strefy czasowej z nanosekundową precyzją i nie zwraca uwagi na podział AM/PM, tym zajmują się mechanizmy odpowiedzialne za formatowanie.

Utworzenie obiektu tej klasy sprowadza się do pobrania aktualnego czasu poprzez LocalTime.now() lub z góry ustalonego czasu LocalTime.of(hour, minute, second, nanoOfSecond) gdzie:

• hour - liczba z zakresu 0-23
• minute - liczba z zakresu 0-59
• second - liczba z zakresu 0-59
• nanoOfSecond - liczba z zakresu 0-999 999 999

@Test
void localTimeTest() {
	LocalTime now = LocalTime.now(ZoneId.of("Europe/Warsaw"));
	LocalTime later = now.plusHours(4);
	assertTrue(later.isAfter(now));
	assertEquals(4, Duration.between(now, later).toHours());	
}

LocalDate

Reprezentuje rok, miesiąc i dzień bez informacji o czasie i strefie czasowej. Idealnie nadaje się np. do zapisania daty urodzin lub innych wydarzeń gdzie czas nie ma znaczenia.

LocalDate birthday = LocalDate.of(2022, 11, 14);

Aby obliczyć datę urodzin w przyszłym roku wystarczy użyć wyrażenia w postaci birthday.plus(Period.ofYears(1)) lub po prostu birthday.plusYears(1). Należy pamiętać, że w roku przestępnym wywołanie w postaci birthday.plus(Period.ofDays(365)) zwróci nieprawidłowy wynik.

Warto również wspomnieć, że stworzenie daty 29 lutego w roku nieprzestępnym np. LocalDate.of(2023, 2, 29) objawi się wyjątkiem typu DateTimeException.

Jak wyliczyć dzień programisty

Dzień programisty wypada na 256 dzień w roku. Jak go wyliczyć biorąc pod uwagę, że w roku przestępnym jest o jeden dzień więcej? Możemy to zrobić w następujący sposób.

LocalDate programmersDayInCurrentYear = 
				LocalDate.now()
				.withMonth(1)
				.withDayOfMonth(1)
				.plusDays(255);

ZonedDateTime

ZonedDateTime reprezentuje datę i czas wraz z strefą czasową z nanosekundową precyzją. Bazę danych wszystkich stref czasowych na całym świecie przechowuje agencja IANA i aktualizuje ją kilka razy w roku. Java korzysta z tej bazy danych.

Każda strefa czasowa ma swój identyfikator np. America/New_York czy Europe/Berlin i aktualizuje ją kilka razy w roku. Listę wszystkich dostępnych stref czasowych możemy pobrać przy użyciu ZoneId.getAvailableZoneIds().

Dysponując tym identyfikatorem można przekształcić obiekt LocalDateTime na ZonedDateTime.

LocalDateTime now = LocalDateTime.now();
ZonedDateTime znow = now.atZone(ZoneId.of("Europe/Warsaw"));
System.out.println(now); // 2022-11-13T02:38:03.934777
System.out.println(znow); // 2022-11-13T02:38:03.934777+01:00[Europe/Warsaw]

Możemy również pobrać aktualny czas na podstawie domyślnej strefy czasowej tj. ZonedDateTime.now() lub bezpośrednio przekazać identyfikator strefy ZonedDateTime.now(ZoneId.of("Europe/Warsaw")).

Wywołanie LocalDateTime.atZone(...) dodaję strefę czasową tworząc obiekt typu ZonedDateTime jednak nie zmienia czasu na ten wskazany przez strefę czasową (LocalDateTime nie ma informacji o strefie czasowej więc nawet nie byłoby to możliwe). Jeżeli naszym celem jest również zmiana czasu możemy zrobić to w następujący sposób.

LocalDateTime someDate = LocalDateTime.parse("2022-11-10T18:40:00.000"); // time in Europe/Warsaw zone
ZonedDateTime convertedToSpecificZone = ZonedDateTime.ofInstant(
someDate.atZone(ZoneId.of("Europe/Warsaw")).toInstant(),
ZoneId.of("America/New_York"));

W przypadku konwersji ZonedDateTime -> ZonedDateTime robimy podobnie.

ZonedDateTime someDateWithZone = ZonedDateTime.now(ZoneId.of("Europe/Warsaw"));
ZonedDateTime newYorkTime = ZonedDateTime.ofInstant(someDateWithZone.toInstant(), ZoneId.of("America/New_York"));

lub zwięźlej

ZonedDateTime newYorkTime = someDateWithZone.withZoneSameInstant(ZoneId.of("America/New_York"))

OffsetDateTime

Reprezentuję datę i czas wraz z przesunięciem od czasu UTC/Greenwich z nanosekundową precyzją. Upraszczając OffsetDateTime jest to Instant + ZoneOffset i w taki też sposób możemy utworzyć obiekt tej klasy.

OffsetDateTime offsetDateTime = Instant.now().atOffset(ZoneOffset.of("+01:00"));
// lub
OffsetDateTime now = OffsetDateTime.now();

W przeciwieństwie do klasy ZonedDateTime nie mamy tu informacji o strefie czasowej a tym samym o przybliżonej lokalizacji geograficznej, jedynie sztywno zdefiniowany offset. Warto o tym pamiętać szczególnie gdy następuje zmiana czasu, różnicę możemy zobaczyć w kodzie poniżej, gdzie w dzień zmiany czasu z letniego na zimowy przesunęliśmy się w czasie o 4 godziny.

LocalDateTime dateTime = LocalDateTime.parse("2022-10-30T00:00:00.000");
ZonedDateTime zonedDateTime = dateTime.atZone(ZoneId.of("Europe/Warsaw")).plusHours(4);
OffsetDateTime offsetDateTime = dateTime.atOffset(ZoneOffset.of("+02:00")).plusHours(4);
System.out.println(zonedDateTime); // 2022-10-30T03:00+01:00[Europe/Warsaw]
System.out.println(offsetDateTime); // 2022-10-30T04:00+02:00

Period

Klasa mierząca odcinek czasu jako ilość lat, miesięcy i dni w odróżnieniu od klasy Duration omówionej wcześniej, gdzie najmniejszą jednostką, która mierzy upływ czasu były sekundy/nanosekundy.

Z tego względu Period użyjemy raczej do wyliczenia różnicy między dwoma datami typu LocalDate.

var now = LocalDate.parse("2022-11-10");
var later = now.plusDays(64);
var period = Period.between(now, later);
System.out.println(period.getMonths()); // 2
System.out.println(period.getDays()); // 3

Warto zwrócić uwagę, że mimo iż powyżej dodaliśmy 64 dni metoda getDays() zwraca nam 3 gdyż reszta dni została skonsolidowana do ilości miesięcy.

Period różni się także od Duration sposobem traktowania czasu letniego/zimowego w przypadku gdy dodajemy czas do ZonedDateTime. Jak wspomnieliśmy wcześniej Duration traktuje dzień zawsze jako 24h czyli 86400 sekund więc dokładnie o tyle przesuniemy czas w tył lub w przód, w przeciwieństwie do Period gdzie koncepcja dnia stara się zachować czas lokalny. Najłatwiej będzie zobaczyć to na przykładzie.

var dateTime = ZonedDateTime.parse("2022-10-29T09:00+02:00[Europe/Warsaw]");
System.out.println(dateTime.plus(Duration.ofDays(7))); // 2022-11-05T08:00+01:00[Europe/Warsaw]
System.out.println(dateTime.plus(Period.ofDays(7))); // 2022-11-05T09:00+01:00[Europe/Warsaw]

Ustawiłem datę na dzień przed zmianą czasu z letniego na zimowy. Dodając równo 7 dni do tej daty używając Duration godzina również się zmieniła z 9 na 8. Inaczej jest w przypadku Period gdzie godzina została zachowana (w przypadku LocalDateTime w obu przypadkach byłaby taka sama godzina tj. 9 gdyż ta klasa nie bierze pod uwagę zmiany czasu). Warto o tym pamiętać gdy np. chcemy zaplanować jakieś spotkanie w przyszłości.

TimeAdjusters

Często mamy potrzebę wyliczenia pierwszego/ostatniego dnia miesiąca/roku/tygodnia lub innych tego typu wyliczeń. Z pomocą przychodzi klasa TemporalAdjusters. Przykładowo wyliczenie pierwszego dnia miesiąca może wyglądać następująco.

LocalDate firstDayOfMonth = now.with(TemporalAdjusters.firstDayOfMonth());
// lub
LocalDate firstDayOfMonth =  (LocalDate) TemporalAdjusters.firstDayOfMonth().adjustInto(now);

Dostępnych jest wiele innych modyfikatorów m.in.

TemporalAdjusters.firstDayOfMonth();
TemporalAdjusters.lastDayOfMonth();
TemporalAdjusters.firstDayOfYear();
TemporalAdjusters.firstDayOfNextMonth();
TemporalAdjusters.firstDayOfNextYear();
TemporalAdjusters.firstInMonth(DayOfWeek.SATURDAY);
TemporalAdjusters.previous(DayOfWeek.FRIDAY);

Formatowanie, parsowanie i wyświetlanie

Aplikacje nad którymi pracujemy, często wymagają wyświetlenia a tym samym formatowania i parsowania daty i czasu na różne sposoby - czasami celem jest serializacja i przesłanie wartości przez sieć a czasem po prostu zwykłe wyświetlenie.

W najprostszym przypadku możemy skorzystać z domyślnego formatu tj. zgodnego z standardem ISO-8601 wywołując metodę toString() na obiekcie daty.

String now = LocalDate.now().toString();
System.out.println(now); // 2022-11-11
LocalDate localDate = LocalDate.parse(now);

Jednak najczęściej to nam nie wystarczy. Chcielibyśmy mieć większą kontrolę nad formatowaniem i parsowaniem czasu. Z pomocą przychodzi klasa DateTimeFormatter, która pozwala bardzo precyzyjnie to wyrazić.

Zdefiniowanie formatu sprowadza się do stworzenia
obiektu tej klasy na podstawie odpowiedniego wzorca.

LocalDate localDate = LocalDate.parse("2022-10-14");
var formatter = DateTimeFormatter.ofPattern("dd LLLL, yyyy");
String formatted = localDate.format(formatter); // lub formatter.format(localDate);
System.out.println(formatted); // 14 October, 2022

W celu wyświetlenia daty w rodzimym języku podczas
tworzenia formattera należy przekazać odpowiedni Locale.

LocalDate localDate = LocalDate.parse("2022-10-14");
Locale pl = new Locale("pl", "PL");
var formatter = DateTimeFormatter.ofPattern("dd LLLL, yyyy", pl);
System.out.println(localDate.format(formatter)); // 14 październik, 2022

Istnieje również wiele predefiniowanych formatów zgodnych
z standardem ISO-8601, które możemy wykorzystać m.in.

DateTimeFormatter.ISO_LOCAL_DATE
DateTimeFormatter.ISO_LOCAL_DATE_TIME
DateTimeFormatter.ISO_INSTANT
...

Testowanie

Aby napisane przez nas oprogramowanie było solidne warto zadbać o dobre testy jednostkowe i integracyjne.

W przypadku gdy testowany przez nas kod pobiera aktualny czas (np. Instant.now()) i na jego podstawie wykonuje pewną logikę nasz kod staje się trudno testowalny, gdyż nie mamy kontroli nad upływającym czasem, który za każdym uruchomieniem testu będzie inny.

Z pomocą przychodzi klasa Clock i jej pochodne, dzięki którym możemy w prosty sposób skonfigurować źródło, na podstawie którego czas będzie pobierany.

Clock clock = Clock.system(ZoneId.of("Europe/Warsaw"));
Instant instant = Instant.now(clock);

Jeżeli korzystamy z mechanizmu wstrzykiwania zależności np. w Spring'u możemy pójść o krok dalej i stworzyć komponent, który będzie wstrzykiwany tam gdzie nastąpi potrzeba pobierania czasu systemowego.

@Configuration
class AppConfig {

	@Bean
	public Clock clock() {
		return Clock.system(ZoneId.of("Europe/Warsaw"));
	}
}

@Service
class SomeService {

	private final Clock clock;

	public SomeService(Clock clock) {
		this.clock = clock;
	}

	public String bar() {
        return "Hello world " + Instant.now(clock);
    }
}

Następnie możemy przejść do przetestowania funkcjonalności podmieniając implementację Clock'a aby odzyskać kontrolę w testach.

@Test
void barTest() {
    // given
    Clock clock = Clock.fixed(Instant.parse("2022-11-12T10:39:33.307871Z"), ZoneId.of("Europe/Warsaw"));
    var subject = new SomeService(clock);

    // when
    String result = subject.bar();

    // then
    assertEquals("Hello world 2022-11-12T10:39:33.307871Z", result);
}

Pułapki

Planowanie spotkań

Załóżmy, że chcemy zaplanować spotkanie co tydzień o 14:30 czasu w strefie Europe/Warsaw. W tym celu musimy dodać do ostatniego czasu strefowego 7 dni czyli 7 * 4 * 3600 sekund, jednak jeśli przy tym przekroczymy granice zmiany czasu z letniego na zimowy okaże się, że spotkanie wypadnie o godzinę za wcześnie lub za późno.

ZonedDateTime dateTime = ZonedDateTime.of(LocalDateTime.of(2022, 10, 29, 14, 30), ZoneId.of("Europe/Warsaw"));
System.out.println(dateTime.plusSeconds(7 * 24 * 3600)); // 13:30 !!!

Z tego powodu projektanci API zalecają aby godzin z informacjami o strefie czasowej używać jedynie wtedy gdy posługiwanie się bezwzględnymi momentami czasu jest absolutnie niezbędne. Urodziny, święta, zaplanowane spotkania najlepiej zapisywać przy użyciu lokalnych dat i godzin.

LocalDateTime localDateTime = LocalDateTime.of(2022, 10, 29, 14, 30);
System.out.println(localDateTime.plusSeconds(7 * 24 * 3600)); // 14:30 OK

Używanie LocalDateTime gdy musimy mieć więcej informacji

Jak wiemy klasa LocalDateTime nie posiada informacji o żadnym offsecie od czasu UTC a tym samym o strefie czasowej. Jeżeli przykładowo tworzymy aplikację, która ma za zadanie przypominać użytkownika o różnych wydarzeniach i datę rozpoczęcia wydarzenia zapiszemy w postaci LocalDateTime tak naprawdę utracimy informację o faktycznym czasie rozpoczęcia (chyba, że zakładamy, że używamy tylko jednej globalnej strefy czasowej). Z tego względu warto mieć w takim przypadku dodatkową informację tj. strefę czasową w jakiej operuje użytkownik.

Błędy związane z formatowaniem

• Używanie "mm" dla miesięcy i "MM" dla minut i odwrotnie
• Używanie "DD" jako dzień miesiąca zamiast roku, w rzeczywistości dzień miesiąca to "dd"
• Używanie "hh" (1-12) jako godzina w danym dniu zamiast "HH" (0-23)
• Używanie "YYYY" do formatowania roku zamiast "yyyy"

Podsumowanie

Java 8 przyniosła liczne i długo wyczekiwane zmiany w kontekście date & time API. Nowe API jest bezpieczniejsze i prostsze w użyciu, z pewnością więc warto jest nim zastąpić poprzednie implementacje. Na koniec kilka dobrych praktyk, które mogą Ci się przydać przy pracy z datami i czasem:

• Unikaj używania konstrukcji daty i czasu, które są zbyt szczegółowe lub zbyt ogólne
• Nie polegaj na systemowej strefie czasowej lub tej ustawionej w bazie danych
• Używaj Clock w celu konfiguracji źródła, na podstawie którego czas będzie pobierany
• Staraj się używać formatu w standardzie ISO-8601 w API, które oferujesz
• Używaj ZonedDateTime jeśli musisz uwzględniać strefy czasowe i zmiany czasu
• Używaj Instant jeśli chcesz zapisać czas wystąpienia jakiegoś zdarzenia jako punkt na osi czasu
• Przechowuj czas w UTC i konwertuj na czas lokalny po stronie frontendu jeżeli musisz wyświetlać daty z uwzględnieniem różnych stref czasowych
• Unikaj używania legacy date-time API w Java na rzecz nowego API
• Pamiętaj o walidacji pól wpisywanych przez użytkownika
• Pamiętaj o testach jednostkowych szczególnie przypadków brzegowych tj.
  - początek/koniec miesiąca/roku
  - dni powszednie i weekendy
  - 29 lutego
  - strefy czasowe, czas letni

Po więcej szczegółowych informacji zachęcam do przejrzenia dokumentacji a także do zerknięcia na świetną prezentację autorstwa Tomasza Nurkiewicza. A tymczasem zostawiam Cię z utworem i do następnego 👋

W tym artykule chciałbym przedstawić wam najbardziej obiecujący Framework do tworzenia multiplatformowych aplikacji. Rozpocznę od nakreślenia czym w ogóle jest Flutter skąd się wziął i dlaczego w bardzo krótkim czasie zyskał taką popularność.

Flutter rozpoczął swoje istnienie w 2015 roku kiedy to na konferencji Dart Developer Summit firma Google zaprezentowała nowy projekt, początkowo pod nazwą „Sky”. Na pierwszą wersję przyszło nam nieco poczekać, wersja alfa była dostępna od maja 2017 roku. Następnie upłynął nieco ponad rok i we wrześniu 2018 roku udostępniono wersję beta. Pierwszą wersję stabilną otrzymaliśmy 4 grudnia 2018 podczas Flutter Live Event. W chwili pisania tego artykułu najnowsza dostępna wersja ma numer 3.0.1.

Co to jest Flutter?

Najłatwiej jest go zdefiniować jako zestaw narzędzi do tworzenia natywnych aplikacji webowych, desktopowych oraz wbudowanych. Tutaj warto podkreślić, że nie ma potrzeby rozdzielania kodu na poszczególne wersje, wystarczy jedna aby cieszyć się mobilną aplikacją oraz to samo zobaczyć w przeglądarce internetowej. Flutter to framework typu open-source dzięki czemu mamy dostęp do ogromnej liczby pakietów, które bardzo często są gotowym do użycia rozwiązaniem naszych problemów.

Cechy

Czymże byłby dobry Framework bez szeregu funkcjonalności/cech/atrybutów, które ułatwią nam pracę. Do najważniejszych zaliczyłbym:

• Multiplatformowość - piszesz kod raz i odpalasz „wszędzie”
• Szybki development - dzięki temu, że kod zapisujemy w obiektowym języku Dart, który wykorzystuje strategię JIT
• Widgety - zarówno te, które napiszemy jak i te dostępne w bazie, to szybki sposób na rozwijanie aplikacji
• Hot reload - zmiany widoczne od razu po zapisaniu fragmentu kodu, bez konieczności przebudowywania czy przeładowywania aplikacji. Są od tego oczywiście wyjątki dla przykładu zmiany w serwisach mogą wymagać przeładowania (hot restart)
• Dostęp do natywnych funkcji i SDK platformy - gwarantuje to szybkie tworzenie funkcjonalności przy użyciu wbudowanych funkcji Flutter’a jak również mamy możliwość sięgnięcia do SDK platformy, na którą aktualnie tworzymy aplikację. Pierwszym z brzegu przykładem może być konfiguracja powiadomień typu push dla Android i iOS wykorzystując ich domyślne rozwiązania
• Funkcjonalności nie opierają się na WebView - WebView można w skrócie zdefiniować jako zwykłą stronę Web pozbawioną interfejsu przeglądarki. Obecnie istotne jest aby unikać tego podejścia przy tworzeniu rozwiązań mobilnych ponieważ firmy takie jak Apple blokują aplikacje oparte na WebView w swoich sklepach. Flutter tworzy kod natywny, który jest przez jego silnik obsługiwany, dzięki czemu aplikacje wyświetlają się płynnie w 60 klatkach na sekundę.

Wszystko jest Widgetem

Wszystko co widzimy w naszej aplikacji napisanej w frameworku Flutter jest określane jako widget. Aplikacje tworzymy z gotowych widgetów, co można porównać do układania domku z klocków. Strukturę dziedziczenia widgetów przedstawia powyższy wykres.

Stateful

• dynamiczny widget posiadający swoje właściwości znane pod nazwą state
• setState() jest metodą używaną do aktualizacji stanu
• widget może być przerysowany wielokrotnie podczas działania aplikacji
• widgety są mutowalne, używamy ich gdy treść zmienia się dynamicznie
• z widgetem stanowym związany jest cykl życia, który zaczyna się od metody createState a kończy na dispose

Stateless

• niemutowalne widgety nieposiadające stanu i nie zmieniające swojego stanu podczas działania aplikacji
• metoda build() wywoływana jest tylko raz
• przykładem jest widget Icon, IconButton czy Text

Jestem przekonany, że w swoich aplikacjach znajdziecie największą liczbę widgetów o nazwie Container, zaraz po nim będą plasowały się takie podstawowe struktury jak Text, Row, Column, Image, Icon. Wszystko to zacznie się od skromnego Scaffold, który jest szkieletem, dającym możliwość skorzystania z takiej struktury jak appBary, bottomBary czy backButtony.

Podział widgetów

Zdecydowana większość widgetów należy do grupy generycznych, tych które udostępnia nam Framework. Oznacza to, że niezależnie od platformy będą wyglądały i zachowywały się tak samo. Znajdą się jednak też takie, które będą dostępne tylko dla danej platformy jak również w całym tym bogactwie znajdziemy te, które w zależności od platformy będą prezentowały się inaczej. Przykładem jest widget wyboru daty i czasu.

Podobieństwa do HTML

Zastanawiasz się zapewne czy stworzenie własnego widgetu jest trudne. Otóż dla osób zaznajomionych ze składnią języka HTML nie powinno to stanowić większego problemu. Poniżej przedstawiam fragment kodu porównujący składnię HTML z składnią Flutter’a.

Oczywiście podobnych lub takich samych tagów jest znacznie więcej. Znajome bez wątpienia będą Row, Column, ScrollView i wiele innych.

Przydatne pakiety

• get - pakiet, który łączy w sobie kilka funkcjonalności, zaczynając od najważniejszej - menadżera stanu przez wstrzykiwanie zależności po kontrolę przejść między stronami aplikacji. W ogromie funkcjonalności tego dodatku warto wspomnieć o takich możliwościach jak internacjonalizacja czy zmiana motywu aplikacji
• file_picker - pakiet, który pozwoli na korzystanie z natywnego eksploratora plików wraz z możliwością filtrowania. Pakiet pozwala także na wybieranie plików bezpośrednio z chmury
• rate_my_app - gdy chcemy umożliwić użytkownikom aplikacji jej ocenę warto sięgnąć po rate my app, oczywiście najlepiej w chwili gdy udało mu się pozytywnie przejść jakiś proces
• awesome_notifications - pakiet umożliwia odbieranie i tworzenie zaawansowanych powiadomień typu push notification

Trendy

Flutter na przełomie ostatnich 5 lat stale pnie się na szczyt listy popularności multiplatformowych narzędzi. Na pozycji lidera znajduje się już niekwestionowanie od 2 lat i nic nie wskazuje na to by jego popularność w najbliższej przyszłości miała się zmniejszyć.

Wady

Oczywiście jak każde gotowe narzędzie ma też swoje bolączki. Na szczęście tych nie ma dużo i właściwie to musiałem się długo zastanawiać by czymś zapełnić tę sekcję. Napisałem wyżej, że w frameworku Flutter na prawdę szybko wytwarza się oprogramowanie pod warunkiem, że znamy już język Dart. Puryści czy to od strony Androida czy to iOS mogą być zawiedzeni faktem, że dostęp do SDK natywnej platformy jest ograniczony.

Docker jest przydatnym narzędziem służącym do wirtualizacji na poziomie systemu operacyjnego. Oprogramowanie to pozwala na uruchamianie procesów aplikacji w "lekkich" kontenerach odizolowanych od systemu operacyjnego hosta. W pewnym sensie kontenery przypominają maszyny wirtualne jednak zakres izolacji obsługiwany przez dockera jest zdecydowanie mniejszy.

Kontenery w przeciwieństwie do maszyn wirtualnych korzystają z tego samego jądra a izolacja jest zaimplementowana w ramach tego pojedynczego jądra. Nazywamy to wirtualizacją systemu operacyjnego. Z kolei maszyny wirtualne są ciężkie i zasobożerne w porównaniu do kontenerów z uwagi na fakt, iż każda ich nowa instancja jest równoznaczna z nową instancją jądra.

Wymienione technologie tj. wirtualizacja i konteneryzacja są nieco odmienne w związku z tym ich zastosowanie będzie również nieco inne.

Maszyny wirtualne wykorzystamy gdy chcemy mieć pełną izolację od systemu operacyjnego hosta jak również mając potrzebę uruchomienia wielu różnych systemów operacyjnych na tym samym komputerze. Maszyny wirtualne z założenia zastępują rzeczywisty sprzęt, który można postawić w szafie na kilka lat. Ponieważ zastępują one prawdziwy serwer często z założenia są utrzymywane przez długi czas.

Kontenery wykorzystamy gdy chcemy uruchamiać nasze aplikacje w "lekkich opakowaniach" w sytuacjach gdy tworzenie kolejnej maszyny wirtualnej byłoby zbyt kosztowne. Przykładowo nie uruchomilibyśmy maszyny wirtualnej aby wystartować w niej pojedynczy proces np. curl albo ffmpeg w celu uzyskania wyniku ponieważ byłoby to bardzo czasochłonne i wymagałoby uruchomienia całego systemu operacyjnego w celu wykonania jednego polecenia. Kontenery natomiast idealnie nadają się do tego typu zastosowań a jedną z największych korzyści z ich zastosowania jest dobre wykorzystanie zasobów ponieważ nie jest potrzebny cały system operacyjny dla każdej wyizolowanej funkcji. Kontenery również znajdą zastosowanie do szybkiego stawiania lokalnych środowisk np. przy użyciu Docker Compose.

Jednak być może zastanawiasz się w jakim celu pakować swoje aplikacje w kontenery? Po co jest ta kolejna warstwa? Czemu nie instalować aplikacji bezpośrednio na serwerze? Przecież Java już wykonuje się na maszynie wirtualnej po co więc ta kolejna abstrakcja?

Jedną z najważniejszych silnych stron dockera jest jego zdolność do odseparowania aplikacji od sprzętu i systemu operacyjnego serwera, na którym działa dzięki czemu Twoja aplikacja nie jest przywiązana do żadnego konkretnego komputera czy środowiska. Z dockerem dostarczasz aplikację wraz ze wszystkimi plikami niezbędnymi do jej uruchomienia w postaci obrazu lub artefaktu, z którego później tworzone są działające kontenery. W celu wdrożenia aplikacji na dane środowisko nie musisz na nim instalować zależności czy też bibliotek, od których aplikacja zależy ponieważ wszystkie zależności są już w środku w obrazie. Pozwala to nie tylko horyzontalnie skalować aplikacje w prosty sposób używając różnych platform do orkiestracji np. Kubernetes lub Swarm, ale również uniknąć dziwnych błędów spowodowanych różnicami w konfiguracji między środowiskami ponieważ aplikacja nie zależy od zewnętrznego środowiska.

Architektura

W dużym uproszczeniu Docker składa się z trzech komponentów:

• docker - klient serwera czyli warstwa, z którą użytkownik końcowy ma największą styczność
• dockerd - serwer, demon działający w tle, który zarządza kontenerami i obsługuje żądania od klienta
• rejestry - repozytoria, z których Docker zaciąga obrazy np. Docker Hub

Warto wspomnieć, że proces dockerd można uruchomić natywnie tylko w systemie Linux. Jeżeli uruchamiamy Dockera w systemach Windows lub MacOS to wykorzystamy wirtualną maszynę z uruchomionym systemem Linux aby uruchomić dockerd - serwer Dockera.

Każdy kontener powstaje z obrazu podobnie jak wirtualny dysk staje się maszyną wirtualną po jej uruchomieniu. W pracy z Dockerem wykorzystujemy gotowe obrazy pobrane z zdalnego repozytorium lub tworzymy własne z wykorzystaniem pliku Dockerfile.

Plik Dockerfile

Plik, który opisuje wszystkie kroki niezbędne do wykonania aby utworzyć jeden obraz. Zazwyczaj powinien być umieszczony w głównym katalogu repozytorium aplikacji, którą chcemy umieścić w obrazie.

Poniżej przykładowy plik Dockerfile. W komentarzach zawarłem wyjaśnienia poszczególnych komend.

FROM java:8  			# obraz bazowy (składa się z wielu warstw tj. obrazów przejściowych)
COPY . /var/www/java    # kopiuje bieżący katalog do /var/www/java w kontenerze
WORKDIR /var/www/java   # ustawia katalog bieżący w kontenerze
RUN javac Hello.java    # uruchamia kompilację programu
CMD ["java", "Hello"]   # uruchamia program

Na podstawie tak przygotowanego pliku możemy spróbować zbudować obraz a następnie na jego podstawie uruchomić instancję kontenera.

❯ docker build . -t hello-java
[+] Building 15.4s (10/10) FINISHED
 => [internal] load build definition from Dockerfile                                                                 
 => [1/4] FROM docker.io/library/java:8@sha256:c1ff613e8ba25833d2e1940da0940c3824f03f802c449f3d1815a66b7f8c0e9d                                                 10.5s
 => => resolve docker.io/library/java:8@sha256:c1ff613e8ba25833d2e1940da0940c3824f03f802c449f3d1815a66b7f8c0e9d                                                  0.0s
 => => sha256:76610ec20bf5892e24cebd4153c7668284aa1d1151b7c3b0c7d50c579aa5ce75 42.50MB / 42.50MB                                                                 2.0s
...
 => [2/4] COPY . /var/www/java                                                                                                                                   0.1s
 => [3/4] WORKDIR /var/www/java                                                                                                                                  0.0s
 => [4/4] RUN javac Hello.java                                                                                                                                   2.8s
 => exporting to image                                                                                                                                           0.0s
 => => exporting layers                                                                                                                                          0.0s
 => => writing image sha256:e772e4db060862c73991141dc7dc57c7d86655ff2d1685954d865b5debc857c7                                                                     0.0s
 => => naming to docker.io/library/hello-java                                                                                                                    0.0s

❯ docker run hello-java
Hello world

Obraz dockerowy jest zbudowany z warstw nakładających się na siebie. Każda komenda w pliku Dockerfile dodaje kolejną warstwę. Podczas tego procesu docker uruchamia kontener na bazie obrazu z warstwy niżej następnie wykonuje zadaną operację po czym zapisuje stan systemu plików jako nowy obraz. Ze względu na to, że Docker cache'uje powstałe warstwy aby przyśpieszyć budowanie obrazu, jeżeli dokonamy zmian w pliku Dockerfile  i przebudujemy obraz Docker przebuduje tylko te warstwy (obrazy pośrednie), które się zmieniły i wyższe ponieważ wyższe bazują na niższych więc zmiana tych niższych mogła wpłynąć na wyższe warstwy. Z tego względu dobrą praktyką jest umieszczanie jak najniżej pliku poleceń bazujących na zasobach, które często się zmieniają.

Uruchamianie obrazów

Jak widzieliśmy na przykładzie wyżej obrazy uruchamiamy z wykorzystaniem komendy docker run <image>. W ten sposób Docker utworzył na jego podstawie nowy kontener przypisując mu unikalny identyfikator. Za każdym razem gdy uruchomimy docker run stworzymy nową instancję kontenera podobnie jak tworzymy nową instancję klasy za pomocą operatora new w programowaniu obiektowym. Możemy wykonać kilka prostych komend aby przekonać się, że faktycznie tak się dzieje. W tym celu posłużę się obrazem Ubuntu.

❯ docker run ubuntu:latest whoami
root
❯ docker run ubuntu:latest uname -a
Linux 2c410a1519fb 5.10.104-linuxkit #1 SMP PREEMPT Thu Mar 17 17:05:54 UTC 2022 aarch64 aarch64 aarch64 GNU/Linux
❯ docker ps -a | head -3
CONTAINER ID   IMAGE            COMMAND                  CREATED              STATUS                          PORTS                               NAMES
2c410a1519fb   ubuntu:latest    "uname -a"               17 seconds ago       Exited (0) 16 seconds ago                                           distracted_napier
89f9a750d6e2   ubuntu:latest    "whoami"                 26 seconds ago       Exited (0) 25 seconds ago                                           nostalgic_yalow

Powyższy test potwierdza, że wykonanie dwóch poleceń używając komendy docker run faktycznie spowodowało stworzenie dwóch różnych kontenerów z unikalnymi identyfikatorami, które zakończyły się po wykonaniu tych poleceń.

Czas życia kontenera jest zdefiniowany przez proces, który jest uruchomiony w środku. Jeżeli proces, który "podtrzymuje" kontener zakończy działanie kontener również się zakończy. Możemy zobaczyć to zachowanie w praktyce używając komendy sleep.

❯ docker run ubuntu:latest sleep 5

Nowa instancja kontenera została stworzona po czym wystartował proces sleep, który zamroził konsolę na 5 sekund następnie proces ten zakończył swoje działanie a zaraz po nim kontener. Zakończony kontener zobaczymy wykonując poniższą komendę, która listuje wszystkie kontenery w systemie.

❯ docker ps -a

CONTAINER ID   IMAGE            COMMAND                  CREATED              STATUS                          PORTS                               NAMES
4f6d73900753   ubuntu:latest    "sleep 5"                13 seconds ago       Exited (0) 7 seconds ago

Nie musimy za każdym razem tworzyć nowej instancji kontenera. Możemy wykorzystać polecenie docker start aby wystartować istniejący zakończony kontener i docker attach aby się do niego podłączyć i obserwować standardowe wyjście procesu, który jest uruchomiony.

❯ docker start 4f6d73900753
❯ docker attach 4f6d73900753

Uruchomiony działający w tle kontener możemy również w prosty sposób zrestartować.

❯ docker restart 4f6d73900753

Uruchamianie kontenera w tle

Podając parametr -d możemy uruchomić kontener w tle:

❯ docker run -d ubuntu:latest sh -c "while true; do date; sleep 1; done"

Następnie możemy się do niego podłączyć i obserwować standardowe wyjście:

❯ docker attach 4e8c73d5487a
Tue May 24 11:50:44 UTC 2022
Tue May 24 11:50:45 UTC 2022
Tue May 24 11:50:46 UTC 2022
...

Aby zakończyć sesje z kontenerem możemy uruchomić ctrl + c jednak to zastopuje kontener. Jeżeli chcemy tego uniknąć możemy podłączyć się do kontenera z opcją --sig-proxy=false.

❯ docker attach --sig-proxy=false 4e8c73d5487a
Tue May 24 11:50:44 UTC 2022
Tue May 24 11:50:45 UTC 2022
Tue May 24 11:50:46 UTC 2022
...

Po czym gdy uruchomimy ctrl + c kontener dalej będzie działał w tle. Natomiast w celu samego obserwowania logów lepszym pomysłem będzie komenda docker logs omówiona później.

Przekazanie zmiennych środowiskowych podczas uruchamiania kontenera

Dobrą praktyką jest aby nie przechowywać haseł czy też innych danych wrażliwych w obrazach. Zamiast tego lepiej je wstrzykiwać do kontenera podczas jego uruchamiania w następujący sposób.

❯ docker run -d -e APP_ENV=production -e APP_SECRET=DACFC787 myapp:latest

Usuwanie kontenerów

Domyślnie zakończone kontenery nie są usuwane przez Dockera. Jeżeli chcemy uruchomić w kontenerze tylko jedno polecenie i po jego zakończeniu pozbyć się kontenera bez konieczności usuwania go ręcznie możemy skorzystać z opcji --rm.

❯ docker run --rm ubuntu:latest ls -la

Usunięcie kontenera, który działa w tle wygląda następująco.

❯ docker stop 4e8c73d5487a && docker rm 4e8c73d5487a

Tryb interaktywny

Z poprzednich rozważań dowiedzieliśmy się, że kontener dockera zakończy się jeżeli nie będzie procesu, który będzie go "podtrzymywał". Jeżeli jednak mamy potrzebę podłączyć się do konsoli w celu eksploracji systemu plików (przydaje się podczas debugowania) możemy to osiągnąć uruchamiając kontener w trybie interaktywnym w następujący sposób.

❯ docker run -it ubuntu:latest /bin/bash

lub

❯ docker run -it --entrypoint /bin/bash ubuntu:latest

Jeżeli chcemy podłączyć się do już istniejącego kontenera w sposób interaktywny możemy wykorzystać polecenie docker exec.

❯ docker exec -it 4e8c73d5487a /bin/bash

Tworzenie obrazu na podstawie istniejącego kontenera

W trybie interaktywnym, który był poruszony w poprzedniej sekcji możemy bez problemu dokonać dowolnych zmian np. zmienić konfigurację czy też zainstalować potrzebne nam pakiety i zależności. Mamy możliwość niejako zapisania tych zmian tworząc nowy obraz na podstawie zmian, których dokonaliśmy.

❯ docker commit 4e8c73d5487a testimage:1.0

Jednak lepszym i rekomendowanym sposobem na tworzenie obrazów jest plik Dockerfile omówiony wcześniej.

Wyeksportowanie systemu plików kontenera

Wykorzystując polecenie docker export możemy w prosty sposób "zrzucić" aktualny stan systemu plików kontenera np. w celu jego eksploracji w wygodnym dla nas narzędziu i debugowania.

❯ docker export 4e8c73d5487a -o exported.tar
❯ tar -tvf exported.tar | head
-rwxr-xr-x  0 0      0           0 May 24 13:50 .dockerenv
lrwxrwxrwx  0 0      0           0 Apr 28 13:55 bin -> usr/bin
drwxr-xr-x  0 0      0           0 Apr 18 12:28 boot/
drwxr-xr-x  0 0      0           0 May 24 13:50 dev/
-rwxr-xr-x  0 0      0           0 May 24 13:50 dev/console
drwxr-xr-x  0 0      0           0 May 24 13:50 dev/pts/
drwxr-xr-x  0 0      0           0 May 24 13:50 dev/shm/
drwxr-xr-x  0 0      0           0 May 24 13:50 etc/
-rw-------  0 0      0           0 Apr 28 13:56 etc/.pwd.lock
-rw-r--r--  0 0      0        3028 Apr 28 13:56 etc/adduser.conf

Tworzenie archiwum tar z obrazem

Możesz spotkać się z sytuacją, że maszyna, na której chcesz uruchomić obraz nie ma dostępu do internetu w związku z tym nie będzie w stanie pobrać tego obrazu z zdalnego repozytorium obrazów. Z pomocą przychodzi polecenie docker save, które wyeksportuje nam obraz do archiwum tar.

❯ docker save -o ubuntu:latest.tar ubuntu:latest

Następnie przenosimy archiwum na drugą maszynę z zainstalowanym dockerem i ładujemy wykorzystując polecenie docker load.

❯ docker load -i ubuntu:latest.tar 

CMD vs ENTRYPOINT

W sekcji dot. pliku Dockerfile użyliśmy następującej komendy.

CMD ["java", "Hello"]

Powyższe polecenie jest informacją dla Dockera jaki proces a w zasadzie polecenie chcemy uruchomić wewnątrz kontenera gdy ten startuje. Podczas gdy uruchomiliśmy kontener używając polecenia docker run java-hello Docker uruchomił polecenie wskazane przez nas w CMD tj. java. Możemy również napisać polecenie jakie ma być wykonane gdy startujemy kontener.

❯ docker run java-hello ls -la

Przekazując polecenie podczas uruchamiania kontenera nadpisaliśmy te domyślnie, które zapisaliśmy w pliku Dockerfile na samym końcu. W tym momencie zamiast programu w Java na standardowe wejście zostanie wylistowany bieżący katalog.

Polecenie ENTRYPOINT jest w pewnym sensie podobne do CMD. Domyślnie ENTRYPOINT jest ustawiony na wartość sh -c jednak można zmienić tę wartość. CMD nie ma domyślnej wartości więc trzeba ją wskazać. Podając w CMD wartość ls -la tak naprawdę Docker najpierw patrzy na zmienną ENTRYPOINT i domyślnie uruchamia proces powłoki sh -c a jako parametr podaje polecenie podane w CMD. W efekcie wykonywane jest polecenie sh -c ls -la . Dlatego upraszczając można powiedzieć, że wartości podane w CMD są argumentami dla programu wskazanego w ENTRYPOINT, który zostanie uruchomiony. Warto zmienić domyślną wartość dla ENTRYPOINT na proces aplikacji, który chcemy docelowo uruchomić w kontenerze gdyż uruchamianie dodatkowo powłoki raczej nie ma większego zastosowania chyba, że aplikację startujemy skryptem powłoki.

Przekierowanie standardowych strumieni kontenera

Warto wiedzieć, że Docker mapuje na zewnątrz standardowe strumienie tj. STDOUT i STDERR a także kody wyjściowe procesu uruchomionego w kontenerze.

❯ docker run --rm ubuntu:latest cat /etc/passwd > pass
❯ echo $?
0

Może mieć to szerokie zastosowanie w aplikacjach, które dynamicznie uruchamiają kontenery na żądanie użytkownika i zaczytują rezultat z STDOUT. Uruchamianie poleceń bezpośrednio na serwerze nie byłoby dobrym pomysłem z punktu widzenia bezpieczeństwa natomiast wykonanie tego w kontenerze jest zdecydowanie lepszym rozwiązaniem ponieważ dzięki izolacji polecenie w żaden sposób nie zaszkodzi środowisku wykonawczemu hosta.

Logi

W celu pobrania wszystkich logów z kontenera wykonujemy następującą komendę przekazując w parametrze identyfikator kontenera.

❯ docker logs 4e8c73d5487a

Aby widzieć logi w trybie śledzącym używamy parametru -f

❯ docker logs -f 4e8c73d5487a

Mamy również możliwość filtrowania logów w różny sposób.

❯ docker logs --since=1h 4e8c73d5487a // logi z ostatniej godziny
❯ docker logs --since=3m -f 4e8c73d5487a // logi z ostatnich 3 minut w trybie śledzącym
❯ docker logs --tail=20 -f 4e8c73d5487a // ostatnie 20 linni w trybie śledzącym

Woluminy

Różne aplikacje często zapisują stan do systemu plików. Aby mieć dostęp do danych aplikacji i zachować stan pomiędzy restartowaniem kontenera (np. aktualizacja aplikacji do nowej wersji) możemy użyć woluminów. Dzięki nim mamy możliwość zmapowania katalogu hosta i zamontowania go pod kontener dockera. W celu definicji woluminu dla kontenera możemy użyć parametru -v.

❯ docker run -v $(pwd):/tmp/test --rm ubuntu:latest bash -c "echo 'Hello' > /tmp/test/file.txt"
❯ cat file.txt
Hello

Dlaczego nie możemy zdefiniować tego mapowania w pliku Dockerfile? Ponieważ plik Dockerfile zawiera tylko komendy dot. docelowego obrazu odpowiedzialne za poprawne zbudowanie tego obrazu. Zewnętrzne zasoby, mapowania systemu plików, portów itd. są elementami na styku obrazu i środowiska, na którym ten obraz chcemy wdrożyć i uruchomić w postaci kontenera. Z pewnością nie chcemy aby nasz obraz mocno zależał od tego środowiska.

Podłączanie się do usług hosta wewnątrz kontenera

W przypadku gdy mamy na hoście zainstalowaną jakąś usługę np. mysql połączenie się z nią w środku kontenera używając localhost:3306 nie zadziała. Zamiast tego możemy użyć specjalnej nazwy domenowej host.docker.internal:3306.

.dockerignore

Plik .dockerignore pełni podobną rolę co .gitignore w systemie kontroli wersji. Umieszczamy go obok pliku Dockerfile. Plik ten zawiera zestaw reguł, które informują Dockera, które pliki i katalogi powinien wykluczyć z build kontekstu. Często możemy spotkać się z kopiowaniem do kontenera całego katalogu z kodem aplikacji w następujący sposób.

COPY . /var/www/html

W naszym repozytorium aplikacji może być wiele różnych plików, które niekoniecznie są potrzebne w obrazie wynikowym np. pliki zawierające hasła i inne wrażliwe dane lub pliki tymczasowe. Dzięki .dockerignore możemy je wykluczyć. Dzięki temu nie tylko zmniejszymy rozmiar obrazu ale również przyśpieszymy jego budowanie ze względu na cache invalidation. Każde polecenie COPY czy też ADD tworzy nową warstwę obrazu. Jeżeli pliki, w którego kontekście COPY jest wykonywane uległy modyfikacji co często się zdarza np. pliki z logami, warstwa będzie musiała zostać przebudowana. Wydłuży to proces budowania obrazu dlatego warto wykluczyć tego typu pliki w .dockerignore. Poniżej przykładowy plik .dockerignore.

.git
.cache
*.md
**/*.class
passwords.txt
logs/

Dobre praktyki podczas używania Dockera

Nie używaj tagu latest w środowisku produkcyjnym
Tag latest jest wygodny w użytkowaniu jednak nie sprawdza się w dłuższym horyzoncie czasowym. Gdy korzystasz z tagu latest Twoje wdrożenia nie są powtarzalne ponieważ wersja obrazu jest dynamiczna i może się zmieniać. Może to łatwo doprowadzić do sytuacji gdy nie masz tej samej wersji aplikacji uruchomionej na wszystkich serwerach.

Używaj zmiennych środowiskowych w celu konfiguracji aplikacji
Dzięki umieszczeniu informacji konfiguracyjnych poza repozytorium kodu źródłowego bardzo proste jest uruchamianie dokładnie tego samego kontenera w różnych środowiskach bez wprowadzania zmian w repozytorium a co istotne w repozytorium nie zostają zapisane dane wrażliwe. Co ważniejsze pozwala to na dokładniejsze przetestowanie kontenerów przed wdrożeniem ich na środowisko produkcyjne ponieważ ten sam obraz jest używany we wszystkich środowiskach.

Unikaj przechowywania stanu w kontenerach
Aplikacje zamykane w kontenerach powinny być traktowane jako efemeryczne tzn. mogą łatwo się pojawiać, restartować lub znikać. Jeżeli taki kontener zapisuje stan do swojego systemu plików np. sesję http proces aktualizacji aplikacji do nowej wersji spowoduje usunięcie wszystkich danych z lokalnego stanu aplikacji. Dlatego jeśli to możliwe preferowane jest pisanie aplikacji, które nie muszą przechowywać informacji o stanie dłużej niż przez czas potrzebny na przetworzenie pojedynczego zapytania i udzielenie odpowiedzi. Dzięki temu zatrzymanie któregokolwiek kontenera aplikacji w minimalny sposób wpływa na jego działanie. Gdy trzeba zachować informacje na temat stanu najlepszym podejściem jest użycie zewnętrznego magazynu danych np. Redis, PostgreSQL itp.

Nie używaj użytkownika root
Nie jest dobry pomysłem uruchamianie procesu kontenera z UID=0. W takiej sytuacji każda luka bezpieczeństwa pozwalająca na ominięcie ograniczenia przestrzeni nazw (mechanizm izolacji, który jest wykorzystywany przez dockera) spowoduje, że w systemie będzie działał proces ze wszystkimi uprawnieniami. Aby uruchomić cały kontener z innymi uprawnieniami niż root możesz skorzystać z przełącznika -u np. docker run -d -u 500 my-java-app:1.0.

Z tego artykułu dowiesz się jak w prosty sposób bez kodowania możesz dodać na swoją stronę w miarę przyzwoity album z zdjęciami. Efekt końcowy możesz zobaczyć tutaj. Na końcu artykułu znajdziesz linka do githuba z prostym plikiem html, który możesz wykorzystać na swojej stronie.

Jakiś czas temu pomyślałem, że fajnie byłoby mieć na stronie galerię w postaci albumów z zdjęciami w dobrej jakości, do których miałbym łatwy dostęp z dowolnego urządzenia w postaci prostego linka, który mógłbym wpisać w pasku przeglądarki lub podesłać go komuś innemu. Jednym zdaniem mówiąc wszystko w jednym miejscu.

Zacząłem zastanawiać się jakich technologii mógłbym użyć aby zrealizować to co przyszło mi do głowy. Postanowiłem, że rozwiązanie ma być relatywnie jak najprostsze bez kodowania po stronie serwera. Chciałem również uniknąć serwowania zdjęć z serwera, na którym działa moja strona aby odciążyć serwer i zaoszczędzić miejsce a tym samym uniknąć zbędnych kosztów. Poza tym nie od dziś wiemy, że statyczny kontent lepiej serwować z oddzielnej domeny (cookie-less-domain).

Postanowiłem, że skorzystam z gotowych rozwiązań w chmurze tj. Dropbox lub Google Photos. Natomiast pojawił się problem z tymi usługami gdyż nie udostępniają one możliwości wyeksportowania kodu i zamieszczenia treści na stronie w postaci fajnie wyglądającej galerii zdjęć, przynajmniej nie w takiej postaci w jakiej bym oczekiwał. Kolejna rzecz to API tych usług wymaga uwierzytelniania, mimo że chciałem pobierać informacje tylko o publicznie dostępnych albumach/folderach. Wiązałoby się to z zaimplementowaniem autoryzacji po stronie serwera czego chciałem uniknąć. Zależało mi na prostocie rozwiązania.

Ostatecznie padło na google photos gdyż znalazłem ciekawe narzędzie, które po podaniu linka do publicznego albumu z google photos "eksportuje" nam ten album i generuje gotowy kod HTML do umieszczenia na stronie. Przykładowy kod wygenerowany przez wspomniane narzędzie:

<script src="https://cdn.jsdelivr.net/npm/publicalbum@latest/embed-ui.min.js" async></script>
<div class="pa-gallery-player-widget" style="width:100%; height:480px; display:none;"
  data-link="https://photos.app.goo.gl/CSV7NDstShTUwUZq5"
  data-title="Mr. Monstro"
  data-description="4 new items · Album by Pavel M.">
  <object data="https://lh3.googleusercontent.com/XlH6wo2PzrAEqmplYrZwV0fI-2TafTT6BRwZhKDfZSHd_zT7HIdPyPWd3Xuqhn1QQADuTJ32QFmcgYiTOEU0sC4Bvf-VyTIiq-DxxEaxIeWDYyUK_VjaW8-zrMGBvekDZT77lpduYQ=w1920-h1080"></object>
  <object data="https://lh3.googleusercontent.com/VvK__Vx8kpPTP57WZPLblacZbTE0NqWeIGTyHSQ8Rq9pvOpWQG_CQE_tOc6jHPtj02XIBYa0Zo9fWbXXQyNYs9hDGGj34QibKFJky4W9nYBpSb57OwxiQoDyo25vzIXMTN2SNxuzqg=w1920-h1080"></object>
  <object data="https://lh3.googleusercontent.com/HISe-DV_b4gjLvSEGzrJlsqBU2rSE8uQpSqHHKTPihg_Ax9VtfCrOrvdXF01raBeBleAWQKI7Hfb4_w9vZeJKFymQfNTlubwXxTBTbqGTPwjg7S0CBtQsQJqsspvIhD9c-pniSZrEw=w1920-h1080"></object>
  <object data="https://lh3.googleusercontent.com/05lhR1IAQY_B9rdQ_GvHDNLe1lJsSPyyuDeIMkt--gDDAnO2_EATwif7-sfNd2K_48RvyqKmN-u2svKZ06yfh8bnrbQ5kBUrIHfZvWheTzDGhIeFd1roPor-F_BycJmVKbQO6a9EaA=w1920-h1080"></object>
</div>

Jednak to narzędzie nie do końca spełniło moje oczekiwania. Wygenerowany widget, który wyświetla zdjęcia nie do końca trafia w moje gusta. Kolejna rzecz to adresy do zdjęć są na sztywno zahardkodowane w kodzie. W przypadku aktualizacji albumu w google photos nowe zdjęcia nie będą widoczne na stronie. Musiałbym jeszcze raz wygenerować kod z wykorzystaniem tego narzędzia i zaktualizować stronę co byłoby uciążliwe. Chciałem osiągnąć efekt, w którym dodając zdjęcia do albumu na google photos automatycznie będą widoczne na stronie.

W związku z tym postanowiłem zautomatyzować to narzędzie. Na początku odpaliłem Burpa aby sprawdzić jaki endpoint jest wykorzystywany pod spodem. Okazało się, że jest wywoływany następujący endpoint:

POST https://www.publicalbum.org/api/v2/webapp/embed-player/jsonrpc

W ciele żądania jest m.in. link do publicznego albumu, który podałem narzędziu. W odpowiedzi otrzymuję m.in. takie dane jak nazwa albumu jak również listę linków do zdjęć w tym albumie. Zakładam, że pod spodem narzędzie wykorzystuje metodę web scrappingu (jeżeli masz pomysł jak to może być zrealizowane daj znać w komentarzu).

Postanowiłem więc skorzystać z tego API i wywoływać je dla każdego publicznego albumu, który chcę wyświetlić na stronie za każdym razem gdy galeria zdjęć jest ładowana. Dzięki temu zdjęcia wyświetlane na stronie będą zawsze "zsynchronizowane" z tymi w chmurze. Poniżej kod, który napisałem aby pobrać dane i wyrenderować galerię:

function fetchAlbum(albumId) {
    const payload = {
        method: 'getGooglePhotosAlbum',
        params: {
            sharedLink: GOOGLE_PHOTOS_URL + '/' + albumId,
            imageWidth: IMAGE_WIDTH,
            imageHeight: IMAGE_HEIGHT,
            includeThumbnails: true,
            videoQuality: '1080p',
            attachMetadata: false
        },
        id: 1
    };
    return fetch('/google-photo-album', {
        method: 'POST',
        body: JSON.stringify(payload),
        headers: {
            'Content-Type': 'text/plain;charset=UTF-8',
            'Accept': 'application/json'
        }
    })
        .then(response => response.json())
        .then(response => response["result"]);
}

$(document).ready(function () {
    (async () => {
        const items = [];
        for (const albumId of GOOGLE_ALBUM_IDS) {
            const album = await fetchAlbum(albumId);
            const title = album.title;
            album.mediaItems.forEach((mediaItem, i) => {
                if (i === 0) {
                    const item = {
                        ID: albumId,
                        src: mediaItem.url,
                        srct: mediaItem.url.split('=')[0] + `=w${THUMBNAIL_L1_WIDTH}-h${THUMBNAIL_L1_HEIGHT}`,
                        kind: 'album',
                        title: title
                    };
                    items.push(item);
                }
                const item = {
                    ID: mediaItem.id,
                    albumID: albumId,
                    src: mediaItem.url,
                    srct: mediaItem.url.split('=')[0] + `=w${THUMBNAIL_WIDTH}-h${THUMBNAIL_HEIGHT}`
                };
                items.push(item);
            });
        }
        return items;
    })().then(items => renderGallery(items));

Stała GOOGLE_ALBUM_IDS jest tablicą, która przechowuje identyfikatory publicznych albumów z google photos. Jeżeli chcesz wyświetlić swoje albumy po prostu wrzuć do tablicy odpowiednie identyfikatory.

Endpoint /google-photo-album jest usługą wystawioną przeze mnie, która tylko przekierowuje do docelowego API przy okazji podmieniając nagłówek Referer. Poniżej konfiguracja nginx:

location /google-photo-album {
        proxy_set_header        Referer https://www.publicalbum.org/blog/embedding-google-photos-albums;
        proxy_pass              https://www.publicalbum.org/api/v2/webapp/embed-player/jsonrpc;
}

Za renderowanie galerii odpowiedzialna jest biblioteka nanoGallery2, która spełnia moje oczekiwania. Udostępnia ciekawy, nowoczesny i interaktywny styl i dobrze sprawdza się na urządzeniach mobilnych.

Zaletą rozwiązania, które opisałem powyżej jest prostota. Wystarczy jeden plik HTML aby wyświetlić galerię w postaci albumów "zsynchronizowanych" z google photos dzięki pobieraniu danych z API przy każdym ładowaniu.

Na koniec warto wspomnieć o tym, że rozwiązanie nie jest idealne. Pierwszą wadą rozwiązania jest to, że jest uzależnione od zewnętrznego API. Jeżeli API się zmieni lub usługa zostanie wyłączona galeria się nie wyświetli. Kolejna wada (moim zdaniem bardziej istotna) to czas ładowania galerii. Im więcej albumów chcemy wyświetlić tym dłużej będziemy czekać ponieważ każdy album to oddzielne żądanie HTTP. Jeżeli masz pomysł jak to zoptymalizować lub lepiej zintegrować/zrealizować daj znać w komentarzu 😉.

Jeżeli ten artykuł był dla Ciebie wartościowy podziel się nim z innymi. A tymczasem zostawiam Ciebie z przydatnymi linkami i utworem, którego teraz słucham 😎.

Linki

Galeria: https://lsdev.pl/gallery/
Github: https://github.com/lukascode/photo-gallery/

Thunderbird jest jak dotąd moim ulubionym klientem pocztowym. Dzisiaj miałem okazję konfigurować tego klienta na nowym komputerze. O ile protokół IMAP zapewnia nam synchronizację poczty w tym prywatnych folderów z poziomu wielu urządzeń o tyle nie dotyczy to filtrów czyli pewnych reguł i akcji im towarzyszących, które są specyficzne dla konkretnego klienta.

Z uwagi na to, że mam skonfigurowanych dość sporo filtrów nie chciało mi się ich
ponownie ręcznie konfigurować.

Poniżej wyjaśnię jak w prosty sposób można je wyeksportować (przenieść).
W moim przypadku "przenosiłem się" z Linuksa na Maca.

Pierwszym krokiem jest odnalezienie lokalizacji plików, w których
Thunderbird przechowuje dane użytkownika tj. ustawienia, wiadomości
w tym także filtry. Lokalizacja może się różnić w zależności od
systemu operacyjnego.

W przypadku Linuksa dane składowane są w katalogu domowym
pod ścieżką ~/.thunderbird. W przypadku Maca powinna być to następująca
lokalizacja: ~/Library/Thunderbird. W obu przypadkach ~ wskazuje
na katalog domowy aktualnie zalogowanego użytkownika.

Thunderbird dla każdego konta przechowuję filtry w pliku o nazwie
msgFilterRules.dat. Wyszukam zatem na Linuksie pliku z filtrami, który mnie interesuje tj. ten, który zamierzam przenieść na Maca gdzie skonfigurowałem świeżo zainstalowanego klienta pocztowego tak aby nie konfigurować filtrów ręcznie.

$ find ~/.thunderbird/ -name msgFilterRules.dat

/home/lukasz/.thunderbird/npo5t3or.default-release/Mail/Local Folders/msgFilterRules.dat
/home/lukasz/.thunderbird/npo5t3or.default-release/ImapMail/pro2.mail.ovh.net/msgFilterRules.dat
/home/lukasz/.thunderbird/npo5t3or.default-release/ImapMail/imap.gmail.com/msgFilterRules.dat

W tym przypadku interesuje mnie konto na gmail w związku z tym kopiuję plik
z lokalizacji .../ImapMail/imap.gmail.com/msgFilterRules.dat i przerzucam na Maca.

Na Macu szukam analogicznej ścieżki.

find ~/Library/Thunderbird -iname msgFilterRules.dat

/Users/lukas/Library/Thunderbird/Profiles/okd5md7p.default-release/Mail/Local Folders/msgFilterRules.dat
/Users/lukas/Library/Thunderbird/Profiles/okd5md7p.default-release/ImapMail/imap.gmail.com/msgFilterRules.dat

Następnie kopiuję pobrany wcześniej plik do odpowiedniej lokalizacji nadpisując ten domyślny.

cp ~/Downloads/msgFilterRules.dat ./Profiles/okd5md7p.default-release/ImapMail/imap.gmail.com/

Następnie po zrestartowaniu Thunderbird filtry powinny zostać poprawnie dodane i widoczne w menedżerze filtrów.

Przez ostatnie miesiące brałem udział w wielu rozmowach rekrutacyjnych na stanowisko
Java Software Developera. Wiele z pytań, które się pojawiły lub pojawiały najczęściej, udało mi się zapamiętać i zapisać. Dzisiaj chciałbym podzielić się z Tobą tymi pytaniami.
Jeżeli właśnie przygotowujesz się do rozmów na podobne stanowisko mam nadzięję, że
poniższy zestaw pytań będzie dla Ciebie wartościowy a odpowiedzi, które przygotowałem w jakimś stopniu uzupełnią Twoją wiedzę.

Gratulacje dotrwałeś do końca! Jeżeli ten artykuł był dla Ciebie wartościowy podziel się nim z innymi

SOP (Same-Origin Policy) jest mechanizmem bezpieczeństwa przeglądarek internetowych
polegający na odizolowaniu od siebie zasobów różnego pochodzenia. Każdy zasób webowy ma źródło, z którego pochodzi tzw. origin. Jeden unikalny origin definiują jego 3 główne składowe tj. protokół, domena i port.

Przykładowo

http://api.example.com/app.js
http://api.example.com:8090/app.js
http://example.com/app.js
https://example.com/app.js

są różnymi originami mimo, że mogą wskazywać na ten sam zasób. Z drugiej strony

http://example.com/example1.html
http://example.com/example2.html

są różnymi zasobami jednak pochodzą z tego samego origin'a.

W praktyce pod jednym origin zwykle mamy aplikację webową
składającą się z wielu różnych zasobów aby jej funkcjonowanie było możliwe.

Przeglądarka implementując SOP w podstawowym zakresie zabezpiecza naszą aplikację
przed różnego rodzaju potencjalnym zagrożeniem ze strony bezpieczeństwa gdzie inna aplikacja np. stworzona przez atakującego mogłaby z wykorzystaniem AJAX wywoływać metody w imieniu użytkownika naszej aplikacji np. kupić produkt w sklepie uprzednio zmieniając adres wysyłki na atakującego czyli tzw. atak CSRF (Cross-site request forgery). Warto wspomnieć, że nie należy polegać jedynie na tym mechaniźmie i stosować różnego rodzaju zabezpiczenia po stronie serwera tj.  csrf token, walidacja origin, nagłówki access control i inne zabezpieczenia.

W celu przetestowania mechanizmu SOP wystarczy wejść na dowolną stronę np. google.com otworzyć narzędzia developerskie w zakładce Console i wysłać żądanie Ajaxowe na inny origin:

var req = new XMLHttpRequest();
req.open('GET', 'http://localhost:8081', false);
req.send();

Jak widać przeglądarka zablokowała możliwość odczytania / dostępu do odpowiedzi z uwagi na inny origin, z którego pobieramy zasób niż ten, w kontekście którego aktualnie się znajdujemy czyli google.com. Warto zaznaczyć, że przeglądarka jedynie zablokowała dostęp do odpowiedzi natomiast samo żądanie zostało wysłane poprawnie. Wynika to z faktu, że przeglądarka dzieli żądania na „proste” czyli np. wykonywane w kontekście img, iframe, style, form i „złożone” np. typu PUT, DELETE (więcej o różnicy tutaj).

Wiemy już dlaczego nie możemy polegać tylko na mechaniźmie SOP. Atakujący w łatwy sposób mógłby spreparować tzw. „proste” żądanie przygotowując np. odpowiedni
formularz, który automatycznie by został wysłany do serwera zmieniając stan systemu w niekontrolowany sposób.

Z uwagi na to, że SOP jest dość restrykcyjny ponieważ pozwala na dostęp do zasobów tylko z tego samego origin, CORS (Cross-Origin Resource Sharing) ma za zadanie zluzować tą sztywną politykę i umożliwić za pomocą odpowiedniej konfiguracji na bezproblemową komunikację pomiędzy różnymi origin'ami.

Przykładowo aby odblokować dostęp do odpowiedzi, która wcześniej była przyblokowana przez przeglądarkę możemy po stronie serwera w odpowiedzi ustawić nagłówek w taki sposób:

Access-Control-Allow-Origin: *

W ten sposób zapewnimy dostęp dla danego zasobu wszystkim aplikacjom (origins), które będą chciały uzyskać do niego dostęp. Zwykle powyższy nagłówek ustawiany jest w taki sposób dla zasobów statycznych dostępnych publicznie np. biblioteki javascriptowe. Jest to typowe dla sieci CDN:

$ curl -I https://cdnjs.cloudflare.com/ajax/libs/jquery/3.6.0/jquery.min.js

HTTP/2 200 
content-type: application/javascript; charset=utf-8
access-control-allow-origin: *
server: cloudflare
...

Przykładowa konfiguracja CORS w Springu

Może się zdarzyć tak, że aplikacja kliencka po stronie przeglądarki (np. Angular) będzie musiała komunikować się z api serwera w innym origin niż jest serwowana np. aplikacja napisana w Angular jest dostępna pod adresem https://example.com i komunikuje się z backendem poprzez https://api.example.com. Wiemy już, że są to dwa różne origin'y w związku z tym aby komunikacja przebiegła pomyślnie musimy w taki sposób skonfigurować backend aby zezwolić na taką komunikację.

Rozpoczniemy od zdefiniowania beana odpowiedzialnego za dostarczenie ww. konfiguracji:

import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import org.springframework.web.cors.CorsConfigurationSource;
import org.springframework.web.cors.UrlBasedCorsConfigurationSource;

import java.util.List;

@Configuration
@ConditionalOnProperty(prefix = "cors", name = "allowedOrigins")
public class CorsConfiguration {

    @Bean
    public CorsConfigurationSource corsConfigurationSource(
            @Value("${cors.allowedOrigins}") List allowedOrigins
    ) {
        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        org.springframework.web.cors.CorsConfiguration corsConfiguration = new org.springframework.web.cors.CorsConfiguration();
        corsConfiguration.setAllowedOrigins(allowedOrigins);
        corsConfiguration.addAllowedHeader("*");
        corsConfiguration.setAllowedMethods(List.of(
                HttpMethod.GET.name(),
                HttpMethod.HEAD.name(),
                HttpMethod.POST.name(),
                HttpMethod.PUT.name(),
                HttpMethod.DELETE.name()
        ));
        corsConfiguration.setMaxAge(3600L);
        source.registerCorsConfiguration("/**", corsConfiguration);
        return source;
    }
}

Następnie stworzymy adnotację pomocniczą, która zaimportuje nam ww. konfigurację.
Zakładam, że konfiguracja będzie w jednej z bibliotek wspólnych w związku z tym pozwoli to nam ją włączać w zależności od potrzeb dla modułów, które wystawiają api restowe.

import org.springframework.context.annotation.Import;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Import({CorsConfiguration.class})
public @interface EnableCorsConfiguration {
}

Po czym wykorzystamy ww. konfigurację:

import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.oauth2.config.annotation.web.configuration.EnableResourceServer;
import org.springframework.security.oauth2.config.annotation.web.configuration.ResourceServerConfigurerAdapter;

@Configuration
@EnableResourceServer
@EnableCorsConfiguration
public class ExampleSecurityConfiguration extends ResourceServerConfigurerAdapter {
    
    @Value("${oauth.resourceId}")
    private String resourceId;

    @Override
    public void configure(HttpSecurity http) throws Exception {
        http.requestMatchers().antMatchers("/**")
                    .anyRequest().authenticated().and().cors();
    }
    
    @Override
    public void configure(ResourceServerSecurityConfigurer resources) throws Exception {
        resources.resourceId(resourceId);
    }
}

Na koniec w pliku application.yaml zdefiniujemy na jakie origin'y zezwalamy:

cors:
  allowedOrigins: https://example.com

Od teraz aplikacja kliencka bez problemu powinna komunikować się z backendem.

Warto wspomnieć, że jeżeli przed naszymi aplikacjami backendowymi w Java stoi jakiś reverse proxy np. Nginx tam również byłaby możliwa konfiguracja poprzez manipulację nagłówkami.

Na koniec warto zastanowić się czy architektura, w której API mamy na oddzielnej domenie faktycznie ma sens. Przeniesienie go na główną domenę może zredukować liczbę wykonywanych żądań nawet o połowę (z uwagi na Preflight Requests) co na pewno odciąży nasz serwer.