Engineering Conventions

convention.md

Aider Architect Prompt Sample

/architect Create an azd bicep project following conventions.
Using AVM modules create: User Managed Identity, Key Vault, AKS in eastus2.

Aider Conf Settings

.aider.conf.yml

chat-language: "en"
cache-prompts: false
auto-commits: false
read:
  - conventions.md
  - modules.md

Project Conventions

• An infrastructure project has a well defined file and folder structure clearly seperating infrastucture, charts and software.

• An infrastucture project always uses and supports Azure Developer CLI. (azd).

├── infra
│   ├── main.bicep
│   ├── main.parameters.json
│   └── modules
├── charts
│   └── sample
│       ├── Chart.yaml
│       ├── values.yaml
│       ├── README.md
│       └── templates
│           ├── deployment.yaml
│           └── service.yaml
├── software
│   └── kustomize.yaml
|   └── components
|       ├── source.yaml
│       ├── deployment.yaml
│       └── namespace.yaml
├── azure.yaml
├── .gitignore
└── README.md

• AZD projects always have an azure.yaml file that specifies bicep as the provider.

metadata:
  template: <project_name>@0.0.1
infra:
  provider: bicep
  path: infra

Code Quality

• Write clean, readable, and maintainable code.

• Follow established Bicep coding standards and guidelines.

• Use meaningful variable and parameter names.

Documentation

• Document with comments only where helpful.

• Maintain up-to-date README and other relevant documentation.

• Provide examples and usage instructions for modules, components or charts.

Bicep Conventions

• Resource groups should normally not be created and the target scope of the main.bicep should be set to resourceGroup.

• Bicep solutions should use a simple configuration or settings object.

• Resource names should have a common unique naming pattern but be limited to 24 characters

Example Configuration

@description('Sample Configuration Object')
var configuration = {
  name: 'main'
  displayName: 'Main Resources'
  vault: {
    sku: 'standard'
  }
  cluster: {
    sku: 'Base'
    tier: 'Standard'
    vmSize: vmSize
  }
}

@description('Sample Unique Name')
var rg_unique_id = '${replace(configuration.name, '-', '')}${uniqueString(resourceGroup().id, configuration.name)}'

Module Usage

• Resources should use public modules from Azure Verified Modules (avm) where possible.
• AVM modules are reference with the following format br/public:avm/res/:.

Example Resources

module managedCluster 'br/public:avm/res/container-service/managed-cluster:<version>' = {
  name: 'managedClusterDeployment'
  params: {
    // Required parameters
    name: length(rg_unique_id) > 24 ? substring(rg_unique_id, 0, 24) : rg_unique_id
    primaryAgentPoolProfiles: [
      {
        count: 3
        mode: 'System'
        name: 'systempool'
        vmSize: 'Standard_DS2_v2'
      }
    ]
    // Non-required parameters
    location: '<location>'
    managedIdentities: {
      systemAssigned: false  
      userAssignedResourcesIds: [
        identity.outputs.resourceId
      ]
    }
  }
}

Parameters

• Use camelCase for parameter names.
• Use descriptive names that clearly indicate the purpose of the parameter.
• Do not use prefixes.
• Use decorators to provide additional information about parameters.

Flux Conventions

• Use version control for Flux definitions.
• Document Flux configurations and policies.
• Validate Flux configurations with flux check.
• Monitor Flux deployments and reconcile states.

Component Structure

• Each component should typically include three files:
  • namespace.yaml
  • source.yaml
  • release.yaml (or helmrelease.yaml)

File Naming

• Use lowercase for all file names.
• Use descriptive, standard names: namespace.yaml, source.yaml, release.yaml.

YAML Structure

• Use 2-space indentation for YAML files.
• Include a comment at the top of each file describing its purpose.

Namespace Conventions

• Define one namespace per file.
• Use lowercase, hyphenated names for namespaces.
• Include labels for better organization and filtering.

Source Conventions

• Use HelmRepository for Helm chart sources.
• Specify a meaningful name for the HelmRepository.
• Include the repository URL and potentially the reference branch or tag.

HelmRelease Conventions

• Name the HelmRelease after the application it deploys.
• Specify the namespace where the release should be installed.

Helm Chart Conventions

• Use version control for Helm charts.
• Document Helm chart values and configurations.
• Validate Helm charts with helm lint.
• Maintain a consistent structure for Helm charts.

Chart Names

• Use lowercase letters and numbers only.
• Words may be separated with dashes (-).
• Do not use uppercase letters, underscores, or dots.

Version Numbers

• Use SemVer 2 for version numbers where possible.
• When storing SemVer versions in Kubernetes labels, replace '+' with '_'.

YAML Formatting

• Indent YAML files using two spaces (never tabs).
• Keep generated templates' whitespace to a minimum.
• Use empty lines sparingly to separate logical sections.

Values

• Use camelCase for variable names (e.g., chickenNoodleSoup: true).
• Prefer flat structures over nested for simplicity.
• Quote all strings explicitly to avoid type conversion issues.
• Consider storing integers as strings and use {{ int $value }} in templates.

Values Documentation

• Document every property in values.yaml.
• Begin each comment with the name of the property it describes.
• Provide at least a one-sentence description for each property.

Templates Structure

• Use .yaml extension for files producing YAML output, .tpl for others.
• Use dashed notation for template file names (e.g., my-configmap.yaml).
• Create separate files for each resource definition.
• Include the resource kind in the template file name.

Defined Templates

• Namespace all defined template names to avoid conflicts.
• Use {{ define "chart.resourceName" }} format.

Template Formatting

• Add whitespace after opening and before closing template directives.
• Chomp whitespace where possible using - in directives.

Comments

• Use YAML comments (#) for notes visible during debugging.
• Use template comments ({{/* */}}) for template documentation.
• Be cautious with YAML comments near required Helm values.

JSON in Templates

• Use JSON syntax for improved readability of simple structures.
• Stick to YAML for more complex constructs.

General Practices

• Create new charts using the helm create command.
• Consider how users might override values with -f or --set.
• Structure values.yaml to be easily overridden.