control-service: refactor service user doc (#2436)

what: updated service user setup documentation

why: it was(is) potentially unclear

testing: n/a doc change.

---------

Signed-off-by: mrMoZ1 <[email protected]>

projects/control-service/projects/pipelines_control_service/src/main/resources/application.properties

@@ -286,18 +286,35 @@ datajobs.aws.secretAccessKey=${AWS_ACCESS_KEY_SECRET}
 
 # Variables for using the Service Account pattern. Must be set if the data job builder is to use
 # an AWS ECR repository accessed by an IAM user instead of long term credentials.
-# The AWS Service Account pattern is a design pattern used to manage access to AWS resources.
 # The pattern involves creating an AWS Identity and Access Management (IAM)
-# user account with a unique access key and secret key. The access key and secret key are then
-# stored in a secure location, such as an encrypted file, on the EC2 instance.
+# user account with a unique access key and secret key.
 # The application running on the EC2 instance can then use the access key and secret key
 # to authenticate with AWS services and make API calls on behalf of the IAM user account.
-# By using a separate IAM user account for each application, the principle of least privilege is
-# enforced and the attack surface is reduced.
+# By using a separate IAM user, the principle of least privilege is enforced.
 # https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html
-# These need to be stored in different variables than the AWS credentials - datajobs.aws.accessKeyId
-# and secretAccessKey used by the control service, because if the K8S cluster is hosted on a EKS
-# instance, some API calls to the instance made by the control-service could fail.
+# The service user variables are different than the AWS credentials - datajobs.aws.accessKeyId
+# and secretAccessKey used by the control service.
+#
+# Necessary steps to setup Service Account:
+# - Create a Service Account in Amazon (regular account that will be granted permissions to ECR repo) e.g:
+#   https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html#id_users_create_console
+#   e.g - IAM user: svc.example-service-user
+# - Create a role in your AWS account (account where your ECR repository lives) - https://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html
+#   e.g - IAMRole: svc.example-service-user, the role must have the same name as your service user.
+#   More information on what the example-service-user document should include can be found in the above link
+#   which describes the process of creating a role.
+# - Create a trust relationship on the role to the control account - edit your newly created role's Trust Relationship:
+#   This is the trust relationship in your main account which is associated with the service user. Or
+#   the role ARN - which is used to delegate access to resources securely.
+#   More information on how to create and use role ARN can be found in the below mentioned documents.
+#   https://aws.amazon.com/blogs/security/how-to-use-external-id-when-granting-access-to-your-aws-resources/
+#   https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html.
+# - Verify access to the linked account:
+#   aws sts get-caller-identity with the Service Account credentials - this is the account for which
+#   a role was created in the main account (where the Elastic Container Repository is stored)
+#   Any AWS account can be created for the purpose of being a service account.
+# If everything is configured correctly you need to fill in the below values and ECR repository
+# access through the control-service (when deploying data job images) will go through the service account.
 # datajobs.aws.assumeIAMRole tells the control-service if the Service Account pattern should be used.
 datajobs.aws.assumeIAMRole=${DATAJOBS_AWS_ASSUME_IAM_ROLE:false}
 # All flags must be set if the datajobs.aws.assumeIAMRole flag is true