# External DNS integration

The integration with an external DNS system is done via an `extension` which is invoked if certain buttons or API calls are done in the user interface:

![](/assets/configuration/integrations/DNS_Provisioning_01.png)

As with all extensions, the DNS extension calls will originate on or be executed from the Site Controller.


## Integration with the sample DNS service

MetalSoft provides a sample DNS service that leverages PowerDNS to demonstrate how to integrate with other systems and to be used in POC envs. To deploy it follow the following steps:

### 1. Deploying the service

The sample dns service is disabled by default. To enable it follow the following instructions:

1. Create a directory
```
mkdir -p /opt/metalsoft/pdns
```

2. Add the following to `/opt/metalsoft/agents/docker-compose.yaml`
```
pdns-auth-recursor:
    container_name: pdns-auth-recursor
    network_mode: host
    hostname: pdns-auth-recursor
    image: registry.metalsoft.dev/sc/sc-pdns-auth-recursor:develop
    restart: always
    environment:
      - TZ=Etc/UTC
    volumes:
      - /opt/metalsoft/pdns:/appdata
```

3. Bring everything up
```
cd /opt/metalsoft/agents
docker compose up -d
```

### 2. Retrieve the ansible scripts

Retrieve the ansible bundle:
```
curl -O https://repo.metalsoft.io/.extensions_ms/workflows/power_dns.zip 
unzip power_dns.zip -d ansible
```

### 3. Update the references to the DNS service in the ansible bundle

Edit the `ansible/roles/powerdns/defaults/main.yml` file and update the following variables:
```
powerdns_api_host: "localhost"
powerdns_api_port: 8081
powerdns_api_key: "your-api-key"
```

The `powerdns_api_host` is the IP address of the Site Controller. The default `powerdns_api_port` is `8081`.

To retrieve the `powerdns_api_key` key from the image run the following command from the **Site Controller**:

```
docker exec -it pdns-auth-recursor grep api-key /etc/powerdns/pdns.conf | awk -F '=' '{print $2}'
```


### 4. Upload the ansible script to the repository

Upload the ansible bundle zip to an http server reachable by the Global Controller such as:
`https://repo.metalsoft.io/.extensions_ms/workflows/power_dns.zip`.

### 5. Install the DNS extension

Note that MetalSoft provides a sample PowerDNS image that can be used during POCs but should not be used in production.

1. Clone the [sample DNS workflow repository](https://github.com/metalsoft-io/metalsoft-extensions/tree/main/dns-workflow).
```
git clone https://github.com/metalsoft-io/metalsoft-extensions
```
2. Update the ansible bundle URL in the `pdns-workflow-full-example.json` file in the `assets` section to match the above.
3. Install the extension using the CLI:
```
cd metalsoft-extensions
cd dns-workflow
metalcloud-cli extension create test-dns workflow "test dns workflow" --definition-source pdns-workflow-full-example.json --format json
```
### 6. Configure the MetalSoft DNS service

Go to **Global Configuration** > **DNS** and ensure that the configuration is correct for your environment.

## Using the DNS extension to create DNS records for servers and endpoints

To create the records in the DNS via the extension connect an endpoint to a network. The DNS options are available under Provision Instance DNS Records and Provision Load Balancing DNS Record. 

The first option will create records for each server, endpoint or VM attached to the network whereas the last will create a single DNS record with CNAME entries for all.


## More details on the behavior of the extension

Consult the [Extension Readme](https://github.com/metalsoft-io/metalsoft-extensions/tree/main/dns-workflow) for more details on the behaviour of the extension and how to modify it to suit your needs.


## Ports open

In addition to the normal Site Controller ports, this component adds the following port:
* port 53 -> the DNS recursor will listen on this port for DNS requests.