Home / internal / azure / hermes-agent-a-dotnet10-na-aks-pruvodce.md

AKS průvodce: Hermes Agent v Dockeru a vlastní .NET 10 aplikace v Dockeru

Praktický interní návod navazující na průzkum Docker v Azure pro PensionPlanner.

Cíl: - Scénář 1: provozovat Hermes Agenta v Dockeru na AKS - Scénář 2: provozovat vlastní .NET 10 aplikaci v Dockeru na AKS - mít klikací postup v Azure Portalu krok za krokem

1. Kdy dává AKS smysl

AKS je vhodné, když chceš: - provozovat víc kontejnerových služeb - mít oddělené prostředí dev / test / prod - řešit škálování, rolling update, health checky a ingress standardně přes Kubernetes - do budoucna přidat další workloady, cron joby, worker kontejnery nebo interní služby

AKS nedává smysl, pokud chceš jen jednu jednoduchou webovou appku a nechceš spravovat Kubernetes provoz. V takovém případě bývá jednodušší Azure Container Apps nebo App Service for Containers.

2. Co budeš v Azure potřebovat

Minimum pro oba scénáře: - Resource Group - Azure Container Registry (ACR) - Azure Kubernetes Service (AKS) - Log Analytics Workspace - veřejný vstup do clusteru přes Ingress - DNS záznam a volitelně TLS certifikát

Velmi doporučené: - Key Vault na secrets - Managed Identity místo ukládání hesel do YAMLů - Azure Monitor / Container Insights - separate namespaces pro jednotlivé aplikace

Podle potřeby navíc: - Azure SQL / PostgreSQL / MySQL - Storage Account / Azure Files / Blob Storage - Application Gateway / Front Door / WAF

3. Referenční architektura

flowchart TD U[Uživatel / admin] --> DNS[DNS / custom domain] DNS --> ING[Ingress / Load Balancer] ING --> AKS[AKS cluster] AKS --> HERMES[Hermes Agent container] AKS --> DOTNET[.NET 10 app container] AKS --> KV[Key Vault / secrets] AKS --> ACR[Azure Container Registry] AKS --> LOG[Azure Monitor / Log Analytics] DOTNET --> DB[DB / Storage dle potřeby]

4. Naming convention

Příklad pro produkci: - Resource Group: rg-aks-prod - ACR: acrhermesprod - AKS: aks-hermes-prod - Log Analytics: log-aks-prod - Key Vault: kv-hermes-prod - Namespace pro Hermes: hermes - Namespace pro .NET app: dotnet-app

Pokud chceš oddělit prostředí: - rg-aks-dev - rg-aks-test - rg-aks-prod

5. Co si připravit před klikáním v Azure

Ještě před Azure Portálem si připrav:

Pro oba scénáře

Specificky pro Hermes Agent

Ujasni si: - poběží jako web/API služba, nebo jako worker / automation container? - potřebuje příchozí HTTP provoz, nebo jen odchozí přístup ven? - jak budeš řešit credentials, API klíče, OAuth tokeny a config - jestli chceš 1 repliku, nebo víc instancí - zda Hermes používá trvalý disk / mount / config soubory

Specificky pro .NET 10 app

Ujasni si: - zda jde o ASP.NET Core web app / API - jaký je port, typicky 8080 - jaké connection stringy potřebuje - zda potřebuje migrace databáze při startu nebo mimo start - jaké readiness/liveness endpointy budou použité, typicky: - /health - /healthz - /ready

6. Rozhodnutí architektury pro scénář 1 a 2

Scénář 1: Hermes Agent na AKS

Doporučený model: - 1 namespace hermes - 1 deployment hermes-agent - 1 service - ingress jen pokud Hermes vystavuje HTTP endpoint - secrets z Key Vaultu nebo Kubernetes Secret - persistent volume jen pokud je opravdu potřeba

Scénář 2: .NET 10 app na AKS

Doporučený model: - 1 namespace dotnet-app - 1 deployment pro web/API - 1 service typu ClusterIP - 1 ingress pro veřejný přístup - health probes - HPA podle CPU/memory až později - DB mimo cluster

ČÁST A — CO VŠECHNO VYKLKAT V AZURE

7. Krok 1: založení Resource Group

Co vyklikat

  1. Otevři Azure Portal
  2. Do hledání napiš Resource groups
  3. Klikni Create
  4. Vyber:
  5. Subscription
  6. Resource group name: např. rg-aks-prod
  7. Region: např. West Europe
  8. Klikni Review + create
  9. Klikni Create

