|
| 1 | +# nginx SSL Proxy Setup for Ansible Automation Platform |
| 2 | + |
| 3 | +## Table of Contents |
| 4 | + |
| 5 | +1. [Overview](#overview) |
| 6 | +2. [Architecture Explanation](#architecture-explanation) |
| 7 | +3. [How the Setup Works](#how-the-setup-works) |
| 8 | +4. [Port Configuration Discovery](#port-configuration-discovery) |
| 9 | +5. [The nginx Proxy Solution](#the-nginx-proxy-solution) |
| 10 | +6. [Traffic Flow](#traffic-flow) |
| 11 | +7. [Why This Approach](#why-this-approach) |
| 12 | +8. [Key Configuration Files](#key-configuration-files) |
| 13 | + |
| 14 | +## Overview |
| 15 | + |
| 16 | +This document explains how the `issue_cert` role implements SSL certificates for Ansible Automation Platform (AAP) workshops **without modifying AAP itself**. Instead of reconfiguring AAP's SSL certificates (which would require re-running the entire installer), this solution installs a **separate nginx instance** that acts as an SSL-terminating reverse proxy. |
| 17 | + |
| 18 | +## Architecture Explanation |
| 19 | + |
| 20 | +**Important**: This setup does **NOT** modify AAP's configuration or install nginx "into" AAP. Instead, it: |
| 21 | + |
| 22 | +1. **Installs a standalone nginx service** on the same host as AAP |
| 23 | +2. **Configures nginx as a reverse proxy** with SSL termination |
| 24 | +3. **Leaves AAP completely unchanged** - AAP continues running on its original port with its original configuration |
| 25 | + |
| 26 | +## How the Setup Works |
| 27 | + |
| 28 | +### AAP Installation (Pre-built in AMI) |
| 29 | +- AAP is installed during the Packer AMI build process |
| 30 | +- The `extra_vars.yml` file specifies `aap_port: 8501` |
| 31 | +- AAP's envoy gateway is configured to listen on port 8501 instead of the default 443 |
| 32 | +- AAP runs with its own self-signed certificates on port 8501 |
| 33 | + |
| 34 | +### SSL Certificate Solution (During Workshop Provisioning) |
| 35 | +- The `issue_cert` role installs a **separate nginx instance** |
| 36 | +- nginx obtains proper SSL certificates from Let's Encrypt |
| 37 | +- nginx is configured to listen on port 443 (the standard HTTPS port) |
| 38 | +- nginx proxies all traffic to AAP running on localhost:8501 |
| 39 | + |
| 40 | +## Port Configuration Discovery |
| 41 | + |
| 42 | +The mystery of port 8501 is solved by examining the Packer build configuration: |
| 43 | + |
| 44 | +**File: `/provisioner/packer/extra_vars.yml`** |
| 45 | +```yaml |
| 46 | +aap_port: 8501 |
| 47 | +``` |
| 48 | +
|
| 49 | +This variable is used during AMI creation, causing AAP to be installed with: |
| 50 | +```yaml |
| 51 | +envoy_https_port: 8501 # Instead of default 443 |
| 52 | +``` |
| 53 | +
|
| 54 | +## The nginx Proxy Solution |
| 55 | +
|
| 56 | +### nginx Installation and Configuration |
| 57 | +
|
| 58 | +The `issue_cert` role performs these steps: |
| 59 | + |
| 60 | +1. **Installs nginx** (separate from AAP) |
| 61 | +```yaml |
| 62 | +- name: Make sure nginx and certbot are installed |
| 63 | + ansible.builtin.dnf: |
| 64 | + name: |
| 65 | + - nginx |
| 66 | + - certbot |
| 67 | +``` |
| 68 | + |
| 69 | +2. **Obtains SSL certificates** from Let's Encrypt |
| 70 | +```yaml |
| 71 | +- name: Issue SSL cert |
| 72 | + ansible.builtin.shell: certbot certonly --standalone -d {{ dns_name }} |
| 73 | +``` |
| 74 | + |
| 75 | +3. **Configures nginx as SSL proxy** |
| 76 | +```nginx |
| 77 | +# HTTPS server block |
| 78 | +server { |
| 79 | + listen 443 ssl; |
| 80 | + server_name {{ dns_name }}; |
| 81 | +
|
| 82 | + # SSL certificates from Let's Encrypt |
| 83 | + ssl_certificate /etc/nginx/ssl/aap.crt; |
| 84 | + ssl_certificate_key /etc/nginx/ssl/aap.key; |
| 85 | +
|
| 86 | + # Proxy all traffic to AAP |
| 87 | + location / { |
| 88 | + proxy_pass https://127.0.0.1:8501; |
| 89 | + proxy_ssl_verify off; |
| 90 | + # ... additional proxy headers |
| 91 | + } |
| 92 | +} |
| 93 | +``` |
| 94 | + |
| 95 | +## Traffic Flow |
| 96 | + |
| 97 | +``` |
| 98 | +Internet Request (HTTPS:443) |
| 99 | + ↓ |
| 100 | +nginx (Port 443) - SSL Termination with Let's Encrypt Certs |
| 101 | + ↓ |
| 102 | +Proxy Pass to AAP (localhost:8501) - Original AAP with Self-Signed Certs |
| 103 | + ↓ |
| 104 | +AAP Response back through nginx |
| 105 | + ↓ |
| 106 | +Encrypted Response to Client |
| 107 | +``` |
| 108 | +
|
| 109 | +## Why This Approach |
| 110 | +
|
| 111 | +### Advantages: |
| 112 | +1. **No AAP Modification**: AAP installation remains completely untouched |
| 113 | +2. **No Installer Re-run**: Avoids the time and complexity of reconfiguring AAP |
| 114 | +3. **Proper SSL Certificates**: Uses Let's Encrypt for trusted certificates |
| 115 | +4. **Clean Separation**: nginx handles SSL, AAP handles application logic |
| 116 | +5. **Easy Maintenance**: SSL certificate renewal happens independently of AAP |
| 117 | +
|
| 118 | +### Alternative Approaches (Not Used): |
| 119 | +- **Modifying AAP SSL**: Would require re-running the AAP installer with new certificate paths |
| 120 | +- **Direct Certificate Replacement**: Would require stopping AAP services and complex certificate management |
| 121 | +
|
| 122 | +## Key Configuration Files |
| 123 | +
|
| 124 | +### 1. Packer Build Configuration |
| 125 | +**File**: `provisioner/packer/extra_vars.yml` |
| 126 | +```yaml |
| 127 | +aap_port: 8501 # Forces AAP to use port 8501 during AMI build |
| 128 | +``` |
| 129 | + |
| 130 | +### 2. AAP Installation Template |
| 131 | +**File**: `roles/control_node/templates/controller_install.j2` |
| 132 | +```ini |
| 133 | +envoy_https_port={{ aap_port | default('443') | int }} |
| 134 | +``` |
| 135 | + |
| 136 | +### 3. nginx Configuration Template |
| 137 | +**File**: `roles/issue_cert/templates/nginx.conf.j2` |
| 138 | +```nginx |
| 139 | +server { |
| 140 | + listen 443 ssl; |
| 141 | + location / { |
| 142 | + proxy_pass https://127.0.0.1:8501; # Proxy to AAP |
| 143 | + } |
| 144 | +} |
| 145 | +``` |
| 146 | + |
| 147 | +### 4. Security Group Rules |
| 148 | +**File**: `provisioner/group_vars/all/vpc_rules.yml` |
| 149 | +```yaml |
| 150 | +- proto: tcp |
| 151 | + to_port: 8501 |
| 152 | + from_port: 8501 |
| 153 | + cidr_ip: 0.0.0.0/0 |
| 154 | + rule_desc: receptor # AAP internal port |
| 155 | +``` |
| 156 | +
|
| 157 | +--- |
| 158 | +
|
| 159 | +**Summary**: This is an elegant solution that provides proper SSL certificates for workshop participants without the complexity and time required to modify AAP's native SSL configuration. The separate nginx proxy handles all SSL concerns while AAP continues running unchanged on its internal port. |
0 commit comments