Untitled
AWS Environment Setup Guide Introduction : 1.1 Purpose This document provides details instructions to create an AWS environment involving the following components for COMPASS. • App Groups : An App group is a group of application configuration items (including but not limited to IAM roles, security groups, and Cloud Map namespaces) that can be used by application deployment tasks. You can configure App groups for your application in each environment via SSP. To apply an App group to a deployment task, you need to run CICD Pipeline based on the grd.yml file that is configured with the correct App group name (via AppGrpName parameter). • Cloud Map Domain : Domains used to provide service discovery over ALB for ECS cluster • ALB : Load balancer used for routing traffic to and across ECS cluster • ECS Cluster : Manages and runs our containerized application services (React Components & Spring Boot Services) • ECS Service – Spring Boot : Backend Application Service running as ECS task (spring boot container) • ECS Service – React : Frontend service running in ECS task (Modularized React component as a container) 1.2 CICD tool access method Tools Access Method GitHub SAML login Jenkins SAML login JFrog SAML login SSP SAML login. For more information, see the Accessing SSP section. CICD Service Desk Log in via MyApps. For more information, see the Accessing CICD Service Desk section. 2. Step-by-Step Setup Guide: 2.1 Step1 : Configuring IAM Roles/Security Groups/Cloud Map Namespaces: To create an App group for an environment: Log in to SSP (via SAML) and switch to your application, as shown in Figure 1. IMPORTANT The DPE APP ID of an application would appear on your Switch Application dropdown list only if you are a member of the application's default teams or the application's IT manager (primary maintainer). Navigate to Application Configuration, as shown in below figure. Application Configuration tab In the criteria fields, select the environment class, enter the environment name, and then click Search, as shown in Figure. - Remain on the APP Groups subtab, and then click Create. - Enter the App group name and click OK in the displayed dialog box. Hover over the info icon to see the valid format of an App group name to avoid invalid input. IMPORTANT If you do not configure a name for an App group, the name is displayed as <NONE> on SSP. To apply an App group that does not have a name, please remove the AppGrpName parameter or set the AppGrpName parameter to NONE in your grd.yml file. App group name dialog box You can add or remove IAM roles for a resource class in an App group. IMPORTANT Each resource class supports only one IAM role, except for RDS. The RDS resource class supports up to two IAM roles. Before adding an IAM role to a resource class, you need to make sure the IAM role is provided by default or has been requested in advance. For more information, see this section. You need to select the IAM role based on environment. The end of an IAM role name reflects the environment for which it is created. For example, for the dev environment, select the IAM role name that ends with "DEV". To add an IAM role, follow these steps: 1. Click the desired resource class tab from the App group configuration table. 2. Click the white plus icon in the IAM Role row. 3. Select an IAM role from the dialog box and click OK. IMPORTANT The name of the IAM role must end with the name of the environment that the App group is applied to, such as DEV or UAT. - After the IAM role is added, you can check its status by the status icon in front of it, as shown in Figure 8. If the icon is green, the IAM role is added successfully. If the icon is red, errors have occurred. - Pay attention to the feature tag when adding IAM roles for the RDS resource class. Adding an IAM role IAM role status Above App Group is used for creation of a ECS cluster and hence it is associated with ECS service & ELB Pay attention to the following steps: a. Select ecs_setup, ecs_service, and ec2 as the resource classes. The ec2 resource class is required only for Linux ECS. b. For each resource class, add the desired IAM roles/security groups/Cloud Map namespaces. - ecs_setup: IAM roles - ecs_service: IAM roles, security groups, and Cloud Map namespaces - ec2: IAM roles and (up to 5) security groups (applies to Linux ECS only) Adding/Removing Security Groups You can add or remove security groups for a resource class in an App group. To add a security group, follow these steps: 1. Click the desired resource class tab from the App group configuration table. 2. Click the white plus icon in the Security Group row, as shown in Figure. 3. Select a security group from the dialog box and click OK, as shown in Figure. Adding a security group IAM roles/security groups for to be used for our application Resource Type IAM Roles Security Groups EC2 GSRole<DPE APP ID>EC2Default<Environment> COMMON///SSGSBase COMMON///SSGSWeb AWS///SSGSRDSApp (remove this if RDS server connection is not required) ELB N/A COMMON///SSGSWeb Security group status Note: Please add minimum App Groups as possible and try to reuse the same app group for common stack unless it is really needed to create a new one. Configuring a Cloudmap Namespace : AWS Cloud Map is a cloud resource discovery service. With Cloud Map, you can define custom names for your application resources, and it maintains the updated location of these dynamically changing resources. This increases your application availability because your web service always discovers the most up-to-date locations of its resources. Each Cloud Map namespace can be configured to only one App group. Attempt to configure a Cloud Map namespace (that belongs to an existing App group) to another App group would fail. Each resource class supports only one Cloud Map namespace for each region. Before adding a Cloud Map namespace to a resource class, you need to make sure the Cloud Map namespace has been requested in advance. Please do not delete a Cloud Map namespace that is mapped to an active resource. If you do, service errors might occur. For example, if you delete a Cloud Map namespace mapped to an active EC2 instance, termination of the EC2 instance cannot trigger instance deregistration from Cloud Map. You can add or remove Cloud Map namespaces for the EC2/RDS/ECS/EMR/ELB resource class in an App group. See above how cloudmap domain resolving to Load Balancer is attached to an App group for Compass backend cluster. To add a Cloud Map namespace, follow these steps: 1. Click the desired resource class tab from the App group configuration table. 2. Click the white plus icon in the Cloud Map Service row. 3. Select a Cloud Map namespace from the dialog box and click OK, as shown in below Figure . Note After the Cloud Map namespace is added, you can check its status by the status icon in front of it. If the status icon is green, the Cloud Map namespace is added successfully. If the icon is red, errors have occurred. Figure Adding a Cloud Map namespace 2.2 Creating ECS Branches Branch introduction Branch Name Convention Description Write Access Jenkins Pipeline Triggered Feature feature* e.g. feature0001 Used by developers to deliver features. Develop team DEV Integration integration* e.g. integration0001 Used for testing and deploying multiple features together in DEV. Review team SYS Release release* e.g. release0001 Used for testing and deploying multiple features together in UAT. Release team UAT Master master The branch where all changes eventually get merged into. Used for testing and deploying multiple features together in PROD. Release team PROD Please refer to DPE0202 GITHUB for COMPASS Repos & Branches GAInnovationLab/compass-transacton at feature_wave_2b 2.3 Configuring an ECS cluster : For our COMPASS application we have 2 separate clusters , one for backend & another for frontend. Backend cluster will host all our Spring Boot services as containers & Frontend cluster will accommodate React Components as container. To ensure the successful deployment of the Linux ECS, you need to configure the Dockerfile, ecs_template.yml file, and ecs_parameters.json file correctly. To deploy/delete ECS cluster in compass please follow below GIT link : GAInnovationLab/compass-cluster-backend at feature_init GAInnovationLab/compass-cluster-frontend at feature_001 Please be careful with Autoscaling configuration when you start a new cluster , below figure will give an idea about current configuration. But the instances number can change for different environment depending on the Application load & usage. Explanation for GRD for cluster setup Compass Front End Cluster GRD for reference: Please read below configuration with explanation in above figure. 2.4 Setting ECS Services : Compass has 2 kinds of ECS services , one is react component deployed as micro-frontend using Ngnix webserver & other is Spring Boot service used for backend application domains. Both these services are deployed in separate Clusters. ECS Spring Boot service Deployment: Please use following git repo for reference and setup your project structure in accordance: GAInnovationLab/compass-transacton at feature_wave_2b Key components for deploying spring boot services are as below : Please ensure to use the latest version of the template – confirm the latest release from DPE CICD team Once the template is configured , please use below guide to setup your docker file. Above is the docker file with description of each section , please refer to below docker file for compass and read in accordance with above descriptions. Pay attention to the highlighted sections and choose correct linux version , latest & compatible JDK (17 in case of compass) and update the Target with appropriate build artifact. Final step is to configure grd.yml which is the key for creation of the stack using CICD pipeline and provides the ultimate guard rails for CloudFormation templates. Ensure to use all the highlighted modules in your grd for running a Spring Boot Container Please use all maven run statement you would desire for your build as highlighted above. And also make sure to ‘skip : false’ if you desire to skip or exclude any scan or unit test. Deploy Type : Please force_Create as standard and use delete in case if you would like to stop or kill the running container. App Group Name : Please use the relevant app group name and remember this could be reused. App Descriptor : This should be always unique for each service and this will be key in the configuration of LogGroups. Cluster Descriptor : This is the label or descriptor created for the ECS cluster where you want to host your Spring Boot Service , please be attentive and use the correct Cluster label , eg. SPB services should use Backend Cluster Descriptor only. ListenerRulePath : This should match the api context to make it easily discoverable and priority should be decided based on number of services deployed in the same cluster. This rule will be used to Stack Name : Here you should configure the Load Balancer name that you will use for accessing your cluster. ECS Front End Component Deployment: Please refer following git Repo for configuring a frontend react component to be hosted within an ngnix container. compass-frontend/compass_web/Dockerfile at feature_wave_2b · GAInnovationLab/compass-frontend Please use below commands and steps given in docker file for hosting your ngnix web service within a container: Highlighted above config files should be revisited for each react component. Sample Ngnix Conf : Pay attention to Reverse Proxy configuration which should based on the UI redirection you desire Finally place below modules within grd.yml to run your UX component inside ngnix web instance Specify npm build steps as below similar to mvn script used for building spring boot. Last , use below stack configuration by specifying the ALB , Cluster Descriptor as used for above Spring Boot Service ECS task creation. 2.5 ECS Maintenance : 1. Figure 1 SSP access and application switching 2. Click AWS Container > AWS ECS, as shown in Figure 2. Figure 2 AWS ECS tab 3. On the criteria fields, select the environment class, enter the environment name, select the region, and then click Search, as shown in Figure 2. ECS clusters that meet the criteria will be listed, as shown in Figure 2. From the list, you can view the general information of each ECS cluster. For example, the number of tasks in an ECS cluster. o To search for a cluster, follow these steps: a. Go to the ECS cluster list on the AWS ECS tab, as shown in Figure 2. b. Enter the keyword in the search box above the ECS cluster list. o To view ECS cluster details, follow these steps: a. Go to the ECS cluster list on the AWS ECS tab, as shown in Figure 2. b. On the desired cluster record, click the dot icon in the Actions column and then select View Details, as shown in Figure 3. The cluster details page will be displayed, as shown in Figure 4. Figure 3 Actions on an ECS cluster Figure 4 Cluster details o To stop a task, follow these steps: a. Go to the ECS cluster details page, as shown in Figure 4. b. Choose the desired task from the task list on the Task subtab, as shown in Figure 4. c. On the desired task record, click the dot icon in the Actions column and then select Stop, as shown in Figure 5. d. Enter stop in the field and then click Stop on the confirmation dialog box, as shown in Figure 6.
Leave a Comment