Installation on AWS

Edit online

Detailed procedure to install the IBM Verify Identity Governance - Container on Amazon Web Services (AWS).

Overview

IBM Verify Identity Governance - Container supports deployment on Amazon Web Services (AWS) and AWS GovCloud (US) platforms using all the supported Databases and Directory Servers.

In addition, you can also Amazon Aurora PostgreSQL as an external database and Amazon Simple Email Service.

Before you begin

  1. While AWS manages the hardware infrastructure, it is important to efficiently allocate computing resources, such as memory, CPU (including virtual sockets and cores), and storage (HDD/SSD), when creating Kubernetes nodes. Here are the recommended specifications for IBM Verify Identity Governance - Container:
    • CPU: 4 Sockets with 2 Cores per socket (dedicated)
    • Storage: 150 GB HDD/SSD
    • Memory: 16-20 GB

    Select an appropriate AWS instance type. Each instance type comes with its unique resource capabilities and costs. The selected instance type is used to create Nodegroups for your cluster. It is recommended to use instance types such as t3, m5, m6, and r series. Note that the availability of these instances may vary depending on your region.

  2. You must have an AWS account.
  3. Create an IAM user. Grant the permissions to IAM User as per the user_policy.json file located at [Starter_Kit]/cloud/aws/util/

    This documentation is based on these policies. These policies enable the user to create, view, and delete the essential resources required for Amazon Elastic Kubernetes Service (EKS). In the event of additional configurations or any encountered inconveniences, you may adjust the permissions as per your needs.

  4. Download and install the following software components:
    • Install and set up Kubectl version 1.28 on Linux | Kubernetes. For detailed information, see this documentation.
    • Download the install Helm version 3.x from this page.
    • Download and install the latest version of AWS CLI. For detailed information, see this documentation.
    • Download and install Eksctl version 0.161.0 (or higher) from this page.
  5. Next, connect AWS CLI to your AWS account. You must have programmatic access for it. For details, see this documentation.
    Attention: AWS and AWS GovCloud utilize distinct region names. Ensure that you provide accurate details when prompted later in the deployment process.

Amazon Aurora PostgreSQL

Amazon Aurora PostgreSQL is a fully-managed, PostgreSQL–compatible, and ACID–compliant relational database engine that combines the speed, reliability, and manageability of Amazon Aurora with the simplicity and cost-effectiveness of open-source databases.

Reference: AWS documentation
Hardware recommendations
CPU: 8 Sockets, 2 Cores per socket (dedicated)
Storage: 150 GB HDD/SSD
Memory: 32 GB
There are two ways of creating the Amazon Aurora database.
  1. Easy Create approach:
  2. Standard Create approach
Here is an example of Standard approach:
  1. Open the Amazon RDS Console and click Create Database.
  2. Choose database creation method as Standard Create.
  3. Under credential settings either choose Auto generate a password option or specify your own password.
  4. Configure the instance using your preferred instance type, such as Burstable classes
  5. Specify the VPC and subnets for your cluster, allowing public access if needed. You can also choose different VPC configurations.
  6. Under Connectivity, enable public access.
  7. In the Additional Configuration section, specify an initial database name, and make a note of it for use during the configure.sh step.
  8. Leave the remaining parameters to default, or edit if necessary.
  9. After the database is created, note down the credentials.
  10. Add a rule in security group of the database to allow access to port 5432.
  11. Provide the appropriate details in config.yaml file. Here is an example:
    
db:
  # Use lowercase only for username while configuring postgresdb
  user: postgres
  password: password_here
  dbtype: postgres
  ip: database-1.cluster-caa5kqguj58p.ap-south-1.rds.amazonaws.com
  port: 5432
  name: isvgim
  admin: postgres
  adminPwd: password_here
  security.protocol:
  tablespace.location.data: /isimdata
  tablespace.location.indexes: /isimindex
  12. Install the starter kit.

Amazon Simple Email Service

Amazon Simple Email Service (SES) is a cloud-based email service by Amazon Web Services. It allows you to send and receive emails effortlessly, scale your email operations, and ensure high deliverability. It provides features like email authentication, monitoring, and easy integration with other AWS services, making it a reliable solution for managing email communication in the cloud.

