If you are not familiar with modules, check out Ansible - Getting Started with Modules.

The ansible.builtin.user module is similar to the useradd and usermod commands. The user module is used to create, modify, delete a users account on a managed node (e.g. target system).

If the users account does not exist, the users account will be created. If the users account already exists, the users account will be modified.

Create user account

In this example, user john.doe is created. This is similar to the useradd command.

---
- hosts: all
  tasks:
  - name: create john.doe account
    ansible.builtin.user:
      name: john.doe
      state: present
...      

Password

When creating a user account, the users password can be defined. Let's say you try this.

---
- hosts: all
  tasks:
  - name: create john.doe account
    ansible.builtin.user:
      name: john.doe
      password: itsasecret
      state: present
...    

The following will be returned.

[WARNING]: The input password appears not to have been hashed. The 'password' argument must be encrypted for this module to work properly.

As the warning suggests, the password must be hashed. Notice in this example that the clear text password is included, as a string since the value is wrapped in single quotes. For security reasons, a users password is almost never embedded in the playbook like this.

---
- hosts: all
  tasks:
  - name: create john.doe account
    ansible.builtin.user:
      name: john.doe
      password: "{{ 'itsasecret' | password_hash('sha512') }}"
      state: present
...        

Instead, the ansible-vault create or ansible-vault encrypt command is used to create an encrypted file that contains the users password.

ansible-vault create vault.yml

Let's say the password in vault.yml is "itsasecret". Attempting to view the vault.yml file using the cat command will display something like this.

$ANSIBLE_VAULT;1.1;AES256
66303833643731313633343266616162613965636161313534376563383639646463376630626635
3136316663626536303061333531303234616562323637330a373633393736393863373566623261
65643764336263613730666665663763383063386137383331386136366232666637626566653032
3933393061666138650a656238386665343838613833643435623932306539633138376533613039
6531

Let's say users.yml is the playbook to create John Doe's user account. Here is how you could use the vault encrypted string in users.yml.

---
- hosts: all
  vars:
    password: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          66303833643731313633343266616162613965636161313534376563383639646463376630626635
          3136316663626536303061333531303234616562323637330a373633393736393863373566623261
          65643764336263613730666665663763383063386137383331386136366232666637626566653032
          3933393061666138650a656238386665343838613833643435623932306539633138376533613039
          6531
  tasks:
  - name: create john.doe account
    ansible.builtin.user:
      name: john.doe
      password: "{{ '%s' | format(password) | regex_replace('\n', '') | password_hash('sha512') }}"
      state: present
...

When invoking users.yml to create John Doe's user account, you will either need to use the --ask-vault-pass flag to prompt you for the vault password that was used to decrypt vault.yml.

ansible-playbook users.yml --ask-vault-pass

Better yet, the password that was used to encrypt vault.yml could be appended to a file, such as .vault_password.txt.

echo "shhhhhhhhhh" > .vault_password.txt

And then update .vault_password.txt so that only the owner of the .vault_password.txt file can read and write to the .vault_password.txt file.

chmod 0600 .vault_password.txt

And now the --vault-password-file command line option can be used.

ansible-playbook users.yml --vault-password-file /usr/local/vault/.vault_password.txt

Following are additional, optional options.

• comment: almost always the users first and last name
• create_home: true or false, to create the users home directory
• home: the users home directory
• shell: something like /bin/bash or /bin/sh or /bin/fish
• uid: give the user a certain user ID number

---
- hosts: all
  tasks:
  - name: create john.doe account
    ansible.builtin.user:
      name: john.doe
      comment: John Doe
      password: "{{ 'itsasecret' | password_hash('sha512') }}"
      groups: wheel
      create_home: true
      home: /home/john.doe
      shell: /bin/bash
      uid: 1234
      expires: -1
      state: present
...    

Delete user account

state: absent and remove:yes are used to delete/remove a users account. The remove option is used to remove the /home/john.doe directory.

---
- hosts: all
  tasks:
  - name: delete john.doe account
    ansible.builtin.user:
      name: john.doe
      state: absent
      remove: yes
...

Password expiration

In this example, john.doe user account will never expire, thus john.doe will never need to reset his password.

---
- hosts: all
  tasks:
  - name: john.doe password never expires
    ansible.builtin.user:
      name: john.doe
      expires: -1
...