Skip to content

Commit 3f1b26f

Browse files
gablyu-ocigablyu-oci
committed
Update Ingress README
1 parent a7f2c57 commit 3f1b26f

File tree

3 files changed

+164
-140
lines changed

3 files changed

+164
-140
lines changed

‎INGRESS_AND_TLS_SETUP.md‎

Lines changed: 153 additions & 139 deletions
Original file line numberDiff line numberDiff line change
@@ -1,223 +1,237 @@
1-
# Ingress and TLS Setup Prerequisites
1+
# Ingress and TLS Setup Guide
22

3-
This guide covers the ingress and TLS prerequisites for the Corrino Lens Helm chart installation. The chart automatically installs **ingress-nginx**, **cert-manager**, and configures **Let's Encrypt** for TLS certificates.
3+
This guide covers ingress and TLS prerequisites for Corrino Lens Helm chart installation.
44

55
## Overview
66

7-
The Corrino Lens Helm chart automatically installs and configures:
7+
The Helm chart automatically installs as dependencies:
8+
- **ingress-nginx** (v4.13.2) - Kubernetes Ingress Controller in `lens` namespace
9+
- **cert-manager** (v1.13.2) - TLS certificate management in `lens` namespace
10+
- **Let's Encrypt ClusterIssuer** - Production ACME certificates (cluster-wide)
11+
- **IngressClass** `lens-nginx` (cluster-wide)
812

9-
1. **ingress-nginx** (v4.13.2) - Kubernetes Ingress Controller
10-
2. **cert-manager** (v1.13.2) - Automated TLS certificate management
11-
3. **Let's Encrypt ClusterIssuer** - Production ACME certificates
13+
**Architecture:**
14+
```
15+
Internet → [LoadBalancer] → [ingress-nginx] → [Ingress] → [Apps]
16+
```
1217

13-
**Important:** These components are **always installed** as Helm subchart dependencies and cannot currently be disabled. Customizable options are coming soon in the future release!
18+
**Important:** Deleting the `lens` namespace is safe and removes all namespace-scoped resources. Only delete cluster-wide resources (IngressClass, ClusterIssuer, CRDs) if certain no other applications use them.
1419

15-
### Architecture
20+
---
1621

17-
```
18-
Internet → [LoadBalancer Service] → [ingress-nginx Controller] → [Ingress Resources] → [Application Services]
19-
```
22+
## Pre-Install Check
2023

21-
### Components Created
24+
Check for existing resources before installation:
2225

23-
| Component | Namespace | Purpose |
24-
|-----------|-----------|---------|
25-
| ingress-nginx controller | `ingress-nginx` | Routes traffic based on hostnames |
26-
| cert-manager | `cert-manager` | Manages TLS certificates |
27-
| Let's Encrypt ClusterIssuer | cluster-wide | Issues production TLS certificates |
28-
| Application Ingresses | `lens` | Backend, Frontend, Grafana, Prometheus |
26+
```bash
27+
# Check if lens namespace exists
28+
kubectl get ns lens 2>&1
29+
30+
# Check for existing pods in lens namespace
31+
kubectl get pods -n lens 2>&1
32+
33+
# Check cluster-wide resources
34+
kubectl get ingressclass lens-nginx 2>&1
35+
kubectl get clusterissuer letsencrypt-prod 2>&1
36+
kubectl get crd | grep cert-manager
37+
```
38+
39+
**If any resources exist from a previous installation, proceed to cleanup.**
2940

3041
---
3142

32-
## Pre-Installation: Check and Clean Up Existing Infrastructure
43+
## Clean Up if Exists
3344

34-
**Before installing**, check if ingress-nginx or cert-manager already exist in your cluster. Conflicts will cause installation failures.
45+
### Option 1: Safe Cleanup (Recommended)
3546

36-
### Step 1: Check for Existing Infrastructure
47+
Removes only the `lens` namespace, preserving cluster-wide resources:
3748

3849
```bash
39-
# Check for existing namespaces
40-
kubectl get namespace ingress-nginx cert-manager
41-
42-
# Check for existing IngressClass
43-
kubectl get ingressclass nginx
50+
# Uninstall Helm release
51+
helm uninstall lens -n lens
4452

45-
# Check for existing cert-manager CRDs
46-
kubectl get crd | grep cert-manager
53+
# Delete namespace (removes all namespace-scoped resources)
54+
kubectl delete namespace lens
4755

48-
# Check for existing ClusterIssuer
49-
kubectl get clusterissuer letsencrypt-prod
56+
# Wait for deletion to complete
57+
kubectl wait --for=delete namespace/lens --timeout=120s 2>/dev/null || echo "Namespace deleted"
58+
```
5059

