Sources de extensions

Les sources de extensions permettent à vos développeurs de pousser des extensions vers une infrastructure qu'ils contrôlent déjà — un dépôt Git ou un registre OCI — et que votre installation Scrydon les récupère automatiquement selon un calendrier. Aucun trafic entrant, aucun téléversement manuel à chaque version.

Fonctionnement

Votre installation Scrydon exécute un réconciliateur qui interroge chaque source enregistrée selon un intervalle configurable (5 minutes par défaut, minimum 30 secondes). À chaque cycle, il :

1. Récupère le fichier catalogue scrydon.yaml depuis votre source.
2. Le compare aux versions précédemment installées.
3. Pour chaque entrée nouvelle ou modifiée : récupère l'artefact, vérifie sa signature et l'installe via le même pipeline qu'un téléversement manuel.
4. Enregistre le résultat du catalogue et les compteurs d'entrées ordinaires dans l'historique des exécutions de la source. La réponse d'une synchronisation manuelle et le journal du réconciliateur contiennent aussi le résumé borné par environnement décrit ci-dessous.

Le réconciliateur fonctionne en mode pull uniquement. Votre pipeline CI n'a jamais besoin d'un accès entrant vers votre cluster Scrydon.

Réconciliation de l'ontologie entre environnements

L'état de l'ontologie appartient à un environnement d'espace de travail ; une synchronisation de source n'envoie donc jamais une requête d'ontologie unique au niveau de l'organisation. Le réconciliateur énumère les vrais environnements d'espace de travail de l'organisation dans un ordre stable et applique chaque extension d'ontologie éligible une fois par environnement, avec au plus huit applications simultanées. Les sources de données de référence statiques restent à l'échelle de l'organisation et sont appliquées une fois par extension, pas une fois par environnement.

Pour les extensions déjà installées dans un environnement, les mises à jour automatiques de l'ontologie sont additives. Un environnement où l'extension n'est pas installée est compté comme skipped avec la raison not_installed ; la synchronisation ne l'installe pas implicitement. Le réconciliateur revisite toutes les cibles même lorsque l'entrée source elle-même n'a pas changé, de sorte qu'une nouvelle tentative après une réussite partielle peut converger sans republier l'artefact.

L'échec d'un environnement n'annule pas les environnements déjà appliqués et n'empêche pas les tentatives sur les autres. La réponse de l'API Synchroniser maintenant fournit targetAttempts, le nombre de cibles appliquées, ignorées et échouées, ainsi qu'un digest couvrant tous les échecs et au plus les 16 premiers résumés bornés de cible/erreur. Le toast des Paramètres n'affiche actuellement que les compteurs d'entrées ; les tuples exacts des cibles échouées et les compteurs agrégés sont également écrits dans le journal structuré de l'exécution en cours. La ligne stockée dans l'historique conserve le statut, l'erreur et les compteurs d'entrées habituels ; elle ne persiste ni le résumé complet des cibles ni le corps du manifeste.

Si l'organisation ne possède aucun environnement d'espace de travail, l'application automatique de l'ontologie signale no_workspace_environments et n'effectue aucun appel d'ontologie. La réconciliation du catalogue et les autres types de contenu indépendants peuvent tout de même aboutir ; vérifiez donc toujours les compteurs d'ontologie dans le résultat de Synchroniser maintenant au lieu d'interpréter une synchronisation du catalogue réussie comme la preuve que toutes les cibles d'ontologie ont été appliquées.

Chaque cible réussie enregistre l'identifiant réel de la ligne de catalogue, l'identifiant de la source, la référence immuable de l'entrée source et l'instantané complet du manifeste normalisé. Ces champs permettent à la page Paramètres → Plateforme → Extensions de détecter des environnements manquants ou divergents sans déduire l'état à partir des horodatages ou des identifiants de révision propres aux environnements.

Le catalogue source fait autorité

Le fichier catalogue scrydon.yaml est la source de vérité pour les extensions présents dans le catalogue de votre organisation. Si un administrateur retire de l'interface une extension géré par une source, la prochaine synchronisation le restaure tant qu'il est encore listé dans scrydon.yaml — de la même façon que re-téléverser une extension retraité manuellement le ramène. Pour supprimer définitivement une extension géré par une source :

• supprimez son entrée du scrydon.yaml de la source, ou
• désactivez (ou supprimez) la source elle-même.

Le retrait reste utile pour les extensions téléversés manuellement (aucune source ne les gère, ils restent donc retirés) et comme masquage temporaire pour les extensions gérés par une source entre deux synchronisations.

Choisir un type de source

Vous pouvez enregistrer plusieurs sources de chaque type par organisation.

Le fichier catalogue scrydon.yaml

