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.

Prerequisites

This example assumes that the user:

• Has an AWS account
• Installed Idem
• Installed the idem-aws plugin
• Set up Idem authentication to the AWS account

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

i-0f2e6b9b642beaf91:
  aws.ec2.instance.present:
  - 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
      Ebs:
        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
      Groups:
      - sg-43d8c830
      InterfaceType: interface
      Ipv6Addresses: []
      NetworkCardIndex: 0
      PrivateIpAddresses:
      - Primary: true
        PrivateIpAddress: 172.31.17.39
      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: 172.31.17.39
  - 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"]
 Changes:

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'])",)
 Changes:
old:
    ----------
    tags:
        ----------
        Salutation:
            Goodbye World
new:
    ----------
    tags:
        ----------
        Salutation:
            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.