Creating or updating resources with Idem#

To have Idem create or update a resource, apply states that make use of the present directive.

Prerequisites#

Connect Idem to the host environment and set up authentication. See Connecting Idem to providers and Authenticating Idem with providers.
Be familiar with the resources, resource types, and attributes from the API of your provider.

Describing resources#

When creating or updating resources, you need a state (SLS) file. The file contents can be generated with the Idem describe command, be hand written, or be assembled by combining the two approaches. The file should include resource data that follows this pattern:

state-name:
  plug-in.resource.type.present:
    - attribute1: xxxxxxxx
    - attribute2: xxxxxxxx
    - attribute3: xxxxxxxx

Where:

`state-name`	Unique identifier for this resource state
`plug-in`	The provider environment from your credentials file
`resource`	A supported resource for your plug-in, from the provider API
`type`	The supported resource type, from the provider API
`present`	The directive to create or update the resource to match the attributes shown

For example:

instance-idem-test:
  aws.ec2.instance.present:
    - image_id: ${exec:test_ami:resource_id}
    - instance_type: 't1.micro'
    - subnet_id: ${aws.ec2.subnet:subnet-idem-test:resource_id}
    - tags:
        Name: 'instance-idem-demo'

In the preceding example, note that some attributes use argument binding to derive values from elsewhere in the SLS file. Although the example shows one state, a single SLS file may contain many states in order to fully manage a large group of resources.

Testing and running the state command#

To test the create or update action without making real changes, use the Idem state command with the --test argument.

idem state path-to-state-file/my-resource-group.sls --test

The command output gives you a report on what would be created or modified.

To actually apply the create or update action, remove the --test argument.

idem state path-to-state-file/my-resource-group.sls

The command output gives you a report on what was actually created or modified.

Rerunning the state command#

If you were to immediately rerun the same state command, nothing additional would be created or updated. On the other hand, if resources had been changed by a third party, rerunning the command would restore them.

When rerunning a state, be aware that simply removing a line from a present directive doesn’t remove its attribute. You must proactively supply an empty value. See the following example, where a test tag is initially created with present to be an attribute of the instance.

instance-idem-test:
  aws.ec2.instance.present:
    - image_id: ${exec:test_ami:resource_id}
    - instance_type: 't1.micro'
    - subnet_id: ${aws.ec2.subnet:subnet-idem-test:resource_id}
    - tags:
        Name: 'test'

Rerunning the state with the following code change to remove tags: doesn’t remove the test tag from the instance.

aws.ec2.instance.present:
  - image_id: ${exec:test_ami:resource_id}
  - instance_type: 't1.micro'
  - subnet_id: ${aws.ec2.subnet:subnet-idem-test:resource_id}

However, rerunning the state with the following code does.

aws.ec2.instance.present:
  - image_id: ${exec:test_ami:resource_id}
  - instance_type: 't1.micro'
  - subnet_id: ${aws.ec2.subnet:subnet-idem-test:resource_id}
  - tags: {}

Alternatively, you achieve the same removal by running the absent directive as shown in the following code example. For more about the absent directive, see Deleting resources with Idem.

aws.ec2.instance.absent:
  - tags:
      Name: 'test'

Note

A single SLS file can include both present and absent operations, so one file and command can establish resources that you want to exist or not exist.

In addition, you can run an idem state command with the --invert option, which removes what would normally be created with present, and vice versa.