Chaque source est décrite par un unique fichier scrydon.yaml situé à un chemin configurable dans votre dépôt ou registre. Ce fichier est la source de vérité pour les extensions à installer et leur version.

apiVersion: scrydon.io/v1
kind: ExtensionCatalog
extensions:
  - id: example.sample
    version: 1.0.0
    artifact:
      kind: git-tar
      ref: main
      path: extensions/sample
    signature:
      kind: none

  - id: example.fraud
    version: 1.2.0
    artifact:
      kind: oci
      ref: ghcr.io/example/scrydon-fraud@sha256:abc123def456...
    signature:
      kind: cosign-keyless
      certificateIdentityRegexp: "https://github.com/example/.*"
      certificateOidcIssuer: "https://token.actions.githubusercontent.com"

Champs du catalogue de extensions

Publication depuis la CI

Organisation d'une source Git

Pour une source Git, votre dépôt contient le catalogue scrydon.yaml aux côtés de vos répertoires de extensions. Le réconciliateur emballe le sous-répertoire déclaré à la référence configurée dans un fichier .scrydon-extension.tar.gz à la volée.

Organisation minimale :

my-extensions/
├── scrydon.yaml          # Catalogue de extensions
├── extensions/
│   └── fraud/            # Répertoire de l'extension — chacun contient une extension.json
│       ├── extension.json
│       └── ontology/
│           └── manifest.json
└── .github/
    └── workflows/
        └── validate.yml  # Valide scrydon.yaml à chaque PR

Validez scrydon.yaml sur les pull requests pour détecter les erreurs de catalogue avant qu'elles n'atteignent votre installation Scrydon :

# .github/workflows/validate.yml
name: validate-catalog
on:
  pull_request:
    paths: ['scrydon.yaml', 'extensions/**']
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - name: Validate catalog schema
        run: |
          bunx @scrydon/sdk-authoring sources validate scrydon.yaml

Organisation d'une source OCI

Pour une source OCI, votre pipeline CI construit un fichier .scrydon-extension.tar.gz pour chaque extension, le pousse en tant qu'artefact OCI, le signe avec cosign, et met à jour le catalogue scrydon.yaml (également poussé en tant qu'artefact OCI).

- uses: sigstore/cosign-installer@v3
- uses: oras-project/setup-oras@v1

bunx @scrydon/sdk-authoring extension build extensions/fraud \
  --out dist/fraud-${{ github.ref_name }}.tar.gz

oras push ghcr.io/${{ github.repository_owner }}/scrydon-fraud:${{ github.ref_name }} \
  --artifact-type application/vnd.scrydon.extension.v1.tar.gzip \
  dist/fraud-${{ github.ref_name }}.tar.gz:application/vnd.scrydon.extension.v1.tar.gzip

COSIGN_EXPERIMENTAL=1 cosign sign --yes \
  ghcr.io/${{ github.repository_owner }}/scrydon-fraud:${{ github.ref_name }}

DIGEST=$(oras manifest fetch --output - \
  ghcr.io/${{ github.repository_owner }}/scrydon-fraud:${{ github.ref_name }} \
  | jq -r '.config.digest // .digest')
sed -i "s|REPLACE_WITH_DIGEST|$DIGEST|" catalog/scrydon.yaml

oras push ghcr.io/${{ github.repository_owner }}/scrydon-catalog:catalog \
  --artifact-type application/vnd.scrydon.catalog.v1+yaml \
  catalog/scrydon.yaml:application/vnd.scrydon.catalog.v1+yaml

Des exemples complets et fonctionnels se trouvent dans le répertoire examples/extension-sources/ du dépôt du SDK Scrydon.

Enregistrer une source via l'interface Paramètres

Authentification d'une source privée

Les dépôts Git privés et les registres OCI privés nécessitent un identifiant. Collez-le directement dans le champ Identifiant d'accès de la source — Scrydon l'enregistre comme un secret d'organisation chiffré et établit la référence automatiquement. Vous n'avez jamais à gérer un secret séparé manuellement.

Livraison d'intégrations personnalisées

Une extension peut inclure une entrée de contenu extension dans son extension.json. Lors de l'installation d'un tel extension, la plateforme enregistre l'intégration personnalisée aux côtés de tout autre type de contenu (ontologie, processus, etc.) — aucune étape de téléversement séparée n'est nécessaire.

