# Ansible tasks

MetalSoft has the ability to execute Ansible playbooks via the site controller at certain moments in time. This is done via the Ansible Task Type (`taskType: ExtensionTaskAnsible`) attached to an workflow or other Extension types.

:::{Warning}
The Ansible Runner capability must be enabled on the site controller in order for this task type to be supported. See [Enabling the Ansible Runner Capability](enabling_the_ansible_runner_capability) for more details.
:::

The way it gets executed is relatively complex:
![](/assets/developer_resources/ansible_task.svg)

Execution process:
1. Depending on the `stage` a Job Graph will be updated with several tasks that will prepare and execute the ansible playbook on the site controller.
2. The global controller downloads the ansible bundle specified in the extension' `assets[*].url` section and sends it to the site controller. For example this is `https://repo.metalsoft.io/.extensions_ms/workflows/power_dns.zip` in the example below.
3.  The site controller then unzips it and executes ansible against the specified playbook such as `deploy_dns_flexible` in the example below with the provided `variables.json` see below more details.

## Task Object Schema

```json
{
    "label": "create-or-update-dns-and-ptr-records-for-instance",
    "taskType": "ExtensionTaskAnsible",
    "options": {
        "asset": "power-dns-configuration",
        "playbook": "deploy_dns_flexible.yaml"
    }
}
```

## Options
* `asset` - The asset to call
* `playbook` - The playbook to execute that must exist within the asset bundle.
* `executionTimeout` - Timeout for the execution
* `executionTimeoutTick` - How often to retry in case of an error

## variables.yaml
When the Ansible bundle is executed the following `variables.yaml` will be available in the directory. The content will depend on the execution `stage`:

* For `serverRegistered`, `serverDecommissioned`, `switchRegistered`: 
The `Server` and `Network` objects are available. The user can refer to the [Server](https://us08.metalsoft.io/api/v2/swagger#/Server/getServerInfo) and [NetworkDevice](https://us08.metalsoft.io/api/v2/swagger#/Network%20Device/getNetworkDevice) objects' parameters depending on the asset that is being changed. Refer to your environment's API documentation.
* For `serverInstanceGroupCreateDNS`, `serverInstanceGroupUpdateDNS`, `serverInstanceGroupDeleteDN`,`serverInstanceUpdateDNS`, `serverInstanceDeleteDNS` check the `RecordSet` object in the API documentation.
A server DNS record set object similar to this:
```json
"serverInstanceGroupDNSRecordSet": {
    "zone": {
    "zoneName": "eveng-qa02.metalcloud.io",
    "soaEmail": "admin.eveng-qa02.metalcloud.io",
    "nameServers": [
        "ns1.evenq-qa02.metalcloud.io"
    ],
    "ttl": 3600,
    "isDefault": true
    },
    "infrastructureId": 3870,
    "serverInstanceGroup": {
    "label": "instance-array-3386"
    },
    "hostname": "lambda",
    "fqdn": "lambda.eveng-qa02.metalcloud.io",
    "ips": [
    {
        "status": "allocated",
        "ip": "10.20.50.36"
    }
    ]
}
```
* For `serverCreateDNS`, `serverDeleteDNS` an object similar to is provided in `variables.json`:
```json
"serverDNSRecordSet": {
    "zone": {
      "zoneName": "us08.metalsoft.io",
      "soaEmail": "admin.us08.metalsoft.io",
      "nameServers": ["n1.metalsoft.io"],
      "ttl": 3600,
      "isDefault": true
    },
    "serverId": 10,
    "serialNumber": "serial-number",
    "managementAddress": "192.168.100.100",
    "hostname": "server-10",
    "fqdn": "server-10.us08.metalsoft.io",
      "ip": {
      "status": "allocated",
      "ip": "192.168.100.100"
    },
    "operation": "create"
}
```
* For `switchCreateDNS`, `switchDeleteDNS` the following payload is provided:
```json
"switchDNSRecordSet": {
    "zone": {
      "zoneName": "us08.metalsoft.io",
      "soaEmail": "admin.us08.metalsoft.io",
      "nameServers": ["n1.metalsoft.io"],
      "ttl": 3600,
      "isDefault": true
    },
    "switchId": 10,
    "managementAddress": "192.168.100.100",
    "hostname": "switch-10",
    "fqdn": "switch-10.us08.metalsoft.io",
    "ip": {
      "status": "allocated",
      "ip": "192.168.100.100"
    },
    "operation": "create"
}
```

## Extension Example
```json
{
  "kind": "ExtensionDefinition",
  "schemaVersion": "1.1",
  "name": "powerdns-automation",
  "label": "powerdnsautomation",
  "extensionType": "workflow",
  "vendor": "MetalSoft",
  "extensionVersion": "1.0.0",
  "description": "Manages DNS records via PowerDNS API during server lifecycle",
  "icon": "dns",
  "dependencies": {
    "controllerVersion": "string"
  },
  "inputs": [],
  "outputs": [],
  "assets": [
    {
      "label": "power-dns-configuration",
      "name": "power-dns-configuration",
      "assetType": "Bundle",
      "url": "https://repo.metalsoft.io/.extensions_ms/workflows/power_dns.zip"
    }
  ],
  "onAssetChange": [
    {
      "stage": "serverInstanceGroupCreateDNS",
      "tasks": [
        {
          "label": "create-dns-records-for-instance-group",
          "taskType": "ExtensionTaskAnsible",
          "options": {
            "asset": "power-dns-configuration",
            "playbook": "deploy_dns_flexible.yaml"
          }
        }
      ]
    },
  ]
}
```