Documentation updates. (#182)

Azure · Aug 27, 2024 · 3ac2425 · 3ac2425
1 parent 8b4989e
commit 3ac2425
Show file tree

Hide file tree

Showing 7 changed files with 31 additions and 45 deletions.
diff --git a/README.md b/README.md
@@ -12,13 +12,7 @@ OSDU Developer enables the deployment of personal instances of the [OSDU™](htt
 > For a fully managed implementation use [Azure Data Manager for Energy](https://azure.microsoft.com/en-us/products/data-manager-for-energy).
 
 
-__Documentation__
-
-For detailed instructions please view our online [Documentation](https://azure.github.io/osdu-developer/)
-
-__Roadmap__
-
-Check out what is on the [roadmap](https://github.com/orgs/Azure/projects/696/views/2) and what the team is currently working on.
+For detailed instructions, view our online [Documentation](https://azure.github.io/osdu-developer/) and see what the team is currently working by looking through the [Roadmap](https://github.com/orgs/Azure/projects/696/views/2).
 
 ## OSDU Services
 

diff --git a/docs/src/feature_flags.md b/docs/src/feature_flags.md
@@ -25,7 +25,7 @@ Software customizations can be managed and modified using the following feature
 | SOFTWARE_VERSION          | Sets the version (branch) of OSDU to be installed                           |
 
 
-## Public Storage Access
+## Storage Access
 
 Control public access to Storage.
 
@@ -34,7 +34,7 @@ Control public access to Storage.
 | ENABLE_BLOB_PUBLIC_ACCESS | Enables public access for storage account blob (False by default)           |
 
 
-## Bastion Management
+## Private Access
 
 Modify the infrastructure and network by enabling Bastion Host with a virtual machine to use for access.
 
@@ -45,32 +45,24 @@ Modify the infrastructure and network by enabling Bastion Host with a virtual ma
 
 ## Cluster Network
 
-Modify the AKS cluster network configuration for Azure CNI with Dynamic IP allocation.
+Modify the cluster network configuration to utilize Azure CNI with Dynamic IP allocation.
 
 | Feature Flag              | Description                                                                 |
 |---------------------------|-----------------------------------------------------------------------------|
 | ENABLE_POD_SUBNET         | Enables a separate subnet for pod networking in the AKS cluster             |
 
 
-## Vnet Injection
-
-__Purpose:__ Enables a bring your own network capability.
-
-__Details:__ Typically, internal solutions require a preconfigured network due to possible S2S vpn configurations or a Hub Spoke Network design.
-
-__How To Enable:__
-
-```bash
-azd env set VIRTUAL_NETWORK_GROUP <your_network_group>
-azd env set VIRTUAL_NETWORK_NAME <your_network_name>
-azd env set VIRTUAL_NETWORK_PREFIX <your_network_prefix>
-azd env set VIRTUAL_NETWORK_IDENTITY <your_network_managed_identity>
-
-azd env set AKS_SUBNET_NAME <your_subnet_name>
-azd env set AKS_SUBNET_PREFIX <your_subnet_prefix>
-
-azd env set POD_SUBNET_NAME <your_subnet_name>
-azd env set POD_SUBNET_PREFIX <your_subnet_prefix>
-```
+## Virtual Network Injection
 
+Modify the network configuration for use with a pre-existing virtual network.
 
+| Feature Flag              | Description                                                                 |
+|---------------------------|-----------------------------------------------------------------------------|
+| VIRTUAL_NETWORK_GROUP     | Resource group of the existing virtual network                               |
+| VIRTUAL_NETWORK_NAME      | Name of the existing virtual network                                         |
+| VIRTUAL_NETWORK_PREFIX    | Address prefix of the existing virtual network                               |
+| VIRTUAL_NETWORK_IDENTITY  | Managed identity associated with the existing virtual network                |
+| AKS_SUBNET_NAME           | Name of the subnet for AKS within the existing virtual network               |
+| AKS_SUBNET_PREFIX         | Address prefix for the AKS subnet                                            |
+| POD_SUBNET_NAME           | Name of the subnet for Pods within the existing virtual network              |
+| POD_SUBNET_PREFIX         | Address prefix for the Pod subnet                                            |
diff --git a/docs/src/software.md b/docs/src/software.md
@@ -24,7 +24,7 @@ flowchart TD
 
 
 
-### Components Structure
+### Component Structure
 
 The Components directory is organized to facilitate the management of various middleware layers essential for our infrastructure. Below is the layout:
 

diff --git a/docs/src/tutorial_cli.md b/docs/src/tutorial_cli.md
@@ -1,4 +1,4 @@
-# Deploy using the AZD
+# Deploy using AZD
 
 The process for working with the solution using the Azure Developer CLI is the recommended way for deployent offering the most flexibility.  This process can be used if working directly with the solution on a computer, working in a Visual Studio Code remote container, or using a cloud environment like Github Codespaces.
 
@@ -9,7 +9,7 @@ It is recommended to use persistent files in Azure Cloud Shell for non-ephemeral
 - [How to Use Azure Cloud Shell](https://learn.microsoft.com/en-us/azure/cloud-shell/new-ui-shell-window)
 - [Persist Files in  Azure Cloud Shell](https://learn.microsoft.com/en-us/azure/cloud-shell/persisting-shell-storage)
 
-### 1. Prepare your Cloud Shell Environment
+### 1. Prepare your Cloud Shell
 
 Create a PowerShell profile for use with helper functions and restart the session.
 
@@ -102,14 +102,14 @@ azd provision
 A successful deployment will result in a web page opening for the Identity Provider. Retrieve a one time use Authorization Code and set it for the environment.
 
 
-### 4. Generate the settings
+### 4. Generate settings
 
 ```powershell
 azd env set AUTH_CODE=<your_auth_code>
 azd hooks run settings
 ```
 
-### 5. Clone the services and test
+### 5. Clone services and test
 
 Clone the OSDU Services
 
@@ -142,7 +142,7 @@ cd src/core/entitilements/testing/entitlements-v2-test-azure
 mvn test
 ```
 
-### 6. Remove services and cleanup (Optional)
+### 6. Clean up (Optional)
 
 After a deployment remove environment and delete the Azure Application that was created in Microsoft Entra.
 

diff --git a/docs/src/tutorial_click.md b/docs/src/tutorial_click.md
@@ -2,13 +2,13 @@
 
 The solution is a native bicep solution and includes a transpiled ARM template from the latest release.  This ARM template can then be easily used as a custom template deployment.
 
-### 1. Retrieve an existing or create a new Microsoft Entra Application
+### 1. Microsoft Entra App Create
 
 The solution requires the use of an Application to be registered in Microsoft Entra.
 
 ![Create Application](./images/tutorial_click_1.png)
 
-### 2. Collect the required IDs and secret from the Application
+### 2. Microsoft Entra App Info
 
 Create a new client secret to use and note the following IDs for the application.
 
@@ -18,7 +18,7 @@ Create a new client secret to use and note the following IDs for the application
 ![Client Id](./images/tutorial_click_2.png)
 ![Principal Id](./images/tutorial_click_3.png)
 
-### 2. Deploy the solution
+### 2. Deploy Solution
 
 [![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.luolix.top%2FAzure%2Fosdu-developer%2Fmain%2Fazuredeploy.json)
 
@@ -43,7 +43,7 @@ Additional fields are all optional changes.  Please see feature flags for furthe
 
 ![Principal Id](./images/tutorial_click_4.png)
 
-### 3. Validate completion
+### 3. Validate Completion
 
 Deployment is broken up into 2 parts, Infrastructure and Software.
 
@@ -55,15 +55,15 @@ Software deployment occurs after successful infrastructure and be seen by lookin
 ![Software Deployment](./images/tutorial_click_6.png)
 
 
-### 3. Set the Application SPA platform redirect URL
+### 3. Microsoft Entra App Auth
 
 Lookup the ingress IP address that has been configured under the kubernetes service `services and ingresses` blade and add the redirect uri to a spa platform on the application authentication blade.
 
 ![Ingress](./images/tutorial_click_7.png)
 ![Redirect](./images/tutorial_click_8.png)
 
 
-### 3. Retrieve an access token
+### 3. Retrieve Token
 
 Using the form located at `https://<ip_address>/auth/spa/` retrieve a valid access token by clicking the Authorize button which will return an authorization code, then clicking the Get Tokens button which will retrieve a limited use access token.
 
@@ -73,7 +73,7 @@ Using the form located at `https://<ip_address>/auth/spa/` retrieve a valid acce
 ![Token](./images/tutorial_click_9c.png)
 
 
-### 4. Using an api service swagger page execute api calls.
+### 4. Execute API Requests
 
 OSDU Services have swagger pages that are available.  Using the retrieved bearer token authenticate and execute API calls as desired.
 

diff --git a/docs/src/tutorial_rest.md b/docs/src/tutorial_rest.md
@@ -1,4 +1,4 @@
-# Test using REST
+# Test using REST scripts
 
 The solution has an integrated capability for the immediate execution of Rest API's using visual studio code. This integration only occurs if the Azure Developer CLI installation process has been performed.
 

diff --git a/docs/src/tutorial_vnet.md b/docs/src/tutorial_vnet.md
@@ -1,4 +1,4 @@
-# Virtual Network Injection
+# Using a Custom Network
 
 The provided custom deployment solution is a sample of how to leverage the virtual network (VNet) injection feature. This allows for the integration of the solution into a preexisting network design and ensuring the solution is on an internal network.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -24,7 +24,7 @@ flowchart TD



		### Components Structure
		### Component Structure

		The Components directory is organized to facilitate the management of various middleware layers essential for our infrastructure. Below is the layout:

Expand Down