Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 24 additions & 5 deletions roles/ocp4_workload_cert_manager/defaults/main.yml
Original file line number Diff line number Diff line change
Expand Up @@ -79,12 +79,31 @@ ocp4_workload_cert_manager_gcp_credentials: "{{ gcp_credentials }}"
# ---------------------------------------------------------------
# Settings for Azure
# ---------------------------------------------------------------
# Set from AgnosticV to the actual azure credentials
ocp4_workload_cert_manager_azure_client_id: "{{ azure_service_principal }}"
# Azure DNS service principal application/client ID (string). Explicit role inputs
# override these defaults, which use the canonical Azure names.
ocp4_workload_cert_manager_azure_client_id: "{{ azure_service_principal_id }}"

# Azure DNS service principal password (secret string). Stored in a Kubernetes
# Secret in cert-manager for issuance AND renewal. Never log this value.
ocp4_workload_cert_manager_azure_client_secret: "{{ azure_service_principal_password }}"

# Azure cloud environment recognized by cert-manager (string), used by both
# primary and fallback AzureDNS solvers. Public Azure is the default.
ocp4_workload_cert_manager_azure_environment: AzurePublicCloud
ocp4_workload_cert_manager_azure_hostedzone_name: "{{ azure_user_domain }}"
ocp4_workload_cert_manager_azure_resource_group_name: "{{ az_dnszone_resource_group }}"
ocp4_workload_cert_manager_azure_subscription_id: "{{ azure_subscription_id }}"

# Existing publicly delegated Azure DNS zone (string, not a resource ID).
# Enabled certificate targets must equal this zone or be beneath it.
ocp4_workload_cert_manager_azure_hostedzone_name: "{{ azure_dns_zone }}"

# Resource group containing that DNS zone (string), NOT the cluster resource
# group. The service principal needs DNS record write/delete permission here.
ocp4_workload_cert_manager_azure_resource_group_name: "{{ azure_resource_group }}"

# Subscription containing the DNS zone (string).
ocp4_workload_cert_manager_azure_subscription_id: "{{ azure_subscription }}"

# Tenant of the DNS service principal (string). An explicit role override may
# supply a dedicated DNS identity independently of cluster provisioning.
ocp4_workload_cert_manager_azure_tenant_id: "{{ azure_tenant }}"

# ---------------------------------------------------------------
Expand Down
99 changes: 97 additions & 2 deletions roles/ocp4_workload_cert_manager/readme.adoc
Original file line number Diff line number Diff line change
@@ -1,3 +1,98 @@
= ocp4_workload_cert_manager - Install Red Hat Cert Manager Operator and Request and install certificates from Let's Encrypt or ZeroSSL
= ocp4_workload_cert_manager

See defaults/main.yml for variables to set.
Installs the Red Hat cert-manager Operator, configures an ACME ClusterIssuer,
requests certificates, and installs ready certificates on the default ingress
controller and optionally the API server. It runs on the bastion with cluster-admin
Kubernetes access. See `defaults/main.yml` for inputs and defaults.

== Azure DNS with Azure IPI

Use `cloud_provider: azure` and `host_ocp4_deploy_installation_method: openshift_install`.
Add `agnosticd.core_workloads.ocp4_workload_cert_manager` to the config's existing
`workloads` list. Ingress certificates are enabled by default; API certificates
are disabled. Enabling API replacement restarts API servers and uses the existing
rollout wait and kubeconfig adjustment flow.

The Azure config maps normalized controller facts to these workload inputs, so
workloads running on the bastion use the same sandbox credentials and delegated
DNS zone:

[cols="1,1"]
|===
|Role input suffix (`ocp4_workload_cert_manager_azure_`) |Controller fact
|client_id |azure_auth.app_id
|client_secret |azure_auth.password
|subscription_id |azure_auth.subscription_id
|tenant_id |azure_auth.tenant
|hostedzone_name |azure_settings.dns_zone
|resource_group_name |azure_settings.sandbox_group
|===

Explicit role-specific inputs override these defaults, allowing a dedicated DNS
identity or a zone in another subscription. Standalone role use prefers canonical
Azure variables and falls back to legacy aliases; missing values fail before
operator installation. The default environment is `AzurePublicCloud`; both primary
and fallback issuers honor `ocp4_workload_cert_manager_azure_environment`.

The public zone must already exist and be delegated. The service principal must
be able to read the zone and create/delete TXT records; `DNS Zone Contributor`
on that zone is the documented AzureDNS setup. This workload creates neither
identities nor role assignments. See
https://cert-manager.io/docs/configuration/acme/dns01/azuredns/[AzureDNS authentication].
The resource group is the one containing the DNS zone, not the cluster's group.

