Ansible Modules¶

cloudformation¶

New in version 1.1.

Launches an AWS CloudFormation stack and waits for it complete.

parameter	required	default	choices	comments
disable_rollback	no	no	yes no	If a stacks fails to form, rollback will remove the stack
region	yes			The AWS region to use. If not specified then the value of the EC2_REGION environment variable, if any, is used.
stack_name	yes			name of the cloudformation stack
state	yes			If state is "present", stack will be created. If state is "present" and if stack exists and template has changed, it will be updated. If state is absent, stack will be removed.
template	yes			the path of the cloudformation template
template_parameters	yes			a list of hashes of all the template variables for the stack

Requirements: boto

# Basic task example
tasks:
- name: launch ansible cloudformation example
  action: cloudformation >
    stack_name="ansible-cloudformation" state=present
    region=us-east-1 disable_rollback=yes
    template=files/cloudformation-example.json
  args:
    template_parameters:
      KeyName: jmartin
      DiskType: ephemeral
      InstanceType: m1.small
      ClusterSize: 3

digital_ocean¶

New in version 1.3.

Create/delete a droplet in DigitalOcean and optionally waits for it to be ‘running’, or deploy an SSH key.

parameter	required	default	choices	comments
api_key	no			Digital Ocean api key.
client_id	no			Digital Ocean manager id.
command	no	droplet	droplet ssh	Which target you want to operate on.
id	no			Numeric, the droplet id you want to operate on.
image_id	no			Numeric, this is the id of the image you would like the droplet created with.
name	no			String, this is the name of the droplet - must be formatted by hostname rules, or the name of a SSH key.
region_id	no			Numeric, this is the id of the region you would like your server
size_id	no			Numeric, this is the id of the size you would like the droplet created at.
ssh_key_ids	no			Optional, comma separated list of ssh_key_ids that you would like to be added to the server
ssh_pub_key	no			The public SSH key you want to add to your account.
state	no	present	present active absent deleted	Indicate desired state of the target.
wait	no	yes	yes no	Wait for the droplet to be in state 'running' before returning. If wait is "no" an ip_address may not be returned.
wait_timeout	no	300		How long before wait gives up, in seconds.

# Ensure a SSH key is present
# If a key matches this name, will return the ssh key id and changed = False
# If no existing key matches this name, a new key is created, the ssh key id is returned and changed = False

- digital_ocean: >
      state=present
      command=ssh
      name=my_ssh_key
      ssh_pub_key='ssh-rsa AAAA...'
      client_id=XXX
      api_key=XXX

# Create a new Droplet
# Will return the droplet details including the droplet id (used for idempotence)

- digital_ocean: >
      state=present
      command=droplet
      name=my_new_droplet
      client_id=XXX
      api_key=XXX
      size_id=1
      region_id=2
      image_id=3
      wait_timeout=500
  register: my_droplet
- debug: msg="ID: {{ my_droplet.droplet.id }} IP: {{ my_droplet.droplet.ip_address }}"

# Ensure a droplet is present
# If droplet id already exist, will return the droplet details and changed = False
# If no droplet matches the id, a new droplet will be created and the droplet details (including the new id) are returned, changed = True.

- digital_ocean: >
      state=present
      command=droplet
      id=123
      name=my_new_droplet
      client_id=XXX
      api_key=XXX
      size_id=1
      region_id=2
      image_id=3
      wait_timeout=500

# Create a droplet with ssh key
# The ssh key id can be passed as argument at the creation of a droplet (see ssh_key_ids).
# Several keys can be added to ssh_key_ids as id1,id2,id3
# The keys are used to connect as root to the droplet.

- digital_ocean: >
      state=present
      ssh_key_ids=id1,id2
      name=my_new_droplet
      client_id=XXX
      api_key=XXX
      size_id=1
      region_id=2
      image_id=3
=======
- digital_ocean: state=present command=ssh name=my_ssh_key ssh_pub_key='ssh-rsa AAAA...' client_id=XXX api_key=XXX

If a key matches this name, will return the ssh key id and changed = False
If no existing key matches this name, a new key is created, the ssh key id is returned and changed = False

# Create a new Droplet
- digital_ocean: state=present command=droplet name=my_new_droplet client_id=XXX api_key=XXX size_id=1 region_id=2 image_id=3 wait_timeout=500

Will return the droplet details including the droplet id (used for idempotence)

# Ensure a droplet is present
- digital_ocean: state=present command=droplet id=123 name=my_new_droplet client_id=XXX api_key=XXX size_id=1 region_id=2 image_id=3 wait_timeout=500

If droplet id already exist, will return the droplet details and changed = False
If no droplet matches the id, a new droplet will be created and the droplet details (including the new id) are returned, changed = True.

# Create a droplet with ssh key
- digital_ocean: state=present ssh_key_ids=id name=my_new_droplet client_id=XXX api_key=XXX size_id=1 region_id=2 image_id=3

The ssh key id can be passed as argument at the creation of a droplet (see ssh_key_ids).
Several keys can be added to ssh_key_ids as id1,id2,id3

The keys are used to connect as root to the droplet.

Notes

Two environment variables can be used, DO_CLIENT_ID and DO_API_KEY.

ec2¶

New in version 0.9.

Creates or terminates ec2 instances. When created optionally waits for it to be ‘running’. This module has a dependency on python-boto >= 2.5

parameter	required	default	choices	comments
aws_access_key	no			AWS access key. If not set then the value of the AWS_ACCESS_KEY environment variable is used.
aws_secret_key	no			AWS secret key. If not set then the value of the AWS_SECRET_KEY environment variable is used.
count	no	1		number of instances to launch
ec2_url	no			Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Must be specified if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used
group	no			security group (or list of groups) to use with the instance
group_id	no			security group id (or list of ids) to use with the instance (added in Ansible 1.1)
id	no			identifier for this instance or set of instances, so that the module will be idempotent with respect to EC2 instances. This identifier is valid for at least 24 hours after the termination of the instance, and should not be reused for another call later on. For details, see the description of client token at http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Run_Instance_Idempotency.html.
image	yes			emi (or ami) to use for the instance
instance_ids	no			list of instance ids, currently only used when state='absent' (added in Ansible 1.3)
instance_profile_name	no			Name of the IAM instance profile to use (added in Ansible 1.3)
instance_tags	no			a hash/dictionary of tags to add to the new instance; '{"key":"value"}' and '{"key":"value","key":"value"}' (added in Ansible 1.0)
instance_type	yes			instance type to use for the instance
kernel	no			kernel eki to use for the instance
key_name	yes			key pair to use on the instance
monitor	no			enable detailed monitoring (CloudWatch) for instance (added in Ansible 1.1)
placement_group	no			placement group for the instance when using EC2 Clustered Compute (added in Ansible 1.3)
private_ip	no			the private ip address to assign the instance (from the vpc subnet) (added in Ansible 1.2)
ramdisk	no			ramdisk eri to use for the instance
region	no			The AWS region to use. Must be specified if ec2_url is not used. If not specified then the value of the EC2_REGION environment variable, if any, is used. (added in Ansible 1.2)
state	no	present		create or terminate instances (added in Ansible 1.3)
user_data	no			opaque blob of data which is made available to the ec2 instance (added in Ansible 0.9)
vpc_subnet_id	no			the subnet ID in which to launch the instance (VPC) (added in Ansible 1.1)
wait	no	no	yes no	wait for the instance to be in state 'running' before returning
wait_timeout	no	300		how long before wait gives up, in seconds
zone	no			AWS availability zone in which to launch the instance (added in Ansible 1.2)

Requirements: boto

# Note: None of these examples set aws_access_key, aws_secret_key, or region.
# It is assumed that their matching environment variables are set.

# Basic provisioning example
- local_action:
    module: ec2
    keypair: mykey
    instance_type: c1.medium
    image: emi-40603AD1
    wait: yes
    group: webserver
    count: 3

# Advanced example with tagging and CloudWatch
- local_action:
    module: ec2
    keypair: mykey
    group: databases
    instance_type: m1.large
    image: ami-6e649707
    wait: yes
    wait_timeout: 500
    count: 5
    instance_tags: '{"db":"postgres"}' monitoring=yes'

# Multiple groups example
local_action:
    module: ec2
    keypair: mykey
    group: ['databases', 'internal-services', 'sshable', 'and-so-forth']
    instance_type: m1.large
    image: ami-6e649707
    wait: yes
    wait_timeout: 500
    count: 5
    instance_tags: '{"db":"postgres"}' monitoring=yes'

# VPC example
- local_action:
    module: ec2
    keypair: mykey
    group_id: sg-1dc53f72
    instance_type: m1.small
    image: ami-6e649707
    wait: yes
    vpc_subnet_id: subnet-29e63245


# Launch instances, runs some tasks
# and then terminate them


- name: Create a sandbox instance
  hosts: localhost
  gather_facts: False
  vars:
    keypair: my_keypair
    instance_type: m1.small
    security_group: my_securitygroup
    image: my_ami_id
    region: us-east-1
  tasks:
    - name: Launch instance
      local_action: ec2 keypair={{ keypair }} group={{ security_group }} instance_type={{ instance_type }} image={{ image }} wait=true region={{ region }}
      register: ec2
    - name: Add new instance to host group
      local_action: add_host hostname={{ item.public_ip }} groupname=launched
      with_items: ec2.instances
    - name: Wait for SSH to come up
      local_action: wait_for host={{ item.public_dns_name }} port=22 delay=60 timeout=320 state=started
      with_items: ec2.instances

- name: Configure instance(s)
  hosts: launched
  sudo: True
  gather_facts: True
  roles:
    - my_awesome_role
    - my_awesome_test

- name: Terminate instances
  hosts: localhost
  connection: local
  tasks:
    - name: Terminate instances that were previously launched
      local_action:
        module: ec2
        state: 'absent'
        instance_ids: {{ec2.instance_ids}}

ec2_ami¶

Creates or deletes ec2 images. This module has a dependency on python-boto >= 2.5

parameter	required	default	choices	comments
aws_access_key	no			AWS access key. If not set then the value of the AWS_ACCESS_KEY environment variable is used.
aws_secret_key	no			AWS secret key. If not set then the value of the AWS_SECRET_KEY environment variable is used.
delete_snapshot	no			Whether or not to deleted an AMI while deregistering it.
description	no			An optional human-readable string describing the contents and purpose of the AMI.
ec2_url	no			Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Must be specified if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used
image_id	no			Image ID to be deregistered.
instance_id	no			instance id of the image to create
name	no			The name of the new image to create
no_reboot	no		yes no	An optional flag indicating that the bundling process should not attempt to shutdown the instance before bundling. If this flag is True, the responsibility of maintaining file system integrity is left to the owner of the instance.
region	no			The AWS region to use. Must be specified if ec2_url is not used. If not specified then the value of the EC2_REGION environment variable, if any, is used.
state	no	present		create or deregister/delete image
wait	no	no	yes no	wait for the AMI to be in state 'available' before returning.
wait_timeout	no	300		how long before wait gives up, in seconds

Requirements: boto

# Basic AMI Creation
- local_action:
    module: ec2_ami
    aws_access_key: xxxxxxxxxxxxxxxxxxxxxxx
    aws_secret_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    instance_id: i-xxxxxx
    wait: yes
    name: newtest
  register: instance

# Basic AMI Creation, without waiting
- local_action:
    module: ec2_ami
    aws_access_key: xxxxxxxxxxxxxxxxxxxxxxx
    aws_secret_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    region: xxxxxx
    instance_id: i-xxxxxx
    wait: no
    name: newtest
  register: instance

# Deregister/Delete AMI
- local_action:
    module: ec2_ami
    aws_access_key: xxxxxxxxxxxxxxxxxxxxxxx
    aws_secret_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    region: xxxxxx
    image_id: ${instance.image_id}
    delete_snapshot: True
    state: absent

# Deregister AMI
- local_action:
    module: ec2_ami
    aws_access_key: xxxxxxxxxxxxxxxxxxxxxxx
    aws_secret_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    region: xxxxxx
    image_id: ${instance.image_id}
    delete_snapshot: False
    state: absent

ec2_elb¶

New in version 1.2.

This module de-registers or registers an AWS EC2 instance from the EL**s** that it belongs to. Returns fact “ec2_elbs” which is a list of elbs attached to the instance if state=absent is passed as an argument. Will be marked changed when called only if there are ELBs found to operate on.

parameter	required	default	choices	comments
aws_access_key	no	None		AWS access key. If not set then the value of the AWS_ACCESS_KEY environment variable is used.
aws_secret_key	no			AWS secret key. If not set then the value of the AWS_SECRET_KEY environment variable is used.
ec2_elbs	no	None		List of ELB names, required for registration. The ec2_elbs fact should be used if there was a previous de-register.
instance_id	yes			EC2 Instance ID
region	no			The AWS region to use. If not specified then the value of the EC2_REGION environment variable, if any, is used.
state	yes			register or deregister the instance
wait	no	True	yes no	Wait for instance registration or deregistration to complete successfully before returning.

Requirements: boto

# basic pre_task and post_task example
pre_tasks:
  - name: Gathering ec2 facts
    ec2_facts:
  - name: Instance De-register
    local_action: ec2_elb
    args:
      instance_id: "{{ ansible_ec2_instance_id }}"
      state: 'absent'
roles:
  - myrole
post_tasks:
  - name: Instance Register
    local_action: ec2_elb
    args:
      instance_id: "{{ ansible_ec2_instance_id }}"
      ec2_elbs: "{{ item }}"
      state: 'present'
    with_items: ec2_elbs

ec2_facts¶

New in version 1.0.

This module fetches data from the metadata servers in ec2 (aws). Eucalyptus cloud provides a similar service and this module should work this cloud provider as well.

# Conditional example
- name: Gather facts
  action: ec2_facts

- name: Conditional
  action: debug msg="This instance is a t1.micro"
  when: ansible_ec2_instance_type == "t1.micro"

Notes

Parameters to filter on ec2_facts may be added later.

ec2_group¶

maintains ec2 security groups. This module has a dependency on python-boto >= 2.5

parameter	required	default	choices	comments
description	yes			Description of the security group.
ec2_access_key	no			EC2 access key
ec2_secret_key	no			EC2 secret key
ec2_url	no			Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints)
name	yes			Name of the security group.
region	no			the EC2 region to use
rules	yes			List of firewall rules to enforce in this group (see example).
vpc_id	no			ID of the VPC to create the group in.

Requirements: boto

