GeneratedAPI

Coming soon

In preparation. This page describes the target interface to gather your feedback; nothing is usable yet.

Generated APIs are in preparation: this manifest is not accepted by sng apply yet.

apiVersion	apibuilder.stackngo.io/v1alpha1
kind	GeneratedAPI
Applied by	sng apply (upcoming)

What it is for

A GeneratedAPI assembles the Model and View objects of the same application, generates the Go code of an HTTP API, compiles it, and serves it. You describe your data and your routes; the platform produces the binary, deploys it, and exposes it over HTTPS.

Attaching to an API

The Model and View resources are attached to the GeneratedAPI by their spec.application field, which carries its name (application: blog). Without selector, the API is made of all the tenant's resources whose spec.application equals its name.

To send e-mails, spec.mail designates a sender (senderRef, a MailUser) and the templates (templates, MailTemplate objects) the API may use. See Send an email.

Minimal example

apiVersion: apibuilder.stackngo.io/v1alpha1
kind: GeneratedAPI
metadata:
  name: blog
spec:
  servicePort: 8080

Complete annotated example

apiVersion: apibuilder.stackngo.io/v1alpha1
kind: GeneratedAPI
metadata:
  name: blog
spec:
  servicePort: 8080              # creates an internal service; without it, no exposure
  replicas: 2
  ingress:
    enabled: true
    includeGeneratedHost: true   # keeps the generated host api-<uuid>.<domain>
    domains: [api.blog.acme.dev.stackngo.app]
  env:                           # non-sensitive variables of the generated server
    LOG_LEVEL: info
  envFromSecrets:                # sensitive variables, from a tenant secret
    - envVar: PAYMENT_API_KEY
      name: blog-runtime
      key: payment-api-key
  resources:
    requests: {cpu: 100m, memory: 128Mi}

Fields

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

Status and conditions

Condition	Meaning
Ready	The generated server is deployed and ready
Synced	The models and views are merged without conflict, and the designated sender and e-mail templates exist and are ready

Reason	Meaning	What to do
MergeFailed	Two models for the same key, two views for the same path	Read the message, rename
MailNotReady	The MailUser or a MailTemplate designated by spec.mail is missing or not ready	See Send an email
MissingImages	Generation or runtime images not configured	Report it to support
InvalidEnvConfig	Malformed variable in env or envFromSecrets	Read the message
DeploymentNotReady	The server does not start	Read the logs of the generation container, then of the server

status.ingressHost gives the public address, status.ingressUUID the stable identifier of the generated host, status.mergedConfigHash the fingerprint of the merged configuration.

What happens when you apply

Every change to an attached Model or View regenerates and redeploys the API.

What happens when you delete

Deleting the GeneratedAPI stops the API: its HTTPS address no longer responds. The Model and View objects remain.

See also

• Model, View
• MailUser, MailTemplate (sending e-mails, spec.mail field)
• Manifests: index