Perform the following steps to configure Amazon SES.
  1. Set up your AWS SES configuration by referring these instructions.
  2. IBM Verify Identity Governance - Container SMTP currently supports basic authentication and SSL authentication. To generate SMTP Credentials, refer this documentation.
  3. If you want to configure SSL connection from IBM Verify Identity Governance - Container to AWS SES, then you must add certificate to IBM Verify Identity Governance - Container application. Perform the following steps:
    1. Execute the following command to retrieve the certificate from AWS SES On Linux terminal. Replacing <region-name> with the desired region. For example: 
      openssl s_client -crlf -starttls smtp -connect email-smtp.ap-south-1.amazonaws.com:587 | awk '/-----BEGIN CERTIFICATE-----/,/-----END CERTIFICATE-----/' > smtp_server_certificate.pem
    2. Store the certificate in the [STARTER]/config/certs/ directory with the filename smtp_server_certificate.pem
    3. During the installation of IBM Verify Identity Governance - Container, when you run the configure.sh, provide this certificate name.

Installation

There are multiple approaches to create an Elastic Kubernetes Cluster, and this AWS documentation topic describes the various options by referring to this AWS documentation.

This document describes one of the approaches. The example snippets presented here represent a basic configuration. For detailed background information, references to Amazon documentation are provided at each step.

Perform the following steps.
Create an Elastic Kubernetes Cluster (EKS) Role
To begin with, create an EKS-Cluster Role which enables secure and controlled interaction between Kubernetes workloads and AWS services within an EKS cluster. You can create it by performing the steps described in this documentation.
Here is an example:
  1. Log in to Identity Access Management (IAM).
  2. Click Create Role > AWS Service
  3. Under Use Case section, select EKS and select EKS-CLuster.
  4. Provide the required details, and create the role (for example: Test-eksServiceRole).
  5. Update the remaining role settings according to your specific requirements as needed.
Create a CloudFormation Stack
This is a template-driven method to automatically set up all the required resources for a Kubernetes cluster. This includes important VPC components such as subnets, route tables, gateways and Elastic IPs. It simplifies the process of creating and managing Kubernetes clusters on AWS, making it efficient and well-organized.
Reference: AWS documentation
Here is an example:
  1. Go to CloudFormationStack.
  2. Click Create and choose the option to specify the template using an Amazon S3 URL.
  3. Retrieve the S3 URL from this page.
  4. Copy the S3 URL from one of the 3 subsections.
  5. Paste the S3 URL in Create Stack options. If needed, you can make any necessary modifications using the Designer tool. Create a CloudFormationStack (for example: Test-eksCloudFormation).
  6. Leave the remaining parameters to default, or edit if necessary.
Create the EKS Cluster
EKS Cluster allows you to run containers at scale and deploy, manage, and scale containerized applications efficiently in a highly available and secure environment.
Reference: Perform second step onwards from this page.
Here is an example:
  1. Go to Elastic Kubernetes Service, and click Create.
  2. Provide a Name: (for example:)Test-EKS-Cluster
  3. Specify a Version: 1.28 (recommended)
  4. Associate the cluster with the Cluster Service Role named Test-eksServiceRole that you created in EKS-Cluster Role step.
  5. For Networking, VPC, Subnets, Security Group settings, choose the ones created by Test-eksCloudFormation.
  6. Leave the remaining parameters to default, or edit as per your requirements if necessary.
Create a NodeGroup
Node groups are a way to organize and manage the worker nodes that run your containerized applications. These nodes are the designated locations where pods are scheduled for execution. You can create 3 types of Node groups as described here.
It is advisable to use Amazon EKS managed node groups, so that provisioning and maintaining the nodes is managed by AWS itself.
It is recommended to refrain from selecting the Fargate option, as it is specifically designed for stateless containers and lacks the capability to directly access the underlying EC2 instances or have dynamic provision of persistent volume.
To create a managed node group, see this documentation.
You must create Amazon EKS node IAM role before creating NodeGroup. See this topic.
Here is an example:
  1. Log in to IAM and create node IAM role (for example: Test-eksNodeGroupRole) with following policies.
  2. In the Use Case section, select EC2 for the specific use case.
  3. Attach these policies:
    • AmazonEC2ContainerRegistryReadOnly
    • AmazonEKS_CNI_Policy
    • AmazonEKSWorkerNodePolicy
  4. Next, create Node Group. Click on your Cluster > Compute tab > Add Node Group.
    • Provide a Name: (for example) Test-eksNodeGroup
    • Specify the Node IAM role: Test-eksNodeGroupRole (the one you had created earlier)
    • Choose the appropriate Subnets created through CloudFormation Stack
    • Refer the Persistent Storage section. If you have selected EBS as storage, then select the desired size as 1 node and minimum nodes as >=0. If you did not select EBS as persistent storage, select desired size as x (x>=2) and minimum nodes as >=2.
    • Choose instance type based on your hardware setup.
  5. Leave the remaining parameters to default, or edit if necessary.
