If you are interested in becoming a maintainer, please reach out to vinyldns-core@googlegroups.com
Ruby gem for working with VinylDNS.
- It was built around the API
- It relies, currently, on the AWS-SDK to sign the HTTP requests it makes
- Ruby ~> 2.4
ENV['VINYLDNS_ACCESS_KEY_ID']&ENV['VINYLDNS_SECRET_ACCESS_KEY']are set in your application or local shell- You can find both of these within the portal by downloading your credentials file
ENV['VINYLDNS_API_URL']is set with your api url (if applicable include http[s]:// and port)
Add this line to your application's Gemfile:
gem 'vinyldns-ruby'Add this require to your code:
require 'vinyldns/api'This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior
- Each method returns a JSON object
- The methods request an 'api_request_object' with the HTTP Method specified like:
Vinyldns::API.new('get'), then perform a variation ofVinyldns::API.make_request(api_request_object, "zones/#{zone_id}") - Method parameters match the HTTP Request Parameter requirements in the API. See the API Reference for more information.
- SSL verification is enabled by default;
ENV['VINYLDNS_VERIFY_SSL']can be set to false in order to disable.
If you decide to contribute, please read over our contributor documentation.
Testing requires a local running VinylDNS instance and this depends on having Docker.
There are a number of scripts for executing the tests located in the scripts/ directory. These can be executed simply by running:
$ make test
If the local api isn't available it will be downloaded and launched before the tests begin running. The script will leave the api running. When you are done with it you can stop it using the following command:
$ make stop-api
- Arguments to methods, take Vinyldns::API::Zone.get(id) as an example, can be a little confusing at first. All arguments used under a method that are not explicit, like in our example id, can be understood as zone_id due to it existing under the namespace ::Zone.
-
Requires you to have at least one zone for your user/group
[1] pry(main)> require 'vinyldns/api' => true [2] pry(main)> Vinyldns::API::Zone.search() => {"zones"=> [{"name"=>"XXXXXXX.yourdomain.net.", "email"=>"XXXXX@yourdomain.com", "status"=>"Active", "created"=>"2017-11-27T17:06:53Z", "updated"=>"2018-01-30T13:56:55Z", "id"=>"92cXXXXX3b67a", "connection"=>{"name"=>"XXXXXXX.yourdomain.net.", "keyName"=>"_t&p-@yourdomain.com", "key"=>"OBe0nmlA==", "primaryServer"=>"XX.rXXXX.yourdomain.net"}, "account"=>"system", "shared"=>false, "acl"=>{"rules"=>[{"accessLevel"=>"Delete", "groupId"=>"15e073b7119c", "recordTypes"=>["A", "NS", "SPF", "AAAA", "SSHFP", "CNAME", "SRV", "PTR", "TXT", "MX"]}]}, "adminGroupId"=>"ac1", "latestSync"=>"2017-12-04T19:35:53Z"}], "maxItems"=>5}
- Below method arguments with "=" next to them indicate a default value. You do not have to specify "argmuentX = nil', just know if you don't set it nil will be used.
- new(method, region = 'us-east-1', api_url = ENV['VINYLDNS_API_URL'], content_type = 'application/x-www-form-urlencoded')
- Required for make_request, but not before any of the Vinyldns::API::* methods.
- make_request(signed_object, uri, body = '')
- HTTP requests that fail are returned as: ```#<Net::HTTPUnauthorized 401 Unauthorized readbody=true>```
- connect(name, distribution_email, group_id = nil, group_name_filter = nil)
- "Connects user to an existing zone. User must be a member of the group that has access to the zone."
- name must be the full zone name you wish to connect to. For example: ingest.yourdomain.net instead of ingest.
- Will use group_id and ignore group_name_filter if group_id is set.
- If group_id is nil and group_name_filter is set, it will run Vinyldns::API::Group.list_my_groups and use the ID of the group it finds.
- group_name_filter searches must return only 1 entry else it will error, so be specific.
- update(id, request_params)
- Zone API Reference > Zone Model details all available options
- request_params must be a hash of values permitted by the API. See the API reference linked to above.
- Updates are NOT immediate.
- delete(id)
- get(id)
- search(name_filter = nil, max_items = 5, start_from = nil)
- If name_filter is not set, it will pull an alphabetical list of zones you have access to.
- sync(id)
- history(id)
- list_changes(id, max_items = 5, start_from = nil)
- create(zone_id, name, type, ttl, records_array)
- Suggested ttl is 900
- update(zone_id, request_params)
- request_params must be a hash of values permitted by the API. See the API reference linked to above.
- delete(zone_id, id)
- get(zone_id, id)
- search(zone_id, name_filter = nil, max_items=10, start_from = nil)
- If name_filter is not set, it will pull an alphabetical list of zones you have access to.
- get_change(zone_id, id, change_id)
- Use Vinyldns::API::Zone.list_changes to obtain change_id
[No Zone ID needed for these]
- create(changes_array, comments)
- changes must be an array of Add or DeleteRecordSet hashes.
- get(id)
- user_recent
- Summary information for the most recent 100 batch changes created by the user.
- create(name, distribution_email, members_array, admins_array, description = '')
- members_array and admins_array must be included. Please see API reference linked to at the top of this readme.
- update(id, request_params)
- request_params must be a hash of values permitted by the API. See the API reference linked to above.
- delete(id)
- get(id)
- list_my_groups(name_filter = nil, max_items = 5, start_from = nil)
- If name_filter is not set, it will pull an alphabetical list of zones you have access to.
- list_group_admins(id)
- list_group_members(id, max_items = 5, start_from = nil)
- get_group_activity(id, max_items = 5, start_from = nil)