AWS
Before you can perform a ForgeOps deployment on a Kubernetes cluster running on AWS, you must complete these prerequisite tasks:
forgeops
and forgeops-extras
repositories
Get the forgeops
and forgeops-extras
repositories:
-
Clone the repositories. For example:
$ git clone https://github.com/ForgeRock/forgeops.git $ git clone https://github.com/ForgeRock/forgeops-extras.git
Both repositories are public; you do not need credentials to clone them.
-
Check out the
forgeops
repository’srelease/7.5-20240618
branch:$ cd /path/to/forgeops $ git checkout
release/7.5-20240618
Depending on your organization’s repository strategy, you might need to clone the repository from a fork, instead of cloning ForgeRock’s master repository. You might also need to create a working branch from the
release/7.5-20240618
branch. For more information, refer to Repository Updates. -
Check out the
forgeops-extras
repository’smaster
branch:$ cd /path/to/forgeops-extras $ git checkout
master
Third-party software
Before performing a ForgeOps deployment, obtain non-ForgeRock software and install it on your local computer.
The versions listed in the following table have been validated for ForgeOps deployments on Amazon Web Services. Earlier and later versions will probably work. If you want to try using versions that are not in the table, it is your responsibility to validate them.
Install the following third-party software:
Software | Version | Homebrew package |
---|---|---|
Python 3 |
3.12.4 |
|
Bash |
5.2.26 |
|
Docker client |
26.1.4 |
|
Kubernetes client (kubectl) |
1.30.2 |
|
Kubernetes context switcher (kubectx) |
0.9.5 |
|
Kustomize |
5.4.2 |
|
Helm |
3.15.2 |
|
JSON processor jq |
1.7.1 |
|
Terraform |
1.5.7 |
|
Six (Python compatibility library) |
1.16.0 |
|
Setup tools (Python) |
70.1.1 |
|
Amazon AWS Command Line Interface |
2.17.1 |
|
AWS IAM Authenticator for Kubernetes |
0.6.20 |
|
Docker engine
In addition to the software listed in the preceding table, you’ll need to start a virtual machine that runs Docker engine.
-
On macOS systems, use Docker Desktop or an alternative, such as Colima.
-
On Linux systems, use Docker Desktop for Linux, install Docker machine from your Linux distribution, or use an alternative, such as Colima.
For more information about using Colima when performing ForgeOps deployments, refer to this article.
The default configuration for a Docker virtual machine provides adequate resources for a ForgeOps deployment.
For users running Microsoft Windows
ForgeRock supports ForgeOps deployments on macOS and Linux. If you have a Windows computer, you’ll need to create a Linux VM. We tested the following configurations:
-
Hypervisor: Hyper-V, VMWare Player, or VMWare Workstation
-
Guest OS: Current Ubuntu LTS release with 12 GB memory and 60 GB disk space
-
Nested virtualization enabled in the Linux VM.
Perform all the procedures in this documentation within the Linux VM. In this documentation, the local computer refers to the Linux VM for Windows users.
The Minikube implementation on Windows Subsystem for Linux (WSL2) has networking issues. As a result, consistent access to the ingress controller or the apps deployed on Minikube is not possible. This issue is tracked here. Do not attempt to perform ForgeOps deployments on WSL2 until this issue is resolved. |
Setup for AWS
Perform these steps to set up an AWS environment that meets the requirements for ForgeOps deployments:
-
Create and configure an IAM group:
-
Create a group with the name
forgeops-users
. -
Attach the following AWS preconfigured policies to the
forgeops-users
group:-
IAMUserChangePassword
-
IAMReadOnlyAccess
-
AmazonEC2FullAccess
-
AmazonEC2ContainerRegistryFullAccess
-
AWSCloudFormationFullAccess
-
-
Create two policies in the IAM service of your AWS account:
-
Create the
EksAllAccess
policy using theeks-all-access.json
file in the /path/to/forgeops/etc/aws-example-iam-policies directory. -
Create the
IamLimitedAccess
policy using theiam-limited-access.json
file in the /path/to/forgeops/etc/aws-example-iam-policies directory.
-
-
Attach the policies you created to the
forgeops-users
group.Remember, a ForgeOps deployment is a reference implementation, and is not for production use. The policies you create in this procedure are suitable for ForgeOps deployments. When you create a project plan, you’ll need to determine how to configure AWS permissions.
-
Assign one or more AWS users who will perform ForgeOps deployments to the
forgeops-users
group.
-
-
If you haven’t already done so, set up your aws command-line interface environment using the aws configure command.
-
Verify that your AWS user is a member of the
forgeops-users
group:$ aws iam list-groups-for-user --user-name my-user-name --output json { "Groups": [ { "Path": "/", "GroupName": "forgeops-users", "GroupId": "ABCDEFGHIJKLMNOPQRST", "Arn": "arn:aws:iam::048497731163:group/forgeops-users", "CreateDate": "2020-03-11T21:03:17+00:00" } ] }
-
Verify that you are using the correct user profile:
$ aws iam get-user { "User": { "Path": "/", "UserName": "my-user-name", "UserId": "...", "Arn": "arn:aws:iam::01...3:user/my-user-name", "CreateDate": "2020-09-17T16:01:46+00:00", "PasswordLastUsed": "2021-05-10T17:07:53+00:00" } }
Kubernetes cluster creation
ForgeRock provides Terraform artifacts for Amazon EKS cluster creation. Use them to create a cluster that supports ForgeOps deployments. After performing a ForgeOps deployment, you can use your cluster as a sandbox to explore Ping Identity Platform customization.
When you create a project plan, you’ll need to identify your organization’s preferred infrastructure-as-code solution, and, if necessary, create your own cluster creation automation scripts.
Here are the steps the ForgeOps team follows to create a Kubernetes cluster on Amazon EKS:
-
Copy the file that contains default Terraform variables to a new file:
-
Change to the /path/to/forgeops-extras/terraform directory.
-
Copy the terraform.tfvars file to override.auto.tfvars [2].
Copying the terraform.tfvars file to a new file preserves the original content in the file.
-
-
Determine the cluster size: small, medium, or large.
-
Define your cluster’s configuration:
-
Open the override.auto.tfvars file.
-
Determine the location of your cluster’s configuration in the override.auto.tfvars file:
Cluster size Section containing the cluster configuration Small
cluster.tf_cluster_eks_small
Medium
cluster.tf_cluster_eks_medium
Large
cluster.tf_cluster_eks_large
-
Modify your cluster’s configuration by setting values in the section listed in the table:
-
Modify your cluster’s configuration by setting values in the section listed in the table:
-
Set the value of the
enabled
variable totrue
. -
Set the value of the
meta.cluster_name
variable to the name of the Amazon EKS cluster you’ll create. -
Set the values of the
location.region
andlocation.zones
variables to the region and zones where you’ll perform the ForgeOps deployment.Before continuing:
-
Go to the Amazon Elastic Kubernetes Service endpoints and quotas page and verify the region you’re specifying supports Amazon EKS.
-
Run the aws ec2 describe-availability-zones --region region-name command to identify three availability zones in your AWS region.
-
-
-
Save and close the override.auto.tfvars file.
-
-
Ensure your region has an adequate CPU quota for a ForgeOps deployment.
Locate these two variables in your cluster’s configuration in the override.auto.tfvars file:
-
node_pool.type
: the machine type to be used in your cluster -
node_pool.max_count
: the maximum number of machines to be used in your cluster
Your quotas must be large enough to let you allocate the maximum number of machines in your region. If your quotas are too low, request and wait for a quota increase from Amazon Web Services before attempting to create your cluster.
-
-
Create a cluster using Terraform artifacts in the
forgeops-extras
repository:-
Change to the directory that contains Terraform artifacts:
$ cd /path/to/forgeops-extras/terraform
-
Run the tf-apply script to create your cluster:
$ ./tf-apply
Respond
yes
to theDo you want to perform these actions?
prompt.When the tf-apply script finishes, it issues a message that provides the path to a kubeconfig file for the cluster.
The script creates:
-
The EKS cluster
-
The
fast
storage class -
The
ds-snapshot-class
volume snapshot class
The script deploys:
-
An ingress controller
-
Certificate manager
-
-
-
Set your Kubernetes context to reference the new cluster by setting the
KUBECONFIG
environment variable as shown in the message from the tf-apply command’s output. -
To verify the tf-apply script created the cluster, log in to the AWS console. Access the console panel for the Amazon Elastic Kubernetes Service, and then list the EKS clusters. The new cluster should appear in the list of Kubernetes clusters.
Hostname resolution
Set up hostname resolution for the Ping Identity Platform servers you’ll deploy in your namespace:
-
Get the ingress controller’s FQDN from the
EXTERNAL-IP
column of the kubectl get services command output:$ kubectl get services --namespace ingress-nginx NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE ingress-nginx-controller LoadBalancer 10.100.43.88 k8s-ingress ...elb.us-east-1.amazonaws.com 80:30005/TCP,443:30770/TCP 62s ingress-nginx-controller-admission ClusterIP 10.100.2.215 <none> 443/TCP 62s
-
Run the host command to get the ingress controller’s external IP addresses. For example:
$ host k8s-ingress ...elb.us-east-1.amazonaws.com k8s-ingress ...elb.us-east-1.amazonaws.com has address 3.210.123.210 k8s-ingress ...elb.us-east-1.amazonaws.com has address 3.208.207.77 k8s-ingress ...elb.us-east-1.amazonaws.com has address 44.197.104.140
Depending on the state of the cluster, between one and three IP addresses appear in the host command’s output.
-
Configure hostname resolution for the ingress controller:
-
Choose an FQDN (referred to as the deployment FQDN) that you’ll use when you deploy the Ping Identity Platform, and when you access its GUIs and REST APIs.
Examples in this documentation use
forgeops.example.com
as the deployment FQDN. You are not required to useforgeops.example.com
; you can specify any FQDN you like. -
If DNS does not resolve your deployment FQDN, add an entry to the /etc/hosts file that maps the ingress controller’s external IP address to the deployment FQDN. For example:
3.210.123.210 forgeops.example.com
-
forgerock
that adds labels required for clusters created by ForgeRock employees. If you’re a ForgeRock employee creating a cluster, set values for these variables.