SSL Certificates¶
All user connections go through a Traefik service. The infrastructure uses SSL certificates for exposing the Portal through Traefik as well as for internal communications between platform services.
Important
It is recommended to use a different PKI for internal communications than the one used for Traefik.
Traefik¶
Three modes are available:
Default certificate¶
By default, a self-signed certificate is automatically generated when creating the Traefik container. This mode is suitable for test environments but not recommended for production.
Local certificate¶
You can provide a certificate and key stored on the Ansible machine. The reemo-infra role deploys these files on the servers hosting Traefik.
TRAEFIK_SSL_CERTS is a list: you can declare several certificate/key pairs, for example a distinct certificate for the user portal URL and for the admin portal URL. Traefik selects the certificate matching the requested domain name.
Inventory example:
TRAEFIK_SSL_CERTS:
- cert_file: "/localpath/to/portal.crt"
key_file: "/localpath/to/portal.key"
- cert_file: "/localpath/to/admin.crt"
key_file: "/localpath/to/admin.key"
Certificate already present on the server¶
If certificates are already installed on the target servers, you can specify their local paths. They will then be mounted directly into the Traefik container.
Like TRAEFIK_SSL_CERTS, TRAEFIK_SSL_CERTS_REMOTE accepts several certificate/key pairs.
Inventory example:
TRAEFIK_SSL_CERTS_REMOTE:
- cert_file_remotepath: "/remotepath/to/portal.crt"
key_file_remotepath: "/remotepath/to/portal.key"
- cert_file_remotepath: "/remotepath/to/admin.crt"
key_file_remotepath: "/remotepath/to/admin.key"
Internal communications¶
Default PKI¶
The reemo-infra Ansible role includes a complete, ready-to-use dedicated PKI. It enables a simple deployment with encrypted and authenticated internal communications.
Automatically generated CA¶
You can use a Certification Authority (CA) generated automatically when running the reemo-infra role.
Steps:
Create a local directory on the Ansible machine, writable by the user running Ansible.
Add the required options in the inventory file to enable this feature.
all:
vars:
LOCAL_PATH: "/opt/reemo/ssl"
INITCA_ENABLE: "true"
infra_manager:
hosts:
infra_manager1:
ansible_host: "10.0.0.1"
infra_manager2:
ansible_host: "10.0.0.2"
infra_manager3:
ansible_host: "10.0.0.3"
When the role starts, a CA will be created automatically in this directory. The associated keys and certificates will then be exported to the Docker Swarm cluster as Secrets and mounted into the containers that need them.
Git persistence and automatic renewal¶
The automatically generated PKI (CA, keys, and certificates) can be stored in a Git repository. On each run of the reemo-infra role, the PKI is pulled from the repository (git pull) into LOCAL_PATH before certificates are checked, then the updated artifacts are published back (git commit and git push) after generation.
Combined with a scheduled run (CRON), this mode provides automatic certificate renewal: the CA is renewed as it approaches expiration (30 days before), and the updated PKI is published back to the repository.
This mode complements the automatically generated CA: INITCA_ENABLE must be enabled. The repository is accessed over SSH, through an SSH agent whose SSH_AUTH_SOCK environment variable is set.
Inventory example:
all:
vars:
LOCAL_PATH: "/opt/reemo/ssl"
INITCA_ENABLE: "true"
INITCA_GIT_ENABLE: "true"
INITCA_GIT_SSH_URL: "git@example.com:your-org/reemo-pki.git"
INITCA_GIT_BRANCH: "main"
infra_manager:
hosts:
infra_manager1:
ansible_host: "10.0.0.1"
infra_manager2:
ansible_host: "10.0.0.2"
infra_manager3:
ansible_host: "10.0.0.3"
Available options:
INITCA_GIT_ENABLE: enables PKI persistence in a Git repository (
falseby default).INITCA_GIT_SSH_URL: SSH URL of the Git repository hosting the PKI.
INITCA_GIT_BRANCH: branch used for
pullandpush(mainby default).
Renewing the PKI¶
Certificate generation and renewal are driven by the initca tag of the reemo-infra role. Re-running the role is idempotent: a certificate is regenerated only when it enters its last 30 days of validity, when the internal CA has itself been renewed (all certificates it signed are then re-issued), or when a certificate’s SAN (Subject Alternative Name, the list of host names it covers) has changed; otherwise nothing is touched.
This procedure applies to the internal PKI generated automatically (INITCA_ENABLE). To check the internal PKI and renew any certificate nearing expiry, run the role with the initca tag:
ansible-playbook -i inventory.yml playbooks/reemo-infra.yml --tags initca
When INITCA_GIT_ENABLE is set, this single command also pulls the PKI from the Git repository before the check and pushes the renewed artifacts back afterwards.
Available tags:
initca: the full PKI chain:
git pull(if enabled), CA and per-service certificate check and renewal, thengit push(if enabled).initca_git: the Git steps only (
pullthenpush), without regenerating certificates.
To make renewal fully automatic, schedule this command (for example with CRON). As the run is idempotent, it can be executed as often as you like; a daily run ensures that every certificate is renewed within the 30-day window before it expires:
# Every day at 03:00: renew the internal PKI if needed
0 3 * * * cd /path/to/ansible && ansible-playbook -i inventory.yml playbooks/reemo-infra.yml --tags initca >> /var/log/reemo-initca.log 2>&1
Note
Git persistence (INITCA_GIT_ENABLE) is what makes a scheduled renewal durable: the renewed CA and certificates are published back to the repository instead of living only on the Ansible machine. Without it, the renewed PKI is kept only in LOCAL_PATH on the host running the playbook. When INITCA_GIT_ENABLE is set, the scheduled task must also have access to an SSH agent whose SSH_AUTH_SOCK environment variable is set.
Manual configuration¶
You can also generate the SSL certificates yourself, then specify in the Ansible inventory the local paths of the keys and certificates. They will be copied automatically to the Docker Swarm cluster by the reemo-infra role.
For each URL, the variables follow the same pattern: <URL>_SSL_CRT_LOCALPATH and <URL>_SSL_KEY_LOCALPATH (URL name in uppercase, without the reemo_ prefix). For example, reemo_provision uses PROVISION_SSL_CRT_LOCALPATH and PROVISION_SSL_KEY_LOCALPATH.
Core URLs (always required):
reemo_apireemo_apicronreemo_portalreemo_portaladminreemo_signalreemo_proapireemo_prorelayapireemo_procloudapireemo_traefik
Depending on the topology and the enabled options, other URLs are required:
Provisioning nodes (HAProxy):
reemo_provisionWebSocket relay:
reemo_relaywsDatabase with SSL (
DB_SSL_REQUIRE):reemo_db(orreemo_mariadbdepending on the engine) andreemo_ndbmonitorRecord API (
RECORDAPI_ENABLED):reemo_recordapi,reemo_recordportal,reemo_recorddb, andreemo_recordapicronAppliance module (
APPLIANCE_ENABLED):reemo_applianceapiandreemo_applianceportalIdentity (
IDENTITY_ENABLED):reemo_identityapi,reemo_identityportal, andreemo_applianceidentityVault (
VAULT_ENABLED):reemo_vaultCredentialAPI (
CREDENTIAL_ENABLED):reemo_credentialapiandreemo_credentialportalWake-on-LAN (
WOLAPI_ENABLE):reemo_wolapiLogs (LogAPI):
reemo_logapiMaintenance mode:
reemo_maintenance
Example:
all:
vars:
API_LICENSE: "ewogICAg ... Uw5NXhGVDF0NFU2TkxOdjQvZU53PT0iCiAgICC9Cn0="
...
infra_manager:
hosts:
infra_manager1:
ansible_host: "10.0.0.1"
infra_manager2:
ansible_host: "10.0.0.2"
infra_manager3:
ansible_host: "10.0.0.3"
vars:
CA_SSL_CRT_LOCALPATH: "/local/path/ca.crt"
API_SSL_CRT_LOCALPATH: "/local/path/reemo_api.crt"
API_SSL_KEY_LOCALPATH: "/local/path/reemo_api.key"
PROAPI_SSL_CRT_LOCALPATH: "/local/path/reemo_proapi.crt"
PROAPI_SSL_KEY_LOCALPATH: "/local/path/reemo_proapi.key"
PRORELAYAPI_SSL_CRT_LOCALPATH: "/local/path/reemo_prorelayapi.crt"
PRORELAYAPI_SSL_KEY_LOCALPATH: "/local/path/reemo_prorelayapi.key"
SIGNAL_SSL_CRT_LOCALPATH: "/local/path/reemo_signal.crt"
SIGNAL_SSL_KEY_LOCALPATH: "/local/path/reemo_signal.key"
PORTAL_SSL_CRT_LOCALPATH: "/local/path/reemo_portal.crt"
PORTAL_SSL_KEY_LOCALPATH: "/local/path/reemo_portal.key"
PORTALADMIN_SSL_CRT_LOCALPATH: "/local/path/reemo_portaladmin.crt"
PORTALADMIN_SSL_KEY_LOCALPATH: "/local/path/reemo_portaladmin.key"
PROVISION_SSL_CRT_LOCALPATH: "/local/path/reemo_provision.crt"
PROVISION_SSL_KEY_LOCALPATH: "/local/path/reemo_provision.key"
TRAEFIK_SSL_CERTS:
- cert_file: "/local/path/domain.crt"
key_file: "/local/path/domain.key"