Create persistent storage
For persistent storage with IBM Verify Identity Governance - Container pods, there are two options to consider:
  • Elastic Block Store (EBS): EBS is an easy-to-use, scalable, high-performance block-storage service designed for Amazon Elastic Compute Cloud (Amazon EC2). Customers are responsible for replicating EBS in another zone in case of a zone failure.
  • Elastic File System (EFS): EFS is a scalable and fully managed file storage service provided by AWS. It is designed to provide scalable, elastic, and "shared file storage" for EC2 instances and other AWS services.
  • EBS:
    Restriction: EBS is limited to a single availability zone, can be only attached to a single node exclusively, thus is suitable only for single-node clusters.
    You have two installation options outlined in this documentation: ebs-csi
    Alternatively, you can create the EBS CSI Driver using a script provided by us. Here are the steps:
    1. Customize the storageClass file located at starter-kit/cloud/aws/util/storageClass-ebs.yaml or create your own.
    2. In the file starter-kit/cloud/aws/util/ebs_csi_driver.sh , modify the values of the variables [PROFILE, REGION, CLUSTER_NAME]
    3. Make sure that kubectl is configured to point to the created cluster.
    4. Execute the script starter-kit/cloud/aws/util/ebs_csi_driver.sh
    5. The script will take care of creating the necessary roles, permissions, and the required CSI pods for you.
  • EFS: To set up EFS for your environment, perform these steps:
    1. Begin by creating the EFS file system using these guidelines. When creating the file system, take note of the following details:
      • Use the VPC that was created for your cluster.
      • While choosing Security groups for Mount Targets, create a new security group under the same VPC as the cluster, allowing inbound access for port 2049.
      • File System Policy could be left blank.
    2. Record the File System ID (ex: fs-01563c43b86c85844).
    3. Install the EFS Container Storage Interface (CSI) driver by referring to these steps.
    4. Alternatively: You can use a provided script to create the EFS CSI Driver. Perform these steps:
      1. Open the storageClass file found at starter-kit/cloud/aws/util/storageClass-efs.yaml
      2. Set parameters.fileSystemId to the ID obtained while create EFS.
      3. Modify the values of the variables [PROFILE, REGION, CLUSTER_NAME, IMAGE_REPOSITORY] in the file starter-kit/cloud/aws/util/efs_csi_driver.sh
      4. Make sure that kubectl is configured to point to the created cluster.
      5. Execute the script starter-kit/cloud/aws/util/efs_csi_driver.sh
      6. The script manages the creation of necessary roles, permissions, and required CSI pods.
    To integrate EFS as your storage solution, make the following adjustments to the starter-kit:
    1. Modify the accessModes in the PVC files located under starter-kit/helm/templates.

      Update instances of: accessModes: [ "ReadWriteOnce" ] to accessModes: [ "ReadWriteMany" ]

    2. Apply the above change to the following YAML files:
      • 070-pvc-isvd
      • 071-pvc-isvd2
      • 072-pvc-isvd-proxy
      • 075-pvc-mqshare
      • 080-pvc-postgres
      • 300-statefulset-isvgim
    3. Adjust values.yaml file with the following changes:
      • Set services.{service}.user and services.{service}.group to 1000 and 1000 as specified in storageClass-efs.yaml file.
      • Replace {service} with isvd, isvdproxy, isvgim, mqlocal, mqshare, and postgres.
      • Set `services.mqlocal.user` and `services.mqshare.user` to "app".
