Merge pull request #13 from DecisiveAI/doc-updates-3.18.24

fix: docs issues 3.18.24

src/install/aws/aws-env.md

@@ -2,8 +2,12 @@
 
 Navigate to the `values/aws.env` file and start inputting the environment configuration that's relevant to your AWS account.
 
+<div class="warning">
+  Due to our engine's Load Balancer capabilities alongside security measures, we're only able to support full engine compatibility with a <a href="https://docs.aws.amazon.com/elasticloadbalancing/latest/application/listener-authenticate-users.html#cognito-requirements" target="_blank" rel="noreferrer noopener">limited list</a> of AWS Regions.
+</div>
+
 ```
-# region where the engine going to be installed
+# region where the engine going to be installed.
 AWS_REGION=
 
 # AWS account to be used

src/install/aws/aws-sso.md

@@ -2,10 +2,13 @@
 
 To deploy an MDAI Engine, you'll need to use the AWS CLI.
 
+>**Note:** Our install steps use the recommended AWS CLI access method, AWS SSO. There are other [AWS CLI Access options](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html) that you can use to interact with your AWS account.
+
 #### Login via the CLI
 
 ```shell
-aws configure sso
+# Assumes your machine is already configured access to AWS via `aws configure sso`.
+aws sso login --profile <AWS_PROFILE>
 ```
 
 #### Choose the right AWS Account and AWS Role

src/install/aws/deploy.md

@@ -15,6 +15,7 @@
 ```shell
 make install
 ```
+
 <div class="warning">
   <b><em>Don't walk away just yet!</em></b>
   <p>There's one more manual verification step required before CloudFormation will deploy all necessary infrastructure to get your engine up and running as soon as possible.</p>

src/install/aws/destroy.md

@@ -34,8 +34,8 @@ Delete listed dependencies by following steps below or through AWS Console.
         ```
     - Delete security groups if the destroy failed to delete the VPC. Use the VPC ID from the cdk error output:
         ```bash
-        for sg_id in $(aws ec2 describe-security-groups --region <your_region> --filters Name=vpc-id,Values='<your_vpc_id>' --query 'SecurityGroups[?GroupName!=`default`].[GroupId]' --output text); do
-            aws ec2 delete-security-group --group-id $sg_id --region <your_region>
+        for sg_id in $(aws ec2 describe-security-groups --region <your_region> --profile <your_profile> --filters Name=vpc-id,Values='<your_vpc_id>' --query 'SecurityGroups[?GroupName!=`default`].[GroupId]' --output text); do
+            aws ec2 delete-security-group --group-id $sg_id --region <your_region> --profile <your_profile>
             echo "Deleted security group $sg_id"
         done
         ```

src/install/aws/prerequisites.md