- name: example ec2 group
  local_action:
    module: ec2_group
    name: example
    description: an example EC2 group
    vpc_id: 12345
    region: eu-west-1a
    ec2_secret_key: SECRET
    ec2_access_key: ACCESS
    rules:
      - proto: tcp
        from_port: 80
        to_port: 80
        cidr_ip: 0.0.0.0/0
      - proto: tcp
        from_port: 22
        to_port: 22
        cidr_ip: 10.0.0.0/8
      - proto: udp
        from_port: 10050
        to_port: 10050
        cidr_ip: 10.0.0.0/8
      - proto: udp
        from_port: 10051
        to_port: 10051
        group_id: abcdef

ec2_tag¶

New in version 1.3.

Creates and removes tags from any EC2 resource. The resource is referenced by its resource id (e.g. an instance being i-XXXXXXX). It is designed to be used with complex args (tags), see the examples. This module has a dependency on python-boto.

parameter	required	default	choices	comments
aws_access_key	no	None		AWS access key. If not set then the value of the AWS_ACCESS_KEY environment variable is used.
aws_secret_key	no	None		AWS secret key. If not set then the value of the AWS_SECRET_KEY environment variable is used.
ec2_url	no			Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Must be specified if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used.
region	no			region in which the resource exists.
resource	yes			The EC2 resource id.
state	yes			Whether the tags should be present or absent on the resource.

Requirements: boto

# Basic example of adding tag(s)
tasks:
- name: tag a resource
  local_action: ec2_tag resource=vol-XXXXXX region=eu-west-1 state=present
  args:
    tags:
      Name: ubervol
      env: prod

# Playbook example of adding tag(s) to spawned instances
tasks:
- name: launch some instances
  local_action: ec2 keypair={{ keypair }} group={{ security_group }} instance_type={{ instance_type }} image={{ image_id }} wait=true region=eu-west-1
  register: ec2

- name: tag my launched instances
  local_action: ec2_tag resource={{ item.id }} region=eu-west-1 state=present
  with_items: ec2.instances
  args:
    tags:
      Name: webserver
      env: prod

ec2_vol¶

New in version 1.1.

creates an EBS volume and optionally attaches it to an instance. If both an instance ID and a device name is given and the instance has a device at the device name, then no volume is created and no attachment is made. This module has a dependency on python-boto.

parameter	required	default	choices	comments
aws_access_key	no	None		AWS access key. If not set then the value of the AWS_ACCESS_KEY environment variable is used.
aws_secret_key	no	None		AWS secret key. If not set then the value of the AWS_SECRET_KEY environment variable is used.
device_name	no			device id to override device mapping. Assumes /dev/sdf for Linux/UNIX and /dev/xvdf for Windows.
ec2_url	no			Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Must be specified if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used
instance	no			instance ID if you wish to attach the volume.
iops	no	100		the provisioned IOPs you want to associate with this volume (integer). (added in Ansible 1.3)
region	no			The AWS region to use. If not specified then the value of the EC2_REGION environment variable, if any, is used.
volume_size	yes			size of volume (in GB) to create.
zone	no			zone in which to create the volume, if unset uses the zone the instance is in (if set)

Requirements: boto

# Simple attachment action
- local_action:
    module: ec2_vol
    instance: XXXXXX
    volume_size: 5
    device_name: sdd

# Example using custom iops params
- local_action:
    module: ec2_vol
    instance: XXXXXX
    volume_size: 5
    iops: 200
    device_name: sdd

# Playbook example combined with instance launch
- local_action:
    module: ec2
    keypair: "{{ keypair }}"
    image: "{{ image }}"
    wait: yes
    count: 3
    register: ec2
- local_action:
    module: ec2_vol
    instance: "{{ item.id }} "
    volume_size: 5
    with_items: ec2.instances
    register: ec2_vol

glance_image¶

Add or Remove images from the glance repository.

parameter	required	default	choices	comments
auth_url	no	http://127.0.0.1:35357/v2.0/		The keystone url for authentication
container_format	no	bare		The format of the container
copy_from	no	None		A url from where the image can be downloaded, mutually exclusive with file parameter
disk_format	no	qcow2		The format of the disk that is getting uploaded
file	no	None		The path to the file which has to be uploaded, mutually exclusive with copy_from
is_public	no	yes		Whether the image can be accessed publicly
login_password	yes	yes		Password of login user
login_tenant_name	yes	yes		The tenant name of the login user
login_username	yes	admin		login username to authenticate to keystone
min_disk	no	None		The minimum disk space required to deploy this image
min_ram	no	None		The minimum ram required to deploy this image
name	yes	None		Name that has to be given to the image
owner	no	None		The owner of the image
region_name	no	None		Name of the region
state	no	present	present absent	Indicate desired state of the resource
timeout	no	180		The time to wait for the image process to complete in seconds

Requirements: glanceclient keystoneclient

# Upload an image from an HTTP URL
- glance_image: login_username=admin
                login_password=passme
                login_tenant_name=admin
                name=cirros
                container_format=bare
                disk_format=qcow2
                state=present
                copy_from=http:launchpad.net/cirros/trunk/0.3.0/+download/cirros-0.3.0-x86_64-disk.img

keystone_user¶

Manage users,tenants, roles from OpenStack.

parameter	required	default	choices	comments
description	no	None		A description for the tenant
email	no	None		An email address for the user
endpoint	no	http://127.0.0.1:35357/v2.0/		The keystone url for authentication
login_password	no	yes		Password of login user
login_tenant_name	no	None		The tenant login_user belongs to
login_user	no	admin		login username to authenticate to keystone
password	no	None		The password to be assigned to the user
role	no	None		The name of the role to be assigned or created
state	no	present	present absent	Indicate desired state of the resource
tenant	no	None		The tenant name that has be added/removed
token	no	None		The token to be uses in case the password is not specified
user	no	None		The name of the user that has to added/removed from OpenStack

Requirements: python-keystoneclient

# Create a tenant
- keystone_user: tenant=demo tenant_description="Default Tenant"

# Create a user
- keystone_user: user=john tenant=demo password=secrete

# Apply the admin role to the john user in the demo tenant
- keystone_user: role=admin user=john tenant=demo

linode¶

New in version 1.3.

creates / deletes a Linode Public Cloud instance and optionally waits for it to be ‘running’.

parameter	required	default	choices	comments
api_key	no			Linode API key
datacenter	no			datacenter to create an instance in (Linode Datacenter)
distribution	no			distribution to use for the instance (Linode Distribution)
linode_id	no			Unique ID of a linode server
name	no			Name to give the instance (alphanumeric, dashes, underscore)To keep sanity on the Linode Web Console, name is prepended with LinodeID_
password	no			root password to apply to a new server (auto generated if missing)
payment_term	no	1	1 12 24	payment term to use for the instance (payment term in months)
plan	no			plan to use for the instance (Linode plan)
ssh_pub_key	no			SSH public key applied to root user
state	no	present	present active started absent' deleted stopped restarted	Indicate desired state of the resource
swap	no	512		swap size in MB
wait	no	no	yes no	wait for the instance to be in state 'running' before returning
wait_timeout	no	300		how long before wait gives up, in seconds

Requirements: linode-python

# Create a server
- local_action:
     module: linode
     api_key: 'longStringFromLinodeApi'
     name: linode-test1
     plan: 1
     datacenter: 2
     distribution: 99
     password: 'superSecureRootPassword'
     ssh_pub_key: 'ssh-rsa qwerty'
     swap: 768
     wait: yes
     wait_timeout: 600
     state: present

# Ensure a running server (create if missing)
- local_action:
     module: linode
     api_key: 'longStringFromLinodeApi'
     name: linode-test1
     linode_id: 12345678
     plan: 1
     datacenter: 2
     distribution: 99
     password: 'superSecureRootPassword'
     ssh_pub_key: 'ssh-rsa qwerty'
     swap: 768
     wait: yes
     wait_timeout: 600
     state: present

# Delete a server
- local_action:
     module: linode
     api_key: 'longStringFromLinodeApi'
     name: linode-test1
     linode_id: 12345678
     state: absent

# Stop a server
- local_action:
     module: linode
     api_key: 'longStringFromLinodeApi'
     name: linode-test1
     linode_id: 12345678
     state: stopped

# Reboot a server
- local_action:
     module: linode
     api_key: 'longStringFromLinodeApi'
     name: linode-test1
     linode_id: 12345678
     state: restarted

Notes

LINODE_API_KEY env variable can be used instead

nova_compute¶

Create or Remove virtual machines from Openstack.

parameter	required	default	choices	comments
auth_url	no	http://127.0.0.1:35357/v2.0/		The keystone url for authentication
flavor_id	no	1		The id of the flavor in which the new VM has to be created
image_id	yes	None		The id of the image that has to be cloned
key_name	no	None		The key pair name to be used when creating a VM
login_password	yes	yes		Password of login user
login_tenant_name	yes	yes		The tenant name of the login user
login_username	yes	admin		login username to authenticate to keystone
meta	no	None		A list of key value pairs that should be provided as a metadata to the new VM
name	yes	None		Name that has to be given to the image
nics	no	None		A list of network id's to which the VM's interface should be attached
region_name	no	None		Name of the region
security_groups	no	None		The name of the security group to which the VM should be added
state	no	present	present absent	Indicate desired state of the resource
wait	no	yes		If the module should wait for the VM to be created.
wait_for	no	180		The amount of time the module should wait for the VM to get into active state

Requirements: novaclient

# Creates a new VM and attaches to a network and passes metadata to the instance
- nova_compute:
       state: present
       login_username: admin
       login_password: admin
       login_tenant_name: admin
       name: vm1
       image_id: 4f905f38-e52a-43d2-b6ec-754a13ffb529
       key_name: ansible_key
       wait_for: 200
       flavor_id: 4
       nics:
         - net-id: 34605f38-e52a-25d2-b6ec-754a13ffb723
       meta:
         hostname: test1
         group: uge_master

nova_keypair¶

Add or Remove key pair from nova .

parameter	required	default	choices	comments
auth_url	no	http://127.0.0.1:35357/v2.0/		The keystone url for authentication
login_password	yes	yes		Password of login user
login_tenant_name	yes	yes		The tenant name of the login user
login_username	yes	admin		login username to authenticate to keystone
name	yes	None		Name that has to be given to the key pair
public_key	no	None		The public key that would be uploaded to nova and injected to vm's upon creation
region_name	no	None		Name of the region
state	no	present	present absent	Indicate desired state of the resource

Requirements: novaclient

# Creates a key pair with the running users public key
- nova_keypair: state=present login_username=admin
                login_password=admin login_tenant_name=admin name=ansible_key
                public_key={{ lookup('file','~/.ssh/id_rsa.pub') }}

# Creates a new key pair and the private key returned after the run.
- nova_keypair: state=present login_username=admin login_password=admin
                login_tenant_name=admin name=ansible_key

quantum_floating_ip¶

Add or Remove a floating IP to an instance

parameter	required	default	choices	comments
auth_url	no	http://127.0.0.1:35357/v2.0/		The keystone url for authentication
instance_name	yes	None		The name of the instance to which the IP address should be assigned
login_password	yes	yes		Password of login user
login_tenant_name	yes	yes		The tenant name of the login user
login_username	yes	admin		login username to authenticate to keystone
network_name	yes	None		Name of the network from which IP has to be assigned to VM. Please make sure the network is an external network
region_name	no	None		Name of the region
state	no	present	present absent	Indicate desired state of the resource

Requirements: novaclient quantumclient keystoneclient

# Assign a floating ip to the instance from an external network
- quantum_floating_ip: state=present login_username=admin login_password=admin
                       login_tenant_name=admin network_name=external_network
                       instance_name=vm1

quantum_floating_ip_associate¶

Associates or disassociates a specific floating IP with a particular instance

parameter	required	default	choices	comments
auth_url	no	http://127.0.0.1:35357/v2.0/		the keystone url for authentication
instance_name	yes	None		name of the instance to which the public IP should be assigned
ip_address	yes	None		floating ip that should be assigned to the instance
login_password	yes	yes		password of login user
login_tenant_name	yes	True		the tenant name of the login user
login_username	yes	admin		login username to authenticate to keystone
region_name	no	None		name of the region
state	no	present	present absent	indicates the desired state of the resource

Requirements: quantumclient keystoneclient

# Associate a specific floating IP with an Instance
- quantum_floating_ip_associate:
           state=present
           login_username=admin
           login_password=admin
           login_tenant_name=admin
           ip_address=1.1.1.1
           instance_name=vm1

quantum_network¶

Add or Remove network from OpenStack.

parameter	required	default	choices	comments
admin_state_up	no	True		Whether the state should be marked as up or down
auth_url	no	http://127.0.0.1:35357/v2.0/		The keystone url for authentication
login_password	yes	yes		Password of login user
login_tenant_name	yes	yes		The tenant name of the login user
login_username	yes	admin		login username to authenticate to keystone
name	yes	None		Name to be assigned to the nework
provider_network_type	no	None		The type of the network to be created, gre, vlan, local. Available types depend on the plugin. The Quantum service decides if not specified.
provider_physical_network	no	None		The physical network which would realize the virtual network for flat and vlan networks.
provider_segmentation_id	no	None		The id that has to be assigned to the network, in case of vlan networks that would be vlan id and for gre the tunnel id
region_name	no	None		Name of the region
router_external	no			If 'yes', specifies that the virtual network is a external network (public).
shared	no			Whether this network is shared or not
state	no	present	present absent	Indicate desired state of the resource
tenant_name	no	None		The name of the tenant for whom the network is created

Requirements: quantumclient keystoneclient

# Create a GRE backed Quantum network with tunnel id 1 for tenant1
- quantum_network: name=t1network tenant_name=tenant1 state=present
                   provider_network_type=gre provider_segmentation_id=1
                   login_username=admin login_password=admin login_tenant_name=admin

# Create an external network
- quantum_network: name=external_network state=present
                   provider_network_type=local router_external=yes
                   login_username=admin login_password=admin login_tenant_name=admin

quantum_router¶

Create or Delete routers from OpenStack

parameter	required	default	choices	comments
admin_state_up	no	True		desired admin state of the created router .
auth_url	no	http://127.0.0.1:35357/v2.0/		The keystone url for authentication
login_password	yes	yes		Password of login user
login_tenant_name	yes	yes		The tenant name of the login user
login_username	yes	admin		login username to authenticate to keystone
name	yes	None		Name to be give to the router
region_name	no	None		Name of the region
state	no	present	present absent	Indicate desired state of the resource
tenant_name	no	None		Name of the tenant for which the router has to be created, if none router would be created for the login tenant.

Requirements: quantumclient keystoneclient

# Creates a router for tenant admin
- quantum_router: state=present
                login_username=admin
                login_password=admin
                login_tenant_name=admin
                name=router1"

quantum_router_gateway¶

Creates/Removes a gateway interface from the router, used to associate a external network with a router to route external traffic.

