instance_profiles

Creates, updates, deletes, gets or lists an instance_profiles resource.

Overview

Name	instance_profiles
Type	Resource
Id	aws.iam.instance_profiles

Fields

The following fields are returned by SELECT queries:

get_instance_profile

Name	Datatype	Description
arn	string	The Amazon Resource Name (ARN) specifying the instance profile. For more information about ARNs and how to use them in policies, see IAM identifiers in the IAM User Guide.
create_date	string	The date when the instance profile was created.
instance_profile_id	string	The stable and unique string identifying the instance profile. For more information about IDs, see IAM identifiers in the IAM User Guide.
instance_profile_name	string	The name identifying the instance profile.
path	string	The path to the instance profile. For more information about paths, see IAM identifiers in the IAM User Guide.
roles	string	The role associated with the instance profile.
tags	string	A list of tags that are attached to the instance profile. For more information about tagging, see Tagging IAM resources in the IAM User Guide.

list_instance_profiles

Name	Datatype	Description
arn	string	The Amazon Resource Name (ARN) specifying the instance profile. For more information about ARNs and how to use them in policies, see IAM identifiers in the IAM User Guide.
create_date	string	The date when the instance profile was created.
instance_profile_id	string	The stable and unique string identifying the instance profile. For more information about IDs, see IAM identifiers in the IAM User Guide.
instance_profile_name	string	The name identifying the instance profile.
path	string	The path to the instance profile. For more information about paths, see IAM identifiers in the IAM User Guide.
roles	string	The role associated with the instance profile.
tags	string	A list of tags that are attached to the instance profile. For more information about tagging, see Tagging IAM resources in the IAM User Guide.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_instance_profile	select	InstanceProfileName, region		Retrieves information about the specified instance profile, including the instance profile's path, GUID, ARN, and role. For more information about instance profiles, see Using instance profiles in the IAM User Guide.
list_instance_profiles	select	region	PathPrefix, Marker, MaxItems	Lists the instance profiles that have the specified path prefix. If there are none, the operation returns an empty list. For more information about instance profiles, see Using instance profiles in the IAM User Guide. IAM resource-listing operations return a subset of the available attributes for the resource. For example, this operation does not return tags, even though they are an attribute of the returned object. To view all of the information for an instance profile, see GetInstanceProfile. You can paginate the results using the MaxItems and Marker parameters.
create_instance_profile	insert	InstanceProfileName, region	Path, Tags	Creates a new instance profile. For information about instance profiles, see Using roles for applications on Amazon EC2 in the IAM User Guide, and Instance profiles in the Amazon EC2 User Guide. For information about the number of instance profiles you can create, see IAM object quotas in the IAM User Guide.
add_role_to_instance_profile	update	InstanceProfileName, RoleName, region		Adds the specified IAM role to the specified instance profile. An instance profile can contain only one role, and this quota cannot be increased. You can remove the existing role and then add a different role to an instance profile. You must then wait for the change to appear across all of Amazon Web Services because of eventual consistency. To force the change, you must disassociate the instance profile and then associate the instance profile, or you can stop your instance and then restart it. The caller of this operation must be granted the PassRole permission on the IAM role by a permissions policy. When using the iam:AssociatedResourceArn condition in a policy to restrict the PassRole IAM action, special considerations apply if the policy is intended to define access for the AddRoleToInstanceProfile action. In this case, you cannot specify a Region or instance ID in the EC2 instance ARN. The ARN value must be arn:aws:ec2::CallerAccountId:instance/. Using any other ARN value may lead to unexpected evaluation results. For more information about roles, see IAM roles in the IAM User Guide. For more information about instance profiles, see Using instance profiles in the IAM User Guide.
delete_instance_profile	delete	InstanceProfileName, region		Deletes the specified instance profile. The instance profile must not have an associated role. Make sure that you do not have any Amazon EC2 instances running with the instance profile you are about to delete. Deleting a role or instance profile that is associated with a running instance will break any applications running on the instance. For more information about instance profiles, see Using instance profiles in the IAM User Guide.
remove_role_from_instance_profile	exec	InstanceProfileName, RoleName, region		Removes the specified IAM role from the specified Amazon EC2 instance profile. Make sure that you do not have any Amazon EC2 instances running with the role you are about to remove from the instance profile. Removing a role from an instance profile that is associated with a running instance might break any applications running on the instance. For more information about roles, see IAM roles in the IAM User Guide. For more information about instance profiles, see Using instance profiles in the IAM User Guide.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
InstanceProfileName	string	The name of the instance profile to update. This parameter allows (through its regex pattern) a string of characters consisting of upper and lowercase alphanumeric characters with no spaces. You can also include any of the following characters: _+=,.@-
RoleName	string	The name of the role to remove. This parameter allows (through its regex pattern) a string of characters consisting of upper and lowercase alphanumeric characters with no spaces. You can also include any of the following characters: _+=,.@-
region	string	AWS region (default: us-east-1)
Marker	string	Use this parameter only when paginating results and only after you receive a response indicating that the results are truncated. Set it to the value of the Marker element in the response that you received to indicate where the next call should start.
MaxItems	integer	Use this only when paginating results to indicate the maximum number of items you want in the response. If additional items exist beyond the maximum you specify, the IsTruncated response element is true. If you do not include this parameter, the number of items defaults to 100. Note that IAM might return fewer results, even when there are more results available. In that case, the IsTruncated response element returns true, and Marker contains a value to include in the subsequent call that tells the service where to continue from.
Path	string	The path to the instance profile. For more information about paths, see IAM Identifiers in the IAM User Guide. This parameter is optional. If it is not included, it defaults to a slash (/). This parameter allows (through its regex pattern) a string of characters consisting of either a forward slash (/) by itself or a string that must begin and end with forward slashes. In addition, it can contain any ASCII character from the ! (\u0021) through the DEL character (\u007F), including most punctuation characters, digits, and upper and lowercased letters.
PathPrefix	string	The path prefix for filtering the results. For example, the prefix /application_abc/component_xyz/ gets all instance profiles whose path starts with /application_abc/component_xyz/. This parameter is optional. If it is not included, it defaults to a slash (/), listing all instance profiles. This parameter allows (through its regex pattern) a string of characters consisting of either a forward slash (/) by itself or a string that must begin and end with forward slashes. In addition, it can contain any ASCII character from the ! (\u0021) through the DEL character (\u007F), including most punctuation characters, digits, and upper and lowercased letters.
Tags	array	A list of tags that you want to attach to the newly created IAM instance profile. Each tag consists of a key name and an associated value. For more information about tagging, see Tagging IAM resources in the IAM User Guide. If any one of the tags is invalid or if you exceed the allowed maximum number of tags, then the entire request fails and the resource is not created.

