First run at creating documentation pattern. (#163)

Azure · Aug 22, 2024 · 78fb1f8 · 78fb1f8
1 parent 9501eb5
commit 78fb1f8
Show file tree

Hide file tree

Showing 6 changed files with 304 additions and 0 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,65 @@
+# Documentation
+
+Documentation is written in Markdown from the `docs` folder. The
+`src` folder contains the sources with the `.md` extension.
+
+We have adopted [MkDocs](https://www.mkdocs.org/) as an open source solution to
+build the documentation starting from Markdown format.
+
+Before you submit a pull request for the documentation, you must have gone through the following steps:
+
+1. local test of the documentation
+2. run through the spell checker
+
+## How to locally test the documentation
+
+You can locally test the documentation in two ways:
+
+- using Docker
+- using `mkdocs` directly
+
+In both cases, you should issue the commands inside the `docs` folder.
+
+With Docker, you just need to execute the following command and point your
+browser to `http://127.0.0.1:8000/`:
+
+``` bash
+docker run --rm -v "$(pwd):$(pwd)" -w "$(pwd)" -p 8000:8000 \
+    minidocks/mkdocs \
+    mkdocs serve -a 0.0.0.0:8000
+```
+
+If you have installed `mkdocs` directly in your workstation, you can simply run:
+
+``` bash
+mkdocs serve
+```
+
+Even in this case, point your browser to `http://127.0.0.1:8000/`.
+
+Make sure you review what you have written by putting yourself in the end
+user's shoes. Once you are ready, proceed with the spell check and then with
+the pull request.
+
+## How to run the spell checker
+
+Every time you work on the documentation, please run from the top directory:
+
+``` bash
+make spellcheck
+```
+
+This will run a spell checker and highlight all the words that need to be
+either fixed or added to the `.wordlist-en-custom.txt` file.
+
+## How to build the documentation in HTML
+
+From the `docs` folder, run the following command to build the documentation
+and place it in the `dist` directory:
+
+``` bash
+docker run --rm -v "$(pwd):$(pwd)" -w "$(pwd)" \
+    minidocks/mkdocs \
+    sh -c "pip install mkdocs-mermaid2-plugin && mkdocs build -v -d dist"
+```
+
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -0,0 +1,22 @@
+site_name: OSDU Developer
+site_author: Microsoft Azure Energy
+docs_dir: src
+
+theme: readthedocs
+
+extra_css:
+  - css/override.css
+
+markdown_extensions:
+  - admonition
+  - def_list
+  - attr_list
+
+plugins:
+  - search
+  - mermaid2
+
+nav:
+  - index.md
+  - before_you_start.md
+  - architecture.md
diff --git a/docs/src/architecture.md b/docs/src/architecture.md
@@ -0,0 +1,106 @@
+# Architecture
+
+!!! Hint
+    The developer sandbox is built using the following principles from the Azure Well-Architeced Framework.
+    For a deeper understanding, we recommend reading our article on the Micosoft Learn
+    [Azure Well-Architected Framework](https://learn.microsoft.com/en-us/azure/well-architected/),
+    which provides valuable insights into best practices and design
+    considerations for azure workloads.
+
+
+**Cost Optimization** - Creating a cost-effective solution while balancing security.
+
+**Security** - Enhancing security within a development context, adhering to a zero trust model.
+
+**Operational Excellence** - Prioritizing DevOps standards with automation to ensure efficient operations and robust monitoring.
+
+#### Desired State Configuration
+
+Bicep is a domain-specific language (DSL) for deploying Azure resources declaratively. It simplifies authoring ARM templates and allows you to define the desired state of your Azure infrastructure in code. Azure Resource Manager (ARM) processes the Bicep file to ensure the Azure environment matches the defined desired state, correcting any drift through redeployment.
+
+!!! Note
+    Microsoft recommends when developing with Bicep to use the official [Azure Verified Modules](https://azure.github.io/Azure-Verified-Modules/).
+
+
+#### Desired State Management
+
+GitOps uses Git as a single source of truth for declarative components and applications. It ensures that the actual state of the components or application matches the desired state defined in the Git repository, automating updates through continuous monitoring and Git commits.
+
+
+# Sequence Diagram
+
+This diagram documents how the interactions work for the Azure CLI Developer Command Structures
+
+<!--- https://diagrams.helpful.dev/ --->
+
+```mermaid
+sequenceDiagram
+    participant Azd as user
+    participant Provision as command
+    participant Azure as azure
+
+
+    rect rgb(191, 223, 255)
+    alt
+    Note over Provision: featureCheck
+    Note over Provision: credCheck
+    end
+    Azd->>+Provision: azd provision
+    Provision->>Azure: arm deploy
+    Provision-->>-Azd: complete
+    alt
+    Note over Provision: softwareCheck
+    Note over Provision: entraAuth
+    end
+    end
+
+    rect rgb(144,238,144)
+    alt
+    Note over Provision: firstUser
+    Note over Provision: refreshToken
+    end
+    Azd->>Provision: azd deploy
+    activate Provision
+    Provision-->>Azd: complete
+    deactivate Provision
+    alt
+    Note over Provision: settingsJson
+    end
+    end
+```
+
+# Infrastructure
+
+The architecture diagram below provides a visual representation of the infrastructure when deployed. It's designed to help you understand the various components and how they interact within the Azure environment.
+
+![[0]][0]
+
+## Key Components Illustrated in the Diagram:
+
+1. Azure Virtual Network: Illustrates the default network design.
+2. Kubernetes Node Pools: Illustrate the design of the cluster nodepools.
+3. Storage Resources: Illustrates how Storage Accounts and Cosmos Databases are connected to the network.
+4. Ingress Load Balancers: Illustrates how the Load Balancers created by Istio Gateways are to the network.
+
+## Software Management with a Gitops Approach
+
+In this workspace, we utilize a GitOps approach for efficient and reliable software management. This method leverages this Git repository as the source of truth for defining and updating the software configurations and deployments within the infrastructure.
+
+### GitOps Configuration
+
+Our GitOps configuration resides in this Git repository and uses a customized [repo-per-team](https://fluxcd.io/flux/guides/repository-structure/#repo-per-team) pattern. This repository includes:
+
+- **Configuration Files**: YAML files defining the desired state of our components and applications.
+
+- **Charts**: Helm charts used for defining, installing, and upgrading Kubernetes applications.
+
+### Advantages of GitOps
+
+- **Consistency and Standardization**: Ensures consistent configurations across different environments.
+- **Audit Trails**: Every change is recorded in Git, providing a clear audit trail.
+- **Rollbacks and Recovery**: Every change is recorded in Git, providing a clear audit trail.
+- **Enhanced Security**: Changes are reviewed through pull requests, increasing security and collaboration.
+
+Our GitOps approach simplifies the process of deploying and managing software, making it easier to maintain and update, as well as providing a configurable way of leveraging other software configurations by pointing to alternate repositories hosting other configurations. By leveraging this method, we ensure that our deployments can be extended to things that not only include the default software load.
+
+[0]: images/architecture.png "Architecture Diagram"
diff --git a/docs/src/before_you_start.md b/docs/src/before_you_start.md
@@ -0,0 +1,53 @@
+# Before you start
+
+Before starting it is important to ensure the Azure Subscription is properly configured for the solution to deploy.
+
+## Required Resource Providers
+
+To ensure the successful deployment of this solution, the following Azure Resource Providers must be registered in your subscription.
+
+| Resource Provider                 | Description                                                                 |
+|-----------------------------------|-----------------------------------------------------------------------------|
+| Microsoft.AlertsManagement        | Manages alerts and notifications for Azure resources                        |
+| Microsoft.AppConfiguration        | Manages application settings and feature flags                              |
+| Microsoft.Authorization           | Manages access control and permissions for Azure resources                  |
+| Microsoft.Cache                   | Manages Azure Cache for Redis instances                                     |
+| Microsoft.CloudShell              | Provides an interactive command-line shell experience in the Azure portal   |
+| Microsoft.Compute                 | Manages virtual machines, virtual machine scale sets, and related resources |
+| Microsoft.ContainerRegistry       | Manages container registries for storing and managing container images      |
+| Microsoft.ContainerService        | Manages Kubernetes clusters and related resources                           |
+| Microsoft.Dashboard               | Creates and manages dashboards for visualizing Azure resources              |
+| Microsoft.DocumentDB              | Manages Azure Cosmos DB databases and collections                           |
+| Microsoft.Insights                | Provides monitoring and diagnostics for Azure resources                     |
+| Microsoft.KeyVault                | Safeguards and manages cryptographic keys and secrets                       |
+| Microsoft.KubernetesConfiguration | Manages Azure Kubernetes Service (AKS) clusters and related resources       |
+| Microsoft.ManagedIdentity         | Provides an identity for Azure resources without the need for credentials   |
+| Microsoft.Monitor                 | Provides monitoring and alerting capabilities for Azure resources           |
+| Microsoft.Network                 | Manages virtual networks, network security groups, and related resources    |
+| Microsoft.OperationalInsights     | Provides log analytics and monitoring for Azure resources                   |
+| Microsoft.OperationsManagement    | Manages and monitors the health and performance of Azure resources          |
+| Microsoft.Resources               | Manages Azure Resource Manager resources and resource groups                |
+| Microsoft.ServiceBus              | Provides reliable messaging and publish/subscribe capabilities              |
+| Microsoft.Storage                 | Manages Azure Storage accounts and resources                                |
+
+### Registering Resource Providers
+
+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).
+
+This documentation provides detailed instructions on how to register resource providers using the Azure portal, Azure CLI, and other methods.
+
+## Role Assignments
+
+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`           |
+
+### Assigning Roles
+
+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.
diff --git a/docs/src/images/architecture.png b/docs/src/images/architecture.png
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -0,0 +1,58 @@
+# OSDU Personal Instances
+
+OSDU Developer is an open-source solution to enable easy creation of Personal Instances of OSDU running in the Azure Public Cloud.
+
+## What is it?
+
+This Azure Developer CLI (AZD) integrated solution, along with a one-click deployment option, allows engineers to explore authoring applications or work directly on individual or custom OSDU services prior to transitioning to a fully managed service offering like ADME.
+
+The primary objective is to offer an environment for use as an inner loop development cycle within an organization’s own cloud tenant while working and exploring with the open-source codebase. This engineering environment is easy to work with and strives to ensure compliance through a flexible infrastructure framework, providing a path to explore the depth of OSDU.
+
+Deploying a personal instance of the OSDU open-source solution on Azure Cloud delivers practical insights into early development and integration processes. It ensures transparency, cost-efficiency, and flexibility, while enabling essential application and cloud developer scenarios.
+
+### Key Benefits
+
+- **Observability and Transparency:**  Direct interaction with the resources, software, and components of the solution facilitates enhanced observability through logs, dashboards, and source code debugging, providing transparency crucial for developers.
+
+- **Cost Efficiency:**  By deploying with minimal resources, cluster compute, and omitting costly features like disaster recovery (DR) and backup, consumption costs are minimized.
+
+- **Flexibility:**  Supports scenarios such as:
+
+- **Virtual Network Injection:** Allows for flexible network designs with site-to-site VPN connections and integration with preexisting networks.
+
+- **Controlled Access:** Supports both public and private ingress along with the ability to layer your own routing solutions for ingress, such as Azure Firewall and Azure Front Door.
+
+- **Software Isolation**:** Override and isolate the defined software customizations while extending into additional custom software configurations.
+
+### Scenarios
+
+Several scenarios illustrate the practical applications of this approach, such as:
+
+- **Service Development:** Enables engineers to create, update, debug, and work with integrated OSDU services.
+Application Development: Allows for easy developer integration with applications being developed for initial testing prior to integration with a managed service offering.
+
+- **Innovate with Azure-Specific Technologies:**  Fork and extend the solution to explore deeper integration with Azure-specific tools and technologies such as Azure Fabric, Co-Pilot, and Power Platform, impacting various Azure integration points.
+
+- **Training and Onboarding:**  Provides a valuable opportunity for training new employees on Azure within the OSDU framework, offering hands-on experience in a controlled environment.
+
+
+## Main features
+
+ | **Feature**            | **Description**                                                                                                    |
+|------------------------|--------------------------------------------------------------------------------------------------------------------|
+| Data Partitions        | Supports a single data partition for managing and organizing data within the platform, named "opendes."            |
+| Schema Loading         | Automatically loads Well Known Schemas for efficient data management and validation.                               |
+| Software Locations     | Utilizes Flux to direct the software loading process to private GitHub repositories and branches.                  |
+| Ingress                | Supports both public-facing and private network access points.                                                     |
+| Network flexibility    | Supports VNet injection and integration with existing networks, to easily allow for S2S Vpn access.                |
+| Mesh Observability     | Provides observability for istio using Kiali dashboards to investigate latency, traffic, errors, and saturation.   |
+| Elastic Tools          | Supports connectivity to Elastic Kibana for advanced devtools, search capabilities, and user management.           |
+| Application Logging    | Integrated with Application Insights for detailed service-level logging and metrics monitoring.                    |
+| Initial User           | Includes initial user setup and configuration for openid connect access.                                           |
+| Rest Scripts           | Integrated Sample Rest Scripts for easily executing API calls to test and explore functionality.                   |
+| Token Tools            | Integrated Access Token Tools for easy retrieval of Bearer Access Tokens for with Swagger Pages and docs.          |
+
+## About this guide
+
+Follow the instructions in the "Quickstart" to quickly bring online a personal instance of OSDU.
+