@pulumi/aws
Version:
A Pulumi package for creating and managing Amazon Web Services (AWS) cloud resources.
410 lines (409 loc) • 19.6 kB
TypeScript
import * as pulumi from "@pulumi/pulumi";
import * as inputs from "../types/input";
import * as outputs from "../types/output";
/**
* 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 `forceDetachPolicies` 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 `managedPolicyArns` argument or `inlinePolicy` 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.
*
* > **NOTE:** We suggest using explicit JSON encoding or `aws.iam.getPolicyDocument` when assigning a value to `policy`. They seamlessly translate configuration to JSON, enabling you to maintain consistency within your configuration without the need for context switches. Also, you can sidestep potential complications arising from formatting discrepancies, whitespace inconsistencies, and other nuances inherent to JSON.
*
* ## Example Usage
*
* ### Basic Example
*
* ```typescript
* import * as pulumi from "@pulumi/pulumi";
* import * as aws from "@pulumi/aws";
*
* const testRole = new aws.iam.Role("test_role", {
* name: "test_role",
* assumeRolePolicy: JSON.stringify({
* Version: "2012-10-17",
* Statement: [{
* Action: "sts:AssumeRole",
* Effect: "Allow",
* Sid: "",
* Principal: {
* Service: "ec2.amazonaws.com",
* },
* }],
* }),
* tags: {
* "tag-key": "tag-value",
* },
* });
* ```
*
* ### Example of Using Data Source for Assume Role Policy
*
* ```typescript
* import * as pulumi from "@pulumi/pulumi";
* import * as aws from "@pulumi/aws";
*
* const instanceAssumeRolePolicy = aws.iam.getPolicyDocument({
* statements: [{
* actions: ["sts:AssumeRole"],
* principals: [{
* type: "Service",
* identifiers: ["ec2.amazonaws.com"],
* }],
* }],
* });
* const instance = new aws.iam.Role("instance", {
* name: "instance_role",
* path: "/system/",
* assumeRolePolicy: instanceAssumeRolePolicy.then(instanceAssumeRolePolicy => instanceAssumeRolePolicy.json),
* });
* ```
*
* ### Example of Exclusive Inline Policies
*
* > The `inlinePolicy` argument is deprecated. Use the `aws.iam.RolePolicy` resource instead. If Pulumi should exclusively manage all inline policy associations (the current behavior of this argument), use the `aws.iam.RolePoliciesExclusive` resource as well.
*
* 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.
*
* ```typescript
* import * as pulumi from "@pulumi/pulumi";
* import * as aws from "@pulumi/aws";
*
* const inlinePolicy = aws.iam.getPolicyDocument({
* statements: [{
* actions: ["ec2:DescribeAccountAttributes"],
* resources: ["*"],
* }],
* });
* const example = new aws.iam.Role("example", {
* name: "yak_role",
* assumeRolePolicy: instanceAssumeRolePolicy.json,
* inlinePolicies: [
* {
* name: "my_inline_policy",
* policy: JSON.stringify({
* Version: "2012-10-17",
* Statement: [{
* Action: ["ec2:Describe*"],
* Effect: "Allow",
* Resource: "*",
* }],
* }),
* },
* {
* name: "policy-8675309",
* policy: inlinePolicy.then(inlinePolicy => inlinePolicy.json),
* },
* ],
* });
* ```
*
* ### Example of Removing Inline Policies
*
* > The `inlinePolicy` argument is deprecated. Use the `aws.iam.RolePolicy` resource instead. If Pulumi should exclusively manage all inline policy associations (the current behavior of this argument), use the `aws.iam.RolePoliciesExclusive` resource as well.
*
* This example creates an IAM role with what appears to be empty IAM `inlinePolicy` argument instead of using `inlinePolicy` 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.
*
* ```typescript
* import * as pulumi from "@pulumi/pulumi";
* import * as aws from "@pulumi/aws";
*
* const example = new aws.iam.Role("example", {
* inlinePolicies: [{}],
* name: "yak_role",
* assumeRolePolicy: instanceAssumeRolePolicy.json,
* });
* ```
*
* ### Example of Exclusive Managed Policies
*
* > The `managedPolicyArns` argument is deprecated. Use the `aws.iam.RolePolicyAttachment` resource instead. If Pulumi should exclusively manage all managed policy attachments (the current behavior of this argument), use the `aws.iam.RolePolicyAttachmentsExclusive` resource as well.
*
* 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.
*
* ```typescript
* import * as pulumi from "@pulumi/pulumi";
* import * as aws from "@pulumi/aws";
*
* const policyOne = new aws.iam.Policy("policy_one", {
* name: "policy-618033",
* policy: JSON.stringify({
* Version: "2012-10-17",
* Statement: [{
* Action: ["ec2:Describe*"],
* Effect: "Allow",
* Resource: "*",
* }],
* }),
* });
* const policyTwo = new aws.iam.Policy("policy_two", {
* name: "policy-381966",
* policy: JSON.stringify({
* Version: "2012-10-17",
* Statement: [{
* Action: [
* "s3:ListAllMyBuckets",
* "s3:ListBucket",
* "s3:HeadBucket",
* ],
* Effect: "Allow",
* Resource: "*",
* }],
* }),
* });
* const example = new aws.iam.Role("example", {
* name: "yak_role",
* assumeRolePolicy: instanceAssumeRolePolicy.json,
* managedPolicyArns: [
* policyOne.arn,
* policyTwo.arn,
* ],
* });
* ```
*
* ### Example of Removing Managed Policies
*
* > The `managedPolicyArns` argument is deprecated. Use the `aws.iam.RolePolicyAttachment` resource instead. If Pulumi should exclusively manage all managed policy attachments (the current behavior of this argument), use the `aws.iam.RolePolicyAttachmentsExclusive` resource as well.
*
* This example creates an IAM role with an empty `managedPolicyArns` argument. If someone attaches a policy out-of-band, on the next apply, this provider will detach that policy.
*
* ```typescript
* import * as pulumi from "@pulumi/pulumi";
* import * as aws from "@pulumi/aws";
*
* const example = new aws.iam.Role("example", {
* name: "yak_role",
* assumeRolePolicy: instanceAssumeRolePolicy.json,
* managedPolicyArns: [],
* });
* ```
*
* ## Import
*
* Using `pulumi import`, import IAM Roles using the `name`. For example:
*
* ```sh
* $ pulumi import aws:iam/role:Role developer developer_name
* ```
*/
export declare class Role extends pulumi.CustomResource {
/**
* Get an existing Role resource's state with the given name, ID, and optional extra
* properties used to qualify the lookup.
*
* @param name The _unique_ name of the resulting resource.
* @param id The _unique_ provider ID of the resource to lookup.
* @param state Any extra arguments used during the lookup.
* @param opts Optional settings to control the behavior of the CustomResource.
*/
static get(name: string, id: pulumi.Input<pulumi.ID>, state?: RoleState, opts?: pulumi.CustomResourceOptions): Role;
/**
* Returns true if the given object is an instance of Role. This is designed to work even
* when multiple copies of the Pulumi SDK have been loaded into the same process.
*/
static isInstance(obj: any): obj is Role;
/**
* Amazon Resource Name (ARN) specifying the role.
*/
readonly arn: pulumi.Output<string>;
/**
* Policy that grants an entity permission to assume the role.
*
* > **NOTE:** The `assumeRolePolicy` 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:
*/
readonly assumeRolePolicy: pulumi.Output<string>;
/**
* Creation date of the IAM role.
*/
readonly createDate: pulumi.Output<string>;
/**
* Description of the role.
*/
readonly description: pulumi.Output<string | undefined>;
/**
* Whether to force detaching any policies the role has before destroying it. Defaults to `false`.
*/
readonly forceDetachPolicies: pulumi.Output<boolean | undefined>;
/**
* Configuration block defining an exclusive set of IAM inline policies associated with the IAM role. See below. If no blocks are configured, Pulumi will not manage any inline policies in this resource. Configuring one empty block (i.e., `inlinePolicy {}`) will cause Pulumi to remove _all_ inline policies added out of band on `apply`.
*/
readonly inlinePolicies: pulumi.Output<outputs.iam.RoleInlinePolicy[]>;
/**
* Set of exclusive IAM managed policy ARNs to attach to the IAM role. If this attribute is not configured, Pulumi will ignore policy attachments to this resource. When configured, Pulumi will align the role's managed policy attachments with this set by attaching or detaching managed policies. Configuring an empty set (i.e., `managedPolicyArns = []`) will cause Pulumi to remove _all_ managed policy attachments.
*/
readonly managedPolicyArns: pulumi.Output<string[]>;
/**
* 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.
*/
readonly maxSessionDuration: pulumi.Output<number | undefined>;
/**
* 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.
*/
readonly name: pulumi.Output<string>;
/**
* Creates a unique friendly name beginning with the specified prefix. Conflicts with `name`.
*/
readonly namePrefix: pulumi.Output<string>;
/**
* Path to the role. See [IAM Identifiers](https://docs.aws.amazon.com/IAM/latest/UserGuide/Using_Identifiers.html) for more information.
*/
readonly path: pulumi.Output<string | undefined>;
/**
* ARN of the policy that is used to set the permissions boundary for the role.
*/
readonly permissionsBoundary: pulumi.Output<string | undefined>;
/**
* Key-value mapping of tags for the IAM role. If configured with a provider `defaultTags` configuration block present, tags with matching keys will overwrite those defined at the provider-level.
*/
readonly tags: pulumi.Output<{
[key: string]: string;
} | undefined>;
/**
* A map of tags assigned to the resource, including those inherited from the provider `defaultTags` configuration block.
*/
readonly tagsAll: pulumi.Output<{
[key: string]: string;
}>;
/**
* Stable and unique string identifying the role.
*/
readonly uniqueId: pulumi.Output<string>;
/**
* Create a Role resource with the given unique name, arguments, and options.
*
* @param name The _unique_ name of the resource.
* @param args The arguments to use to populate this resource's properties.
* @param opts A bag of options that control this resource's behavior.
*/
constructor(name: string, args: RoleArgs, opts?: pulumi.CustomResourceOptions);
}
/**
* Input properties used for looking up and filtering Role resources.
*/
export interface RoleState {
/**
* Amazon Resource Name (ARN) specifying the role.
*/
arn?: pulumi.Input<string>;
/**
* Policy that grants an entity permission to assume the role.
*
* > **NOTE:** The `assumeRolePolicy` 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:
*/
assumeRolePolicy?: pulumi.Input<string | inputs.iam.PolicyDocument>;
/**
* Creation date of the IAM role.
*/
createDate?: pulumi.Input<string>;
/**
* Description of the role.
*/
description?: pulumi.Input<string>;
/**
* Whether to force detaching any policies the role has before destroying it. Defaults to `false`.
*/
forceDetachPolicies?: pulumi.Input<boolean>;
/**
* Configuration block defining an exclusive set of IAM inline policies associated with the IAM role. See below. If no blocks are configured, Pulumi will not manage any inline policies in this resource. Configuring one empty block (i.e., `inlinePolicy {}`) will cause Pulumi to remove _all_ inline policies added out of band on `apply`.
*/
inlinePolicies?: pulumi.Input<pulumi.Input<inputs.iam.RoleInlinePolicy>[]>;
/**
* Set of exclusive IAM managed policy ARNs to attach to the IAM role. If this attribute is not configured, Pulumi will ignore policy attachments to this resource. When configured, Pulumi will align the role's managed policy attachments with this set by attaching or detaching managed policies. Configuring an empty set (i.e., `managedPolicyArns = []`) will cause Pulumi to remove _all_ managed policy attachments.
*/
managedPolicyArns?: pulumi.Input<pulumi.Input<string>[]>;
/**
* 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.
*/
maxSessionDuration?: pulumi.Input<number>;
/**
* 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.
*/
name?: pulumi.Input<string>;
/**
* Creates a unique friendly name beginning with the specified prefix. Conflicts with `name`.
*/
namePrefix?: pulumi.Input<string>;
/**
* Path to the role. See [IAM Identifiers](https://docs.aws.amazon.com/IAM/latest/UserGuide/Using_Identifiers.html) for more information.
*/
path?: pulumi.Input<string>;
/**
* ARN of the policy that is used to set the permissions boundary for the role.
*/
permissionsBoundary?: pulumi.Input<string>;
/**
* Key-value mapping of tags for the IAM role. If configured with a provider `defaultTags` configuration block present, tags with matching keys will overwrite those defined at the provider-level.
*/
tags?: pulumi.Input<{
[key: string]: pulumi.Input<string>;
}>;
/**
* A map of tags assigned to the resource, including those inherited from the provider `defaultTags` configuration block.
*/
tagsAll?: pulumi.Input<{
[key: string]: pulumi.Input<string>;
}>;
/**
* Stable and unique string identifying the role.
*/
uniqueId?: pulumi.Input<string>;
}
/**
* The set of arguments for constructing a Role resource.
*/
export interface RoleArgs {
/**
* Policy that grants an entity permission to assume the role.
*
* > **NOTE:** The `assumeRolePolicy` 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:
*/
assumeRolePolicy: pulumi.Input<string | inputs.iam.PolicyDocument>;
/**
* Description of the role.
*/
description?: pulumi.Input<string>;
/**
* Whether to force detaching any policies the role has before destroying it. Defaults to `false`.
*/
forceDetachPolicies?: pulumi.Input<boolean>;
/**
* Configuration block defining an exclusive set of IAM inline policies associated with the IAM role. See below. If no blocks are configured, Pulumi will not manage any inline policies in this resource. Configuring one empty block (i.e., `inlinePolicy {}`) will cause Pulumi to remove _all_ inline policies added out of band on `apply`.
*/
inlinePolicies?: pulumi.Input<pulumi.Input<inputs.iam.RoleInlinePolicy>[]>;
/**
* Set of exclusive IAM managed policy ARNs to attach to the IAM role. If this attribute is not configured, Pulumi will ignore policy attachments to this resource. When configured, Pulumi will align the role's managed policy attachments with this set by attaching or detaching managed policies. Configuring an empty set (i.e., `managedPolicyArns = []`) will cause Pulumi to remove _all_ managed policy attachments.
*/
managedPolicyArns?: pulumi.Input<pulumi.Input<string>[]>;
/**
* 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.
*/
maxSessionDuration?: pulumi.Input<number>;
/**
* 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.
*/
name?: pulumi.Input<string>;
/**
* Creates a unique friendly name beginning with the specified prefix. Conflicts with `name`.
*/
namePrefix?: pulumi.Input<string>;
/**
* Path to the role. See [IAM Identifiers](https://docs.aws.amazon.com/IAM/latest/UserGuide/Using_Identifiers.html) for more information.
*/
path?: pulumi.Input<string>;
/**
* ARN of the policy that is used to set the permissions boundary for the role.
*/
permissionsBoundary?: pulumi.Input<string>;
/**
* Key-value mapping of tags for the IAM role. If configured with a provider `defaultTags` configuration block present, tags with matching keys will overwrite those defined at the provider-level.
*/
tags?: pulumi.Input<{
[key: string]: pulumi.Input<string>;
}>;
}