Aller au contenu

Format de l'architecture JSON

Structure complète du document d'architecture version 1.0 — blocs, champs, références entre blocs, transformations à l'export et dérivations à l'import.

RéférenceDéveloppeur
Voir en Markdown

Le document d'architecture décrit les définitions d'une application, sans identifiant ni valeur propre à une application donnée. La console le produit avec Exporter et l'accepte avec Importer ; voir Exporter et importer l'architecture.

Le format est validé par un schéma JSON (draft 2020-12). Tout champ non décrit ici est refusé.

Racine du document

ChampTypeObligatoireDescription
versionchaîneouiToujours "1.0"
kindchaîneouiToujours "wakastart-app-architecture"
exportedAtdate-heure ISO 8601nonPosé à l'export, ignoré à l'import
appobjetouiNom et nom court de l'application d'origine, à titre indicatif
repostableaunonDépôts Git
harborProjectobjetnonProjet du registre d'images
openbaoSecretEngineobjetnonCoffre de secrets
databaseDefinitionstableaunonDéfinitions de bases de données
storageBucketDefinitionstableaunonDéfinitions de buckets
serviceDefinitionstableaunonDéfinitions de service, avec leurs variables attendues
appUrlstableaunonURLs publiques, sans domaine
appRoutestableaunonRoutes HTTP entre une URL et un service
appApexUrlstableaunonExpositions sur le domaine racine d'un domaine personnalisé
appUrlRedirectstableaunonRedirections au niveau de l'application
environmentstableaunonEnvironnements à créer, sans instance

Références entre blocs

Les blocs se désignent par leur clé ref, jamais par un identifiant de la plateforme.

RègleValeur
Format d'une ref^[a-z0-9][a-z0-9-]{0,62}$
Format d'un shortname^[a-z0-9][a-z0-9-]{0,11}$, unique par application
Champs qui pointent vers une refrepoRef, serviceRef, urlRef, targetUrlRef, targetApexRef

La validation vérifie que chaque référence pointe vers un bloc existant (message Unknown repo ref "…", Unknown serviceDefinition ref "…", Unknown appUrl ref "…", Unknown appApexUrl ref "…").

app

ChampTypeObligatoireContraintes
namechaîneoui100 caractères au plus
shortnamechaîneouivoir shortname

L'import cible une application existante : ces valeurs ne la renomment pas.

repos[]

ChampTypeObligatoireDéfautDescription
refrefouiClé du dépôt dans le document
namechaîneoui^[a-z0-9][a-z0-9-]*$, 63 caractères au plus ; sur GitHub, un dépôt géré est nommé <wid>-<name>
isManagedbooléennontruetrue : Wakastart crée le dépôt ; false : référence à un dépôt existant
fullNamechaînesi isManaged: falseorganisation/depot ; ignoré pour un dépôt géré
htmlUrlURI ou nullsi isManaged: falseURL HTTPS se terminant par .git ; ignorée pour un dépôt géré
defaultBranchchaînenonmain63 caractères au plus
visibilitychaînenoninternalpublic, private ou internal

harborProject et openbaoSecretEngine

BlocChampTypeDéfaut
harborProjectimportExistingbooléenfalse
harborProjectimportExistingIdchaîne
openbaoSecretEngineengineTypechaînekv-v2
openbaoSecretEnginedescriptionchaîne, 500 caractères au plus

Le nom du projet et le chemin du coffre sont recalculés pour l'application cible.

databaseDefinitions[]

ChampTypeObligatoireDéfautContraintes
refrefoui
namechaîneoui100 caractères au plus
shortnameshortnameoui
engineTypechaîneouiPOSTGRESQL, MYSQL, MONGODB, VALKEY
defaultModechaînenonIN_CLUSTERIN_CLUSTER ou MANAGED
defaultPlanchaînenon63 caractères au plus
defaultRegionchaînenon63 caractères au plus
defaultVersionchaînenon20 caractères au plus
defaultDiskSizeGbentiernon1 au minimum
defaultStorageSizechaînenonpar exemple 10Gi
defaultReplicasentiernon11 au minimum
defaultDatabaseNamechaînenon63 caractères au plus

storageBucketDefinitions[]

ChampTypeObligatoireDéfaut
refrefoui
namechaîne, 100 caractères au plusoui
shortnameshortnameoui
defaultRegionchaînenongra
defaultStorageClasschaînenonSTANDARD
defaultVersioningbooléennonfalse

serviceDefinitions[]

ChampTypeObligatoireDéfautContraintes
refrefoui
namechaîneoui100 caractères au plus
shortnameshortnameoui
slugchaînenonshortname63 caractères au plus
repoRefrefouiDépôt du service
rootDirectorychaînenonracineDossier du service dans le dépôt
dockerfilePathchaînenonDockerfileRelatif au contexte de build
buildContextchaînenon.Relatif à rootDirectory
imageRegistrychaînenonregistre de la plateforme
imageProjectchaînenonnom court de l'application cible
imageNamechaîneoui63 caractères au plus
rolechaîneouiFRONT, BACK, BFF, WORKER
technologychaînenon50 caractères au plus ; nestjs, nextjs et custom fixent le port par défaut
defaultExposurechaîneouiPUBLIC, INTERNAL, PRIVATE
defaultProtocolchaînenonHTTP
defaultPortentiernonselon technology1 à 65535
defaultCpuRequest, defaultCpuLimitchaînenon100m, 500mmillicores, par exemple 250m
defaultMemoryRequest, defaultMemoryLimitchaînenon128Mi, 512MiMi ou Gi
defaultHealthCheckPathchaînenon/healthChemin des sondes
defaultHealthCheckInitialDelayentiernon30Secondes avant la première sonde de vie
defaultReadinessCheckPath, defaultStartupCheckPathchaînenonchemin des sondes
defaultHealthCheckPort, defaultReadinessCheckPort, defaultStartupCheckPortentiernon1 à 65535
defaultLivenessProbeEnabledbooléennontrue
defaultReadinessProbeEnabledbooléennontrue
defaultStartupProbeEnabledbooléennonfalse
varRequirementstableaunonVariables attendues

Important

Renseignez les ressources dans le format accepté par la console : CPU en millicores (250m), mémoire en Mi ou Gi (512Mi, 1Gi), avec au plus 2000m de CPU et 8Gi de mémoire. Une valeur hors de ce format empêche ensuite de modifier le service depuis la console.

varRequirements[]

ChampTypeObligatoireDéfautDescription
envVarNamechaîneouiNom de la variable, UPPER_SNAKE_CASE
requiredbooléennontrue
descriptionchaînenon500 caractères au plus
defaultValuechaînenonJamais un secret
mountTypechaînenonENV_VARENV_VAR ou FILE
mountPathchaînesi FILEChemin absolu du fichier dans le conteneur
mountModechaînenon0400Permissions octales
mountSubPathchaînenon

appUrls[] et appRoutes[]

BlocChampTypeObligatoireDéfaut
appUrlsrefrefoui
appUrlssubdomainchaîne, 63 caractères au plusoui
appUrlsdomainReftoujours nullnon
appRoutesserviceRefref d'un serviceoui
appRoutesurlRefref d'une URLoui
appRoutespathchaînenon/
appRoutespathTypePathPrefix ou ExactnonPathPrefix

À l'import, les URLs sont rattachées au domaine de la plateforme s'il existe, sinon créées détachées : rattachez-les ensuite depuis Architecture > URLs.

appApexUrls[] et appUrlRedirects[]