La synchronisation place uniquement les extensions dans le catalogue de votre organisation — l'installation est une seconde étape explicite. Le catalogue Paramètres → Plateforme → Extensions → Ajouter une extension est l'endroit où les intégrations personnalisées sont découvertes et installées pour la première fois. La ligne d'une extension dans l'onglet Installées (et l'onglet Version & sécurité de sa fiche) permet de suivre l'état d'installation pour tous les types de contenu et d'appliquer les mises à jour.

Dans le catalogue Ajouter une extension, une intégration personnalisée synchronisée est une ligne qui nomme son extension (depuis l'extension <extension>), listée parmi les fournisseurs auxquels elle appartient — et Filtrer → Source → Depuis vos extensions n'affiche que celles-ci :

• Pas encore installée — affiche Connecter lorsque la première étape après l'installation est un identifiant, et Installer sinon ; l'une comme l'autre installe et active l'intégration immédiatement, et Connecter enchaîne directement sur son étape de connexion.
• Déjà installée et à jour — est la ligne du fournisseur lui-même, repliée sous la ligne N installées de son groupe, avec Gérer qui ouvre le panneau du fournisseur.
• Mise à jour disponible — n'est pas proposée dans Ajouter une extension. La ligne du fournisseur dans l'onglet Installées l'affiche dans la colonne version (1.3.0 → 1.4.0), et la mise à jour s'examine et s'applique dans la fiche de l'extension sous Version & sécurité. Voir Gestion des versions de extensions.

L'installation d'une extension entier (y compris ses types de contenu non-intégration tels que l'ontologie, les workflows et les sources de données) se fait depuis le groupe Solutions et contenu du catalogue Ajouter une extension.

Connecter ou installer une extension depuis le catalogue Ajouter une extension l'active immédiatement — l'action explicite de l'administrateur est la révision. La politique de signature contrôle les flux non interactifs :

Limites de taille pour les artefacts d'intégration : 8 Mo par archive.tar.gz, dans une archive de extension de 16 Mo compressés au maximum. Les deux sont appliquées par le même pipeline quelle que soit la façon dont l'extension arrive — synchronisation d'une source ou téléversement ponctuel — il n'existe donc pas de porte plus large ; un artefact de plus de 8 Mo doit être réduit. Voir le guide de création de extensions pour la structure complète des sous-répertoires et la déclaration extension.json.

Politiques de signature

Chaque artefact de extension doit passer la vérification de signature avant d'être installé. La politique de signature est définie par source lors de l'enregistrement.

Les nouvelles sources utilisent cosign-keyless par défaut. Les déploiements réglementés peuvent définir la valeur Helm auth.requireSignedExtensionSources: true ; les politiques comportant une branche acceptant du contenu non signé sont alors refusées lors de la création, de la mise à jour, du test de connexion, de la réconciliation et de l'activation dans un espace de travail. Le contenu non signé déjà présent dans le catalogue ne peut pas être activé tant que ce paramètre est actif.

cosign-keyless (recommandé)

signature:
  kind: cosign-keyless
  certificateIdentityRegexp: "https://github.com/acme/scrydon-extensions/.*"
  certificateOidcIssuer: "https://token.actions.githubusercontent.com"

Le réconciliateur appelle cosign verify avec ces contraintes. L'émetteur OIDC et l'identité du certificat doivent correspondre exactement — une extension signé dans un dépôt différent ou par un système CI différent échouera à la vérification.

Pour que cela fonctionne, votre workflow de publication doit demander la permission id-token: write et utiliser sigstore/cosign-installer@v3.

cosign-key

signature:
  kind: cosign-key
  publicKey: |
    -----BEGIN PUBLIC KEY-----
    MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...
    -----END PUBLIC KEY-----

Générez une paire de clés avec cosign generate-key-pair et collez la clé publique ci-dessus. Conservez la clé privée dans un secret CI (COSIGN_PRIVATE_KEY) et signez avec cosign sign --key env://COSIGN_PRIVATE_KEY.

unsigned-allowed

À utiliser uniquement pour le développement local ou les environnements de laboratoire isolés où l'exécution d'une infrastructure de signature est impraticable. Dans scrydon.yaml, les entrées sous une source unsigned-allowed utilisent signature: { kind: none }.

Si auth.requireSignedExtensionSources est activé, unsigned-allowed reste indisponible même lors d'une action explicite d'un administrateur. Configurez cosign-keyless, cosign-key ou une autre politique dont chaque branche impose la vérification de signature.

Dépannage

verify_failed

La vérification de signature a échoué pour un ou plusieurs artefacts de extension.

• Vérifiez que votre workflow de publication a la permission id-token: write (pour le mode sans clé).
• Confirmez que certificateIdentityRegexp correspond à l'URL d'exécution GitHub Actions de votre dépôt (par ex. https://github.com/acme/scrydon-extensions/.*).
• Confirmez que certificateOidcIssuer correspond au fournisseur OIDC utilisé par votre CI (https://token.actions.githubusercontent.com pour GitHub Actions).
• Pour cosign-key : vérifiez que la clé publique dans la configuration de la source correspond à la clé privée utilisée pour signer l'artefact.
• Vérifiez que l'extension a été signé après avoir été poussé dans le registre — signer un tag ou un digest différent de celui référencé dans scrydon.yaml échouera.

fetch_failed

Le réconciliateur n'a pas pu atteindre votre source.

• Pour les sources Git : vérifiez que l'URL est une URL de clonage HTTPS et que les identifiants (PAT ou clé de déploiement) ont la portée read sur le dépôt.
• Pour les sources OCI : vérifiez que la référence de registre est correcte et que les identifiants de tirage ont un accès en lecture au dépôt.
• Vérifiez que la source est accessible depuis le réseau de votre cluster Scrydon. Le réconciliateur effectue des requêtes HTTPS sortantes — assurez-vous que le trafic sortant n'est pas bloqué.
• Cliquez sur Tester la connexion dans les Paramètres pour obtenir une erreur plus détaillée.

parse_failed

scrydon.yaml a échoué à la validation du schéma.

• Exécutez le validateur localement : bunx @scrydon/sdk-authoring sources validate scrydon.yaml
• Causes courantes : clés inconnues (fautes de frappe), champs requis manquants, format d'identifiant de extension invalide (doit être en minuscules avec des points, par ex. acme.fraud), semver invalide, ref d'artefact manquant pour les entrées OCI.
• Confirmez que le fichier est un YAML valide avant de vérifier le schéma.

install_failed

L'extension a été récupéré et vérifié mais son installation a échoué.

• L'archive de l'extension elle-même est peut-être malformée. Testez-la localement : bunx @scrydon/sdk-authoring extension test extensions/fraud
• Vérifiez le détail de l'erreur dans l'historique des exécutions sous Paramètres > Plateforme > Extensions > onglet Sources — cliquez sur une ligne de source (ou son action Voir l'historique) pour ouvrir le panneau d'historique — pour l'erreur de validation extension.json spécifique.
• Confirmez que extension.json package.id correspond au schéma en minuscules avec points et que installOrder correspond aux types dans contents.

no_workspace_environments

L'organisation ne possède aucun environnement d'espace de travail pouvant recevoir le contenu d'ontologie. Aucune requête d'ontologie n'a été envoyée. Créez l'environnement prévu, puis relancez Synchroniser maintenant. Le hook de création d'environnement installe l'ontologie knowledge-base intégrée dans cet environnement ; les extensions gérées par une source convergent toujours lors de la synchronisation suivante.

Certaines cibles d'ontologie ont échoué ou ont été ignorées

• Vérifiez ontologyAutoApply dans la réponse de l'API Synchroniser maintenant. Comparez targetAttempts aux nombres de cibles appliquées, ignorées et échouées.
• not_installed est un saut intentionnel : la réconciliation automatique met à jour une extension installée, mais n'inscrit pas un nouvel environnement à cette extension.
• Pour les échecs, utilisez le tuple d'espace de travail/environnement renvoyé ou journalisé ainsi que le texte d'erreur borné. Le digest d'échec couvre l'ensemble complet lorsque plus de 16 résumés existent.
• Corrigez la cause propre à la cible puis relancez Synchroniser maintenant. Les cibles réussies sont idempotentes et les entrées source inchangées sont délibérément revisitées.
• Ne copiez pas le corps d'un manifeste dans les tickets ou les journaux. Utilisez les champs de provenance du catalogue/de la source et les digests pour corréler l'artefact.

La source indique « géré par le chart » et est en lecture seule

Cette source a été initialisée via extensionSources: dans vos valeurs Helm. Modifiez les valeurs du chart pour la changer — ne créez pas une source dupliquée gérée par l'interface avec le même nom.

La synchronisation s'arrête après des échecs répétés

Après trois exécutions consécutives échouées, le réconciliateur augmente l'intervalle au double de celui configuré (plafonné à une heure). Corrigez l'erreur sous-jacente — le recul se réinitialise automatiquement lors de la prochaine synchronisation réussie. Cliquer sur Synchroniser maintenant dans l'interface réinitialise le compteur immédiatement.

Une extension retraité est revenu / une extension est absent du catalogue

Les extensions gérés par une source suivent le catalogue de la source : une extension retraité qui est encore listé dans scrydon.yaml est restauré lors de la prochaine synchronisation (voir Le catalogue source fait autorité). Inversement, si une extension attendu est absent, vérifiez qu'il est listé dans le scrydon.yaml de la source, que la dernière exécution dans l'historique de la source a réussi, et que le toast Synchroniser maintenant l'indique comme installé — l'état retraité/restauré suit ensuite la source automatiquement.