NS1’s integration with AWS allows users to view their Route 53 zones, records, DNS policies, Virtual Private Cloud (VPC) data, instances, and IP addresses in the NS1 Enterprise DDI platform. Import data from AWS Route 53, Virtual Private Cloud (VPC), Elastic Compute Cloud (EC2), and Elastic Load Balancing into the Enterprise DDI platform for easy viewing.
Once configured, the NS1 + AWS integration loads your AWS information into your DDI deployment, allowing users to view your DNS and IPAM resources in one place. The integration allows you to:
- Create, edit, delete, approve, and view scheduled updates history and next scheduled updates to keep NS1 in sync with zones, resource records, policies, VPCs, and other AWS assets.
- Maintain multi-factor authentication for increased account security.
- Use AWS IAM roles to define specific permissions to NS1 user accounts. The access key ID and secret access key of the user who will be used to install this integration must have read-only permissions for Route 53 and EC2.
Visualize DNS resource information, including your DNS zones and records. AWS Route 53 resources are easily accessible in the form of DNS views, and you can update these resources manually or on a schedule that you create.
AWS IPAM resources are easily accessible from within the Enterprise DDI portal:
- VPCs, VPC subnets, and available IP addresses
- EC2 instances and their IP addresses
- Elastic Load Balancing instances and their IP addresses
Review these resources from the Network tab, looking for objects with the AWS prefix and the name of the VPC. You can update these resources manually or on a schedule that you create.
- Enterprise DDI software version 3.1.2 or later.
- A valid API key with Manage IPAM, View IPAM, and Allow Zone Management permissions enabled. Note: The API key must be created from within the Enterprise DDI platform (not Managed DNS).
- A valid IAM role (if AWS Identity and Access Management is enabled with managed policies AmazonEC2ReadOnlyAccess and AmazonRoute53ReadOnlyAccess)
- MFA serial number (if multi-factor authentication is enabled)
- Users who access AWS features from NS1 must have AWS credentials and permission to read from AWS Route 53 and EC2.
- Enterprise DDI must use the same network as the Docker container you will create through this installation process.
If you have questions about target environments, contact the NS1 support team.
The requirements below are specific to the NS1 + AWS integration. System requirements applicable to the entire Enterprise DDI platform are outlined in the NS1 Enterprise DDI Installation Guide.
A typical installation should look like the following diagram:
The following table lists the port and firewall rules for each AWS Docker container:
|Port (as exposed in containers)||Description|
HTTP port for API and portal
|443 (inbound)||HTTPS port for API and portal|
The following table lists the port and firewall rules for the host where you run the CORE container:
|8095 (inbound / outbound)||Used to access the web interface to configure the
- Linux Ubuntu 18.04 / 17.04 / 16.04
- CentOS 7 x86_64
- Red Hat x86_64
Before you begin, ensure that you have the following information at hand:
- Enterprise DDI CORE container IP address and host name
- Enterprise DDI API key with View IPAM, Manage IPAM, and Allow Zone Management permissions enabled
- AWS credentials (including the IAM role and multi-factor authentication [MFA] serial number, if required)
Step One: Download the container image files
- Download the container image file from the following URL: https://hub.docker.com/repository/docker/ns1inc/privatedns_cloudsync
- Load the container image on each host with the following command, using the container name plus the version of the image tag to load. For example, to load the
privatedns_cloudsynccontainer for version 1.0.0:
docker load ns1-privatedns_cloudsync-1.0.0.tgzNOTE
You must use the same network for the CORE container and the
- Download the
docker-compose.ymlfile from https://github.com/ns1/ns1-privatedns.
- Run the following command to start the Docker Compose tool.
docker-compose -p privatedns_cloudsync up -dNOTE
This integration uses HTTPS with a self-signed certificate. If you want to customize the CA-signed certificate, use steps 5 and 6 to specify the certificate path, name, and key.
- Run the
downcommand to stop the container:
docker-compose -p privatedns_cloudsync down -d
- Set the variables with the following command, replacing the path, name, and key name in between the brackets
<>with the path, name, and key of your certificate:
DDI_SYNC_CERTIFICATE_PATH=</mypath/certs/> \ DDI_SYNC_CERTIFICATE_NAME=<mycert.crt> \ DDI_SYNC_CERTIFICATE_KEY_NAME=<mycert.key> docker-compose -p privatedns_cloudsync -f docker-compose.yml -f docker-compose-cert.yml up
Step Two: Verify container health
After approximately 60 seconds, run the
docker ps command to confirm that the
privatedns_cloudsync container is displayed on the containers list:
docker-compose -p privatedns_cloudsync ps
privatedns_cloudsync container will show that it is unhealthy. This is normal.
Step Three: Bootstrapping
- Open a browser and navigate to the IP address or hostname where the CORE container is running. The default port is
8095. For example, navigate to
- Complete the form. Required fields are marked with an asterisk.
Field Description IP / Hostname The IP address or hostname of the CORE container (the Enterprise DDI portal) DDI Credential An API key created within the DDI platform DNS View Name (Optional) Name of the NS1 DNS view with which to associate imported GCP resources. Refer to Configuring NS1 DNS views (DDI only) to learn more. Route Table Prefix
The autonomous system number (ASN) or IP address of the routing table
Access Key The access key ID for the AWS IAM user or AWS root user who is installing or managing the integration Secret Key The secret access key for the AWS IAM user or AWS root user who is installing or managing the integration IAM Roles The AWS IAM roles for the IAM user or AWS root user who is installing or managing the integration MFA Serial Number The ID or serial number of the multifactor authentication (MFA) device for the AWS IAM user or AWS root user who is installing or managing the integration
- Click Submit to initiate bootstrapping. Note that you will be prompted to log in to AWS during this process.
- Log in to Enterprise DDI with your username and password.
- After approximately 60 seconds, run the
docker pscommand to confirm that the container is displayed on the container list. The container should show that it is healthy.
Post-installation: Updating credentials & AWS resources, scheduling events
Updating AWS credentials
If your AWS credentials change, you must update them from the NS1 Cloud integration platform.
- Open a browser and navigate to the IP address or hostname where the CORE container (Enterprise DDI portal) is running. The default port is
8095. For example, navigate to
- On the AWS Integration page, click the Setup tab, and then click Change credentials.
- As needed, update the access key and secret key (required), the IAM role(s), and/or the MFA serial number. Click Save Credentials.
- When prompted, click Run Incremental Update.
Updating the Enterprise DDI CORE container (portal) hostname and API key
If the IP address (or host name) or API key for the CORE container must be updated for any reason, you can update these settings from the DDI Setup page.
- Open a browser and navigate to the IP address or hostname of the CORE container, or the Enterprise DDI portal.
- Update the IP / Hostname of the DDI portal (that is, the CORE container) and the DDI Credential (API key generated within the DDI portal), and then click Save Credentials.
- Wait for the connection to be checked. The credentials will save successfully if you entered the correct information.
If the connection fails, check the network access and review your DDI credentials (API key generated within the DDI platform) before trying again.
The update mechanism on the AWS integration stores a copy of AWS resources in the DDI solution. Through this, the integration is able to make incremental updates without having to load all AWS resources into the DDI solution.
To manually perform an incremental update, click the vertical ellipsis menu at the top right of the screen, then click Incremental Update. This process guarantees that the resources you have in your AWS are the same as you have in your Enterprise DDI solution.
You should perform the Full Update only if you have received an error message after having performed a Quick Update. The Full Update might impact Enterprise DDI performance and take longer to complete.
The Schedules tab allows you to create a new schedule, see the scheduled events, and edit a schedule.
Click the Schedules tab in the navigation menu to see a list of your scheduled events.
Click the + Add Schedule button to add a new schedule and complete the fields on the screen.
You can also edit or delete schedules on the Schedule screen.
Verifying the installation
After you install the NS1 + AWS Route 53 integration, you should verify that it is installed correctly and that your AWS resources have been imported into the NS1 Enterprise DDI portal. You can check this in a couple of ways:
- First, verify that you can synchronize your assets via the Updates tab of the AWS Integration portal. Note that this only specifies whether a synchronization was successful, not that the data was actually synchronized.
- Then, log into the Enterprise DDI portal and determine whether you can view your AWS resources. For example, your VPC resources can be found on the IPAM > Networks page in the Enterprise DDI portal, and the CIDR blocks for these resources are found in the Metadata tab for the selected resource.
If you encounter any issues during this process, review the common questions, errors, and workarounds below.
Common questions and errors/workarounds
The system maps the port from the container to the host, which may cause some conflicts if the mapped port is already in use. By default, the port used by the application is 8096. In this case, if such port is already in use, the following error is displayed:
ERROR: for privatedns_cloudsync Cannot start service privatedns_cloudsync: driver failed programming external connectivity on endpoint privatedns_cloudsync (8cab1495265bba47f5f9c4a4f63e75c0b3b0e682d84b2751bd1a69dde87f6274): Bind for 0.0.0.0:8096 failed: port is already allocated
ERROR: Encountered errors while bringing up the project.
To resolve this issue, run the following command to pass a new value to the port that will be exposed to your host. In this example, we use port
DDI_SYNK_REST_SERVER_PORT=8097 docker-compose up -d
Docker must be up to date
Make sure that you are running the correct version of Docker.
Running docker as a non-root user
If you are running Docker as a non-root user, consult the official Docker documentation for more information.
Cannot see the bootstrap page
docker ps to make sure the container is visible and pointing to the correct port.
Nothing happens after bootstrapping
- Check container logs by running the following commands:
docker logs <container_id>
docker logs <container_name>
Verify that the user ID and password that you have entered are the same user ID and password that you use to log in to Enterprise DDI.
If you encounter problems scheduling updates, run the following command in the application directory to verify a cause in the logs:
To view logs for a specific container, run the following commands:
docker logs <container_id>
docker logs <container_name>
Most commonly, the following errors happen when attempting to schedule updates:
- Wrong AWS credentials
- Incorrect Enterprise DDI credentials
- AWS server is unreachable
- Enterprise DDI server is unreachable
- AWS IAM role mismatch
- AWS multi-factor authentication isn’t enabled
- AWS multi-factor authentication code is incorrect
Network issues, Docker connections, and disk space are the most common system issues.
Run the following checklist when you encounter system issues:
- Check that you are connected to the internet and that you have configured the system properly.
- Verify that the container is running:
- Verify that the Docker containers can connect to each other:
docker exec -it <first_container_name> ping <second_container_name>or
docker exec -it <first_container_id> ping <second_container_id>
- Verify that the first container can connect to the second container and the correct port:
docker exec -it <first_container_name> telnet <second_container_name port>or
docker exec -it <first_container_id> telnet <second_container_id port>
- Verify that the directory that is storing the container data has sufficient space. Unless you have changed the default installation location, the directory should be
sudo du -c /var/lib/docker | grep totalFor the integration to run correctly, you must have at least 2 GB of free space in the directory. You can delete unused files, volumes, and logs to free up space.
- Check docker logs with the
docker pscommand, then run the
docker logscommand to review the logs for a container:
docker logs <container_id> or docker logs <container_name>
DDI changes not replicated on AWS
This is expected, because the AWS integration is a one-way integration. The information that you update in AWS will be saved into your Enterprise DDI solution, but Enterprise DDI changes are not reflected in AWS.
Incremental Update errors
If AWS information diverges from Enterprise DDI, you may encounter issues with an incremental update. If this happens, run a full update. This will force AWS information to be reloaded within Enterprise DDI, correcting inconsistencies.