suite_dns

This role will manage MAS and DNS provider integration. IBM Cloud Internet Services is the only supported DNS provider currently. It will also create a secure route (https://cp4d.) to the CP4D web client using the custom domain used in this role.

Note: this role will take no action when mas_manual_cert_mgmtis set to True

DNS management

There are two different ways this role controls DNS entries in the provider:

Top Level DNS entries

This mode will create the entries directly under your DNS zone. Use this when the DNS zone matches the MAS domain exactly. If your MAS installation will be using the domain mymas.mycompany.com and you have a DNS zone for mymas.mycompany.com then you will be creating top-level DNS entries for MAS, e.g. admin, home, & api.

Subdomain DNS entries

This mode will create DNS entries in the zone under a subdomain. Use this when your DNS zone will be used for more than just one MAS instance. If your MAS installation will be using the domain mymas.mycompany.com and you have a DNS zone for mycompany.com then you will be creating subdomain DNS entries for MAS, e.g. admin.mymas, home.mymas, & api.mymas.

CIS and Cloudflare integrations support both mode of DNS management. A single optional variable is required to enable subdomain DNS management, in the examples above you would set these to mymas:

cis_subdomain
cloudflare_subdomain

Let's Encrypt Integration

Both the CIS and Cloudflare options also enable integration with Let's Encrypt for automatic certificate management via IBM Certificate Manager. Each will create a new ClusterIssuer which can be used when installing Maximo Application Suite:

Cloudflare Let's Encrypt ClusterIssuer: {{ mas_instance_id }}-cloudflare-le-prod
IBM Cloud Internet Services Let's Encrypt ClusterIssuer: {{ mas_instance_id }}-cis-le-prod

If you want to use Let's Encrypt certificates in your MAS installation you will need to configure the mas_cluster_issuer variable in the suite_install role, setting it to the name of the ClusterIssuer as documented above.

Note

There are issues with how cert-manager works with LetsEncrypt staging servers. It creates a secret for the certificate that doesn't contain the LetsEncrypt CA, but the staging service does not use a well known cert so we end up with MAS unable to trust the certificates generated by LetsEncrypt staging.

At present there is no workaround for this, so do not use the LetsEncrypt staging certificate issuer.

Role Variables - General

dns_provider

Required
Environment Variable: DNS_PROVIDER
Default: None

mas_instance_id:

Required
Environment Variable: MAS_INSTANCE_ID
Default: None

mas_workspace_id:

Required
Environment Variable: MAS_WORKSPACE_ID
Default: None

mas_domain

Required
Environment Variable: MAS_DOMAIN
Default: None

ocp_ingress

Optional
Environment Variable: OCP_INGRESS
Default: None

custom_labels

List of comma separated key=value pairs for setting custom labels on instance specific resources.

Optional
Environment Variable: CUSTOM_LABELS
Default: None

Role Variables - Cloudflare DNS Integration

cloudflare_email

Required if dns_provider is set to cloudflare
Environment Variable: CLOUDFLARE_EMAIL
Default: None

cloudflare_apitoken

To generate an API token follow the Cloudflare documentation.

Required if dns_provider is set to cloudflare
Environment Variable: CLOUDFLARE_APITOKEN
Default: None

cloudflare_zone

This is your domain name that is managed by Cloudflare (e.g. mydomain.com).

Required if dns_provider is set to cloudflare
Environment Variable: CLOUDFLARE_ZONE
Default: None

cloudflare_subdomain

Set this to the name of the subdomain under your Cloudflare domain where you would like to manage the MAS DNS entires if you don't want MAS to use the top-level domain itself. In other words cloudflare_subdomain.cloudflare_zone should equal mas_domain.

Optional
Environment Variable: CLOUDFLARE_SUBDOMAIN
Default: None

Role Variables - IBM Cloud Internet Services DNS Integration

Note

When using CIS integration, some resources will be installed in the cluster such as RBACs, API Services and CIS Webhook deployments. In OCP 4.12+, to avoid CIS webhook deployment failure at start up, this role will grant anyuid permission to cert-manager-webhook-ibm-cis service account so it can fully access the cert-manager-webhook-ibm-cis deployment pod as a workaround: oc adm policy add-scc-to-user anyuid -z cert-manager-webhook-ibm-cis -n ibm-common-services

cis_email

Required if dns_provider is set to cis
Environment Variable: CIS_EMAIL
Default: None

cis_apikey

Required if dns_provider is set to cis
Environment Variable: CIS_APIKEY
Default: None

cis_crn

Required if dns_provider is set to cis
Environment Variable: CIS_CRN
Default: None

cis_subdomain

Optional
Environment Variable: CIS_SUBDOMAIN
Default: None

cis_enhanced_security

Set this to true to enable the enhanced IBM CIS DNS integration security - which includes: - Enabling WAF firewall disabling rules that affect MAS application functionalities - Enabling Proxy for DNS entries - Using an expanded list of DNS entries - Ensuring there are no wildcard DNS entry in CIS - Creating Edge Certificates in CIS instance See https://cloud.ibm.com/docs/cis?topic=cis-manage-your-ibm-cis-for-optimal-security for more details.

Optional
Environment Variable: CIS_ENHANCED_SECURITY
Default: false

Role Variables - Enhanced IBM CIS DNS Integration Secruity

See the "cis_enhanced_security" variable above for details.

cis_waf

Optional
Environment Variable: CIS_WAF
Default: true

cis_proxy

Optional
Environment Variable: CIS_PROXY
Default: false

cis_service_name

Set this to override the default CIS service name that would otherwise be created as {ClusterName}-cis-{mas_instance_id} (where Cluster Name is derived automatically from the cluster)

Optional
Environment Variable: CIS_SERVICE_NAME

update_dns

Set this to false if you want to not update DNS entries if they already exist

Optional
Environment Variable: UPDATE_DNS_ENTRIES
Default: true

delete_wildcards

Set this to true to force deletion of wildcard dns entries in cis

Optional
Environment Variable: DELETE_WILDCARDS
Default: false

override_edge_certs

Set this to false to not override and delete any existing edge certificates in cis instance when creating new edge certificates

Optional
Environment Variable: OVERRIDE_EDGE_CERTS
Default: true

output_dir

Location to output the edge-routes-{mas_instance_id}.txt

Optional
Environment Variable: OUTPUT_DIR
Default: . (which will set the directory file in ibm/mas_devops)

Role Variables - AWS Route 53

Prerequisites

To run this role successfully you must have already installed the AWS CLI. Also, you need to have AWS user credentials configured via aws configure command or simply export AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables with your corresponding AWS username credentials prior running this role.

Note

In some cases, the Route 53 zone may not resolve the certificate challenges generated by IBM Certificate Manager, which could cause a problem while issuing the public certificates via Let's Encrypt. In this case, a manual workaround might be needed in cert-manager-controller pod to enable recursive nameservers.

For more details on how to apply this workaround, refer to this documentation.

This workaround is not automated, as most of the times this is not needed, but when it is, it requires the cert-manager-controller pod to be stopped, thus we want to avoid making this behavior as standard approach.

route53_hosted_zone_name

AWS Route53 Hosted Zone name.

Required.
Environment Variable: ROUTE53_HOSTED_ZONE_NAME
Default Value: None

route53_hosted_zone_region

AWS Route53 Hosted Zone region.

Required.
Environment Variable: ROUTE53_HOSTED_ZONE_REGION
Default Value: Same value as defined in AWS_REGION, or if none defined, then us-east-2 is the defaulted region.

route53_subdomain

If a subdomain is defined, this will be used to create the corresponding CNAME entries in the targeted Route53 hosted zone instance. Therefore, the Route53 subdomain + the Route53 hosted zone name defined, when combined, needs to match with the chosen MAS Domain, otherwise the DNS records won't be able to get resolved.

Example:
MAS Top Level Domain: my-mas-instance.mycompany.com
AWS Route53 hosted zone name: mycompany.com
AWS Route53 subdomain: my-mas-instance

Optional.
Environment Variable: ROUTE53_SUBDOMAIN
Default Value: None

route53_email

AWS Route53 contact e-mail. Will be set in the cluster issuer created in order to receive alerts.

Optional.
Environment Variable: ROUTE53_EMAIL
Default Value: None.

Role Variables - CloudPak for Data

cpd_instance_namespace

Namespace where the Cloud Pak for Data is installed and the cpd route exists. If set, then this role will also attempt to configure public certificates to the CPD route using the DNS provider defined.

Optional
Environment Variable: CPD_INSTANCE_NAMESPACE
Default Value: None.

cpd_prod_issuer_name

Define the certificate issuer responsible for generating the public certificate for your CPD route. If not set, then it will use same issuer set for MAS instance.

Optional
Environment Variable: CPD_PROD_ISSUER_NAME
Default Value: Same certificate issuer used for MAS instance.

cpd_custom_domain

Define the custom domain for your CPD route. If not set, then it will use same domain set for MAS instance.

Optional
Environment Variable: CPD_CUSTOM_DOMAIN
Default Value: cp4d.{{ mas_domain }}.

Example Playbook - CIS or Cloudflare

---
- hosts: localhost
  any_errors_fatal: true
  vars:
    dns_provider: cis OR cloudflare
    mas_instance_id: inst1
    mas_domain: mydomain.com
    cis_crn: xxx
    cis_apikey: xxx
    cis_email: xxx
  roles:
    - ibm.mas_devops.suite_dns

Example Playbook - AWS Route 53

---
- hosts: localhost
  any_errors_fatal: true
  vars:
    dns_provider: route53
    mas_instance_id: inst1
    mas_domain: inst1.mydomain.com
    aws_access_key_id: xxx
    aws_secret_access_key: xxx
    route53_hosted_zone_name: mydomain.com
    route53_hosted_zone_region: us-east-2
    route53_subdomain: inst1
    route53_email: anyemail@test.com
  roles:
    - ibm.mas_devops.suite_dns

License

EPL-2.0