Install IBM Verify Identity Governance - Container
  1. Download and extract the IBM Verify Identity Governance - Container starter kit in your Linux Terminal.
  2. If you want isvgim service to be a Load Balancer, edit the helm/100-service-isvgim.yaml file and update the spec.type parameter value to LoadBalancer. Also, comment out any line containing the term sessionAffinity.
  3. If you have a multi-node setup, consider using a LoadBalancer.
  4. If you want to use Amazon Aurora as your database, see Amazon Aurora PostgreSQL section in this topic.
  5. If you want to use AWS Simple Email Service, see Amazon Simple Email Service section in this topic.
  6. Run starter/bin/configure.sh script. This script prompts for all the required parameters required for the installation process. Provide the input values as per your software and hardware setup.
    • Specify the InstallType parameter as cloud
    • Update the storage class parameter value. Based on your selection between EFS and EBS, retrieve the value of `metadata.name` from the corresponding storageClass-efs.yaml or storageClass-ebs file and assign it to the `storageclass` when prompted.
    Tip: The input values are added to the config/config.yaml file. For a detailed description of all the parameters in the config.yaml file, see config.yaml reference topic.
    Attention: IBM Verify Identity Governance - Container supports TLS v1.2 and TLS v1.3. If you plan to use TLS v1.3, ensure that your external components (such as external LDAP, external PostgreSQL database, etc.) are also configured to use TLS v1.3. Note that IBM Verify Identity Governance - Container currently does not work with IBM DB2 database configured with TLS v1.3.
  7. Ensure that the kubectl is pointing to the cluster, by using the following command: 
    aws eks update-kubeconfig --region <region_name> --name <cluster_name>
  8. Go to bin directory and run install.sh script. For detailed information, see the Installation topic.

Post-installation steps

Attention: After the installation, you must retain the Starter kit. Starter kit contains configuration files that are required for executing various scripts. The starter kit is also required when deploying the Fix Packs and Interim Fixes.
Accessing IBM Verify Identity Governance - Container Console URL
With Load Balancer
If you opted for a load balancer for IBM Verify Identity Governance - Container, perform these steps:
  1. In your Linux terminal, execute the command: kubectl get svc --namespace <namespace>

    Here, replace `<namespace>` with the one you specified during configure.sh, for example, isvgim

  2. Copy the IP address from the external ip column.
  3. Access the IBM Verify Identity Governance - Container console in your web browser using the URL: https://<external_IP>:9443/itim/console
Without Load Balancer
If you haven't modified the 100-service-isvgim.yaml file, you will need to create an inbound rule to access IBM Verify Identity Governance - Container console.
  1. Go to EKS dashboard, and select your cluster.
  2. Under Compute, click the specific EC2 (node Name).
  3. Select the Instance ID and then go Security tab.
  4. Click the Security Groups. Create an inbound rule specifying "custom TCP" with port 30943. Make it accessible from either 0.0.0.0/0 or specific IP addresses as needed. Save the rule.
  5. You should now be able to access the IBM Verify Identity Governance - Container console using https://<Node_IP>:30943/itim/console
Update mail baseUrl property
Perform the steps in this section only if you had already configured mail for IBM Verify Identity Governance - Container
  1. After the installation the URL of the IBM Verify Identity Governance - Container host is shown. This URL needs to be added to the enRoleMail.properties file.
  2. Navigate to the starter-kit/bin directory and execute the following command: ./getConfig.sh enRoleMail.properties

    This command retrieves the file from the pod and store it in the starter-kit/data directory.

  3. Open the file obtained in step 2 (enRoleMail.properties) and provide values for the following parameters:
    • If you have configured NodePort: mail.baseurl=https://<NodeIP>:<port>
    • If you have configured LoadBalancer: mail.baseurl=https://<LoadBalancerIP>:<port>
  4. Save the file.
  5. To apply the configured email properties to the IBM Verify Identity Governance - Container pod, run: ./createConfigs.sh
  6. Restart the IBM Verify Identity Governance - Container pod to activate the changes: kubectl rollout restart statefulset -n isvgim isvgim
  7. Monitor the pod status using: watch kubectl get pods -n isvgim
After the pod is active, you can send a test mail. Go to IBM Verify Identity Governance - Container Console → Configure System → Post Office. Click Test. Enter an email ID and submit. Check the receiver email account for the email.

Next steps

If you are deploying a fresh installation of IBM Verify Identity Governance - Container, then proceed to configuration activities.

If you are migrating from a legacy Identity Manager-Virtual Appliance or Identity Manager-Software Stack setup, then proceed to database migration.