🌐 MoJ DNS Management

This repository manages the Ministry of Justice DNS records using octoDNS. It provides a streamlined, code-based approach to DNS management, ensuring consistency and enabling version control for our DNS records.

📖 Table of Contents

• 🌐 MoJ DNS Management
  • 📖 Table of Contents
  • Repository Structure
  • How It Works
  • Configuration
  • CI/CD Pipeline
    • CI/CD AWS IAM User
  • AWS Credentials
  • Making Changes
  • Viewing Current Configuration
  • Applying Changes
  • Makefile Commands
  • Identifying GitHub Pages Delegations
    • Weekly Automation
    • Manual Identification
    • Example .github_pages Output
    • Updating the GitHub Pages Records
  • License

Repository Structure

.
├── .github/                # GitHub Actions workflows
├── bin/                    # Contains various scripts to operate this repository
├── hostedzones/            # DNS zone files
├── .gitignore
├── .github_pages           #  Domains and subdomains that are delegated to GitHub Pages
├── LICENSE
├── Makefile
├── README.md
├── config.yaml             # octoDNS configuration
└── requirements.txt        # Python dependencies

How It Works

1. DNS records are stored as YAML files in the hostedzones/ directory. Each file represents a single hosted zone and contains all records for that zone.

2. Changes are proposed via Pull Requests.

3. A CI/CD pipeline runs octodns-sync in dry-run mode for each PR, allowing for review of proposed changes.

4. Upon merging to the main branch, changes are automatically applied to our Route53 hosted zones.

Configuration

The config.yaml file is set up dynamically to encompass all hosted zones in the mojdsd AWS account (An AWS account owned by Operations Engineering). We use the lenient option due to historical non-uniform record creation.

CI/CD Pipeline

• Pull Requests: Triggers a dry-run of octodns-sync to preview changes.
• Merge to main: Applies changes to Route53 using octodns-sync --doit. Changes typically take about 2 minutes to propagate.

CI/CD AWS IAM User

The AWS IAM user required for the pipelines in this repository is not created or managed within this repository. Instead, it is provisioned and maintained in the main operations-engineering repository.

This approach centralises our IAM user management and ensures that the DNS management system uses credentials that are consistently managed alongside our other operational resources.

AWS Credentials

This project requires AWS credentials to interact with Route53. The Makefile will attempt to use AWS credentials from the following sources, in order:

1. Environment variables (AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY)
2. AWS CLI configuration

If neither of these sources provides valid credentials, commands that require AWS access will fail with an error message.

To set your AWS credentials, you can either:

1. Export them as environment variables:

   export AWS_ACCESS_KEY_ID=your_access_key_id
   export AWS_SECRET_ACCESS_KEY=your_secret_access_key

2. Configure them using the AWS CLI:

   aws configure

Ensure your AWS credentials have the necessary permissions to manage Route53 hosted zones.

Making Changes

1. Clone this repository:

   git clone https://github.com/ministryofjustice/dns.git
   cd dns

2. Install dependencies:

   make install

3. Create a new branch for your changes:

   git checkout -b your-branch-name

4. Edit the appropriate zone file:

   make edit-zone zone=example.com

   This will open the zone file in your default editor. If the file doesn't exist, it will be created.

5. Ensure changes are made in alphabetical order within the file.

6. Validate your changes:

   📝 Note: This may look a little messy, but you're looking for errors rather than warnings.

   make validate-zones

7. Perform a dry-run to see what changes would be made:

   make sync-dry-run

8. If you want to compare your local changes with the live configuration:

   make compare-zone zone=example.com

9. Commit your changes and create a Pull Request:

   git add .
   git commit -m "Your descriptive commit message"
   git push origin your-branch-name

10. Create a Pull Request on GitHub.

Example of adding a new A record to example.com.yaml:

---
'':
  type: A
  values:
    - 192.0.2.1
api:
  type: CNAME
  value: api.example.net.
# New record (note alphabetical order)
blog:
  type: A
  values:
    - 203.0.113.10
www:
  type: CNAME
  value: example.com.

Viewing Current Configuration

To view the current live configuration for a zone:

make dump-zone zone=example.com

This will dump the current Route53 configuration for example.com to a file in the tmp/ directory.

Applying Changes

⚠️ Caution: We strongly recommend you don't apply changes locally. Instead, use the CI/CD pipeline to apply changes.

If you need to apply changes locally (which should be done with extreme caution), you can use:

make sync-apply

This will apply all pending changes to Route53. Always perform a make sync-dry-run first to review the changes that will be made.

Makefile Commands

This repository includes a Makefile to simplify common operations. You can use the following commands:

make                          # Show help message with available commands
make help                     # Same as above, shows help message
make install                  # Set up the Python environment
make edit-zone zone=<zone>    # Edit a hosted zone file
make validate-zones           # Validate all zone files
make sync-dry-run             # Perform a dry-run sync for all zones
make sync-apply               # Apply changes to all zones
make list-zones               # List all zones
make dump-zone zone=<zone>    # Dump the current live configuration for a zone
make compare-zone zone=<zone> # Compare a zone file with its live configuration
make clean                    # Clean up generated files
make print-github-delegations # Print GitHub Pages delegations

To see a full list of available commands and their descriptions, simply run make or make help.

Identifying GitHub Pages Delegations

This repository includes functionality to identify DNS records associated with GitHub Pages. These delegations are automatically identified and logged, and a Pull Request is created weekly if changes are detected.

Weekly Automation

A GitHub Action runs every Sunday at midnight (UTC) to identify GitHub Pages delegations across the DNS records. If any changes are detected in the delegations, a Pull Request is automatically created with the updated .github_pages file. This file lists all GitHub Pages delegations in the format <record>.<hostedzone>.

Manual Identification

To manually identify GitHub Pages delegations, you can use the following Makefile command:

make print_github_delegation

This command outputs the current list of GitHub Pages delegations in the .github_pages file.

Example .github_pages Output

The .github_pages file contains entries in the format <record>.<hostedzone>. For example:

cjsm.justice.gov.uk
hmpps-architecture-blueprint.service.justice.gov.uk
runbooks.operations-engineering.service.justice.gov.uk

Updating the GitHub Pages Records

If you need to update the GitHub Pages records manually:

1. Run the following command to identify changes:

make print-github-delegations

1. Commit and push any changes to the .github_pages file:

git add .github_pages
git commit -m "Update GitHub Pages delegations"
git push

License

This project is licensed under the MIT License - see the LICENSE file for details.