Enabled certificate names must equal the zone or be descendants at a DNS-label
boundary. Case and a final dot are ignored for this check. Azure IPI API/ingress
names beneath the workshop zone work. Microsoft's managed ARO domains do not
belong to that zone; ARO custom domains and HCP are outside this integration.
Disabled targets are not requested or checked. Disabling a flag does not delete
an already installed certificate or revert an existing endpoint.

== Example

[source,yaml]
----
cloud_provider: azure
host_ocp4_deploy_installation_method: openshift_install
workloads:
- agnosticd.core_workloads.ocp4_workload_cert_manager

# Ingress is the default; opt into API replacement only when needed.
ocp4_workload_cert_manager_install_ingress_certificates: true
ocp4_workload_cert_manager_install_api_certificates: false

# First validate issuance with the staging CA (certificates are untrusted).
# Omit this override for production Let's Encrypt certificates.
ocp4_workload_cert_manager_acme_url: https://acme-staging-v02.api.letsencrypt.org/directory

# Optional dedicated DNS identity. Supply its password through Vault/secrets.
# ocp4_workload_cert_manager_azure_client_id: <application UUID>
# ocp4_workload_cert_manager_azure_client_secret: <Vault reference>
# ocp4_workload_cert_manager_azure_tenant_id: <tenant UUID or domain>
# ocp4_workload_cert_manager_azure_subscription_id: <subscription UUID>
# ocp4_workload_cert_manager_azure_resource_group_name: <DNS resource group>
# ocp4_workload_cert_manager_azure_hostedzone_name: <guid>.azure.redhatworkshops.io
----

== Secrets, renewal and troubleshooting

The client password is stored as `client-secret` in `cert-manager-azure-creds` in
namespace `cert-manager`. Rendering and applying that Secret uses `no_log`.
Protect access to the Secret and keep credentials valid for renewals. Both issuers
reference the same Secret. Updating its credentials and rerunning the workload
does not require creating a new service principal. Do not remove the credentials
or DNS permissions after initial issuance.

Certificates retain the existing 90-day duration and 15-day renewal window;
cert-manager updates the same TLS Secrets referenced by ingress/API configuration.
After issuance, verify the served certificate. Test renewal with `cmctl renew`
and confirm the Certificate revision and served serial change. Operator installation,
retries and optional fallback CA behavior otherwise follow the existing role.
Removal of this workload is currently not implemented.

For failures inspect `Certificate`, `CertificateRequest`, `Order` and `Challenge`
conditions, and controller logs. Verify zone delegation, DNS permissions, tenant,
subscription and the DNS resource group. A boundary failure is a configuration
error; changing ACME providers will not fix it. Avoid dumping Secrets or credential
variables while debugging. Live issuance and renewal create temporary Azure TXT
records and require explicit approval in this project.
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,4 @@
kubernetes.core.k8s:
state: present
template: secret-azure-credentials.yaml.j2
no_log: true
49 changes: 49 additions & 0 deletions roles/ocp4_workload_cert_manager/tasks/validate_azure.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
---
- name: Validate public Azure DNS settings
ansible.builtin.assert:
that:
- lookup('vars', item) is string
- lookup('vars', item) | trim | length > 0
fail_msg: "Required Azure DNS input {{ item }} is missing or empty"
loop:
- ocp4_workload_cert_manager_azure_client_id
- ocp4_workload_cert_manager_azure_environment
- ocp4_workload_cert_manager_azure_hostedzone_name
- ocp4_workload_cert_manager_azure_resource_group_name
- ocp4_workload_cert_manager_azure_subscription_id
- ocp4_workload_cert_manager_azure_tenant_id

- name: Validate protected Azure DNS client secret
ansible.builtin.assert:
that:
- ocp4_workload_cert_manager_azure_client_secret is string
- ocp4_workload_cert_manager_azure_client_secret | length > 0
fail_msg: Supply ocp4_workload_cert_manager_azure_client_secret or the Azure service principal password
no_log: true

- name: Validate enabled certificate targets are nonempty hostnames
ansible.builtin.assert:
that:
- >-
not ocp4_workload_cert_manager_install_api_certificates | bool or
(_ocp4_workload_cert_manager_api_hostname is string and _ocp4_workload_cert_manager_api_hostname | length > 0)
- >-
not ocp4_workload_cert_manager_install_ingress_certificates | bool or
(_ocp4_workload_cert_manager_wildcard_domain is string and _ocp4_workload_cert_manager_wildcard_domain | length > 0)
fail_msg: Enabled certificates require openshift_api_url and/or openshift_cluster_ingress_domain

