Skip to content

Commit dc8ce62

Browse files
Claudio-MerolaClaudio-Merola
authored
Merge pull request #315 from ChrisHope123/Documentation-GitHub-Integration-Addition
Updating existing GitHub Action documentation + Adding documentation for usage of User-Assigned Identity
2 parents 22feed7 + 6cb0324 commit dc8ce62

File tree

2 files changed

+214
-13
lines changed

2 files changed

+214
-13
lines changed

‎docs/about/authors.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ Many people have contributed to Azure Resource Inventory over time. Contributors
2525
- Jeferson Machado dos Santos
2626
- JP Sarmiento
2727
- Lucas Hattori Costa
28+
- Peter Szabo
2829
- Thiago Almeida
2930

3031
## Special Thanks

‎docs/advanced/github-actions.md‎

Lines changed: 213 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -16,11 +16,13 @@ GitHub Actions offers a flexible way to automate the execution of Azure Resource
1616
To use this approach, you'll need:
1717

1818
1. A GitHub repository
19-
2. An Azure service principal with appropriate permissions
19+
2. An Azure service principal or user-assigned identity with appropriate permissions
2020
3. GitHub Secrets to store your Azure credentials securely
2121

2222
## Setting Up Azure Authentication
2323

24+
### Using service principal
25+
2426
1. Create a service principal in Azure:
2527

2628
```bash
@@ -43,16 +45,212 @@ az ad sp create-for-rbac --name "ARI-GitHub-Action" --role "Reader" --scopes "/s
4345
"managementEndpointUrl": "https://management.core.windows.net/"
4446
}
4547
```
46-
4748
3. In your GitHub repository, go to Settings → Secrets and variables → Actions
49+
4850
4. Create these repository secrets:
49-
- `AZURE_CREDENTIALS`: The entire JSON output from step 1
5051
- `AZURE_CLIENT_ID`: The client ID from the JSON
5152
- `AZURE_CLIENT_SECRET`: The client secret from the JSON
5253
- `AZURE_TENANT_ID`: The tenant ID from the JSON
5354
- `AZURE_SUBSCRIPTION_ID`: The subscription ID from the JSON
5455

