Merge pull request #410 from MicrosoftDocs/main

9/25 OOB Publish

Author: huypub

articles/cyclecloud/how-to/ccws/cleanup-roles.md

@@ -0,0 +1,18 @@
+---
+title: How to clean up roles using the CLI
+description: How to clean up roles built in a Azure CycleCloud Workspace for Slurm environment using the Azure CLI
+author: xpillons
+ms.date: 08/29/2024
+ms.author: xpillons
+---
+
+# Cleaning up roles
+
+Deleting a deployment's resource group will delete all of the resources created by Azure Azure CycleCloud Workspace for Slurm but fail to remove its role assignments. To fix this, we provide `util/delete_roles.sh` to delete these role assignments for all resource groups, including those that were deleted or had their resources manually deleted.
+
+```bash
+./util/delete_roles.sh --location my-location --resource-group my-ccws-rg [--delete-resource-group]
+```
+
+> [!NOTE]
+> It is required to temporarily recreate a deleted resource group in a simple deployment that outputs the GUIDs produced for the given resource group name and location. Passing in `--delete-resource-group` will clean up this resource group irrespective of whether it is a byproduct of this utility or created by the user.

articles/cyclecloud/how-to/ccws/connect-to-login-node-with-bastion.md

@@ -0,0 +1,34 @@
+---
+title: How to connect to a Login Node through Bastion
+description: How to securily connect using SSH to a Login Node through Bastion
+author: xpillons
+ms.date: 08/30/2024
+ms.author: xpillons
+---
+
+# How to connect to a Login Node through Bastion
+There is no SSH route open from your local environment to Virtual Machines running in an Azure CycleCloud Workspace for Slurm by default for security reasons. However, an Azure Bastion can be deployed and used to SSH through to your Virtual Machines. Below are the instructions on how to do based on this documentation: [Connect to a VM using Bastion](/azure/bastion/connect-vm-native-client-linux).
+
+## Step 1 – Identify the SSH private key locally
+Locate the private SSH key file associated with the public key provided during the deployment. If it is not accessible locally, then download it.
+
+## Step 2 – Retrieve the Resource ID of the Login Node
+From the CycleCloud UI, select the Login node to which you want to connect and double click on that line to open the detail view of the node. Select the VM tab to display the resource details below and copy the `ResourceId`.
+
+![Login Node properties](../../images/ccws/login-node-resource-id.png)
+
+## Step 3 – Create a connect script
+Create a login script using the template below. Paste the login node `resourceID` retrieved above and specify the resource group and the private SSH key file to use.
+
+```bash
+#!/bin/bash
+resourceId=<paste_your_loginnode_id>
+resourceGroup=$(echo $resourceId | cut -d'/' -f5)
+
+az network bastion ssh --name bastion --resource-group $resourceGroup --target-resource-id $resourceId --auth-type ssh-key --username hpcadmin --ssh-key hpcadmin_id_rsa
+```
+
+> Note: The github repository https://github.com/Azure/cyclecloud-slurm-workspace.git contains the utility script `./util/ssh_thru_bastion.sh` to help connecting.
+
+## Step 4 - Connect
+Run the script created/updated above to SSH on the login node.

articles/cyclecloud/how-to/ccws/deploy-with-cli.md

