NS1 status

Articles in this section

Installation Instructions: NS1 Cloud-Managed DDI

  • Updated
Follow

The instructions below detail the process for installing edge services and components as part of full production NS1 Cloud-Managed DDI deployments.

Before you begin:

Ensure each node running an edge service meets the following minimum hardware requirements:

  • 4 CPUs minimum

  • 4 GB RAM minimum (8 GB recommended)

  • 60+ GB minimum free disk space (100 GB recommended)

Note

  • Requirements may vary depending on the size of the network, topology, and deployment models.

  • NS1 highly recommends monitoring disk usage on each host to prevent service disruption.

  • NS1 recommends using SSD drives for storage to improve cache load speed on restart.

The following are the operating system requirements:

  • Ubuntu LTS 18.04+ x86_64

  • Red Hat Enterprise Linux 8+ x86_64

Note

  • NS1 does not support running edge services on Mac OS or Windows.

  • The Linux kernel must support the SO_REUSEPORT socket option to allow multiple sockets on the same host to bind to the same port.

  • Ubuntu 20.04 and18.04 installs may require systemd-resolved to be disabled and stopped on DNS hosts. Note that doing this will prevent you from being able to resolve names on the server. To disable service: sudo systemctl disable systemd-resolved.

  • Centos 7 and 8, RHEL requires firewalld to be disabled and stopped. This is because of a potential conflict between firewalld and other software packages over control of IP tables.

Step 1: Create an NS1 API key and set the environment variable.

  1. Log into the NS1 Connect portal and click your username in the top right corner.

  2. Select Account Settings > Users & Teams.

  3. Click the “API Keys” tab, and click Add Key.

  4. Enter a name for the API key. We recommend naming the API key something to indicate clearly that this key is used for installing and managing DDI services and components.

  5. Adjust API key permissions as desired. Ensure the “Manage Account Settings” permission is enabled. Click Create Key. The new API key appears in the list.

    Warning

    Do not navigate away from the page without first toggling the show/hide icon to display the API key secret. Record the API key in a secure password manager or key vault for future reference. You will not be able to view the key after navigating away from this page. Refer to this article for details.

  6. Click the info icon next to the new API key to reveal the key secret.

    api_key_reveal.png

  7. Execute the command below to save it as an environment variable:

    NSONE_API_KEY=YOUR_API_KEY_HERE

Step 2: Install NS1 Connect agent on your nodes.

Execute the following command on your nodes that will run DNS services, replacing the API key and other variables (pop, region) as desired.

curl https://api.prod.svc.ns1.dev/connect | sudo bash -s $NSONE_API_KEY pop=ex01 region=US role=dns

Execute the following command on your nodes that will run DHCP services, replacing the API key and other variables (pop, region) as desired.

curl https://api.prod.svc.ns1.dev/connect | sudo bash -s $NSONE_API_KEY pop=ex02 region=US role=dhcp

If you are conducting a PoC or non-production deployment, you can execute the following command on a node that will run both DNS and DHCP services.

curl https://api.prod.svc.ns1.dev/connect | sudo bash -s $NSONE_API_KEY pop=ex02 region=US role=dns_dhcp

Step 3: Determine your enabled DDI services.

To begin, you must identify the DDI services enabled on your account. Each service has a unique service name you’ll need for the installation process.

Execute the following command to return a list of all services associated with your account:

curl -X GET -H "X-NSONE-KEY: $NSONE_API_KEY" https://api.prod.svc.ns1.dev/v1/service

Example response:

{
"services": [
     {
     "name": "228",
     "type": "dns"
     },
     {
     "name": "229",
     "type": "dhcp"
     }
  ]
}

The response includes the following information for each service associated with your account:

  • name - Name of the service

  • type - Type of service (i.e., DNS or DHCP)

Step 4: Apply the desired edge service components.

For each instance of an edge service, you must specify which service component should be running. A component is a software module representing a specific capability within a service category.

DNS service component configuration

Execute the command below to configure DNS service.

curl -X POST -s -H "X-NSONE-KEY: $NSONE_API_KEY" https://api.prod.svc.ns1.dev/v1/service/<service_name>/dns -d '
{
"selector": "role=dns",
"version": "latest",
"config": {
"operation_mode": "authoritative"
}
}'.

where

  • service name is the unique name of the specific service set as returned in the response in step 2.

  • selector is a key-value pair that connects a type of service to a node. In this example, the tag role is set to DNS to indicate the node should run the DNS service component.

  • version is the software version of the edge service you are deploying.

    Tip: Set to latest to instruct the server to find and set the latest software version available from NS1.

  • operation mode indicates whether to operate in authoritative or recursive DNS.

DHCP service component configuration

Execute the command below. Do this for all nodes on which you want to deploy DHCP services.

curl -X POST -s -H "X-NSONE-KEY: $NSONE_API_KEY" https://api.prod.svc.ns1.dev/v1/service/<service_name>/dhcp -d '
{
"selector": "role=dhcp",
"version": "latest"
}'

where

  • service name is the unique name of the specific service set as returned in the response in step 2.

  • selector is a key-value pair that connects a type of service to a node. In this example, the tag role is set to DHCP to indicate the node should run the DHCP service component.

  • version is the software version of the edge service you are deploying.

    Tip: Set to latest to instruct the server to find and set the latest software version available from NS1.

Step 5: Determine all node IDs.

In order to deploy the services you just configured to a node, you must first record the node IDs. Execute the command below to return a list of nodes including their unique node IDs.

curl -H "X-NSONE-KEY: $NSONE_API_KEY" https://api.prod.svc.ns1.dev/v1/fleet/node

Example response:

{
  "nodes": [
    {
      "id": "1wIGNX4ASHi6KqPhE2LdTe1lE8x",
      "tags": {
        "hostname": "testfleet01"
      }
    },
    {
      "id": "1xrxKPYFl2dS25jxCuDRTes1Yxv",
      "tags": {
        "pop": "ex01",
        "region": "US",
        "role": "dns"
      }
   .......................
  ]
}

Step 6: Deploy the services to each node.

Execute the command below to deploy a service on a single node.

curl -X PUT -H "X-NSONE-KEY: $NSONE_API_KEY" https://api.prod.svc.ns1.dev/v1/fleet/node/<node_id>/deploy | jq .

Alternatively, you can specify certain tags (e.g., pop) to deploy all services in a single location, replacing the pop tag with the relevant location. For example:

curl -X PUT -H "X-NSONE-KEY: $NSONE_API_KEY" https://api.prod.svc.ns1.dev/v1/fleet/node/deploy?tags=pop=ex01 | jq .

Step 7: Validate the deployment

Execute the following command to see the status of deployed services. This should take about two minutes.

watch kubectl get pods

Example response:

Every 2.0s: kubectl get pods                                                                                                       fleet-test-prod01: Mon Sep 27 20:13:08 2021

NAME                                 READY   STATUS    RESTARTS   AGE
ns1agent-844bd4fc87-hzs7g            1/1     Running   1          4d2h
ns1-cmddi-dhcp-99b7b75dc-hmpg2       1/1     Running   0          6h10m
ns1-cmddi-dns-b7cff7969-mt874        1/1     Running   0          13

This completes the installation process. Next, work with your dedicated NS1 engineer to configure services and the running components.

Related articles