Generación de documentación a partir del código de infraestructura
Tip
Consulte la pestaña Texto e imágenes para obtener más detalles.
El código de infraestructura suele estar muy poco documentado. Una plantilla de Bicep puede implementar correctamente una arquitectura compleja de varios niveles. Pero si nadie documentó lo que implementa, por qué existe cada recurso o cuáles son los parámetros que controlan, la plantilla se convierte en conocimientos tribales. Solo la persona que lo escribió puede cambiarla de forma segura.
Esta brecha existe porque la documentación es tediosa de escribir y es fácil de omitir. Después de finalizar y validar una plantilla de Bicep de 400 líneas, escribir una descripción de arquitectura coincidente se parece a un proyecto independiente.
GitHub Copilot cambia esta ecuación. Dada una plantilla, Copilot puede generar un primer borrador de la documentación en segundos. El trabajo del ingeniero cambia de escribir documentación a revisarla y refinarla. La documentación deja de ser opcional y comienza a formar parte del flujo de trabajo normal.
Generación de descripciones de arquitectura de lenguaje simple
La necesidad de documentación más inmediata es una explicación legible de lo que implementa una plantilla. Este nivel de documentación es lo que necesita un administrador de proyectos, un revisor de seguridad o un nuevo miembro del equipo para poder comprender o trabajar con la infraestructura.
Explain what this Bicep template deploys in plain language.
Structure your explanation as follows:
1. A one-paragraph summary of the overall architecture
2. A section for each major resource group or logical component,
describing what it does and why it exists
3. A description of how the components connect to each other
4. Any security controls that are configured
Use language that a technical project manager could understand.
Avoid Bicep-specific syntax in the explanation.
[paste template here]
La instrucción sobre la estructura es importante. Sin ella, Copilot genera una lista plana de recursos en lugar de una explicación que transmite la intención de la arquitectura.
Estructura de salida de ejemplo
Para una plantilla de red hub-spoke, una explicación bien estructurada podría tener este aspecto:
## Architecture Overview
This template deploys a hub-and-spoke network topology for Azure, a standard
pattern for enterprise environments that need centralized security controls
alongside segmented workload networks.
## Hub Network
The hub virtual network (10.0.0.0/16) is the central connection point for all
network traffic. It hosts the Azure Firewall, which inspects and filters all
traffic entering and leaving the environment. It also contains an Azure Bastion
host, which provides secure browser-based access to virtual machines without
exposing RDP or SSH ports to the internet.
## Spoke Network
The spoke virtual network (10.1.0.0/16) is where application workloads run.
It connects to the hub through VNet peering, a low-latency, private connection
within the Azure backbone. Traffic from the spoke to the internet is routed
through the hub firewall, ensuring all outbound connections are inspected.
## Observability
A Log Analytics workspace collects diagnostic logs from the Azure Firewall.
This enables security monitoring, threat detection, and compliance auditing
from a single location.
## Security Controls
- All internet-bound traffic from workloads is inspected by Azure Firewall
- No management ports (SSH, RDP) are exposed directly to the internet
- Network access to VMs is restricted to Azure Bastion sessions only
Generar documentación de referencia de parámetros
Las plantillas con muchos parámetros son difíciles de usar sin documentación. Una tabla de referencia de parámetros indica a los usuarios qué hace cada parámetro, qué valores son válidos y cuáles son los valores predeterminados.
Generate a markdown parameter reference table for this Bicep template.
Include these columns:
| Parameter | Type | Default | Allowed Values | Description |
Cover all parameters. For parameters with @allowed() decorators,
list the allowed values. For parameters with no default, mark the
Default column as "Required". Write descriptions in plain language,
not a repeat of the parameter name.
Copilot genera esta tabla con precisión porque lee los decoradores @description(), @allowed() y @minLength() directamente desde la plantilla. Si la plantilla carece de decoradores, Copilot deduce descripciones de los nombres de parámetro. Otra razón para usar nombres de parámetro descriptivos al generar plantillas.
Referencia de generación de resultados
Add a second table below the parameters table documenting all outputs
from this template. Include: Output Name | Type | Description.
Describe what each output contains and when you would use it.
Este ejemplo es útil para las salidas de módulo consumidas por otras plantillas. La documentación de salida indica al autor de la llamada lo que reciben y en qué formato está.
Creación de diagramas de arquitectura con Sirena
Mermaid es un lenguaje de diagramas basado en texto compatible de forma nativa en GitHub Markdown, Azure DevOps Wiki y VS Code. Genera diagramas a partir de texto sin formato. Esto significa que los diagramas pueden residir en el mismo repositorio que el código de infraestructura, con versiones y actualizados junto con las plantillas.
Represent the network topology deployed by this Bicep template as a Mermaid diagram.
Use flowchart LR (left to right) direction.
Show:
- Each VNet as a subgraph
- Subnets as nodes inside their VNet subgraph
- Resources (Firewall, Bastion, VMs) as nodes in the appropriate subnet
- VNet peering as a double-headed arrow between VNets
- The Log Analytics workspace outside the VNets, with a log collection arrow
from the Firewall
- Use descriptive labels on each node showing the resource name and type
Wrap the Mermaid code in a markdown code block with the mermaid language tag.
Los diagramas de Mermaid no siempre son perfectos para píxeles en la primera generación. Pídele a Copilot que ajuste el diseño, añada o quite componentes, o cambie el tipo de diagrama según lo que se visualice mejor.
Validación de diagramas
Obtenga una vista previa del diagrama en VS Code mediante la vista previa de Markdown (Ctrl+Shift+V). Si GitHub renderiza Mermaid en el archivo README de tu repositorio, sube el archivo y comprueba allí el resultado renderizado. El renderizador de GitHub tiene un comportamiento ligeramente distinto al de VS Code.
Si el diagrama es demasiado complejo para representarse de forma limpia, pida Copilot simplificar:
Simplify this Mermaid diagram to show only the major components and their
connections. Remove subnet-level detail and focus on the resource relationships
at the VNet level.
Generación de resúmenes de cambios
Cuando cambia la infraestructura, alguien debe revisar lo que ha cambiado. Las descripciones de solicitudes de incorporación de cambios como "plantilla de Bicep actualizada" no proporcionan información útil para un revisor. Copilot puede generar resúmenes de cambios significativos comparando dos versiones de una plantilla.
Compare these two Bicep templates (v1 and v2) and generate a change summary
in markdown format.
For each change, include:
- What changed (resource added, modified, or removed)
- Why it likely changed (e.g., added for security, added for observability,
fixed a misconfiguration)
- Impact on existing deployments (e.g., requires redeployment, causes downtime,
is additive only)
Group changes by category: Security, Observability, Networking, Compute, Cost.
--- v1 template ---
[paste old template]
--- v2 template ---
[paste new template]
Este resumen de cambios es útil de inmediato como descripción de una pull request, comunicación para las partes interesadas o sección de una guía de despliegue.
Ejemplo de salida del resumen de cambios
## Infrastructure Change Summary — v1 to v2
### Security
- **Added:** AzureFirewallSubnet resized from /27 to /26
- *Why:* Azure Firewall requires a minimum /26 subnet. The /27 caused deployment failures.
- *Impact:* Requires redeployment of the hub VNet. Existing peering will need to be re-established.
- **Added:** CostCenter tag on all resources
- *Why:* Azure Policy requires a CostCenter tag. Missing tag caused policy denial.
- *Impact:* Additive only. No resource changes.
### Observability
- **Added:** Azure Bastion host in AzureBastionSubnet
- *Why:* Provides browser-based secure access to VMs without exposing management ports.
- *Impact:* Additive. New resource. Costs approximately $140/month per Bastion instance.
- **Added:** Log Analytics Workspace and Firewall diagnostic settings
- *Why:* Required for security monitoring and compliance auditing.
- *Impact:* Additive. Data ingestion costs depend on log volume.
Mantener la documentación sincronizada
El error de documentación más común es obsolescencia. Un documento escrito cuando la plantilla era la versión 1 se vuelve engañosa en la versión 5.
Varias prácticas ayudan a mantener la precisión con el tiempo.
Genere documentación como parte del proceso de PR. Agregue un paso a su canalización de CI que marque la solicitud de compra para la revisión de la documentación cuando la plantilla cambie de forma significativa.
Use decoradores @description() como origen de confianza. La documentación insertada en la plantilla a través de decoradores siempre está sincronizada con el código porque reside en el mismo archivo. La documentación externa de Markdown puede estar desfasada.
Genere documentación para cada versión principal. Utilice el mensaje de resumen de cambios después de cada fusión importante en la versión principal. Confirme la documentación actualizada en la misma solicitud de compra que el cambio de plantilla.
Texto para una actualización de README:
The following changes were made to our infrastructure template in this release:
[paste change summary]
Update the Infrastructure README to reflect these changes. Specifically:
- Update the Architecture Overview section to mention Azure Bastion
- Add the new CostCenter parameter to the parameter reference table
- Update the "Resources Deployed" list