55-
## GitHub Action Workflow Template
56+
57+
58+
59+
60+
61+
62+
### Using user-assigned identity
63+
1. Create a user-assigned identity in Azure:
64+
``` bash
65+
az identity create --name <identity-name> --resource-group <resource-group-name>
66+
```
67+
68+
The output of this command will look similar to this:
69+
``` json
70+
{
71+
"clientId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
72+
"clientResourceGroup": "myResourceGroup",
73+
"id": "/subscriptions/<subscription-id>/resourcegroups/myResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myIdentity",
74+
"location": "eastus",
75+
"name": "myIdentity",
76+
"principalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
77+
"resourceGroup": "myResourceGroup",
78+
"tags": {},
79+
"tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
80+
"type": "Microsoft.ManagedIdentity/userAssignedIdentities"
81+
}
82+
```
83+
84+
You should save this for later steps.
85+
86+
2. Assign reader role with appropiate scope:
87+
``` bash
88+
az role assignment create --assignee <principal-id> --role "Reader" --scope <scope>
89+
```
90+
The scope of the role assignement will define if ARI will be able to find resources. It is adviseable to use the subscription/management group that contains everything you want to document.
91+
92+
3. Create Federated Credentials
93+
To log in with the created user-assigned identity, we need to create a federated credential, to be able to use OIDC to connect.
94+
``` bash
95+
az identity federated-credential create
96+
--identity-name "myManagedIdentity"
97+
--resource-group "myResourceGroup"
98+
--issuer "https://token.actions.githubusercontent.com"
99+
--subject "repo:myorg/myrepo:ref:refs/heads/main"
100+
--name "github-federation"
101+
# Issuer will differ if you use GitHub Enterprise server.
102+
```
103+
You can also follow the the Microsoft Learn documentation: [MS Learn/Configure a federated identity credential on a user-assigned managed identity](https://learn.microsoft.com/en-gb/entra/workload-id/workload-identity-federation-create-trust-user-assigned-managed-identity?pivots=identity-wif-mi-methods-azp#github-actions-deploying-azure-resources)
104+
105+
106+
4. (Optional) Retrieve identity parameters
107+
If you forgot to save the output of the user-assigned identity, you can retrieve the necessary fields using the following commands:
108+
109+
``` bash
110+
az identity show --name <identity-name> --resource-group <resource-group>
111+
```
112+
113+
5. Set GitHub Secrets
114+
You can either set GitHub secrets using the online interface, or using GitHub CLI.
115+
116+
- If you want to set it using the online graphical interface:
117+
- In your GitHub repository, go to Settings → Secrets and variables → Actions
118+
119+
120+
- If you want to set it using GitHub CLI:
121+
- Make sure that you have GitHub CLI installed
122+
- Create repository secrets using the following template:
123+
124+
gh secret set <secret-name> -b <secret-value> -R <owner>/<repo-name>
125+
126+
- Set the required secrets:
127+
- `AZURE_CLIENT_ID`: The client ID from the JSON
128+
- `AZURE_TENANT_ID`: The tenant ID from the JSON
129+
- `AZURE_SUBSCRIPTION_ID`: The subscription ID from the JSON
130+
131+
## GitHub Action Workflow Template For Service Principal
132+
133+
Create a file named `.github/workflows/azure-inventory.yml` in your repository with the following content:
134+
135+
```yaml
136+
name: Azure Resource Inventory
137+
138+
on:
139+
schedule:
140+
# Run weekly on Monday at 8:00 AM UTC
141+
- cron: '0 8 * * 1'
142+
# Allow manual trigger
143+
workflow_dispatch:
144+
inputs:
145+
subscriptionId:
146+
description: 'Specific subscription ID (optional)'
147+
required: false
148+
default: '00000000-0000-0000-0000-000000000000'
149+
resourceGroup:
150+
description: 'Specific resource group (optional)'
151+
required: false
152+
default: 'test-rg'
153+
reportName:
154+
description: 'Custom report name (optional)'
155+
required: false
156+
default: 'TestInventory'
157+
158+
jobs:
159+
run-inventory:
160+
runs-on: ubuntu-latest
161+
steps:
162+
- name: Checkout repository
163+
uses: actions/checkout@v3
164+
165+
- name: Login to Azure
166+
uses: azure/login@v2
167+
with:
168+
creds: '{"clientId":"${{ secrets.AZURE_CLIENT_ID }}","clientSecret":"${{ secrets.AZURE_CLIENT_SECRET }}","subscriptionId":"${{ secrets.AZURE_SUBSCRIPTION_ID }}","tenantId":"${{ secrets.AZURE_TENANT_ID }}"}'
169+
enable-AzPSSession: true
170+
171+
- name: Install ARI and dependencies
172+
shell: pwsh
173+
run: |
174+
Install-Module -Name AzureResourceInventory -Force -Scope CurrentUser
175+
Install-Module -Name Az.Accounts -Force -Scope CurrentUser
176+
Install-Module -Name ImportExcel -Force -Scope CurrentUser
177+
Import-Module AzureResourceInventory
178+
179+
- name: Run ARI
180+
shell: pwsh
181+
run: |
182+
$params = @{}
183+
184+
# If subscription ID is provided
185+
if ("${{ github.event.inputs.subscriptionId }}" -ne "") {
186+
$params.Add("SubscriptionID", "${{ github.event.inputs.subscriptionId }}")
187+
}
188+
189+
# If resource group is provided
190+
if ("${{ github.event.inputs.resourceGroup }}" -ne "") {
191+
$params.Add("ResourceGroup", "${{ github.event.inputs.resourceGroup }}")
192+
}
193+
194+
# Set report name
195+
if ("${{ github.event.inputs.reportName }}" -ne "") {
196+
$params.Add("ReportName", "${{ github.event.inputs.reportName }}")
197+
} else {
198+
$params.Add("ReportName", "AzureInventory_$(Get-Date -Format 'yyyyMMdd')")
199+
}
200+
201+
# Add any other parameters you want to use here
202+
# For example: $params.Add("SecurityCenter", $true)
203+
204+
# Run ARI
205+
Invoke-ARI @params
206+
207+
# Create artifacts directory
208+
New-Item -Path "$env:GITHUB_WORKSPACE/ari-reports" -ItemType Directory -Force
209+
210+
# Move reports to artifacts directory
211+
Move-Item -Path "$HOME/AzureResourceInventory/*.xlsx" -Destination "$env:GITHUB_WORKSPACE/ari-reports/" -Force
212+
213+
if (Test-Path "$HOME/AzureResourceInventory/*.xml") {
214+
Move-Item -Path ""$HOME/AzureResourceInventory/*.xml" -Destination "$env:GITHUB_WORKSPACE/ari-reports/" -Force
215+
}
216+
217+
- name: Upload Reports as Artifacts
218+
uses: actions/upload-artifact@v4
219+
with:
220+
name: ARI-Reports
221+
path: ari-reports/
222+
retention-days: 90
223+
224+
# Optional: Upload to Azure Storage
225+
# - name: Upload to Azure Storage
226+
# shell: pwsh
227+
# run: |
228+
# $storageAccount = "yourstorageaccount"
229+
# $container = "ari-reports"
230+
#
231+
# # Create the storage context
232+
# $ctx = New-AzStorageContext -StorageAccountName $storageAccount -UseConnectedAccount
233+
#
234+
# # Upload files to Azure Storage
235+
# Get-ChildItem -Path "$env:GITHUB_WORKSPACE/ari-reports" -File | ForEach-Object {
236+
# Set-AzStorageBlobContent -File $_.FullName -Container $container -Blob $_.Name -Context $ctx -Force
237+
# }
238+
239+
# Optional: Send email notification
240+
# - name: Send Email Notification
241+
# uses: dawidd6/action-send-mail@v3
242+
# with:
243+
# server_address: smtp.gmail.com
244+
# server_port: 465
245+
# username: ${{ secrets.EMAIL_USERNAME }}
246+
# password: ${{ secrets.EMAIL_PASSWORD }}
247+
# subject: Azure Resource Inventory Report
248+
# body: Azure Resource Inventory has completed. Reports are attached.
249+
# to: [email protected]
250+
# from: Azure Inventory <[email protected]>
251+
```
252+
253+
## GitHub Action Workflow Template For User-Assigned Identity
56254

57255
Create a file named `.github/workflows/azure-inventory.yml` in your repository with the following content:
58256

@@ -87,9 +285,12 @@ jobs:
87285
uses: actions/checkout@v3
88286

89287
- name: Login to Azure
90-
uses: azure/login@v1
288+
uses: azure/login@v2
91289
with:
92-
creds: ${{ secrets.AZURE_CREDENTIALS }}
290+
client-id: ${{ secrets.AZURE_CLIENT_ID }}
291+
tenant-id: ${{ secrets.AZURE_TENANT_ID }}
292+
subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
293+
enable-AzPSSession: true
93294

94295
- name: Install ARI and dependencies
95296
shell: pwsh
@@ -131,14 +332,14 @@ jobs:
131332
New-Item -Path "$env:GITHUB_WORKSPACE/ari-reports" -ItemType Directory -Force
132333
133334
# Move reports to artifacts directory
134-
Move-Item -Path ".\*.xlsx" -Destination "$env:GITHUB_WORKSPACE/ari-reports/" -Force
335+
Move-Item -Path "$HOME/AzureResourceInventory/*.xlsx" -Destination "$env:GITHUB_WORKSPACE/ari-reports/" -Force
135336
136-
if (Test-Path ".\*.drawio") {
137-
Move-Item -Path ".\*.drawio" -Destination "$env:GITHUB_WORKSPACE/ari-reports/" -Force
337+
if (Test-Path "$HOME/AzureResourceInventory/*.xml") {
338+
Move-Item -Path ""$HOME/AzureResourceInventory/*.xml" -Destination "$env:GITHUB_WORKSPACE/ari-reports/" -Force
138339
}
139340
140341
- name: Upload Reports as Artifacts
141-
uses: actions/upload-artifact@v3
342+
uses: actions/upload-artifact@v4
142343
with:
143344
name: ARI-Reports
144345
path: ari-reports/
@@ -253,16 +454,15 @@ Before using this feature, make sure to add the following secrets to your reposi
253454

254455
If you encounter authentication errors:
255456

256-
1. Check that your service principal has the required permissions
457+
1. Check that your service principal/user-assigned identity has the required permissions
257458
2. Verify the secrets are correctly set in GitHub
258-
3. Try using `azure/login@v1` with the entire JSON credential
259459

260460
### Missing Reports
261461

262462
If reports aren't generated:
263463

264464
1. Check the workflow logs for errors
265-
2. Ensure the service principal has at least Reader access to the subscriptions
465+
2. Ensure the service principal/user-assigned identity has at least Reader access to the subscriptions
266466
3. Try running with the `-Debug` parameter for detailed logging
267467

268468
## Comparison with Azure Automation

0 commit comments

Comments
 (0)