Skip to content

Commit

Permalink
Documentation work. (#219)
Browse files Browse the repository at this point in the history
  • Loading branch information
@danielscholl
danielscholl authored Oct 8, 2024
1 parent d865156 commit f2af465
Show file tree
Hide file tree
Showing 5 changed files with 267 additions and 114 deletions.
122 changes: 95 additions & 27 deletions docs/src/design_architecture.md
View file
Original file line number Diff line number Diff line change
@@ -1,18 +1,20 @@
# Architecture

!!! Hint
OSDU Developer is built using the following principles from the Azure Well-Architeced Framework.
For a deeper understanding, we recommend reading our article on Micosoft Learn
Personal OSDU™ instances are built using principles from the Azure Well-Architected Framework which provide a set of best practices and design considerations for azure workloads.

??? Tip "Learning Opportunity"

For a deeper understanding read about the
[Azure Well-Architected Framework](https://learn.microsoft.com/en-us/azure/well-architected/).
This provides valuable insights into best practices and design
considerations of azure workloads.


#### IaC: Declarative Resource Definition

Infrastructure as Code (IaC) uses declarative definitions to specify the desired state of cloud resources. Bicep is a domain-specific language (DSL) used for deploying Azure resources declaratively. It simplifies authoring ARM templates and allows you to define the desired state of your Infrastructure as Code (IaC). 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 official [Azure Verified Modules](https://azure.github.io/Azure-Verified-Modules/).
??? Tip "Learning Opportunity"

Understand Bicep development with the official [Azure Verified Modules](https://azure.github.io/Azure-Verified-Modules/).


#### GitOps: Declarative Configuration Management
Expand All @@ -21,8 +23,14 @@ Infrastructure as Code (IaC) uses declarative definitions to specify the desired

GitOps uses versioned CI/CD on top of a declarative infrastructure, allowing developers to "[stop scripting and start shipping](https://twitter.com/kelseyhightower/status/953638870888849408)," as Kelsey Hightower put it. This declarative configuration is helpful to define the entire softwarestack as code and continuously deliver changes with confidence to environments.

??? Tip "Learning Opportunity"

Dive Deeper into [GitOps for Azure Kubernetes Service](https://learn.microsoft.com/en-us/azure/architecture/example-scenario/gitops-aks/gitops-blueprint-aks).

## Command Sequence

## CLI Command Sequencing

The Azure Developer CLI (azd) provides a set of commands to provision and deploy resources to Azure. These commands offer the ability to include hooks to inject custom logic into the deployment process. This custom logic is written with powershell scripts to ensure cross-platform compatability.

This sequence diagram illustrates the interactions within the Azure CLI developer command structures.

Expand Down Expand Up @@ -64,41 +72,101 @@ sequenceDiagram
end
```

## Infrastructure
## Azure Infrastructure Diagram

This diagram provides a visual representation of the infrastructure as deployed. It is intended to help illustrate the various components and interactions within Azure.
This diagram provides a broad visual representation of the infrastructure as deployed. It is intended to help illustrate the various components and interactions within Azure.

![[0]][0]

### Components
### Resource Catagories

<div class="grid cards" markdown>

- :material-lan:{ .lg .middle } __Azure Virtual Network__

---

Illustrate the default network design.

- :material-kubernetes:{ .lg .middle } __Kubernetes Node Pools__

---

1. Azure Virtual Network - Illustrate the default network design.
2. Kubernetes Node Pools - Illustrate the design for the cluster nodepools.
3. Storage Resources - Illustrate how Storage Accounts and Cosmos Databases connect to the network.
4. Ingress Load Balancers - Illustrate how the Load Balancers created by Istio Gateways are available in the network.
Illustrate the design for the cluster nodepools.

- :material-database:{ .lg .middle } __Storage Resources__

---

Illustrate how Storage Accounts and Cosmos Databases connect to the network.

- :material-server-network:{ .lg .middle } __Ingress Load Balancers__

---

Illustrate how the Load Balancers created by Istio Gateways are available in the network.

</div>

## Software

In this workspace, we utilize a GitOps approach for efficient and reliable software management. This method leverages a Git repository as the source of truth for defining and updating the software configurations and deployments within the infrastructure.
This workspace utilizes a GitOps approach for efficient and reliable software management. This method leverages a Git repository as the source of truth for defining and updating software configurations and deployments within the infrastructure.

### GitOps Configuration

A 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:
A GitOps configuration resides in this Git repository and uses a gitops repository pattern. This repository includes:

- **Configuration Files**: YAML files defining the desired state of our components and applications.
<div class="grid cards" markdown>

- **Charts**: Helm charts used for defining, installing, and upgrading Kubernetes applications.
- :material-file-cog:{ .lg .middle } __Configuration Files__

### GitOps Advantages
---

YAML files defining the desired state of our components and applications.

- :material-package-variant-closed:{ .lg .middle } __Charts__

- **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.
---

Helm charts used for defining, installing, and upgrading Kubernetes applications.

</div>

??? Tip "Learning Opportunity"

Understand more about the [repo-per-team](https://fluxcd.io/flux/guides/repository-structure/#repo-per-team) pattern.

### GitOps Advantages

A 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.

![[1]][1]
<div class="grid cards" markdown>

- :material-sync:{ .lg .middle } __Consistency and Standardization__

---

Ensures consistent configurations across different environments.

- :material-history:{ .lg .middle } __Audit Trails__

---

Every change is recorded in Git, providing a clear audit trail.

- :material-backup-restore:{ .lg .middle } __Rollbacks and Recovery__

---

Easily revert to previous states if issues arise, enhancing system reliability.

- :material-shield-check:{ .lg .middle } __Enhanced Security__

---

Changes are reviewed through pull requests, increasing security and collaboration.

</div>


[0]: images/architecture.png "Architecture Diagram"
[1]: images/architecture_2.png "Gitops Diagram"
[0]: images/architecture.png "Architecture Diagram"
77 changes: 41 additions & 36 deletions docs/src/feature_flags.md
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,38 @@
# Feature Flags

Feature flags can be set prior to running provision with the command `azd env set <FLAG> <VALUE>`
Feature flags are configuration settings used to modify the default behavior of an OSDU™ personal instance.

## Reusable Entra App
<div class="grid cards" markdown>

Entra App configurations are by default automatically created but one can be reused or created manually as well.
- :material-toggle-switch-outline: __Toggle__ alternate functionality
- :material-cloud-outline: __Deploy__ alternate infrastructure
- :material-cog-outline: __Override__ default settings
- :material-wrench-outline: __Configure__ custom software

</div>


!!! warning "CLI Deployment Only"
Feature flags are implemented as named environment variables which correspond to ARM template parameter objects.

!!! tip "Setting Feature Flags"
Set feature flags prior to provisioning.
```bash
azd env set <FLAG> <VALUE>
```

## 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 |
|---------------------------|-----------------------------------------------------------------------------|
Expand All @@ -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 |
|---------------------------|-----------------------------------------------------------------------------|
Expand All @@ -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.

Expand Down
Loading

0 comments on commit f2af465

Please sign in to comment.