@@ -0,0 +1,43 @@
+---
+title: How to deploy a CycleCloud Workspace for Slurm environment using the CLI
+description: How to deploy a CycleCloud Workspace for Slurm environment using the Azure CLI and the Azure Portal UI Sandbox
+author: xpillons
+ms.date: 08/22/2024
+ms.author: xpillons
+---
+
+# How to deploy a CycleCloud Workspace for Slurm environment using the CLI
+
+Prerequisites: Users will need to install the Azure CLI and Git. They will then need to sign into or set their Azure subscription.
+
+- Clone the Azure CycleCloud Workspace for Slurm on the latest stable release
+
+```bash
+git clone https://github.com/Azure/cyclecloud-slurm-workspace.git --branch <release>
+```
+
+- Copy the content of the UI definition file `./uidefinitions/createUiDefinition.json`
+
+- Browse to the UI Definition Sandbox:
+    - For Azure Public Cloud [Azure Public Portal](https://portal.azure.com/#view/Microsoft_Azure_CreateUIDef/SandboxBlade)
+    - For Azure US Gov [Azure US Gov Portal](https://portal.azure.us/#view/Microsoft_Azure_CreateUIDef/SandboxBlade)
+
+- Paste the content of the UI Definition file into the multiline text box in the right,
+- Click `Preview >>` in the bottom-left corner. This will bring up a UI experience. 
+- Proceed through each page of the UI flow to ensure that necessary values populate in the output payload described in the next step,
+- Proceed with the UI flow to the `Review + create` page and then click the link labeled `View outputs payload` adjacent to the `Create` button. This will generate a pane with JSON-formatted text in its body on the right-hand side of the browser window,
+- Copy the JSON-formatted text into a local JSON file, 
+- Save it as `parameters.json` and make note of the path to it. This is what we call the Parameters File for the deployment,
+- Open the shell of choice and navigate to the folder/directory that contains the `cyclecloud-slurm-workspace` repository cloned above,
+- Accept the terms of the Cycle image plan:  
+
+```bash
+az vm image terms accept --urn azurecyclecloud:azure-cyclecloud:cyclecloud8-gen2:latest
+```
+- Run the following deployment command in shell. Substitutions should be made for fields with square brackets (be sure to delete brackets). The instructions below assume that the current directory is as described in the previous step,
+
+```bash
+az deployment sub create --template-file ./cyclecloud-slurm-workspace/bicep/mainTemplate.bicep --parameters parameters.json --location [ANY AZURE LOCATION E.G. eastus] --name [OPTIONAL BUT HELPFUL, DELETE IF UNUSED] 
+```
+
+- Wait until the shell indicates that the deployment was successful. One can also track the progress of the deployment in the Azure Portal by navigating to the resource group indicated in the UI, selecting `Deployments` from the Settings dropdown menu on the left-hand side menu, and checking the Status of the Deployment Name that begins with “pid-” at the bottom of the displayed list.

articles/cyclecloud/how-to/ccws/plan-your-deployment.md

@@ -0,0 +1,47 @@
+---
+title: Plan your CycleCloud Workspace for Slurm Deployment
+description: A checklist to help plan for your CycleCloud Workspace for Slurm deployment
+author: xpillons
+ms.date: 08/22/2024
+ms.author: xpillons
+---
+
+# Plan your CycleCloud Workspace for Slurm Deployment
+You can deploy either a greenfield environment in which all resources needed for Azure CycleCloud Workspace for Slurm will be provisioned for you or a brownfield deployment for which you will provide existing resources.
+
+When doing a deployment, the Azure user account used need to be granted the following roles:
+- `Contributor` on the Subscription
+- `User Access Administrator` on the Subscription
+
+## Greenfield Deployment
+
+In a greenfield deployment, the following resources and role assignments will be created:
+- Resource Group
+- The Virtual Network, its subnets `ccw-cyclecloud-subnet`, and `ccw-compute-subnet`
+- The Virtual Machine `ccw-cyclecloud-vm`, NIC, OS, Data Disks, and a System Managed Identity
+- A uniquely named storage account for CycleCloud projects
+- Network Security Group named `nsg-ccw-common`
+- `Contributor`, `Storage Account Contributor`, and `Storage Blob Data Contributor` roles at the subscription level for the CycleCloud VM System Managed Identity
+- Optionally a Bastion, subnet `AzureBastionSubnet`, and public IP `bastion-pip`
+- Optionally a NAT gateway named `ccw-nat-gateway` and public IP `pip-ccw-nat-gateway`
+- Optionally an Azure NetApp Files account, pool, and volume with subnet `hpc-anf-subnet`
+- Optionally an Azure Managed Lustre Filesystem with subnet `ccw-lustre-subnet`
+- Optionally a VNET Peering
+- Optionally a Private Endpoint to an existing Azure Database for MySQL flexible server instance
+
+## Brownfield Deployment
+You will be able to provide existing resources for:
+- The VNET and subnets in which the environment will be deployed
+- Filesystem Storage for the users's home directories and/or additional filers, as external NFS mount points or Azure Managed Lustre Filesystem
+- an Azure Database for MySQL flexible server instance for Slurm Job Accounting
+
+If you bring your own VNET you have to follow these pre-requisistes:
+- a /29 **cyclecloud** subnet for the CycleCloud VM, with `Microsoft.Storage` Service Endpoint assigned,
+- a **compute** subnet for the nodes, with `Microsoft.Storage` Service Endpoint assigned. This is where the scheduler, login, and compute nodes will be created
+- when using Azure NetApp Files, a dedicated **netapp** subnet with the `Microsoft.NetApp/volumes` delegation as documented here [Azure NetApp Files](/azure/azure-netapp-files/azure-netapp-files-introduction).
+- when using Azure Managed Lustre Filesystem, a dedicated **lustre** subnet with a CIDR based on the storage capacity to provision as documented here [Azure Managed Lustre](/azure/azure-managed-lustre/amlfs-overview)
+- if deploying a Bastion, a dedicated **BastionSubnet** as documented [here](/azure/bastion/configuration-settings#subnet)
+- Your NSGs should allow communications between subnets as defined in the [bicep/network-new.bicep](https://github.com/Azure/cyclecloud-slurm-workspace/blob/main/bicep/network-new.bicep) file.
+
+## Quotas
+Before deploying, ensure that your subscription has the required quota for the Virtual Machine types desired for CycleCloud nodes.

articles/cyclecloud/how-to/create-app-registration.md

@@ -53,14 +53,15 @@ ms.author: aevdokimova
 
     At a minimum, add the following roles:
     ![Basic roles required for CycleCloud](../images/entra_setup/entra21.png)
-
+1. By default, the app registration issues access tokens v2.0, which are currently not supported by CycleCloud. To configure the issuing of tokens v1.0, you should select **Manifest**, locate the property **accessTokenAcceptedVersion** in the manifest, and change the value of that property to **null**. Once you changed the token version, select **Save**.
+![Manifest menu](../images/entra_setup/entra24.png)
 ## Permissioning Users for CycleCloud
 
 1. After you have create the required CycleCloud roles, you may add users and assign roles to them. To do this, navigate to the app’s **Enterprise Application** page. The easiest way to do it is via a helper link located on your App roles page 
 ![A shortcut to get to the Enterprise Application's role assignment window](../images/entra_setup/entra10.png)
 1. To add a user and assign a role, navigate to **Users and groups** page of the Enterprise Application and select **Add user/group**
 ![Add a user/group menu](../images/entra_setup/entra11.png)
-1. On the **Add Assignment** page, select one or more users and the role (or roles) to be assigned to them. You can use a search bar to filter users (since only one app role was created in the screenshot, it is selected automatically – you might need to select a list of roles to assign in the same way you did users)
+1. On the **Add Assignment** page, select one or more users and the role to be assigned to them. You can use a search bar to filter users (since only one app role was created in the screenshot, it is selected automatically, but the menu for selecting it is similar to how you select users). Only one role can be assigned at a time, so, to add multiple roles to the same user, you will need to go through this process several times.
 ![Add a role assignment selection](../images/entra_setup/entra12.png)
 ![Add a role assignment completion](../images/entra_setup/entra13.png)
 1. After the role is assigned, the user should show up on the **User and groups** page – please note that assigning multiple roles to a single user will result in several entries for that user - one entry per role.

articles/cyclecloud/how-to/managed-identities.md

@@ -56,6 +56,7 @@ A sufficient policy for most CycleCloud features is posted below.
           "Microsoft.Compute/virtualMachineScaleSets/virtualMachines/*",
           "Microsoft.ManagedIdentity/userAssignedIdentities/*/assign/action",
           "Microsoft.MarketplaceOrdering/offertypes/publishers/offers/plans/agreements/read",
+          "Microsoft.MarketplaceOrdering/offertypes/publishers/offers/plans/agreements/write",
           "Microsoft.Network/*/read",
           "Microsoft.Network/locations/*/read",
           "Microsoft.Network/networkInterfaces/read",