Idempotency: Safe to Retry Automation

WHY IT EXISTS: Automation scripts run in unreliable environments where networks drop and servers crash. If a script fails halfway through, you need to be able to run it again without making things worse. Idempotency solves the problem of 'is it safe to retry?' by ensuring that re-running a completed or partially completed task doesn't cause duplicate actions or errors.

THE MENTAL MODEL: An idempotent operation is like a light switch. Pressing it once turns the light on. Pressing it again doesn't change the state; the light stays on. The action (pressing the switch) is idempotent because the result (light is on) is stable after the first successful application. An idempotent script doesn't care if the system is already in the desired state; it just ensures it gets there.

HOW IT WORKS: Idempotency is achieved by checking the system's current state before taking action. Instead of an imperative command like 'create user X,' an idempotent script uses a declarative goal: 'ensure user X exists.' It first checks if the user is present. If so, it does nothing. If not, it creates the user. This 'check-then-act' pattern is the core mechanism. Tools like Ansible or Terraform abstract this away; you define the target state, and their engines calculate the necessary changes.

WHEN TO USE IT: Use idempotency for any automated task that might be run more than once, especially in failure scenarios. This includes server configuration management (installing packages, managing files), infrastructure provisioning (creating cloud resources), CI/CD deployment pipelines, and database schema migrations. It is the foundation of reliable, repeatable automation.

WHEN NOT TO USE IT: Idempotency is the wrong goal for operations that are inherently cumulative. For example, sending a notification, appending a log entry, or processing a payment are typically non-idempotent by design; you want each execution to have a distinct effect. For these, you need different safety mechanisms, like transactional guarantees or exactly-once processing systems.

ONE CANONICAL EXAMPLE: Consider managing a user account. A non-idempotent script might run useradd myuser. Running this twice fails because the user already exists. An idempotent approach is to first check if myuser exists, and only run useradd myuser if they do not. In a tool like Ansible, you simply declare the goal: user: name=myuser state=present. The state=present instruction makes the operation idempotent; Ansible handles the underlying check automatically. Running this task 100 times results in one user, with subsequent runs reporting 'OK' or 'unchanged' instead of failing.