51-
# Check for any running ingress controllers
52-
kubectl get pods -A | grep ingress
53-
kubectl get pods -n cert-manager
60+
**Verification:**
61+
```bash
62+
kubectl get namespace lens 2>&1 | grep "NotFound" && echo "✅ Ready for install" || echo "❌ Namespace still exists"
5463
```
5564

56-
### Step 2: Clean Up if Infrastructure Exists
65+
### Option 2: Complete Cleanup (Fresh Cluster Only)
5766

58-
If any of the above commands return existing resources, **you must clean them up**:
67+
⚠️ **Use only if no other applications use cert-manager or ingress-nginx**
5968

6069
```bash
61-
# 1. Find and uninstall existing Helm releases
62-
helm ls -A # Find any ingress-nginx or cert-manager releases
63-
helm uninstall <release-name> -n <namespace>
70+
# 1. Uninstall Helm release and namespace
71+
helm uninstall lens -n lens
72+
kubectl delete namespace lens
73+
kubectl wait --for=delete namespace/lens --timeout=120s 2>/dev/null
6474

65-
# 2. Delete infrastructure namespaces
66-
kubectl delete namespace ingress-nginx cert-manager
75+
# 2. Verify no other apps are using these resources
76+
kubectl get certificate --all-namespaces
77+
kubectl get ingress --all-namespaces
6778

68-
# 3. Delete cert-manager CRDs (not automatically removed by Helm)
69-
kubectl get crd | grep cert-manager | awk '{print $1}' | xargs kubectl delete crd
79+
# 3. Delete cluster-wide resources (if safe)
80+
kubectl delete clusterissuer letsencrypt-prod --ignore-not-found
81+
kubectl delete ingressclass lens-nginx --ignore-not-found
7082

71-
# 4. Delete cluster-wide resources
72-
kubectl delete clusterissuer letsencrypt-prod --ignore-not-found=true
73-
kubectl delete ingressclass nginx --ignore-not-found=true
83+
# 4. Delete cert-manager CRDs (affects entire cluster!)
84+
kubectl get crd | grep cert-manager | awk '{print $1}' | xargs kubectl delete crd --ignore-not-found
7485

7586
# 5. Delete webhook configurations
76-
kubectl delete validatingwebhookconfiguration -l app.kubernetes.io/instance=cert-manager --ignore-not-found=true
77-
kubectl delete mutatingwebhookconfiguration -l app.kubernetes.io/instance=cert-manager --ignore-not-found=true
78-
87+
kubectl delete validatingwebhookconfiguration -l app.kubernetes.io/instance=lens --ignore-not-found
88+
kubectl delete mutatingwebhookconfiguration -l app.kubernetes.io/instance=lens --ignore-not-found
7989
```
8090

81-
### Step 3: Verify Clean State
82-
83-
Before proceeding with installation, verify everything is cleaned up:
84-
91+
**Verification:**
8592
```bash
86-
# All of these should return "NotFound" or no results:
87-
kubectl get namespace ingress-nginx cert-manager 2>&1 | grep "NotFound"
88-
kubectl get ingressclass nginx 2>&1 | grep "NotFound"
89-
kubectl get crd | grep cert-manager # Should return nothing
90-
kubectl get clusterissuer letsencrypt-prod 2>&1 | grep "NotFound"
93+
kubectl get namespace lens 2>&1 | grep "NotFound"
94+
kubectl get ingressclass lens-nginx 2>&1 | grep "NotFound"
95+
kubectl get crd | grep cert-manager || echo "No cert-manager CRDs"
9196
```
9297

93-
✅ If verification passes, you're ready to proceed with the Helm installation!
94-
9598
---
9699

97-
## Post-Installation: Verification
100+
## Post-Install Check
98101

99-
After installing the Helm chart, verify all components are running correctly:
100-
101-
### Check Infrastructure Components
102+
After helm installation, verify all components are running:
102103

103104
```bash
104-
# Verify all namespaces exist
105-
kubectl get namespace lens ingress-nginx cert-manager
105+
# 1. Verify namespace and pods
106+
kubectl get namespace lens
107+
kubectl get pods -n lens
106108

107-
# Verify controllers are running
108-
kubectl get pods -n ingress-nginx
109-
kubectl get pods -n cert-manager
109+
# 2. Check ingress-nginx and cert-manager are running
110+
kubectl get pods -n lens | grep -E 'ingress|cert-manager'
110111

111-
# Check IngressClass
112-
kubectl get ingressclass nginx
112+
# 3. Get LoadBalancer external IP (may take 1-2 minutes)
113+
kubectl get svc -n lens -l app.kubernetes.io/component=controller
113114

114-
# Check ClusterIssuer is ready
115+
# 4. Check cluster-wide resources
116+
kubectl get ingressclass lens-nginx
115117
kubectl get clusterissuer letsencrypt-prod
116-
```
117118

