[Module Proposal]: `avm-res-iotoperations-instance`

### Check for previous/existing GitHub issues/module proposals

- [x] I have checked for previous/existing GitHub issues/module proposals.

### Check this module doesn't already exist in the module indexes

- [x] I have checked for that this module doesn't already exist in the module indexes.

### Bicep or Terraform?

Terraform

### Module Classification?

Resource Module

### Module Name

Terraform: `avm-res-iotoperations-instance`

### Module Details

# Azure Verified Module (AVM) Proposal: Azure IoT Operations Terraform Resource Module

## Overview

- **Primary Resource**: `Microsoft.IoTOperations/instances` - Azure IoT Operations instance
- **Module Purpose**: Deploys a complete Azure IoT Operations solution on Azure Arc-enabled Kubernetes clusters with WAF-aligned best practices and security configurations
- **Module Type**: Resource Module
- **Target Resource Provider**: Microsoft.IoTOperations
- **Infrastructure as Code**: Terraform/OpenTofu
- **Reference Documentation**: [Microsoft.IoTOperations/instances AzApi template reference](https://learn.microsoft.com/en-us/azure/templates/microsoft.iotoperations/instances?pivots=deployment-language-terraform)

## Primary Resources Included

- **Azure IoT Operations Instance** (`Microsoft.IoTOperations/instances@2025-04-01`)
- Core IoT Operations instance with schema registry integration
- User-assigned managed identity configuration
- Feature flags and capabilities configuration with validation

- **MQTT Broker Configuration** (`Microsoft.IoTOperations/instances/brokers@2025-04-01`)
- Default broker with configurable memory profiles (Low, Medium, High) and cardinality settings
- Service Account Token authentication configuration with configurable audiences
- Secure TLS-enabled listeners with automatic certificate management
- Optional anonymous listeners for development/testing scenarios

- **Data Flow Components**
- Data Flow Profiles (`Microsoft.IoTOperations/instances/dataflowProfiles@2025-04-01`)
- Data Flow Endpoints (`Microsoft.IoTOperations/instances/dataflowEndpoints@2025-04-01`)
- Configurable instance counts and MQTT endpoint settings

## Supporting Azure Arc Extensions

- **Azure IoT Operations Platform Extension** (`microsoft.iotoperations.platform`)
- Certificate manager and trust manager installation (configurable)
- Core platform components required for IoT Operations
- Version and release train configuration

- **Azure IoT Operations Extension** (`microsoft.iotoperations`)
- Main IoT Operations runtime components
- Configurable namespace, Kubernetes distribution (K3s, K8s, MicroK8s), and timeout settings
- Comprehensive configuration settings for connectors, MQTT broker, and observability

- **Secret Store Extension** (`microsoft.azure.secretstore`)
- Integration with Azure Key Vault for secret management
- Configurable rotation polling intervals and validation policies

- **Container Storage Extension** (`microsoft.arc.containerstorage`)
- Fault-tolerant storage configuration options
- Custom storage class and mount point configuration
- Version and release train management

- **Open Service Mesh Extension** (`microsoft.openservicemesh`)
- Service mesh capabilities for secure service-to-service communication
- Performance-optimized configuration settings with resource limits

## Custom Location and Resource Sync

- **Custom Location** (`Microsoft.ExtendedLocation/customLocations@2021-08-31-preview`)
- Enables deployment of Azure resources to on-premises Kubernetes clusters
- Automatic cluster extension ID management
- System-assigned managed identity configuration

- **Resource Sync Rules** (`Microsoft.ExtendedLocation/customLocations/resourceSyncRules@2021-08-31-preview`)
- Optional automatic synchronization of IoT Operations resources
- Device Registry integration for asset management
- Configurable priority-based resource synchronization

## Optional Supporting Resources

- **User-Assigned Managed Identities** (`azurerm_user_assigned_identity`)
- IoT Operations identity for accessing Azure resources and schema registry operations
- Secret Sync identity for Key Vault integration and secret synchronization
- Optional creation with federated identity credentials for Kubernetes service accounts
- Can be pre-created or optionally created by module for maximum flexibility

- **Azure Device Registry Schema Registry** (`Microsoft.DeviceRegistry/schemaRegistries@2024-09-01-preview`)
- Schema registry for data processing and transformation operations
- Optional creation when not using existing registry
- Integration with IoT Operations instance for data flow operations
- Storage account integration for schema storage and management
- Reference: [Microsoft.DeviceRegistry/schemaRegistries AzApi template reference](https://learn.microsoft.com/en-us/azure/templates/microsoft.deviceregistry/schemaregistries?pivots=deployment-language-terraform)

## Security and Identity Features

- **Managed Identity Integration**
- User-assigned managed identity for IoT Operations
- Federated identity credentials for Kubernetes service accounts
- Key Vault access with least-privilege RBAC roles

- **Trust and Certificate Management**
- Self-signed certificate support (default)
- Customer-managed certificate authority options
- Trust issuer and bundle configuration

- **Role-Based Access Control**
- Azure Arc Kubernetes cluster operator roles
- Key Vault secrets user and officer roles
- Deployment identity permissions

## Optional Components

- **OPC UA Simulator**
- Asset endpoint profiles and assets for testing
- Configurable OPC UA server simulation

- **OpenTelemetry Collector**
- Metrics and telemetry collection
- Integration with Azure Monitor

- **Deployment Scripts**
- Post-deployment configuration automation
- Key Vault-based script storage and execution

## WAF Alignment Features

- **Security Best Practices**
- Default encryption and authentication enabled
- Secure secret management with Azure Key Vault
- Network isolation with service mesh

- **Reliability and Availability**
- Configurable redundancy factors for broker components
- Fault-tolerant storage options
- Health monitoring and metrics collection

- **Operational Excellence**
- Standardized configuration patterns
- Automated deployment scripts
- Comprehensive logging and monitoring

## External Dependencies (Not Deployed)

- **Azure Arc-enabled Kubernetes Cluster** - Must exist before deployment
- **Azure Key Vault** - Required for secret synchronization and deployment script storage
- **Azure Storage Account** - Required for ADR Schema Registry operations
- **User-Assigned Managed Identities** - Can be pre-created or optionally created by module
- **Azure Device Registry Schema Registry** - Can be pre-created or optionally created by module

## Configuration Flexibility

- **Kubernetes Distribution Support** - K3s, K8s, MicroK8s
- **Memory Profiles** - Low, Medium, High for different workload requirements
- **Storage Configuration** - Fault-tolerant vs. standard storage options
- **Trust Models** - Self-signed, customer-managed certificates
- **Feature Toggles** - OPC UA simulator, OpenTelemetry, anonymous listeners
- **Resource Creation Options** - Optional creation of managed identities and schema registry vs. using existing resources

## Customer Experience Benefits

- **Complete Solution** - Single module deploys entire IoT Operations stack
- **Production Ready** - WAF-aligned security and reliability defaults
- **Flexible Configuration** - Supports development to production scenarios
- **Integrated Security** - Built-in identity, secrets, and certificate management
- **Extensible** - Optional components for different use cases
- **Resource Management** - Option to create or use existing supporting resources for maximum flexibility

## Resource Naming and Tagging

- **Consistent Naming** - Follows Azure naming conventions with configurable prefixes
- **Resource Tagging** - Standard tags for cost management and governance
- **Environment Support** - Development, test, production configuration patterns

## API Versions and Compatibility

- **Latest Stable APIs** - Uses current stable API versions where available
- **Preview API Support** - Leverages preview APIs for latest IoT Operations features
- **Version Management** - Configurable extension versions with auto-upgrade options

### Do you want to be the owner of this module?

Yes

### Module Owner's GitHub Username (handle)

agreaves-ms

### (Optional) Secondary Module Owner's GitHub Username (handle)

WilliamBerryiii