F-SNICAP

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

  1. Repo appApp repoMR verso mainMR to main
  2. GitLab CITest e registryTests & registry
  3. KargoPromozione DevOpsDevOps promotion
  4. GitOpsReview e mergeReview & merge
  5. Argo CDSync e rolloutSync & rollout
GitOps fornisce i valori non sensibili. External Secrets Operator consegna al workload i segreti dall’OpenBao dell’ambiente.
GitOps supplies non-sensitive values. External Secrets Operator delivers secrets to the workload from the environment’s OpenBao.

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.

devteststageprod

Pipeline 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.

Da main a mainFrom main to main
  1. mainParti dal codice condivisoStart from shared code
  2. Branch di lavoroWorking branchSviluppa ed esegui i testDevelop and run tests
  3. Merge RequestReview e controlli CIReview and CI checks
  4. 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

Due percorsi verso lo stesso workloadTwo paths to the same workload
  1. GitOpsURL, feature flag e valori di runtimeURLs, feature flags & runtime values
  2. Argo CD e HelmArgo CD & HelmApplica la configurazione dell’ambienteApplies environment configuration
  3. WorkloadConfigurazione non sensibileNon-sensitive configuration
  1. OpenBaoPassword, token e chiavi APIPasswords, tokens & API keys
  2. External Secrets OperatorSincronizza il Secret KubernetesSyncs the Kubernetes Secret
  3. 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

Chi interviene durante una promozione di test-appWho takes part during a test-app promotion
  1. SviluppoDevelopmentConsegna versione, ambiente e smoke testHands over version, environment & smoke test
  2. DevOps e KargoDevOps & KargoAvvio della promozione e MR sul digestStarts promotion & digest MR
  3. GitLabValidazione, review e merge GitOpsGitOps validation, review & merge
  4. Kargo e Argo CDKargo & Argo CDSync completo, PreSync e rolloutFull sync, PreSync & rollout
  5. 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 → prod via Kargo, con validazione MR e controllo PreSync.dev → test → stage → prod via Kargo, with MR validation and PreSync check.
DocOps
IaC dichiara lo Stage dev e genera i valori di runtime. Il percorso previsto è dev → prod. Nel riferimento GitOps consultato mancano chart e values DocOps. Il validatore MR è configurato per test-app.IaC declares the dev Stage and generates runtime values. The planned path is dev → prod. In the consulted GitOps reference, DocOps chart and values are missing. The MR validator is configured for test-app.
Nextcloud e OpenProjectNextcloud & OpenProject
MR revisionata in gitops-prod e sync Argo CD avviato dall’operatore.Reviewed MR in gitops-prod and operator-triggered Argo CD sync.
Keycloak
Configurazione non segreta in GitOps per dev e prod. Helmfile gestisce l’installazione e Terraform l’identità.Non-secret configuration in GitOps for dev and prod. Helmfile manages installation and Terraform manages identity.

Delivery applicativaApplication delivery · DocOps · Keycloak