Poznámka

Všechny související resources drž ve stejné Resource Group, pokud nemáš důvod je dělit.

8. Krok 2: založení Log Analytics Workspace

Co vyklikat

  1. Do hledání napiš Log Analytics workspaces
  2. Klikni Create
  3. Vyplň:
  4. Subscription
  5. Resource group: rg-aks-prod
  6. Name: např. log-aks-prod
  7. Region: stejný jako Resource Group
  8. Klikni Review + create
  9. Klikni Create

Proč

Budeš to používat pro: - logy z AKS - Container Insights - troubleshooting

9. Krok 3: založení Azure Container Registry (ACR)

Co vyklikat

  1. Do hledání napiš Container registries
  2. Klikni Create
  3. Vyplň:
  4. Subscription
  5. Resource group: rg-aks-prod
  6. Registry name: např. acrhermesprod
    • musí být globálně unikátní
    • bez mezer
  7. Location: stejná oblast
  8. SKU: pro start obvykle Basic nebo Standard
  9. Klikni Review + create
  10. Klikni Create

Co si zapiš

10. Krok 4: založení AKS clusteru

Co vyklikat

  1. Do hledání napiš Kubernetes services
  2. Klikni Create → Create a Kubernetes cluster

Záložka Basics

Vyplň: - Subscription - Resource group: rg-aks-prod - Kubernetes cluster name: aks-hermes-prod - Region: stejná oblast - Availability zones: klidně zapnout, pokud chceš vyšší odolnost - AKS pricing tier: pro začátek obvykle Free nebo dle požadavků Standard - Kubernetes version: nech doporučenou stabilní verzi - Automatic upgrade: doporučeno zapnout podle firemní politiky

Primary node pool

Vyplň: - Node size: pro malé prostředí například něco úsporného; podle reálné zátěže - Scale method: doporučeno Manual pro začátek nebo Autoscale - Node count: typicky 1 až 3

Pro levný lab/test: - 1 node

Pro produkci raději: - alespoň 2 nody

Záložka Node pools

Pro začátek můžeš nechat default. Později můžeš přidat separátní pool např. pro: - Hermes workery - backend služby - joby

Záložka Access

Doporučené volby: - Authentication and Authorization: standardní Azure RBAC podle tvého modelu - Managed identity: nechat zapnuté - Local accounts: vypnout jen pokud víš proč; jinak podle security politiky

Záložka Networking

Doporučení pro první cluster: - Network configuration: Azure CNI Overlay nebo doporučené defaultní nastavení - Network policy: podle bezpečnostní politiky, klidně none pro start - DNS name prefix: vyplnit - Private cluster: vypnuté, pokud nechceš čistě privátní cluster - Load balancer: standard

Záložka Integrations

Zapni: - Container insights - připoj Log Analytics Workspace log-aks-prod

Záložka Monitoring

Nech zapnuté relevantní monitorovací funkce, pokud jsou k dispozici.

Dokončení

  1. Klikni Review + create
  2. Po validaci klikni Create
  3. Počkej na dokončení deploymentu

11. Krok 5: napojení AKS na ACR

Po vytvoření clusteru je potřeba zajistit, aby si AKS uměl stáhnout image z ACR.

Varianta v Portálu

V portálu to bývá částečně viditelné přes IAM / role / integrations, ale prakticky se to často dělá CLI.

Co si v Azure zkontrolovat

  1. Otevři AKS cluster
  2. Otevři Settings / Identity
  3. Otevři ACR nebo Access control (IAM) na registry
  4. Zkontroluj, že identita AKS má právo AcrPull na registru

Praktická poznámka

Pokud toto neuděláš, deployment v AKS spadne na chybu typu image pull failure.

12. Krok 6: založení Key Vaultu

Co vyklikat

  1. Do hledání napiš Key vaults
  2. Klikni Create
  3. Vyplň:
  4. Resource group: rg-aks-prod
  5. Name: kv-hermes-prod
  6. Region: stejná oblast
  7. Pricing tier: Standard obvykle stačí
  8. Klikni Review + create
  9. Klikni Create

Co do něj typicky uložit

13. Krok 7: DNS a veřejný vstup

AKS sám o sobě není uživatelsky hotová webová URL platforma. Potřebuješ ingress.

Nejčastější jednoduchá varianta: - v clusteru nasadit Ingress Controller - ten vytvoří Load Balancer IP - do DNS přidáš A záznam na tuto IP

