272 lines
6.9 KiB
Markdown
272 lines
6.9 KiB
Markdown
# 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)
|
|
|