- name: Validate enabled certificate targets belong to the Azure DNS zone
when: item | length > 0
vars:
_ocp4_workload_cert_manager_dns_zone: "{{ ocp4_workload_cert_manager_azure_hostedzone_name | lower | regex_replace('[.]$', '') }}"
ansible.builtin.assert:
that:
- >-
(item | lower | regex_replace('[.]$', '')) == _ocp4_workload_cert_manager_dns_zone or
(item | lower | regex_replace('[.]$', '')).endswith('.' ~ _ocp4_workload_cert_manager_dns_zone)
fail_msg: >-
Certificate target {{ item }} is outside Azure DNS zone {{ ocp4_workload_cert_manager_azure_hostedzone_name }}.
Microsoft-managed ARO domains require separate custom-domain configuration; this integration targets Azure IPI.
loop:
- "{{ _ocp4_workload_cert_manager_api_hostname }}"
- "{{ _ocp4_workload_cert_manager_wildcard_domain }}"
47 changes: 34 additions & 13 deletions roles/ocp4_workload_cert_manager/tasks/workload.yml
Original file line number Diff line number Diff line change
@@ -1,4 +1,15 @@
---
- name: Set DNS facts for enabled certificate targets
ansible.builtin.set_fact:
_ocp4_workload_cert_manager_api_hostname: >-
{{ (openshift_api_url | urlsplit('hostname')) if ocp4_workload_cert_manager_install_api_certificates | bool else '' }}
_ocp4_workload_cert_manager_wildcard_domain: >-
{{ openshift_cluster_ingress_domain if ocp4_workload_cert_manager_install_ingress_certificates | bool else '' }}

- name: Validate Azure DNS inputs before installing the operator
when: ocp4_workload_cert_manager_cloud_provider == 'azure'
ansible.builtin.include_tasks: validate_azure.yml

- name: Install Red Hat Cert Manager operator
ansible.builtin.include_role:
name: install_operator
Expand Down Expand Up @@ -26,13 +37,6 @@
state: present
template: certmanager.yaml.j2

- name: Set DNS facts
ansible.builtin.set_fact:
_ocp4_workload_cert_manager_api_hostname: >-
{{ openshift_api_url | urlsplit('hostname') }}
_ocp4_workload_cert_manager_wildcard_domain: >-
{{ openshift_cluster_ingress_domain }}

- name: Print API and wildcard domain
ansible.builtin.debug:
msg: >-
Expand Down Expand Up @@ -64,6 +68,7 @@
- name: Setup ACME Bifrost
when: ocp4_workload_cert_manager_provider == "acme-bifrost" or ocp4_workload_cert_manager_provider_fallback == "acme-bifrost"
block:

- name: Deploy ACME Bifrost webhook
kubernetes.core.k8s:
state: present
Expand Down Expand Up @@ -103,14 +108,10 @@
retries: 30
delay: 10

- name: Set up ClusterIssuer and request certificates
- name: Set up ClusterIssuer
kubernetes.core.k8s:
state: present
template: "{{ item }}"
loop:
- clusterissuer.yaml.j2
- certificate-ingress.yaml.j2
- certificate-api.yaml.j2
template: clusterissuer.yaml.j2
register: r_clusterissuer
retries: 10
delay: 30
Expand All @@ -122,6 +123,26 @@
state: present
template: "clusterissuer-fallback.yaml.j2"

- name: Request ingress certificate
when: ocp4_workload_cert_manager_install_ingress_certificates | bool
kubernetes.core.k8s:
state: present
template: certificate-ingress.yaml.j2
register: r_certificate_ingress_request
retries: 10
delay: 30
until: r_certificate_ingress_request is success

- name: Request API certificate
when: ocp4_workload_cert_manager_install_api_certificates | bool
kubernetes.core.k8s:
state: present
template: certificate-api.yaml.j2
register: r_certificate_api_request
retries: 10
delay: 30
until: r_certificate_api_request is success