BlocChampTypeObligatoireDescription
appApexUrlsrefrefoui
appApexUrlsdomainNamechaîneouiNom du domaine personnalisé, par exemple mon-app.exemple.fr
appApexUrlsserviceRefref d'un serviceouiService qui reçoit le trafic
appApexUrlspath, pathTypenon/, PathPrefix
appUrlRedirectsrefrefoui
appUrlRedirectsdomainNamechaîneouiDomaine source
appUrlRedirectssourceSubdomainchaîne ou nullnonnull : la source est le domaine racine
appUrlRedirectstargetUrlRef ou targetApexRefrefun des deuxExactement une cible

Ces deux blocs ne s'importent que si l'application cible possède déjà un domaine personnalisé du même nom ; sinon l'entrée est ignorée sans bloquer l'import.

environments[]

ChampTypeObligatoireDéfautDescription
envchaîneouidev, staging ou prod
shortnameshortnameouiSert aussi de nom de l'instance
slugchaîne, 63 caractères au plusoui
gitRefchaînenonvaleur de envBranche suivie, de type branche
urlPrefixchaîne, 20 caractères au plusnonaucunPréfixe d'URL

Un environnement n'est pas créé si l'application cible possède déjà un environnement du même type. Aucune instance n'est créée.

Transformations à l'export

TransformationEffet
Champs propres à l'applicationIdentifiant, chemins et noms qui en dérivent, champs d'état retirés
Dépôts gérésExportés avec "isManaged": false et leur URL .git ; l'export échoue si un dépôt géré n'a pas encore d'URL
URLsDétachées de leur domaine (domainRef: null)
Domaines personnalisésNon exportés ; seuls leurs noms subsistent dans appApexUrls et appUrlRedirects
Exigences de secrets, nombre de versions conservées du coffreNon exportés

Dérivations à l'import

Champ absentValeur appliquée
serviceDefinitions[].slugshortname
serviceDefinitions[].imageProjectnom court de l'application cible
serviceDefinitions[].imageRegistryregistre par défaut de la plateforme
environments[].gitRefvaleur de env

L'import est transactionnel : soit tout est créé, soit rien. Ordre de création : dépôts, projet du registre, coffre, bases, buckets, services et variables, URLs, domaines racines, routes, redirections, environnements.

Exemple complet

JSON
{
  "version": "1.0",
  "kind": "wakastart-app-architecture",
  "app": { "name": "Mon app exemple", "shortname": "monapp" },
  "repos": [
    {
      "ref": "monorepo",
      "name": "wk-monapp",
      "isManaged": false,
      "fullName": "exemple-org/wk-monapp",
      "htmlUrl": "https://github.com/exemple-org/wk-monapp.git",
      "defaultBranch": "main"
    }
  ],
  "databaseDefinitions": [
    { "ref": "main-db", "name": "Base principale", "shortname": "main", "engineType": "POSTGRESQL", "defaultMode": "MANAGED", "defaultVersion": "16" }
  ],
  "serviceDefinitions": [
    {
      "ref": "api",
      "name": "API",
      "shortname": "api",
      "repoRef": "monorepo",
      "rootDirectory": "services/api",
      "imageName": "api",
      "role": "BACK",
      "technology": "nestjs",
      "defaultExposure": "INTERNAL",
      "defaultPort": 3000,
      "defaultMemoryLimit": "1Gi",
      "varRequirements": [
        { "envVarName": "LOG_LEVEL", "defaultValue": "info", "required": false },
        { "envVarName": "DATABASE_URL" }
      ]
    },
    {
      "ref": "front",
      "name": "Front",
      "shortname": "front",
      "repoRef": "monorepo",
      "rootDirectory": "apps/front",
      "imageName": "front",
      "role": "FRONT",
      "technology": "nextjs",
      "defaultExposure": "PUBLIC"
    }
  ],
  "appUrls": [
    { "ref": "app", "subdomain": "app" },
    { "ref": "api", "subdomain": "api" }
  ],
  "appRoutes": [
    { "serviceRef": "front", "urlRef": "app", "path": "/" },
    { "serviceRef": "api", "urlRef": "api", "path": "/" }
  ]
}