zinc
Welcome to Zinc
Zinc is a Route 53 zone manager.
Zinc was developed by the awesome engineering team at Presslabs, a Managed WordPress Hosting provider.
For more open-source projects, check Presslabs Code.
Policy Records on the Cheap
Q: Why would one use Zinc over AWS's Policy Records?
A: Price. 50$ per Record adds up quickly.
Overview
IPs, Policies and Policy Records
At the end of the day your domain name example.com needs to resolve to one or more
ip addresses. Here's how we go about it.
IPs
Should be self explanatory. An IP can be enabled or disabled.
There is no explicit handling in zinc of multiple IPs belonging to one server.
Enabling or disabling can be done from the admin or by implementing a django app (see lattice_sync for an example).
N.B. If implementing your own app it's your responsibility to call
ip.mark_policy_records_dirty if the IP changes, so that zinc's reconcile loop will
actually pick up the changes.
HealthChecks
Zinc will create a Route53 Health Check for each IP. If Route53 deems the IP unavailable, it will stop routing traffic to it.
Currently the Health Checks are hardcoded to expect all servers to accept requests with the
same FQDN (defaults to node.presslabs.net, set ZINC_HEALTH_CHECK_FQDN to change).
Policies
A policy groups several IPs together. There are 2 types of policies:
- Weighted
- Latency
Note that an IP can be a member of multiple Policies at the same time. A PolicyMember can has it's own enabled flag, so you can disable an IP for one Policy only, or you can disable the it for all Policies by setting the enabled flag on the IP model.
Weighted
Trafic will be routed to all IP's based on their weights. Bigger weight means more trafic.
Latency
Each IP you add to a Policy will have a region specified as well. The region must be an AWS region. IPs will still have weights, which will be used to balance the trafic within a region. When a cliend does a DNS lookup, they'll get directed to the region with the lowest latency, and then an IP will be picked based on weight.
The resulting setup will be similar to the example described here: http://docs.aws.amazon.com/Route53/latest/DeveloperGuide/dns-failover-complex-configs.html
Policy Records
Your desired DNS record. In Route53 it will be an alias to the Latency or Weighted records that make up a Policy.
Reconcile Loops and the Single Source of Truth
For simple records in a zone (anything except a PolicyRecord) AWS is the Sigle Source of Truth. Zinc never stores those locally.
For Zones, HealthChecks and PolicyRecords Zinc's database is the single source of truth. Zinc runs reconcile loops and attempts to update your AWS data to match the expected state in the DB. To minimize throttling by AWS, in most cases, Zinc only attempts to reconcile objects marked deemed dirty. This means it is possible to have a missmatch between what you have in AWS and Zinc's expected state if you make changes bypassing Zinc (using the AWS console, or the api).
API
You are encouraged to install django-rest-swagger, run zinc locally and explore the API at http://localhost:8080/swagger
Policies
Policies are read only trough the API. You can define them in the admin.
Policy listing.
GET /policies
Policy detail. Example:
GET /policies/{id}
GET /policies/344b7bee-da33-4234-b645-805cc26adab0
{
"id": "344b7bee-da33-4234-b645-805cc26adab0",
"name": "policy-one",
"members": [
{
"id": "6bcb4e77-04dc-45f7-bebb-a2fcfadd7669",
"region": "us-east-1",
"ip": "192.0.2.11",
"weight": 10,
"enabled": true
},
{
"id": "4f83d47f-af0c-4fa7-80c8-710cb32e4928",
"region": "us-west-1",
"ip": "192.0.2.11",
"weight": 10,
"enabled": true
}
],
"url": "https://zinc.stage.presslabs.net/policies/344b7bee-da33-4234-b645-805cc26adab0"
}
Zones
Zone listing.
GET /zones/
Zone creation.
POST /zones/
Args:
| argument | required | default | description |
|---|---|---|---|
| root | required | - | The domain name of this zone. Trailing dot is optional. |
Returns the newly created zone object.
Delete a zone.
DELETE /zones/{zone_id}/
Zone detail.
GET /zones/{zone_id}
Example:
GET /zones/102
{
"root": "zinc.example.presslabs.net.",
"url": "https://zinc.stage.presslabs.net/zones/102",
"records_url": "https://zinc.stage.presslabs.net/zones/102/records",
"records": [
{
"name": "@",
"fqdn": "zinc.example.presslabs.net.",
"type": "NS",
"values": [
"ns-389.awsdns-48.com.",
"ns-1596.awsdns-07.co.uk.",
"ns-1008.awsdns-62.net.",
"ns-1294.awsdns-33.org."
],
"ttl": 172800,
"dirty": false,
"id": "Z6k504rwKzbamNZ9ZmY5lvkoOJGDW0",
"url": "https://zinc.stage.presslabs.net/zones/102/records/Z6k504rwKzbamNZ9ZmY5lvkoOJGDW0",
"managed": true
},
{
"name": "@",
"fqdn": "zinc.example.presslabs.net.",
"type": "SOA",
"values": [
"ns-389.awsdns-48.com. awsdns-hostmaster.amazon.com. 1 7200 900 1209600 86400"
],
"ttl": 900,
"dirty": false,
"id": "Z6k504rwKzbamNZ6Z7doJ0yg98j9zA",
"url": "https://zinc.stage.presslabs.net/zones/102/records/Z6k504rwKzbamNZ6Z7doJ0yg98j9zA",
"managed": true
}
],
"route53_id": "Z8QRF09VVGAC6",
"dirty": false,
"ns_propagated": false
}
Records
List records in a zone.
GET /zones/{zone_id}/records
Example:
GET /zones/102/records
[
{
"name": "@",
"fqdn": "zinc.example.presslabs.net.",
"type": "NS",
"values": [
"ns-389.awsdns-48.com.",
"ns-1596.awsdns-07.co.uk.",
"ns-1008.awsdns-62.net.",
"ns-1294.awsdns-33.org."
],
"ttl": 172800,
"dirty": false,
"id": "Z6k504rwKzbamNZ9ZmY5lvkoOJGDW0",
"url": "https://zinc.stage.presslabs.net/zones/102/records/Z6k504rwKzbamNZ9ZmY5lvkoOJGDW0",
"managed": true
},
{
"name": "@",
"fqdn": "zinc.example.presslabs.net.",
"type": "SOA",
"values": [
"ns-389.awsdns-48.com. awsdns-hostmaster.amazon.com. 1 7200 900 1209600 86400"
],
"ttl": 900,
"dirty": false,
"id": "Z6k504rwKzbamNZ6Z7doJ0yg98j9zA",
"url": "https://zinc.stage.presslabs.net/zones/102/records/Z6k504rwKzbamNZ6Z7doJ0yg98j9zA",
"managed": true
}
]
Create a record.
POST /zones/{zone_id}/records
Args:
| argument | required | default | description |
|---|---|---|---|
| name | required | - | The domain name (without the zone root). |
| type | required | - | The record type. Must be either POLICY_ROUTED or a valid record type. |
| values | required | - | List of values. Should be one IP for A, MX records, a policy id for POLICY_ROUTED, one or more domain names for NS records. |
| ttl | optional | 300 | The TTL for DNS. |
Delete a record.
DELETE /zones/{zone_id}/records/{record_id}
Record detail.
GET /zones/{zone_id}/records/{record_id}
Example:
GET /zones/102/records/Z6k504rwKzbamNZ1ZxLxRR4BKly04J
{
"name": "www",
"fqdn": "www.zinc.example.presslabs.net.",
"type": "POLICY_ROUTED",
"values": [
"344b7bee-da33-4234-b645-805cc26adab0"
],
"ttl": null,
"dirty": false,
"id": "Z6k504rwKzbamNZ1ZxLxRR4BKly04J",
"url": "https://zinc.stage.presslabs.net/zones/102/records/Z6k504rwKzbamNZ1ZxLxRR4BKly04J",
"managed": false
}
Update an existing record.
PATCH /zones/{zone_id}/records/{record_id}
The type and name can't be changed. Missing attributes don't change.
| argument | required | default | description |
|---|---|---|---|
| values | optional | - | List of values. Should be one IP for A, MX records, a policy id for POLICY_ROUTED, one or more domain names for NS records. |
| ttl | optional | - | The TTL for DNS. |
Installing and Running
The recomended way to get up and running is using our Docker container.
cd contrib/
docker-compose up
Config
If you run the django project with default settings, you can configure zinc by setting environment variables. If you're using the provided docker-compose.yml you can set the environment in ./zinc.env
The following are essential and required:
ZINC_AWS_KEY - AWS Key
ZINC_AWS_SECRET - AWS Secret
ZINC_SECRET_KEY - Django secret
You can also set the following:
ZINC_ALLOWED_HOSTS - Django Allowed Hosts
ZINC_BROKER_URL - Celery Broker URL, defaults to ${REDIS_URL}/0
ZINC_CELERY_RESULT_BACKEND - Celery Result Backend, defaults to ${REDIS_URL}/1
ZINC_DATA_DIR - PROJECT_ROOT
ZINC_DB_ENGINE - The django db engine to use. Defaults to 'django.db.backends.sqlite3'
ZINC_DB_HOST -
ZINC_DB_NAME - zinc
ZINC_DB_PASSWORD - password
ZINC_DB_PORT -
ZINC_DB_USER - zinc
ZINC_DEBUG - Django debug. Defaults to False. Set to the string "True" to turn on debugging.
ZINC_DEFAULT_TTL - 300
ZINC_ENV_NAME - The environment for sentry reporting.
ZINC_GOOGLE_OAUTH2_KEY - For use with social-django. If you don't set this, social-django will be disabled.
ZINC_GOOGLE_OAUTH2_SECRET - For use with social-django.
ZINC_SOCIAL_AUTH_ADMIN_EMAILS - List of email addresses that will be automatically granted admin access.
ZINC_SOCIAL_AUTH_GOOGLE_OAUTH2_WHITELISTED_DOMAINS - see http://python-social-auth.readthedocs.io/en/latest/configuration/settings.html?highlight=whitelisted#whitelists
ZINC_HEALTH_CHECK_FQDN - Hostname to use in Health Checks. Defaults to 'node.presslabs.net.'
ZINC_LOCK_SERVER_URL - Used with redis-lock. Defaults to ${REDIS_URL}/2.
ZINC_LOG_LEVEL - Defaults to INFO
ZINC_NS_CHECK_RESOLVERS - NameServers to use when checking zone propagation. Default: ['8.8.8.8']
ZINC_REDIS_URL - Defaults to 'redis://localhost:6379'
ZINC_SECRET_KEY - The secret key used by the django app.
ZINC_SENTRY_DSN - Set this to enable sentry error reporting.
ZINC_STATIC_URL - Defaults to '/static/'
ZINC_ZONE_OWNERSHIP_COMMENT - Set this comment on records, to Defaults to 'zinc'
Development
Warning! Don't use production AWS credentials when developing or testing Zinc!
After you've cloned the code:
pip install -r requirements.dev.txt
python setup.py develop
cp local_settings.py.example local_settings.py
# open local_settings.py in your favorite editor, and set AWS credentials
To run the tests:
# all tests
py.test .
# to skip tests that need AWS
py.test -k 'not with_aws' .