GeneratedAPI
Fonctionnalité en préparation. Cette page décrit l'interface cible pour recueillir vos retours ; rien n'est encore utilisable.
Les API générées sont en préparation : ce manifeste n'est pas encore accepté par sng apply.
apiVersion | apibuilder.stackngo.io/v1alpha1 |
kind | GeneratedAPI |
| Appliqué par | sng apply (à venir) |
À quoi ça sert
Une GeneratedAPI assemble les Model et View d'une même application, génère le code Go d'une API HTTP, le compile et le sert. Vous décrivez vos données et vos routes ; la plateforme produit le binaire, le déploie et l'expose en HTTPS.
Les Model et View se rattachent à la GeneratedAPI par leur champ spec.application, qui porte son nom (application: blog). Sans selector, l'API se compose de toutes les ressources du tenant dont spec.application vaut son nom.
Pour envoyer des e-mails, spec.mail désigne un expéditeur (senderRef, un MailUser) et les gabarits (templates, des MailTemplate) que l'API peut utiliser. Voir Envoyer un e-mail.
Exemple minimal
apiVersion: apibuilder.stackngo.io/v1alpha1
kind: GeneratedAPI
metadata:
name: blog
spec:
servicePort: 8080
Exemple complet commenté
apiVersion: apibuilder.stackngo.io/v1alpha1
kind: GeneratedAPI
metadata:
name: blog
spec:
servicePort: 8080 # crée un service interne ; sans lui, pas d'exposition
replicas: 2
ingress:
enabled: true
includeGeneratedHost: true # garde l'hôte généré api-<uuid>.<domaine>
domains: [api.blog.acme.dev.stackngo.app]
env: # variables non sensibles du serveur généré
LOG_LEVEL: info
envFromSecrets: # variables sensibles, depuis un secret du tenant
- envVar: PAYMENT_API_KEY
name: blog-runtime
key: payment-api-key
resources:
requests: {cpu: 100m, memory: 128Mi}
Champs
GeneratedAPI
GeneratedAPI assemble vos Model et View en une API HTTP générée et déployée par la plateforme dans votre tenant.
| Champ | Description | Défaut | Validation |
|---|---|---|---|
apiVersion string | apibuilder.stackngo.io/v1alpha1 | ||
kind string | GeneratedAPI | ||
metadata ObjectMeta | Seul metadata.name est à renseigner (nom de la ressource dans votre tenant). | ||
spec GeneratedAPISpec | |||
status GeneratedAPIStatus |
GeneratedAPISpec
GeneratedAPISpec décrit les ressources qui composent l'API et la façon de l'exécuter et de l'exposer.
| Champ | Description | Défaut | Validation |
|---|---|---|---|
selector LabelSelector | Selector choisit, par leurs labels, les Model et View qui composent l'API. Absent : l'API se compose des ressources dont spec.application vaut le nom de cette API. | ||
generatorImage string | GeneratorImage est l'image du générateur d'API. Vide : image fournie par la plateforme. | ||
runtimeImage string | RuntimeImage est l'image qui exécute l'API générée. Vide : image fournie par la plateforme. | ||
binaryPath string | BinaryPath est l'emplacement de l'exécutable de l'API dans l'image d'exécution (défaut : /work/generated-api). | ||
httpCoreBuildPkg string | Paquet compilé par le générateur (défaut : ./src). À ne modifier que sur indication du support. | ||
replicas integer | Replicas est le nombre d'instances de l'API (défaut : 1). | 1 | |
servicePort integer | ServicePort est le port d'écoute de l'API. S'il est supérieur à 0, l'API est joignable par vos autres services sur ce port, et elle peut être publiée sur internet (voir ingress). | ||
debug boolean | Debug active les journaux détaillés du générateur. | ||
resources ResourceRequirements | Resources fixe le processeur et la mémoire réservés et maximaux de l'API (facultatif). | ||
initResources ResourceRequirements | InitResources fixe le processeur et la mémoire de l'étape de génération, avant le démarrage de l'API (facultatif). | ||
ingress GeneratedAPIIngressSpec | Publication de l'API sur internet en HTTPS, à l'adresse api-<nom>.<zone de votre tenant> et sur vos domaines. Nécessite servicePort. | ||
egress string array | Egress : sorties ouvertes en plus des services de votre tenant et du DNS. "internet" ouvre Internet (serveur SMTP, base de données externe), jamais les réseaux internes de la plateforme. | MaxItems: 1 items:Enum: [internet] Optional: {} | |
env object (keys:string, values:string) | Env : variables d'environnement transmises à l'API. | ||
envFromSecrets GeneratedAPIEnvFromSecret array | EnvFromSecrets : variables d'environnement lues dans des secrets de votre tenant. | ||
mail GeneratedAPIMailSpec | Mail : envoi d'e-mails par le service d'e-mails de la plateforme (MailUser et MailTemplate du groupe mail.stackngo.io de votre tenant). Absent : l'API n'envoie pas d'e-mail. |
GeneratedAPIStatus
GeneratedAPIStatus est l'état de l'API constaté par la plateforme.
| Champ | Description | Défaut | Validation |
|---|---|---|---|
conditions Condition array | Conditions : Ready (API déployée et prête), Synced (configuration à jour). | ||
mergedConfigHash string | MergedConfigHash est l'empreinte de la configuration complète de l'API ; elle change à chaque modification prise en compte. | ||
observedGeneration integer | ObservedGeneration est la dernière version du manifeste prise en compte. | ||
ingressUUID string | Obsolète : identifiant de l'ancienne adresse générée api-<identifiant>.<domaine>, conservée pour les API qui l'ont déjà reçue hors d'un tenant. Les nouvelles API n'en reçoivent plus. | ||
ingressHost string | Adresse publique principale de l'API (ex. api-blog.acme.example.com). | ||
ingressHosts string array | Toutes les adresses publiques de l'API. |
GeneratedAPIIngressSpec
GeneratedAPIIngressSpec règle la publication de l'API sur internet.
| Champ | Description | Défaut | Validation |
|---|---|---|---|
enabled boolean | Enabled : false garde l'API privée à votre tenant. Absent : l'API est publiée dès que servicePort est défini. | ||
domains string array | Domains : noms de domaine complets supplémentaires sous lesquels publier l'API, dans la zone de votre tenant ou dans un domaine que vous avez apporté. | ||
includeGeneratedHost boolean | IncludeGeneratedHost garde l'adresse générée api-<nom>.<zone de votre tenant> en plus de vos domaines (défaut : true). | true |
GeneratedAPIEnvFromSecret
GeneratedAPIEnvFromSecret lit une variable d'environnement dans une clé d'un secret de votre tenant.
| Champ | Description | Défaut | Validation |
|---|---|---|---|
envVar string | EnvVar est le nom de la variable d'environnement transmise à l'API. | ||
name string | Name est le nom du secret. | ||
key string | Key est la clé du secret qui contient la valeur. |
GeneratedAPIMailSpec
GeneratedAPIMailSpec désigne l'expéditeur et les modèles d'e-mail que l'API peut utiliser.
| Champ | Description | Défaut | Validation |
|---|---|---|---|
senderRef string | SenderRef est le nom d'un MailUser (expéditeur) de votre tenant. | MaxLength: 253 MinLength: 1 | |
templates string array | Templates : noms des MailTemplate de votre tenant que l'API peut envoyer. | MaxItems: 50 MinItems: 1 |
Statut et conditions
| Condition | Sens |
|---|---|
Ready | Le serveur généré est déployé et prêt |
Synced | Les modèles et vues sont fusionnés sans conflit, et l'expéditeur et les gabarits d'e-mail désignés existent et sont prêts |
| Raison | Sens | Que faire |
|---|---|---|
MergeFailed | Deux modèles pour la même clé, deux vues pour le même chemin | Lire le message, renommer |
MailNotReady | Le MailUser ou un MailTemplate désigné par spec.mail est absent ou pas prêt | Voir Envoyer un e-mail |
MissingImages | Images de génération ou d'exécution non configurées | Signaler au support |
InvalidEnvConfig | Variable mal formée dans env ou envFromSecrets | Lire le message |
DeploymentNotReady | Le serveur ne démarre pas | Lire les journaux du conteneur de génération puis du serveur |
status.ingressHost donne l'adresse publique, status.ingressUUID l'identifiant stable de l'hôte généré, status.mergedConfigHash l'empreinte de la configuration fusionnée.
Ce qui se passe à l'application
Chaque modification d'un Model ou d'une View rattachés regénère et redéploie l'API.
Ce qui se passe quand vous supprimez
Supprimer la GeneratedAPI arrête l'API : son adresse HTTPS ne répond plus. Les Model et View restent.
Voir aussi
- Model, View
- MailUser, MailTemplate (envoi d'e-mails, champ
spec.mail) - Manifestes : index