SELECT examples

get_instance_profile

Retrieves information about the specified instance profile, including the instance profile's path, GUID, ARN, and role. For more information about instance profiles, see Using instance profiles in the IAM User Guide.

SELECT
arn,
create_date,
instance_profile_id,
instance_profile_name,
path,
roles,
tags
FROM aws.iam.instance_profiles
WHERE InstanceProfileName = '{{ InstanceProfileName }}' -- required
AND region = '{{ region }}' -- required
;

list_instance_profiles

Lists the instance profiles that have the specified path prefix. If there are none, the operation returns an empty list. For more information about instance profiles, see Using instance profiles in the IAM User Guide. IAM resource-listing operations return a subset of the available attributes for the resource. For example, this operation does not return tags, even though they are an attribute of the returned object. To view all of the information for an instance profile, see GetInstanceProfile. You can paginate the results using the MaxItems and Marker parameters.

SELECT
arn,
create_date,
instance_profile_id,
instance_profile_name,
path,
roles,
tags
FROM aws.iam.instance_profiles
WHERE region = '{{ region }}' -- required
AND PathPrefix = '{{ PathPrefix }}'
AND Marker = '{{ Marker }}'
AND MaxItems = '{{ MaxItems }}'
;

INSERT examples

create_instance_profile

Creates a new instance profile. For information about instance profiles, see Using roles for applications on Amazon EC2 in the IAM User Guide, and Instance profiles in the Amazon EC2 User Guide. For information about the number of instance profiles you can create, see IAM object quotas in the IAM User Guide.

INSERT INTO aws.iam.instance_profiles (
InstanceProfileName,
region,
Path,
Tags
)
SELECT 
'{{ InstanceProfileName }}',
'{{ region }}',
'{{ Path }}',
'{{ Tags }}'
RETURNING
arn,
create_date,
instance_profile_id,
instance_profile_name,
path,
roles,
tags
;

