Geração de documentação do código de infraestrutura
Dica
Consulte a guia Texto e imagens para obter mais detalhes!
O código de infraestrutura é notoriamente sub-documentado. Um modelo de Bicep pode implantar corretamente uma arquitetura complexa, de várias camadas. Mas se ninguém documentou o que ele implanta, por que cada recurso existe ou o que os parâmetros controlam, o modelo se torna conhecimento tribal. Somente a pessoa que o escreveu pode alterá-lo com segurança.
Essa lacuna existe porque a documentação é entediante para escrever e fácil de ignorar. Depois de concluir e validar um modelo de Bicep de 400 linhas, escrever uma descrição de arquitetura correspondente parece um projeto à parte.
GitHub Copilot altera essa equação. Dado um modelo, Copilot pode gerar um primeiro rascunho da documentação em segundos. O trabalho do engenheiro muda de escrever documentação para revisá-la e refina-la. A documentação deixa de ser opcional e começa a fazer parte do fluxo de trabalho normal.
Gerando descrições de arquitetura de linguagem simples
A necessidade de documentação mais imediata é uma explicação legível pelo ser humano do que um modelo implanta. Esse nível de documentação é o que um gerente de projeto, um revisor de segurança ou um novo membro da equipe precisam para entender ou trabalhar com a infraestrutura.
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]
A instrução da estrutura é importante. Sem ele, Copilot produz uma lista simples de recursos em vez de uma explicação que transmite a intenção da arquitetura.
Estrutura de saída de exemplo
Para um modelo de rede hub-spoke, uma explicação bem estruturada pode ter esta aparência:
## 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
Gerando documentação de referência de parâmetro
Modelos com muitos parâmetros são difíceis de usar sem documentação. Uma tabela de referência de parâmetro informa aos usuários o que cada parâmetro faz, quais valores são válidos e quais são os padrões.
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 gera essa tabela com precisão porque lê os decoradores @description(), @allowed() e @minLength() diretamente do modelo. Se o modelo não tiver decoradores, o Copilot infere as descrições com base nos nomes dos parâmetros. O que é outro motivo para usar nomes de parâmetro descritivo ao gerar modelos.
Referência para geração 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 exemplo é útil para saídas de módulo consumidas por outros modelos. A documentação de saída informa ao chamador o que ele recebe e em que formato isso é fornecido.
Criando diagramas de arquitetura com a Sereia
Mermaid é uma linguagem de criação de diagramas baseada em texto que tem suporte nativo no GitHub Markdown, no Azure DevOps Wiki e no VS Code. Ele renderiza diagramas de texto sem formatação. Isso significa que os diagramas podem ficar no mesmo repositório que o código de infraestrutura, versionados e atualizados junto com os templates.
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.
Os diagramas Mermaid nem sempre ficam perfeitos nos mínimos detalhes na primeira geração. Peça ao Copilot para ajustar o layout, adicionar ou remover componentes, ou alterar o tipo de diagrama com base no que é melhor renderizado.
Validação de diagrama
Visualize o diagrama no VS Code usando a visualização Markdown (Ctrl+Shift+V). Se o GitHub renderiza Mermaid no README do seu repositório, faça push do arquivo e verifique o resultado renderizado lá. O renderizador do GitHub tem um comportamento ligeiramente diferente do do VS Code.
Se o diagrama for muito complexo para ser renderizado de forma limpa, peça Copilot para 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.
Gerando resumos de alterações
Quando a infraestrutura é alterada, alguém precisa examinar o que mudou. Descrições de pull requests como “modelo Bicep atualizado” não fornecem nenhuma informação útil ao revisor. Copilot pode gerar resumos de alterações significativos comparando duas versões de um modelo.
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 resumo de alterações pode ser utilizado imediatamente como descrição de uma solicitação de pull, como comunicação às partes interessadas ou como seção em um manual de implantação.
Exemplo de saída de resumo de alterações
## 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.
Manter a documentação em sincronia
A falha de documentação mais comum é a desatualização. Um documento escrito quando o modelo era a versão 1 torna-se enganoso pela versão 5.
Várias práticas ajudam a manter a precisão ao longo do tempo.
Gere a documentação como parte do processo de PR. Adicione uma etapa ao seu pipeline de integração contínua que sinalize o PR para revisão da documentação quando o modelo sofrer alterações significativas.
Use os decoradores @description() como a fonte da verdade. A documentação inserida no modelo por meio de decoradores está sempre em sincronia com o código porque ele reside no mesmo arquivo. A documentação externa em Markdown pode ficar desatualizada.
Gere documentação para cada versão principal. Use o prompt de resumo de alterações após cada fusão significativa com o branch principal. Envie a documentação atualizada no mesmo PR em que foi feita a alteração no modelo.
Prompt para atualização do 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