Co budeš řešit v Azure

Pokud chceš enterprise vstup, můžeš místo jednoduchého ingressu použít: - Application Gateway Ingress Controller - případně Front Door

Pro první scénář je jednodušší běžný ingress controller.

ČÁST B — SCÉNÁŘ 1: HERMES AGENT V DOCKERU NA AKS

14. Doporučený deployment model pro Hermes Agent

Nejdřív si rozhodni, jak bude Hermes běžet:

Varianta A: Hermes jako HTTP služba

Použij, pokud: - přijímá webové requesty - má webhook endpointy - má UI/API

Potřebuješ: - deployment - service - ingress

Varianta B: Hermes jako interní worker

Použij, pokud: - běží dávkově - zpracovává joby - nepotřebuje veřejný HTTP vstup

Potřebuješ: - deployment nebo job/cronjob - service možná vůbec ne - ingress nepotřebuješ

Pro většinu agentních integračních scénářů je časté rozdělení na: - 1 veřejný API/webhook container - 1 nebo více worker containerů

15. Co budeš muset připravit pro Hermes image

Checklist: - Docker image v ACR - start command - port (pokud je HTTP) - env vars - secrets - volume mounty, pokud existují - health endpoint, pokud je to webová služba

Typické proměnné: - PORT - ENVIRONMENT - HERMES_HOME - přístupové tokeny - secrets pro integrace

Důležité: - nic citlivého nedávej napevno do image - secrets drž mimo image

16. Azure Portal klikací postup pro Hermes scénář

16.1 Vytvoř namespace pro Hermes

Tohle se typicky dělá po připojení ke clusteru přes Kubernetes nástroje, ne čistě v Azure GUI. Ale v portálu pak namespace uvidíš.

Doporučený namespace: - hermes

16.2 Připrav secrets

V Azure Portalu: 1. Otevři Key Vault 2. Jdi do Secrets 3. Klikni Generate/Import 4. Založ všechny potřebné secrets

16.3 Rozhodni repliku a sizing

Pro první nasazení: - replicas: 1

Pokud je Hermes stateless a zvládá horizontální škálování: - můžeš přidat další repliky později

16.4 Rozhodni storage

Pokud Hermes ukládá lokální stav, logy nebo cache na disk, musíš rozhodnout: - opravdu to potřebuje persistentně? - nebo to má jít do externí storage?

Preferované je: - stav do DB / storage služby - lokální disk jen na dočasná data

16.5 Pokud Hermes potřebuje veřejný endpoint

Budeš navíc řešit: - Service - Ingress - DNS - TLS

16.6 Pokud Hermes endpoint nepotřebuje

Stačí interní workload v clusteru bez ingressu.

17. Co je potřeba vyklikat a rozhodnout pro Hermes provozně

V Azure musíš u Hermes scénáře rozhodnout hlavně toto:

Povinné volby

Rozhodnutí navíc

Doporučený minimální první rollout

ČÁST C — SCÉNÁŘ 2: VLASTNÍ .NET 10 APLIKACE V DOCKERU NA AKS

18. Doporučený Docker model pro .NET 10

Pro .NET 10 web/API appku je typický model: - multi-stage Docker build - finální image s ASP.NET runtime - port vystavený typicky na 8080 - health endpointy - konfigurace přes env vars

Doporučené vlastnosti aplikace: - readiness endpoint - liveness endpoint - structured logs na stdout/stderr - connection stringy z environment variables - žádné lokální persistentní soubory jako primární storage

19. Azure Portal klikací postup pro .NET 10 scénář

19.1 Připrav databázi, pokud ji app potřebuje

Pokud app potřebuje DB: 1. V Azure Portalu založ odpovídající DB službu 2. Vezmi connection string 3. Ulož ho do Key Vaultu

Typicky: - Azure SQL Database - nebo Azure Database for PostgreSQL

19.2 Připrav namespace pro aplikaci

Doporučený namespace: - dotnet-app

19.3 Připrav ingress endpoint

Rozhodni: - jaká bude URL - jaký DNS záznam použiješ - jestli chceš jen jednu app, nebo více app pod jedním ingress controllerem

19.4 Nastav health checks

U .NET aplikace je to velmi důležité.

Doporučené endpointy: - /health - /ready

19.5 Nastav škálování

První nasazení: - 1 nebo 2 repliky

Produkce: - spíš 2+ repliky, pokud chceš vyšší dostupnost