Manifest

# Description fields are for documentation purposes
- name: instance_profiles
props:
  - name: InstanceProfileName
    value: "{{ InstanceProfileName }}"
    description: Required parameter for the instance_profiles resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the instance_profiles resource.
  - name: Path
    value: "{{ Path }}"
    description: The path to the instance profile. For more information about paths, see IAM Identifiers in the IAM User Guide. This parameter is optional. If it is not included, it defaults to a slash (/). This parameter allows (through its regex pattern) a string of characters consisting of either a forward slash (/) by itself or a string that must begin and end with forward slashes. In addition, it can contain any ASCII character from the ! (\u0021) through the DEL character (\u007F), including most punctuation characters, digits, and upper and lowercased letters.
    description: The path to the instance profile. For more information about paths, see IAM Identifiers in the IAM User Guide. This parameter is optional. If it is not included, it defaults to a slash (/). This parameter allows (through its regex pattern) a string of characters consisting of either a forward slash (/) by itself or a string that must begin and end with forward slashes. In addition, it can contain any ASCII character from the ! (\u0021) through the DEL character (\u007F), including most punctuation characters, digits, and upper and lowercased letters.
  - name: Tags
    value: "{{ Tags }}"
    description: A list of tags that you want to attach to the newly created IAM instance profile. Each tag consists of a key name and an associated value. For more information about tagging, see Tagging IAM resources in the IAM User Guide. If any one of the tags is invalid or if you exceed the allowed maximum number of tags, then the entire request fails and the resource is not created.
    description: A list of tags that you want to attach to the newly created IAM instance profile. Each tag consists of a key name and an associated value. For more information about tagging, see Tagging IAM resources in the IAM User Guide. If any one of the tags is invalid or if you exceed the allowed maximum number of tags, then the entire request fails and the resource is not created.

UPDATE examples

add_role_to_instance_profile

Adds the specified IAM role to the specified instance profile. An instance profile can contain only one role, and this quota cannot be increased. You can remove the existing role and then add a different role to an instance profile. You must then wait for the change to appear across all of Amazon Web Services because of eventual consistency. To force the change, you must disassociate the instance profile and then associate the instance profile, or you can stop your instance and then restart it. The caller of this operation must be granted the PassRole permission on the IAM role by a permissions policy. When using the iam:AssociatedResourceArn condition in a policy to restrict the PassRole IAM action, special considerations apply if the policy is intended to define access for the AddRoleToInstanceProfile action. In this case, you cannot specify a Region or instance ID in the EC2 instance ARN. The ARN value must be arn:aws:ec2::CallerAccountId:instance/. Using any other ARN value may lead to unexpected evaluation results. For more information about roles, see IAM roles in the IAM User Guide. For more information about instance profiles, see Using instance profiles in the IAM User Guide.

UPDATE aws.iam.instance_profiles
SET 
-- No updatable properties
WHERE 
InstanceProfileName = '{{ InstanceProfileName }}' --required
AND RoleName = '{{ RoleName }}' --required
AND region = '{{ region }}' --required;

DELETE examples

delete_instance_profile

Deletes the specified instance profile. The instance profile must not have an associated role. Make sure that you do not have any Amazon EC2 instances running with the instance profile you are about to delete. Deleting a role or instance profile that is associated with a running instance will break any applications running on the instance. For more information about instance profiles, see Using instance profiles in the IAM User Guide.

DELETE FROM aws.iam.instance_profiles
WHERE InstanceProfileName = '{{ InstanceProfileName }}' --required
AND region = '{{ region }}' --required
;

Lifecycle Methods

remove_role_from_instance_profile

Removes the specified IAM role from the specified Amazon EC2 instance profile. Make sure that you do not have any Amazon EC2 instances running with the role you are about to remove from the instance profile. Removing a role from an instance profile that is associated with a running instance might break any applications running on the instance. For more information about roles, see IAM roles in the IAM User Guide. For more information about instance profiles, see Using instance profiles in the IAM User Guide.

EXEC aws.iam.instance_profiles.remove_role_from_instance_profile 
@InstanceProfileName='{{ InstanceProfileName }}' --required, 
@RoleName='{{ RoleName }}' --required, 
@region='{{ region }}' --required
;