Example: Correcting drift with Idem#

In this example, Idem learns about an existing AWS resource, detects that it has been changed, and restores the resource to its original state.

Use this workflow as a guideline for Idem compliance management in brownfield environments.


This example assumes that the user:

Inspect the existing resource#

Idem doesn’t require that you review your brownfield environment in AWS first, but a quick look might help to confirm that Idem accurately describes existing resources. In this example, it’s an EC2 instance.


Describe the existing resource to Idem#

To retrieve data that describes the instance, enter a describe command from the Idem command line.

idem describe aws.ec2.instance

  - name: i-0f2e6b9b642beaf91
  - resource_id: i-0f2e6b9b642beaf91
  - image_id: ami-094125af156557ca2
  - instance_type: t1.micro
  - volume_attachments:
      /dev/xvda: vol-03724e0febe4632e7
  - block_device_mappings:
    - DeviceName: /dev/xvda
        DeleteOnTermination: true
        Encrypted: false
        Iops: 100
        SnapshotId: snap-078839db345bfeece
        VolumeSize: 8
        VolumeType: gp2
  - ebs_optimized: false
  - subnet_id: subnet-0120b61d6c1313e1f
  - network_interfaces:
    - AssociatePublicIpAddress: false
      DeleteOnTermination: true
      Description: ''
      DeviceIndex: 0
      - sg-43d8c830
      InterfaceType: interface
      Ipv6Addresses: []
      NetworkCardIndex: 0
      - Primary: true
      SubnetId: subnet-0120b61d6c1313e1f
  - monitoring_enabled: false
  - root_device_name: /dev/xvda
  - client_token: eef2732c-95cf-4f05-abdd-2ff04fb4e802
  - product_codes: []
  - source_dest_check: true
  - running: true
  - private_ip_address:
  - reservation_id: r-0282215c32f0d943e
  - owner_id: '840258433862'
  - availability_zone: us-west-2c
  - group_name: ''
  - tenancy: default
  - disable_api_termination: false
  - tags:
      Name: instance-idem-1
      Salutation: Hello World
  - iam_profile_arn: {}
  - instance_initiated_shutdown_behavior: stop
  - auto_recovery_enabled: true
  - sriov_net_support: simple
  - nitro_enclave_enabled: false
  - license_arns: []
  - hibernation_enabled: false
  - valid_until: ''
  - http_tokens: optional
  - http_put_response_hop_limit: 1
  - http_endpoint_enabled: true
  - http_protocol_ipv6_enabled: false
  - metadata_tags_enabled: false
  - hostname_type: ip-name
  - enable_resource_name_dns_a_record: false
  - enable_resource_name_dns_aaaa_record: false
  - capacity_reservation_preference: open
  - bootstrap: []

Create the state file#

In an empty text editor session, paste in the output from the preceding idem describe command, and save the file as my-instance.sls.

Verify the resource state#

To check that the state file accurately describes the instance, enter an idem state command with the --test flag.

idem state my-instance.sls --test

      ID: i-0f2e6b9b642beaf91
Function: aws.ec2.instance.present
  Result: True
 Comment: ["Instance 'i-0f2e6b9b642beaf91' already exists"]

present: 1 no-op

The output reports that there would be no changes, so the state file matches what’s currently on AWS.

Without the --test flag, if there were a mismatch, Idem would have modified the resource to match the state file.

Change the existing resource#

From AWS, use the Manage tags option to change Hello to Goodbye.

This example only changes a simple tag, but a dynamic environment might have many changes that Idem needs to correct.


Correct the drift#

From the Idem command line, rerun the same idem state command to bring the instance back into compliance.

Consider running the command twice, first with the --test flag so that you can review what will change, then without --test to actually make those changes.

idem state instance.sls

      ID: i-0f2e6b9b642beaf91
Function: aws.ec2.instance.present
  Result: True
 Comment: ("Update tags: Add keys dict_keys(['Salutation']) Remove keys dict_keys(['Salutation'])",)
            Goodbye World
            Hello World

present: 1 updated successfully

The output reports the change back to Hello.

To verify the restoration, you can inspect the instance in AWS or rerun a describe command.