@@ -13,6 +13,8 @@ export GOBIN=${GOBIN:-$(go env GOPATH)/bin}
 ```
 - Install [node](https://nodejs.org/en/download).
 
+>**Note:** We do install Helm automatically, however, it's important to note that we support [Helm v3.13.0](https://github.com/helm/helm/releases/tag/v3.13.0) and later. If you have helm installed, but at an earlier version, we cannot guarantee our install process will work as expected.
+
 ### AWS Requirements
 
 - Install [AWS CDK Toolkit](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_install)

src/install/aws/ui-auth.md

@@ -2,9 +2,27 @@
 
 We knew it wouldn't be acceptable to leave your precious new resources unprotected and open to any user of the internet!
 
-*Enter Cognito*
+*...Enter Cognito...*
 
 We've added the ability to connect [Amazon Cognito](https://aws.amazon.com/cognito/) easily to your new Engine to limit access for undesired users.
+
+<div class="warning">
+  Cognito is not supported in all AWS Regions. If you run into issues
+  post-install, this is likely the reason. A typical error you would see looks like this:<br />
+  <code style="color: #d10707;">
+    Failed deploy model due to failed to create listener rule: ValidationError: Action type 'authenticate-cognito' must be one of 'redirect,fixed-response,forward,authenticate-oidc' status code: 400, request id: ########-####-####-####-############
+  </code><br /><br />
+  <b>The above error can be found in the AWS Console > EKS service.</b><br /><br />
+  You can access the ingress output manually:<br />
+  <code>
+    EKS > Clusters > [YOUR_CLUSTER] > Resources > Service and networking > Ingresses > ui-alb-ingress
+  </code><br /><br />
+  You can access the ingress output by hitting this link after updating the values in brackets:<br />
+  <code>
+    https://[AWS_REGION].console.aws.amazon.com/eks/home?region=[AWS_REGION]#/clusters/[YOUR_CLUSTER]/ingresses/ui-alb-ingress?namespace=default
+  </code><br />
+</div>
+
 Our installation includes the following resources upon creating an engine:
 
 1. [User pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools.html) `mdai-user-pool`

src/install/local/quick-start.md

@@ -16,41 +16,73 @@ You are going to learn to do the following in less than five minutes:
 
 ## Prerequisites
 
+<div class="warning">
+  <b>System Dependencies</b>
+  <ul>
+    <li>These docs assume that you have <a href="https://brew.sh/" target="_blank">homebrew</a> installed.</li>
+    <li>If you're using MacOS, you'll also need <a href="https://mac.install.guide/commandlinetools/" target="_blank">XCode Commandline Tools</a> installed.</li>
+    <li>You will also need to have <a href="https://kubernetes.io/releases/download/" target="_blank">Kubernetes</a> installed.</li>
+  </ul>
+</div>
+
 ### Automated installation
+
 Our automated installation process is setting up all the required dependencies like
 - Docker
 - Kind cluster
 - Npm
 - Aws CDK
 - Go
-- Helm
+- Helm (we support [Helm v3.13.0](https://github.com/helm/helm/releases/tag/v3.13.0) and later)
 
->_Note: Once the Engine installed your k8s context will be switched automatically to new cluster._   
+>_Note: Once the Engine installed your k8s context will be switched automatically to new cluster._
 
 Here are installation steps:
 
 1. Pull down the latest from the [MDAI infrastructure installation repo](https://github.com/DecisiveAI/mdai-inkops)
 2. Install [kind](https://kind.sigs.k8s.io/docs/user/quick-start/) for local cluster management using docker containers
 3. Run automated installation script
 ```bash
-make -f ./make/Makefile-local-recipies create-mdai
+make -f ./make/Makefile-local-recipes create-mdai
 ```
+
+<div class="warning">
+   <b>Other steps:</b>
+   Upon installation you encounter an error where Docker is the culprit, please ensure the docker daemon is running. If this doesn't fix the error, feel free to:
+   <ul>
+      <li>
+         Email us at <a href="mailto:support@mydecisive.ai">support@mydecisive.ai</a>
+      </li>
+      <li>
+         File an issue under the <a href="https://github.com/DecisiveAI/mdai-inkops">MDAI InkOps Project</a>
+      </li>
+   </ul>
+</div>
+
 ### Automated uninstall
+
 Make sure your k8s context is set to `kind-mdai-local` cluster:
+
 ```bash
 kubectl config get-contexts
 ```
+
 Switch the context if needed:
+
 ```bash
 kubectl cluster-info --context kind-mdai-local
 ```
+
 Run automated de-installation script
+
 ```bash
- make -f ./make/Makefile-local-recipies delete-mdai
+ make -f ./make/Makefile-local-recipes delete-mdai
 ```
+
 If you want to remove all helm artifacts installed (you don't use it your other local setup), run the following
+
 ```bash
- make -f ./make/Makefile-local-recipies delete-mdai-all
+ make -f ./make/Makefile-local-recipes delete-mdai-all
 ```
 
 ### Manual pre-req installations