work and questions on IAM role and policies

docs/_partials/_create-oauth-app.mdx

@@ -1,4 +1,4 @@
-AI Unlimited uses the [OAuth](https://oauth.net/2/) app to authorize your GitHub or GitLab account to store user and project information.
+Create an [OAuth](https://oauth.net/2/) app so that AI Unlimited can authorize your GitHub or GitLab account to store user and project information.
 
 1. Sign in to your Git repository.
 2. Create an OAuth app. See [GitHub: Create an OAuth app](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) or [GitLab: Create an OAuth app](https://docs.gitlab.com/ee/integration/oauth_provider.html).

docs/install-ai-unlimited/demo/AWS/demo-aws-permissions-policies.md

@@ -1,30 +1,46 @@
 ---
 id: demo-aws-permissions-policies
-title: Teradata - AI Unlimited - Demo - AWS - Create custom policies for an IAM role
-description: Learn how AWS IAM roles and policies impact the Teradata AI Unlimited deployment.
-sidebar_label: Create custom policies for an IAM role
+title: Teradata - AI Unlimited - Demo - AWS - Create custom IAM roles and policies
+description: Learn what IAM roles and policies are needed to  deployment.
+sidebar_label: Create custom IAM roles and policies
 sidebar_position: 5
 ---
 
-# Create custom policies for an IAM role
+# Create custom IAM roles and policies
 
-Configure roles and policies with the necessary permissions to provide AI Unlimited access to the AWS resources. ***Is this topic just about policies or roles as well?*** ***TA: Roles and policies***
+***Looks like they create 1 role, then create 1 or more policies to attach to it. We provde the JSON for creating the policies. So the title could be "Create a custom IAM role and policies."***
+
+***To whom/what is this role assigned? The AI Unlimited service?***
+
+***The policies they attach depend on their needs. At the least, they will attach one of the first two, correct?***
+
+***So the role is for creating engine instances and, optionally, for specifying that AI Unlimited can create a new role each time the engine deploys for the cluster on which it deploys?***
+
+***The role, then, is for AI Unlimited and also for the cluster on which the engine gets deployed? They both need the same role? At the end of the day, is the role really for the cluster? It's just that the cluster can get it 2 different ways?***
+
+***I am assuming the role is for launching the engine. Need to specify that up front.***
+
+***Maybe need to explain up front that AI Unlimited (which gets the role, correct?) passes the role to the engine every time the engine is deployed OR AI Unlimited creates a new role for the engine each time it deploys the engine. Is that correct?***
+
+***Permissions to create roles and policies seem to be granted to a user/role, not an AWS account--so I'm confused about that.***
+
+If you ***(the user, not their AWS account, right?)*** have the necessary IAM permissions ***(iam:CreateRole & iam: PutRolePolicy? Wondering if we should mention them.)***, create IAM roles ***("an IAM role")*** and policies to provide AI Unlimited with access to AWS resources ***(add "for deploying the engine"?)***. 
 
 :::note 
-If your AWS account does not have sufficient IAM permissions to create IAM roles and policies, your cloud administrator can define the roles and policies and pass them to the CloudFormation template. 
+If you ***(the AWS account?)*** don't have the necessary IAM permissions, your cloud administrator can define the IAM roles ***("role")*** and policies and pass them to the CloudFormation template, which you'll use to install AI Unlimited and JupyterLab. ***(Should they do something now to get that started?)***
 :::
 
-***Is this topic about defining the roles and policies in order to pass them to the CFT? Probably not. It's about how to create them in the console. The above para must be the workaround.*** ***TA: If users don't have access to create own roles, then they should go through IT. If they do have access, they can create new roles via the Console.***
+To create the role and policies yourself, see [Creating roles and attaching policies (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_job-functions_create-policies.html).
 
-For detailed instructions, see [Creating roles and attaching policies (console) - AWS Identity and Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_job-functions_create-policies.html).
+Attach these policies to the role: 
 
-Attach the required IAM policies to an IAM role:
+- [ai-unlimited-workspaces.json](https://github.com/Teradata/ai-unlimited/blob/develop/deployments/aws/policies/ai-unlimited-workspaces.json): Includes the permissions needed to create AI Unlimited instances ***(engine instances?)***, and grants AI Unlimited permissions to create cluster-specific roles and policies for the engine.
 
-- [ai-unlimited-workspaces.json](https://github.com/Teradata/ai-unlimited/blob/develop/deployments/aws/policies/ai-unlimited-workspaces.json): This JSON sample includes permissions needed to create AI Unlimited instances and grants AI Unlimited the permissions to create cluster-specific IAM roles and policies for the engine.
+***Would it be accurate to just say "Includes the permissions needed to create engine instances and cluster-specific roles and policies for the engine."? I am confused about what the cluster-specific roles and policies are for, though.***
 
-- [ai-unlimited-without-iam-role-permissions.json](https://github.com/Teradata/ai-unlimited/blob/develop/deployments/aws/policies/ai-unlimited-without-iam-role-permissions.json): This JSON sample includes the permissions needed to create AI Unlimited instances. If your account restrictions do not allow AI Unlimited to create IAM roles and policies, then you must provide an IAM role with a policy to pass to the engine. In this case, you can use this modified policy, which does not include permissions to create IAM roles or IAM policies.
+- [ai-unlimited-without-iam-role-permissions.json](https://github.com/Teradata/ai-unlimited/blob/develop/deployments/aws/policies/ai-unlimited-without-iam-role-permissions.json): Includes the permissions needed to create AI Unlimited instances ***(engine instances?)***. If your AWS account has restrictions that don't allow AI Unlimited  to create roles and policies ***(can we just say "If you don't have permissions to create roles and policies"?)***, then you must provide a role with a policy to pass to the engine ***(Is this what the cloud admin can provide for the CFT, as in the note at the top of this topic?)***. In this case, use this policy, which does not include permissions to create IAM roles or IAM policies.
 
-- [session-manager.json](https://github.com/Teradata/ai-unlimited/blob/develop/deployments/aws/policies/session-manager.json): This JSON sample includes the permissions needed to interact with the AWS Session Manager. If you use AWS Session Manager to connect to the instance, you must attach this policy to the IAM role.
+- [session-manager.json](https://github.com/Teradata/ai-unlimited/blob/develop/deployments/aws/policies/session-manager.json): This JSON sample includes the permissions needed to interact with the AWS Session Manager. If you will use AWS Session Manager to connect to the instance, you must attach this policy to the IAM role. ***(So this ties back to the bullet in the Prepare topic.)***
 
 - [ai-unlimited-engine.json](https://github.com/Teradata/ai-unlimited/blob/develop/deployments/aws/policies/ai-unlimited-engine.json): If you pass the AI Unlimited IAM role to a new engine instead of allowing AI Unlimited to create the cluster-specific role, you can use this JSON sample as a starting point to create your policy.
 
@@ -35,14 +51,14 @@ When AI Unlimited creates policies for the engine ***[But the topic says the use
 "Resource": ["arn:aws:secretsmanager:`REGION`:`ACCOUNT_ID`:secret:compute-engine/`CLUSTER_NAME`/`SECRET_NAME`"]
 ```
 
-If you provide an IAM role and policy,***"if" - what is the opposite? Just 1 policy, not 4?*** then you can't predict the cluster name, and to avoid the situation, you can use wildcarding in the replacement policy, such as:
+If you provide an IAM role and policy, then you can't predict the cluster name, and to avoid the situation, you can use wildcarding in the replacement policy, such as:
+
+***So this is for
 
 ``` bash
 "arn:aws:secretsmanager:`REGION`:`ACCOUNT_ID`:secret:compute-engine/*"
 or
 "arn:aws:secretsmanager:`REGION`:111111111111:secret:compute-engine/*"
 or
 "arn:aws:secretsmanager:us-west-2:111111111111:secret:compute-engine/*"
-```
-
-***So are we asking them to create 1 role? 1 role with 4 policies attached?***
+```

docs/install-ai-unlimited/demo/AWS/demo-aws-prepare-your-account.md

@@ -8,13 +8,17 @@ sidebar_position: 3
 
 # Prepare your AWS account
 
-- Your AWS account must have sufficient IAM permissions to create [custom IAM roles and policies](../../demo/AWS/demo-aws-permissions-policies.md).
+- Your AWS account must have sufficient IAM permissions ***(I found iam:CreateRole and iam: PutRolePolicy. They are for users/roles, not the account. Should the sentence say "You must have" instead of "Your AWS account must have"?)*** to create [custom IAM roles and policies](../../demo/AWS/demo-aws-permissions-policies.md). 
 
-- In the AWS Management Console, choose the AWS region in which to deploy AI Unlimited. 
+:::note 
+If your AWS account does not have sufficient IAM permissions to create IAM roles and policies, your cloud administrator can define the roles and policies and pass them to the CloudFormation template. 
+:::
 
-- If you need access to your AI Unlimited server instance host operating system (OS), you can connect these ways:
-    - Generate a [key pair](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) to securely connect to your AI Unlimited instance using Secure Shell (SSH) after it launches.
-    - Use AWS Session Manager to connect to the AI Unlimited instance. In this case, you must attach the [session-manager.json](https://github.com/Teradata/ai-unlimited/blob/develop/deployments/aws/policies/session-manager.json) policy to the IAM role. See [Control AWS access and permissions using custom permissions and policies](/docs/install-ai-unlimited/production/AWS/aws-permissions-policies.md). 
+- In the AWS Management Console, choose the AWS region in which to deploy AI Unlimited. ***Maybe this was part of a task that we no longer have.***
+
+- If you will need to closely manage the AI Unlimited server instance after it is launches ***(Why might they want to?)***, you can connect to it within its host operating system (OS) two ways:
+    - After it launches, generate a [key pair](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) to securely connect using Secure Shell (SSH).
+    - After it launches, use AWS Session Manager to connect. To enable this, you must attach the [session-manager.json](https://github.com/Teradata/ai-unlimited/blob/develop/deployments/aws/policies/session-manager.json) policy to the IAM role. See [Control AWS access and permissions using custom permissions and policies](/docs/install-ai-unlimited/production/AWS/aws-permissions-policies.md). ***(This topic is "Prepare," but attaching policies to the role is done in the other topic. Is there a reason to introduce it here?)***
 
 - If you’re using load balancers, make sure you have permission to manage these AWS services:
     - [AWS Certificate Manager](https://docs.aws.amazon.com/acm/) to issue a new certificate for the hosted zone ID in Route 53.