Configuring Let's Encrypt for Maximo Application Suite on Amazon Web Services

When you install Maximo® Application Suite along with a Stack on Amazon Web Services using the automated deployment offerings, Maximo Application Suite uses self-signed certificates.

If you want to use well-known certificates that are signed by Certificate Authority such as Let's Encrypt, install and configure Let's Encrypt and Route53 on Amazon Web Services.

Before you begin

Complete the following tasks:

Create an Access Key in the Amazon Web Services console.
Create an IAM policy so that certificate manager is able to add records to Route53 in order to solve the DNS01 challenges. To create an IAM policy, complete the following steps:
1. Login to the Amazon Web Services console, then search for IAM and click the first option that is displayed.
2. Click Policies and then click Create Policy.
3. Go to the JSON tab and paste the following JSON:
```
{
	"Version": "2012-10-17",
	"Statement": [{
			"Effect": "Allow",
			"Action": "route53:GetChange",
			"Resource": "arn:aws:route53:::change/*"
		},
		{
			"Effect": "Allow",
			"Action": [
				"route53:ChangeResourceRecordSets",
				"route53:ListResourceRecordSets"
			],
			"Resource": "arn:aws:route53:::hostedzone/*"
		},
		{
			"Effect": "Allow",
			"Action": "route53:ListHostedZonesByName",
			"Resource": "*"
		}
	]
}
```
4. Click Next: Tags, then Next: Review. Provide Name and Description values.
5. Click Create policy.

Procedure

Amazon Web Services Route 53 configuration
1. In Route53, go to Hosted Zones, click your domain, and then click Create record.
  
  For example:
  
  Tip: For all examples, replace the parameters given in the example with your own parameters.
2. Add a CNAME record for your Maximo Application Suite instance ID:
  1. Record Name: <mas-instance-id>
  2. Record Value: Load Balancer endpoint, which is located under your Hosted Zones. Filter by your cluster unique ID, and then copy the corresponding value for your cluster ingress.
  Use the second option. For example, the record name beginning with *.apps.masocp- and the value beginning with a77 as shown in the screen shot of the previous step.
  
  Note: Save the instance ID name so you can later use it during the Maximo Application Suite installation.
3. Add a new wildcard CNAME record as the following:
  1. Record Name: *.<mas-instance-id>
  2. Record Value: Load Balancer endpoint, which is found under your Hosted Zones. Filter by your cluster unique ID, and then copy the corresponding value for your cluster ingress.
  Use the second option. For example, the record name beginning with *.apps.masocp- and the value beginning with a77 as shown in the screen shot of the previous step.
  For example:
4. Click Create records.

Configure a Let's Encrypt cluster issuer for Maximo Application Suite.

Run the following script in your terminal. You need to be logged into the cluster via oc login command. The script will create a custom cluster issuer named prod-route53-issuer in your cluster.


# Export the namespace/project where IBM Certificate Manager is installed in your cluster. Example: ibm-common-services.
CERT_MANAGER_NAMESPACE=ibm-common-services

# Export your AWS secret access key.
SECRET_ACCESS_KEY=<your aws access key>

# Export your AWS secret access ID.
SECRET_ACCESS_ID=<your aws access id>

# Export your email adress where you'll get alerts and notifications from Let's Encrypt certificates
EMAIL_ADDRESS=test@test.com

# Export your route53 hosted zone id.
# Find it under AWS console > Route53 > Hosted Zones > search for your Route53 instance, the hosted zone id will show at the right hand side.
HOSTED_ZONE_ID=<your route53 hosted zone id>

# Create a secret for secret-access-key
oc create secret generic prod-route53-credentials-secret --from-literal=secret-access-key=${SECRET_ACCESS_KEY} -n ${CERT_MANAGER_NAMESPACE}

# create a cluster issuer
cat <<EOF > cluster-issuer.yaml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: prod-route53-issuer
spec:
  acme:
    email: ${EMAIL_ADDRESS}
    preferredChain: ''
    privateKeySecretRef:
      name: letsencrypt-prod
    server: 'https://acme-v02.api.letsencrypt.org/directory'
    solvers:
      - dns01:
          route53:
            accessKeyID: ${SECRET_ACCESS_ID}
            hostedZoneID: ${HOSTED_ZONE_ID}
            region: us-east-1
            secretAccessKeySecretRef:
              key: secret-access-key
              name: prod-route53-credentials-secret
EOF
oc apply -f cluster-issuer.yaml -n ${CERT_MANAGER_NAMESPACE}

To check if this was properly created, log in to your Red Hat® OpenShift® cluster, go to Administration > Custom Resource Definitions, search for ClusterIssuer > Instances, search for prod-route53-issuer and click it. The cluster issuer shows the following message:


The ACME account was registered with the ACME server.

Select the Suite > YAML tab and in the spec section of the Suite YAML, add cluster issue and domain parameters.

---
spec:
  certificateIssuer:
    duration: 8760h0m0s
    name: prod-route53-issuer
    renewBefore: 720h0m0s
  domain: <<masinstance_id>>.<<domain>>

Delete the finalizer section from the same Suite YAML to force a reconciliation, and then save the YAML file.
```
finalizers: 
  - core.mas.ibm.com/finalizer
```
In Networking under Routes of project mas-<mas_instance_id>-core, wait for the Routes to regenerate for the namespace.
Login to the Maximo Application Suite administrator screen and verify the certificate signer.

Note: If IBM® Maximo Manage is deployed, the changes might take some time to take effect in Maximo Manage.

Optional: Configure recursive nameservers

On the Red Hat OpenShift web console, select the ibm-common-services project.
In the Details tab of workloads > -> deployment > ibm-cert-manager-operator, scale down the pod from 1 to 0.
In the Deployment tab, select the cert-manager controller.

Add the following lines in the yaml file.

- '--dns01-recursive-nameservers-only'
- '--dns01-recursive-nameservers=8.8.8.8:53'

The following is a sample yaml file.

   image: >-
            icr.io/cpopen/cpfs/icp-cert-manager-controller@sha256:1927c16a4dd369c56fa6d2d1897d3ea3d333a3217b8c05ea32b6617c94833a0e
          args:
            - >-
              --acme-http01-solver-image=icr.io/cpopen/cpfs/icp-cert-manager-acmesolver@sha256:e8f50ee7b08dc96627e138e9b0d98ed5848c7b4ad92491962c13ef32b2866591
            - '--cluster-resource-namespace=ibm-common-services'
            - '--leader-election-namespace=ibm-common-services'
            - '--dns01-recursive-nameservers-only'
            - '--dns01-recursive-nameservers=8.8.8.8:53'
      serviceAccount: ibm-cert-manager-controller
      dnsPolicy: ClusterFirst