19.6 Nastav storage jen pokud je reálně potřeba

Pokud app generuje exporty nebo pracuje se soubory, raději použij: - Blob Storage - Azure Files

Nepoužívej container filesystem jako hlavní úložiště.

20. Co všechno budeš muset u .NET app rozhodnout

Povinné

Silně doporučené

ČÁST D — DOPORUČENÝ REÁLNÝ POSTUP OD NULY

21. Doporučené pořadí krok za krokem

Fáze 1 — Azure základ

  1. založit Resource Group
  2. založit Log Analytics Workspace
  3. založit Azure Container Registry
  4. založit AKS cluster
  5. propojit AKS ↔ ACR
  6. založit Key Vault

Fáze 2 — síť a vstup

  1. rozhodnout ingress variantu
  2. zprovoznit veřejnou IP / load balancer
  3. nastavit DNS
  4. nastavit TLS

Fáze 3 — aplikace

  1. připravit Docker image
  2. pushnout image do ACR
  3. založit namespace hermes
  4. nasadit Hermes workload
  5. založit namespace dotnet-app
  6. nasadit .NET 10 workload

Fáze 4 — provoz

  1. nastavit logy
  2. zkontrolovat health checky
  3. otestovat rollout / restart / update image
  4. nastavit alerting

22. Co přesně budeš klikat v Azure Portalu v kostce

Jednou pro platformu

Potom pro provoz

23. Doporučené rozdělení odpovědností

Azure řeší

Ty řešíš

24. Nejčastější chyby

Chyba 1: AKS bez ACR oprávnění

Výsledek: - image nepůjde stáhnout

Chyba 2: žádný health endpoint

Výsledek: - rollout bude nespolehlivý - Kubernetes bude appku restartovat nebo označovat chybně

Chyba 3: secrets zapečené v image

Výsledek: - bezpečnostní problém

Chyba 4: ukládání důležitých dat do kontejneru

Výsledek: - ztráta dat po restartu / redeployi

Chyba 5: příliš velký cluster hned na začátku

Výsledek: - zbytečné náklady

Chyba 6: AKS pro jednu mini app bez důvodu

Výsledek: - zbytečně složitý provoz

25. Praktické doporučení pro tvoje dva scénáře

Scénář 1 — Hermes Agent v Dockeru na AKS

Zvol AKS tehdy, pokud: - Hermes bude součást větší platformy - chceš více agentních workloadů - chceš oddělit API, worker a pomocné služby - potřebuješ provozní standard Kubernetes

Minimální rozumná varianta: - 1 cluster - 1 namespace hermes - 1 replika na start - Key Vault na secrets - logy do Log Analytics - ingress jen pokud Hermes přijímá HTTP

Scénář 2 — vlastní .NET 10 aplikace v Dockeru na AKS

Zvol AKS tehdy, pokud: - .NET app je součást větší platformy - plánuješ více služeb - chceš standardní Kubernetes deployment model

Minimální rozumná varianta: - 1 namespace dotnet-app - 1 deployment - 1 service - 1 ingress - health probes - externí DB - 1–2 repliky podle prostředí

26. Kdy bych doporučil změnit směr

Pokud chceš pouze: - jednu veřejnou .NET appku - bez složitých workerů - bez více služeb - bez Kubernetes know-how

pak bych prakticky zvážil místo AKS: - Azure Container Apps, nebo - App Service for Containers

Pokud ale chceš společnou platformu pro Hermes i .NET aplikace, AKS smysl dává.

27. Krátký závěr

Pro oba cíle je AKS použitelný, ale je to platformní volba, ne „nejjednodušší deployment“.

Nejjednodušší reálný blueprint

Pokud chceš jít do realizace

Další praktický krok je připravit navazující artefakty: 1. Dockerfile pro Hermes scénář 2. Dockerfile pro .NET 10 scénář 3. Kubernetes YAML / Helm chart 4. checklist nasazení do AKS 5. CI/CD pipeline do ACR a AKS

28. Rychlý checklist „co budu muset v Azure vyklikat“

Platforma

Síť

Scénář 1 — Hermes

Scénář 2 — .NET 10

29. Doporučený další výstup

Pokud budeš chtít pokračovat, navazující smysluplný krok je vytvořit už konkrétní: - AKS deployment architekturu pro Hermes - AKS deployment architekturu pro tvoji .NET 10 app - konkrétní YAML manifesty - konkrétní seznam env vars a secrets - CI/CD postup build → ACR → AKS