parameter	required	default	choices	comments
auth_url	no	http://127.0.0.1:35357/v2.0/		The keystone URL for authentication
login_password	yes	yes		Password of login user
login_tenant_name	yes	yes		The tenant name of the login user
login_username	yes	admin		login username to authenticate to keystone
network_name	yes	None		Name of the external network which should be attached to the router.
region_name	no	None		Name of the region
router_name	yes	None		Name of the router to which the gateway should be attached.
state	no	present	present absent	Indicate desired state of the resource

Requirements: quantumclient keystoneclient

# Attach an external network with a router to allow flow of external traffic
- quantum_router_gateway: state=present login_username=admin login_password=admin
                          login_tenant_name=admin router_name=external_router
                          network_name=external_network

quantum_router_interface¶

Attach/Dettach a subnet interface to a router, to provide a gateway for the subnet.

parameter	required	default	choices	comments
auth_url	no	http://127.0.0.1:35357/v2.0/		The keystone URL for authentication
login_password	yes	yes		Password of login user
login_tenant_name	yes	yes		The tenant name of the login user
login_username	yes	admin		login username to authenticate to keystone
region_name	no	None		Name of the region
router_name	yes	None		Name of the router to which the subnet's interface should be attached.
state	no	present	present absent	Indicate desired state of the resource
subnet_name	yes	None		Name of the subnet to whose interface should be attached to the router.
tenant_name	no	None		Name of the tenant whose subnet has to be attached.

Requirements: quantumclient keystoneclient

# Attach tenant1's subnet to the external router
- quantum_router_interface: state=present login_username=admin
                            login_password=admin
                            login_tenant_name=admin
                            tenant_name=tenant1
                            router_name=external_route
                            subnet_name=t1subnet

quantum_subnet¶

Add or Remove a floating IP to an instance

parameter	required	default	choices	comments
allocation_pool_end	no	None		From the subnet pool the last IP that should be assigned to the virtual machines
allocation_pool_start	no	None		From the subnet pool the starting address from which the IP should be allocated
auth_url	no	http://127.0.0.1:35357/v2.0/		The keystone URL for authentication
cidr	yes	None		The CIDR representation of the subnet that should be assigned to the subnet
enable_dhcp	no	True		Whether DHCP should be enabled for this subnet.
gateway_ip	no	None		The ip that would be assigned to the gateway for this subnet
ip_version	no	4		The IP version of the subnet 4 or 6
login_password	yes	True		Password of login user
login_tenant_name	yes	True		The tenant name of the login user
login_username	yes	admin		login username to authenticate to keystone
network_name	yes	None		Name of the network to which the subnet should be attached
region_name	no	None		Name of the region
state	no	present	present absent	Indicate desired state of the resource
tenant_name	no	None		The name of the tenant for whom the subnet should be created

Requirements: quantum keystoneclient

# Create a subnet for a tenant with the specified subnet
- quantum_subnet: state=present login_username=admin login_password=admin
                  login_tenant_name=admin tenant_name=tenant1
                  network_name=network1 name=net1subnet cidr=192.168.0.0/24"

rax¶

New in version 1.2.

creates / deletes a Rackspace Public Cloud instance and optionally waits for it to be ‘running’.

parameter	required	default	choices	comments
api_key	no			Rackspace API key (overrides credentials)
credentials	no			File to find the Rackspace credentials in (ignored if api_key and username are provided)
files	no			Files to insert into the instance. remotefilename:localcontent
flavor	no			flavor to use for the instance
image	no			image to use for the instance
key_name	no			key pair to use on the instance
meta	no			A hash of metadata to associate with the instance
name	no			Name to give the instance
region	no	DFW		Region to create an instance in
service	no	cloudservers	cloudservers	Cloud service to interact with
state	no	present	present active absent deleted	Indicate desired state of the resource
username	no			Rackspace username (overrides credentials)
wait	no	no	yes no	wait for the instance to be in state 'running' before returning
wait_timeout	no	300		how long before wait gives up, in seconds

Requirements: pyrax

- name: Build a Cloud Server
  gather_facts: False

  tasks:
    - name: Server build request
      local_action:
        module: rax
        credentials: ~/.raxpub
        service: cloudservers
        name: rax-test1
        flavor: 5
        image: b11d9567-e412-4255-96b9-bd63ab23bcfe
        files:
          /root/.ssh/authorized_keys: /home/localuser/.ssh/id_rsa.pub
          /root/test.txt: /home/localuser/test.txt
        wait: yes
        state: present

Notes

The following environment variables can be used, RAX_USERNAME, RAX_API_KEY, RAX_CREDS, RAX_CREDENTIALS, RAX_REGION.

RAX_CREDENTIALS and RAX_CREDS points to a credentials file appropriate for pyrax

RAX_USERNAME and RAX_API_KEY obviate the use of a credentials file

RAX_REGION defines a Rackspace Public Cloud region (DFW, ORD, LON, ...)

rds¶

New in version 1.3.

Creates or deletes rds instances. When creating an instance it can be either a new instance or a read-only replica of an existing instance. This module has a dependency on python-boto >= 2.5.

parameter	required	default	choices	comments
apply_immediately	no		yes no	Used only when command=modify. If enabled, the modifications will be applied as soon as possible rather than waiting for the next preferred maintenance window.
aws_access_key	no			AWS access key. If not set then the value of the AWS_ACCESS_KEY environment variable is used.
aws_secret_key	no			AWS secret key. If not set then the value of the AWS_SECRET_KEY environment variable is used.
backup_retention	no			Number of days backups are retained. Set to 0 to disable backups. Default is 1 day. Valid range: 0-35. Used only when command=create or command=modify.
backup_window	no			Backup window in format of hh24:mi-hh24:mi. If not specified then a random backup window is assigned. Used only when command=create or command=modify.
command	yes		create replicate delete facts modify	Specifies the action to take.
db_engine	no		MySQL oracle-se1 oracle-se oracle-ee sqlserver-ee sqlserver-se sqlserver-ex sqlserver-web	The type of database. Used only when command=create.
db_name	no			Name of a database to create within the instance. If not specified then no database is created. Used only when command=create.
engine_version	no			Version number of the database engine to use. Used only when command=create. If not specified then the current Amazon RDS default engine version is used.
instance_name	yes			Database instance identifier.
instance_type	no		db.t1.micro db.m1.small db.m1.medium db.m1.large db.m1.xlarge db.m2.xlarge db.m2.2xlarge db.m2.4xlarge	The instance type of the database. Must be specified when command=create. Optional when command=replicate or command=modify. If not specified then the replica inherits the same instance type as the source instance.
iops	no			Specifies the number of IOPS for the instance. Used only when command=create or command=modify. Must be an integer greater than 1000.
license_model	no		license-included bring-your-own-license general-public-license	The license model for this DB instance. Used only when command=create.
maint_window	no			Maintenance window in format of ddd:hh24:mi-ddd:hh24:mi. (Example: Mon:22:00-Mon:23:15) If not specified then a random maintenance window is assigned. Used only when command=create or command=modify.
multi_zone	no		yes no	Specifies if this is a Multi-availability-zone deployment. Can not be used in conjunction with zone parameter. Used only when command=create or command=modify.
option_group	no			The name of the option group to use. If not specified then the default option group is used. Used only when command=create.
parameter_group	no			Name of the DB parameter group to associate with this instance. If omitted then the RDS default DBParameterGroup will be used. Used only when command=create or command=modify.
password	no			Password for the master database username. Used only when command=create or command=modify.
port	no			Port number that the DB instance uses for connections. Defaults to 3306 for mysql, 1521 for Oracle, 1443 for SQL Server. Used only when command=create or command=replicate.
region	yes			The AWS region to use. If not specified then the value of the EC2_REGION environment variable, if any, is used.
security_groups	no			Comma separated list of one or more security groups. Used only when command=create or command=modify. If a subnet is specified then this is treated as a list of VPC security groups.
size	no			Size in gigabytes of the initial storage for the DB instance. Used only when command=create or command=modify.
snapshot	no			Name of final snapshot to take when deleting an instance. If no snapshot name is provided then no snapshot is taken. Used only when command=delete.
source_instance	no			Name of the database to replicate. Used only when command=replicate.
subnet	no			VPC subnet group. If specified then a VPC instance is created. Used only when command=create.
upgrade	no		yes no	Indicates that minor version upgrades should be applied automatically. Used only when command=create or command=replicate.
username	no			Master database username. Used only when command=create.
wait	no	no	yes no	When command=create, replicate, or modify then wait for the database to enter the 'available' state. When command=delete wait for the database to be terminated.
wait_timeout	no	300		how long before wait gives up, in seconds
zone	no			availability zone in which to launch the instance. Used only when command=create or command=replicate.

Requirements: boto

# Basic mysql provisioning example
- rds: >
      command=create
      instance_name=new_database
      db_engine=MySQL
      size=10
      instance_type=db.m1.small
      username=mysql_admin
      password=1nsecure

# Create a read-only replica and wait for it to become available
- rds: >
      command=replicate
      instance_name=new_database_replica
      source_instance=new_database
      wait=yes
      wait_timeout=600

# Delete an instance, but create a snapshot before doing so
- rds: >
      command=delete
      instance_name=new_database
      snapshot=new_database_snapshot

# Get facts about an instance
- rds: >
      command=facts
      instance_name=new_database
      register: new_database_facts

route53¶

New in version 1.3.

Creates and deletes DNS records in Amazons Route53 service

parameter	required	default	choices	comments
aws_access_key	no			AWS access key.
aws_secret_key	no			AWS secret key.
command	yes		get create delete	Specifies the action to take.
overwrite	no			Whether an existing record should be overwritten on create if values do not match
record	yes			The full DNS record to create or delete
ttl	no	3600 (one hour)		The TTL to give the new record
type	yes		A CNAME MX AAAA TXT PTR SRV SPF NS	The type of DNS record to create
value	no			The new value when creating a DNS record. Multiple comma-spaced values are allowed. When deleting a record all values for the record must be specified or Route53 will not delete it.
zone	yes			The DNS zone to modify

Requirements: boto

# Add new.foo.com as an A record with 3 IPs
- route53: >
      command=create
      zone=foo.com
      record=new.foo.com
      type=A
      ttl=7200
      value=1.1.1.1,2.2.2.2,3.3.3.3

# Retrieve the details for new.foo.com
- route53: >
      command=get
      zone=foo.com
      record=new.foo.com
      type=A
  register: rec

# Delete new.foo.com A record using the results from the get command
- route53: >
      command=delete
      zone=foo.com
      record={{ rec.set.record }}
      type={{ rec.set.type }}
      value={{ rec.set.value }}

# Add an AAAA record.  Note that because there are colons in the value
# that the entire parameter list must be quoted:
- route53: >
      "command=create
      zone=foo.com
      record=localhost.foo.com
      type=AAAA
      ttl=7200
      value=::1"

s3¶

New in version 1.1.

This module allows the user to dictate the presence of a given file in an S3 bucket. If or once the key (file) exists in the bucket, it returns a time-expired download URL. This module has a dependency on python-boto.

