1.. _community.aws.iam_module: 2 3 4***************** 5community.aws.iam 6***************** 7 8**Manage IAM users, groups, roles and keys** 9 10 11Version added: 1.0.0 12 13.. contents:: 14 :local: 15 :depth: 1 16 17 18Synopsis 19-------- 20- Allows for the management of IAM users, user API keys, groups, roles. 21 22 23 24Requirements 25------------ 26The below requirements are needed on the host that executes this module. 27 28- python >= 2.6 29- boto 30 31 32Parameters 33---------- 34 35.. raw:: html 36 37 <table border=0 cellpadding=0 class="documentation-table"> 38 <tr> 39 <th colspan="1">Parameter</th> 40 <th>Choices/<font color="blue">Defaults</font></th> 41 <th width="100%">Comments</th> 42 </tr> 43 <tr> 44 <td colspan="1"> 45 <div class="ansibleOptionAnchor" id="parameter-"></div> 46 <b>access_key_ids</b> 47 <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> 48 <div style="font-size: small"> 49 <span style="color: purple">list</span> 50 / <span style="color: purple">elements=string</span> 51 </div> 52 </td> 53 <td> 54 </td> 55 <td> 56 <div>A list of the keys that you want affected by the <em>access_key_state</em> parameter.</div> 57 </td> 58 </tr> 59 <tr> 60 <td colspan="1"> 61 <div class="ansibleOptionAnchor" id="parameter-"></div> 62 <b>access_key_state</b> 63 <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> 64 <div style="font-size: small"> 65 <span style="color: purple">string</span> 66 </div> 67 </td> 68 <td> 69 <ul style="margin: 0; padding: 0"><b>Choices:</b> 70 <li>create</li> 71 <li>remove</li> 72 <li>active</li> 73 <li>inactive</li> 74 <li>Create</li> 75 <li>Remove</li> 76 <li>Active</li> 77 <li>Inactive</li> 78 </ul> 79 </td> 80 <td> 81 <div>When type is user, it creates, removes, deactivates or activates a user's access key(s). Note that actions apply only to keys specified.</div> 82 </td> 83 </tr> 84 <tr> 85 <td colspan="1"> 86 <div class="ansibleOptionAnchor" id="parameter-"></div> 87 <b>aws_access_key</b> 88 <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> 89 <div style="font-size: small"> 90 <span style="color: purple">string</span> 91 </div> 92 </td> 93 <td> 94 </td> 95 <td> 96 <div>AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used.</div> 97 <div>If <em>profile</em> is set this parameter is ignored.</div> 98 <div>Passing the <em>aws_access_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> 99 <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_access_key, access_key</div> 100 </td> 101 </tr> 102 <tr> 103 <td colspan="1"> 104 <div class="ansibleOptionAnchor" id="parameter-"></div> 105 <b>aws_ca_bundle</b> 106 <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> 107 <div style="font-size: small"> 108 <span style="color: purple">path</span> 109 </div> 110 </td> 111 <td> 112 </td> 113 <td> 114 <div>The location of a CA Bundle to use when validating SSL certificates.</div> 115 <div>Only used for boto3 based modules.</div> 116 <div>Note: The CA Bundle is read 'module' side and may need to be explicitly copied from the controller if not run locally.</div> 117 </td> 118 </tr> 119 <tr> 120 <td colspan="1"> 121 <div class="ansibleOptionAnchor" id="parameter-"></div> 122 <b>aws_config</b> 123 <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> 124 <div style="font-size: small"> 125 <span style="color: purple">dictionary</span> 126 </div> 127 </td> 128 <td> 129 </td> 130 <td> 131 <div>A dictionary to modify the botocore configuration.</div> 132 <div>Parameters can be found at <a href='https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config'>https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config</a>.</div> 133 <div>Only the 'user_agent' key is used for boto modules. See <a href='http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto'>http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto</a> for more boto configuration.</div> 134 </td> 135 </tr> 136 <tr> 137 <td colspan="1"> 138 <div class="ansibleOptionAnchor" id="parameter-"></div> 139 <b>aws_secret_key</b> 140 <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> 141 <div style="font-size: small"> 142 <span style="color: purple">string</span> 143 </div> 144 </td> 145 <td> 146 </td> 147 <td> 148 <div>AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used.</div> 149 <div>If <em>profile</em> is set this parameter is ignored.</div> 150 <div>Passing the <em>aws_secret_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> 151 <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_secret_key, secret_key</div> 152 </td> 153 </tr> 154 <tr> 155 <td colspan="1"> 156 <div class="ansibleOptionAnchor" id="parameter-"></div> 157 <b>debug_botocore_endpoint_logs</b> 158 <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> 159 <div style="font-size: small"> 160 <span style="color: purple">boolean</span> 161 </div> 162 </td> 163 <td> 164 <ul style="margin: 0; padding: 0"><b>Choices:</b> 165 <li><div style="color: blue"><b>no</b> ←</div></li> 166 <li>yes</li> 167 </ul> 168 </td> 169 <td> 170 <div>Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action" API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used.</div> 171 </td> 172 </tr> 173 <tr> 174 <td colspan="1"> 175 <div class="ansibleOptionAnchor" id="parameter-"></div> 176 <b>ec2_url</b> 177 <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> 178 <div style="font-size: small"> 179 <span style="color: purple">string</span> 180 </div> 181 </td> 182 <td> 183 </td> 184 <td> 185 <div>Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used.</div> 186 <div style="font-size: small; color: darkgreen"><br/>aliases: aws_endpoint_url, endpoint_url</div> 187 </td> 188 </tr> 189 <tr> 190 <td colspan="1"> 191 <div class="ansibleOptionAnchor" id="parameter-"></div> 192 <b>groups</b> 193 <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> 194 <div style="font-size: small"> 195 <span style="color: purple">list</span> 196 / <span style="color: purple">elements=string</span> 197 </div> 198 </td> 199 <td> 200 </td> 201 <td> 202 <div>A list of groups the user should belong to. When <em>state=update</em>, will gracefully remove groups not listed.</div> 203 </td> 204 </tr> 205 <tr> 206 <td colspan="1"> 207 <div class="ansibleOptionAnchor" id="parameter-"></div> 208 <b>iam_type</b> 209 <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> 210 <div style="font-size: small"> 211 <span style="color: purple">string</span> 212 / <span style="color: red">required</span> 213 </div> 214 </td> 215 <td> 216 <ul style="margin: 0; padding: 0"><b>Choices:</b> 217 <li>user</li> 218 <li>group</li> 219 <li>role</li> 220 </ul> 221 </td> 222 <td> 223 <div>Type of IAM resource.</div> 224 </td> 225 </tr> 226 <tr> 227 <td colspan="1"> 228 <div class="ansibleOptionAnchor" id="parameter-"></div> 229 <b>key_count</b> 230 <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> 231 <div style="font-size: small"> 232 <span style="color: purple">integer</span> 233 </div> 234 </td> 235 <td> 236 <b>Default:</b><br/><div style="color: blue">1</div> 237 </td> 238 <td> 239 <div>When <em>access_key_state=create</em> it will ensure this quantity of keys are present.</div> 240 </td> 241 </tr> 242 <tr> 243 <td colspan="1"> 244 <div class="ansibleOptionAnchor" id="parameter-"></div> 245 <b>name</b> 246 <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> 247 <div style="font-size: small"> 248 <span style="color: purple">string</span> 249 / <span style="color: red">required</span> 250 </div> 251 </td> 252 <td> 253 </td> 254 <td> 255 <div>Name of IAM resource to create or identify.</div> 256 </td> 257 </tr> 258 <tr> 259 <td colspan="1"> 260 <div class="ansibleOptionAnchor" id="parameter-"></div> 261 <b>new_name</b> 262 <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> 263 <div style="font-size: small"> 264 <span style="color: purple">string</span> 265 </div> 266 </td> 267 <td> 268 </td> 269 <td> 270 <div>When <em>state=update</em>, will replace <em>name</em> with <em>new_name</em> on IAM resource.</div> 271 </td> 272 </tr> 273 <tr> 274 <td colspan="1"> 275 <div class="ansibleOptionAnchor" id="parameter-"></div> 276 <b>new_path</b> 277 <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> 278 <div style="font-size: small"> 279 <span style="color: purple">string</span> 280 </div> 281 </td> 282 <td> 283 </td> 284 <td> 285 <div>When <em>state=update</em>, will replace the path with new_path on the IAM resource.</div> 286 </td> 287 </tr> 288 <tr> 289 <td colspan="1"> 290 <div class="ansibleOptionAnchor" id="parameter-"></div> 291 <b>password</b> 292 <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> 293 <div style="font-size: small"> 294 <span style="color: purple">string</span> 295 </div> 296 </td> 297 <td> 298 </td> 299 <td> 300 <div>When <em>type=user</em> and either <em>state=present</em> or <em>state=update</em>, define the users login password.</div> 301 <div>Note that this will always return 'changed'.</div> 302 </td> 303 </tr> 304 <tr> 305 <td colspan="1"> 306 <div class="ansibleOptionAnchor" id="parameter-"></div> 307 <b>path</b> 308 <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> 309 <div style="font-size: small"> 310 <span style="color: purple">string</span> 311 </div> 312 </td> 313 <td> 314 <b>Default:</b><br/><div style="color: blue">"/"</div> 315 </td> 316 <td> 317 <div>When creating or updating, specify the desired path of the resource.</div> 318 <div>If <em>state=present</em>, it will replace the current path to match what is passed in when they do not match.</div> 319 </td> 320 </tr> 321 <tr> 322 <td colspan="1"> 323 <div class="ansibleOptionAnchor" id="parameter-"></div> 324 <b>profile</b> 325 <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> 326 <div style="font-size: small"> 327 <span style="color: purple">string</span> 328 </div> 329 </td> 330 <td> 331 </td> 332 <td> 333 <div>Uses a boto profile. Only works with boto >= 2.24.0.</div> 334 <div>Using <em>profile</em> will override <em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> and support for passing them at the same time as <em>profile</em> has been deprecated.</div> 335 <div><em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> will be made mutually exclusive with <em>profile</em> after 2022-06-01.</div> 336 <div style="font-size: small; color: darkgreen"><br/>aliases: aws_profile</div> 337 </td> 338 </tr> 339 <tr> 340 <td colspan="1"> 341 <div class="ansibleOptionAnchor" id="parameter-"></div> 342 <b>region</b> 343 <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> 344 <div style="font-size: small"> 345 <span style="color: purple">string</span> 346 </div> 347 </td> 348 <td> 349 </td> 350 <td> 351 <div>The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See <a href='http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region'>http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region</a></div> 352 <div style="font-size: small; color: darkgreen"><br/>aliases: aws_region, ec2_region</div> 353 </td> 354 </tr> 355 <tr> 356 <td colspan="1"> 357 <div class="ansibleOptionAnchor" id="parameter-"></div> 358 <b>security_token</b> 359 <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> 360 <div style="font-size: small"> 361 <span style="color: purple">string</span> 362 </div> 363 </td> 364 <td> 365 </td> 366 <td> 367 <div>AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used.</div> 368 <div>If <em>profile</em> is set this parameter is ignored.</div> 369 <div>Passing the <em>security_token</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> 370 <div style="font-size: small; color: darkgreen"><br/>aliases: aws_security_token, access_token</div> 371 </td> 372 </tr> 373 <tr> 374 <td colspan="1"> 375 <div class="ansibleOptionAnchor" id="parameter-"></div> 376 <b>state</b> 377 <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> 378 <div style="font-size: small"> 379 <span style="color: purple">string</span> 380 / <span style="color: red">required</span> 381 </div> 382 </td> 383 <td> 384 <ul style="margin: 0; padding: 0"><b>Choices:</b> 385 <li>present</li> 386 <li>absent</li> 387 <li>update</li> 388 </ul> 389 </td> 390 <td> 391 <div>Whether to create, delete or update the IAM resource. Note, roles cannot be updated.</div> 392 </td> 393 </tr> 394 <tr> 395 <td colspan="1"> 396 <div class="ansibleOptionAnchor" id="parameter-"></div> 397 <b>trust_policy</b> 398 <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> 399 <div style="font-size: small"> 400 <span style="color: purple">dictionary</span> 401 </div> 402 </td> 403 <td> 404 </td> 405 <td> 406 <div>The inline (JSON or YAML) trust policy document that grants an entity permission to assume the role.</div> 407 <div>Mutually exclusive with <em>trust_policy_filepath</em>.</div> 408 </td> 409 </tr> 410 <tr> 411 <td colspan="1"> 412 <div class="ansibleOptionAnchor" id="parameter-"></div> 413 <b>trust_policy_filepath</b> 414 <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> 415 <div style="font-size: small"> 416 <span style="color: purple">string</span> 417 </div> 418 </td> 419 <td> 420 </td> 421 <td> 422 <div>The path to the trust policy document that grants an entity permission to assume the role.</div> 423 <div>Mutually exclusive with <em>trust_policy</em>.</div> 424 </td> 425 </tr> 426 <tr> 427 <td colspan="1"> 428 <div class="ansibleOptionAnchor" id="parameter-"></div> 429 <b>update_password</b> 430 <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> 431 <div style="font-size: small"> 432 <span style="color: purple">string</span> 433 </div> 434 </td> 435 <td> 436 <ul style="margin: 0; padding: 0"><b>Choices:</b> 437 <li><div style="color: blue"><b>always</b> ←</div></li> 438 <li>on_create</li> 439 </ul> 440 </td> 441 <td> 442 <div>When to update user passwords.</div> 443 <div><em>update_password=always</em> will ensure the password is set to <em>password</em>.</div> 444 <div><em>update_password=on_create</em> will only set the password for newly created users.</div> 445 </td> 446 </tr> 447 <tr> 448 <td colspan="1"> 449 <div class="ansibleOptionAnchor" id="parameter-"></div> 450 <b>validate_certs</b> 451 <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> 452 <div style="font-size: small"> 453 <span style="color: purple">boolean</span> 454 </div> 455 </td> 456 <td> 457 <ul style="margin: 0; padding: 0"><b>Choices:</b> 458 <li>no</li> 459 <li><div style="color: blue"><b>yes</b> ←</div></li> 460 </ul> 461 </td> 462 <td> 463 <div>When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.</div> 464 </td> 465 </tr> 466 </table> 467 <br/> 468 469 470Notes 471----- 472 473.. note:: 474 - Currently boto does not support the removal of Managed Policies, the module will error out if your user/group/role has managed policies when you try to do state=absent. They will need to be removed manually. 475 - If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence ``AWS_URL`` or ``EC2_URL``, ``AWS_PROFILE`` or ``AWS_DEFAULT_PROFILE``, ``AWS_ACCESS_KEY_ID`` or ``AWS_ACCESS_KEY`` or ``EC2_ACCESS_KEY``, ``AWS_SECRET_ACCESS_KEY`` or ``AWS_SECRET_KEY`` or ``EC2_SECRET_KEY``, ``AWS_SECURITY_TOKEN`` or ``EC2_SECURITY_TOKEN``, ``AWS_REGION`` or ``EC2_REGION``, ``AWS_CA_BUNDLE`` 476 - Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html 477 - ``AWS_REGION`` or ``EC2_REGION`` can be typically be used to specify the AWS region, when required, but this can also be configured in the boto config file 478 479 480 481Examples 482-------- 483 484.. code-block:: yaml 485 486 # Basic user creation example 487 - name: Create two new IAM users with API keys 488 community.aws.iam: 489 iam_type: user 490 name: "{{ item }}" 491 state: present 492 password: "{{ temp_pass }}" 493 access_key_state: create 494 loop: 495 - jcleese 496 - mpython 497 498 # Advanced example, create two new groups and add the pre-existing user 499 # jdavila to both groups. 500 - name: Create Two Groups, Mario and Luigi 501 community.aws.iam: 502 iam_type: group 503 name: "{{ item }}" 504 state: present 505 loop: 506 - Mario 507 - Luigi 508 register: new_groups 509 510 - name: Update user 511 community.aws.iam: 512 iam_type: user 513 name: jdavila 514 state: update 515 groups: "{{ item.created_group.group_name }}" 516 loop: "{{ new_groups.results }}" 517 518 # Example of role with custom trust policy for Lambda service 519 - name: Create IAM role with custom trust relationship 520 community.aws.iam: 521 iam_type: role 522 name: AAALambdaTestRole 523 state: present 524 trust_policy: 525 Version: '2012-10-17' 526 Statement: 527 - Action: sts:AssumeRole 528 Effect: Allow 529 Principal: 530 Service: lambda.amazonaws.com 531 532 533 534Return Values 535------------- 536Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this module: 537 538.. raw:: html 539 540 <table border=0 cellpadding=0 class="documentation-table"> 541 <tr> 542 <th colspan="1">Key</th> 543 <th>Returned</th> 544 <th width="100%">Description</th> 545 </tr> 546 <tr> 547 <td colspan="1"> 548 <div class="ansibleOptionAnchor" id="return-"></div> 549 <b>role_result</b> 550 <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> 551 <div style="font-size: small"> 552 <span style="color: purple">string</span> 553 </div> 554 </td> 555 <td>if iam_type=role and state=present</td> 556 <td> 557 <div>the IAM.role dict returned by Boto</div> 558 <br/> 559 <div style="font-size: smaller"><b>Sample:</b></div> 560 <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">{'arn': 'arn:aws:iam::A1B2C3D4E5F6:role/my-new-role', 'assume_role_policy_document': '...truncated...', 'create_date': '2017-09-02T14:32:23Z', 'path': '/', 'role_id': 'AROAA1B2C3D4E5F6G7H8I', 'role_name': 'my-new-role'}</div> 561 </td> 562 </tr> 563 <tr> 564 <td colspan="1"> 565 <div class="ansibleOptionAnchor" id="return-"></div> 566 <b>roles</b> 567 <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> 568 <div style="font-size: small"> 569 <span style="color: purple">list</span> 570 </div> 571 </td> 572 <td>if iam_type=role and state=present</td> 573 <td> 574 <div>a list containing the name of the currently defined roles</div> 575 <br/> 576 <div style="font-size: smaller"><b>Sample:</b></div> 577 <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">['my-new-role', 'my-existing-role-1', 'my-existing-role-2', 'my-existing-role-3', 'my-existing-role-...']</div> 578 </td> 579 </tr> 580 </table> 581 <br/><br/> 582 583 584Status 585------ 586 587 588Authors 589~~~~~~~ 590 591- Jonathan I. Davila (@defionscode) 592- Paul Seiffert (@seiffert) 593