- name: Install Ingress controller certificate
when: ocp4_workload_cert_manager_install_ingress_certificates | bool
block:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,17 @@ spec:
{% endif %}
solvers:
- selector:
{% if not (ocp4_workload_cert_manager_install_api_certificates | bool or ocp4_workload_cert_manager_install_ingress_certificates | bool) %}
{}
{% else %}
dnsZones:
{% if ocp4_workload_cert_manager_install_api_certificates | bool %}
- {{ _ocp4_workload_cert_manager_api_hostname }}
{% endif %}
{% if ocp4_workload_cert_manager_install_ingress_certificates | bool %}
- {{ _ocp4_workload_cert_manager_wildcard_domain }}
{% endif %}
{% endif %}
dns01:
{% if ocp4_workload_cert_manager_cloud_provider == "aws" and ocp4_workload_cert_manager_provider != "acme-bifrost" %}
route53:
Expand All @@ -43,15 +51,15 @@ spec:
{% endif %}
{% if ocp4_workload_cert_manager_cloud_provider == "azure" %}
azureDNS:
clientID: {{ ocp4_workload_cert_manager_azure_client_id }}
clientID: {{ ocp4_workload_cert_manager_azure_client_id | to_json }}
clientSecretSecretRef:
name: cert-manager-azure-creds
key: client-secret
environment: AzurePublicCloud
hostedZoneName: {{ ocp4_workload_cert_manager_azure_hostedzone_name }}
resourceGroupName: {{ ocp4_workload_cert_manager_azure_resource_group_name }}
subscriptionID: {{ ocp4_workload_cert_manager_azure_subscription_id }}
tenantID: {{ ocp4_workload_cert_manager_azure_tenant_id }}
environment: {{ ocp4_workload_cert_manager_azure_environment | to_json }}
hostedZoneName: {{ ocp4_workload_cert_manager_azure_hostedzone_name | to_json }}
resourceGroupName: {{ ocp4_workload_cert_manager_azure_resource_group_name | to_json }}
subscriptionID: {{ ocp4_workload_cert_manager_azure_subscription_id | to_json }}
tenantID: {{ ocp4_workload_cert_manager_azure_tenant_id | to_json }}
{% endif %}
{% if ocp4_workload_cert_manager_provider == "acme-bifrost" %}
webhook:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,17 @@ spec:
{% endif %}
solvers:
- selector:
{% if not (ocp4_workload_cert_manager_install_api_certificates | bool or ocp4_workload_cert_manager_install_ingress_certificates | bool) %}
{}
{% else %}
dnsZones:
{% if ocp4_workload_cert_manager_install_api_certificates | bool %}
- {{ _ocp4_workload_cert_manager_api_hostname }}
{% endif %}
{% if ocp4_workload_cert_manager_install_ingress_certificates | bool %}
- {{ _ocp4_workload_cert_manager_wildcard_domain }}
{% endif %}
{% endif %}
dns01:
{% if ocp4_workload_cert_manager_cloud_provider == "aws" and ocp4_workload_cert_manager_provider != "acme-bifrost" %}
route53:
Expand All @@ -43,15 +51,15 @@ spec:
{% endif %}
{% if ocp4_workload_cert_manager_cloud_provider == "azure" %}
azureDNS:
clientID: {{ ocp4_workload_cert_manager_azure_client_id }}
clientID: {{ ocp4_workload_cert_manager_azure_client_id | to_json }}
clientSecretSecretRef:
name: cert-manager-azure-creds
key: client-secret
environment: AzurePublicCloud
hostedZoneName: {{ ocp4_workload_cert_manager_azure_hostedzone_name }}
resourceGroupName: {{ ocp4_workload_cert_manager_azure_resource_group_name }}
subscriptionID: {{ ocp4_workload_cert_manager_azure_subscription_id }}
tenantID: {{ ocp4_workload_cert_manager_azure_tenant_id }}
environment: {{ ocp4_workload_cert_manager_azure_environment | to_json }}
hostedZoneName: {{ ocp4_workload_cert_manager_azure_hostedzone_name | to_json }}
resourceGroupName: {{ ocp4_workload_cert_manager_azure_resource_group_name | to_json }}
subscriptionID: {{ ocp4_workload_cert_manager_azure_subscription_id | to_json }}
tenantID: {{ ocp4_workload_cert_manager_azure_tenant_id | to_json }}
{% endif %}
{% if ocp4_workload_cert_manager_provider == "acme-bifrost" %}
webhook:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,4 +6,4 @@ metadata:
namespace: cert-manager
type: Opaque
stringData:
client-secret: {{ azure_password }}
client-secret: {{ ocp4_workload_cert_manager_azure_client_secret | to_json }}
11 changes: 10 additions & 1 deletion tests/static/tox.ini
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
[tox]
envlist = yamllint, ansible-lint
envlist = yamllint, ansible-lint, cert-manager
skipsdist = True
skip_missing_interpreters = True

Expand All @@ -16,3 +16,12 @@ changedir = {toxinidir}/../..
commands =
ansible-galaxy collection install -r {toxinidir}/collections-requirements.yml --force
ansible-lint

# Offline regression checks: writes synthetic manifests only, no cloud/cluster IO.
[testenv:cert-manager]
deps =
ansible-core
PyYAML
Jinja2
changedir = {toxinidir}/../..
commands = python -m unittest discover -s tests/unit -p test_cert_manager_azure.py -v
Loading
Loading