Clone or download
Latest commit e6df9f3 Jul 11, 2018

README.md

NS1 Terraform Provider

Contents

  1. Requirements - lists the requirements for building the provider
  2. Building The Provider - lists the steps for building the provider
  3. Using The Provider - details how to use the provider
  4. Developing The Provider - steps for contributing back to the provider

Requirements

  • Terraform 0.10.x
  • Go 1.9+ (to build the provider plugin)

Building The Provider

Clone repository to: $GOPATH/src/github.com/terraform-providers/terraform-provider-ns1

$ mkdir -p $GOPATH/src/github.com/terraform-providers; cd $GOPATH/src/github.com/terraform-providers
$ git clone git@github.com:terraform-providers/terraform-provider-ns1

Enter the provider directory and build the provider

$ cd $GOPATH/src/github.com/terraform-providers/terraform-provider-ns1
$ make build

Using The Provider

NS1 Resources List and examples

  1. ApiKey
  2. Datafeed
  3. Datasource
  4. MonitoringJob
  5. NotifyList
  6. Record
  7. Team
  8. User
  9. Zone

Addendum

  1. Permissions

ApiKey

ApiKeys Api Doc

ApiKeys are one of the data types that supports permissions at the top level of its Terraform resource in addition to its regular parameters. See Permissions for the parameters that are available.

Example

resource "ns1_apikey" "apikey" {
  #required
  name = "my api key"

  #optional
  teams = ["myteam"]

  #permissions are available at the top level, see permissions for documentation
}

Datafeed

Datafeed Api Doc

A Datafeed requires a Datasource

Example

resource "ns1_datafeed" "datafeed" {
  name = "terraform test"
  source_id = "${ns1_datasource.api.id}"

  #optional
  config {
    label = "exampledc2"
  }
}

Datasource

Datasource Api Doc

Example

resource "ns1_datasource" "datasource" {
  #required
  name = "terraform test"
  sourcetype = "nsone_v1"

  #optional
  config {}
}

MonitoringJob

MonitoringJob Api Doc

Example

resource "ns1_monitoringjob" "it" {
  #required
  job_type = "tcp"
  name     = "terraform test"

  regions   = ["lga"]
  frequency = 60

  config = {
    ssl = "1",
    send = "HEAD / HTTP/1.0\r\n\r\n"
    port = 443
    host = "1.2.3.4"
  }

  #optional
  active = true
  rapid_recheck = false
  notes = "some notes about this job"
  notify_delay = 3000
  notify_repeat = 3000
  notify_failback = false
  notify_list = ""
  notify_regional = true


  rules = [{
    value = "200 OK"
    comparison = "contains"
    key = "output"
  }]
}

NotifyList

NotifyList Api Doc

Example

resource "ns1_notifylist" "test" {
  #required
  name = "terraform test"

  #optional
  notifications = {
    type = "webhook"
    config = {
      url = "http://localhost:9090"
    }
  }
}

Record

Record Api Doc

Records have metadata at three different levels:

  • Record Level - Lowest precedence
  • Region Level - Middle precedence
  • Answer Level - Highest precedence

Due to some limitations in Terraform's support of nested maplike objects, there are some irregularities in supporting metadata, however metadata is now supported at every level.

A record requires a Zone

Example

resource "ns1_record" "it" {
  #required
  zone              = "${ns1_zone.test.zone}"
  domain            = "test.${ns1_zone.test.zone}"
  type              = "CNAME"

  #optional
  ttl               = 60
  use_client_subnet = true
  link = ""

  meta = {
    up          = true
    connections = 5
    latitude    = 0.50
    longitude   = 0.40
  }

  answers = [
    {
      answer = "10.0.0.1"

      meta = {
        up          = true
        connections = 4
        latitude    = 0.5
        georegion   = "US-EAST"
      }
    },
  ]

  regions = [
    {
      name = "cal"

      meta = {
        up          = true
        connections = 3
      }
    },
  ]

  filters {
    filter = "up"
  }

  filters {
    filter = "geotarget_country"
  }

  filters {
    filter = "select_first_n"
    config = {N=1}
  }
}

Team

Team Api Docs

Team is one of the data types that supports permissions at the top level of its Terraform resource in addition to its regular parameters. See Permissions for the parameters that are available.

Example

resource "ns1_team" "foobar" {
  name = "terraform test"

  dns_view_zones = true
  dns_zones_allow_by_default = true
  dns_zones_allow = ["mytest.zone"]
  dns_zones_deny = ["myother.zone"]

  data_manage_datasources = true
}

User

User Api Docs

User is one of the data types that supports permissions at the top level of its Terraform resource in addition to its regular parameters. See Permissions for the parameters that are available.

Example

resource "ns1_user" "u" {
  #required
  name = "terraform acc test user %s"
  username = "tf_acc_test_user_%s"
  email = "tf_acc_test_ns1@hashicorp.com"
  
  #optional
  teams = ["${ns1_team.t.id}"]
  notify {
    billing = true
  }
}

Zone

Zone Api Docs

Example

resource "ns1_zone" "it" {
  zone    = "terraform-test-zone.io"
  ttl     = 10800
  refresh = 3600
  retry   = 300
  expiry  = 2592000
  nx_ttl  = 3601
}

Permissions

There are three resources that support permissions:

  • Apikey
  • Team
  • User

For each of those resources, these parameters are available at the top level of the resource:

  • dns_view_zones: boolean - allows the requestor to view zones
  • dns_manage_zones: boolean - allows the requestor to edit/manage zones
  • dns_zones_allow_by_default: boolean
  • dns_zones_deny: list of strings - explicitly deny these zones for this user/team/key
  • dns_zones_allow: list of strings - explicitly allow these zones for this user/team/key
  • data_push_to_datafeeds: boolean - allows the requestor to push to datafeeds
  • data_manage_datasources: boolean - allows the requestor to manage datasources
  • data_manage_datafeeds: boolean - allows the requestor to manage datafeeds
  • account_manage_users: boolean - allows the requstor to manage users
  • account_manage_payment_methods: boolean - allows the requestor to manage payment methods
  • account_manage_plan: boolean - allows the requestor to manage the account payment plan
  • account_manage_teams: boolean - allows the requestor to manage teams
  • account_manage_apikeys: boolean - allows the requestor to manage apikeys
  • account_manage_account_settings: boolean - allows the requestor to manage account settings
  • account_view_activity_log: boolean - allows the requestor to view the activity log
  • account_view_invoices: boolean - allows the requestor to view account invoices
  • monitoring_manage_lists: boolean - allows the requestor to manage monitoring lists
  • monitoring_manage_jobs: boolean - allows the requestor to manage monitoring jobs
  • monitoring_view_jobs: boolean - allows the requestor to view monitoring jobs

Developing The Provider

If you wish to work on the provider, you'll first need Go installed on your machine (version 1.8+ is required). You'll also need to correctly setup a GOPATH, as well as adding $GOPATH/bin to your $PATH.

To compile the provider, run make build. This will build the provider and put the provider binary in the $GOPATH/bin directory.

$ make bin
...
$ $GOPATH/bin/terraform-provider-ns1
...

In order to test the provider, you can simply run make test.

$ make test

In order to run the full suite of Acceptance tests, run make testacc.

Note: Acceptance tests create real resources, and often cost money to run.

$ make testacc