Add TLS standardization for platform, mongo, gateway & redis roles by Amunagala-itential · Pull Request #300 · itential/itential.deployer

Amunagala-itential · 2026-02-11T15:00:25Z

PKI Standardization and Hostname-Based Certificate Support

Summary

Standardized PKI implementation across MongoDB, Redis, Platform, and Gateway roles with hostname-based certificate naming to support multi-server deployments with unique certificates per host.

Problem

Hardcoded certificate names (server.pem, redis.crt) prevented multi-server deployments
Inconsistent PKI paths across roles (/etc/ssl/, /opt/itential/)
No flexible certificate strategy support (per-host, per-role, wildcard)

Solution

Hostname-based certificate naming using {{ inventory_hostname }}
Standardized PKI directory structure (/etc/pki/*)
Comprehensive PKI variables for all roles
Certificate preparation automation script
Support for 3 deployment scenarios via configuration

…s-changes

kvelarde-itential · 2026-02-11T15:39:58Z

roles/gateway/defaults/main/pki.yml

+# ============================================================================
+# Backward Compatibility - Legacy Variable Names
+# These maintain compatibility with existing templates
+# ============================================================================
+
+# Legacy variables for templates (point to new paths)
+gateway_ssl_cert_dest: "{{ gateway_https_cert_file }}"
+gateway_ssl_key_dest: "{{ gateway_https_key_file }}"
+gateway_ssl_rootca_dest: "{{ gateway_https_ca_file }}"


I don't think we need to provide backwards compatibility. Update the templates with the new variables.

kvelarde-itential · 2026-02-11T15:41:12Z

roles/gateway/tasks/configure-gateway-https.yml

Since you are using the same tags for all tasks, use a task block and move the tags to the block.

kvelarde-itential · 2026-02-11T15:45:14Z

roles/platform/defaults/main/mongodb.yml

 # and allows the use of invalid or self-signed certificates to connect.
 platform_mongo_tls_allow_invalid_certificates: false


Should this be moved to the pki defaults file?

I vote we keep it here. Ultimately, its used in the mongo config file template only.

kvelarde-itential · 2026-02-11T15:46:25Z

roles/platform/defaults/main/pki.yml

+# ============================================================================
+
+# Source directory for HTTPS certificates (on Ansible controller)
+platform_https_pki_src_dir: "/Users/ananth.munagala/deployer_checkins/PE-1386/certificates/platform"


I think this needs to change...

This is why we do code reviews. :-)

kvelarde-itential · 2026-02-11T15:46:34Z

roles/platform/defaults/main/pki.yml

+platform_https_pki_src_dir: "/Users/ananth.munagala/deployer_checkins/PE-1386/certificates/platform"
+
+# Source directory for MongoDB certificates (on Ansible controller)
+platform_mongodb_pki_src_dir: "/Users/ananth.munagala/deployer_checkins/PE-1386/certificates/platform"


kvelarde-itential · 2026-02-11T15:49:45Z

roles/redis/tasks/configure-redis-tls.yml

Use block for tags

kvelarde-itential · 2026-02-11T17:20:08Z

docs/itential_gateway_guide.md

+| `gateway_https_cert_filename` | String | HTTPS certificate filename. | `{{ inventory_hostname }}.crt` |
+| `gateway_https_key_filename` | String | HTTPS private key filename. | `{{ inventory_hostname }}.key` |
+| `gateway_https_ca_filename` | String | HTTPS CA bundle filename. | `ca-bundle.crt` |
+| `gateway_pki_src_dir` | String | Source directory for Gateway certificates (on Ansible controller). | (set in inventory) |


kvelarde-itential · 2026-02-11T17:21:53Z

docs/itential_gateway_guide.md

+| `gateway_https_ca_filename` | String | HTTPS CA bundle filename. | `ca-bundle.crt` |
+| `gateway_pki_src_dir` | String | Source directory for Gateway certificates (on Ansible controller). | (set in inventory) |
+| `gateway_https_cert_file` | String | Deployed HTTPS certificate path. | `{{ gateway_pki_https_dir }}/{{ gateway_https_cert_filename }}` |
+| `gateway_https_key_file` | String | Deployed HTTPS private key path. | `{{ gateway_pki_private_dir }}/{{ gateway_https_key_filename }}` |


I don't see gateway_pki_private_dir.

kvelarde-itential · 2026-02-11T19:29:35Z

docs/itential_platform_guide.md

+certificates/
+├── platform
+│   ├── ca-bundle.crt
+│   ├── ip-10-222-1-169.ec2.internal.crt
+│   ├── ip-10-222-1-64.ec2.internal.crt
+│   ├── ip-10-222-1-64.ec2.internal.key


This doesn't render correctly.

I think it needs the ```

kvelarde-itential · 2026-02-11T19:30:25Z

docs/mongodb_guide.md

+certificates/
+├── mongodb
+│   ├── ca-bundle.crt
+│   ├── hostname1.pem
+│   ├── hostname2.pem
+│   ├── hostname3.pem
+│   ├── replica.key


Probably doesn't render correctly either.

kvelarde-itential · 2026-02-11T19:33:25Z

docs/tls_guide.md

+|----------|----------|---------------------|
+| **Scenario 1** | Per-host certificates (most secure) | One unique cert per server |
+| **Scenario 2** | Per-role certificates (simplified management) | One cert shared per role |
+| **Scenario 3** | Single wildcard certificate (simplest) | One cert for everything |


I may be wrong, but a multi-domain cert and a wild-card cert aren't synonymous. You can have a MD cert with actual hostnames. Or you can have a MD wild-card cert. Maybe just call this "Multi-Domain certificate".

Correct. A multi-domain cert can list many DNS or IPs in it, one file suitable for many servers. A wildcard cert uses a * in the DNS names, which also makes it suitable for many servers but its easier to spoof and depends on regex. I would call these multi-domain certs.

kvelarde-itential · 2026-02-11T19:42:35Z

docs/tls_guide.md

+## Recommendations by Environment
+
+### Development/Testing
+- **Use:** Scenario 3 (Wildcard)
+- **Why:** Simplest, fastest to set up, easy to regenerate
+
+### Staging
+- **Use:** Scenario 2 (Per-Role)
+- **Why:** Balance of simplicity and security, mirrors production patterns
+
+### Production
+- **Use:** Scenario 1 (Per-Host)
+- **Why:** Best security, compliance requirements, limited blast radius


I'm not sure we want to provide recommendations.

Agree. I have removed the recommendations section

kvelarde-itential · 2026-02-11T19:46:11Z

roles/gateway/tasks/configure-gateway-https.yml

+    group: "{{ gateway_pki_group }}"
+    mode: "{{ gateway_pki_subdir_mode }}"
+  loop:
+    - "{{ gateway_pki_https_dir }}"


I don't think you need a loop here.

kvelarde-itential · 2026-02-11T19:47:55Z

roles/mongodb/defaults/main/pki.yml

+# Set this in your inventory to point to your certificate directory
+mongodb_pki_src_dir: ""
+
+mongodb_ssl_root_dir: "{{ mongodb_pki_base_dir }}"


Remove and replace references with mongodb_pki_base_dir

kvelarde-itential · 2026-02-11T19:49:57Z

roles/platform/defaults/main/pki.yml

+platform_pki_base_owner: root
+
+# Group for PKI base directory
+platform_pki_base_group: itential


Suggested change

platform_pki_base_group: itential

platform_pki_base_group: "{{ platform_group }}"

kvelarde-itential · 2026-02-11T19:50:11Z

roles/platform/defaults/main/pki.yml

+platform_pki_private_owner: root
+
+# Group for private key files
+platform_pki_private_group: itential


Suggested change

platform_pki_private_group: itential

platform_pki_private_group: "{{ platform_group }}"

steven-schattenberg-itential

There are also some changes I anticipate to set the appropriate SE Linux labels on files. We can address that separately.

steven-schattenberg-itential · 2026-02-12T10:50:51Z

docs/itential_platform_guide.md

+certificates/
+├── platform
+│   ├── ca-bundle.crt
+│   ├── ip-10-222-1-169.ec2.internal.crt
+│   ├── ip-10-222-1-64.ec2.internal.crt
+│   ├── ip-10-222-1-64.ec2.internal.key


I think it needs the ```

docs/mongodb_guide.md

steven-schattenberg-itential · 2026-02-12T10:57:18Z

docs/tls_guide.md

+|----------|----------|---------------------|
+| **Scenario 1** | Per-host certificates (most secure) | One unique cert per server |
+| **Scenario 2** | Per-role certificates (simplified management) | One cert shared per role |
+| **Scenario 3** | Single wildcard certificate (simplest) | One cert for everything |


Correct. A multi-domain cert can list many DNS or IPs in it, one file suitable for many servers. A wildcard cert uses a * in the DNS names, which also makes it suitable for many servers but its easier to spoof and depends on regex. I would call these multi-domain certs.

steven-schattenberg-itential · 2026-02-12T10:58:39Z

docs/tls_guide.md

+├── wildcard.crt             ← One cert for everything
+├── wildcard.key


roles/gateway/defaults/main/pki.yml

steven-schattenberg-itential · 2026-02-12T11:05:29Z

roles/gateway/defaults/main/pki.yml

+gateway_pki_owner: "{{ gateway_user }}"
+
+# Group for PKI directories and files
+gateway_pki_group: "{{ gateway_group }}"


I'm not sure what value these two vars provide. We should be opinionated in the tasks that create make these files and user the gateway_user and gateway_group. If that's not sufficient for customers then they can change it after.

Agree, gateway_pki_owner and gateway_pki_group are just wrappers around gateway_user and gateway_group with no added value.
I have used gateway_user and gateway_group in the tasks directly.

steven-schattenberg-itential · 2026-02-12T11:07:07Z

roles/gateway/defaults/main/pki.yml

+gateway_https_key_mode: "0600"
+
+# HTTPS CA bundle permissions
+gateway_https_ca_mode: "0644"


I'm not sure what values these provide either. Lets just set the permissions in the tasks and reduce the complexity here. Or move these vars where they can not be overridden.

steven-schattenberg-itential · 2026-02-12T11:12:17Z

roles/platform/defaults/main/mongodb.yml

 # and allows the use of invalid or self-signed certificates to connect.
 platform_mongo_tls_allow_invalid_certificates: false


I vote we keep it here. Ultimately, its used in the mongo config file template only.

steven-schattenberg-itential · 2026-02-12T11:13:11Z

roles/platform/defaults/main/pki.yml

+# ============================================================================
+
+# Source directory for HTTPS certificates (on Ansible controller)
+platform_https_pki_src_dir: "/Users/ananth.munagala/deployer_checkins/PE-1386/certificates/platform"


This is why we do code reviews. :-)

steven-schattenberg-itential · 2026-02-12T11:14:20Z

roles/platform/defaults/main/platform.yml

 platform_root_dir: "{{ platform_root_dir_default }}"
 platform_config_dir: "{{ platform_config_dir_default }}"
-platform_tls_dir: "{{ platform_tls_dir_default }}"
+# platform_tls_dir: "{{ platform_tls_dir_default }}"


If we don't need it then remove it.

Amunagala-itential added 5 commits February 10, 2026 16:27

Adding TLS standardization for platform, mongo, gateway & redis roles

98c3bfb

Merge remote-tracking branch 'upstream/feature/v4' into feature/v4-tl…

68d5183

…s-changes

modified the boolean values as per reference guide

6aa27c9

Additional modifications for https boolean values

9b79f36

Additional modifications for https boolean values

821d642

Amunagala-itential requested review from Madias2222, Nick-Andreano, bill-minear, kvelarde-itential and steven-schattenberg-itential February 11, 2026 15:00

kvelarde-itential reviewed Feb 11, 2026

View reviewed changes

steven-schattenberg-itential requested changes Feb 12, 2026

View reviewed changes

		# and allows the use of invalid or self-signed certificates to connect.
		platform_mongo_tls_allow_invalid_certificates: false

	\| `gateway_pki_src_dir` \| String \| Source directory for Gateway certificates (on Ansible controller). \| (set in inventory) \|
	\| `gateway_pki_src_dir` \| String \| Source directory for Gateway certificates (on Ansible controller). \| MUST be set in inventory \|

	platform_pki_base_group: itential
	platform_pki_base_group: "{{ platform_group }}"

	platform_pki_private_group: itential
	platform_pki_private_group: "{{ platform_group }}"

		├── wildcard.crt ← One cert for everything
		├── wildcard.key

Conversation

Amunagala-itential commented Feb 11, 2026

PKI Standardization and Hostname-Based Certificate Support

Summary

Problem

Solution

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

steven-schattenberg-itential left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants