AMBA consumer guide without the use of a public fork in GitHub

[MilesCameron-DMs]

Check for previous/existing GitHub issues

• I have checked for previous/existing GitHub issues

Description

Hi guys,

I have read through the wiki pages and found conflicting information around consumption of this repo.

For example on github.io page it states for Deploy with GitHub Actions "To start, you can either download a copy of the parameter file or clone/fork the repository."

On the GitHub repo it states "Fork this repo to your own GitHub organization, you should not create a direct clone of the repo"

Ultimately enterprise companies may not desire or will be prevented by GitHub policy from publishing a public repository in an org.

With that in mind, what would be the approach with the aim of consuming this repo, keeping it up to date and ensuring you can use GitHub processes i.e. not PowerShell, the portal or the CLI.

Please can this be covered somewhere? Apologies if it has but i have searched and scrolled through most of the site pages and cant see anything consistent or thorough which will ultimately hamper adoption of all the useful work you guys are doing.

[Brunoga-MS]

Hello @MilesCameron-DMs ,
thanks for your feedback. Our official documentation is the one located at the Azure Monitor Baseline Alerts site, which is basically the githib.io site you mentioned. I really would like to encourage you to only refer to that one.

As per your question, cloning or forking the repo is only required if you need to customize policy definitions, policy set definitons or policy assignments based on your needs. Conversely, you can just consume the official repo, which is maintained by the AMBA team, as it is with no need to clone/fork it. You only need to download and customize the parameter file and to refer to it during the deployment. As an alternative, to speed up and ease the deployment, it is also possible to use the Deploy via the Azure Portal (Preview), which just requires you to input some information leveraging the default values (the ones contained in the parameter files provided in the repo) for alert implementation.

We will take care of clarifying the above in our documentation as soon as possible.

Hope that helps.

Thanks,
Bruno.

[MilesCameron-DMs]

Thanks @Brunoga-MS

I am finding the wiki pages difficult to consume as they dont appear to flow together well. I am sure the information is there :)

I was expecting a GitHub Action to update the repo and then do a release but it looks like there is a process for deploying and then a separate process for updating.

If we do a manual deployment my next question would be how do we maintain and ensure we keep up to date as its not clear from Update to new releases pages.

For example all of the pages mention running PowerShell scripts but they dont tell you what the PowerShell scripts do and none of them suggest they are performing an update.

Apologies but there is a lot of assumed knowledge/experience in these pages that makes them difficult to follow.

For example on this page:

https://azure.github.io/azure-monitor-baseline-alerts/patterns/alz/UpdateToNewReleases/Update_to_release_2024-09-02/

• it only has a Pre update actions section - no update actions section
• It uses a PowerShell script named ./Start-AMBAPolicyInitiativesAndAssignmentsCleanup.ps1 This does not suggest an update but the article ends with this. What does that script do?

Although this information may be somewhere else, it is very difficult and time consuming to follow.

PS how do you do an update? 😆

[Brunoga-MS]

Hello @MilesCameron-DMs ,
I definitely hear you. We will try to make the update documentation more clear. In the meantime I hope the following summary will help:

1. Check the general update guidance at https://azure.github.io/azure-monitor-baseline-alerts/patterns/alz/UpdateToNewReleases/#steps-to-update-to-the-latest-release (which also contains the steps below)
2. If you are using your fork/clone, make sure it is aligned with the official repo
3. Make sure the parameter file structure is aligned with the one in the official repo
4. Check the update to release xxx guidance to see if there's any pre-update step required. For instance, because of a breaking change, before updating to release 2024-09-02 you need to remove all existing policy and policy assignments using the provided script.
5. Deploy the latest version using your preferred method
6. Check the update to release xxx guidance to see if there's any pre-update step required. For instance, after updating to release 2024-04-12 you need to remove existing notification assets using the provided script.
7. Run the remediation using the provided script

As a side note, updating your own fork/clone, is not something we can manage. We only ensure our original repo is up to date. Hence, is you use it , or our releases, as pointers for your deployment, you will always get the latest version.

Thanks,
Bruno.

[MilesCameron-DMs]

Thanks @Brunoga-MS - appreciate you getting back to me.

[Brunoga-MS]

Hello @MilesCameron-DMs ,
I just found out that we have an FAQ entry (Can I use AMBA-ALZ without cloning/forking a GitHub repository) which might contain the guidance you area looking at. Could you please check if it is ok or there's the need for more guidance?