[INFRA-006] infra: Set up SSL/TLS certificates
This commit is contained in:
senke
parent
f989499039
commit
efbb574877
6 changed files with 385 additions and 3 deletions
|
|
@ -11386,8 +11386,14 @@
|
|||
"description": "Configure SSL/TLS with Let's Encrypt or similar",
|
||||
"owner": "devops",
|
||||
"estimated_hours": 3,
|
||||
"status": "todo",
|
||||
"files_involved": [],
|
||||
"status": "completed",
|
||||
"files_involved": [
|
||||
"k8s/certificates/cert-manager-install.yaml",
|
||||
"k8s/certificates/letsencrypt-issuer.yaml",
|
||||
"k8s/certificates/certificate-example.yaml",
|
||||
"k8s/certificates/README.md",
|
||||
"k8s/ingress.yaml"
|
||||
],
|
||||
"implementation_steps": [
|
||||
{
|
||||
"step": 1,
|
||||
|
|
@ -11407,7 +11413,16 @@
|
|||
"Unit tests",
|
||||
"Integration tests"
|
||||
],
|
||||
"notes": ""
|
||||
"notes": "",
|
||||
"completed_at": "2025-12-25T21:34:38.397475",
|
||||
"validation": {
|
||||
"yaml_syntax": "All manifests validated",
|
||||
"cert_manager": "Kubernetes manifests for cert-manager and Lets Encrypt",
|
||||
"cluster_issuers": "Production and staging ClusterIssuers configured",
|
||||
"ingress_updated": "Enhanced with SSL/TLS security headers and cipher suites",
|
||||
"features": "Automatic certificate issuance, renewal, HTTP-01 challenge support",
|
||||
"documentation": "k8s/certificates/README.md with installation and troubleshooting instructions"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "INFRA-007",
|
||||
|
|
|
|||
272
k8s/certificates/README.md
Normal file
272
k8s/certificates/README.md
Normal file
|
|
@ -0,0 +1,272 @@
|
|||
# SSL/TLS Certificate Management
|
||||
|
||||
This directory contains Kubernetes manifests for managing SSL/TLS certificates using cert-manager and Let's Encrypt.
|
||||
|
||||
## Components
|
||||
|
||||
### cert-manager
|
||||
- **Purpose**: Automated certificate management
|
||||
- **Namespace**: cert-manager
|
||||
- **Installation**: Via official cert-manager release
|
||||
|
||||
### ClusterIssuers
|
||||
- **letsencrypt-prod**: Production Let's Encrypt issuer
|
||||
- **letsencrypt-staging**: Staging Let's Encrypt issuer (for testing)
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. **Kubernetes cluster** with ingress controller (nginx-ingress recommended)
|
||||
2. **cert-manager** installed in the cluster
|
||||
3. **DNS records** pointing to your ingress controller
|
||||
4. **Ingress controller** with HTTP-01 challenge support
|
||||
|
||||
## Installation
|
||||
|
||||
### 1. Install cert-manager
|
||||
|
||||
```bash
|
||||
# Install cert-manager CRDs
|
||||
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.crds.yaml
|
||||
|
||||
# Install cert-manager
|
||||
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml
|
||||
|
||||
# Or using Helm
|
||||
helm repo add jetstack https://charts.jetstack.io
|
||||
helm repo update
|
||||
helm install cert-manager jetstack/cert-manager \
|
||||
--namespace cert-manager \
|
||||
--create-namespace \
|
||||
--set installCRDs=true
|
||||
```
|
||||
|
||||
### 2. Verify cert-manager Installation
|
||||
|
||||
```bash
|
||||
# Check cert-manager pods
|
||||
kubectl get pods -n cert-manager
|
||||
|
||||
# Check ClusterIssuers
|
||||
kubectl get clusterissuers
|
||||
```
|
||||
|
||||
### 3. Configure Let's Encrypt Issuers
|
||||
|
||||
**Important**: Update the email address in `letsencrypt-issuer.yaml`:
|
||||
|
||||
```yaml
|
||||
email: ops@veza.com # Change to your email
|
||||
```
|
||||
|
||||
Then apply:
|
||||
|
||||
```bash
|
||||
kubectl apply -f k8s/certificates/letsencrypt-issuer.yaml
|
||||
```
|
||||
|
||||
### 4. Verify ClusterIssuers
|
||||
|
||||
```bash
|
||||
# Check ClusterIssuers status
|
||||
kubectl get clusterissuers
|
||||
|
||||
# Describe to see details
|
||||
kubectl describe clusterissuer letsencrypt-prod
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Automatic Certificate via Ingress
|
||||
|
||||
The easiest way is to use Ingress annotations. The ingress is already configured in `k8s/ingress.yaml`:
|
||||
|
||||
```yaml
|
||||
annotations:
|
||||
cert-manager.io/cluster-issuer: letsencrypt-prod
|
||||
spec:
|
||||
tls:
|
||||
- hosts:
|
||||
- app.veza.com
|
||||
- api.veza.com
|
||||
secretName: veza-tls
|
||||
```
|
||||
|
||||
When you apply the ingress, cert-manager will automatically:
|
||||
1. Create a Certificate resource
|
||||
2. Request certificate from Let's Encrypt
|
||||
3. Store it in the specified secret
|
||||
4. Renew it automatically before expiration
|
||||
|
||||
### Manual Certificate Request
|
||||
|
||||
You can also create a Certificate resource manually:
|
||||
|
||||
```bash
|
||||
kubectl apply -f k8s/certificates/certificate-example.yaml
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
### Check Certificate Status
|
||||
|
||||
```bash
|
||||
# List certificates
|
||||
kubectl get certificates -n veza-production
|
||||
|
||||
# Describe certificate to see status
|
||||
kubectl describe certificate veza-tls -n veza-production
|
||||
|
||||
# Check certificate events
|
||||
kubectl get events -n veza-production --field-selector involvedObject.name=veza-tls
|
||||
```
|
||||
|
||||
### Check Certificate Secret
|
||||
|
||||
```bash
|
||||
# List TLS secrets
|
||||
kubectl get secrets -n veza-production | grep tls
|
||||
|
||||
# View certificate details (base64 encoded)
|
||||
kubectl get secret veza-tls -n veza-production -o yaml
|
||||
```
|
||||
|
||||
### Test Certificate
|
||||
|
||||
```bash
|
||||
# Port forward to ingress
|
||||
kubectl port-forward service/ingress-nginx-controller 8443:443 -n ingress-nginx
|
||||
|
||||
# Test with curl
|
||||
curl -v https://localhost:8443 -k --resolve app.veza.com:8443:127.0.0.1
|
||||
|
||||
# Or check certificate expiration
|
||||
echo | openssl s_client -servername app.veza.com -connect app.veza.com:443 2>/dev/null | openssl x509 -noout -dates
|
||||
```
|
||||
|
||||
## Staging vs Production
|
||||
|
||||
### Use Staging for Testing
|
||||
|
||||
When testing certificate issuance, use the staging issuer first:
|
||||
|
||||
```yaml
|
||||
annotations:
|
||||
cert-manager.io/cluster-issuer: letsencrypt-staging
|
||||
```
|
||||
|
||||
Staging certificates:
|
||||
- Don't count against rate limits
|
||||
- Are not trusted by browsers (expected)
|
||||
- Useful for testing the setup
|
||||
|
||||
### Switch to Production
|
||||
|
||||
Once staging works, switch to production:
|
||||
|
||||
```yaml
|
||||
annotations:
|
||||
cert-manager.io/cluster-issuer: letsencrypt-prod
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Certificate Not Issued
|
||||
|
||||
1. **Check cert-manager logs**:
|
||||
```bash
|
||||
kubectl logs -n cert-manager deployment/cert-manager
|
||||
kubectl logs -n cert-manager deployment/cert-manager-webhook
|
||||
kubectl logs -n cert-manager deployment/cert-manager-cainjector
|
||||
```
|
||||
|
||||
2. **Check Certificate status**:
|
||||
```bash
|
||||
kubectl describe certificate veza-tls -n veza-production
|
||||
```
|
||||
|
||||
3. **Check CertificateRequest**:
|
||||
```bash
|
||||
kubectl get certificaterequests -n veza-production
|
||||
kubectl describe certificaterequest <name> -n veza-production
|
||||
```
|
||||
|
||||
4. **Check Challenge**:
|
||||
```bash
|
||||
kubectl get challenges -n veza-production
|
||||
kubectl describe challenge <name> -n veza-production
|
||||
```
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Issue**: Certificate pending
|
||||
- **Cause**: DNS not pointing to ingress, or ingress controller not accessible
|
||||
- **Solution**: Verify DNS records and ingress controller accessibility
|
||||
|
||||
**Issue**: Rate limit exceeded
|
||||
- **Cause**: Too many certificate requests to Let's Encrypt
|
||||
- **Solution**: Use staging issuer for testing, wait for rate limit reset
|
||||
|
||||
**Issue**: HTTP-01 challenge failing
|
||||
- **Cause**: Ingress not accessible on port 80, or wrong ingress class
|
||||
- **Solution**: Verify ingress controller is accessible and annotation matches
|
||||
|
||||
**Issue**: Certificate secret not created
|
||||
- **Cause**: Certificate request failed
|
||||
- **Solution**: Check certificate status and cert-manager logs
|
||||
|
||||
### Debug Commands
|
||||
|
||||
```bash
|
||||
# Check all cert-manager resources
|
||||
kubectl get certificates,certificaterequests,challenges -n veza-production
|
||||
|
||||
# Check ClusterIssuer status
|
||||
kubectl describe clusterissuer letsencrypt-prod
|
||||
|
||||
# Check ingress annotations
|
||||
kubectl get ingress veza-ingress -n veza-production -o yaml
|
||||
|
||||
# Check cert-manager pods
|
||||
kubectl get pods -n cert-manager
|
||||
|
||||
# View cert-manager controller logs
|
||||
kubectl logs -n cert-manager -l app=cert-manager --tail=100
|
||||
```
|
||||
|
||||
## Certificate Renewal
|
||||
|
||||
cert-manager automatically renews certificates before expiration (default: 30 days before expiry).
|
||||
|
||||
### Manual Renewal
|
||||
|
||||
```bash
|
||||
# Delete the certificate to force renewal
|
||||
kubectl delete certificate veza-tls -n veza-production
|
||||
|
||||
# cert-manager will automatically recreate it
|
||||
```
|
||||
|
||||
### Check Expiration
|
||||
|
||||
```bash
|
||||
# View certificate expiration
|
||||
kubectl get certificate veza-tls -n veza-production -o jsonpath='{.status.notAfter}'
|
||||
|
||||
# Or decode and view
|
||||
kubectl get secret veza-tls -n veza-production -o jsonpath='{.data.tls\.crt}' | base64 -d | openssl x509 -noout -dates
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use staging first**: Test with staging issuer before production
|
||||
2. **Monitor certificates**: Set up alerts for certificate expiration
|
||||
3. **Backup secrets**: Backup certificate secrets for disaster recovery
|
||||
4. **Multiple domains**: Use wildcard certificates for multiple subdomains
|
||||
5. **DNS-01 for wildcards**: Use DNS-01 challenge for wildcard certificates
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [cert-manager Documentation](https://cert-manager.io/docs/)
|
||||
- [Let's Encrypt Documentation](https://letsencrypt.org/docs/)
|
||||
- [cert-manager GitHub](https://github.com/cert-manager/cert-manager)
|
||||
|
||||
16
k8s/certificates/cert-manager-install.yaml
Normal file
16
k8s/certificates/cert-manager-install.yaml
Normal file
|
|
@ -0,0 +1,16 @@
|
|||
# Cert-Manager Installation
|
||||
# This file installs cert-manager using the official installation method
|
||||
# For production, use: kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml
|
||||
# Or use Helm: helm install cert-manager jetstack/cert-manager --namespace cert-manager --create-namespace
|
||||
|
||||
# Note: This is a reference file. In production, install cert-manager using:
|
||||
# kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml
|
||||
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: Namespace
|
||||
metadata:
|
||||
name: cert-manager
|
||||
labels:
|
||||
cert-manager.io/disable-validation: "true"
|
||||
|
||||
25
k8s/certificates/certificate-example.yaml
Normal file
25
k8s/certificates/certificate-example.yaml
Normal file
|
|
@ -0,0 +1,25 @@
|
|||
# Example Certificate resource
|
||||
# This demonstrates how to request a certificate manually (optional)
|
||||
# Usually, certificates are automatically requested via Ingress annotations
|
||||
|
||||
---
|
||||
apiVersion: cert-manager.io/v1
|
||||
kind: Certificate
|
||||
metadata:
|
||||
name: veza-tls
|
||||
namespace: veza-production
|
||||
spec:
|
||||
# Secret name where the certificate will be stored
|
||||
secretName: veza-tls
|
||||
# Issuer reference
|
||||
issuerRef:
|
||||
name: letsencrypt-prod
|
||||
kind: ClusterIssuer
|
||||
# DNS names for the certificate
|
||||
dnsNames:
|
||||
- app.veza.com
|
||||
- api.veza.com
|
||||
- www.veza.com
|
||||
# Optional: Common name
|
||||
commonName: veza.com
|
||||
|
||||
51
k8s/certificates/letsencrypt-issuer.yaml
Normal file
51
k8s/certificates/letsencrypt-issuer.yaml
Normal file
|
|
@ -0,0 +1,51 @@
|
|||
# Let's Encrypt ClusterIssuers for production and staging
|
||||
|
||||
---
|
||||
# Production ClusterIssuer (Let's Encrypt Production)
|
||||
apiVersion: cert-manager.io/v1
|
||||
kind: ClusterIssuer
|
||||
metadata:
|
||||
name: letsencrypt-prod
|
||||
spec:
|
||||
acme:
|
||||
# Let's Encrypt production server
|
||||
server: https://acme-v02.api.letsencrypt.org/directory
|
||||
# Email address used for ACME registration
|
||||
email: ops@veza.com # Change this to your email
|
||||
# Name of a secret used to store the ACME account private key
|
||||
privateKeySecretRef:
|
||||
name: letsencrypt-prod
|
||||
# Enable the HTTP-01 challenge provider
|
||||
solvers:
|
||||
- http01:
|
||||
ingress:
|
||||
class: nginx
|
||||
# Optional: DNS-01 challenge (for wildcard certificates)
|
||||
# - dns01:
|
||||
# cloudflare:
|
||||
# email: ops@veza.com
|
||||
# apiKeySecretRef:
|
||||
# name: cloudflare-api-key
|
||||
# key: api-key
|
||||
|
||||
---
|
||||
# Staging ClusterIssuer (Let's Encrypt Staging - for testing)
|
||||
apiVersion: cert-manager.io/v1
|
||||
kind: ClusterIssuer
|
||||
metadata:
|
||||
name: letsencrypt-staging
|
||||
spec:
|
||||
acme:
|
||||
# Let's Encrypt staging server (for testing)
|
||||
server: https://acme-staging-v02.api.letsencrypt.org/directory
|
||||
# Email address used for ACME registration
|
||||
email: ops@veza.com # Change this to your email
|
||||
# Name of a secret used to store the ACME account private key
|
||||
privateKeySecretRef:
|
||||
name: letsencrypt-staging
|
||||
# Enable the HTTP-01 challenge provider
|
||||
solvers:
|
||||
- http01:
|
||||
ingress:
|
||||
class: nginx
|
||||
|
||||
|
|
@ -8,6 +8,9 @@ metadata:
|
|||
cert-manager.io/cluster-issuer: letsencrypt-prod
|
||||
nginx.ingress.kubernetes.io/ssl-redirect: "true"
|
||||
nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
|
||||
nginx.ingress.kubernetes.io/ssl-protocols: "TLSv1.2 TLSv1.3"
|
||||
nginx.ingress.kubernetes.io/ssl-ciphers: "ECDHE-ECDSA-AES128-GCM-SHA256,ECDHE-RSA-AES128-GCM-SHA256,ECDHE-ECDSA-AES256-GCM-SHA384,ECDHE-RSA-AES256-GCM-SHA384"
|
||||
nginx.ingress.kubernetes.io/ssl-prefer-server-ciphers: "true"
|
||||
spec:
|
||||
tls:
|
||||
- hosts:
|
||||
|
|
|
|||
Loading…
Reference in a new issue