118-
### Check LoadBalancer
119-
120-
```bash
121-
# Get external IP (wait if showing <pending>)
122-
kubectl get svc -n ingress-nginx -l app.kubernetes.io/component=controller
119+
# 5. View all ingress endpoints
120+
kubectl get ingress -n lens
123121

124-
# Save external IP for later use
125-
EXTERNAL_IP=$(kubectl get svc -n ingress-nginx -l app.kubernetes.io/component=controller -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
126-
echo "External IP: $EXTERNAL_IP"
122+
# 6. Check TLS certificates (should show READY=True after 2-5 minutes)
123+
kubectl get certificate -n lens
127124
```
128125

129-
### Check Ingress Resources
126+
**Expected output:**
127+
- All pods in `Running` state
128+
- LoadBalancer service has an `EXTERNAL-IP`
129+
- Certificates show `READY=True`
130+
- Ingress resources show correct hosts
130131

132+
**If certificates not ready:**
131133
```bash
132-
# View all ingress resources
133-
kubectl get ingress -n lens
134-
135-
# Check specific ingress details
136-
kubectl describe ingress lens-backend-ingress -n lens
137-
kubectl describe ingress lens-frontend-ingress -n lens
134+
# Check certificate details and challenges
135+
kubectl describe certificate -n lens
136+
kubectl get challenge -n lens
137+
kubectl logs -n lens -l app=cert-manager --tail=50
138138
```
139139

140-
### Check TLS Certificates
140+
---
141141

142-
```bash
143-
# View certificate status (should show READY=True)
144-
kubectl get certificate -n lens
142+
## Complete Uninstall
145143

146-
# Check certificate details
147-
kubectl describe certificate lens-backend-tls -n lens
148-
kubectl describe certificate lens-frontend-tls -n lens
144+
### Standard Uninstall (Preserves Cluster-Wide Resources)
149145

150-
# If certificates not ready, check requests and challenges
151-
kubectl get certificaterequest -n lens
152-
kubectl get challenge -n lens
146+
```bash
147+
helm uninstall lens -n lens
148+
kubectl delete namespace lens
153149
```
154150

155-
## Quick Reference
151+
### Full Uninstall (Removes Everything)
156152

157-
### View All Resources
158-
```bash
159-
kubectl get namespace ingress-nginx cert-manager lens
160-
kubectl get ingressclass
161-
kubectl get clusterissuer
162-
kubectl get pods -n ingress-nginx
163-
kubectl get pods -n cert-manager
164-
kubectl get certificate,certificaterequest,ingress -n lens
165-
```
153+
⚠️ **Only use on dedicated test clusters**
166154

167-
### Get External IP
168155
```bash
169-
kubectl get svc -n ingress-nginx -l app.kubernetes.io/component=controller
170-
```
156+
# 1. Uninstall Helm release
157+
helm uninstall lens -n lens
171158

172-
### View Logs
173-
```bash
174-
kubectl logs -n ingress-nginx -l app.kubernetes.io/component=controller --tail=100
175-
kubectl logs -n cert-manager -l app=cert-manager --tail=100
176-
kubectl logs -n cert-manager -l app=webhook --tail=100
159+
# 2. Delete namespace
160+
kubectl delete namespace lens
161+
162+
# 3. Wait for namespace deletion
163+
kubectl wait --for=delete namespace/lens --timeout=120s 2>/dev/null
164+
165+
# 4. Delete cluster-wide resources
166+
kubectl delete clusterissuer letsencrypt-prod --ignore-not-found
167+
kubectl delete ingressclass lens-nginx --ignore-not-found
168+
169+
# 5. Delete cert-manager CRDs
170+
kubectl get crd | grep cert-manager | awk '{print $1}' | xargs kubectl delete crd --ignore-not-found
171+
172+
# 6. Delete webhook configurations
173+
kubectl delete validatingwebhookconfiguration -l app.kubernetes.io/instance=lens --ignore-not-found
174+
kubectl delete mutatingwebhookconfiguration -l app.kubernetes.io/instance=lens --ignore-not-found
177175
```
178176

179-
### Force Certificate Renewal
177+
**Verify complete removal:**
180178
```bash
181-
kubectl delete certificate <cert-name> -n lens
182-
# cert-manager will automatically recreate it
179+
kubectl get all -n lens 2>&1 | grep "NotFound" && echo "✅ Complete uninstall successful"
183180
```
184181

185182
---
186183

187-
## Complete Cleanup
184+
## Troubleshooting
188185

189-
To completely remove ingress and TLS infrastructure:
186+
### Namespace Stuck in "Terminating"
187+
```bash
188+
# Check what's blocking deletion
189+
kubectl get all -n lens
190+
kubectl get certificate -n lens
191+
192+
# Force remove finalizers (use with caution)
193+
kubectl get namespace lens -o json | jq '.spec.finalizers = []' | kubectl replace --raw /api/v1/namespaces/lens/finalize -f -
194+
```
190195

196+
### Certificates Not Getting Issued
191197
```bash
192-
# 1. Uninstall Helm release
193-
helm uninstall lens -n lens
198+
# Check status and challenges
199+
kubectl describe certificate -n lens
200+
kubectl get challenge -n lens
201+
202+
# Check cert-manager logs
203+
kubectl logs -n lens -l app=cert-manager -f
194204

