Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation: Known issues #757

Merged
merged 5 commits into from
Apr 10, 2024
Merged

Documentation: Known issues #757

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
a5df6bb
Added known issues wiki
oZakari Apr 10, 2024
825c82e
Update wording for known issues
oZakari Apr 10, 2024
5cb41dc
Merge branch 'main' into known-issues
oZakari Apr 10, 2024
5ce6056
Fix lint errors
oZakari Apr 10, 2024
5fd5ca3
Merge branch 'known-issues' of https://github.com/oZakari/ALZ-Bicep i…
oZakari Apr 10, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
103 changes: 53 additions & 50 deletions docs/wiki/Home.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
<!-- markdownlint-disable -->

## Azure Landing Zones Bicep Repo - Wiki

<!-- markdownlint-restore -->

![Bicep Logo](media/bicep-logo.png)
Expand All @@ -12,30 +14,33 @@ Artefacts like policies etc. are pulled down from the [`Azure/Enterprise-Scale`

## Navigation

* [Wiki Home][wiki_home]
* [Deployment Flow][wiki_deployment_flow]
* [Network Topology: Hub and Spoke][wiki_deployment_flow_hs]
* [Network Topology: Virtual WAN][wiki_deployment_flow_vwan]
* [Zero Trust Networking Guide: Hub and Spoke][wiki_zt_networking]
* [Consumer Guide][wiki_consumer_guide]
* [Accelerator][accelerator]
* [How Does ALZ-Bicep Implement Azure Policies?][wiki_policy_deep_dive]
* [Adding Custom Azure Policy Definitions][wiki_policy_defs]
* [Assigning Azure Policies][wiki_policy_assignments]
* [How Does ALZ-Bicep Implement resilient deployments across availability zones?][wiki_resiliency]
* [Contributing][wiki_contributing]
* [Telemetry Tracking Using Customer Usage Attribution (PID)][wiki_cuaid]
* [Azure Container Registry Deployment - Private Bicep Registry][wiki_acrdeploy]
* [Frequently Asked Questions][wiki_faq]
* [Sample Pipelines][wiki_pipelines]
* [GitHub Actions][wiki_pipelines_gh]
* [Azure DevOps][wiki_pipelines_ado]
* [Code Tours][code_tours]
- [Wiki Home][wiki_home]
- [Deployment Flow][wiki_deployment_flow]
- [Network Topology: Hub and Spoke][wiki_deployment_flow_hs]
- [Network Topology: Virtual WAN][wiki_deployment_flow_vwan]
- [Zero Trust Networking Guide: Hub and Spoke][wiki_zt_networking]
- [Consumer Guide][wiki_consumer_guide]
- [Accelerator][accelerator]
- [Known Issues][wiki_known_issues]
- [Frequently Asked Questions][wiki_faq]
- [How Does ALZ-Bicep Implement Azure Policies?][wiki_policy_deep_dive]
- [Adding Custom Azure Policy Definitions][wiki_policy_defs]
- [Assigning Azure Policies][wiki_policy_assignments]
- [How Does ALZ-Bicep Implement resilient deployments across availability zones?][wiki_resiliency]
- [Contributing][wiki_contributing]
- [Telemetry Tracking Using Customer Usage Attribution (PID)][wiki_cuaid]
- [Azure Container Registry Deployment - Private Bicep Registry][wiki_acrdeploy]
- [Sample Pipelines][wiki_pipelines]
- [GitHub Actions][wiki_pipelines_gh]
- [Azure DevOps][wiki_pipelines_ado]
- [Code Tours][code_tours]

## Azure Enablement Show Videos

We have created a short 3-part series of video on the Azure Enablement Show that can be found below:

<!-- markdownlint-disable -->

### Part 1 - Introduction to Azure Landing Zones Bicep

[![Part 1 - Introduction to Azure Landing Zones Bicep](https://img.youtube.com/vi/-pZNrH1GOxs/hqdefault.jpg)](https://aka.ms/azenable/94)
Expand All @@ -47,42 +52,40 @@ We have created a short 3-part series of video on the Azure Enablement Show that
### Part 3 - Azure Landing Zones Bicep - Enabling landing zones

[![Part 3 - Azure Landing Zones Bicep - Enabling landing zones](https://img.youtube.com/vi/cZ7IN3zGbyM/hqdefault.jpg)](https://aka.ms/azenable/96)
<!-- markdownlint-restore -->




<!-- markdownlint-restore -->

[//]: # (************************)
[//]: # (INSERT LINK LABELS BELOW)
[//]: # (************************)
[//]: # "************************"
[//]: # "INSERT LINK LABELS BELOW"
[//]: # "************************"

<!--
The following link references should be copied from `_sidebar.md` in the `./docs/wiki/` folder.
Replace `./` with `https://github.com/Azure/ALZ-Bicep/wiki/` when copying to here.
-->

[wiki_home]: https://github.com/Azure/ALZ-Bicep/wiki/home "Wiki - Home"
[wiki_deployment_flow]: https://github.com/Azure/ALZ-Bicep/wiki/DeploymentFlow "Wiki - Deployment Flow"
[wiki_deployment_flow_hs]: https://github.com/Azure/ALZ-Bicep/wiki/DeploymentFlowHS "Wiki - Deployment Flow - Hub and Spoke"
[wiki_deployment_flow_vwan]: https://github.com/Azure/ALZ-Bicep/wiki/DeploymentFlowVWAN "Wiki - Deployment Flow - Virtual WAN"
[wiki_consumer_guide]: https://github.com/Azure/ALZ-Bicep/wiki/ConsumerGuide "Wiki - Consumer Guide"
[wiki_accelerator]: https://github.com/Azure/ALZ-Bicep/wiki/Accelerator "Wiki - Consumer Guide - Accelerator"
[wiki_policy_deep_dive]: https://github.com/Azure/ALZ-Bicep/wiki/PolicyDeepDive "Wiki - Policy Deep Dive"
[wiki_policy_defs]: https://github.com/Azure/ALZ-Bicep/wiki/AddingPolicyDefs "Wiki - Policy Definitions"
[wiki_policy_assignments]: https://github.com/Azure/ALZ-Bicep/wiki/AssigningPolicies "Wiki - Policy Assignments"
[wiki_resiliency]: https://github.com/Azure/ALZ-Bicep/wiki/Resiliency "Wiki - Resiliency"
[wiki_contributing]: https://github.com/Azure/ALZ-Bicep/wiki/Contributing "Wiki - Contributing"
[wiki_acrdeploy]: https://github.com/Azure/ALZ-Bicep/wiki/ACRDeployment "Wiki - Private Bicep Registry"
[wiki_cuaid]: https://github.com/Azure/ALZ-Bicep/wiki/CustomerUsage "Wiki - Telemetry Usage ID"
[wiki_faq]: https://github.com/Azure/ALZ-Bicep/wiki/FAQ "Wiki - FAQs"
[wiki_pipelines]: https://github.com/Azure/ALZ-Bicep/wiki/PipelinesOverview "Wiki - Sample Pipelines"
[wiki_pipelines_gh]: https://github.com/Azure/ALZ-Bicep/wiki/PipelinesGitHub "Wiki - Sample Pipelines - GitHub Actions"
[wiki_pipelines_ado]: https://github.com/Azure/ALZ-Bicep/wiki/PipelinesADO "Wiki - Sample Pipelines - Azure DevOps"
[code_tours]: https://github.com/Azure/ALZ-Bicep/wiki/CodeTour "Wiki - Code tours"
[aes_part_1]: https://aka.ms/azenable/94 "Part 1 - Introduction to Azure Landing Zones Bicep"
[aes_part_2]: https://aka.ms/azenable/95 "Part 2 - Enabling platform services"
[aes_part_3]: https://aka.ms/azenable/96 "Part 3 - Enabling landing zones"
[aac_article]: https://learn.microsoft.com/azure/architecture/landing-zones/bicep/landing-zone-bicep "Azure Architecture Center - Azure landing zones - Bicep modules design considerations"
[accelerator]: https://github.com/Azure/ALZ-Bicep/wiki/Accelerator "Accelerator"
[wiki_zt_networking]: https://github.com/Azure/ALZ-Bicep/wiki/DeploymentGuideHSZT "Zero Trust Networking Guide: Hub and Spoke"
[wiki_home]: https://github.com/Azure/ALZ-Bicep/wiki/home "Wiki - Home"
[wiki_deployment_flow]: https://github.com/Azure/ALZ-Bicep/wiki/DeploymentFlow "Wiki - Deployment Flow"
[wiki_deployment_flow_hs]: https://github.com/Azure/ALZ-Bicep/wiki/DeploymentFlowHS "Wiki - Deployment Flow - Hub and Spoke"
[wiki_deployment_flow_vwan]: https://github.com/Azure/ALZ-Bicep/wiki/DeploymentFlowVWAN "Wiki - Deployment Flow - Virtual WAN"
[wiki_consumer_guide]: https://github.com/Azure/ALZ-Bicep/wiki/ConsumerGuide "Wiki - Consumer Guide"
[wiki_accelerator]: https://github.com/Azure/ALZ-Bicep/wiki/Accelerator "Wiki - Consumer Guide - Accelerator"
[wiki_known_issues]: https://github.com/Azure/ALZ-Bicep/wiki/KnownIssues "Wiki - Known Issues"
[wiki_faq]: https://github.com/Azure/ALZ-Bicep/wiki/FAQ "Wiki - FAQs"
[wiki_policy_deep_dive]: https://github.com/Azure/ALZ-Bicep/wiki/PolicyDeepDive "Wiki - Policy Deep Dive"
[wiki_policy_defs]: https://github.com/Azure/ALZ-Bicep/wiki/AddingPolicyDefs "Wiki - Policy Definitions"
[wiki_policy_assignments]: https://github.com/Azure/ALZ-Bicep/wiki/AssigningPolicies "Wiki - Policy Assignments"
[wiki_resiliency]: https://github.com/Azure/ALZ-Bicep/wiki/Resiliency "Wiki - Resiliency"
[wiki_contributing]: https://github.com/Azure/ALZ-Bicep/wiki/Contributing "Wiki - Contributing"
[wiki_acrdeploy]: https://github.com/Azure/ALZ-Bicep/wiki/ACRDeployment "Wiki - Private Bicep Registry"
[wiki_cuaid]: https://github.com/Azure/ALZ-Bicep/wiki/CustomerUsage "Wiki - Telemetry Usage ID"
[wiki_pipelines]: https://github.com/Azure/ALZ-Bicep/wiki/PipelinesOverview "Wiki - Sample Pipelines"
[wiki_pipelines_gh]: https://github.com/Azure/ALZ-Bicep/wiki/PipelinesGitHub "Wiki - Sample Pipelines - GitHub Actions"
[wiki_pipelines_ado]: https://github.com/Azure/ALZ-Bicep/wiki/PipelinesADO "Wiki - Sample Pipelines - Azure DevOps"
[code_tours]: https://github.com/Azure/ALZ-Bicep/wiki/CodeTour "Wiki - Code tours"
[aes_part_1]: https://aka.ms/azenable/94 "Part 1 - Introduction to Azure Landing Zones Bicep"
[aes_part_2]: https://aka.ms/azenable/95 "Part 2 - Enabling platform services"
[aes_part_3]: https://aka.ms/azenable/96 "Part 3 - Enabling landing zones"
[aac_article]: https://learn.microsoft.com/azure/architecture/landing-zones/bicep/landing-zone-bicep "Azure Architecture Center - Azure landing zones - Bicep modules design considerations"
[accelerator]: https://github.com/Azure/ALZ-Bicep/wiki/Accelerator "Accelerator"
[wiki_zt_networking]: https://github.com/Azure/ALZ-Bicep/wiki/DeploymentGuideHSZT "Zero Trust Networking Guide: Hub and Spoke"
43 changes: 43 additions & 0 deletions docs/wiki/KnownIssues.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
<!-- markdownlint-disable -->
## Known Issues
<!-- markdownlint-restore -->

This page lists the known issues and limitations currently present in ALZ-Bicep. Please review these before using the repository to understand any potential challenges or constraints.

## Issue 1: What-If Check Fails within Azure DevOps Pipeline/GitHub Actions Workflow with the error: `Additional content found in JSON reference object. A JSON reference object should only have a $ref property. Path 'parResourceLockConfig.defaultValue'`

- **Description:** There is a bug with the Azure PowerShell Module version 11.3.1 where the default JSON serializer used to read Bicep output treats `$ref` properties as a JSON reference, whereas the desired behavior is to preserve it in the serialized JSON. We do specify within our workflows/pipelines to use the latest version of Az module within each relevant task/action. However, the "latest" version correlates to the latest version installed on the particular agent/runner, which is 11.3.1 at this time.
- **Impact:** All What-If checks/operations fail within Azure DevOps Pipeline/GitHub Actions Workflows
- **Workaround:** To mitigate this issue until the agents have the updated Az version installed, you can explicitly reference a particular Az version for each PowerShell task/action. For example:
Azure DevOps Workaround:

```yaml
- task: AzurePowerShell@5
displayName: "Logging and Sentinel Deployment"
inputs:
azureSubscription: ${{ variables.SERVICE_CONNECTION_NAME }}
azurePowerShellVersion: "11.3.0"
pwsh: true
ScriptType: "InlineScript"
Inline: |
.\pipeline-scripts\Deploy-ALZLoggingAndSentinel.ps1
```

GitHub Actions Workaround:

```yaml
- name: "Logging and Sentinel Deployment"
uses: azure/powershell@v1
with:
inlineScript: |
.\pipeline-scripts\Deploy-ALZLoggingAndSentinel.ps1
azPSVersion: "11.3.0"
```

- **Status:** As our team doesn't directly own the impacted module or have control over the agents/runners, we aim to enhance flexibility to assist with such issues in the future. To achieve this, we plan to introduce a variable in the .env file, enabling version control without the need for individual additions.

## How to Report an Issue

If you encounter an issue not listed here that would be helpful to be included or have additional information to provide, please open a [new issue](https://github.com/Azure/ALZ-Bicep/issues/new?assignees=&labels=bug&projects=&template=bug-report-issue-form.yaml&title=%5BPLACEHOLDER%5D+-+Place+a+descriptive+title+here) in the GitHub repository's issue tracker. Be sure to include detailed steps to reproduce the issue and any relevant context or screenshots.

We appreciate your help in improving ALZ-Bicep by reporting issues and providing feedback.
39 changes: 20 additions & 19 deletions docs/wiki/_Sidebar.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,22 @@
# Wiki Navigation

* [Wiki Home](https://github.com/Azure/ALZ-Bicep/wiki/Home)
* [Deployment Flow](https://github.com/Azure/ALZ-Bicep/wiki/DeploymentFlow)
* [Network Topology: Hub and Spoke](https://github.com/Azure/ALZ-Bicep/wiki/DeploymentFlowHS)
* [Network Topology: Virtual WAN](https://github.com/Azure/ALZ-Bicep/wiki/DeploymentFlowVWAN)
* [Zero Trust Networking Guide: Hub and Spoke](https://github.com/Azure/ALZ-Bicep/wiki/DeploymentGuideHSZT)
* [Consumer Guide](https://github.com/Azure/ALZ-Bicep/wiki/ConsumerGuide)
* [Accelerator](https://github.com/Azure/ALZ-Bicep/wiki/Accelerator)
* [How Does ALZ-Bicep Implement Azure Policies?](https://github.com/Azure/ALZ-Bicep/wiki/PolicyDeepDive)
* [Adding Custom Azure Policy Definitions](https://github.com/Azure/ALZ-Bicep/wiki/AddingPolicyDefs)
* [Assigning Azure Policies](https://github.com/Azure/ALZ-Bicep/wiki/AssigningPolicies)
* [How Does ALZ-Bicep Implement resilient deployments across availability zones?](https://github.com/Azure/ALZ-Bicep/wiki/Resiliency)
* [Contributing](https://github.com/Azure/ALZ-Bicep/wiki/Contributing)
* [Telemetry Tracking Using Customer Usage Attribution (PID)](https://github.com/Azure/ALZ-Bicep/wiki/CustomerUsage)
* [Azure Container Registry Deployment - Private Bicep Registry](https://github.com/Azure/ALZ-Bicep/wiki/ACRDeployment)
* [Frequently Asked Questions](https://github.com/Azure/ALZ-Bicep/wiki/FAQ)
* [Sample Pipelines](https://github.com/Azure/ALZ-Bicep/wiki/PipelinesOverview)
* [GitHub Actions](https://github.com/Azure/ALZ-Bicep/wiki/PipelinesGitHub)
* [Azure DevOps](https://github.com/Azure/ALZ-Bicep/wiki/PipelinesADO)
* [Code tours](https://github.com/Azure/ALZ-Bicep/wiki/CodeTour)
- [Wiki Home](https://github.com/Azure/ALZ-Bicep/wiki/Home)
- [Deployment Flow](https://github.com/Azure/ALZ-Bicep/wiki/DeploymentFlow)
- [Network Topology: Hub and Spoke](https://github.com/Azure/ALZ-Bicep/wiki/DeploymentFlowHS)
- [Network Topology: Virtual WAN](https://github.com/Azure/ALZ-Bicep/wiki/DeploymentFlowVWAN)
- [Zero Trust Networking Guide: Hub and Spoke](https://github.com/Azure/ALZ-Bicep/wiki/DeploymentGuideHSZT)
- [Consumer Guide](https://github.com/Azure/ALZ-Bicep/wiki/ConsumerGuide)
- [Accelerator](https://github.com/Azure/ALZ-Bicep/wiki/Accelerator)
- [Known Issues](https://github.com/Azure/ALZ-Bicep/wiki/KnownIssues)
- [Frequently Asked Questions](https://github.com/Azure/ALZ-Bicep/wiki/FAQ)
- [How Does ALZ-Bicep Implement Azure Policies?](https://github.com/Azure/ALZ-Bicep/wiki/PolicyDeepDive)
- [Adding Custom Azure Policy Definitions](https://github.com/Azure/ALZ-Bicep/wiki/AddingPolicyDefs)
- [Assigning Azure Policies](https://github.com/Azure/ALZ-Bicep/wiki/AssigningPolicies)
- [How Does ALZ-Bicep Implement resilient deployments across availability zones?](https://github.com/Azure/ALZ-Bicep/wiki/Resiliency)
- [Contributing](https://github.com/Azure/ALZ-Bicep/wiki/Contributing)
- [Telemetry Tracking Using Customer Usage Attribution (PID)](https://github.com/Azure/ALZ-Bicep/wiki/CustomerUsage)
- [Azure Container Registry Deployment - Private Bicep Registry](https://github.com/Azure/ALZ-Bicep/wiki/ACRDeployment)
- [Sample Pipelines](https://github.com/Azure/ALZ-Bicep/wiki/PipelinesOverview)
- [GitHub Actions](https://github.com/Azure/ALZ-Bicep/wiki/PipelinesGitHub)
- [Azure DevOps](https://github.com/Azure/ALZ-Bicep/wiki/PipelinesADO)
- [Code tours](https://github.com/Azure/ALZ-Bicep/wiki/CodeTour)