From ac444b33a960310c5075ea1da8124e7c50106d57 Mon Sep 17 00:00:00 2001 From: MEM4GH <118773316+MEM4GH@users.noreply.github.com> Date: Mon, 6 May 2024 22:21:29 -0400 Subject: [PATCH] lots of clean up - GS and OR ready for reviewers --- docs/FAQ.md | 44 +++++------ .../example-projects.md | 2 +- docs/explore-and-analyze-data/index.md | 6 +- docs/install-ai-unlimited/index.md | 4 +- .../prod-aws-console-deploy-ai-unlimited.md | 2 +- .../prod-azure-portal-deploy-manager.md | 2 +- docs/manage-ai-unlimited/add-collaborators.md | 2 +- docs/manage-ai-unlimited/change-settings.md | 18 ++--- docs/manage-ai-unlimited/index.md | 6 +- docs/manage-ai-unlimited/monitor-projects.md | 6 +- .../suspend-and-resume-project.md | 5 +- docs/resources/aws-requirements.md | 37 +++++---- docs/resources/azure-requirements.md | 15 ++-- docs/resources/git-requirements.md | 15 +--- docs/resources/index.md | 2 +- docs/resources/jupyterlab/index.md | 6 +- .../jupyterlab/install-jupyterlab-aws.md | 28 ++++--- .../jupyterlab/install-jupyterlab-azure.md | 78 ++++++++++++++----- .../docker-install-ai-unlimited-jupyter.md | 8 +- .../quickstart/docker-when-you-are-done.md | 1 + docs/resources/quickstart/index.md | 1 + docs/resources/release-notes.md | 13 ++++ 22 files changed, 181 insertions(+), 120 deletions(-) create mode 100644 docs/resources/release-notes.md diff --git a/docs/FAQ.md b/docs/FAQ.md index dfe7c69963..731f9b3f58 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -1,14 +1,14 @@ --- id: faq title: FAQ -description: Frequently asked questions regarding the installation and use of AI Unlimited. +description: Find answers to your AI Unlimited questions here. sidebar_label: FAQ sidebar_position: 6 --- # FAQ -(Just brainstorming ideas for Q's, for now. Can categorize to make them more skimmable.) +(Just brainstorming ideas, for now. Will categorize to make them more skimmable.) **What's the difference between AI Unlimited and Teradata Vantage?** Answer. @@ -16,47 +16,39 @@ Answer. **What's the difference between AI Unlimited and Teradata ClearScape Analytics?** Answer. -**How do I pay for AI Unlimited use?** +**How do I pay for AI Unlimited?** Answer. **Is the QuickStart free?** Answer. **What CSPs does AI Unlimited support?** -Currently, AWS and Azure. +AWS and Azure -**What kind of data needs to be in my data lake?** Object (too obvious?) +**What are the AI Unlimited user types?** +Admin, project owner, collaborator--will expound. -**As a general AI Unlimited user, what can I do?** -Answer. - -**As the administrator user, what can I do?** -Answer. +**What integrations and automation are possible?** +(Not specifically addressing devs for *initial* PPP. But surely folks will ask?) -**As a developer, what can I do?** -Answer. +**I'm an admin. After the initial setup, can I go back and change settings?** +Yes. (any of them?) -**What's my API key for?** -It enables your notebook to connect to the project's engine. (Accurate?) There is always only one API key per authenticated user. It doesn't change or expire. (not yet anyway) +**Can I add other administrator users?** +You can have only one AI Unlimited admin. -**What is a project owner?** -If you create a project, you are its owner. If you add collaborators, they are not the project's owners. +**As a project owner, can I add other users to my project?** +Of course. Explain. -**As a project owner, can I add other users to my project?** Answer. +**What's my API key for?** +Answer. **How can I access another user's project?** -(Ask them to add you as a collaborator? Artur will write up this capability and the current real reason for it.) +Ask the owner to add you as a collaborator. Link to the steps. **What happens when I suspend a project?** Answer. -**And when I resume it?** +**And when I restore it?** Answer. -**After the initial setup, can I change the settings?** -Yes. (any of them?) - -**Can I add other administrator users?** -In this release, you can have only one administrator. - -**What integrations and automation are possible?** Dunno. \ No newline at end of file diff --git a/docs/explore-and-analyze-data/example-projects.md b/docs/explore-and-analyze-data/example-projects.md index e84546ee74..1532c837b7 100644 --- a/docs/explore-and-analyze-data/example-projects.md +++ b/docs/explore-and-analyze-data/example-projects.md @@ -16,6 +16,6 @@ Here are just some of the types of workloads you can run using AI Unlimited: - b - c -***The example notebooks and data files will be in the "examples" folder in the AI Unlim repo. Here we just need to add links.*** +(The notebooks and data files will be in the "examples" folder in the AI Unlim repo. Here we just need to add links.) diff --git a/docs/explore-and-analyze-data/index.md b/docs/explore-and-analyze-data/index.md index dd46270e3e..b4914dddb2 100644 --- a/docs/explore-and-analyze-data/index.md +++ b/docs/explore-and-analyze-data/index.md @@ -13,7 +13,7 @@ pagination_next: null Connect to JupyterLab, open a notebook, and select the AI Unlimited kernel. :::note -If you don't have JupyterLab or the AI Unlimited kernel, see [Jupyter installation options](/docs/advanced/jupyterlab). +If you don't have JupyterLab or the AI Unlimited kernel, see [Jupyter installation options](/docs/resources/jupyterlab). ::: @@ -24,4 +24,8 @@ If you don't have JupyterLab or the AI Unlimited kernel, see [Jupyter installati :::tip To avoid incurring charges for unneeded engine resources, remember to [suspend](/docs/manage-ai-unlimited/suspend-resume-project.md) projects you're not working on. +::: + +:::tip +For help with AI Unlimited projects, magic commands, and analytic functions, ask the [community](https://support.teradata.com/community?id=community_forum&sys_id=b0aba91597c329d0e6d2bd8c1253affa). ::: \ No newline at end of file diff --git a/docs/install-ai-unlimited/index.md b/docs/install-ai-unlimited/index.md index ae7045f041..13b0a1e58c 100644 --- a/docs/install-ai-unlimited/index.md +++ b/docs/install-ai-unlimited/index.md @@ -43,12 +43,10 @@ If AI Unlimited has already been installed and set up by someone at your organiz When you install the manager, you'll provide values for some cloud deployment details. See the [AWS details](/docs/install-ai-unlimited/prod-aws-console-deploy-ai-unlimited.md#aws-parms) or [Azure details](/docs/install-ai-unlimited/prod-azure-portal-deploy-manager.md#azure-parms)—if you want to work with a cloud admin to get the values ahead of time. ::: -***maybe we no longer want the note that follows - too confusing with the new option to deploy from the marketplace - might depend on the name of the new deployment method*** - :::note With AI Unlimited you can collaborate on projects with other users. -If you prefer a simpler, single-user approach, try the [QuickStart](/docs/advanced/quickstart) which runs the manager and JupyterLab in Docker containers on your computer. +If you prefer a simpler, single-user approach, try the [QuickStart](/docs/resources/quickstart) which runs the manager and JupyterLab in Docker containers on your computer. ::: diff --git a/docs/install-ai-unlimited/prod-aws-console-deploy-ai-unlimited.md b/docs/install-ai-unlimited/prod-aws-console-deploy-ai-unlimited.md index 1599647562..e6e05ed690 100644 --- a/docs/install-ai-unlimited/prod-aws-console-deploy-ai-unlimited.md +++ b/docs/install-ai-unlimited/prod-aws-console-deploy-ai-unlimited.md @@ -14,7 +14,7 @@ Before you begin, make sure you have the [prerequisites](/docs/install-ai-unlimi The AI Unlimited manager orchestrates the engine's deployment and includes a web-based user interface for monitoring projects. And the manager is where you'll set up AI Unlimited. -You'll deploy a server instance, on which the manager runs in a container controlled by [systemd](/docs/glossary.md#glo-systemd). +You'll use a CloudFormation template provided by Teradata to install the manager from the AWS Management Console. You'll deploy a server instance, on which the manager runs in a container controlled by [systemd](/docs/glossary.md#glo-systemd). :::tip For installation support, ask the [community](https://support.teradata.com/community?id=community_forum&sys_id=b0aba91597c329d0e6d2bd8c1253affa). diff --git a/docs/install-ai-unlimited/prod-azure-portal-deploy-manager.md b/docs/install-ai-unlimited/prod-azure-portal-deploy-manager.md index 5d34ff3e73..4a065333dc 100644 --- a/docs/install-ai-unlimited/prod-azure-portal-deploy-manager.md +++ b/docs/install-ai-unlimited/prod-azure-portal-deploy-manager.md @@ -14,7 +14,7 @@ Before you begin, make sure you have the [prerequisites](/docs/install-ai-unlimi The AI Unlimited manager orchestrates the engine's deployment and includes a web-based user interface for monitoring projects. And the manager is where you'll set up AI Unlimited. -You'll deploy a server instance, on which the manager runs in a container controlled by [systemd](/docs/glossary.md#glo-systemd) +You'll use an Azure Resource Manager (ARN) template provided by Teradata to install the manager from the Azure Portal. You'll deploy a server instance, on which the manager runs in a container controlled by [systemd](/docs/glossary.md#glo-systemd) :::tip For installation support, ask the [community](https://support.teradata.com/community?id=community_forum&sys_id=b0aba91597c329d0e6d2bd8c1253affa). diff --git a/docs/manage-ai-unlimited/add-collaborators.md b/docs/manage-ai-unlimited/add-collaborators.md index 79132446fd..1c01c1211e 100644 --- a/docs/manage-ai-unlimited/add-collaborators.md +++ b/docs/manage-ai-unlimited/add-collaborators.md @@ -12,4 +12,4 @@ pagination_next: null [placeholder] -***from Artur: User are added to the project by github/gitlab, if users are added before deploy then they are all created automatically as part of the deployment. If users are added there after deploy then %project_engine_update_users need to be used to update and create new users in the deployed engine.*** \ No newline at end of file +"Users are added to the project by github/gitlab, if users are added before deploy then they are all created automatically as part of the deployment. If users are added there after deploy then %project_engine_update_users need to be used to update and create new users in the deployed engine." \ No newline at end of file diff --git a/docs/manage-ai-unlimited/change-settings.md b/docs/manage-ai-unlimited/change-settings.md index 38885898d4..5da8bc2b2a 100644 --- a/docs/manage-ai-unlimited/change-settings.md +++ b/docs/manage-ai-unlimited/change-settings.md @@ -1,32 +1,32 @@ --- id: change-settings -title: Change settings (administrator only) +title: Change settings (admin) description: Learn how to change AI Unlimited settings. -sidebar_label: Change settings (administrator only) +sidebar_label: Change settings (admin) sidebar_position: 4 pagination_prev: null pagination_next: null --- -# Change settings (administrator only) +# Change settings (admin) ***WIP*** -***Needs 2 separate topics - old UI vs. new UI.*** +(Needs 2 separate topics - old UI vs. new UI) If you are the AI Unlimited admin, you can change AI Unlimited settings. -***(make clear what they can/would change and why)*** +(make clear what they can/would change and why) :::note -The user who [set up AI Unlimited](/docs/install-ai-unlimted/setup-ai-unlimited.md) is the admin. +The user who [set up AI Unlimited](/docs/install-ai-unlimited/setup-ai-unlimited.md) is the admin. ::: -1. Access the manager ***(more details)***, sign in to your GitHub or GitLab account... how to say that... ***(will watch recording)*** +1. Access the manager ***(more details)***, sign in to your GitHub or GitLab account... how to say that... (will watch recording) 3. Select **Setup**. -3. In any section, change any values, then select **Save Changes**. ***(can they change anything at all?)***
+3. In any section, change any values, then select Save Changes. (can they change anything at all?)
[Learn about the fields](/docs/install-ai-inlimited/setup-ai-unlimited). 4. If you've enabled TLS, select **Restart**.
AI Unlimited restarts with TLS in place. -Go to the **Profile** page to copy your new API Key. ***(explain why they have a new one & to start using the new one)*** +Go to the **Profile** page to copy your new API Key. (explain why they have a new one & to start using the new one) diff --git a/docs/manage-ai-unlimited/index.md b/docs/manage-ai-unlimited/index.md index 2aca1f7da2..2cc8bc2d5d 100644 --- a/docs/manage-ai-unlimited/index.md +++ b/docs/manage-ai-unlimited/index.md @@ -13,7 +13,7 @@ Here's what different users can do. - Use [magic commands](/docs/explore-and-analyze-data/magic-commands.md) to manage projects in Jupyter notebooks -- [Suspend and restore projects](/docs/manage-ai-unlimited/suspend-and-resume-project.md) to *pay as you go* +- [Suspend and restore projects](/docs/manage-ai-unlimited/suspend-and-resume-project.md) (*pay as you go*) - [Monitor the status](/docs/manage-ai-unlimited/monitor-projects.md) of projects @@ -29,3 +29,7 @@ A user who creates a project is the project's owner. The user who [set up AI Unlimited](/docs/install-ai-unlimited/setup-ai-unlimited.md) is the admin. - [Change overall settings](/docs/manage-ai-unlimited/change-settings.md) ***(will explain this better - what does this really mean)*** + +:::tip +For help with managing projects, ask the [community](https://support.teradata.com/community?id=community_forum&sys_id=b0aba91597c329d0e6d2bd8c1253affa). +::: diff --git a/docs/manage-ai-unlimited/monitor-projects.md b/docs/manage-ai-unlimited/monitor-projects.md index 627a18dc99..b3e221862e 100644 --- a/docs/manage-ai-unlimited/monitor-projects.md +++ b/docs/manage-ai-unlimited/monitor-projects.md @@ -10,6 +10,8 @@ pagination_next: null # Monitor projects -***old ui - no diff beween what admin and general user sees - they just see a table with all the projects and their statuses*** +[placeholder] -***new ui - admin sees all projects, with statuses, and logs - general user sees that for just their own projects*** \ No newline at end of file +old ui - no diff beween what admin and general user sees - they just see a table with all the projects and their statuses + +new ui - admin sees all projects, with statuses, and logs - general user sees that for just their own projects \ No newline at end of file diff --git a/docs/manage-ai-unlimited/suspend-and-resume-project.md b/docs/manage-ai-unlimited/suspend-and-resume-project.md index 048d3a3354..593696ddbf 100644 --- a/docs/manage-ai-unlimited/suspend-and-resume-project.md +++ b/docs/manage-ai-unlimited/suspend-and-resume-project.md @@ -9,7 +9,7 @@ pagination_next: null To avoid incurring charges for unneeded engine resources, suspend projects you're not working on. -All project information, including user and object store authorizations and data objects, are saved. +All project information, including user and object store authorizations and data objects, are saved. When you restore the project, you can pick up where you left off. In your project notebook, run this: @@ -17,10 +17,9 @@ In your project notebook, run this: %project_engine_suspend ``` -You can restore the project anytime by running this: +Restore the project anytime by running this: ```bash %project_restore project=, gitref= ``` -You can now pick up where you left off, without having to re-create the project. diff --git a/docs/resources/aws-requirements.md b/docs/resources/aws-requirements.md index 31320d6a2c..ed946e0825 100644 --- a/docs/resources/aws-requirements.md +++ b/docs/resources/aws-requirements.md @@ -10,12 +10,12 @@ pagination_next: null # AWS account requirements -***(This topic is still being discussed.)*** +Prepare your AWS account: -- Work with your cloud admin to ensure you have the [Identity and Access Management (IAM)](https://aws.amazon.com/iam/) permissions to create cloud resources. +- Work with your cloud admin to ensure you have the [IAM](https://aws.amazon.com/iam/) permissions you need to create the cloud resources defined in your choice of [AI Unlimited template](https://github.com/Teradata/ai-unlimited/tree/develop/deployments/aws/templates/ai-unlimited). - If you'll need to access the manager instance, after it is installed, to run commands or debug, you can connect to it one of these ways: - - Generate a [key pair](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) to securely connect using Secure Shell (SSH). You will need the key pair when you [specify the manager's stack details](/docs/install-ai-unlimited/prod-aws-console-ai-unlimited.md#aws-parms). + - Use a [key pair](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) that you generate to securely connect using Secure Shell (SSH). You will need the key pair when you [specify the stack details](/docs/install-ai-unlimited/prod-aws-console-deploy-ai-unlimited.md#aws-parms). - Use AWS Session Manager to connect. To enable this, attach the [session-manager.json](https://github.com/Teradata/ai-unlimited/blob/develop/deployments/aws/policies/session-manager.json) policy to a [role you provide](#provide-roles) to the manager. - If you’re using an [Application Load Balancer (ALB)](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/application-load-balancer-getting-started.html) or [Network Load Balancer (NLB)](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/network-load-balancer-getting-started.html), make sure you have permission to manage these AWS services: @@ -27,31 +27,28 @@ pagination_next: null The manager requires a role that allows it to deploy the engine. The engine requires a role that allows the engine's nodes to communicate. -:::note -If your security does not allow AI Unlimited to create roles, [create the roles](#provide-roles) yourself or with the help of your cloud admin. -::: - - **Role required by the manager** -To let Unlimited create this role for you, when you [install the manager](/docs/install-ai-unlimited/prod-aws-console-ai-unlimited.md), provide these values for these parameters: +To let Unlimited create this role for you, when you [specify the stack details](/docs/install-ai-unlimited/prod-aws-console-deploy-ai-unlimited.md#aws-parms), provide these values for these parameters: - `IamRole`: **New** - `IamRoleName`: leave blank **Role required by the engine** -Let AI Unlimited create a new role for the cluster that deploys the engine each time the engine is deployed. +Let AI Unlimited create a new role for the engine each time the engine is deployed. -The cluster-specific policies AI Unlimited creates are restricted this way: +The engine-specific policies AI Unlimited creates are restricted this way: - ***(we are aware of this type size issue)*** - ```bash "Resource": ["arn:aws:secretsmanager:`REGION`:`ACCOUNT_ID`:secret:compute-engine/`CLUSTER_NAME`/`SECRET_NAME`"] ``` -To allow this, when you [set up AI Unlimited](/docs/install-ai-unlimited/setup-ai-unlimited), leave the **Default IAM role** field blank. +To allow this, when you [set up AI Unlimited](/docs/install-ai-unlimited/setup-ai-unlimited), leave the **Default IAM role** field blank. + +:::note +If your security does not allow AI Unlimited to create roles, create the roles yourself or with the help of your cloud admin. +::: @@ -64,23 +61,25 @@ If your security does not allow AI Unlimited to create roles, provide them. - If you have permissions to create IAM resources, create the role: - Attach a policy that includes the JSON that meets your needs. See the JSON samples that follow. - - When you [specify the manager's stack details](/docs/install-ai-unlimited/prod-aws-console-ai-unlimited.md#aws-parms), use these parameter values: + - When you [specify the stack details](/docs/install-ai-unlimited/prod-aws-console-deploy-ai-unlimited.md#aws-parms), use these parameter values: - `IamRole`: **New** - `IamRoleName`: the new role's name - If you don't have permissions to create IAM resources, work with your cloud admin to use an existing role: - Attach a policy that includes the JSON that meets your needs. See the JSON samples that follow. - - When you [specify the manager's stack details](/docs/install-ai-unlimited/prod-aws-console-ai-unlimited.md#aws-parms), use these parameter values: + - When you [specify the stack details](/docs/install-ai-unlimited/prod-aws-console-deploy-ai-unlimited.md#aws-parms), use these parameter values: - `IamRole`: **Existing** - `IamRoleName`: the existing role's name **JSON samples** +If you are providing the manager's role, use the samples you need in an attached policy. + - Allow AI Unlimited to create the engine role. Include [ai-unlimited-workspaces.json](https://github.com/Teradata/ai-unlimited/blob/develop/deployments/aws/policies/ai-unlimited-workspaces.json). It includes permissions to create engine instances, and grants AI Unlimited permissions to create cluster-specific roles and policies. - If your security does not allow AI Unlimited to create roles, include [ai-unlimited-without-iam-role-permissions.json](https://github.com/Teradata/ai-unlimited/blob/develop/deployments/aws/policies/ai-unlimited-workspaces-without-iam-role-permissions.json). It includes permissions to create engine instances, but not those needed for AI Unlimited to create cluster-specific roles and policies. :::note - If you use **ai-unlimited-without-iam-role-permissions.json**, attach [ai-unlimited-engine.json](https://github.com/Teradata/ai-unlimited/blob/develop/deployments/aws/policies/ai-unlimited-engine.json) to the engine role's policy. + If you use [ai-unlimited-without-iam-role-permissions.json](https://github.com/Teradata/ai-unlimited/blob/develop/deployments/aws/policies/ai-unlimited-workspaces-without-iam-role-permissions.json) for the manager's role, use [ai-unlimited-engine.json](https://github.com/Teradata/ai-unlimited/blob/develop/deployments/aws/policies/ai-unlimited-engine.json) for the engine's role. ::: - Optionally, include [session-manager.json](https://github.com/Teradata/ai-unlimited/blob/develop/deployments/aws/policies/session-manager.json): It includes permissions for the engine to interact with the [AWS Session Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager.html). Use this if you plan to use Session Manager to connect to the engine to closely manage it. @@ -102,10 +101,10 @@ If your security does not allow AI Unlimited to create roles, provide them. ``` :::note -In the policy for the manager's role, use [ai-unlimited-without-iam-role-permissions.json](https://github.com/Teradata/ai-unlimited/blob/develop/deployments/aws/policies/ai-unlimited-workspaces-without-iam-role-permissions.json). +If you use [ai-unlimited-engine.json](https://github.com/Teradata/ai-unlimited/blob/develop/deployments/aws/policies/ai-unlimited-engine.json) for the engine's role, use [ai-unlimited-without-iam-role-permissions.json](https://github.com/Teradata/ai-unlimited/blob/develop/deployments/aws/policies/ai-unlimited-workspaces-without-iam-role-permissions.json) for the manager's role. ::: -- Put the role's name in the **Default IAM role** field during setup. +- When you [set up AI Unlimited](/docs/install-ai-unlimited/setup-ai-unlimited.md), put the role name in the **Default IAM role** field. diff --git a/docs/resources/azure-requirements.md b/docs/resources/azure-requirements.md index f2a65fc220..db871c3adb 100644 --- a/docs/resources/azure-requirements.md +++ b/docs/resources/azure-requirements.md @@ -12,28 +12,31 @@ pagination_next: null ***(This topic is still being worked - please disregard for now.)*** -- Work with your cloud admin to ensure your Azure account has permissions to create the cloud resources definined in the [AI Unlimited template](https://github.com/Teradata/ai-unlimited/blob/develop/deployments/azure/ai-unlimited.json). +Prepare your Azure account: + +- Work with your cloud admin to ensure your Azure account has the permissions needed to create the cloud resources definined in the [AI Unlimited template](https://github.com/Teradata/ai-unlimited/blob/develop/deployments/azure/ai-unlimited.json). - Networking requirements: Your Azure [resource group](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-portal) must have an [Azure Virtual Network (VNet)](https://learn.microsoft.com/en-us/azure/virtual-network/quick-create-portal) configured with a [subnet](https://learn.microsoft.com/en-us/azure/virtual-network/virtual-network-manage-subnet?tabs=azure-portal). Use an existing VNet or subnet, or create your own, depending on your account permissions. ***(This roll link was included, how does it fit with the context? [role](https://learn.microsoft.com/en-us/azure/role-based-access-control/custom-roles))*** -- If you'll need to access the manager instance, after it is installed, to run commands or debug, you can use a [key pair](https://learn.microsoft.com/en-us/azure/virtual-machines/linux/mac-create-ssh-keys) to securely connect using Secure Shell (SSH). You'll need the key pair when you [specify the manager's stack details](/docs/install-ai-unlimited/prod-azure-portal-deploy-manager.md#azure-parms). +- If you'll need to access the manager instance, after it is installed, to run commands or debug, you can use a [key pair](https://learn.microsoft.com/en-us/azure/virtual-machines/linux/mac-create-ssh-keys) that you generate to securely connect using Secure Shell (SSH). You'll need the key pair when you [specify the instance details](/docs/install-ai-unlimited/prod-azure-portal-deploy-manager.md#azure-parms). ## Create the role required by the manager -The manager's role allows it to deploy the engine. Each time the manager deploys the engine, AI Unlimited creates a new role for the engine to enable its nodes to communicate. +The manager's role allows it to deploy the engine. Each time the manager deploys the engine, the manager creates a new role for the engine to enable its nodes to communicate. ***(Jack is looking into whether we provide the role or if the user has to provide it.)*** -If you have the permissions needed to create roles, create the role for the manager using the [role-policy](https://github.com/Teradata/ai-unlimited/blob/develop/deployments/azure/role-policy.json) template. (with the [ai-unlimited.json](https://github.com/Teradata/ai-unlimited/blob/develop/deployments/azure/policies/ai-unlimited.json) policy?) +If you have the permissions needed to create roles, create the role for the manager using the [role-policy](https://github.com/Teradata/ai-unlimited/blob/develop/deployments/azure/role-policy.json) template. ***(with the [ai-unlimited.json](https://github.com/Teradata/ai-unlimited/blob/develop/deployments/azure/policies/ai-unlimited.json) policy or is that baked in? verify)*** See [Create or update Azure custom roles using the Azure portal](https://learn.microsoft.com/en-us/azure/role-based-access-control/custom-roles-portal) for details. -You'll need the `RoleDefinitionId` when you [specify the manager's stack details](/docs/install-ai-unlimited/prod-azure-portal-deploy-manager.md#azure-parms). +Or share [ai-unlimited.json](https://github.com/Teradata/ai-unlimited/blob/develop/deployments/azure/policies/ai-unlimited.json) with your cloud admin they can create the custom role for you. + +You'll need the `RoleDefinitionId` when you [specify the instance details](/docs/install-ai-unlimited/prod-azure-portal-deploy-manager.md#azure-parms). -Optionally, you can share the [ai-unlimited.json](https://github.com/Teradata/ai-unlimited/blob/develop/deployments/azure/policies/ai-unlimited.json) file with your cloud admin to create the custom role for you. diff --git a/docs/resources/git-requirements.md b/docs/resources/git-requirements.md index b90b37cb2b..661889f835 100644 --- a/docs/resources/git-requirements.md +++ b/docs/resources/git-requirements.md @@ -10,7 +10,7 @@ pagination_next: null # Git requirements -Make sure you have a GitHub or GitLab account, and complete these tasks. +Make sure you have a GitHub or GitLab account. And complete these two tasks. ## Clone the provided repository @@ -30,23 +30,16 @@ An OAuth app allows a user to grant access to their account on one website or se 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. -:::note -AI Unlimited creates this repository when you install the AI Unlimited manager. ***READ Jack's slack response to my Q*** -::: - 1. Sign in to your GitHub or GitLab account. 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). While registering the OAuth app, use these URLs. - - Homepage URL: - - If you are using the QuickStart, `http://localhost:3000` - - For a demo or full installation, `http://[ip_or_hostname]:[port]` - - + - Homepage URL: `http://[ip_or_hostname]:[port]` + - Authorization callback URL: `[Homepage URL]/auth/github/callback` For GitLab, select the appropriate OAuth **Scopes** as defined in [Authorized Applications](https://docs.gitlab.com/ee/integration/oauth_provider.html#view-all-authorized-applications). -3. Copy and retain the **Client ID** and **Client secret**. You'll use them to authorize AI Unlimited to save user and project information. +3. Copy and keep the **Client ID** and **Client secret**. You'll use them when you [set up AI Unlimited](/docs/install-ai-unlimited/setup-ai-unlimited.md). diff --git a/docs/resources/index.md b/docs/resources/index.md index 5f18355d73..5917727085 100644 --- a/docs/resources/index.md +++ b/docs/resources/index.md @@ -10,4 +10,4 @@ pagination_next: null # Other resources -Here you'll find more installation-related resources. \ No newline at end of file +Here you'll find more installation-related, and other, resources. \ No newline at end of file diff --git a/docs/resources/jupyterlab/index.md b/docs/resources/jupyterlab/index.md index df88d28117..7ca6c727c7 100644 --- a/docs/resources/jupyterlab/index.md +++ b/docs/resources/jupyterlab/index.md @@ -14,9 +14,9 @@ You may already have [JupyterLab](https://jupyter.org/)—somewhere on the c Or, get JupyterLab with the AI Unlimited kernel now: -- Install it on [AWS](/docs/advanced/jupyterlab/install-jupyterlab-aws.md) or on [Azure](/docs/advanced/jupyterlab/install-jupyterlab-azure.md) -- [Run it locally](/docs/advanced/jupyterlab/run-jupyterlab-docker.md) in a Docker container +- Install it on [AWS](/docs/resources/jupyterlab/install-jupyterlab-aws.md) or on [Azure](/docs/resources/jupyterlab/install-jupyterlab-azure.md) +- [Run it locally](/docs/resources/jupyterlab/run-jupyterlab-docker.md) in a Docker container :::note -The [QuickStart](/docs/advanced/quickstart) includes JupyterLab. If you plan to use the QuickStart, you do not need to install JupyterLab separately. +The [QuickStart](/docs/resources/quickstart) includes JupyterLab. If you plan to use the QuickStart, you do not need to install JupyterLab separately. ::: diff --git a/docs/resources/jupyterlab/install-jupyterlab-aws.md b/docs/resources/jupyterlab/install-jupyterlab-aws.md index c8bb5a08b3..fd7dff0af9 100644 --- a/docs/resources/jupyterlab/install-jupyterlab-aws.md +++ b/docs/resources/jupyterlab/install-jupyterlab-aws.md @@ -10,7 +10,7 @@ pagination_next: null # Install JupyterLab on AWS -You'll use a CloudFormation template provided by Teradata to install JupyterLab, and the AI Unlimited kernel, from the AWS Management Console. +You'll use a CloudFormation template provided by Teradata to install JupyterLab and the AI Unlimited kernel from the AWS Management Console. This deploys a server instance, with JupyterLab running in a container controlled by [systemd](/docs/glossary.md#glo-systemd). @@ -24,7 +24,14 @@ References to the AWS Management Console are accurate as of April 11, 2024. ## Prepare your AWS account -***(to be adapted from the manager's prep account topic - probably make it a separate topic as it was originally)*** +- Work with your cloud admin to ensure you have the [IAM](https://aws.amazon.com/iam/) permissions you need to create the cloud resources defined in your choice of [JupyterLab template](https://github.com/Teradata/ai-unlimited/tree/develop/deployments/aws/templates/jupyter). + +- If you'll need to access the JupyterLab instance, after it is installed, to run commands or debug, you can use a [key pair](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) you generate to securely connect using Secure Shell (SSH). You will need the key pair when you [specify the stack details](#jup-aws-parms). + +- If you’re using an [Application Load Balancer (ALB)](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/application-load-balancer-getting-started.html) or [Network Load Balancer (NLB)](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/network-load-balancer-getting-started.html), 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. + - [AWS Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/Welcome.html)—to configure a custom domain name and route DNS queries to your load balancer. + ## Download the Jupyter template @@ -44,21 +51,20 @@ CloudFormation templates for JupyterLab are here in the AI Unlimited GitHub repo ## Upload the template -1. Sign in to the [AWS console](https://aws.amazon.com), and select the region in which to deploy AI Unlimited. - Teradata recommends selecting the region closest to your primary work location. +1. Sign in to the [AWS console](https://aws.amazon.com), and select the region in which to deploy JupyterLab. + We recommend selecting the region closest to your primary work location. 3. Search for and go to **CloudFormation**. 4. Select **Create Stack**, then **With new resources (standard)**. 5. Select **Choose an existing template** and **Upload a template file**. 6. Choose the template file you downloaded, and click **Next**. + ## Specify stack details and options 1. Provide a stack name. 2. Review the parameters. Provide values for the required ones. Your organization might require others. -***We are working on the table/scrollbar issues.*** -
AWS and JupyterLab parameters @@ -129,12 +135,14 @@ If the container, pod, or node crashes or terminates, and the JupyterLab configu ## Review and create the stack +***Can a tester please provide a screen recording so we can verify these steps?*** + 1. Review the template settings. 2. Select the check box to acknowledge that the template will create IAM resources. -3. Select **Submit** to deploy the stack. -4. Monitor the stack's status. When you see `CREATE_COMPLETE`, JupyterLab is ready. +3. Select **Submit** to deploy the stack.
+On the **Events** tab, you can monitor progress. When the **Status** is `CREATE_COMPLETE`, the JupyterLab is ready. + +The **Outputs** tab shows the URL for accessing JupyterLab. -You'll find the JupyterLab connection parameters in **Outputs**. -***Haven't actually seen what happens after clicking Submit.*** diff --git a/docs/resources/jupyterlab/install-jupyterlab-azure.md b/docs/resources/jupyterlab/install-jupyterlab-azure.md index 6d8830efd6..96ef1487bf 100644 --- a/docs/resources/jupyterlab/install-jupyterlab-azure.md +++ b/docs/resources/jupyterlab/install-jupyterlab-azure.md @@ -25,7 +25,15 @@ References to the Azure Portal are accurate as of April 14, 2024. ## Prepare your Azure account -***(to be adapted from the manager's prep account topic - probably make it a separate topic as it was originally)*** +***(update after Azure requirements topic is done)*** + +- Work with your cloud admin to ensure your Azure account has the permissions needed to create the cloud resources definined in the [JupyterLab template](https://github.com/Teradata/ai-unlimited/blob/develop/deployments/azure/jupyter.json). + +- Networking requirements: Your Azure [resource group](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-portal) must have an [Azure Virtual Network (VNet)](https://learn.microsoft.com/en-us/azure/virtual-network/quick-create-portal) configured with a [subnet](https://learn.microsoft.com/en-us/azure/virtual-network/virtual-network-manage-subnet?tabs=azure-portal). Use an existing VNet or subnet, or create your own, depending on your account permissions. + +***(This roll link was included, how does it fit with the context? [role](https://learn.microsoft.com/en-us/azure/role-based-access-control/custom-roles))*** + +- If you'll need to access the JupyterLab instance, after it is installed, to run commands or debug, you can use a [key pair](https://learn.microsoft.com/en-us/azure/virtual-machines/linux/mac-create-ssh-keys) you generate to securely connect using Secure Shell (SSH). You'll need the key pair when you [specify the instance details](#jup-azure-parms). ## Download the Jupyter template @@ -40,47 +48,81 @@ Download the template (`/deployments/azure/jupyter.json`) from the AI Unlimited 4. Choose the template file you downloaded, and select **Save**. + ## Specify instance details Review the parameters. Provide values for the required ones. Your organization might require others. -***We are working on the table/scrollbar issues.*** -
Azure and JupyterLab parameters | Parameter | Description | Notes |---------|-------------|-----------| -| Subscription | The Azure subscription you want to use for deploying AI Unlimited. | Required
Default:NA
We recommend using an account that is not a Free Trial. | -| Region | The region where you want to deploy AI Unlimited. | Required
Default:NA
Select the Azure region closest to your work location and the data resources to use with AI Unlimited. | +| Subscription | The Azure subscription you want to use for deploying AI Unlimited. | Required
Default: NA
We recommend using an account that is not a Free Trial. | +| Region | The region where you want to deploy AI Unlimited. | Required
Default: NA
Select the Azure region closest to your work location and the data resources to use with AI Unlimited. | | Resource Group Name | The name of the container that groups together related AI Unlimited resources. | Required
Default: ai-unlimited-jupyter | | OS Version | The versions of the operating systems that are available in the current subscription.| Optional with default
Default: Ubuntu-2004 | | Instance Type | The instance type that you want to use for AI Unlimited.| Optional
Default: STANDARD_D2_V3
We recommend using the default instance type to save costs. The default instance type is the standard Dv3 series with 2 vCPUs and 8.0 GiB of memory.| | Network | The name of the network to which you want to deploy the AI Unlimited instance.| Optional
Default: NA| -| Subnet | The subnetwork to which you want to deploy the AI Unlimited instance.| Required
Default:NA
The subnet must reside in the selected availability zone. | -| Security Group | The virtual firewall that controls inbound and outbound traffic to the instance. | Optional
Default:JupyterSecurityGroup
Security Group is implemented as a set of rules that specify which protocols, ports, and IP addresses or CIDR blocks are allowed to access the instance. Define at least one of Access CIDR, or Security Group to allow inbound traffic unless you create custom security group ingress rules. | +| Subnet | The subnetwork to which you want to deploy the AI Unlimited instance.| Required
Default: NA
The subnet must reside in the selected availability zone. | +| Security Group | The virtual firewall that controls inbound and outbound traffic to the instance. | Optional
Default: JupyterSecurityGroup
Security Group is implemented as a set of rules that specify which protocols, ports, and IP addresses or CIDR blocks are allowed to access the instance. Define at least one of Access CIDR, or Security Group to allow inbound traffic unless you create custom security group ingress rules. | | Access CIDR | The CIDR IP address range that is permitted to access the instance. | Optional
Default: 0.0.0.0/0
We recommend setting this value to a trusted IP range. Define at least one of Access CIDR, or Security Group to allow inbound traffic unless you create custom security group ingress rules. | -| Source App Sec Groups (ASG) | The source application security groups that have permission to connect to the AI Unlimited instance. ASGs let you organize your virtual machines (VMs) based on their specific network security policies. These security policies determine what traffic is or is not permissible on your virtual machine. | Optional
Default:NA
Select an application security group in the same region as the network interface. | -| Destination App Sec Groups | The destination application security Groups that have permission to connect to the AI Unlimited instance. | Optional
Default:NA
Select an application security group in the same region as the network interface.  | -| Role Definition ID | The ID of the role to use with AI Unlimited. | Required
Default:NA
Use Azure CLI command- `Get-AzRoleDefinition` command to get your Role Definition ID. | -| Allow Public SSH | Specifies whether you can use secure shell (SSH) keys to connect to VMs in Azure. | Optional
Default:true | -| Public Key | The public SSH Key that you can use to connect to a VM over SSH. | Optional
Default:NA
This value must start with `ssh-rsa`.  | -| Use Persistent Volume | Specifies whether you want to use persistent volume to store data.| Optional with default
Default: New
Supported options are: new persistent volume, an existing one, or none, depending on your use case. | +| Source App Sec Groups (ASG) | The source application security groups that have permission to connect to the AI Unlimited instance. ASGs let you organize your virtual machines (VMs) based on their specific network security policies. These security policies determine what traffic is or is not permissible on your virtual machine. | Optional
Default: NA
Select an application security group in the same region as the network interface. | +| Destination App Sec Groups | The destination application security Groups that have permission to connect to the AI Unlimited instance. | Optional
Default: NA
Select an application security group in the same region as the network interface. | +| Role Definition ID | The ID of the role to use with AI Unlimited. | Required
Default: NA
Use Azure CLI command- `Get-AzRoleDefinition` command to get your Role Definition ID. | +| Allow Public SSH | Specifies whether you can use secure shell (SSH) keys to connect to VMs in Azure. | Optional
Default: true | +| Public Key | The public SSH Key that you can use to connect to a VM over SSH. | Optional
Default: NA
This value must start with `ssh-rsa`.  | +| Use Persistent Volume | Specifies whether you want to use persistent volume to store data. See *Learn more: Why use a persistent volume?* below the parameters section. | Optional with default
Default: New
Supported options are: new persistent volume, an existing one, or none, depending on your use case. | | Persistent Volume Size | The size of the persistent volume that you can attach to the instance, in GB. | Optional
Default: 100
Supports values between 8  and 1000. | -| Existing Persistent Volume | The ID of the existing persistent volume that you can attach to the instance.| Required if UsePersistentVolume is set to Existing.
Default:NA
The persistent volume must be in the same availability zone as the AI Unlimited instance. | +| Existing Persistent Volume | The ID of the existing persistent volume that you can attach to the instance.| Required if Use Persistent Volume is set to Existing
Default: NA
The persistent volume must be in the same availability zone as the AI Unlimited instance. | | JupyterHttpPort | The port to access the JupyterLab service UI. | Required with default
Default: 8888 | | JupyterVersion | The version of JupyterLab you want to deploy. | Required with default
Default: latest
The value is a container version tag, for example, latest. | | JupyterToken | The token or password used to access JupyterLab from the UI.| Required
Default: NA
The token must begin with a letter and contain only alphanumeric characters. The allowed pattern is ^[a-zA-Z][a-zA-Z0-9-]*. |
+
+ +Learn more: Why use a persistent volume? + +The JupyterLab instance runs in a container and saves its configuration data in a database in the root volume of the instance. This data persists if you shut down, restart, or snapshot and relaunch the instance. + +But a persistent volume stores data for a containerized application beyond the lifetime of the container, pod, or node in which it runs. + +#### Without a persistent volume + +If the container, pod, or node crashes or terminiates, you lose the JupyterLab configuration data. You can deploy a new JupyterLab instance, but not to the same state as the one that was lost. + +#### With a persistent volume + +If the container, pod, or node crashes or terminates, and the JupyterLab configuration data is stored in a persistent volume, you can deploy a new JupyterLab instance that has the same configuration as the one that was lost. + +#### Example + +1. Deploy JupyterLab, and include these parameters: + - `UsePersistentVolume`: **New** +3. After you create the stack, on the **Outputs** tab, note the `volume-id`. +4. Use JupyterLab. +5. If the JupyterLab instance is lost, deploy JupyterLab again, and include these parameters: + - `UsePersistentVolume`: **New** + - `ExistingPersistentVolumeId`: the value you noted in step 2 + +The new JupyterLab instance has the same configuration as the one that was lost. + +
+ ## Create the instance -1. Select **Review + Create**, then **Create**. -2. Monitor the deployment status on the **Notifications** page. +***Can a tester please provide a screen recording so we can verify these steps?*** + +1. Select **Review + create**. +2. Select **Create**.
+On the **Notifications** page, you can monitor progress. ***(accurate?)*** + +When deployment is complete, the **Outputs** page shows the URL for accessing JupyterLab. + + -After the template is deployed, you'll find the JupyterLab connection parameters in **Outputs**. -***Haven't actually seen what happens after clicking Create.*** diff --git a/docs/resources/quickstart/docker-install-ai-unlimited-jupyter.md b/docs/resources/quickstart/docker-install-ai-unlimited-jupyter.md index e615b1ed3f..e12e13e6fb 100644 --- a/docs/resources/quickstart/docker-install-ai-unlimited-jupyter.md +++ b/docs/resources/quickstart/docker-install-ai-unlimited-jupyter.md @@ -4,6 +4,8 @@ title: QuickStart - Run AI Unlimited and JupyterLab using Docker description: Learn how to run AI Unlimited and JupyterLab using Docker. sidebar_label: Run the manager and JupyterLab using Docker sidebar_position: 3 +pagination_prev: null +pagination_next: null --- import Tabs from '@theme/Tabs'; @@ -11,9 +13,9 @@ import TabItem from '@theme/TabItem'; # Run the manager and JupyterLab using Docker -The AI Unlimited manager orchestrates the engine's deployment and includes a web-based user interface for monitoring projects. And the manager is where you'll set up AI Unlimited. +The AI Unlimited manager orchestrates the engine's deployment and includes a web-based user interface for monitoring projects. And the manager is where you'll set up AI Unlimited. -Installing the manager also creates a Git repository for user and project information. +You'll use JupyterLab to explore and analyze data. You'll use [Docker Compose](https://docs.docker.com/compose/) to run the AI Unlimited manager and JupyterLab, with the AI Unlimited Jupyter Kernel, locally in containers. @@ -66,7 +68,7 @@ This QuickStart uses the first method. -2. In the Teradata AI Unlimited GitHub repository, open the `[AWS or Azure]-credentials-env-vars.yaml` file and update the environment variable values. +2. In the [Teradata AI Unlimited GitHub repository](https://github.com/Teradata/ai-unlimited), open the `[AWS or Azure]-credentials-env-vars.yaml` file and update the environment variable values. ## Start the manager and JupyterLab diff --git a/docs/resources/quickstart/docker-when-you-are-done.md b/docs/resources/quickstart/docker-when-you-are-done.md index 86a36244b7..c2fc5ca380 100644 --- a/docs/resources/quickstart/docker-when-you-are-done.md +++ b/docs/resources/quickstart/docker-when-you-are-done.md @@ -3,6 +3,7 @@ id: docker-when-you're-done title: When you're done description: Prerequisites for installing Teradata AI Unlimited using Docker. sidebar_position: 7 +pagination_prev: null pagination_next: null --- import Tabs from '@theme/Tabs'; diff --git a/docs/resources/quickstart/index.md b/docs/resources/quickstart/index.md index c1d8819247..30c266d987 100644 --- a/docs/resources/quickstart/index.md +++ b/docs/resources/quickstart/index.md @@ -5,6 +5,7 @@ description: Start here to install AI Unlimited for a single user quickly. sidebar_label: QuickStart sidebar_position: 6 pagination_prev: null +pagination_next: null --- # QuickStart diff --git a/docs/resources/release-notes.md b/docs/resources/release-notes.md new file mode 100644 index 0000000000..113e1f4c8b --- /dev/null +++ b/docs/resources/release-notes.md @@ -0,0 +1,13 @@ +--- +id: release-notes +title: Release notes +description: Find notes about the current release +sidebar_label: Release notes +sidebar_position: 6 +pagination_prev: null +pagination_next: null +--- + +# Git requirements + +placeholder for information about CS functions limitations