Guida sviluppatoriDeveloper guide
Il team di sviluppo prepara codice, configurazione e segreti applicativi. DevOps gestisce le promozioni tra ambienti tramite Kargo.
The development team prepares code, configuration, and application secrets. DevOps manages environment promotions through Kargo.
Dal codice al deployFrom code to deploy
- Repo appApp repoMR verso mainMR to main
- GitLab CITest e registryTests & registry
- KargoPromozione DevOpsDevOps promotion
- GitOpsReview e mergeReview & merge
- Argo CDSync e rolloutSync & rollout
In test-app, la CI pubblica l’immagine da main. Kargo promuove lo stesso digest OCI lungo tutta la catena. Il digest identifica la build che viene effettivamente installata.
In test-app, CI publishes the image from main. Kargo promotes the exact same OCI digest across the entire chain. The digest identifies the build that is actually installed.
devteststageprodPipeline di test-apptest-app pipeline · Stage KargoKargo stages
Repo applicativa e branchApplication repo and branches
main è l’unico branch permanente e la base delle release. Parti da main, lavora su una branch breve e apri una Merge Request verso main per review e test. Indica nella MR cosa cambia, quali test hai eseguito e se servono migrazioni o nuove impostazioni.
main is the only permanent branch and the base for releases. Branch off main, work on a short-lived branch, and open a Merge Request targeting main for review and testing. State in the MR what changes, which tests you ran, and whether migrations or new settings are needed.
Gli ambienti corrispondono a directory nei repository GitOps, sotto environments/<ambiente>/<app>/ su main.
Environments map to directories in the GitOps repositories, under environments/<environment>/<app>/ on main.
main a mainFrom main to mainmainParti dal codice condivisoStart from shared code- Branch di lavoroWorking branchSviluppa ed esegui i testDevelop and run tests
- Merge RequestReview e controlli CIReview and CI checks
mainMerge e pubblicazione dalla CIMerge and CI publication
Configurazione non sensibileNon-sensitive configuration
Il team di sviluppo apre la MR per l’ambiente interessato. DevOps rivede la modifica e coordina il rilascio.
The development team opens the MR for the target environment. DevOps reviews the change and coordinates the release.
- Dev · test · stage
gitops-noprod- Prod
gitops-prod
Nei values vanno URL pubblici, feature flag e impostazioni di runtime. Tratta come pubblico ogni valore che arriva al browser, incluse le variabili incorporate al momento della build.
Public URLs, feature flags, and runtime settings belong in values. Treat any value that reaches the browser as public, including variables embedded at build time.
Segreti applicativiApplication secrets
Il team di sviluppo carica e aggiorna password, token e chiavi API in OpenBao con account personali, nei percorsi assegnati all’app. Usa OpenBao noprod per dev, test e stage, e OpenBao prod per prod. In Git, ticket e chat condividi solo il nome della chiave e il riferimento.
The development team uploads and updates passwords, tokens, and API keys in OpenBao using personal accounts under the paths assigned to the app. Use OpenBao noprod for dev, test, and stage, and OpenBao prod for prod. In Git, tickets, and chat, share only the key name and reference.
DevOps predispone permessi e consegna via ESO e gestisce le credenziali di piattaforma. Se una chiamata dal frontend richiede una credenziale privata, falla passare dal backend.
DevOps provisions permissions and delivery via ESO and manages platform credentials. If a frontend call requires a private credential, route it through the backend.
Account OpenBaoOpenBao accounts · Policy di accessoAccess policies
- GitOpsURL, feature flag e valori di runtimeURLs, feature flags & runtime values
- Argo CD e HelmArgo CD & HelmApplica la configurazione dell’ambienteApplies environment configuration
- WorkloadConfigurazione non sensibileNon-sensitive configuration
- OpenBaoPassword, token e chiavi APIPasswords, tokens & API keys
- External Secrets OperatorSincronizza il Secret KubernetesSyncs the Kubernetes Secret
- WorkloadLegge il Secret configuratoReads the configured Secret
Il team di sviluppo apre la MR per i values e carica i segreti dell’app nell’istanza OpenBao dell’ambiente.
The development team opens the MR for values and uploads app secrets to the environment’s OpenBao instance.
Passaggio a DevOpsDevOps handoff
Quando chiedi una promozione, indica:
When requesting a promotion, specify:
- Versione e destinazione. MR applicativa, commit o immagine e ambiente richiesto.
- Prerequisiti. MR GitOps, nomi delle nuove chiavi OpenBao e stato della configurazione.
- Migrazioni e verifica. Ordine di esecuzione, compatibilità con la release precedente e smoke test con risultato atteso.
- Version and target. Application MR, commit or image, and target environment.
- Prerequisites. GitOps MR, names of new OpenBao keys, and configuration status.
- Migrations and verification. Execution order, backward compatibility with the previous release, and smoke test with expected result.
DevOps avvia e segue la promozione in Kargo. Nel flusso di test-app, Kargo apre la MR GitOps. Dopo review, validazione e merge, richiede ad Argo CD il sync completo della revisione approvata e attende la salute del workload. Il team di sviluppo esegue lo smoke test dopo il rollout.
DevOps initiates and monitors the promotion in Kargo. In the test-app flow, Kargo opens the GitOps MR. After review, validation, and merge, it requests a full sync of the approved revision from Argo CD and waits for workload health. The development team runs the smoke test after rollout.
Controlli di promozionePromotion checks
test-appWho takes part during a test-app promotion- SviluppoDevelopmentConsegna versione, ambiente e smoke testHands over version, environment & smoke test
- DevOps e KargoDevOps & KargoAvvio della promozione e MR sul digestStarts promotion & digest MR
- GitLabValidazione, review e merge GitOpsGitOps validation, review & merge
- Kargo e Argo CDKargo & Argo CDSync completo, PreSync e rolloutFull sync, PreSync & rollout
- SviluppoDevelopmentEsegue lo smoke testRuns the smoke test
Casi praticiPractical cases
Cambio un URL pubblico del frontendChanging a public frontend URL
Verifico con DevOps se l’app legge l’URL a runtime o lo incorpora nella build. Nel primo caso apro una MR sui values dell’ambiente. Nel secondo il valore deve entrare anche nella nuova build.
Check with DevOps whether the app reads the URL at runtime or embeds it at build time. In the first case, open an MR on the environment values. In the second, the value must also be included in the new build.
Aggiungo una chiave API al backendAdding an API key to the backend
Dichiaro il nome della chiave e se è obbligatoria. Inserisco il valore in OpenBao per gli ambienti interessati prima di chiedere la promozione. Se manca il percorso o l’accesso, chiedo a DevOps di predisporlo.
Declare the key name and whether it is mandatory. Insert the value in OpenBao for the affected environments before requesting promotion. If the path or access is missing, ask DevOps to provision it.
La release è bloccata o l’app ha una regressioneThe release is blocked or the app has a regression
Se la MR di promozione è bloccata, leggo l’esito di promotion-validation e correggo values o segreti applicativi. DevOps verifica Kargo, sync e rollout. Dopo il deploy controllo i log dell’app e lo smoke test. Prima di un ripristino verifico con DevOps la compatibilità con le migrazioni DB già eseguite.
If the promotion MR is blocked, check the promotion-validation output and fix the values or application secrets. DevOps checks Kargo, sync, and rollout. After deployment, inspect app logs and run the smoke test. Before a rollback, verify compatibility with already-executed DB migrations with DevOps.
Percorsi applicativiApplication paths
- test-app
dev → test → stage → prodvia Kargo, con validazione MR e controlloPreSync.dev → test → stage → prodvia Kargo, with MR validation andPreSynccheck.- DocOps
- IaC dichiara lo Stage
deve genera i valori di runtime. Il percorso previsto èdev → prod. Nel riferimento GitOps consultato mancano chart e values DocOps. Il validatore MR è configurato pertest-app.IaC declares thedevStage and generates runtime values. The planned path isdev → prod. In the consulted GitOps reference, DocOps chart and values are missing. The MR validator is configured fortest-app. - Nextcloud e OpenProjectNextcloud & OpenProject
- MR revisionata in
gitops-prode sync Argo CD avviato dall’operatore.Reviewed MR ingitops-prodand operator-triggered Argo CD sync. - Keycloak
- Configurazione non segreta in GitOps per
deveprod. Helmfile gestisce l’installazione e Terraform l’identità.Non-secret configuration in GitOps fordevandprod. Helmfile manages installation and Terraform manages identity.
Delivery applicativaApplication delivery · DocOps · Keycloak