parameter	required	default	choices	comments
aws_access_key	no			AWS access key. If not set then the value of the AWS_ACCESS_KEY environment variable is used.
aws_secret_key	no			AWS secret key. If not set then the value of the AWS_SECRET_KEY environment variable is used.
bucket	yes			Bucket name.
dest	no	600		The destination file path when downloading an object/key with a GET operation. (added in Ansible 1.3)
expiry	no			Time limit (in seconds) for the URL generated and returned by S3/Walrus when performing a mode=put or mode=geturl operation.
mode	yes			Switches the module behaviour between put (upload), get (download), geturl (return download url (Ansible 1.3+), getstr (download object as string (1.3+)), create (bucket) and delete (bucket).
object	no			Keyname of the object inside the bucket. Can be used to create "virtual directories", see examples. (added in Ansible 1.3)
overwrite	no			Force overwrite either locally on the filesystem or remotely with the object/key. Used with PUT and GET operations. (added in Ansible 1.2)
s3_url	no			S3 URL endpoint. If not specified then the S3_URL environment variable is used, if that variable is defined.
src	no			The source file path when performing a PUT operation. (added in Ansible 1.3)

Requirements: boto

# Simple PUT operation
- s3: bucket=mybucket object=/my/desired/key.txt src=/usr/local/myfile.txt mode=put
# Simple GET operation
- s3: bucket=mybucket object=/my/desired/key.txt dest=/usr/local/myfile.txt mode=get
# GET/download and overwrite local file (trust remote)
- s3: bucket=mybucket object=/my/desired/key.txt dest=/usr/local/myfile.txt mode=get overwrite=true
# PUT/upload and overwrite remote file (trust local)
- s3: bucket=mybucket object=/my/desired/key.txt src=/usr/local/myfile.txt mode=put overwrite=true
# Download an object as a string to use else where in your playbook
- s3: bucket=mybucket object=/my/desired/key.txt src=/usr/local/myfile.txt mode=getstr
# Create an empty bucket
- s3: bucket=mybucket mode=create
# Create a bucket with key as directory
- s3: bucket=mybucket object=/my/directory/path mode=create
# Delete a bucket and all contents
- s3: bucket=mybucket mode=delete

virt¶

New in version 0.2.

Manages virtual machines supported by libvirt.

parameter	required	default	choices	comments
command	no		create status start stop pause unpause shutdown undefine destroy get_xml autostart freemem list_vms info nodeinfo virttype define	in addition to state management, various non-idempotent commands are available. See examples
name	yes			name of the guest VM being managed. Note that VM must be previously defined with xml.
state	no	no	running shutdown	Note that there may be some lag for state requests like shutdown since these refer only to VM states. After starting a guest, it may not be immediately accessible.
uri	no			libvirt connection uri
xml	no			XML document used with the define command

Requirements: libvirt

# a playbook task line:
- virt: name=alpha state=running

# /usr/bin/ansible invocations
ansible host -m virt -a "name=alpha command=status"
ansible host -m virt -a "name=alpha command=get_xml"
ansible host -m virt -a "name=alpha command=create uri=lxc:///"

# a playbook example of defining and launching an LXC guest
tasks:
  - name: define vm
    virt: name=foo
          command=define
          xml="{{ lookup('template', 'container-template.xml.j2') }}"
          uri=lxc:///
  - name: start vm
    virt: name=foo state=running uri=lxc:///

command¶

The command module takes the command name followed by a list of space-delimited arguments. The given command will be executed on all selected nodes. It will not be processed through the shell, so variables like $HOME and operations like "<", ">", "|", and "&" will not work.

parameter	required	default	choices	comments
chdir	no			cd into this directory before running the command (added in Ansible 0.6)
creates	no			a filename, when it already exists, this step will not be run.
executable	no			change the shell used to execute the command. Should be an absolute path to the executable. (added in Ansible 0.9)
free_form	yes			the command module takes a free form command to run
removes	no			a filename, when it does not exist, this step will not be run. (added in Ansible 0.8)

# Example from Ansible Playbooks
- command: /sbin/shutdown -t now

# Run the command if the specified file does not exist
- command: /usr/bin/make_database.sh arg1 arg2 creates=/path/to/database

Notes

If you want to run a command through the shell (say you are using <, >, |, etc), you actually want the shell module instead. The command module is much more secure as it's not affected by the user's environment.

creates, removes, and chdir can be specified after the command. For instance, if you only want to run a command if a certain file does not exist, use this.

raw¶

Executes a low-down and dirty SSH command, not going through the module subsystem. This is useful and should only be done in two cases. The first case is installing python-simplejson on older (Python 2.4 and before) hosts that need it as a dependency to run modules, since nearly all core modules require it. Another is speaking to any devices such as routers that do not have any Python installed. In any other case, using the shell or command module is much more appropriate. Arguments given to raw are run directly through the configured remote shell. Standard output, error output and return code are returned when available. There is no change handler support for this module. This module does not require python on the remote system, much like the script module.

parameter	required	default	choices	comments
executable	no			change the shell used to execute the command. Should be an absolute path to the executable. (added in Ansible 1.0)
free_form	yes			the raw module takes a free form command to run

# Bootstrap a legacy python 2.4 host
- raw: yum -y install python-simplejson

Notes

If you want to execute a command securely and predictably, it may be better to use the command module instead. Best practices when writing playbooks will follow the trend of using command unless shell is explicitly required. When running ad-hoc commands, use your best judgement.

script¶

The script module takes the script name followed by a list of space-delimited arguments. The local script at path will be transfered to the remote node and then executed. The given script will be processed through the shell environment on the remote node. This module does not require python on the remote system, much like the raw module.

parameter	required	default	choices	comments
free_form	yes			path to the local script file followed by optional arguments.

# Example from Ansible Playbooks
- script: /some/local/script.sh --some-arguments 1234

Notes

It is usually preferable to write Ansible modules than pushing scripts. Convert your script to an Ansible module for bonus points!

shell¶

New in version 0.2.

The shell module takes the command name followed by a list of arguments, space delimited. It is almost exactly like the command module but runs the command through a shell (/bin/sh) on the remote node.

parameter	required	default	choices	comments
(free form)	no			The command module takes a free form command to run
chdir	no			cd into this directory before running the command (added in Ansible 0.6)
creates	no			a filename, when it already exists, this step will NOT be run
executable	no			change the shell used to execute the command. Should be an absolute path to the executable. (added in Ansible 0.9)

# Execute the command in remote shell; stdout goes to the specified
# file on the remote
- shell: somescript.sh >> somelog.txt

Notes

If you want to execute a command securely and predictably, it may be better to use the command module instead. Best practices when writing playbooks will follow the trend of using command unless shell is explicitly required. When running ad-hoc commands, use your best judgement.

mongodb_user¶

New in version 1.1.

Adds or removes a user from a MongoDB database.

parameter	required	default	choices	comments
database	yes			The name of the database to add/remove the user from
login_host	no	localhost		The host running the database
login_password	no			The password used to authenticate with
login_port	no	27017		The port to connect to
login_user	no			The username used to authenticate with
password	no			The password to use for the user
roles	no	readWrite		The database user roles valid values are one or more of the following: read, 'readWrite', 'dbAdmin', 'userAdmin', 'clusterAdmin', 'readAnyDatabase', 'readWriteAnyDatabase', 'userAdminAnyDatabase', 'dbAdminAnyDatabase'This param requires mongodb 2.4+ and pymongo 2.5+ (added in Ansible 1.3)
state	no	present	present absent	The database user state
user	yes			The name of the user to add or remove

Requirements: pymongo

# Create 'burgers' database user with name 'bob' and password '12345'.
- mongodb_user: database=burgers name=bob password=12345 state=present

# Delete 'burgers' database user with name 'bob'.
- mongodb_user: database=burgers name=bob state=absent

# Define more users with various specific roles (if not defined, no roles is assigned, and the user will be added via pre mongo 2.2 style)
- mongodb_user: database=burgers name=ben password=12345 roles='read' state=present
- mongodb_user: database=burgers name=jim password=12345 roles='readWrite,dbAdmin,userAdmin' state=present
- mongodb_user: database=burgers name=joe password=12345 roles='readWriteAnyDatabase' state=present

Notes

Requires the pymongo Python package on the remote host, version 2.4.2+. This can be installed using pip or the OS package manager. @see http://api.mongodb.org/python/current/installation.html

mysql_db¶

New in version 0.6.

Add or remove MySQL databases from a remote host.

parameter	required	default	choices	comments
collation	no			Collation mode
encoding	no			Encoding mode
login_host	no	localhost		Host running the database
login_password	no			The password used to authenticate with
login_unix_socket	no			The path to a Unix domain socket for local connections
login_user	no			The username used to authenticate with
name	yes			name of the database to add or remove
state	no	present	present absent dump import	The database state
target	no			Where to dump/get the .sql file

Requirements: ConfigParser

# Create a new database with name 'bobdata'
- mysql_db: name=bobdata state=present

Notes

Requires the MySQLdb Python package on the remote host. For Ubuntu, this is as easy as apt-get install python-mysqldb. (See apt.)

Both login_password and login_user are required when you are passing credentials. If none are present, the module will attempt to read the credentials from ~/.my.cnf, and finally fall back to using the MySQL default login of root with no password.

mysql_replication¶

New in version 1.3.

Manages MySQL server replication, slave, master status get and change master host.

parameter	required	default	choices	comments
login_host	no			mysql host to connect
login_password	no			password to connect mysql host, if defined login_user also needed.
login_unix_socket	no			unix socket to connect mysql server
login_user	no			username to connect mysql host, if defined login_password also needed.
master_connect_retry	no			same as mysql variable
master_host	no			same as mysql variable
master_log_file	no			same as mysql variable
master_log_pos	no			same as mysql variable
master_password	no			same as mysql variable
master_port	no			same as mysql variable
master_ssl	no			same as mysql variable
master_ssl_ca	no			same as mysql variable
master_ssl_capath	no			same as mysql variable
master_ssl_cert	no			same as mysql variable
master_ssl_cipher	no			same as mysql variable
master_ssl_key	no			same as mysql variable
master_user	no			same as mysql variable
mode	no	getslave	getslave getmaster changemaster stopslave startslave	module operating mode. Could be getslave (SHOW SLAVE STATUS), getmaster (SHOW MASTER STATUS), changemaster (CHANGE MASTER TO), startslave (START SLAVE), stopslave (STOP SLAVE)
relay_log_file	no			same as mysql variable
relay_log_pos	no			same as mysql variable

# Stop mysql slave thread
- mysql_replication: mode=stopslave

# Get master binlog file name and binlog position
- mysql_replication: mode=getmaster

# Change master to master server 192.168.1.1 and use binary log 'mysql-bin.000009' with position 4578
- mysql_replication: mode=changemaster master_host=192.168.1.1 master_log_file=mysql-bin.000009 master_log_pos=4578

mysql_user¶

New in version 0.6.

Adds or removes a user from a MySQL database.

parameter	required	default	choices	comments
check_implicit_admin	no			Check if mysql allows login as root/nopassword before trying supplied credentials. (added in Ansible 1.3)
host	no	localhost		the 'host' part of the MySQL username
login_host	no	localhost		Host running the database
login_password	no			The password used to authenticate with
login_unix_socket	no			The path to a Unix domain socket for local connections
login_user	no			The username used to authenticate with
name	yes			name of the user (role) to add or remove
password	no			set the user's password
priv	no			MySQL privileges string in the format: db.table:priv1,priv2
state	no	present	present absent	Whether the user should exist. When absent, removes the user.

Requirements: ConfigParser MySQLdb

# Create database user with name 'bob' and password '12345' with all database privileges
- mysql_user: name=bob password=12345 priv=*.*:ALL state=present

# Ensure no user named 'sally' exists, also passing in the auth credentials.
- mysql_user: login_user=root login_password=123456 name=sally state=absent

# Example privileges string format
mydb.*:INSERT,UPDATE/anotherdb.*:SELECT/yetanotherdb.*:ALL

# Example using login_unix_socket to connect to server
- mysql_user: name=root password=abc123 login_unix_socket=/var/run/mysqld/mysqld.sock

# Example .my.cnf file for setting the root password
# Note: don't use quotes around the password, because the mysql_user module
# will include them in the password but the mysql client will not

[client]
user=root
password=n<_665{vS43y

Notes

Requires the MySQLdb Python package on the remote host. For Ubuntu, this is as easy as apt-get install python-mysqldb.

Both login_password and login_username are required when you are passing credentials. If none are present, the module will attempt to read the credentials from ~/.my.cnf, and finally fall back to using the MySQL default login of 'root' with no password.

MySQL server installs with default login_user of 'root' and no password. To secure this user as part of an idempotent playbook, you must create at least two tasks: the first must change the root user's password, without providing any login_user/login_password details. The second must drop a ~/.my.cnf file containing the new root credentials. Subsequent runs of the playbook will then succeed by reading the new credentials from the file.

mysql_variables¶

New in version 1.3.

Query / Set MySQL variables

parameter	required	default	choices	comments
login_host	no			mysql host to connect
login_password	no			password to connect mysql host, if defined login_user also needed.
login_unix_socket	no			unix socket to connect mysql server
login_user	no			username to connect mysql host, if defined login_password also needed.
value	no			If set, then sets variable value to this
variable	yes			Variable name to operate

# Check for sync_binary_log setting
- mysql_variables: variable=sync_binary_log

# Set read_only variable to 1
- mysql_variables: variable=read_only value=1

postgresql_db¶

New in version 0.6.

Add or remove PostgreSQL databases from a remote host.

parameter	required	default	choices	comments
encoding	no			Encoding of the database
lc_collate	no			Collation order (LC_COLLATE) to use in the database. Must match collation order of template database unless template0 is used as template.
lc_ctype	no			Character classification (LC_CTYPE) to use in the database (e.g. lower, upper, ...) Must match LC_CTYPE of template database unless template0 is used as template.
login_host	no	localhost		Host running the database
login_password	no			The password used to authenticate with
login_user	no			The username used to authenticate with
name	yes			name of the database to add or remove
owner	no			Name of the role to set as owner of the database
state	no	present	present absent	The database state
template	no			Template used to create the database

Requirements: psycopg2

# Create a new database with name "acme"
- postgresql_db: name=acme

# Create a new database with name "acme" and specific encoding and locale
# settings. If a template different from "template0" is specified, encoding
# and locale settings must match those of the template.
- postgresql_db: name=acme
                 encoding='UTF-8'
                 lc_collate='de_DE.UTF-8'
                 lc_ctype='de_DE.UTF-8'
                 template='template0'

Notes

The default authentication assumes that you are either logging in as or sudo'ing to the postgres account on the host.

This module uses psycopg2, a Python PostgreSQL database adapter. You must ensure that psycopg2 is installed on the host before using this module. If the remote host is the PostgreSQL server (which is the default case), then PostgreSQL must also be installed on the remote host. For Ubuntu-based systems, install the postgresql, libpq-dev, and python-psycopg2 packages on the remote host before using this module.

postgresql_privs¶

Grant or revoke privileges on PostgreSQL database objects. This module is basically a wrapper around most of the functionality of PostgreSQL’s GRANT and REVOKE statements with detection of changes (GRANT/REVOKE privs ON type objs TO/FROM roles)

parameter	required	default	choices	comments
database	yes			Name of database to connect to.Alias: db
grant_option	no		yes no	Whether role may grant/revoke the specified privileges/group memberships to others.Set to no to revoke GRANT OPTION, leave unspecified to make no changes.grant_option only has an effect if state is present.Alias: admin_option
host	no			Database host address. If unspecified, connect via Unix socket.Alias: login_host
login	no	postgres		The username to authenticate with.Alias: login_user
objs	no			Comma separated list of database objects to set privileges on.If type is table or sequence, the special value ALL_IN_SCHEMA can be provided instead to specify all database objects of type type in the schema specified via schema. (This also works with PostgreSQL < 9.0.)If type is database, this parameter can be omitted, in which case privileges are set for the database specified via database.If type is function, colons (":") in object names will be replaced with commas (needed to specify function signatures, see examples)Alias: obj
password	no			The password to authenticate with.Alias: login_password)
port	no	5432		Database port to connect to.
privs	no			Comma separated list of privileges to grant/revoke.Alias: priv
roles	yes			Comma separated list of role (user/group) names to set permissions for.The special value PUBLIC can be provided instead to set permissions for the implicitly defined PUBLIC group.Alias: role
schema	no			Schema that contains the database objects specified via objs.May only be provided if type is table, sequence or function. Defaults to public in these cases.
state	no	present	present absent	If present, the specified privileges are granted, if absent they are revoked.
type	no	table	table sequence function database schema language tablespace group	Type of database object to set privileges on.

Requirements: psycopg2

# On database "library":
# GRANT SELECT, INSERT, UPDATE ON TABLE public.books, public.authors
# TO librarian, reader WITH GRANT OPTION
- postgresql_privs: >
    database=library
    state=present
    privs=SELECT,INSERT,UPDATE
    type=table
    objs=books,authors
    schema=public
    roles=librarian,reader
    grant_option=yes

# Same as above leveraging default values:
- postgresql_privs: >
    db=library
    privs=SELECT,INSERT,UPDATE
    objs=books,authors
    roles=librarian,reader
    grant_option=yes

# REVOKE GRANT OPTION FOR INSERT ON TABLE books FROM reader
# Note that role "reader" will be *granted* INSERT privilege itself if this
# isn't already the case (since state=present).
- postgresql_privs: >
    db=library
    state=present
    priv=INSERT
    obj=books
    role=reader
    grant_option=no

# REVOKE INSERT, UPDATE ON ALL TABLES IN SCHEMA public FROM reader
# "public" is the default schema. This also works for PostgreSQL 8.x.
- postgresql_privs: >
    db=library
    state=absent
    privs=INSERT,UPDATE
    objs=ALL_IN_SCHEMA
    role=reader

# GRANT ALL PRIVILEGES ON SCHEMA public, math TO librarian
- postgresql_privs: >
    db=library
    privs=ALL
    type=schema
    objs=public,math
    role=librarian

# GRANT ALL PRIVILEGES ON FUNCTION math.add(int, int) TO librarian, reader
# Note the separation of arguments with colons.
- postgresql_privs: >
    db=library
    privs=ALL
    type=function
    obj=add(int:int)
    schema=math
    roles=librarian,reader

# GRANT librarian, reader TO alice, bob WITH ADMIN OPTION
# Note that group role memberships apply cluster-wide and therefore are not
# restricted to database "library" here.
- postgresql_privs: >
    db=library
    type=group
    objs=librarian,reader
    roles=alice,bob
    admin_option=yes

# GRANT ALL PRIVILEGES ON DATABASE library TO librarian
# Note that here "db=postgres" specifies the database to connect to, not the
# database to grant privileges on (which is specified via the "objs" param)
- postgresql_privs: >
    db=postgres
    privs=ALL
    type=database
    obj=library
    role=librarian

# GRANT ALL PRIVILEGES ON DATABASE library TO librarian
# If objs is omitted for type "database", it defaults to the database
# to which the connection is established
- postgresql_privs: >
    db=library
    privs=ALL
    type=database
    role=librarian

Notes

Default authentication assumes that postgresql_privs is run by the postgres user on the remote host. (Ansible's user or sudo-user).

This module requires Python package psycopg2 to be installed on the remote host. In the default case of the remote host also being the PostgreSQL server, PostgreSQL has to be installed there as well, obviously. For Debian/Ubuntu-based systems, install packages postgresql and python-psycopg2.

Parameters that accept comma separated lists (privs, objs, roles) have singular alias names (priv, obj, role).

To revoke only GRANT OPTION for a specific object, set state to present and grant_option to no (see examples).

Note that when revoking privileges from a role R, this role may still have access via privileges granted to any role R is a member of including PUBLIC.

Note that when revoking privileges from a role R, you do so as the user specified via login. If R has been granted the same privileges by another user also, R can still access database objects via these privileges.

When revoking privileges, RESTRICT is assumed (see PostgreSQL docs).

postgresql_user¶

New in version 0.6.

Add or remove PostgreSQL users (roles) from a remote host and, optionally, grant the users access to an existing database or tables. The fundamental function of the module is to create, or delete, roles from a PostgreSQL cluster. Privilege assignment, or removal, is an optional step, which works on one database at a time. This allows for the module to be called several times in the same module to modify the permissions on different databases, or to grant permissions to already existing users. A user cannot be removed until all the privileges have been stripped from the user. In such situation, if the module tries to remove the user it will fail. To avoid this from happening the fail_on_user option signals the module to try to remove the user, but if not possible keep going; the module will report if changes happened and separately if the user was removed or not.

parameter	required	default	choices	comments
db	no			name of database where permissions will be granted
fail_on_user	no	yes	yes no	if yes, fail when user can't be removed. Otherwise just log and continue
login_host	no	localhost		Host running PostgreSQL.
login_password	no			Password used to authenticate with PostgreSQL
login_user	no	postgres		User (role) used to authenticate with PostgreSQL
name	yes			name of the user (role) to add or remove
password	yes			set the user's password
priv	no			PostgreSQL privileges string in the format: table:priv1,priv2
role_attr_flags	no		[NO]SUPERUSER [NO]CREATEROLE [NO]CREATEUSER [NO]CREATEDB [NO]INHERIT [NO]LOGIN [NO]REPLICATION	PostgreSQL role attributes string in the format: CREATEDB,CREATEROLE,SUPERUSER
state	no	present	present absent	The user (role) state

Requirements: psycopg2

# Create django user and grant access to database and products table
- postgresql_user: db=acme user=django password=ceec4eif7ya priv=CONNECT/products:ALL

# Create rails user, grant privilege to create other databases and demote rails from super user status
- postgresql_user: user=rails password=secret role_attr_flags=CREATEDB,NOSUPERUSER

# Remove test user privileges from acme
- postgresql_user: db=acme user=test priv=ALL/products:ALL state=absent fail_on_user=no

# Remove test user from test database and the cluster
- postgresql_user: db=test user=test priv=ALL state=absent

# Example privileges string format
INSERT,UPDATE/table:SELECT/anothertable:ALL

Notes

The default authentication assumes that you are either logging in as or sudo'ing to the postgres account on the host.

This module uses psycopg2, a Python PostgreSQL database adapter. You must ensure that psycopg2 is installed on the host before using this module. If the remote host is the PostgreSQL server (which is the default case), then PostgreSQL must also be installed on the remote host. For Ubuntu-based systems, install the postgresql, libpq-dev, and python-psycopg2 packages on the remote host before using this module.

If you specify PUBLIC as the user, then the privilege changes will apply to all users. You may not specify password or role_attr_flags when the PUBLIC user is specified.

redis¶

New in version 1.3.

Unified utility to interact with redis instances. ‘slave’ Sets a redis instance in slave or master mode. ‘flush’ Flushes all the instance or a specified db.

parameter	required	default	choices	comments
command	yes		slave flush	The selected redis command
db	no			The database to flush (used in db mode) [flush command]
flush_mode	no	all	all db	Type of flush (all the dbs in a redis instance or a specific one) [flush command]
login_host	no	localhost		The host running the database
login_password	no			The password used to authenticate with (usually not used)
login_port	no	6379		The port to connect to
master_host	no			The host of the master instance [slave command]
master_port	no			The port of the master instance [slave command]
slave_mode	no	slave	master slave	the mode of the redis instance [slave command]

Requirements: redis

# Set local redis instance to be slave of melee.island on port 6377
- redis: command=slave master_host=melee.island master_port=6377

# Deactivate slave mode
- redis: command=slave slave_mode=master

# Flush all the redis db
- redis: command=flush flush_mode=all

# Flush only one db in a redis instance
- redis: command=flush db=1 flush_mode=db

Notes

Requires the redis-py Python package on the remote host. You can install it with pip (pip install redis) or with a package manager. https://github.com/andymccurdy/redis-py

If the redis master instance we are making slave of is password protected this needs to be in the redis.conf in the masterauth variable

riak¶

New in version 1.2.

This module can be used to join nodes to a cluster, check the status of the cluster.

parameter	required	default	choices	comments
command	no		ping kv_test join plan commit	The command you would like to perform against the cluster.
config_dir	no	/etc/riak		The path to the riak configuration directory
http_conn	no	127.0.0.1:8098		The ip address and port that is listening for Riak HTTP queries
target_node	no	riak@127.0.0.1		The target node for certain operations (join, ping)
wait_for_handoffs	no			Number of seconds to wait for handoffs to complete.
wait_for_ring	no			Number of seconds to wait for all nodes to agree on the ring.
wait_for_service	no	None	kv	Waits for a riak service to come online before continuing.

# Join's a Riak node to another node
- riak: command=join target_node=riak@10.1.1.1

# Wait for handoffs to finish.  Use with async and poll.
- riak: wait_for_handoffs=yes

# Wait for riak_kv service to startup
- riak: wait_for_service=kv

assemble¶

New in version 0.5.

Assembles a configuration file from fragments. Often a particular program will take a single configuration file and does not support a conf.d style structure where it is easy to build up the configuration from multiple sources. assemble will take a directory of files that have already been transferred to the system, and concatenate them together to produce a destination file. Files are assembled in string sorting order. Puppet calls this idea fragments.

parameter	required	default	choices	comments
backup	no	no	yes no	Create a backup file (if yes), including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly.
dest	yes			A file to create using the concatenation of all of the source files.
others	no			all arguments accepted by the file module also work here
src	yes			An already existing directory full of source files.

# Example from Ansible Playbooks
- assemble: src=/etc/someapp/fragments dest=/etc/someapp/someapp.conf

copy¶

The copy module copies a file on the local box to remote locations.

parameter	required	default	choices	comments
backup	no	no	yes no	Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly. (added in Ansible 0.7)
content	no			When used instead of 'src', sets the contents of a file directly to the specified value. (added in Ansible 1.1)
dest	yes			Remote absolute path where the file should be copied to.
force	no	yes	yes no	the default is yes, which will replace the remote file when contents are different than the source. If no, the file will only be transferred if the destination does not exist. (added in Ansible 1.1)
others	no			all arguments accepted by the file module also work here
src	no			Local path to a file to copy to the remote server; can be absolute or relative.
validate	no			validation to run before copying into place (added in Ansible 1.2)

# Example from Ansible Playbooks
- copy: src=/srv/myfiles/foo.conf dest=/etc/foo.conf owner=foo group=foo mode=0644

# Copy a new "ntp.conf file into place, backing up the original if it differs from the copied version
- copy: src=/mine/ntp.conf dest=/etc/ntp.conf owner=root group=root mode=644 backup=yes

# Copy a new "sudoers" file into place, after passing validation with visudo
- copy: src=/mine/sudoers dest=/etc/sudoers validate='visudo -cf %s'

Notes

The "copy" module can't be used to recursively copy directory structures to the target machine. Please see the "Delegation" section of the Advanced Playbooks documentation for a better approach to recursive copies.

fetch¶

New in version 0.2.

This module works like copy, but in reverse. It is used for fetching files from remote machines and storing them locally in a file tree, organized by hostname. Note that this module is written to transfer log files that might not be present, so a missing remote file won’t be an error unless fail_on_missing is set to ‘yes’.

parameter	required	default	choices	comments
dest	yes			A directory to save the file into. For example, if the dest directory is /backup a src file named /etc/profile on host host.example.com, would be saved into /backup/host.example.com/etc/profile
fail_on_missing	no	no	yes no	Makes it fails when the source file is missing. (added in Ansible 1.1)
flat	no			Allows you to override the default behavior of prepending hostname/path/to/file to the destination. If dest ends with '/', it will use the basename of the source file, similar to the copy module. Obviously this is only handy if the filenames are unqiue. (added in Ansible 1.2)
src	yes			The file on the remote system to fetch. This must be a file, not a directory. Recursive fetching may be supported in a later release.

# Store file into /tmp/fetched/host.example.com/tmp/somefile
- fetch: src=/tmp/somefile dest=/tmp/fetched

# Specifying a path directly
- fetch: src=/tmp/somefile dest=/tmp/prefix-{{ ansible_hostname }} flat=yes

# Specifying a destination path
- fetch: src=/tmp/uniquefile dest=/tmp/special/ flat=yes

# Storing in a path relative to the playbook
- fetch: src=/tmp/uniquefile dest=special/prefix-{{ ansible_hostname }} flat=yes

file¶

Sets attributes of files, symlinks, and directories, or removes files/symlinks/directories. Many other modules support the same options as the file module - including copy, template, and assemble.

parameter	required	default	choices	comments
force	no	no	yes no	force the creation of the symlinks in two cases: the source file does not exist (but will appear later); the destination exists and a file (so, we need to unlink the "path" file and create symlink to the "src" file in place of it).
group	no			name of the group that should own the file/directory, as would be fed to chown
mode	no			mode the file or directory should be, such as 0644 as would be fed to chmod
owner	no			name of the user that should own the file/directory, as would be fed to chown
path	yes			defines the file being managed, unless when used with state=link, and then sets the destination to create a symbolic link to using src. Aliases: dest, name
recurse	no	no	yes no	recursively set the specified file attributes (applies only to state=directory) (added in Ansible 1.1)
selevel	no	s0		level part of the SELinux file context. This is the MLS/MCS attribute, sometimes known as the range. _default feature works as for seuser.
serole	no			role part of SELinux file context, _default feature works as for seuser.
setype	no			type part of SELinux file context, _default feature works as for seuser.
seuser	no			user part of SELinux file context. Will default to system policy, if applicable. If set to _default, it will use the user portion of the policy if available
src	no			path of the file to link to (applies only to state=link).
state	no	file	file link directory hard absent	If directory, all immediate subdirectories will be created if they do not exist. If file, the file will NOT be created if it does not exist, see the copy or template module if you want that behavior. If link, the symbolic link will be created or changed. Use hard for hardlinks. If absent, directories will be recursively deleted, and files or symlinks will be unlinked.

- file: path=/etc/foo.conf owner=foo group=foo mode=0644
- file: src=/file/to/link/to dest=/path/to/symlink owner=foo group=foo state=link

Notes

See also copy, template, assemble

ini_file¶

New in version 0.9.

Manage (add, remove, change) individual settings in an INI-style file without having to manage the file as a whole with, say, template or assemble. Adds missing sections if they don’t exist.

parameter	required	default	choices	comments
backup	no	no	yes no	Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly.
dest	yes			Path to the INI-style file; this file is created if required
option	no			if set (required for changing a value), this is the name of the option.May be omitted if adding/removing a whole section.
others	no			all arguments accepted by the file module also work here
section	yes			Section name in INI file. This is added if state=present automatically when a single value is being set.
value	no			the string value to be associated with an option. May be omitted when removing an option.

Requirements: ConfigParser

# Ensure "fav=lemonade is in section "[drinks]" in specified file
- ini_file: dest=/etc/conf section=drinks option=fav value=lemonade mode=0600 backup=yes

- ini_file: dest=/etc/anotherconf
            section=drinks
            option=temperature
            value=cold
            backup=yes

Notes

While it is possible to add an option without specifying a value, this makes no sense.

A section named default cannot be added by the module, but if it exists, individual options within the section can be updated. (This is a limitation of Python's ConfigParser.) Either use template to create a base INI file with a [default] section, or use lineinfile to add the missing line.

lineinfile¶

New in version 0.7.

This module will search a file for a line, and ensure that it is present or absent. This is primarily useful when you want to change a single line in a file only. For other cases, see the copy or template modules.

parameter	required	default	choices	comments
backrefs	no	no	yes no	Used with state=present. If set, line can contain backreferences (both positional and named) that will get populated if the regexp matches. This flag changes the operation of the module slightly; insertbefore and insertafter will be ignored, and if the regexp doesn't match anywhere in the file, the file will be left unchanged. If the regexp does match, the last matching line will be replaced by the expanded line parameter. (added in Ansible 1.1)
backup	no	no	yes no	Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly.
create	no	no	yes no	Used with state=present. If specified, the file will be created if it does not already exist. By default it will fail if the file is missing.
dest	yes			The file to modify.
insertafter	no	EOF	EOF *regex*	Used with state=present. If specified, the line will be inserted after the specified regular expression. A special value is available; EOF for inserting the line at the end of the file. May not be used with backrefs.
insertbefore	no		BOF *regex*	Used with state=present. If specified, the line will be inserted before the specified regular expression. A value is available; BOF for inserting the line at the beginning of the file. May not be used with backrefs. (added in Ansible 1.1)
line	no			Required for state=present. The line to insert/replace into the file. If backrefs is set, may contain backreferences that will get expanded with the regexp capture groups if the regexp matches. The backreferences should be double escaped (see examples).
others	no			All arguments accepted by the file module also work here.
regexp	yes			The regular expression to look for in every line of the file. For state=present, the pattern to replace if found; only the last line found will be replaced. For state=absent, the pattern of the line to remove. Uses Python regular expressions; see http://docs.python.org/2/library/re.html.
state	no	present	present absent	Whether the line should be there or not.

- lineinfile: dest=/etc/selinux/config regexp=^SELINUX= line=SELINUX=disabled

- lineinfile: dest=/etc/sudoers state=absent regexp="^%wheel"

- lineinfile: dest=/etc/hosts regexp='^127\.0\.0\.1' line='127.0.0.1 localhost' owner=root group=root mode=0644

- lineinfile: dest=/etc/httpd/conf/httpd.conf regexp="^Listen " insertafter="^#Listen " line="Listen 8080"

- lineinfile: dest=/etc/services regexp="^# port for http" insertbefore="^www.*80/tcp" line="# port for http by default"

# Fully quoted because of the ': ' on the line. See the Gotchas in the YAML docs.
- lineinfile: "dest=/etc/sudoers state=present regexp='^%wheel' line='%wheel ALL=(ALL) NOPASSWD: ALL'"

- lineinfile: dest=/opt/jboss-as/bin/standalone.conf regexp='^(.*)Xms(\d+)m(.*)$' line='\1Xms${xms}m\3' backrefs=yes

stat¶

New in version 1.3.

Retrieves facts for a file similar to the linux/unix ‘stat’ command.

parameter	required	default	choices	comments
follow	no			Whether to follow symlinks
path	yes			The full path of the file/object to get the facts of

# Obtain the stats of /etc/foo.conf, and check that the file still belongs
# to 'root'. Fail otherwise.
- stat: path=/etc/foo.conf
  register: st
- fail: msg="Whoops! file ownership has changed"
  when: st.stat.pw_name != 'root'

# Determine if a path exists and is a directory.  Note we need to test
# both that p.stat.isdir actually exists, and also that it's set to true.
- stat: path=/path/to/something
  register: p
- debug: msg="Path exists and is a directory"
  when: p.stat.isdir is defined and p.stat.isdir == true

template¶

Templates are processed by the Jinja2 templating language (http://jinja.pocoo.org/docs/) - documentation on the template formatting can be found in the Template Designer Documentation (http://jinja.pocoo.org/docs/templates/). Six additional variables can be used in templates: ansible_managed (configurable via the defaults section of ansible.cfg) contains a string which can be used to describe the template name, host, modification time of the template file and the owner uid, template_host contains the node name of the template’s machine, template_uid the owner, template_path the relative path of the template, template_fullpath is the absolute path of the template, and template_run_date is the date that the template was rendered.

parameter	required	default	choices	comments
backup	no	no	yes no	Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly.
dest	yes			Location to render the template to on the remote machine.
others	no			all arguments accepted by the file module also work here
src	yes			Path of a Jinja2 formatted template on the local server. This can be a relative or absolute path.
validate	no			validation to run before copying into place (added in Ansible 1.2)

# Example from Ansible Playbooks
- template: src=/mytemplates/foo.j2 dest=/etc/file.conf owner=bin group=wheel mode=0644

# Copy a new "sudoers file into place, after passing validation with visudo
- action: template src=/mine/sudoers dest=/etc/sudoers validate='visudo -cf %s'

Notes

Since Ansible version 0.9, templates are loaded with trim_blocks=True.

You can override jinja2 settings by adding a special header to template file. i.e. #jinja2: trim_blocks: False

xattr¶

New in version 1.3.

Manages filesystem user defined extended attributes, requires that they are enabled on the target filesystem and that the setfattr/getfattr utilities are present.

parameter	required	default	choices	comments
follow	no	True	yes no	if yes, dereferences symlinks and sets/gets attributes on symlink target, otherwise acts on symlink itself.
key	no	None		The name of a specific Extended attribute key to set/retrieve
name	yes	None		The full path of the file/object to get the facts of
state	no	get	read present all keys absent	defines which state you want to do. read retrieves the current value for a key (default) present sets name to value, default if value is set all dumps all data keys retrieves all keys absent deletes the key
value	no	None		The value to set the named name/key to, it automatically sets the state to 'set'

# Obtain the extended attributes  of /etc/foo.conf
- xattr: name=/etc/foo.conf

# Sets the key 'foo' to value 'bar'
- xattr: path=/etc/foo.conf key=user.foo value=bar

# Removes the key 'foo'
- xattr: name=/etc/foo.conf key=user.foo state=absent

async_status¶

New in version 0.5.

This module gets the status of an asynchronous task. See: http://www.ansibleworks.com/docs/playbooks2.html#asynchronous-actions-and-polling

parameter	required	default	choices	comments
jid	yes			Job or task identifier
mode	no	status	status cleanup	if status, obtain the status; if cleanup, clean up the async job cache located in ~/.ansible_async/ for the specified job jid.

Notes

See http://www.ansibleworks.com/docs/playbooks2.html#asynchronous-actions-and-polling

add_host¶

New in version 0.9.

Use variables to create new hosts and groups in inventory for use in later plays of the same playbook. Takes variables so you can define the new hosts more fully.

parameter	required	default	choices	comments
groups	no			The groups to add the hostname to, comma separated.
name	yes			The hostname/ip of the host to add to the inventory, can include a colon and a port number.

# add host to group 'just_created' with variable foo=42
- add_host: name={{ ip_from_ec2 }} groups=just_created foo=42

# add a host with a non-standard port local to your machines
- add_host: name={{ new_ip }}:{{ new_port }}

# add a host alias that we reach through a tunnel
- add_host: hostname={{ new_ip }}
            ansible_ssh_host={{ inventory_hostname }}
            ansible_ssh_port={{ new_port }}

group_by¶

New in version 0.9.

Use facts to create ad-hoc groups that can be used later in a playbook.

parameter	required	default	choices	comments
key	yes			The variables whose values will be used as groups

# Create groups based on the machine architecture
-  group_by: key=machine_{{ ansible_machine }}
# Create groups like 'kvm-host'
-  group_by: key=virt_{{ ansible_virtualization_type }}_{{ ansible_virtualization_role }}

Notes

Spaces in group names are converted to dashes '-'.

rabbitmq_parameter¶

New in version 1.1.

Manage dynamic, cluster-wide parameters for RabbitMQ

parameter	required	default	choices	comments
component	yes			Name of the component of which the parameter is being set
name	yes			Name of the parameter being set
node	no	rabbit		erlang node name of the rabbit we wish to configure
state	no	present	present absent	Specify if user is to be added or removed
value	no			Value of the parameter, as a JSON term
vhost	no	/		vhost to apply access privileges.

# Set the federation parameter 'local_username' to a value of 'guest' (in quotes)
- rabbitmq_parameter: component=federation
                      name=local-username
                      value='"guest"'
                      state=present

rabbitmq_plugin¶

New in version 1.1.

Enables or disables RabbitMQ plugins

parameter	required	default	choices	comments
names	yes			Comma-separated list of plugin names
new_only	no	no	yes no	Only enable missing pluginsDoes not disable plugins that are not in the names list
prefix	no			Specify a custom install prefix to a Rabbit (added in Ansible 1.3)
state	no	enabled	enabled disabled	Specify if plugins are to be enabled or disabled

# Enables the rabbitmq_management plugin
- rabbitmq_plugin: names=rabbitmq_management state=enabled

rabbitmq_user¶

New in version 1.1.

Add or remove users to RabbitMQ and assign permissions

parameter	required	default	choices	comments
configure_priv	no	^$		Regular expression to restrict configure actions on a resource for the specified vhost.By default all actions are restricted.
force	no	no	yes no	Deletes and recreates the user.
node	no	rabbit		erlang node name of the rabbit we wish to configure
password	no			Password of user to add.To change the password of an existing user, you must also specify force=yes.
read_priv	no	^$		Regular expression to restrict configure actions on a resource for the specified vhost.By default all actions are restricted.
state	no	present	present absent	Specify if user is to be added or removed
tags	no			User tags specified as comma delimited
user	yes			Name of user to add
vhost	no	/		vhost to apply access privileges.
write_priv	no	^$		Regular expression to restrict configure actions on a resource for the specified vhost.By default all actions are restricted.

# Add user to server and assign full access control
- rabbitmq_user: user=joe
                 password=changeme
                 vhost=/
                 configure_priv=.*
                 read_priv=.*
                 write_priv=.*
                 state=present

rabbitmq_vhost¶

New in version 1.1.

Manage the state of a virtual host in RabbitMQ

parameter	required	default	choices	comments
name	yes			The name of the vhost to manage
node	no	rabbit		erlang node name of the rabbit we wish to configure
state	no	present	present absent	The state of vhost
tracing	no	no	yes no	Enable/disable tracing for a vhost

# Ensure that the vhost /test exists.
- rabbitmq_vhost: name=/test state=present

airbrake_deployment¶

New in version 1.2.

Notify airbrake about app deployments (see http://help.airbrake.io/kb/api-2/deploy-tracking)

parameter	required	default	choices	comments
environment	yes			The airbrake environment name, typically 'production', 'staging', etc.
repo	no			URL of the project repository
revision	no			A hash, number, tag, or other identifier showing what revision was deployed
token	yes			API token.
user	no			The username of the person doing the deployment

Requirements: urllib urllib2

- airbrake_deployment: token=AAAAAA
                       environment='staging'
                       user='ansible'
                       revision=4.2

boundary_meter¶

New in version 1.3.

This module manages boundary meters

parameter	required	default	choices	comments
apiid	yes			Organizations boundary API ID
apikey	yes			Organizations boundary API KEY
name	yes			meter name
state	no	True	present absent	Whether to create or remove the client from boundary

Requirements: Boundary API access bprobe is required to send data, but not to register a meter Python urllib2

- name: Create meter
  boundary_meter: apiid=AAAAAA api_key=BBBBBB state=present name={{ inventory_hostname }}"

- name: Delete meter
  boundary_meter: apiid=AAAAAA api_key=BBBBBB state=absent name={{ inventory_hostname }}"

Notes

This module does not yet support boundary tags.

datadog_event¶

New in version 1.3.

Allows to post events to DataDog (www.datadoghq.com) service. Uses http://docs.datadoghq.com/api/#events API.

parameter	required	default	choices	comments
aggregation_key	no			An arbitrary string to use for aggregation.
alert_type	no	info	error warning info success	Type of alert.
api_key	yes			Your DataDog API key.
date_happened	no	now		POSIX timestamp of the event.Default value is now.
priority	no	normal	normal low	The priority of the event.
tags	no			Comma separated list of tags to apply to the event.
text	yes			The body of the event.
title	yes			The event title.

Requirements: urllib2

# Post an event with low priority
datadog_event: title="Testing from ansible" text="Test!" priority="low"
               api_key="6873258723457823548234234234"
# Post an event with several tags
datadog_event: title="Testing from ansible" text="Test!"
               api_key="6873258723457823548234234234"
               tags=aa,bb,cc

monit¶

New in version 1.2.

Manage the state of a program monitored via Monit

parameter	required	default	choices	comments
name	yes			The name of the monit program/process to manage
state	yes		present started stopped restarted monitored unmonitored reloaded	The state of service

# Manage the state of program "httpd" to be in "started" state.
- monit: name=httpd state=started

nagios¶

New in version 0.7.

The nagios module has two basic functions: scheduling downtime and toggling alerts for services or hosts. All actions require the host parameter to be given explicitly. In playbooks you can use the {{inventory_hostname}} variable to refer to the host the playbook is currently running on. You can specify multiple services at once by separating them with commas, .e.g., services=httpd,nfs,puppet. When specifying what service to handle there is a special service value, host, which will handle alerts/downtime for the host itself, e.g., service=host. This keyword may not be given with other services at the same time. Setting alerts/downtime for a host does not affect alerts/downtime for any of the services running on it. To schedule downtime for all services on particular host use keyword “all”, e.g., service=all. When using the nagios module you will need to specify your Nagios server using the delegate_to parameter.

parameter	required	default	choices	comments
action	yes		downtime enable_alerts disable_alerts silence unsilence silence_nagios unsilence_nagios command	Action to take.
author	no	Ansible		Author to leave downtime comments as. Only usable with the downtime action.
cmdfile	no	auto-detected		Path to the nagios command file (FIFO pipe). Only required if auto-detection fails.
command	yes			The raw command to send to nagios, which should not include the submitted time header or the line-feed Required option when using the command action.
host	no			Host to operate on in Nagios.
minutes	no	30		Minutes to schedule downtime for.Only usable with the downtime action.
services	yes			What to manage downtime/alerts for. Separate multiple services with commas. service is an alias for services. Required option when using the downtime, enable_alerts, and disable_alerts actions.

Requirements: Nagios

# set 30 minutes of apache downtime
- nagios: action=downtime minutes=30 service=httpd host={{ inventory_hostname }}

# schedule an hour of HOST downtime
- nagios: action=downtime minutes=60 service=host host={{ inventory_hostname }}

# schedule downtime for ALL services on HOST
- nagios: action=downtime minutes=45 service=all host={{ inventory_hostname }}

# schedule downtime for a few services
- nagios: action=downtime services=frob,foobar,qeuz host={{ inventory_hostname }}

# enable SMART disk alerts
- nagios: action=enable_alerts service=smart host={{ inventory_hostname }}

# "two services at once: disable httpd and nfs alerts"
- nagios: action=disable_alerts service=httpd,nfs host={{ inventory_hostname }}

# disable HOST alerts
- nagios: action=disable_alerts service=host host={{ inventory_hostname }}

# silence ALL alerts
- nagios: action=silence host={{ inventory_hostname }}

# unsilence all alerts
- nagios: action=unsilence host={{ inventory_hostname }}

# SHUT UP NAGIOS
- nagios: action=silence_nagios

# ANNOY ME NAGIOS
- nagios: action=unsilence_nagios

# command something
- nagios: action=command command='DISABLE_FAILURE_PREDICTION'

newrelic_deployment¶

New in version 1.2.

Notify newrelic about app deployments (see http://newrelic.github.io/newrelic_api/NewRelicApi/Deployment.html)

parameter	required	default	choices	comments
app_name	no			(one of app_name or application_id are required) The value of app_name in the newrelic.yml file used by the application
application_id	no			(one of app_name or application_id are required) The application id, found in the URL when viewing the application in RPM
appname	no			Name of the application
changelog	no			A list of changes for this deployment
description	no			Text annotation for the deployment - notes for you
environment	no			The environment for this deployment
revision	no			A revision number (e.g., git commit SHA)
token	yes			API token.
user	no			The name of the user/process that triggered this deployment

Requirements: urllib urllib2

- newrelic_deployment: token=AAAAAA
                       app_name=myapp
                       user='ansible deployment'
                       revision=1.0

pagerduty¶

New in version 1.2.

This module will let you create PagerDuty maintenance windows

parameter	required	default	choices	comments
desc	no	Created by Ansible		Short description of maintenance window.
hours	no	1		Length of maintenance window in hours.
name	yes			PagerDuty unique subdomain.
passwd	yes			PagerDuty user password.
service	no			PagerDuty service ID.
state	yes		running started ongoing	Create a maintenance window or get a list of ongoing windows.
user	yes			PagerDuty user ID.

Requirements: PagerDuty API access

# List ongoing maintenance windows.
- pagerduty: name=companyabc user=example@example.com passwd=password123 state=ongoing

# Create a 1 hour maintenance window for service FOO123.
- pagerduty: name=companyabc
             user=example@example.com
             passwd=password123
             state=running
             service=FOO123

# Create a 4 hour maintenance window for service FOO123 with the description "deployment".
- pagerduty: name=companyabc
             user=example@example.com
             passwd=password123
             state=running
             service=FOO123
             hours=4
             desc=deployment

Notes

This module does not yet have support to end maintenance windows.

pingdom¶

New in version 1.2.

This module will let you pause/unpause Pingdom alerts

parameter	required	default	choices	comments
checkid	yes			Pingdom ID of the check.
key	yes			Pingdom API key.
passwd	yes			Pingdom user password.
state	yes		running paused	Define whether or not the check should be running or paused.
uid	yes			Pingdom user ID.

Requirements: This pingdom python library: https://github.com/mbabineau/pingdom-python

# Pause the check with the ID of 12345.
- pingdom: uid=example@example.com
           passwd=password123
           key=apipassword123
           checkid=12345
           state=paused

# Unpause the check with the ID of 12345.
- pingdom: uid=example@example.com
           passwd=password123
           key=apipassword123
           checkid=12345
           state=running

Notes

This module does not yet have support to add/remove checks.

arista_interface¶

Manage physical Ethernet interface resources on Arista EOS network devices

parameter	required	default	choices	comments
admin	no		up down	controls the operational state of the interface
description	no			a single line text string describing the interface
duplex	no	auto	auto half full	sets the interface duplex setting
interface_id	yes			the full name of the interface
logging	no		true false yes no	enables or disables the syslog facility for this module
mtu	no	1500		configureds the maximum transmission unit for the interface
speed	no	auto	auto 100m 1g 10g	sets the interface speed setting

Requirements: Arista EOS 4.10 Netdev extension for EOS

Example playbook entries using the arista_interface module to manage resource
state.  Note that interface names must be the full interface name not shortcut
names (ie Ethernet, not Et1)

    tasks:
    - name: enable interface Ethernet 1
      action: arista_interface interface_id=Ethernet1 admin=up speed=10g duplex=full logging=true

    - name: set mtu on Ethernet 1
      action: arista_interface interface_id=Ethernet1 mtu=1600 speed=10g duplex=full logging=true

    - name: reset changes to Ethernet 1
      action: arista_interface interface_id=Ethernet1 admin=down mtu=1500 speed=10g duplex=full logging=true

Notes

Requires EOS 4.10 or later

The Netdev extension for EOS must be installed and active in the available extensions (show extensions from the EOS CLI)

See http://eos.aristanetworks.com for details

arista_l2interface¶

Manage layer 2 interface resources on Arista EOS network devices

parameter	required	default	choices	comments
interface_id	yes			the full name of the interface
logging	no		true false yes no	enables or disables the syslog facility for this module
state	no	present	present absent	describe the desired state of the interface related to the config
tagged_vlans	no			specifies the list of vlans that should be allowed to transit this interface
untagged_vlan	no	default		specifies the vlan that untagged traffic should be placed in for transit across a vlan tagged link
vlan_tagging	no	True	enable disable	specifies whether or not vlan tagging should be enabled for this interface

Requirements: Arista EOS 4.10 Netdev extension for EOS

Example playbook entries using the arista_l2interface module to manage resource
state. Note that interface names must be the full interface name not shortcut
names (ie Ethernet, not Et1)

    tasks:
    - name: create switchport ethernet1 access port
      action: arista_l2interface interface_id=Ethernet1 logging=true

    - name: create switchport ethernet2 trunk port
      action: arista_l2interface interface_id=Ethernet2 vlan_tagging=enable logging=true

    - name: add vlans to red and blue switchport ethernet2
      action: arista_l2interface interface_id=Ethernet2 tagged_vlans=red,blue logging=true

    - name: set untagged vlan for Ethernet1
      action: arista_l2interface interface_id=Ethernet1 untagged_vlan=red logging=true

    - name: convert access to trunk
      action: arista_l2interface interface_id=Ethernet1 vlan_tagging=enable tagged_vlans=red,blue logging=true

    - name: convert trunk to access
      action: arista_l2interface interface_id=Ethernet2 vlan_tagging=disable untagged_vlan=blue logging=true

    - name: delete switchport ethernet1
      action: arista_l2interface interface_id=Ethernet1 state=absent logging=true

Notes

Requires EOS 4.10 or later

The Netdev extension for EOS must be installed and active in the available extensions (show extensions from the EOS CLI)

See http://eos.aristanetworks.com for details

arista_lag¶

Manage port channel interface resources on Arista EOS network devices

parameter	required	default	choices	comments
interface_id	yes			the full name of the interface
lacp	no	active	active passive off	enables the use of the LACP protocol for managing link bundles
links	no			array of physical interface links to include in this lag
logging	no		true false yes no	enables or disables the syslog facility for this module
minimum_links	no			the minimum number of physical interaces that must be operationally up to consider the lag operationally up
state	no	present	present absent	describe the desired state of the interface related to the config

Requirements: Arista EOS 4.10 Netdev extension for EOS

Example playbook entries using the arista_lag module to manage resource
state.  Note that interface names must be the full interface name not shortcut
names (ie Ethernet, not Et1)

    tasks:
    - name: create lag interface
      action: arista_lag interface_id=Port-Channel1 links=Ethernet1,Ethernet2 logging=true

    - name: add member links
      action: arista_lag interface_id=Port-Channel1 links=Ethernet1,Ethernet2,Ethernet3 logging=true

    - name: remove member links
      action: arista_lag interface_id=Port-Channel1 links=Ethernet2,Ethernet3 logging=true

    - name: remove lag interface
      action: arista_lag interface_id=Port-Channel1 state=absent logging=true

Notes

Requires EOS 4.10 or later

The Netdev extension for EOS must be installed and active in the available extensions (show extensions from the EOS CLI)

See http://eos.aristanetworks.com for details

arista_vlan¶

Manage VLAN resources on Arista EOS network devices. This module requires the Netdev EOS extension to be installed in EOS. For detailed instructions for installing and using the Netdev module please see [link]

parameter	required	default	choices	comments
logging	no		true false yes no	enables or disables the syslog facility for this module
name	no			a descriptive name for the vlan
state	no	present	present absent	describe the desired state of the vlan related to the config
vlan_id	yes			the vlan id

Requirements: Arista EOS 4.10 Netdev extension for EOS

Example playbook entries using the arista_vlan module to manage resource
state.

  tasks:
  - name: create vlan 999
    action: arista_vlan vlan_id=999 logging=true

  - name: create / edit vlan 999
    action: arista_vlan vlan_id=999 name=test logging=true

  - name: remove vlan 999
    action: arista_vlan vlan_id=999 state=absent logging=true

Notes

Requires EOS 4.10 or later

The Netdev extension for EOS must be installed and active in the available extensions (show extensions from the EOS CLI)

See http://eos.aristanetworks.com for details

bigip_pool¶

New in version 1.2.

Manages F5 BIG-IP LTM pools via iControl SOAP API

parameter	required	default	choices	comments
host	no			Pool member IP
lb_method	no	round_robin	round_robin ratio_member least_connection_member observed_member predictive_member ratio_node_address least_connection_node_address fastest_node_address observed_node_address predictive_node_address dynamic_ratio fastest_app_response least_sessions dynamic_ratio_member l3_addr unknown weighted_least_connection_member weighted_least_connection_node_address ratio_session ratio_least_connection_member ratio_least_connection_node_address	Load balancing method (added in Ansible 1.3)
monitor_type	no		and_list m_of_n	Monitor rule type when monitors > 1 (added in Ansible 1.3)
monitors	no			Monitor template name list. Always use the full path to the monitor. (added in Ansible 1.3)
name	yes			Pool name
partition	no	Common		Partition of pool/pool member
password	yes			BIG-IP password
port	no			Pool member port
quorum	no			Monitor quorum value when monitor_type is m_of_n (added in Ansible 1.3)
server	yes			BIG-IP host
service_down_action	no		none reset drop reselect	Sets the action to take when node goes down in pool (added in Ansible 1.3)
slow_ramp_time	no			Sets the ramp-up time (in seconds) to gradually ramp up the load on newly added or freshly detected up pool members (added in Ansible 1.3)
state	no	present	present absent	Pool/pool member state
user	yes			BIG-IP username

Requirements: bigsuds

## playbook task examples:

---
# file bigip-test.yml
# ...
- hosts: localhost
  tasks:
  - name: Create pool
    local_action: >
      bigip_pool
      server=lb.mydomain.com
      user=admin
      password=mysecret
      state=present
      name=matthite-pool
      partition=matthite
      lb_method=least_connection_member
      slow_ramp_time=120

  - name: Modify load balancer method
    local_action: >
      bigip_pool
      server=lb.mydomain.com
      user=admin
      password=mysecret
      state=present
      name=matthite-pool
      partition=matthite
      lb_method=round_robin

- hosts: bigip-test
  tasks:
  - name: Add pool member
    local_action: >
      bigip_pool
      server=lb.mydomain.com
      user=admin
      password=mysecret
      state=present
      name=matthite-pool
      partition=matthite
      host="{{ ansible_default_ipv4["address"] }}"
      port=80

  - name: Remove pool member from pool
    local_action: >
      bigip_pool
      server=lb.mydomain.com
      user=admin
      password=mysecret
      state=absent
      name=matthite-pool
      partition=matthite
      host="{{ ansible_default_ipv4["address"] }}"
      port=80

- hosts: localhost
  tasks:
  - name: Delete pool
    local_action: >
      bigip_pool
      server=lb.mydomain.com
      user=admin
      password=mysecret
      state=absent
      name=matthite-pool
      partition=matthite

Notes

Requires BIG-IP software version >= 11

F5 developed module 'bigsuds' required (see http://devcentral.f5.com)

Best run as a local_action in your playbook

dnsmadeeasy¶

New in version 1.3.

Manages DNS records via the v2 REST API of the DNS Made Easy service. It handles records only; there is no manipulation of domains or monitor/account support yet. See: http://www.dnsmadeeasy.com/services/rest-api/

parameter	required	default	choices	comments
account_key	yes			Accout API Key.
account_secret	yes			Accout Secret Key.
domain	yes			Domain to work with. Can be the domain name (e.g. "mydomain.com") or the numeric ID of the domain in DNS Made Easy (e.g. "839989") for faster resolution.
record_name	no			Record name to get/create/delete/update. If record_name is not specified; all records for the domain will be returned in "result" regardless of the state argument.
record_ttl	no	1800		record's "Time to live". Number of seconds the record remains cached in DNS servers.
record_type	no		A AAAA CNAME HTTPRED MX NS PTR SRV TXT	Record type.
record_value	no			Record value. HTTPRED: <redirection URL>, MX: <priority> <target name>, NS: <name server>, PTR: <target name>, SRV: <priority> <weight> <port> <target name>, TXT: <text value>If record_value is not specified; no changes will be made and the record will be returned in 'result' (in other words, this module can be used to fetch a record's current id, type, and ttl)
state	yes		present absent	whether the record should exist or not

Requirements: urllib urllib2 hashlib hmac

# fetch my.com domain records
- dnsmadeeasy: account_key=key account_secret=secret domain=my.com state=present
  register: response

# create / ensure the presence of a record
- dnsmadeeasy: account_key=key account_secret=secret domain=my.com state=present record_name="test" record_type="A" record_value="127.0.0.1"

# update the previously created record
- dnsmadeeasy: account_key=key account_secret=secret domain=my.com state=present record_name="test" record_value="192.168.0.1"

# fetch a specific record
- dnsmadeeasy: account_key=key account_secret=secret domain=my.com state=present record_name="test"
  register: response

# delete a record / ensure it is absent
- dnsmadeeasy: account_key=key account_secret=secret domain=my.com state=absent record_name="test"

Notes

The DNS Made Easy service requires that machines interacting with the API have the proper time and timezone set. Be sure you are within a few seconds of actual time by using NTP.

This module returns record(s) in the "result" element when 'state' is set to 'present'. This value can be be registered and used in your playbooks.

netscaler¶

New in version 1.1.

Manages Citrix NetScaler server and service entities.

parameter	required	default	choices	comments
action	no	disable	enable disable	the action you want to perform on the entity
name	yes	hostname		name of the entity
nsc_host	yes			hostname or ip of your netscaler
nsc_protocol	no	https		protocol used to access netscaler
password	yes			password
type	no	server	server service	type of the entity
user	yes			username

Requirements: urllib urllib2

# Disable the server
ansible host -m netscaler -a "nsc_host=nsc.example.com user=apiuser password=apipass"

# Enable the server
ansible host -m netscaler -a "nsc_host=nsc.example.com user=apiuser password=apipass action=enable"

# Disable the service local:8080
ansible host -m netscaler -a "nsc_host=nsc.example.com user=apiuser password=apipass name=local:8080 type=service action=disable"

get_url¶

New in version 0.6.

Downloads files from HTTP, HTTPS, or FTP to the remote server. The remote server must have direct access to the remote resource. By default, if an environment variable <protocol>_proxy is set on the target host, requests will be sent through that proxy. This behaviour can be overridden by setting a variable for this task (see setting the environment), or by using the use_proxy option.

parameter	required	default	choices	comments
dest	yes			absolute path of where to download the file to.If dest is a directory, the basename of the file on the remote server will be used. If a directory, force=yes must also be set.
force	no	no	yes no	If yes, will download the file every time and replace the file if the contents change. If no, the file will only be downloaded if the destination does not exist. Generally should be yes only for small local files. Prior to 0.6, this module behaved as if yes was the default. (added in Ansible 0.7)
others	no			all arguments accepted by the file module also work here
sha256sum	no			If a SHA-256 checksum is passed to this parameter, the digest of the destination file will be calculated after it is downloaded to ensure its integrity and verify that the transfer completed successfully. (added in Ansible 1.3)
url	yes			HTTP, HTTPS, or FTP URL in the form (http|https|ftp)://[user[:pass]]@host.domain[:port]/path
use_proxy	no	yes	yes no	if no, it will not use a proxy, even if one is defined in an environment variable on the target hosts.

Requirements: urllib2 urlparse

- name: download foo.conf
  get_url: url=http://example.com/path/file.conf dest=/etc/foo.conf mode=0440

- name: download file with sha256 check
  get_url: url=http://example.com/path/file.conf dest=/etc/foo.conf sha256sum=b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c

Notes

This module doesn't yet support configuration for proxies.

slurp¶

This module works like fetch. It is used for fetching a base64- encoded blob containing the data in a remote file.

parameter	required	default	choices	comments
src	yes			The file on the remote system to fetch. This must be a file, not a directory.

ansible host -m slurp -a 'src=/tmp/xx'
   host | success >> {
      "content": "aGVsbG8gQW5zaWJsZSB3b3JsZAo=",
      "encoding": "base64"
   }

Notes

See also: fetch

uri¶

New in version 1.1.

Interacts with HTTP and HTTPS web services and supports Digest, Basic and WSSE HTTP authentication mechanisms.

parameter	required	default	choices	comments
HEADER_	no			Any parameter starting with "HEADER_" is a sent with your request as a header. For example, HEADER_Content-Type="application/json" would send the header "Content-Type" along with your request with a value of "application/json".
body	no			The body of the http request/response to the web service.
creates	no			a filename, when it already exists, this step will not be run.
dest	no			path of where to download the file to (if desired). If dest is a directory, the basename of the file on the remote server will be used.
follow_redirects	no	no	yes no	Whether or not the URI module should follow all redirects.
force_basic_auth	no	no	yes no	httplib2, the library used by the uri module only sends authentication information when a webservice responds to an initial request with a 401 status. Since some basic auth services do not properly send a 401, logins will fail. This option forces the sending of the Basic authentication header upon initial request.
method	no	GET	GET POST PUT HEAD DELETE OPTIONS	The HTTP method of the request or response.
others	no			all arguments accepted by the file module also work here
password	no			password for the module to use for Digest, Basic or WSSE authentication.
removes	no			a filename, when it does not exist, this step will not be run.
return_content	no	no	yes no	Whether or not to return the body of the request as a "content" key in the dictionary result. If the reported Content-type is "application/json", then the JSON is additionally loaded into a key called json in the dictionary results.
status_code	no	200		A valid, numeric, HTTP status code that signifies success of the request.
timeout	no	30		The socket level timeout in seconds
url	yes			HTTP or HTTPS URL in the form (http|https)://host.domain[:port]/path
user	no			username for the module to use for Digest, Basic or WSSE authentication.

Requirements: urlparse httplib2

# Check that you can connect (GET) to a page and it returns a status 200
- uri: url=http://www.example.com

# Check that a page returns a status 200 and fail if the word AWESOME is not in the page contents.
- action: uri url=http://www.example.com return_content=yes
  register: webpage

- action: fail
  when: 'AWESOME' not in "{{ webpage.content }}"


# Create a JIRA issue.
- action: >
        uri url=https://your.jira.example.com/rest/api/2/issue/
        method=POST user=your_username password=your_pass
        body="{{ lookup('file','issue.json') }}" force_basic_auth=yes
        status_code=201 HEADER_Content-Type="application/json"

- action: >
        uri url=https://your.form.based.auth.examle.com/index.php
        method=POST body="name=your_username&password=your_password&enter=Sign%20in"
        status_code=302 HEADER_Content-Type="application/x-www-form-urlencoded"
  register: login

# Login to a form based webpage, then use the returned cookie to
# access the app in later tasks.
- action: uri url=https://your.form.based.auth.example.com/dashboard.php
            method=GET return_content=yes HEADER_Cookie="{{login.set_cookie}}"

campfire¶

New in version 1.2.

Send a message to Campfire. Messages with newlines will result in a “Paste” message being sent.

parameter	required	default	choices	comments
msg	yes			The message body.
notify	no		56k bueller crickets dangerzone deeper drama greatjob horn horror inconceivable live loggins noooo nyan ohmy ohyeah pushit rimshot sax secret tada tmyk trombone vuvuzela yeah yodel	Send a notification sound before the message.
room	yes			Room number to which the message should be sent.
subscription	yes			The subscription name to use.
token	yes			API token.

Requirements: urllib2 cgi

- campfire: subscription=foo token=12345 room=123 msg="Task completed."

- campfire: subscription=foo token=12345 room=123 notify=loggins
        msg="Task completed ... with feeling."

flowdock¶

New in version 1.2.

Send a message to a flowdock team inbox or chat using the push API (see https://www.flowdock.com/api/team-inbox and https://www.flowdock.com/api/chat)

parameter	required	default	choices	comments
external_user_name	no			(chat only - required) Name of the "user" sending the message
from_address	no			(inbox only - required) Email address of the message sender
from_name	no			(inbox only) Name of the message sender
link	no			(inbox only) Link associated with the message. This will be used to link the message subject in Team Inbox.
msg	yes			Content of the message
project	no			(inbox only) Human readable identifier for more detailed message categorization
reply_to	no			(inbox only) Email address for replies
source	no			(inbox only - required) Human readable identifier of the application that uses the Flowdock API
subject	no			(inbox only - required) Subject line of the message
tags	no			tags of the message, separated by commas
token	yes			API token.
type	yes		inbox chat	Whether to post to 'inbox' or 'chat'

Requirements: urllib urllib2

- flowdock: type=inbox
            token=AAAAAA
            from_address=user@example.com
            source='my cool app'
            msg='test from ansible'
            subject='test subject'

- flowdock: type=chat
            token=AAAAAA
            external_user_name=testuser
            msg='test from ansible'
            tags=tag1,tag2,tag3

hipchat¶

New in version 1.2.

Send a message to hipchat

parameter	required	default	choices	comments
color	no	yellow	yellow red green purple gray random	Background color for the message. Default is yellow.
from	no	Ansible		Name the message will appear be sent from. max 15 characters. Over 15, will be shorten.
msg	yes			The message body.
msg_format	no	text	text html	message format. html or text. Default is text.
notify	no	yes	yes no	notify or not (change the tab color, play a sound, etc)
room	yes			ID or name of the room.
token	yes			API token.

Requirements: urllib urllib2

- hipchat: token=AAAAAA room=notify msg="Ansible task finished"

irc¶

Send a message to an IRC channel. This is a very simplistic implementation.

parameter	required	default	choices	comments
channel	yes			Channel name
color	no	black	yellow red green blue black	Text color for the message. Default is black.
msg	yes			The message body.
nick	no	ansible		Nickname
passwd	no			Server password
port	no	6667		IRC server port number
server	no	localhost		IRC server name/address

Requirements: socket

- irc: server=irc.example.net channel="#t1" msg="Hello world"

- local_action: irc port=6669
                channel="#t1"
                msg="All finished at {{ ansible_date_time.iso8601 }}"
                color=red
                nick=ansibleIRC

jabber¶

New in version 1.2.

Send a message to jabber

parameter	required	default	choices	comments
encoding	no			message encoding
host	no			host to connect, overrides user info
msg	yes			The message body.
password	yes			password for user to connect
port	no	5222		port to connect to, overrides default
to	yes			user ID or name of the room, when using room use a slash to indicate your nick.
user	yes			User as which to connect

Requirements: xmpp

# send a message to a user
- jabber: user=mybot@example.net
          password=secret
          to=friend@example.net
          msg="Ansible task finished"

# send a message to a room
- jabber: user=mybot@example.net
          password=secret
          to=mychaps@conference.example.net/ansiblebot
          msg="Ansible task finished"

# send a message, specifying the host and port
- jabber user=mybot@example.net
         host=talk.example.net
         port=5223
         password=secret
         to=mychaps@example.net
         msg="Ansible task finished"

mail¶

New in version 0.8.

This module is useful for sending emails from playbooks. One may wonder why automate sending emails? In complex environments there are from time to time processes that cannot be automated, either because you lack the authority to make it so, or because not everyone agrees to a common approach. If you cannot automate a specific step, but the step is non-blocking, sending out an email to the responsible party to make him perform his part of the bargain is an elegant way to put the responsibility in someone else’s lap. Of course sending out a mail can be equally useful as a way to notify one or more people in a team that a specific action has been (successfully) taken.

parameter	required	default	choices	comments
attach	no			A space-separated list of pathnames of files to attach to the message. Attached files will have their content-type set to application/octet-stream. (added in Ansible 1.0)
bcc	no			The email-address(es) the mail is being 'blind' copied to. This is a comma-separated list, which may contain address and phrase portions.
body	no	$subject		The body of the email being sent.
cc	no			The email-address(es) the mail is being copied to. This is a comma-separated list, which may contain address and phrase portions.
charset	no	us-ascii		The character set of email being sent
from	no	root		The email-address the mail is sent from. May contain address and phrase.
headers	no			A vertical-bar-separated list of headers which should be added to the message. Each individual header is specified as header=value (see example below). (added in Ansible 1.0)
host	no	localhost		The mail server
port	no	25		The mail server port (added in Ansible 1.0)
subject	yes			The subject of the email being sent.
to	no	root		The email-address(es) the mail is being sent to. This is a comma-separated list, which may contain address and phrase portions.

# Example playbook sending mail to root
- local_action: mail msg='System {{ ansible_hostname }} has been successfully provisioned.'

# Send e-mail to a bunch of users, attaching files
- local_action: mail
                host='127.0.0.1'
                port=2025
                subject="Ansible-report"
                body="Hello, this is an e-mail. I hope you like it ;-)"
                from="jane@example.net (Jane Jolie)"
                to="John Doe <j.d@example.org>, Suzie Something <sue@example.com>"
                cc="Charlie Root <root@localhost>"
                attach="/etc/group /tmp/pavatar2.png"
                headers=Reply-To=john@example.com|X-Special="Something or other"
                charset=utf8

mqtt¶

New in version 1.2.

Publish a message on an MQTT topic.

parameter	required	default	choices	comments
client_id	no	hostname + pid		MQTT client identifier
password	no			Password for username to authenticate against the broker.
payload	yes			Payload. The special string "None" may be used to send a NULL (i.e. empty) payload which is useful to simply notify with the topic or to clear previously retained messages.
port	no	1883		MQTT broker port number
qos	no		0 1 2	QoS (Quality of Service)
retain	no			Setting this flag causes the broker to retain (i.e. keep) the message so that applications that subsequently subscribe to the topic can received the last retained message immediately.
server	no	localhost		MQTT broker address/name
topic	yes			MQTT topic name
username	no			Username to authenticate against the broker.

Requirements: mosquitto

- local_action: mqtt
              topic=service/ansible/{{ ansible_hostname }}
              payload="Hello at {{ ansible_date_time.iso8601 }}"
              qos=0
              retain=false
              client_id=ans001

Notes

This module requires a connection to an MQTT broker such as Mosquitto http://mosquitto.org and the mosquitto Python module (http://mosquitto.org/python).

osx_say¶

New in version 1.2.

makes an OS computer speak! Amuse your friends, annoy your coworkers!

parameter	required	default	choices	comments
msg	yes			What to say
voice	no			What voice to use

Requirements: say

- local_action: osx_say msg="{{inventory_hostname}} is all done" voice=Zarvox

Notes

If you like this module, you may also be interested in the osx_say callback in the plugins/ directory of the source checkout.

apt¶

New in version 0.0.2.

Manages apt packages (such as for Debian/Ubuntu).

parameter	required	default	choices	comments
cache_valid_time	no	no		If update_cache is specified and the last run is less or equal than cache_valid_time seconds ago, the update_cache gets skipped.
default_release	no			Corresponds to the -t option for apt and sets pin priorities
force	no	no	yes no	If yes, force installs/removes.
install_recommends	no	yes	yes no	Corresponds to the --no-install-recommends option for apt, default behavior works as apt's default behavior, no does not install recommended packages. Suggested packages are never installed.
pkg	no			A package name or package specifier with version, like foo or foo=1.0. Shell like wildcards (fnmatch) like apt* are also supported.
purge	no	no	yes no	Will force purging of configuration files if the module state is set to absent.
state	no	present	latest absent present	Indicates the desired package state
update_cache	no	no	yes no	Run the equivalent of apt-get update before the operation. Can be run as part of the package installation or as a separate step
upgrade	no	yes	yes safe full dist	If yes or safe, performs an aptitude safe-upgrade.If full, performs an aptitude full-upgrade.If dist, performs an apt-get dist-upgrade.Note: This does not upgrade a specific package, use state=latest for that. (added in Ansible 1.1)

Requirements: python-apt aptitude

# Update repositories cache and install "foo" package
- apt: pkg=foo update_cache=yes

# Remove "foo" package
- apt: pkg=foo state=absent

# Install the package "foo"
- apt: pkg=foo state=present

# Install the version '1.00' of package "foo"
- apt: pkg=foo=1.00 state=present

# Update the repository cache and update package "nginx" to latest version using default release squeeze-backport
- apt: pkg=nginx state=latest default_release=squeeze-backports update_cache=yes

# Install latest version of "openjdk-6-jdk" ignoring "install-reccomends"
- apt: pkg=openjdk-6-jdk state=latest install_recommends=no

# Update all packages to the latest version
- apt: upgrade=dist

# Run the equivalent of "apt-get update" as a separate step
- apt: update_cache=yes

# Only run "update_cache=yes" if the last one is more than more than 3600 seconds ago
- apt: update_cache=yes cache_valid_time=3600

Notes

Three of the upgrade modes (full, safe and its alias yes) require aptitude, otherwise apt-get suffices.

apt_key¶

New in version 1.0.

Add or remove an apt key, optionally downloading it

parameter	required	default	choices	comments
data	no	none		keyfile contents
file	no	none		keyfile path
id	no	none		identifier of key
keyring	no	none		path to specific keyring file in /etc/apt/trusted.gpg.d (added in Ansible 1.3)
state	no	present	absent present	used to specify if key is being added or revoked
url	no	none		url to retrieve key from.

# Add an Apt signing key, uses whichever key is at the URL
- apt_key: url=https://ftp-master.debian.org/keys/archive-key-6.0.asc state=present

# Add an Apt signing key, will not download if present
- apt_key: id=473041FA url=https://ftp-master.debian.org/keys/archive-key-6.0.asc state=present

# Remove an Apt signing key, uses whichever key is at the URL
- apt_key: url=https://ftp-master.debian.org/keys/archive-key-6.0.asc state=absent

# Remove a Apt specific signing key
- apt_key: id=473041FA state=absent

# Add a key from a file on the Ansible server
- apt_key: data="{{ lookup('file', 'apt.gpg') }}" state=present

# Add an Apt signing key to a specific keyring file
- apt_key: id=473041FA url=https://ftp-master.debian.org/keys/archive-key-6.0.asc keyring=/etc/apt/trusted.gpg.d/debian.gpg state=present

Notes

doesn't download the key unless it really needs it

as a sanity check, downloaded key id must match the one specified

best practice is to specify the key id and the url