docs: README, changelog, contributing, security, deployment, operations, CI
Some checks are pending
build / build (push) Waiting to run
Some checks are pending
build / build (push) Waiting to run
This commit is contained in:
root
commit
473855e59a
12 changed files with 551 additions and 0 deletions
89
docs/deployment.md
Normal file
89
docs/deployment.md
Normal file
|
|
@ -0,0 +1,89 @@
|
|||
# Deployment
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Samba AD DC
|
||||
- Docker host joined to the AD domain
|
||||
- Docker Swarm mode enabled
|
||||
- Traefik running with API enabled
|
||||
|
||||
---
|
||||
|
||||
## 1. Samba AD: Create service account and keytab
|
||||
|
||||
On the Samba DC:
|
||||
|
||||
sudo samba-tool user create dns-updater --random-password
|
||||
sudo samba-tool group addmembers DnsAdmins dns-updater
|
||||
sudo samba-tool domain exportkeytab /etc/samba/dns-updater.keytab \
|
||||
--principal=dns-updater@DISCWORLD.NETWORK
|
||||
sudo kinit -kt /etc/samba/dns-updater.keytab dns-updater@DISCWORLD.NETWORK
|
||||
klist
|
||||
|
||||
---
|
||||
|
||||
## 2. Join the Docker host to the domain
|
||||
|
||||
sudo apt install sssd-ad sssd-tools realmd adcli krb5-user \
|
||||
packagekit samba-common-bin libnss-sss libpam-sss
|
||||
sudo realm join discworld.network -U administrator
|
||||
sudo realm list
|
||||
|
||||
---
|
||||
|
||||
## 3. Transfer keytab and create Docker secret
|
||||
|
||||
On the DC make the keytab readable temporarily:
|
||||
|
||||
sudo cp /etc/samba/dns-updater.keytab /tmp/dns-updater.keytab
|
||||
sudo chown <youradmin>:<youradmin> /tmp/dns-updater.keytab
|
||||
|
||||
On your local machine:
|
||||
|
||||
scp <dcadmin>@<dc>:/tmp/dns-updater.keytab .
|
||||
scp dns-updater.keytab <dockeradmin>@<dockerhost>:/tmp/
|
||||
shred -u dns-updater.keytab
|
||||
|
||||
On the DC clean up:
|
||||
|
||||
sudo shred -u /tmp/dns-updater.keytab
|
||||
|
||||
On the Docker host:
|
||||
|
||||
sudo docker secret create dns-updater-keytab /tmp/dns-updater.keytab
|
||||
sudo shred -u /tmp/dns-updater.keytab
|
||||
sudo docker secret ls
|
||||
|
||||
---
|
||||
|
||||
## 4. Enable Docker Swarm
|
||||
|
||||
sudo docker swarm init --advertise-addr <docker-host-ip>
|
||||
|
||||
---
|
||||
|
||||
## 5. Build and push the image
|
||||
|
||||
git clone https://git.ankh-morpork.discworld.network/laurence/dns-traefik-sync.git
|
||||
cd dns-traefik-sync
|
||||
sudo docker build -t git.ankh-morpork.discworld.network/laurence/dns-traefik-sync:latest .
|
||||
sudo docker login git.ankh-morpork.discworld.network
|
||||
sudo docker push git.ankh-morpork.discworld.network/laurence/dns-traefik-sync:latest
|
||||
|
||||
---
|
||||
|
||||
## 6. Deploy the stack
|
||||
|
||||
sudo docker stack deploy -c docker-compose.yml dns-traefik-sync
|
||||
sudo docker stack ps dns-traefik-sync
|
||||
sudo docker service logs dns-traefik-sync_dns-traefik-sync
|
||||
|
||||
---
|
||||
|
||||
## 7. Verify DNS records are being created
|
||||
|
||||
dig @192.168.88.1 adguard.ankh-morpork.discworld.network
|
||||
|
||||
Or on the DC:
|
||||
|
||||
sudo samba-tool dns query 127.0.0.1 ankh-morpork.discworld.network @ ALL -U administrator
|
||||
78
docs/operations.md
Normal file
78
docs/operations.md
Normal file
|
|
@ -0,0 +1,78 @@
|
|||
# Operations
|
||||
|
||||
## Checking service status
|
||||
|
||||
sudo docker service ls
|
||||
sudo docker stack ps dns-traefik-sync
|
||||
sudo docker service logs dns-traefik-sync_dns-traefik-sync --follow
|
||||
|
||||
## What healthy logs look like
|
||||
|
||||
2026-05-24 18:00:00 INFO dns-traefik-sync starting
|
||||
2026-05-24 18:00:00 INFO Kerberos ticket obtained
|
||||
2026-05-24 18:00:00 INFO Adding adguard.ankh-morpork.discworld.network -> 192.168.88.2
|
||||
2026-05-24 18:01:00 INFO Kerberos ticket obtained
|
||||
2026-05-24 18:01:00 INFO No changes
|
||||
|
||||
## Manually verifying DNS records
|
||||
|
||||
dig @192.168.88.1 grafana.ankh-morpork.discworld.network A
|
||||
sudo samba-tool dns query 127.0.0.1 ankh-morpork.discworld.network @ ALL -U administrator
|
||||
|
||||
## Forcing a re-sync
|
||||
|
||||
sudo docker service update --force dns-traefik-sync_dns-traefik-sync
|
||||
|
||||
## Updating the image
|
||||
|
||||
cd dns-traefik-sync
|
||||
git pull
|
||||
sudo docker build -t git.ankh-morpork.discworld.network/laurence/dns-traefik-sync:latest .
|
||||
sudo docker push git.ankh-morpork.discworld.network/laurence/dns-traefik-sync:latest
|
||||
sudo docker service update --image \
|
||||
git.ankh-morpork.discworld.network/laurence/dns-traefik-sync:latest \
|
||||
dns-traefik-sync_dns-traefik-sync
|
||||
|
||||
## Keytab rotation
|
||||
|
||||
On the Samba DC:
|
||||
|
||||
sudo samba-tool user setpassword dns-updater --random-password
|
||||
sudo samba-tool domain exportkeytab /etc/samba/dns-updater.keytab \
|
||||
--principal=dns-updater@DISCWORLD.NETWORK
|
||||
|
||||
Update the Docker secret:
|
||||
|
||||
sudo docker secret rm dns-updater-keytab
|
||||
sudo docker secret create dns-updater-keytab /tmp/dns-updater.keytab
|
||||
sudo shred -u /tmp/dns-updater.keytab
|
||||
sudo docker stack deploy -c docker-compose.yml dns-traefik-sync
|
||||
|
||||
## Removing a DNS record manually
|
||||
|
||||
sudo samba-tool dns delete 127.0.0.1 ankh-morpork.discworld.network \
|
||||
<hostname> A 192.168.88.2 -U administrator
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### kinit fails - no suitable keys
|
||||
|
||||
Keytab is stale. Re-export on the DC:
|
||||
|
||||
sudo samba-tool domain exportkeytab /etc/samba/dns-updater.keytab \
|
||||
--principal=dns-updater@DISCWORLD.NETWORK
|
||||
|
||||
### nsupdate fails with REFUSED
|
||||
|
||||
dns-updater not in DnsAdmins:
|
||||
|
||||
sudo samba-tool group addmembers DnsAdmins dns-updater
|
||||
|
||||
### nsupdate fails with NOTAUTH
|
||||
|
||||
Wrong DNS_ZONE or DNS_SERVER environment variable.
|
||||
|
||||
### Records not being created for a container
|
||||
|
||||
Container must have a Host() rule in its Traefik label matching DNS_ZONE.
|
||||
Internal and non-docker providers are ignored.
|
||||
Loading…
Add table
Add a link
Reference in a new issue