Prerequisites

• Ensure that you have these CLI tools installed:
  • AWS CLI
  • Terraform
  • Kubectl
  • Helm - Optional, for deployment from AWS Marketplace
  • eksctl - Optional, for deployment from AWS Marketplace
• Configured AWS CLI with Access Keys or assumed role with sufficient permissions
• You have downloaded the Terraform IaC from here

Configuring Terraform Remote Backend

Disclaimer: The Terraform code provisions the minimum required infrastructure. You may have to modify some of the parameters to ensure that it works in your environment. You may refer to the official AWS and Hashicorp documentation for more details

1. Create a terraform.tfvars file in the backend directory and ensure the following variables are included
   

   app_name="<your-app-name>

   
   

2. Run terraform init
3. Run terraform plan to observe the resources that will be deployed (optional)
4. Once verified, run terraform apply -auto-approve
5. Once the backend has been deployed, go to the infrastructure directory and open main.tf
6. Find the block:
   

   backend "s3" {     bucket         = "xxx"     key            = "terraform.infrastructure.tfstate"     region         = "xxx"     dynamodb_table = "xxx" }

   
   

7. Fill in the xxx with the service details that you have created on step 1 - 5

Note: This process will create a local Terraform state. The remote state will only apply for infrastructure.

Deploying AWS Infrastructure

1. Create a terraform.tfvars file and ensure the following variables are included

   app_name=”<your-app-name>” cluster_name=”<your-eks-cluster-name>” rds_username=”<your-rds-username>” rds_password=”<your-rds-password>”

   
   

2. Run terraform init
3. Run terraform plan to observe the resources that will be deployed (optional)
4. Once verified, run terraform apply -auto-approve

Note: This step will take some time, around 20-30 minutes.

Core Services and Resource Deployed

These are the core services and resources (non exhaustive) list deployed from Terraform:

• Virtual Private Cloud (VPC)
• Elastic Kubernetes Service (EKS)
• Elastic File System (EFS)
• Relational Database System (RDS) - Serverless
• Helm Charts:
  • AWS Load Balancer Controller
  • AWS EFS CSI Driver
• EC2 Servers - Created through EKS provisioning

Deploying Joget DX 8

1. Download the Kubernetes manifest here.
2. Modify the fileSystemId in StorageClass to the one that has been deployed through terraform in prior steps.
3. Run kubectl apply -f joget-dx8-tomcat9-deployment.yaml
4. Wait for the containers to initialize. Run kubectl get pods -A to obtain the status of the pods.

Note: The manifest file creates a Storage Class with EFS CSI as provisioner which will dynamically create a Persistent Volume.

Accessing Joget through Load Balancer

1. Run kubectl get ingress -A . You should see the DNS under Address column as follows:

   k8s-namespace-RANDOM-STRING.REGION.elb.amazonaws.com

   
   

2. Use the Address and go to /jw . It will redirect you to the database setup.
   
   
3. Enter your database information on the above page

Note: The Terraform IaC has RDS Aurora Serverless included in the Infrastructure, and as such, it will be deployed alongside the EKS. You may use the RDS to better synergize with the VPC configuration. Ensure that you use the writer endpoint when setting up Joget database

1. Click Save. Wait for the database to be setup
2. Once the setup is complete, click Done. It will redirect you to the Joget main page

Common Errors

Terraform

• Error: error configuring S3 Backend: no valid credential sources for S3 Backend found.

• You may have not setup your AWS Credentials yet, or if you are assuming role, your session may have expire.
• Solution: Run aws configure and input the Access Keys or export the Access Keys into your terminal environment or assume the previous role once again to get new session credentials.

Kubernetes/EKS

• Unable to locate credentials. You can configure credentials by running "aws configure".

• • You may have not setup your AWS Credentials yet, or if you are assuming role, your session may have expire.
  • Solution: Run aws configure and input the Access Keys or export the Access Keys into your terminal environment or assume the previous role once again to get new session credentials.

• You must be logged in to the server (Unauthorized)

• • This happens when you are using different credentials - different users or roles to access the cluster. If you are the cluster creator, you should be able to access the cluster
  • Solution: 
    1. In the Terraform Iac, go to infrastructure/compute/eks/eks.tf
    2. Under the module “eks”, add the following
       1. If you are using users credential:

          aws_auth_users= [
              {
                userarn  = "arn:aws:iam::<account-id>:user/<username>"
                username = "<username>"
                groups   = ["system:masters"]
              }
           ]

       2. If you are using roles, you may append the aws_auth_roles block like so:

          {
                rolearn  = “arn:aws:iam::<account-id>:role/<role-name>”
                username = "<role-name>"
                groups   = ["system:masters"]
          }

AWS Marketplace

• Quicklaunch: Cloudformation Stack failed to be created

  • There can be numerous reasons the stack can be failed.
  • The most common and important reason is the Helm chart failed to be deployed.
  • Check the reason of failure from the Cloudformation console > Quicklaunch stack > Helm stack in the reason column.