Package com.pulumi.aws.iam

Class Role

  • public class Role
extends com.pulumi.resources.CustomResource
    Provides an IAM role. > **NOTE:** If policies are attached to the role via the `aws.iam.PolicyAttachment` resource and you are modifying the role `name` or `path`, the `force_detach_policies` argument must be set to `true` and applied before attempting the operation otherwise you will encounter a `DeleteConflict` error. The `aws.iam.RolePolicyAttachment` resource (recommended) does not have this requirement. > **NOTE:** If you use this resource's `managed_policy_arns` argument or `inline_policy` configuration blocks, this resource will take over exclusive management of the role's respective policy types (e.g., both policy types if both arguments are used). These arguments are incompatible with other ways of managing a role's policies, such as `aws.iam.PolicyAttachment`, `aws.iam.RolePolicyAttachment`, and `aws.iam.RolePolicy`. If you attempt to manage a role's policies by multiple means, you will get resource cycling and/or errors. ## Example Usage ### Basic Example <!--Start PulumiCodeChooser --> ```java package generated_program; import com.pulumi.Context; import com.pulumi.Pulumi; import com.pulumi.core.Output; import com.pulumi.aws.iam.Role; import com.pulumi.aws.iam.RoleArgs; import static com.pulumi.codegen.internal.Serialization.*; import java.util.List; import java.util.ArrayList; import java.util.Map; import java.io.File; import java.nio.file.Files; import java.nio.file.Paths; public class App { public static void main(String[] args) { Pulumi.run(App::stack); } public static void stack(Context ctx) { var testRole = new Role("testRole", RoleArgs.builder() .name("test_role") .assumeRolePolicy(serializeJson( jsonObject( jsonProperty("version", "2012-10-17"), jsonProperty("statement", jsonArray(jsonObject( jsonProperty("action", "sts:AssumeRole"), jsonProperty("effect", "Allow"), jsonProperty("sid", ""), jsonProperty("principal", jsonObject( jsonProperty("service", "ec2.amazonaws.com") )) ))) ))) .tags(Map.of("tag-key", "tag-value")) .build()); } } ``` <!--End PulumiCodeChooser --> ### Example of Using Data Source for Assume Role Policy <!--Start PulumiCodeChooser --> ```java package generated_program; import com.pulumi.Context; import com.pulumi.Pulumi; import com.pulumi.core.Output; import com.pulumi.aws.iam.IamFunctions; import com.pulumi.aws.iam.inputs.GetPolicyDocumentArgs; import com.pulumi.aws.iam.Role; import com.pulumi.aws.iam.RoleArgs; import java.util.List; import java.util.ArrayList; import java.util.Map; import java.io.File; import java.nio.file.Files; import java.nio.file.Paths; public class App { public static void main(String[] args) { Pulumi.run(App::stack); } public static void stack(Context ctx) { final var instanceAssumeRolePolicy = IamFunctions.getPolicyDocument(GetPolicyDocumentArgs.builder() .statements(GetPolicyDocumentStatementArgs.builder() .actions("sts:AssumeRole") .principals(GetPolicyDocumentStatementPrincipalArgs.builder() .type("Service") .identifiers("ec2.amazonaws.com") .build()) .build()) .build()); var instance = new Role("instance", RoleArgs.builder() .name("instance_role") .path("/system/") .assumeRolePolicy(instanceAssumeRolePolicy.applyValue(getPolicyDocumentResult -> getPolicyDocumentResult.json())) .build()); } } ``` <!--End PulumiCodeChooser --> ### Example of Exclusive Inline Policies This example creates an IAM role with two inline IAM policies. If someone adds another inline policy out-of-band, on the next apply, this provider will remove that policy. If someone deletes these policies out-of-band, this provider will recreate them. <!--Start PulumiCodeChooser --> ```java package generated_program; import com.pulumi.Context; import com.pulumi.Pulumi; import com.pulumi.core.Output; import com.pulumi.aws.iam.IamFunctions; import com.pulumi.aws.iam.inputs.GetPolicyDocumentArgs; import com.pulumi.aws.iam.Role; import com.pulumi.aws.iam.RoleArgs; import com.pulumi.aws.iam.inputs.RoleInlinePolicyArgs; import static com.pulumi.codegen.internal.Serialization.*; import java.util.List; import java.util.ArrayList; import java.util.Map; import java.io.File; import java.nio.file.Files; import java.nio.file.Paths; public class App { public static void main(String[] args) { Pulumi.run(App::stack); } public static void stack(Context ctx) { final var inlinePolicy = IamFunctions.getPolicyDocument(GetPolicyDocumentArgs.builder() .statements(GetPolicyDocumentStatementArgs.builder() .actions("ec2:DescribeAccountAttributes") .resources("*") .build()) .build()); var example = new Role("example", RoleArgs.builder() .name("yak_role") .assumeRolePolicy(instanceAssumeRolePolicy.json()) .inlinePolicies( RoleInlinePolicyArgs.builder() .name("my_inline_policy") .policy(serializeJson( jsonObject( jsonProperty("version", "2012-10-17"), jsonProperty("statement", jsonArray(jsonObject( jsonProperty("action", jsonArray("ec2:Describe*")), jsonProperty("effect", "Allow"), jsonProperty("resource", "*") ))) ))) .build(), RoleInlinePolicyArgs.builder() .name("policy-8675309") .policy(inlinePolicy.applyValue(getPolicyDocumentResult -> getPolicyDocumentResult.json())) .build()) .build()); } } ``` <!--End PulumiCodeChooser --> ### Example of Removing Inline Policies This example creates an IAM role with what appears to be empty IAM `inline_policy` argument instead of using `inline_policy` as a configuration block. The result is that if someone were to add an inline policy out-of-band, on the next apply, this provider will remove that policy. <!--Start PulumiCodeChooser --> ```java package generated_program; import com.pulumi.Context; import com.pulumi.Pulumi; import com.pulumi.core.Output; import com.pulumi.aws.iam.Role; import com.pulumi.aws.iam.RoleArgs; import com.pulumi.aws.iam.inputs.RoleInlinePolicyArgs; import java.util.List; import java.util.ArrayList; import java.util.Map; import java.io.File; import java.nio.file.Files; import java.nio.file.Paths; public class App { public static void main(String[] args) { Pulumi.run(App::stack); } public static void stack(Context ctx) { var example = new Role("example", RoleArgs.builder() .inlinePolicies() .name("yak_role") .assumeRolePolicy(instanceAssumeRolePolicy.json()) .build()); } } ``` <!--End PulumiCodeChooser --> ### Example of Exclusive Managed Policies This example creates an IAM role and attaches two managed IAM policies. If someone attaches another managed policy out-of-band, on the next apply, this provider will detach that policy. If someone detaches these policies out-of-band, this provider will attach them again. <!--Start PulumiCodeChooser --> ```java package generated_program; import com.pulumi.Context; import com.pulumi.Pulumi; import com.pulumi.core.Output; import com.pulumi.aws.iam.Policy; import com.pulumi.aws.iam.PolicyArgs; import com.pulumi.aws.iam.Role; import com.pulumi.aws.iam.RoleArgs; import static com.pulumi.codegen.internal.Serialization.*; import java.util.List; import java.util.ArrayList; import java.util.Map; import java.io.File; import java.nio.file.Files; import java.nio.file.Paths; public class App { public static void main(String[] args) { Pulumi.run(App::stack); } public static void stack(Context ctx) { var policyOne = new Policy("policyOne", PolicyArgs.builder() .name("policy-618033") .policy(serializeJson( jsonObject( jsonProperty("version", "2012-10-17"), jsonProperty("statement", jsonArray(jsonObject( jsonProperty("action", jsonArray("ec2:Describe*")), jsonProperty("effect", "Allow"), jsonProperty("resource", "*") ))) ))) .build()); var policyTwo = new Policy("policyTwo", PolicyArgs.builder() .name("policy-381966") .policy(serializeJson( jsonObject( jsonProperty("version", "2012-10-17"), jsonProperty("statement", jsonArray(jsonObject( jsonProperty("action", jsonArray( "s3:ListAllMyBuckets", "s3:ListBucket", "s3:HeadBucket" )), jsonProperty("effect", "Allow"), jsonProperty("resource", "*") ))) ))) .build()); var example = new Role("example", RoleArgs.builder() .name("yak_role") .assumeRolePolicy(instanceAssumeRolePolicy.json()) .managedPolicyArns( policyOne.arn(), policyTwo.arn()) .build()); } } ``` <!--End PulumiCodeChooser --> ### Example of Removing Managed Policies This example creates an IAM role with an empty `managed_policy_arns` argument. If someone attaches a policy out-of-band, on the next apply, this provider will detach that policy. <!--Start PulumiCodeChooser --> ```java package generated_program; import com.pulumi.Context; import com.pulumi.Pulumi; import com.pulumi.core.Output; import com.pulumi.aws.iam.Role; import com.pulumi.aws.iam.RoleArgs; import java.util.List; import java.util.ArrayList; import java.util.Map; import java.io.File; import java.nio.file.Files; import java.nio.file.Paths; public class App { public static void main(String[] args) { Pulumi.run(App::stack); } public static void stack(Context ctx) { var example = new Role("example", RoleArgs.builder() .name("yak_role") .assumeRolePolicy(instanceAssumeRolePolicy.json()) .managedPolicyArns() .build()); } } ``` <!--End PulumiCodeChooser --> ## Import Using `pulumi import`, import IAM Roles using the `name`. For example: ```sh $ pulumi import aws:iam/role:Role developer developer_name ```

    • Nested Class Summary

      • Nested classes/interfaces inherited from class com.pulumi.resources.CustomResource

        com.pulumi.resources.CustomResource.CustomResourceInternal

      • Nested classes/interfaces inherited from class com.pulumi.resources.Resource

        com.pulumi.resources.Resource.LazyField<T extends java.lang.Object>, com.pulumi.resources.Resource.LazyFields, com.pulumi.resources.Resource.ResourceInternal

    • Field Summary

      • Fields inherited from class com.pulumi.resources.Resource

        childResources, remote

    • Constructor Summary

      Constructors 
      Constructor Description
      Role​(java.lang.String name)  
      Role​(java.lang.String name, RoleArgs args)  
      Role​(java.lang.String name, RoleArgs args, com.pulumi.resources.CustomResourceOptions options)  

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      com.pulumi.core.Output<java.lang.String> arn()  
      com.pulumi.core.Output<java.lang.String> assumeRolePolicy()  
      com.pulumi.core.Output<java.lang.String> createDate()  
      com.pulumi.core.Output<java.util.Optional<java.lang.String>> description()  
      com.pulumi.core.Output<java.util.Optional<java.lang.Boolean>> forceDetachPolicies()  
      static Role get​(java.lang.String name, com.pulumi.core.Output<java.lang.String> id, RoleState state, com.pulumi.resources.CustomResourceOptions options)
      Get an existing Host resource's state with the given name, ID, and optional extra properties used to qualify the lookup.
      com.pulumi.core.Output<java.util.List<RoleInlinePolicy>> inlinePolicies()  
      com.pulumi.core.Output<java.util.List<java.lang.String>> managedPolicyArns()  
      com.pulumi.core.Output<java.util.Optional<java.lang.Integer>> maxSessionDuration()  
      com.pulumi.core.Output<java.lang.String> name()  
      com.pulumi.core.Output<java.lang.String> namePrefix()  
      com.pulumi.core.Output<java.util.Optional<java.lang.String>> path()  
      com.pulumi.core.Output<java.util.Optional<java.lang.String>> permissionsBoundary()  
      com.pulumi.core.Output<java.util.Optional<java.util.Map<java.lang.String,​java.lang.String>>> tags()  
      com.pulumi.core.Output<java.util.Map<java.lang.String,​java.lang.String>> tagsAll()  
      com.pulumi.core.Output<java.lang.String> uniqueId()  

      • Methods inherited from class com.pulumi.resources.CustomResource

        getId, id, idFuture

      • Methods inherited from class com.pulumi.resources.Resource

        getChildResources, getResourceName, getResourceType, getUrn, pulumiChildResources, pulumiResourceName, pulumiResourceType, urn

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • Role

        public Role​(java.lang.String name)
        Parameters:
        name - The _unique_ name of the resulting resource.

      • Role

        public Role​(java.lang.String name,
            RoleArgs args)
        Parameters:
        name - The _unique_ name of the resulting resource.
        args - The arguments to use to populate this resource's properties.

      • Role

        public Role​(java.lang.String name,
            RoleArgs args,
            @Nullable
            com.pulumi.resources.CustomResourceOptions options)
        Parameters:
        name - The _unique_ name of the resulting resource.
        args - The arguments to use to populate this resource's properties.
        options - A bag of options that control this resource's behavior.

    • Method Detail

      • arn

        public com.pulumi.core.Output<java.lang.String> arn()
        Returns:
        Amazon Resource Name (ARN) specifying the role.

      • assumeRolePolicy

        public com.pulumi.core.Output<java.lang.String> assumeRolePolicy()
        Returns:
        Policy that grants an entity permission to assume the role. > **NOTE:** The `assume_role_policy` is very similar to but slightly different than a standard IAM policy and cannot use an `aws.iam.Policy` resource. However, it _can_ use an `aws.iam.getPolicyDocument` data source. See the example above of how this works. The following arguments are optional:

      • createDate

        public com.pulumi.core.Output<java.lang.String> createDate()
        Returns:
        Creation date of the IAM role.

      • description

        public com.pulumi.core.Output<java.util.Optional<java.lang.String>> description()
        Returns:
        Description of the role.

      • forceDetachPolicies

        public com.pulumi.core.Output<java.util.Optional<java.lang.Boolean>> forceDetachPolicies()
        Returns:
        Whether to force detaching any policies the role has before destroying it. Defaults to `false`.

      • inlinePolicies

        public com.pulumi.core.Output<java.util.List<RoleInlinePolicy>> inlinePolicies()
        Returns:
        Configuration block defining an exclusive set of IAM inline policies associated with the IAM role. See below. If no blocks are configured, the provider will not manage any inline policies in this resource. Configuring one empty block (i.e., `inline_policy {}`) will cause the provider to remove _all_ inline policies added out of band on `apply`.

      • managedPolicyArns

        public com.pulumi.core.Output<java.util.List<java.lang.String>> managedPolicyArns()

      • maxSessionDuration

        public com.pulumi.core.Output<java.util.Optional<java.lang.Integer>> maxSessionDuration()
        Returns:
        Maximum session duration (in seconds) that you want to set for the specified role. If you do not specify a value for this setting, the default maximum of one hour is applied. This setting can have a value from 1 hour to 12 hours.

      • name

        public com.pulumi.core.Output<java.lang.String> name()
        Returns:
        Friendly name of the role. If omitted, the provider will assign a random, unique name. See [IAM Identifiers](https://docs.aws.amazon.com/IAM/latest/UserGuide/Using_Identifiers.html) for more information.

      • namePrefix

        public com.pulumi.core.Output<java.lang.String> namePrefix()
        Returns:
        Creates a unique friendly name beginning with the specified prefix. Conflicts with `name`.

      • path

        public com.pulumi.core.Output<java.util.Optional<java.lang.String>> path()
        Returns:
        Path to the role. See [IAM Identifiers](https://docs.aws.amazon.com/IAM/latest/UserGuide/Using_Identifiers.html) for more information.

      • permissionsBoundary

        public com.pulumi.core.Output<java.util.Optional<java.lang.String>> permissionsBoundary()
        Returns:
        ARN of the policy that is used to set the permissions boundary for the role.

      • tags

        public com.pulumi.core.Output<java.util.Optional<java.util.Map<java.lang.String,​java.lang.String>>> tags()
        Returns:
        Key-value mapping of tags for the IAM role. If configured with a provider `default_tags` configuration block present, tags with matching keys will overwrite those defined at the provider-level.

      • tagsAll

        public com.pulumi.core.Output<java.util.Map<java.lang.String,​java.lang.String>> tagsAll()
        Returns:
        A map of tags assigned to the resource, including those inherited from the provider `default_tags` configuration block.

      • uniqueId

        public com.pulumi.core.Output<java.lang.String> uniqueId()
        Returns:
        Stable and unique string identifying the role.

      • get

        public static Role get​(java.lang.String name,
                       com.pulumi.core.Output<java.lang.String> id,
                       @Nullable
                       RoleState state,
                       @Nullable
                       com.pulumi.resources.CustomResourceOptions options)
        Get an existing Host resource's state with the given name, ID, and optional extra properties used to qualify the lookup.
        Parameters:
        name - The _unique_ name of the resulting resource.
        id - The _unique_ provider ID of the resource to lookup.
        state -
        options - Optional settings to control the behavior of the CustomResource.