docs: rewrite README with structured overview and quick start guide
Replaces the minimal project description with a comprehensive README including a component overview table, quick start instructions, common Ansible operations, and links to detailed documentation. Aligns with Red Panda Approval™ standards.
This commit is contained in:
71
ansible/certbot/cert-metrics.sh.j2
Normal file
71
ansible/certbot/cert-metrics.sh.j2
Normal file
@@ -0,0 +1,71 @@
|
||||
#!/bin/bash
|
||||
# Certificate metrics for Prometheus node_exporter textfile collector
|
||||
# Managed by Ansible - DO NOT EDIT MANUALLY
|
||||
#
|
||||
# Writes metrics to: {{ prometheus_node_exporter_text_directory }}/ssl_cert.prom
|
||||
# Metrics:
|
||||
# ssl_certificate_expiry_timestamp - Unix timestamp when cert expires
|
||||
# ssl_certificate_expiry_seconds - Seconds until expiry
|
||||
# ssl_certificate_valid - 1 if valid, 0 if expired or missing
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
METRICS_DIR="{{ prometheus_node_exporter_text_directory }}"
|
||||
METRICS_FILE="${METRICS_DIR}/ssl_cert.prom"
|
||||
CERT_FILE="{{ haproxy_cert_path }}"
|
||||
DOMAIN="{{ haproxy_domain }}"
|
||||
|
||||
# Create temp file for atomic write
|
||||
TEMP_FILE=$(mktemp "${METRICS_DIR}/.ssl_cert.prom.XXXXXX")
|
||||
|
||||
# Write metric headers
|
||||
cat > "${TEMP_FILE}" << 'EOF'
|
||||
# HELP ssl_certificate_expiry_timestamp Unix timestamp when the SSL certificate expires
|
||||
# TYPE ssl_certificate_expiry_timestamp gauge
|
||||
# HELP ssl_certificate_expiry_seconds Seconds until the SSL certificate expires
|
||||
# TYPE ssl_certificate_expiry_seconds gauge
|
||||
# HELP ssl_certificate_valid Whether the SSL certificate is valid (1) or expired/missing (0)
|
||||
# TYPE ssl_certificate_valid gauge
|
||||
EOF
|
||||
|
||||
if [[ -f "${CERT_FILE}" ]]; then
|
||||
# Extract expiry date from certificate
|
||||
EXPIRY_DATE=$(openssl x509 -enddate -noout -in "${CERT_FILE}" 2>/dev/null | cut -d= -f2)
|
||||
|
||||
if [[ -n "${EXPIRY_DATE}" ]]; then
|
||||
# Convert to Unix timestamp
|
||||
EXPIRY_TIMESTAMP=$(date -d "${EXPIRY_DATE}" +%s 2>/dev/null || echo "0")
|
||||
CURRENT_TIMESTAMP=$(date +%s)
|
||||
EXPIRY_SECONDS=$((EXPIRY_TIMESTAMP - CURRENT_TIMESTAMP))
|
||||
|
||||
# Check if certificate is valid (not expired)
|
||||
if [[ ${EXPIRY_SECONDS} -gt 0 ]]; then
|
||||
VALID=1
|
||||
else
|
||||
VALID=0
|
||||
fi
|
||||
|
||||
# Extract issuer for label
|
||||
ISSUER=$(openssl x509 -issuer -noout -in "${CERT_FILE}" 2>/dev/null | sed 's/.*O = \([^,]*\).*/\1/' | tr -d '"' || echo "unknown")
|
||||
|
||||
# Write metrics
|
||||
echo "ssl_certificate_expiry_timestamp{domain=\"${DOMAIN}\",issuer=\"${ISSUER}\"} ${EXPIRY_TIMESTAMP}" >> "${TEMP_FILE}"
|
||||
echo "ssl_certificate_expiry_seconds{domain=\"${DOMAIN}\",issuer=\"${ISSUER}\"} ${EXPIRY_SECONDS}" >> "${TEMP_FILE}"
|
||||
echo "ssl_certificate_valid{domain=\"${DOMAIN}\",issuer=\"${ISSUER}\"} ${VALID}" >> "${TEMP_FILE}"
|
||||
else
|
||||
# Could not parse certificate
|
||||
echo "ssl_certificate_expiry_timestamp{domain=\"${DOMAIN}\",issuer=\"unknown\"} 0" >> "${TEMP_FILE}"
|
||||
echo "ssl_certificate_expiry_seconds{domain=\"${DOMAIN}\",issuer=\"unknown\"} 0" >> "${TEMP_FILE}"
|
||||
echo "ssl_certificate_valid{domain=\"${DOMAIN}\",issuer=\"unknown\"} 0" >> "${TEMP_FILE}"
|
||||
fi
|
||||
else
|
||||
# Certificate file does not exist
|
||||
echo "ssl_certificate_expiry_timestamp{domain=\"${DOMAIN}\",issuer=\"none\"} 0" >> "${TEMP_FILE}"
|
||||
echo "ssl_certificate_expiry_seconds{domain=\"${DOMAIN}\",issuer=\"none\"} 0" >> "${TEMP_FILE}"
|
||||
echo "ssl_certificate_valid{domain=\"${DOMAIN}\",issuer=\"none\"} 0" >> "${TEMP_FILE}"
|
||||
fi
|
||||
|
||||
# Set permissions and atomic move
|
||||
chmod 644 "${TEMP_FILE}"
|
||||
chown prometheus:prometheus "${TEMP_FILE}" 2>/dev/null || true
|
||||
mv "${TEMP_FILE}" "${METRICS_FILE}"
|
||||
323
ansible/certbot/deploy.yml
Normal file
323
ansible/certbot/deploy.yml
Normal file
@@ -0,0 +1,323 @@
|
||||
---
|
||||
# -----------------------------------------------------------------------------
|
||||
# Certbot Deployment Playbook
|
||||
# -----------------------------------------------------------------------------
|
||||
# Deploys certbot with Namecheap DNS-01 validation for wildcard certificates
|
||||
# Host: hippocamp.helu.ca (OCI HAProxy instance)
|
||||
#
|
||||
# Secrets are fetched automatically from OCI Vault via group_vars/all/secrets.yml
|
||||
# -----------------------------------------------------------------------------
|
||||
|
||||
- name: Deploy Certbot with Namecheap DNS-01 Validation
|
||||
hosts: ubuntu
|
||||
vars:
|
||||
ansible_common_remote_group: "{{ certbot_group | default(omit) }}"
|
||||
allow_world_readable_tmpfiles: true
|
||||
tags: [certbot, ssl, deploy]
|
||||
|
||||
handlers:
|
||||
- name: restart certbot-renew timer
|
||||
become: true
|
||||
ansible.builtin.systemd:
|
||||
name: certbot-renew.timer
|
||||
state: restarted
|
||||
daemon_reload: true
|
||||
|
||||
tasks:
|
||||
- name: Check if host has certbot service
|
||||
ansible.builtin.set_fact:
|
||||
has_certbot_service: "{{ 'certbot' in services | default([]) }}"
|
||||
|
||||
- name: Skip hosts without certbot service
|
||||
ansible.builtin.meta: end_host
|
||||
when: not has_certbot_service
|
||||
|
||||
# -------------------------------------------------------------------------
|
||||
# System Setup
|
||||
# -------------------------------------------------------------------------
|
||||
|
||||
- name: Create certbot group
|
||||
become: true
|
||||
ansible.builtin.group:
|
||||
name: "{{ certbot_group }}"
|
||||
system: true
|
||||
|
||||
- name: Create certbot user
|
||||
become: true
|
||||
ansible.builtin.user:
|
||||
name: "{{ certbot_user }}"
|
||||
comment: "Certbot SSL Certificate Management"
|
||||
group: "{{ certbot_group }}"
|
||||
system: true
|
||||
shell: /usr/sbin/nologin
|
||||
home: "{{ certbot_directory }}"
|
||||
create_home: false
|
||||
|
||||
- name: Add ansible user to certbot group
|
||||
become: true
|
||||
ansible.builtin.user:
|
||||
name: "{{ ansible_user }}"
|
||||
groups: "{{ certbot_group }}"
|
||||
append: true
|
||||
|
||||
# -------------------------------------------------------------------------
|
||||
# Directory Structure
|
||||
# -------------------------------------------------------------------------
|
||||
|
||||
- name: Create certbot directories
|
||||
become: true
|
||||
ansible.builtin.file:
|
||||
path: "{{ item }}"
|
||||
owner: "{{ certbot_user }}"
|
||||
group: "{{ certbot_group }}"
|
||||
state: directory
|
||||
mode: '0750'
|
||||
loop:
|
||||
- "{{ certbot_directory }}"
|
||||
- "{{ certbot_directory }}/config"
|
||||
- "{{ certbot_directory }}/work"
|
||||
- "{{ certbot_directory }}/logs"
|
||||
- "{{ certbot_directory }}/credentials"
|
||||
- "{{ certbot_directory }}/hooks"
|
||||
|
||||
- name: Create haproxy group for certificate directory
|
||||
become: true
|
||||
ansible.builtin.group:
|
||||
name: "{{ haproxy_group | default('haproxy') }}"
|
||||
system: true
|
||||
|
||||
- name: Create haproxy user for certificate directory
|
||||
become: true
|
||||
ansible.builtin.user:
|
||||
name: "{{ haproxy_user | default('haproxy') }}"
|
||||
comment: "HAProxy Load Balancer"
|
||||
group: "{{ haproxy_group | default('haproxy') }}"
|
||||
system: true
|
||||
shell: /usr/sbin/nologin
|
||||
home: /nonexistent
|
||||
create_home: false
|
||||
|
||||
- name: Create certificate output directory
|
||||
become: true
|
||||
ansible.builtin.file:
|
||||
path: /etc/haproxy/certs
|
||||
owner: "{{ certbot_user }}"
|
||||
group: "{{ haproxy_group | default('haproxy') }}"
|
||||
state: directory
|
||||
mode: '0750'
|
||||
|
||||
# -------------------------------------------------------------------------
|
||||
# Python Virtual Environment
|
||||
# -------------------------------------------------------------------------
|
||||
|
||||
- name: Install Python venv package
|
||||
become: true
|
||||
ansible.builtin.apt:
|
||||
name:
|
||||
- python3-venv
|
||||
- python3-pip
|
||||
state: present
|
||||
update_cache: true
|
||||
|
||||
- name: Create virtual environment
|
||||
become: true
|
||||
become_user: "{{ certbot_user }}"
|
||||
ansible.builtin.command: python3 -m venv {{ certbot_directory }}/.venv
|
||||
args:
|
||||
creates: "{{ certbot_directory }}/.venv/bin/activate"
|
||||
vars:
|
||||
ansible_common_remote_group: "{{ certbot_group }}"
|
||||
allow_world_readable_tmpfiles: true
|
||||
|
||||
- name: Upgrade pip in virtualenv
|
||||
become: true
|
||||
become_user: "{{ certbot_user }}"
|
||||
ansible.builtin.pip:
|
||||
name: pip
|
||||
state: latest
|
||||
virtualenv: "{{ certbot_directory }}/.venv"
|
||||
vars:
|
||||
ansible_common_remote_group: "{{ certbot_group }}"
|
||||
allow_world_readable_tmpfiles: true
|
||||
|
||||
- name: Install certbot and Namecheap DNS plugin
|
||||
become: true
|
||||
become_user: "{{ certbot_user }}"
|
||||
ansible.builtin.pip:
|
||||
name:
|
||||
- certbot
|
||||
- certbot-dns-namecheap
|
||||
state: present
|
||||
virtualenv: "{{ certbot_directory }}/.venv"
|
||||
vars:
|
||||
ansible_common_remote_group: "{{ certbot_group }}"
|
||||
allow_world_readable_tmpfiles: true
|
||||
|
||||
# -------------------------------------------------------------------------
|
||||
# Namecheap Credentials
|
||||
# -------------------------------------------------------------------------
|
||||
|
||||
- name: Get public IP for Namecheap API
|
||||
ansible.builtin.uri:
|
||||
url: https://ifconfig.me/ip
|
||||
return_content: true
|
||||
register: public_ip_result
|
||||
delegate_to: localhost
|
||||
become: false
|
||||
|
||||
- name: Set client IP fact
|
||||
ansible.builtin.set_fact:
|
||||
namecheap_client_ip: "{{ public_ip_result.content | trim }}"
|
||||
|
||||
- name: Template Namecheap credentials
|
||||
become: true
|
||||
ansible.builtin.template:
|
||||
src: namecheap.ini.j2
|
||||
dest: "{{ certbot_directory }}/credentials/namecheap.ini"
|
||||
owner: "{{ certbot_user }}"
|
||||
group: "{{ certbot_group }}"
|
||||
mode: '0600'
|
||||
|
||||
# -------------------------------------------------------------------------
|
||||
# Renewal Hooks
|
||||
# -------------------------------------------------------------------------
|
||||
|
||||
- name: Template renewal hook script
|
||||
become: true
|
||||
ansible.builtin.template:
|
||||
src: renewal-hook.sh.j2
|
||||
dest: "{{ certbot_directory }}/hooks/renewal-hook.sh"
|
||||
owner: "{{ certbot_user }}"
|
||||
group: "{{ certbot_group }}"
|
||||
mode: '0750'
|
||||
|
||||
- name: Template certificate metrics script
|
||||
become: true
|
||||
ansible.builtin.template:
|
||||
src: cert-metrics.sh.j2
|
||||
dest: "{{ certbot_directory }}/hooks/cert-metrics.sh"
|
||||
owner: "{{ certbot_user }}"
|
||||
group: "{{ certbot_group }}"
|
||||
mode: '0750'
|
||||
|
||||
# -------------------------------------------------------------------------
|
||||
# Initial Certificate Request
|
||||
# -------------------------------------------------------------------------
|
||||
|
||||
- name: Check if certificate already exists
|
||||
become: true
|
||||
ansible.builtin.stat:
|
||||
path: "{{ certbot_directory }}/config/live/{{ certbot_cert_name }}/fullchain.pem"
|
||||
register: cert_exists
|
||||
|
||||
- name: Build domain arguments for certbot
|
||||
ansible.builtin.set_fact:
|
||||
certbot_domain_args: "{{ certbot_domains | map('regex_replace', '^', '-d ') | join(' ') }}"
|
||||
|
||||
- name: Request initial certificate
|
||||
become: true
|
||||
become_user: "{{ certbot_user }}"
|
||||
ansible.builtin.shell: |
|
||||
source {{ certbot_directory }}/.venv/bin/activate
|
||||
certbot certonly \
|
||||
--non-interactive \
|
||||
--agree-tos \
|
||||
--email {{ certbot_email }} \
|
||||
--authenticator dns-namecheap \
|
||||
--dns-namecheap-credentials {{ certbot_directory }}/credentials/namecheap.ini \
|
||||
--dns-namecheap-propagation-seconds 120 \
|
||||
--config-dir {{ certbot_directory }}/config \
|
||||
--work-dir {{ certbot_directory }}/work \
|
||||
--logs-dir {{ certbot_directory }}/logs \
|
||||
--cert-name {{ certbot_cert_name }} \
|
||||
{{ certbot_domain_args }}
|
||||
args:
|
||||
executable: /bin/bash
|
||||
when: not cert_exists.stat.exists
|
||||
register: certbot_request
|
||||
|
||||
- name: Run renewal hook after initial certificate
|
||||
become: true
|
||||
ansible.builtin.command: "{{ certbot_directory }}/hooks/renewal-hook.sh"
|
||||
when: certbot_request.changed
|
||||
|
||||
# -------------------------------------------------------------------------
|
||||
# Systemd Timer for Auto-Renewal
|
||||
# -------------------------------------------------------------------------
|
||||
|
||||
- name: Create certbot renewal service
|
||||
become: true
|
||||
ansible.builtin.copy:
|
||||
content: |
|
||||
[Unit]
|
||||
Description=Certbot Renewal
|
||||
After=network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
User={{ certbot_user }}
|
||||
Group={{ certbot_group }}
|
||||
ExecStart=/bin/bash -c 'source {{ certbot_directory }}/.venv/bin/activate && certbot renew --config-dir {{ certbot_directory }}/config --work-dir {{ certbot_directory }}/work --logs-dir {{ certbot_directory }}/logs --deploy-hook {{ certbot_directory }}/hooks/renewal-hook.sh'
|
||||
PrivateTmp=true
|
||||
dest: /etc/systemd/system/certbot-renew.service
|
||||
mode: '0644'
|
||||
notify: restart certbot-renew timer
|
||||
|
||||
- name: Create certbot renewal timer
|
||||
become: true
|
||||
ansible.builtin.copy:
|
||||
content: |
|
||||
[Unit]
|
||||
Description=Run certbot renewal twice daily
|
||||
|
||||
[Timer]
|
||||
OnCalendar=*-*-* 00,12:00:00
|
||||
RandomizedDelaySec=3600
|
||||
Persistent=true
|
||||
|
||||
[Install]
|
||||
WantedBy=timers.target
|
||||
dest: /etc/systemd/system/certbot-renew.timer
|
||||
mode: '0644'
|
||||
notify: restart certbot-renew timer
|
||||
|
||||
- name: Enable and start certbot renewal timer
|
||||
become: true
|
||||
ansible.builtin.systemd:
|
||||
name: certbot-renew.timer
|
||||
enabled: true
|
||||
state: started
|
||||
daemon_reload: true
|
||||
|
||||
# -------------------------------------------------------------------------
|
||||
# Initial Metrics Update
|
||||
# -------------------------------------------------------------------------
|
||||
|
||||
- name: Ensure prometheus textfile directory exists
|
||||
become: true
|
||||
ansible.builtin.file:
|
||||
path: "{{ prometheus_node_exporter_text_directory }}"
|
||||
state: directory
|
||||
owner: prometheus
|
||||
group: prometheus
|
||||
mode: '0755'
|
||||
|
||||
- name: Run certificate metrics script
|
||||
become: true
|
||||
ansible.builtin.command: "{{ certbot_directory }}/hooks/cert-metrics.sh"
|
||||
changed_when: false
|
||||
|
||||
# -------------------------------------------------------------------------
|
||||
# Verification
|
||||
# -------------------------------------------------------------------------
|
||||
|
||||
- name: Verify certificate exists
|
||||
become: true
|
||||
ansible.builtin.stat:
|
||||
path: "{{ haproxy_cert_path }}"
|
||||
register: final_cert
|
||||
|
||||
- name: Certificate deployment status
|
||||
ansible.builtin.debug:
|
||||
msg: "Certificate deployed: {{ final_cert.stat.exists }}"
|
||||
8
ansible/certbot/namecheap.ini.j2
Normal file
8
ansible/certbot/namecheap.ini.j2
Normal file
@@ -0,0 +1,8 @@
|
||||
# Namecheap API credentials for certbot DNS-01 validation
|
||||
# Managed by Ansible - DO NOT EDIT MANUALLY
|
||||
|
||||
dns_namecheap_username = {{ namecheap_username }}
|
||||
dns_namecheap_api_key = {{ namecheap_api_key }}
|
||||
{% if namecheap_client_ip is defined %}
|
||||
dns_namecheap_client_ip = {{ namecheap_client_ip }}
|
||||
{% endif %}
|
||||
52
ansible/certbot/renewal-hook.sh.j2
Normal file
52
ansible/certbot/renewal-hook.sh.j2
Normal file
@@ -0,0 +1,52 @@
|
||||
#!/bin/bash
|
||||
# Certbot post-renewal hook for HAProxy
|
||||
# Managed by Ansible - DO NOT EDIT MANUALLY
|
||||
#
|
||||
# This script:
|
||||
# 1. Combines fullchain.pem + privkey.pem into HAProxy format
|
||||
# 2. Sets correct permissions
|
||||
# 3. Reloads HAProxy via Docker
|
||||
# 4. Updates certificate metrics for Prometheus
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
CERT_NAME="{{ certbot_cert_name }}"
|
||||
CERT_DIR="{{ certbot_directory }}/config/live/${CERT_NAME}"
|
||||
HAPROXY_CERT="{{ haproxy_cert_path }}"
|
||||
HAPROXY_DIR="{{ haproxy_directory }}"
|
||||
|
||||
echo "[$(date '+%Y-%m-%d %H:%M:%S')] Starting renewal hook for ${CERT_NAME}"
|
||||
|
||||
# Check if certificate files exist
|
||||
if [[ ! -f "${CERT_DIR}/fullchain.pem" ]] || [[ ! -f "${CERT_DIR}/privkey.pem" ]]; then
|
||||
echo "ERROR: Certificate files not found in ${CERT_DIR}"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Combine certificate and private key for HAProxy
|
||||
# HAProxy requires both in a single PEM file
|
||||
cat "${CERT_DIR}/fullchain.pem" "${CERT_DIR}/privkey.pem" > "${HAPROXY_CERT}.tmp"
|
||||
|
||||
# Atomic move to avoid HAProxy reading partial file
|
||||
mv "${HAPROXY_CERT}.tmp" "${HAPROXY_CERT}"
|
||||
|
||||
# Set permissions
|
||||
chown {{ certbot_user }}:{{ haproxy_group }} "${HAPROXY_CERT}"
|
||||
chmod 640 "${HAPROXY_CERT}"
|
||||
|
||||
echo "[$(date '+%Y-%m-%d %H:%M:%S')] Certificate combined and written to ${HAPROXY_CERT}"
|
||||
|
||||
# Reload HAProxy if running
|
||||
if docker ps --format '{{ '{{' }}.Names{{ '}}' }}' | grep -q haproxy; then
|
||||
echo "[$(date '+%Y-%m-%d %H:%M:%S')] Reloading HAProxy..."
|
||||
cd "${HAPROXY_DIR}"
|
||||
docker compose kill -s HUP haproxy || docker-compose kill -s HUP haproxy
|
||||
echo "[$(date '+%Y-%m-%d %H:%M:%S')] HAProxy reloaded"
|
||||
else
|
||||
echo "[$(date '+%Y-%m-%d %H:%M:%S')] HAProxy not running, skipping reload"
|
||||
fi
|
||||
|
||||
# Update certificate metrics
|
||||
{{ certbot_directory }}/hooks/cert-metrics.sh
|
||||
|
||||
echo "[$(date '+%Y-%m-%d %H:%M:%S')] Renewal hook completed successfully"
|
||||
Reference in New Issue
Block a user