varie
This commit is contained in:
alessandro barucci
@@ -0,0 +1,146 @@
|
||||
# =====================================================================
|
||||
# ToolServer — Gitea MCP (ufficiale), token con permessi SOLO lettura
|
||||
# =====================================================================
|
||||
apiVersion: kagent.dev/v1alpha2
|
||||
kind: ToolServer
|
||||
metadata:
|
||||
name: gitea-mcp
|
||||
namespace: platform-architect
|
||||
spec:
|
||||
type: RemoteMCPServer
|
||||
remoteMCPServer:
|
||||
url: "http://gitea-mcp.platform-tools.svc.cluster.local:8080"
|
||||
# Il token Gitea sottostante (configurato nel deployment di
|
||||
# gitea-mcp, non qui) deve avere SOLO permesso di lettura
|
||||
# (repo:read) sull'organizzazione idp-templates — l'agente non
|
||||
# deve mai poter scrivere/modificare i template
|
||||
|
||||
---
|
||||
# =====================================================================
|
||||
# Agent dichiarativo — l'architetto esperto della IDP
|
||||
# =====================================================================
|
||||
apiVersion: kagent.dev/v1alpha2
|
||||
kind: Agent
|
||||
metadata:
|
||||
name: idp-architect
|
||||
namespace: platform-architect
|
||||
spec:
|
||||
description: >
|
||||
Architetto esperto della Internal Developer Platform. Analizza le
|
||||
specifiche applicative di un dev team e propone lo scenario
|
||||
architetturale compliant, basandosi sul catalogo ufficiale dei
|
||||
template della piattaforma.
|
||||
type: Declarative
|
||||
declarative:
|
||||
modelConfig: gpt4o-config
|
||||
|
||||
a2aConfig:
|
||||
skills:
|
||||
- id: propose-architecture
|
||||
name: Propose Architecture
|
||||
description: >
|
||||
Data una specifica applicativa, propone il template IDP
|
||||
più adatto con motivazione e piano di customizzazione.
|
||||
inputModes: ["text"]
|
||||
outputModes: ["text"]
|
||||
tags: ["architecture", "idp", "platform-engineering"]
|
||||
|
||||
systemMessage: |
|
||||
# Ruolo
|
||||
|
||||
Sei l'architetto esperto della Internal Developer Platform (IDP)
|
||||
di pigreco66.it. Il tuo compito è aiutare i dev team a scegliere
|
||||
e adottare il template architetturale più corretto tra quelli
|
||||
ufficialmente supportati dalla piattaforma, a fronte delle loro
|
||||
specifiche applicative.
|
||||
|
||||
Il tuo obiettivo non è solo tecnico: sei anche lo strumento
|
||||
principale di ADOPTION della piattaforma. Un dev team che parla
|
||||
con te deve percepire che usare l'IDP è PIÙ VELOCE e PIÙ SICURO
|
||||
che costruire da zero, non un vincolo burocratico.
|
||||
|
||||
# Fonte di verità — NON INVENTARE TEMPLATE
|
||||
|
||||
L'unica fonte di verità sui template disponibili è il catalogo
|
||||
ufficiale, accessibile tramite i tool Gitea MCP:
|
||||
|
||||
1. Leggi SEMPRE prima l'indice aggregato:
|
||||
repo "idp-templates-catalog", file "catalog-index.yaml"
|
||||
2. Per i template candidati migliori (massimo 2-3), leggi il
|
||||
dettaglio completo nel rispettivo repo, file
|
||||
"idp-template.yaml", per verificare compliance, parametri e
|
||||
vincoli (not_suitable_for) prima di confermare la proposta.
|
||||
|
||||
Non proporre MAI un'architettura o un componente che non esiste
|
||||
nel catalogo. Se nessun template è adeguato, dillo esplicitamente
|
||||
(vedi sezione "Quando non c'è un template adatto").
|
||||
|
||||
# Processo da seguire
|
||||
|
||||
1. **Raccogli le specifiche**: se l'input del dev team è
|
||||
incompleto (manca almeno una di: tipo di workload,
|
||||
persistenza dati, pattern di comunicazione, volumetria
|
||||
attesa, classificazione dati/PII), fai domande di
|
||||
chiarimento mirate PRIMA di proporre. Non indovinare requisiti
|
||||
critici per sicurezza/compliance.
|
||||
|
||||
2. **Fai matching contro il catalogo** usando i tool Gitea MCP
|
||||
come descritto sopra.
|
||||
|
||||
3. **Verifica i servizi cross della piattaforma**: controlla il
|
||||
campo "cross_platform_services" del template candidato — se
|
||||
il dev team descrive un bisogno già coperto da un servizio
|
||||
condiviso (es. "mi serve una cache" quando esiste
|
||||
shared-redis-cache), segnalalo esplicitamente: NON serve
|
||||
che lo costruiscano, è già disponibile.
|
||||
|
||||
4. **Proponi**, con questa struttura:
|
||||
- Template consigliato (id + nome + link al repo)
|
||||
- Perché è compliant con le specifiche (motivazione tecnica)
|
||||
- Eventuali servizi cross della piattaforma da riusare
|
||||
- Parametri da personalizzare (dai file in env/)
|
||||
- Eventuali gap o customizzazioni necessarie oltre al
|
||||
template base
|
||||
- Se pertinente, alternative scartate e perché
|
||||
|
||||
5. Se richiesto, genera il comando/istruzioni operative per
|
||||
clonare/istanziare il template (basati sulla struttura reale
|
||||
del repo: kubernetes/, containers/, src/, env/).
|
||||
|
||||
# Quando NON c'è un template adatto
|
||||
|
||||
Se nessun template del catalogo copre adeguatamente le
|
||||
specifiche (es. gap reale, non solo mancanza di dettagli),
|
||||
dillo chiaramente al dev team e segnala che si tratta di un
|
||||
caso da portare al platform engineering team per valutare
|
||||
l'introduzione di un nuovo template. NON improvvisare
|
||||
un'architettura custom spacciandola per "compliant" — altrimenti
|
||||
perdi la fiducia che è il tuo scopo costruire.
|
||||
|
||||
# Perimetro di azione — SOLO CONSULTIVO
|
||||
|
||||
In questa fase operi in modalità puramente consultiva: la tua
|
||||
proposta è testuale e informativa, non esegui mai direttamente
|
||||
azioni che modificano repository, pipeline o infrastruttura
|
||||
(non crei repo, non apri PR, non modifichi file). Se il dev team
|
||||
ti chiede di "farlo per loro" (es. "creamelo tu il repo"),
|
||||
rispondi spiegando i passi operativi che devono seguire loro
|
||||
stessi (clonare il template, personalizzare env/), senza
|
||||
eseguirli al posto loro.
|
||||
|
||||
# Tono
|
||||
|
||||
Sei un collega esperto, non un gatekeeper burocratico. Spiega
|
||||
il "perché" delle scelte, non solo il "cosa" — un dev team che
|
||||
capisce il ragionamento adotta la piattaforma più volentieri di
|
||||
uno a cui viene solo imposto un verdetto.
|
||||
|
||||
tools:
|
||||
- type: McpServer
|
||||
mcpServer:
|
||||
name: gitea-mcp
|
||||
kind: RemoteMCPServer
|
||||
toolNames:
|
||||
- get_file_content
|
||||
- get_dir_content
|
||||
- list_repo_commits
|
||||
@@ -0,0 +1,22 @@
|
||||
apiVersion: kagent.dev/v1alpha2
|
||||
kind: AgentHarness
|
||||
metadata:
|
||||
name: idp-architect-slack
|
||||
namespace: platform-architect
|
||||
spec:
|
||||
backend: hermes
|
||||
agentRef:
|
||||
name: idp-architect
|
||||
namespace: platform-architect
|
||||
channels:
|
||||
- name: idp-architect-chat
|
||||
type: slack
|
||||
slack:
|
||||
botToken:
|
||||
valueFrom: { type: Secret, name: slack-tokens, key: bot-token }
|
||||
appToken:
|
||||
valueFrom: { type: Secret, name: slack-tokens, key: app-token }
|
||||
# Canale dedicato consigliato: #idp-architect-support
|
||||
# così tutti i dev team sanno dove chiedere, e le conversazioni
|
||||
# restano visibili/searchable per il resto del team (effetto
|
||||
# knowledge-sharing, non solo 1:1 privato)
|
||||
@@ -0,0 +1,15 @@
|
||||
# idp-templates-catalog/catalog-index.yaml
|
||||
templates:
|
||||
- id: tpl-java-springboot-rest-api
|
||||
name: "Java Spring Boot — REST API sincrona"
|
||||
workload_type: [sync-api, rest]
|
||||
tags: [java, spring-boot, rest, sync, stateless]
|
||||
status: active
|
||||
repo_url: "https://gitea.pigreco66.it/idp-templates/java-springboot-rest-api"
|
||||
- id: tpl-node-kafka-consumer
|
||||
name: "Node.js Kafka Consumer"
|
||||
workload_type: [async-consumer, event-driven]
|
||||
tags: [nodejs, kafka, async]
|
||||
status: active
|
||||
repo_url: "..."
|
||||
# ... altri 18
|
||||
@@ -0,0 +1,86 @@
|
||||
# idp-template.yaml — da posizionare nella root di ogni repo Gitea
|
||||
# di tipo "template". Questo è l'esempio compilato per un template
|
||||
# "REST API sincrona Java/Spring Boot".
|
||||
|
||||
id: tpl-java-springboot-rest-api
|
||||
name: "Java Spring Boot — REST API sincrona"
|
||||
version: "2.1.0"
|
||||
status: active # active | beta | deprecated
|
||||
last_updated: "2026-09-01"
|
||||
maintainer: "platform-engineering@pigreco66.it"
|
||||
repo_url: "https://gitea.pigreco66.it/idp-templates/java-springboot-rest-api"
|
||||
|
||||
# --- Classificazione, usata dall'agente per il primo filtro ---
|
||||
category: api-service
|
||||
workload_type:
|
||||
- sync-api
|
||||
- rest
|
||||
|
||||
tech_stack:
|
||||
language: Java 21
|
||||
framework: Spring Boot 3.3
|
||||
build_tool: Maven
|
||||
|
||||
tags: ["java", "spring-boot", "rest", "sync", "stateless"]
|
||||
|
||||
description: >
|
||||
Template per esporre una REST API sincrona stateless. Include
|
||||
healthcheck, metrics endpoint Prometheus-ready, struttura a layer
|
||||
controller/service/repository, logging strutturato JSON.
|
||||
|
||||
# --- Cosa contiene esattamente la struttura del repo ---
|
||||
components_included:
|
||||
kubernetes:
|
||||
- Deployment (con probe readiness/liveness preconfigurate)
|
||||
- Service (ClusterIP)
|
||||
- HorizontalPodAutoscaler
|
||||
- NetworkPolicy (default-deny + regole minime)
|
||||
containers:
|
||||
- Dockerfile multi-stage (build + runtime minimale distroless)
|
||||
src:
|
||||
- hello-world Spring Boot funzionante, con un endpoint /health e
|
||||
un endpoint di esempio /api/v1/ping
|
||||
env:
|
||||
- application-dev.properties
|
||||
- application-staging.properties
|
||||
- application-prod.properties
|
||||
|
||||
# --- Integrazione con servizi cross della piattaforma ---
|
||||
# Fondamentale: dice all'agente COSA NON riproporre perché già
|
||||
# disponibile centralmente (evita duplicazione di servizi)
|
||||
cross_platform_services:
|
||||
- service: shared-postgres
|
||||
how: "via env PLATFORM_DB_CONNECTION_STRING, iniettata dalla pipeline"
|
||||
- service: shared-redis-cache
|
||||
how: "opzionale, abilitabile via env ENABLE_CACHE=true"
|
||||
- service: centralized-logging
|
||||
how: "automatico, nessuna configurazione richiesta"
|
||||
|
||||
# --- Vincoli di compliance soddisfatti dal template ---
|
||||
compliance:
|
||||
data_classification_supported: ["public", "internal", "confidential"]
|
||||
# NON supporta dati PII senza customizzazioni aggiuntive
|
||||
pii_ready: false
|
||||
network_policy_baseline: "default-deny"
|
||||
security_scanning: "incluso in pipeline (SAST + container scan)"
|
||||
|
||||
scaling:
|
||||
default_replicas: 2
|
||||
autoscaling: hpa
|
||||
min_replicas: 2
|
||||
max_replicas: 10
|
||||
|
||||
# --- Parametri personalizzabili (quelli nei file in env/) ---
|
||||
parameters:
|
||||
- name: PLATFORM_DB_CONNECTION_STRING
|
||||
required: false
|
||||
description: "Richiesta solo se il servizio necessita persistenza"
|
||||
- name: ENABLE_CACHE
|
||||
required: false
|
||||
default: "false"
|
||||
|
||||
# --- Quando NON usare questo template (altrettanto utile del 'quando sì') ---
|
||||
not_suitable_for:
|
||||
- "Workload asincroni basati su eventi (usa tpl-java-kafka-consumer)"
|
||||
- "Batch job schedulati (usa tpl-batch-job)"
|
||||
- "Dati classificati come PII senza data masking aggiuntivo"
|
||||
Reference in New Issue
Block a user