Skip to content

Commit aa87c53

Browse files
IPvSeanIPvSean
committed
Create nginx-ssl-proxy-explanation.md
1 parent 43e6c9b commit aa87c53

1 file changed

Lines changed: 159 additions & 0 deletions

File tree

‎nginx-ssl-proxy-explanation.md‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
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

Comments
 (0)