195-
# 2. Delete all namespaces
196-
kubectl delete namespace lens ingress-nginx cert-manager
205+
# Common causes:
206+
# - DNS not pointing to LoadBalancer IP
207+
# - Firewall blocking port 80/443 from internet
208+
# - Let's Encrypt rate limits exceeded
209+
```
197210

198-
# 3. Delete cert-manager CRDs
199-
kubectl get crd | grep cert-manager | awk '{print $1}' | xargs kubectl delete crd
211+
### IngressClass or ClusterIssuer Already Exists
212+
```bash
213+
# Check if from previous lens installation
214+
kubectl get ingressclass lens-nginx -o yaml | grep app.kubernetes.io/instance
200215

201-
# 4. Delete cluster-wide resources
202-
kubectl delete clusterissuer letsencrypt-prod --ignore-not-found=true
203-
kubectl delete ingressclass nginx --ignore-not-found=true
216+
# Delete if from previous lens install
217+
kubectl delete ingressclass lens-nginx
218+
kubectl delete clusterissuer letsencrypt-prod
219+
```
204220

205-
# 5. Delete webhooks
206-
kubectl delete validatingwebhookconfiguration -l app.kubernetes.io/instance=lens --ignore-not-found=true
207-
kubectl delete mutatingwebhookconfiguration -l app.kubernetes.io/instance=lens --ignore-not-found=true
221+
### Check if Other Apps Use Resources
222+
```bash
223+
# List all ingress and certificates across cluster
224+
kubectl get ingress --all-namespaces
225+
kubectl get certificate --all-namespaces
208226

209-
# 6. If namespaces stuck in Terminating state
210-
kubectl patch namespace cert-manager -p '{"metadata":{"finalizers":[]}}' --type=merge
211-
kubectl patch namespace ingress-nginx -p '{"metadata":{"finalizers":[]}}' --type=merge
227+
# If only lens namespace appears, safe to delete cluster-wide resources
212228
```
229+
213230
---
214231

215232
## Additional Resources
216233

217234
- **ingress-nginx**: https://kubernetes.github.io/ingress-nginx/
218235
- **cert-manager**: https://cert-manager.io/docs/
219236
- **Let's Encrypt**: https://letsencrypt.org/docs/
220-
221-
**Report Issues:**
222-
- GitHub: https://github.com/oci-ai-incubations/corrino-lens-devops
223-
237+
- **Report Issues**: https://github.com/oci-ai-incubations/corrino-lens-devops

‎oci_lens_terraform/modules/app/main.tf‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -96,7 +96,7 @@ data "kubernetes_ingress_v1" "prometheus_ingress" {
9696
data "kubernetes_service_v1" "ingress_nginx_controller" {
9797
metadata {
9898
name = "ingress-nginx-controller"
99-
namespace = "ingress-nginx"
99+
namespace = kubernetes_namespace.ns.metadata[0].name
100100
}
101101
depends_on = [helm_release.app]
102102
}

‎oci_lens_terraform/modules/app/outputs.tf‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,3 +61,13 @@ output "prometheus_ingress_host" {
6161
description = "The ingress host for Prometheus"
6262
value = try(data.kubernetes_ingress_v1.prometheus_ingress.spec[0].rule[0].host, "")
6363
}
64+
65+
output "ingress_nginx_loadbalancer_ip" {
66+
description = "The external LoadBalancer IP for the ingress-nginx controller"
67+
value = try(data.kubernetes_service_v1.ingress_nginx_controller.status[0].load_balancer[0].ingress[0].ip, "")
68+
}
69+
70+
output "ingress_nginx_loadbalancer_hostname" {
71+
description = "The external LoadBalancer hostname for the ingress-nginx controller"
72+
value = try(data.kubernetes_service_v1.ingress_nginx_controller.status[0].load_balancer[0].ingress[0].hostname, "")
73+
}

0 commit comments

Comments
 (0)