cookbook 'ec2dnsserver', '= 2.2.1'
ec2dnsserver (5) Versions 2.2.1 Follow0
Installs/Configures ec2dnsserver
cookbook 'ec2dnsserver', '= 2.2.1', :supermarket
knife supermarket install ec2dnsserver
knife supermarket download ec2dnsserver
ec2dnsserver cookbook
Uses the AWS API to build bind zone files to reference all of the nodes in your cluster using their tagged names and internal IPs.
Requirements
- Fog gem (to call the EC2 API and get node tags)
- IPAddress gem (for some IP address parsing)
- Rsyslog (if you want to use syslog logging)
Necessary changes to the chef-client
This cookbook sets the node['chef_client']['interval']
and node['chef_client']['splay']
attributes which are read by the chef-client cookbook to make chef-client run more rapidly. If you are not using the chef-client cookbook, you may want to find some other way to adjust the chef run interval so that your DNS stay reasonably up to date.
Known Issues
- Currently only supports IPv4
- Currently only supports RSyslog
- Possibly more complicated to use than it really should be
Required Permissions
Create an IAM user with the following permissions:
{
"Version": "2014-03-12",
"Statement": [
{
"Action": [
"ec2:DescribeInstances",
"ec2:DescribeNetworkInterface*",
"ec2:DescribeVpcs"
],
"Resource": [
"*"
],
"Effect": "Allow"
}
]
}
Usage
There are essentially two supported ways to use the ec2dnsserver cookbook. One
is to include the recipe via include_recipe
and the other is via the
ec2dnsserver_zone resource, like so:
ec2dnsserver_zone Resource
execute 'reload_zones' do
command 'rndc reload'
action :nothing
end
ec2dnsserver_zone "priv.yourdomain.local" do
vpcs %w(vpc-1a2b3c4d)
stub false
ptr false
suffix "priv.yourdomain.local"
static_records(
'hostname' => {
'cookbook' => 'some_cookbook'
}
)
avoid_subnets %w(subnet-1a2b3c4d)
contact_email 'hostmaster@yourcompany.com'
path '/etc/bind/db.priv.yourdomain.local'
notifies :run, 'execute[reload_zones]'
end
Properties explained
- apex (name attribute) - The zone apex.
- vpcs - This is the list of VPCs from which to include zone data (default: [])
- avoid_subnets - IPs for network adapters in these subnets will not be used to generate the zone
-
path - The location of the zone file (default:
#{node['ec2dnsserver']['zones_dir']}/db.#{apex}
) -
stub - Set to
true
if this is to be a "stub" zone. A stub zone is a zone with only one A record at the zone apex. It is useful for overriding FQDNs in zones for which your DNS server is not authoritative. - suffix - Name to append to any tagged names found in your EC2 cluster. E.g. In PTR zones, records will be constructed as "4.3.2.1.in-addr.arpa IN PTR ec2servername.suffix". Defaults to the zone apex if not specified.
- ptr - True if this is a PTR (reverse lookup) zone (default: false)
-
static_records - A hash describing extra records to be appended to the zone (See
static_records
section) - ns_zone - The parent zone of the name server (NS) record for this zone. (default: value of suffix)
Properties pertaining specifically to the SOA record (See: http://www.zytrax.com/books/dns/ch8/soa.html). All times are in seconds.
- source_host - The host used for the SOA record name server field (default: node.name)
- default_ttl - The default time-to-live (i.e. cache timeout) for the zone in seconds (default: 300)
- contact_email - The hostmaster's email address (REQUIRED)
- refresh_time - Timeout before the slave will try to refresh the zone from the master (default: 3600)
- retry_time - Time between retries if the slave fails to contact the master when refresh (above) has expired (default: 600)
- expire_time - Indicates when the zone data is no longer considered authoritative (default: 86400)
- nxdomain_ttl - How long a bad lookup (e.g. one that finds nothing) is cached (default: 300)
static_records
This section describes the format of the hash used to define static records. Basically they look like this:
To define the base of a "stub" (aka. override) zone
{
"value": "1.1.1.1",
"type": "A"
}
To use a cookbook or a role to create a dynamic mapping
{
"hostname": {
"cookbook": "cookbook_name"
}
}
Or a role
{
"hostname": {
"role": "role_name"
}
}
zones
This section describes the format of the keyed hash used to define zones (by way of the node['ec2dnsserver']['zones']
attribute). The format looks like the following...
Simplest possible primary zone config:
{
"priv.yourdomain.local": {}
}
Simplest possible PTR config:
{
"10.in-addr.arpa": {
"ptr_zone": true,
"suffix": "priv.yourdomain.local"
}
}
For a standard, primary zone with some static records that uses VPCs:
{
"priv.yourdomain.local": {
"ptr_zone": false,
"primary": true,
"static_records": {
"stage-storm": {
"cookbook": "et_ops_haproxy"
}
},
"vpcs": [
"vpc-1a2b3c4d"
]
}
}
For a PTR zone:
{
"10.in-addr.arpa": {
"ptr_zone": true,
"suffix": "priv.yourdomain.local",
"primary": false,
"vpcs": [
"vpc-1a2b3c4d"
]
}
}
For a stub zone that uses a cookbook search to build its apex record:
{
"test-cookbook-host.anotherdomain.com": {
"stub": true,
"suffix": "priv.yourdomain.local",
"primary": false,
"static_records": {
"cookbook": "et_ops_haproxy"
}
}
}
For a stub zone that uses a statically defined IP address for its apex record:
{
"test-value-host.anotherdomain.com": {
"stub": true,
"suffix": "priv.yourdomain.local",
"primary": false,
"static_records": {
"value": "1.1.1.1",
"type": "A"
}
}
}
Attributes
All attributes fall under the *['ec2dnsserver']** hash key.*
- ['user'] - User that bind will run under. (default: bind)
- ['group'] - Grou that bind will run under. (default: bind)
- ['aws_api_user'] - User that ec2dnsserver will use to interact with the EC2 API (in fact this is currently only used as the key to lookup the real keys in the API keys data bag). (default: Ec2DnsServer)
- ['config_dir'] - The bind config path (default: /etc/bind)
- ['cache_dir'] - The bind cache directory (default: /var/cache/bind)
- ['zones_dir'] - Where the zone files live (default: value of ['config_dir'])
- ['contact_email'] - The hostmaster's email address (default: nil)
- ['dnssec_validation'] - Sets the flag by the same name in bind conf (See: DNS BIND9 Security Statements) (default: no)
- ['avoid_subnets'] - IPs for network adapters in these subnets will not be used to generate the zone. (default: [])
- ['recursion_clients'] - Array of CIDR-formatted network addresses that will be allowed to do recursive queries against the nameserver. (attribute default is [] but template automatically includes localhost, 10/8, and localnets)
- ['zones'] - Use this to pass a list of zones to the cookbook instead of using the resource. See zones section.
Logging Attributes
- ['log']['log_queries'] - Enable logging of every single query (warning: disk space monster). (default: false)
- ['log']['facility'] - Which syslog facility to use. (default: daemon)
- ['log']['versions'] - How many old log files to keep. (default: 5)
- ['log']['size'] - Max log file size. (default: 25M)
- ['log']['logger'] - Which log config recipe to use. (default and currently the only one supported: rsyslog)
- ['log']['severity'] - Which severity to attach to syslog messages. (default: dynamic)
- ['log']['file'] - File to send logs to when not using syslog. (default: /var/log/named/named.log)
Recipes
The only one you care about is default
. rsyslog
(and any future sys logger dependencies) are brought in as dependencies automatically.
Author
Author:: EverTrue, Inc. (devops@evertrue.com)
Dependent cookbooks
build-essential >= 0.0.0 |
et_fog ~> 1.0 |
Contingent cookbooks
There are no cookbooks that are contingent upon this one.
CHANGELOG for ec2dnsserver
2.2.1
- Switch to Apache v2.0 license
2.2.0
- Add the ability to handle zone types besides "master"
2.1.3
- Fix Chef search to accommodate chef/chef#2312
- Move installation of
bind9
up to fix race condition () - Rubocop & Test Kitchen config cleanup
- Still doesn’t test standalone
2.1.2:
- A bunch of library code cleanup
- attempt to create host records only for the networking interface that is first according to "deviceIndex" (as opposed to first according to random)
2.1.1:
- Fixed OR code to correctly set record types on static records
2.1.0:
- Enable zone transfers by IP
2.0.2:
- Delete set-bind-forwarders DHCP hook
2.0.1:
- Explicitly specify localhost in dig test
2.0.0:
- Don't put file logging properties in the query syslog config
- Convert to berkshelf 3
- Remove now-meaningless
node['ec2dnsserver']['vpc']
attribute - Rename min_ttl to the more meaningful nxdomain_ttl
- Remove requirement that path be specified in resource
- Duplicate the full path under the template cache path in order to minimize the chances of conflict if a file name is re-used for whatever reason.
- Static records are not really required so the default recipe shouldn't fail if they're missing from the attributes
- Remove options that are not valid in syslog logs from syslog query logger
- Fix format of file parameter in query log config
- ptr is an optional resource parameter so it should also be an optional node attribute
- Don't handle undefined stub attribute in a way that is dumb
- Clean up handling of DNS suffixes in zones other than the parent zone of the name server
- Bump et_fog 1.0.4
- Create docs!
- Broke compatibility with old zones hash format
- Add reverse DNS test; Use regex for test response instead of string matching
1.5.0:
- Support multiple VPCs per DNS server and no VPC at all
- Get VPC CIDR block directly from ohai data rather tha via Fog.
- Allow forwarders override
- Define VPC(s) in zone config
- Refuse to run without EC2
1.4.0:
- Derive local VPC DNS IP if it is not hardcoded in an attribute
1.3.0:
- Optimize library for better testing
1.2.0:
- Add static_records function
1.1.2:
- Removed EverTrue's email from the default
1.1.1:
- Use external fog cookbook
- Add recursion clients default null value
1.1.0:
- Add recursion clients parameter
1.0.13:
- Pass avoid_subnets to ec2 zone resource
1.0.12:
- log avoid_subnets value
1.0.11:
- Don't try to use IP addresses belonging to NICs on the "avoid subnets" list (prevents public subnets from receiving DNS entries)
- Break out query log (if enabled) into a separate non-syslog file, in addition to sending it over the syslog link.
- Give up on using externally generated forwarders file
- Set more permissive mode on log dir
1.0.10:
- Only display "forwarders" section in named.conf if "forwarders" array has non-zero value
1.0.9:
- Started doing a changelog
- Validate hostnames according to http://en.wikipedia.org/wiki/Hostname (essential because many things--like spaces--are valid in EC2 "Name" tags that aren't allowed as hostnames)
- Shorten chef-client interval to 300s and splay to 180s
- Switched to use_inline_resources for resource notification in Zone provider
Foodcritic Metric
2.2.1 passed this metric
2.2.1 passed this metric