# Certificate Management Role

This role manages TLS certificates for the OpenShift cluster, setting up automated certificate issuance and renewal through cert-manager and Let's Encrypt.

## Overview

The certificate management role:

1. Sets up the necessary certificate issuers (Let's Encrypt)
2. Creates certificates for the API server and other critical services
3. Configures DNS validation for certificate issuance
4. Sets up appropriate RBAC for certificate management

## Prerequisites

- cert-manager must be installed in the cluster (via cert_manager_deployment role)
- Cloudflare API credentials must be configured in the vault
- DNS domains must be properly configured

## Role Variables

| Variable | Description | Default |
|----------|-------------|---------|
| setup_api_server_cert | Whether to set up an API server certificate | true |
| certificate_name | Name for the certificate resource | "api-server-cert" |
| certificate_secret_name | Name of the secret to store the certificate | "api-server-tls" |
| certificate_common_name | Common name for the certificate | Based on cluster name and region |
| certificate_dns_names | List of DNS names to include in the certificate | Based on cluster name and region |
| letsencrypt_environment | Let's Encrypt environment to use (staging/production) | "production" |
| cloudflare_api_token_secret_name | Name of the secret containing Cloudflare API token | "cloudflare-api-token" |

## Role Tasks

The role is organized into specific task files:

- **main.yml**: Main entry point that includes other task files
- **setup_roles.yml**: Sets up RBAC for certificate management
- **api_server_cert.yml**: Creates certificates for the API server

## Directory Structure

```
cert_management/
├── defaults/           # Default variables
│   └── main.yml
├── tasks/              # Tasks for certificate management
│   ├── api_server_cert.yml
│   ├── main.yml
│   └── setup_roles.yml
└── vars/               # Role-specific variables
```

## Certificate Issuers

The role sets up two certificate issuers:

1. **letsencrypt-staging**: For testing certificate issuance without rate limits
2. **letsencrypt-production**: For production certificates trusted by browsers

Both issuers use DNS validation through Cloudflare to verify domain ownership.

## DNS Validation

The role uses DNS-01 challenge type with Cloudflare DNS provider for validation. This method:
- Works with wildcard certificates
- Doesn't require opening ports on the cluster
- Automatically manages DNS TXT records for validation

## API Server Certificate

When `setup_api_server_cert` is true, the role:
1. Creates a Certificate custom resource
2. Configures it with the appropriate DNS names
3. Sets up automatic renewal
4. Stores the certificate in a Kubernetes Secret

## Dependencies

This role depends on:
- **cert_manager_deployment**: Must be run first to install cert-manager
- **kubernetes_auth**: For cluster authentication

## Example Usage

```yaml
- name: Set up certificates
  hosts: localhost
  roles:
    - role: cert_management
      vars:
        setup_api_server_cert: true
        certificate_name: "api-server-cert"
        certificate_secret_name: "api-server-tls"
        certificate_common_name: "api.hub.euw.container.mom"
        certificate_dns_names:
          - "api.hub.euw.container.mom"
          - "*.apps.hub.euw.container.mom"
```

## Troubleshooting

Common certificate issues:

- **Certificate not issuing**: Check cert-manager logs and verify Cloudflare API token permissions
- **DNS validation failing**: Verify Cloudflare Zone ID and API token are correct
- **Certificate not trusted**: Ensure you're using the production issuer for trusted certificates

## Notes

- Certificate renewal happens automatically 30 days before expiry
- Let's Encrypt has rate limits that can be hit during testing - use staging issuer for testing
- The role is designed to be idempotent and can be safely rerun