MAS DevOps Ansible Collection Ansible CLI
Home Ansible Automation Platform OCP Install Cloud Pak For Data Install Core Add AIBroker Add IoT Add Manage Add Monitor Add Optimizer Add Predict Add Visual Inspection Update Upgrade Uninstall Core Backup & Restore ocp_cluster_monitoring ocp_config ocp_deprovision ocp_efs ocp_github_oauth ocp_login ocp_node_config ocp_provision ocp_roks_upgrade_registry_storage ocp_upgrade ocp_verify appconnect aws_bucket_access_point aws_documentdb_user aws_policy aws_route53 aws_user_creation aws_vpc cert_manager cis common-services configure_manage_eventstreams cos cos_bucket cp4d_admin_pwd_update cp4d cp4d_service db2 dro eck grafana ibm_catalogs kafka nvidia_gpu mongodb ocs sls turbonomic uds mirror_case_prepare mirror_extras_prepare mirror_images mirror_ocp ocp_contentsourcepolicy ocp_simulate_disconnected_network registry suite_app_config suite_app_install suite_app_uninstall suite_app_upgrade suite_app_rollback suite_app_backup_restore suite_certs suite_config suite_db2_setup_for_manage suite_dns suite_install suite_manage_attachments_config suite_manage_birt_report_config suite_manage_bim_config suite_manage_customer_files_config suite_manage_imagestitching_config suite_manage_import_certs_config suite_manage_load_dbc_scripts suite_manage_logging_config suite_manage_pvc_config suite_uninstall suite_upgrade suite_rollback suite_verify suite_backup_restore ansible_version_check entitlement_key_rotation gencfg_jdbc gencfg_watsonstudio gencfg_workspace install_operator gencfg_mongo
Home Roles: Suite Mgmt suite_dns DNS management Let's Encrypt Integration Role Variables - General Role Variables - Cloudflare DNS Integration Role Variables - IBM Cloud Internet Services DNS Integration Role Variables - Enhanced IBM CIS DNS Integration Secruity Role Variables - AWS Route 53 Prerequisites Role Variables - CloudPak for Data Example Playbook - CIS or Cloudflare Example Playbook - AWS Route 53 License

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:

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:

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¤

mas_instance_id:¤

mas_workspace_id:¤

mas_domain¤

ocp_ingress¤

cert_manager_namespace¤

Namespace where Certificate Manager is installed.

custom_labels¤

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

Role Variables - Cloudflare DNS Integration¤

cloudflare_email¤

cloudflare_apitoken¤

To generate an API token follow the Cloudflare documentation.

cloudflare_zone¤

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

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.

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¤

cis_apikey¤

cis_crn¤

cis_subdomain¤

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.

Role Variables - Enhanced IBM CIS DNS Integration Secruity¤

See the "cis_enhanced_security" variable above for details.

cis_waf¤

cis_proxy¤

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)

update_dns¤

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

delete_wildcards¤

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

override_edge_certs¤

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

output_dir¤

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

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.

route53_hosted_zone_region¤

AWS Route53 Hosted Zone 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

route53_email¤

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

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.

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.

cpd_custom_domain¤

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

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