+ ```
+
+## Azure Region and Subscription
+
+Azure subscriptions and region location are set interactively by default but can be directly specified.
+
+| Feature Flag | Description |
+|---------------------------|-----------------------------------------------------------------------------|
+| AZURE_SUBSCRIPTION_ID | Azure subscription ID for resource deployment |
+| AZURE_LOCATION | Azure location for resource deployment |
+
+## Microsoft Entra ID Application Registration
+
+Application registrations are created automatically with a naming convention of osdu-{environment}-{subscription} but can be manually created and provided.
| Feature Flag | Description |
|---------------------------|-----------------------------------------------------------------------------|
@@ -13,20 +41,23 @@ Entra App configurations are by default automatically created but one can be reu
| AZURE_CLIENT_PRINCIPAL_OID| Skip Principal ID lookup and use provided. |
| AZURE_TENANT_ID | Skip Tenant ID lookup and use provided. |
-## Custom Infrastructure
+## Deploy Custom Infrastructure
-Infrastructure customizations can be managed and modified using the following feature flags.
+Infrastructure customizations can be modified using the following feature flags.
| Feature Flag | Description |
|---------------------------|-----------------------------------------------------------------------------|
| ENABLE_BURSTABLE | User cheaper Burstable server types in the cluster |
| CLUSTER_INGRESS | Specifies the Ingress type for the cluster (External, Internal, or Both) |
| CLUSTER_VM_SIZE | Overrides the default server type with a custom VM size |
+| ENABLE_BLOB_PUBLIC_ACCESS | Enables public access for storage account blob (False by default) |
+| ENABLE_MANAGE | Enables a Bastion Host with a virtual machine for private admin access |
-## Custom Software
-Software customizations can be managed and modified using the following feature flags.
+## Configure Custom Software
+
+Software customizations can be modified using the following feature flags.
| Feature Flag | Description |
|---------------------------|-----------------------------------------------------------------------------|
@@ -38,43 +69,17 @@ Software customizations can be managed and modified using the following feature
| SOFTWARE_BRANCH | Customizes the branch used for software definition |
-## Experimental Software
+## Configure Experimental Software
-Experimental Software can be managed and modified using the following feature flags.
+Experimental Software can be enabled using the following feature flags.
| Feature Flag | Description |
|---------------------------|-----------------------------------------------------------------------------|
| ENABLE_EXPERIMENTAL | Enables loading of experimental software (False by default) |
| ENABLE_ADMIN_UI | Enables loading of the Admin UI (False by default) |
-## Storage Access
-
-Control public access to Storage.
-
-| Feature Flag | Description |
-|---------------------------|-----------------------------------------------------------------------------|
-| ENABLE_BLOB_PUBLIC_ACCESS | Enables public access for storage account blob (False by default) |
-
-
-## Private Access
-
-Modify the infrastructure and network by enabling Bastion Host with a virtual machine to use for access.
-
-| Feature Flag | Description |
-|---------------------------|-----------------------------------------------------------------------------|
-| ENABLE_MANAGE | Enables a Bastion Host with a virtual machine for private admin access |
-
-
-## Cluster Network
-
-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 |
-
-## Virtual Network Injection
+## Enable Virtual Network Injection
Modify the network configuration for use with a pre-existing virtual network.
diff --git a/docs/src/getting_started.md b/docs/src/getting_started.md
index bf20d66c..935ef7a3 100644
--- a/docs/src/getting_started.md
+++ b/docs/src/getting_started.md
@@ -1,10 +1,67 @@
# Getting Started
-Before starting it is important to ensure the Azure Subscription is properly configured for a personal instance.
+Prerequisites and configuration steps for deploying personal OSDU™ instances in an Azure Subscription.
+
+## Subscription Quota
+
+It is recommended to have at least 50 vCPUs in a region along with the ability to deploy Cosmos DB instances which can be resource constrained in some regions. Defaults for MSDN accounts can be increased by requesting a [quota increase](https://learn.microsoft.com/en-us/azure/quotas/regional-quota-requests).
+
+!!! note "Ensure Sufficient Quota"
+ The choice between BS and DS family vCPUs depends on your specific deployment requirements:
+
+ - Increase DS family vCPU quota if necessary.
+ - Increase BS family vCPU quota if using `ENABLE_BATCH`.
+
+| Quota Name | Minimum Quantity |
+|------------|------------------|
+| Total Regional vCPUs | 100 |
+| Standard BS Family vCPUs | 50 |
+| Standard DS Family vCPUs | 50 |
+
+
+!!! tip "Available Cosmos DB Regions"
+ Use the following command to determine the availability of Cosmos DB regions:
+
+ === "Bash"
+ ```bash
+ az provider show --namespace Microsoft.DocumentDB \
+ --query "resourceTypes[?resourceType=='databaseAccounts'].locations" \
+ --output json
+ ```
+
+ === "PowerShell"
+ ```powershell
+ az provider show --namespace Microsoft.DocumentDB `
+ --query "resourceTypes[?resourceType=='databaseAccounts'].locations" `
+ --output json
+ ```
+
+
+## Estimating Costs
+
+Costs will vary widely based on the selected region, instance size, and usage. The following table provides a rough guideline for an idle instance.
+
+!!! note "Costs Will Vary"
+ Idle instance with no activity consumes approximately __$40.00__ per day.
+
+| Resource | Daily | Resource | Daily |
+|----------|--------------|----------|--------------|
+| Virtual Machines | $14.59 | Load Balancer | $0.60 |
+| Log Analytics | $9.76 | Redis Cache | $0.49 |
+| Storage | $2.75 | Key Vault | $0.09 |
+| Azure Cosmos DB | $2.46 | Virtual Network | $0.08 |
+| Microsoft Defender for Cloud | $1.82 | Container Registry | $0.06 |
+| Container Instances | $0.03 | Bandwidth | $0.004 |
+| Service Bus | $0.001 | | |
+
+
## Resource Providers
-To ensure the successful deployment, the following Azure Resource Providers must be registered in the subscription.
+The following Azure Resource Providers must be registered in your subscription.
+
+!!! tip "Register Resource Providers"
+ For instructions to register providers refer to the [Azure Resource Providers and Types documentation](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-providers-and-types).
| Resource Provider | Description |
|-----------------------------------|-----------------------------------------------------------------------------|
@@ -30,24 +87,41 @@ To ensure the successful deployment, the following Azure Resource Providers must
| Microsoft.ServiceBus | Provides reliable messaging and publish/subscribe capabilities |
| Microsoft.Storage | Manages Azure Storage accounts and resources |
-### Registering Resource Providers
+## Required Role Assignments
+
+To deploy and manage an OSDU™ personal instance, you need the following Azure role assignments:
+
+!!! tip "Assigning Roles"
+ For instructions on assigning roles, refer to the [Azure Role Assignments documentation](https://learn.microsoft.com/en-us/azure/role-based-access-control/role-assignments-steps).
+
+| Role | Purpose |
+|-----------------------------------------|-------------------------------------------------------------------------------------------|
+| Contributor | Manage all resources in the subscription, except for assigning roles or managing policies |
+| Role Based Access Control Administrator | Manage access to Azure resources by assigning roles using Azure RBAC |
+| Resource Policy Contributor | Create and manage resource policies |
+
+## Microsoft Entra App Registration
+
+Register an application in Microsoft Entra ID. This is required for OSDU™ personal instance integration with Microsoft Entra ID and delegate access with identity management.
-To register the necessary resource providers for your subscription, please refer to the [Azure Resource Providers and Types documentation](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-providers-and-types).
+These credentials will be used in your ARM template deployment to authenticate and authorize the deployment process.
-This documentation provides detailed instructions on how to register resource providers using the Azure portal, Azure CLI, and other methods.
+!!! important
+ Only required when using custom ARM template deployments or using CLI feature setting overrides.
-## Role Assignments
+!!! tip "Registering Applications"
+ For instructions on registering applications, refer to the [Quickstart documentation](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app?tabs=certificate).
-The following role assignments are required for users within the subscription to ensure the proper functioning of this solution:
-| Role | Purpose | Role ID |
-|-------------------------------|----------------------------------------------------------------------------------------------------------|--------------------------------------------------|
-| Contributor | Grants full access to manage all resources, but does not allow you to assign roles in Azure RBAC, manage assignments in Azure Blueprints, or share image galleries. | `b24988ac-6180-42a0-ab88-20f7382dd24c` |
-| Role Based Access Control Administrator | Manages access to Azure resources by assigning roles using Azure RBAC. This role does not allow you to manage access using other ways, such as Azure Policy. | `f58310d9-a9f6-439a-9e8d-f62e7b41a168` |
-| Resource Policy Contributor | Users with rights to create/modify resource policies, create support tickets, and read resources/hierarchy. This role is essential for managing resource policies effectively. | `36243c78-bf99-498c-9df9-86d9f8d28608` |
+| Name | Description/Value |
+|------|-------------|
+| Directory (tenant) ID | Unique identifier for the Microsoft Entra tenant |
+| Application (client) ID | Unique identifier for the registered application |
+| Object ID | Unique identifier for the application object in Microsoft Entra |
+| Application (client) Secret | Confidential key used to authenticate the application |
+| Single-page application redirect URI | http://localhost:8080 |
-### Assigning Roles
+!!! warning "Secure Your Secret"
+ The client secret is sensitive information. Make sure to store it securely and never commit it to version control systems.
-To assign roles to users within your Azure subscription, follow the steps outlined in the [Azure Role Assignments documentation](https://learn.microsoft.com/en-us/azure/role-based-access-control/role-assignments-steps).
-This documentation provides you with detailed instructions on how to assign roles using the Azure portal, Azure CLI, and other methods.
\ No newline at end of file
diff --git a/docs/src/images/cost_analysis.png b/docs/src/images/cost_analysis.png
new file mode 100644
index 00000000..c26ab230
Binary files /dev/null and b/docs/src/images/cost_analysis.png differ
diff --git a/docs/src/index.md b/docs/src/index.md
index 63448e5b..46e26c7d 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -1,22 +1,27 @@
# Overview
-OSDU Developer is an open-source solution designed to enable the creation of lightweight, personal instances of [OSDU™](https://osduforum.org/osdu-data-platform-primer-1/) running on the Azure Public Cloud. These personal instances are tailored specifically for developers and work with the [Azure Developer CLI](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/overview). This allows engineers to explore and author applications or work directly on technology prior to transitioning to a fully managed service offering. A simplified one-click deployment capability, with fewer development features, is also available.
+OSDU Developer is an open-source solution designed to enable the creation of lightweight, personal instances of the [Open Subsurface Data Universe (OSDU™)](https://osduforum.org/osdu-data-platform-primer-1/) platform running on the Azure Public Cloud. These personal instances are tailored specifically for engineers and are integrated with the [Azure Developer CLI (AZD)](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/overview) for deployment along with a customized environment setup. The solution allows engineers to explore, integrate services, author applications, or work directly with specific technology prior to the transition to a fully managed service.
+
+An alternate deployment approach uses a simplified [custom ARM template deployment](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FAzure%2Fosdu-developer%2Fmain%2Fazuredeploy.json). This method has a slightly more complicated implmentation of parameters with fewer integrations and automation as compared to the AZD deployment. As a result, it is less suited for a tight development loop but can be affective for quick personal deployments.
!!! Note
- Microsoft recommends using [Azure Data Manager for Energy (ADME)](https://azure.microsoft.com/en-us/products/data-manager-for-energy) for production workloads and integration testing.
+ Microsoft recommends using [Azure Data Manager for Energy (ADME)](https://azure.microsoft.com/en-us/products/data-manager-for-energy) for any production workloads and integration testing.
-The primary goal of this solution is to provide an environment that functions within an inner loop process, delivering faster feedback for developers. This personal environment is user-friendly while maintaining compliance with varying organizational standards. It offers a flexible framework to facilitate deeper exploration of OSDU™ capabilities.
+This solution aims to create an environment for efficient inner loop workflows, enabling rapid feedback for engineers. It balances user-friendliness with organizational compliance, offering a flexible pattern to work with for an in-depth exploration or expansion of OSDU™ capabilities. By providing enhanced transparency into the underlying components, it empowers developers to gain deeper insights and troubleshoot more effectively. Personal OSDU™ instances offer developers a unique advantage in early-stage development and integration, allowing for rapid prototyping and testing of OSDU™ based solutions. This approach aligns with modern software development practices, emphasizing the importance of rapid iteration and testing in application prototyping and cloud integration scenarios.
![[0]][0]
-Deploying personal instances provides valuable insights into early-stage development and integration processes. This approach emphasizes transparency, cost-efficiency, and flexibility, empowering developers to engage in essential application and cloud development scenarios.
+- **Observability**: Direct access to the underlying infrastructure and components
+- **Faster feedback**: Accelerated development loops with established patterns for service development and rapid iteration
+- **Compliant**: Ability to align with specific organizational standards and security requirements
+- **Flexible**: Customized environments to suit diverse project needs
-??? Tip "Learning Opportunities"
+??? Tip "Learning Opportunity"
Learn more about how inner and outer loop concepts can enhance developer productivity by viewing a discussion with Scott Hanselman, VP of Developer Community at Microsoft, on the Planet Argon Podcast: [The Fear Factor in Maintainable Software](https://www.youtube.com/watch?v=V5OhIjn7pJo).
## Personas
-The Open Subsurface Data Universe (OSDU) platform is utilized by a variety of personas within the energy industry.
+The OSDU™ platform serves a diverse range of professionals within the energy industry. Each persona may interacts with personal instances in different and unique ways, leveraging different capabilities and features to meet specific needs or challenges.
@@ -24,56 +29,50 @@ The Open Subsurface Data Universe (OSDU) platform is utilized by a variety of pe
---
- Build applications leveraging OSDU APIs to manage subsurface data efficiently.
-
+ Build applications leveraging APIs with the need to debug and interact efficiently.
-- :fontawesome-solid-database:{ .lg .middle } __Data Engineers__
+- :fontawesome-solid-chart-line:{ .lg .middle } __Data Scientists__
---
- Ensure proper data ingestion, transformation, and accessibility within the OSDU ecosystem.
-
+ Analyze data or explore integration options to derive insights using machine learning and statistical methods.
-- :fontawesome-solid-chart-line:{ .lg .middle } __Data Scientists__
+- :fontawesome-solid-cloud:{ .lg .middle } __Cloud Architects__
---
- Analyze large volumes of subsurface data to derive insights using machine learning and statistical methods.
-
+ Explore alternate designs and implementations for the platform and integrate it with additional cloud services or AI services.
-- :fontawesome-solid-cloud:{ .lg .middle } __Cloud Architects__
+- :fontawesome-solid-database:{ .lg .middle } __Data Engineers__
---
- Design scalable, secure infrastructure to support the OSDU platform and integrate it with cloud services.
-
+ Ensure proper data preparation and ingestion within the ecosystem to derive patterns for larger production datasets.
-- :fontawesome-solid-user-tie:{ .lg .middle } __Domain Experts__
+- :fontawesome-brands-git-alt:{ .lg .middle } __DevOps Engineers__
---
- Utilize their specialized knowledge to develop domain-specific applications and services on the OSDU platform.
+ Streamline the deployment, monitoring, and maintenance of the platform and applications, ensuring efficient development and operations.
-- :fontawesome-brands-git-alt:{ .lg .middle } __DevOps Engineers__
+- :fontawesome-solid-user-tie:{ .lg .middle } __Domain Experts__
---
- Streamline the deployment, monitoring, and maintenance of OSDU platform applications, ensuring efficient development and operations.
+ Utilize their specialized knowledge to develop domain-specific applications or services within the platform.
-- **DevOps Engineers**: Focus on the deployment, monitoring, and maintenance of applications on the OSDU platform, ensuring streamlined and efficient development and operational processes.
-
## Benefits
-:material-eye-outline: **Observability:** Interact directly with resources and software components within the solution to enhance observability through logs, dashboards, and source code debugging.
+:material-eye-outline: **Transparent:** Interact directly with resources and software components within the solution to enhance observability through logs, dashboards, and source code debugging.
-:material-cash: **Affordability:** Deploy with minimal resource consumption by omitting costly features like disaster recovery and backups, minimizing operational costs.
+:material-cash: **Affordable:** Deploy with minimal resource consumption by omitting costly features like disaster recovery and backups, minimizing operational costs.
-:material-swap-horizontal-bold: **Flexibility:** The solution provides adaptable infrastructure to meet various organizational needs, including:
+:material-swap-horizontal-bold: **Configurable:** The solution provides adaptable infrastructure to meet various organizational needs, including:
=== "Virtual Network Injection"
@@ -90,30 +89,37 @@ The Open Subsurface Data Universe (OSDU) platform is utilized by a variety of pe
## Scenarios
-Several different scenarios illustrate the practical applications of this approach:
+OSDU™ private instances are designed to support a wide range of use cases, catering to various needs within a software development lifecycle. By providing a flexible and customizable environment, it enables developers, engineers, and other professionals to explore and leverage the OSDU™ platform in multiple ways. Here are several key scenarios that illustrate the practical applications of this approach:
-:material-cog: __Service Development__
+
-Create, update, debug, and work directly with OSDU services.
+- :material-cog:{ .lg .middle } __Service Development__
+ ---
-:fontawesome-solid-laptop-code: __Application Development__
+ Build, test, debug, and work directly with OSDU™ services and experimental features.
-Streamlined development for applications before integration with a managed service offering.
+- :fontawesome-solid-laptop-code:{ .lg .middle } __Application Development__
+ ---
-:fontawesome-solid-lightbulb: __Technology Innovation__
+ Streamlined development for applications before integration with a managed service offering.
-Fork and extend projects to explore deeper integration with various technologies such as Azure Fabric, Co-Pilot, and Power Platform.
+- :fontawesome-solid-lightbulb:{ .lg .middle } __Technology Innovation__
+ ---
-:material-school: __Training and Onboarding__
+ Fork and extend projects to explore deeper integration with various technologies such as Fabric, Co-Pilot, and the Power Platform.
-Train new employees on the OSDU™ platform, offering hands-on experience in a controlled environment.
+- :material-school:{ .lg .middle } __Training and Onboarding__
+ ---
+ Train new employees on the OSDU™ platform, offering hands-on experience in a controlled environment.
+
+
-## Features
+## Feature List
| **Feature** | **Description** |
|------------------------|--------------------------------------------------------------------------------------------------------------------|