bakery-ia/docs/MINIO_CERTIFICATE_GENERATION_GUIDE.md

# MinIO Certificate Generation Guide

## Quick Start

To generate MinIO certificates with the correct format:

```bash
# Generate certificates
./infrastructure/tls/generate-minio-certificates.sh

# Update Kubernetes secret
kubectl delete secret -n bakery-ia minio-tls
kubectl apply -f infrastructure/kubernetes/base/secrets/minio-tls-secret.yaml

# Restart MinIO
kubectl rollout restart deployment -n bakery-ia minio
```

## Key Requirements

### Private Key Format
✅ **Required**: Traditional RSA format (`BEGIN RSA PRIVATE KEY`)
❌ **Problematic**: PKCS#8 format (`BEGIN PRIVATE KEY`)

### Certificate Files
- `minio-cert.pem` - Server certificate
- `minio-key.pem` - Private key (must be traditional RSA format)
- `ca-cert.pem` - CA certificate

## Verification

### Check Private Key Format
```bash
head -1 infrastructure/tls/minio/minio-key.pem
# Should output: -----BEGIN RSA PRIVATE KEY-----
```

### Verify Certificate Chain
```bash
openssl verify -CAfile infrastructure/tls/ca/ca-cert.pem \
  infrastructure/tls/minio/minio-cert.pem
```

### Check Certificate Details
```bash
openssl x509 -in infrastructure/tls/minio/minio-cert.pem -noout \
  -subject -issuer -dates
```

## Troubleshooting

### Error: "The private key contains additional data"
**Cause**: Private key is in PKCS#8 format instead of traditional RSA format

**Solution**: Convert the key:
```bash
openssl rsa -in minio-key.pem -traditional -out minio-key-fixed.pem
mv minio-key-fixed.pem minio-key.pem
```

### Error: "Unable to parse private key"
**Cause**: Certificate/key mismatch or corrupted files

**Solution**: Regenerate certificates and verify:
```bash
# Check modulus of certificate and key (should match)
openssl x509 -noout -modulus -in minio-cert.pem | openssl md5
openssl rsa -noout -modulus -in minio-key.pem | openssl md5
```

## Certificate Rotation

### Step-by-Step Process

1. **Generate new certificates**
   ```bash
   ./infrastructure/tls/generate-minio-certificates.sh
   ```

2. **Update base64 values in secret**
   ```bash
   # Update infrastructure/kubernetes/base/secrets/minio-tls-secret.yaml
   # with new base64 encoded certificate values
   ```

3. **Apply updated secret**
   ```bash
   kubectl delete secret -n bakery-ia minio-tls
   kubectl apply -f infrastructure/kubernetes/base/secrets/minio-tls-secret.yaml
   ```

4. **Restart MinIO pods**
   ```bash
   kubectl rollout restart deployment -n bakery-ia minio
   ```

5. **Verify**
   ```bash
   kubectl logs -n bakery-ia -l app.kubernetes.io/name=minio --tail=5
   # Should show: API: https://minio.bakery-ia.svc.cluster.local:9000
   ```

## Technical Details

### Certificate Generation Process

1. **Generate private key** (RSA 4096-bit)
2. **Convert to traditional RSA format** (critical for MinIO)
3. **Create CSR** with proper SANs
4. **Sign with CA** (valid for 3 years)
5. **Set permissions** (600 for key, 644 for certs)

### SANs (Subject Alternative Names)

The certificate includes these SANs for comprehensive coverage:
- `minio.bakery-ia.svc.cluster.local` (primary)
- `minio.bakery-ia`
- `minio-console.bakery-ia.svc.cluster.local`
- `minio-console.bakery-ia`
- `minio`
- `minio-console`
- `localhost`
- `127.0.0.1`

### Secret Structure

The Kubernetes secret uses the standardized Opaque format:

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: minio-tls
  namespace: bakery-ia
type: Opaque
data:
  ca-cert.pem: <base64>
  minio-cert.pem: <base64>
  minio-key.pem: <base64>
```

## Best Practices

1. **Always verify private key format** before applying
2. **Test certificates** with `openssl verify` before deployment
3. **Use the generation script** to ensure consistency
4. **Document certificate expiration dates** for rotation planning
5. **Monitor MinIO logs** after certificate updates

## Related Documentation

- [MinIO TLS Fix Summary](MINIO_TLS_FIX_SUMMARY.md)
- [Kubernetes TLS Secrets Guide](../kubernetes-tls-guide.md)
- [Certificate Management Best Practices](../certificate-management.md)