Python Azure Iot Edge Modules

---
name: python-azure-iot-edge-modules
description: 'Build and operate Python Azure IoT Edge modules with robust messaging, deployment manifests, observability, and production readiness checks.'
---

# Python Azure IoT Edge Modules

Use this skill to design, implement, and validate Python-based IoT Edge modules for telemetry processing, local inference, protocol translation, and edge-to-cloud integration.

## When To Use

Use this skill for requests like:

- "quiero crear un modulo Python para IoT Edge"
- "como despliego modulos edge con manifest"
- "necesito filtrar/agregar telemetria antes de subirla"
- "como manejo desconexiones y reintentos en edge"

## Mandatory Docs Review

Before recommending runtime behavior or deployment decisions, review:

- https://learn.microsoft.com/azure/iot-edge/
- https://learn.microsoft.com/es-es/azure/iot-edge/

Minimum checks:

- Runtime architecture and module lifecycle.
- Supported host OS and versions.
- Deployment model and configuration flow.
- Current release/version guidance.

If documentation cannot be fetched, proceed with explicit assumptions and flag them clearly.

## Python Official References and Best Practices (Required)

Before proposing Python implementation details, consult official Python sources:

- https://www.python.org/
- https://docs.python.org/3/
- https://docs.python.org/3/reference/
- https://docs.python.org/3/library/
- references/python-official-best-practices.md

Prefer official docs over community snippets unless there is a specific compatibility reason to deviate.

## Goals

- Deliver module architecture and implementation plan that is production-focused.
- Ensure reliable edge messaging under network variability.
- Provide deployment, observability, and validation artifacts.

## Module Use Cases

- Protocol adapter (serial/Modbus/OPC-UA to IoT message format).
- Telemetry enrichment and normalization.
- Local anomaly detection or inference.
- Command orchestration and local actuator control.

## Delivery Workflow

### 1) Contract and Interfaces

Define:

- Module inputs and outputs.
- Message schema and versioning policy.
- Routes and priorities for normal vs critical telemetry.
- Desired properties used for dynamic configuration.

### 2) Runtime and Packaging

Specify:

- Python runtime version target.
- Container image strategy (base image, slim footprint, CVE hygiene).
- Resource profile (CPU/memory bounds).
- Startup and health checks.

### 3) Reliability Design

Implement and validate:

- Retries with exponential backoff and jitter.
- Graceful degradation on upstream failures.
- Local queueing strategy where needed.
- Idempotent processing for replayed messages.

### 4) Security Controls

Require:

- No plaintext secrets in code or manifest.
- Least-privilege module behavior.
- Secure transport and trusted cert chain handling.
- Traceability for command handling and state changes.

### 5) Deployment and Operations

Define:

- Environment-specific deployment manifests.
- Rollout strategy (pilot, staged, broad).
- Rollback criteria.
- SLOs and alerting conditions.

## Reuse Other Skills

When relevant, combine with:

- `azure-smart-city-iot-solution-builder` for platform-level architecture.
- `appinsights-instrumentation` for telemetry instrumentation approaches.
- `azure-resource-visualizer` for architecture diagrams and dependency mapping.

Also use `references/python-official-best-practices.md` as baseline quality criteria for module design and implementation guidance.

## Required Output

Always provide:

1. Module design brief (purpose, inputs, outputs).
2. Deployment model (image, manifest, env settings).
3. Reliability and error-handling strategy.
4. Security and operations checklist.
5. Test matrix (functional, chaos, performance, rollback).

## Output Template

1. Context and assumptions
2. Module architecture
3. Deployment and configuration
4. Reliability, security, observability
5. Validation and rollout plan

## Guardrails

- Do not recommend direct production rollout without pilot stage.
- Do not embed secrets in Dockerfiles, source, or manifests.
- Do not omit health probes, restart behavior, and rollback criteria.

# Python IoT Edge Module Template

Use this template to structure implementation proposals and reviews.

## 0) Official Python Baseline

- Official references reviewed from <https://www.python.org/> and <https://docs.python.org/3/>.
- Language and stdlib usage validated against <https://docs.python.org/3/reference/> and <https://docs.python.org/3/library/>.
- Best practices reviewed from `references/python-official-best-practices.md`.

## 1) Module Summary

- Module name:
- Business capability:
- Inputs:
- Outputs:
- Trigger conditions:

## 2) Message Contract

- Schema version:
- Required fields:
- Optional fields:
- Error payload contract:

## 3) Runtime Configuration

- Python version:
- Base image:
- Environment variables:
- Desired properties:
- Resource limits:

## 4) Resilience

- Retry policy:
- Backoff policy:
- Queueing strategy:
- Idempotency approach:
- Timeout and circuit-breaker behavior:

## 5) Security

- Secret source (never inline):
- Identity and permissions:
- Command authorization model:
- Audit log requirements:

## 6) Observability

- Health signals:
- Business metrics:
- Error metrics:
- Correlation/trace requirements:
- Alert thresholds:

## 7) Validation Matrix

- Happy path tests:
- Malformed payload tests:
- Network interruption tests:
- Throughput and latency tests:
- Rollback validation:

# Python Official References and Best Practices

Use these official Python resources before finalizing module architecture or implementation details.

## Official References

- Python home: <https://www.python.org/>
- Python documentation portal: <https://docs.python.org/3/>
- Python tutorial: <https://docs.python.org/3/tutorial/>
- Python language reference: <https://docs.python.org/3/reference/>
- Python standard library reference: <https://docs.python.org/3/library/>
- Python HOWTOs: <https://docs.python.org/3/howto/>
- Installing modules: <https://docs.python.org/3/installing/>
- Distributing modules: <https://docs.python.org/3/distributing/>
- PEP index: <https://peps.python.org/>
- PyPA packaging guide: <https://packaging.python.org/>

## Coding Best Practices

- Target and pin an explicit Python major/minor runtime for each deployment.
- Prefer explicit, readable code paths over clever compact logic.
- Use type hints for public interfaces and critical data transformations.
- Keep module responsibilities focused; separate protocol, business logic, and transport.
- Validate and sanitize external inputs at boundaries.
- Use structured exceptions with actionable error messages.
- Log with enough context for incident triage (correlation id, module id, message id).

## Reliability and Performance Best Practices

- Avoid blocking operations in high-frequency message paths.
- Enforce timeouts and bounded retries with exponential backoff and jitter.
- Design idempotent handlers for replay and duplicate deliveries.
- Use resource limits and monitor memory growth to prevent edge instability.
- Define graceful shutdown behavior to flush buffered state safely.

## Dependency and Supply Chain Best Practices

- Pin dependencies and document upgrade cadence.
- Prefer actively maintained libraries with clear release history.
- Track vulnerabilities and update dependencies regularly.
- Keep container images minimal and patched.

## Testing Best Practices

- Unit test parsing, validation, and routing logic.
- Add integration tests for module I/O boundaries.
- Add chaos tests for network loss, slow upstream, and restart scenarios.
- Verify rollback behavior and state recovery in deployment tests.