Skip to content

Commit 60340c2

Browse files
BernieWhiteBernieWhite
authored
AKS rule documentation quality updates (Azure#3044)
* AKS rule documentation quality updates * Clean up deprecations note
1 parent 6c59297 commit 60340c2

10 files changed

+434
-363
lines changed

‎docs/deprecations.md

-6
Original file line numberDiff line numberDiff line change
@@ -23,17 +23,11 @@ New name | Old name
2323
`AZURE_RESOURCE_ALLOWED_LOCATIONS` | `Azure_AllowedRegions` | :octicons-milestone-24: v1.30.0
2424
`AZURE_APIM_MINIMUM_CERTIFICATE_LIFETIME` | `Azure_MinimumCertificateLifetime` | :octicons-milestone-24: v1.39.0
2525

26-
!!! Note
27-
Configuration options marked _TBA_ are not available yet.
28-
Please use the old names until they are available.
29-
Check the [change log][1] and the [upgrade notes][2] for more information on a future release.
30-
3126
!!! Important
3227
New option names will work from the release specified by _Available from_.
3328
Configuring these options prior to that release will have no affect.
3429
For details on configuring these options see [upgrade notes][2] for details.
3530

36-
[1]: CHANGELOG-v1.md
3731
[2]: upgrade-notes.md#realigned-configuration-option-names
3832

3933
### Realignment of rules

‎docs/en/rules/Azure.AKS.AuditAdmin.md

+5-2
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
---
2+
reviewed: 2024-07-23
23
severity: Important
34
pillar: Cost Optimization
45
category: CO:07 Component costs
@@ -23,7 +24,7 @@ As a result, collecting audit logs for _get_ and _list_ operations of a producti
2324
AKS provides two log categories for collecting audit logs, `kube-audit` and `kube-audit-admin`.
2425

2526
- `kube-audit` - Audit log data for every audit event including _get_, _list_, _create_, _update_, _delete_, _patch_, and _post_.
26-
- `kube-audit-admin` - Is a subset of the `kube-audit` log category that excludes _get_ and list_ audit events.
27+
- `kube-audit-admin` - Is a subset of the `kube-audit` log category that excludes _get_ and _list_ audit events.
2728

2829
In other words, both `kube-audit` and `kube-audit-admin` contain the same data except `kube-audit-admin` does not contain _get_ and _list_ events.
2930
Changes to the cluster configuration are captured with _create_, _update_, _delete_, _patch_, and _post_ events.
@@ -119,9 +120,11 @@ resource diagnosticSetting 'Microsoft.Insights/diagnosticSettings@2021-05-01-pre
119120
}
120121
```
121122

123+
<!-- external:avm avm/res/container-service/managed-cluster diagnosticSettings -->
124+
122125
## LINKS
123126

124127
- [CO:07 Component costs](https://learn.microsoft.com/azure/well-architected/cost-optimization/optimize-component-costs)
125-
- [Monitor AKS](https://learn.microsoft.com/azure/aks/monitor-aks)
128+
- [Monitoring AKS data reference](https://learn.microsoft.com/azure/aks/monitor-aks-reference)
126129
- [AKS control plane/resource logs](https://learn.microsoft.com/azure/aks/monitor-aks#aks-control-planeresource-logs)
127130
- [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.insights/diagnosticsettings)

‎docs/en/rules/Azure.AKS.AuditLogs.md

+82-118
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
---
2+
reviewed: 2024-07-23
23
severity: Important
34
pillar: Security
4-
category: Monitor
5+
category: SE:10 Monitoring and threat detection
56
resource: Azure Kubernetes Service
67
online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.AKS.AuditLogs/
78
---
@@ -14,15 +15,18 @@ AKS clusters should collect security-based audit logs to assess and monitor the
1415

1516
## DESCRIPTION
1617

17-
To capture security-based audit logs from AKS clusters, the following diagnostic log categories should be enabled:
18+
The Azure Kubernetes Service (AKS) service supports collection of security-based audit logs from clusters.
19+
The following log categories are available:
1820

19-
- `kube-audit` or `kube-audit-admin`, or both.
20-
- `kube-audit` - Contains all audit log data for every audit event, including get, list, create, update, delete, patch, and post.
21-
- `kube-audit-admin` - Is a subset of the `kube-audit` log category.
22-
`kube-audit-admin` reduces the number of logs significantly by excluding the get and list audit events from the log.
23-
- `guard` - Contains logs for Azure Active Directory (AAD) authorization integration.
24-
For managed Azure AD, this includes token in and user info out.
25-
For Azure RBAC, this includes access reviews in and out.
21+
- `kube-audit` - Audit log data for every audit event including _get_, _list_, _create_, _update_, _delete_, _patch_, and _post_.
22+
- `kube-audit-admin` - Is a subset of the `kube-audit` log category that excludes _get_ and _list_ audit events.
23+
- `guard` - Contains logs for Entra ID and Azure RBAC events.
24+
25+
In other words, both `kube-audit` and `kube-audit-admin` contain the same data except `kube-audit-admin` does not contain _get_ and _list_ events.
26+
27+
For most configurations, consider enabling logging for `kube-audit-admin` and `guard`.
28+
This configuration provides good coverage and significantly reduces the number of logs and overall cost for collecting and storing AKS audit events.
29+
Enable `kube-audit` only when required.
2630

2731
## RECOMMENDATION
2832

@@ -35,127 +39,87 @@ Consider configuring diagnostic settings to capture security-based audit logs fr
3539
To deploy AKS clusters that pass this rule:
3640

3741
- Deploy a diagnostic settings sub-resource.
38-
- Enable logging for the `kube-audit`/`kube-audit-admin` and `guard` categories.
42+
- Enable logging for `kube-audit-admin` (or `kube-audit`) and `guard` log categories.
3943

4044
For example:
4145

4246
```json
4347
{
44-
"comments": "Azure Kubernetes Cluster",
45-
"apiVersion": "2020-12-01",
46-
"dependsOn": [
47-
"[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('identityName'))]"
48-
],
49-
"type": "Microsoft.ContainerService/managedClusters",
50-
"location": "[parameters('location')]",
51-
"name": "[parameters('clusterName')]",
52-
"identity": {
53-
"type": "UserAssigned",
54-
"userAssignedIdentities": {
55-
"[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('identityName'))]": {}
48+
"type": "Microsoft.Insights/diagnosticSettings",
49+
"apiVersion": "2021-05-01-preview",
50+
"scope": "[format('Microsoft.ContainerService/managedClusters/{0}', parameters('name'))]",
51+
"name": "audit",
52+
"properties": {
53+
"logs": [
54+
{
55+
"category": "kube-audit-admin",
56+
"enabled": true,
57+
"retentionPolicy": {
58+
"days": 0,
59+
"enabled": false
60+
}
61+
},
62+
{
63+
"category": "guard",
64+
"enabled": true,
65+
"retentionPolicy": {
66+
"days": 0,
67+
"enabled": false
5668
}
57-
},
58-
"properties": {
59-
"kubernetesVersion": "[parameters('kubernetesVersion')]",
60-
"disableLocalAccounts": true,
61-
"enableRBAC": true,
62-
"dnsPrefix": "[parameters('dnsPrefix')]",
63-
"agentPoolProfiles": [
64-
{
65-
"name": "system",
66-
"osDiskSizeGB": 32,
67-
"count": 3,
68-
"minCount": 3,
69-
"maxCount": 10,
70-
"enableAutoScaling": true,
71-
"maxPods": 50,
72-
"vmSize": "Standard_D2s_v3",
73-
"osType": "Linux",
74-
"type": "VirtualMachineScaleSets",
75-
"vnetSubnetID": "[variables('clusterSubnetId')]",
76-
"mode": "System",
77-
"osDiskType": "Ephemeral",
78-
"scaleSetPriority": "Regular"
79-
}
80-
],
81-
"aadProfile": {
82-
"managed": true,
83-
"enableAzureRBAC": true,
84-
"adminGroupObjectIDs": "[parameters('clusterAdmins')]",
85-
"tenantID": "[subscription().tenantId]"
86-
},
87-
"networkProfile": {
88-
"networkPlugin": "azure",
89-
"networkPolicy": "azure",
90-
"loadBalancerSku": "Standard",
91-
"serviceCidr": "192.168.0.0/16",
92-
"dnsServiceIP": "192.168.0.4",
93-
"dockerBridgeCidr": "172.17.0.1/16"
94-
},
95-
"autoUpgradeProfile": {
96-
"upgradeChannel": "stable"
97-
},
98-
"addonProfiles": {
99-
"azurepolicy": {
100-
"enabled": true,
101-
"config": {
102-
"version": "v2"
103-
}
104-
},
105-
"omsagent": {
106-
"enabled": true,
107-
"config": {
108-
"logAnalyticsWorkspaceResourceID": "[parameters('workspaceId')]"
109-
}
110-
},
111-
"kubeDashboard": {
112-
"enabled": false
113-
}
69+
}
70+
],
71+
"workspaceId": "[parameters('workspaceId')]",
72+
"logAnalyticsDestinationType": "Dedicated"
73+
},
74+
"dependsOn": [
75+
"[resourceId('Microsoft.ContainerService/managedClusters', parameters('name'))]"
76+
]
77+
}
78+
```
79+
80+
### Configure with Bicep
81+
82+
To deploy AKS clusters that pass this rule:
83+
84+
- Deploy a diagnostic settings sub-resource.
85+
- Enable logging for `kube-audit-admin` (or `kube-audit`) and `guard` log categories.
86+
87+
For example:
88+
89+
```bicep
90+
resource auditLogs 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = {
91+
name: 'audit'
92+
scope: cluster
93+
properties: {
94+
logs: [
95+
{
96+
category: 'kube-audit-admin'
97+
enabled: true
98+
retentionPolicy: {
99+
days: 0
100+
enabled: false
114101
}
115-
},
116-
"resources": [
117-
{
118-
"apiVersion": "2016-09-01",
119-
"type": "Microsoft.ContainerService/managedClusters/providers/diagnosticSettings",
120-
"name": "[concat(parameters('clusterName'), '/Microsoft.Insights/service')]",
121-
"properties": {
122-
"workspaceId": "[parameters('workspaceId')]",
123-
"logs": [
124-
{
125-
"category": "kube-audit",
126-
"enabled": true,
127-
"retentionPolicy": {
128-
"days": 0,
129-
"enabled": false
130-
}
131-
},
132-
{
133-
"category": "kube-audit-admin",
134-
"enabled": true,
135-
"retentionPolicy": {
136-
"days": 0,
137-
"enabled": false
138-
}
139-
},
140-
{
141-
"category": "guard",
142-
"enabled": true,
143-
"retentionPolicy": {
144-
"days": 0,
145-
"enabled": false
146-
}
147-
}
148-
],
149-
"metrics": []
150-
}
102+
}
103+
{
104+
category: 'guard'
105+
enabled: true
106+
retentionPolicy: {
107+
days: 0
108+
enabled: false
151109
}
110+
}
152111
]
112+
workspaceId: workspaceId
113+
logAnalyticsDestinationType: 'Dedicated'
114+
}
153115
}
154116
```
155117

118+
<!-- external:avm avm/res/container-service/managed-cluster diagnosticSettings -->
119+
156120
## LINKS
157121

158-
- [Security audits](https://learn.microsoft.com/azure/architecture/framework/security/monitor-audit)
122+
- [SE:10 Monitoring and threat detection](https://learn.microsoft.com/azure/well-architected/security/monitor-threats)
159123
- [Monitoring AKS data reference](https://learn.microsoft.com/azure/aks/monitor-aks-reference)
160-
- [Collect resource logs](https://learn.microsoft.com/azure/aks/monitor-aks#collect-resource-logs)
161-
- [Template reference](https://learn.microsoft.com/azure/templates/microsoft.insights/diagnosticsettings?tabs=json)
124+
- [AKS control plane/resource logs](https://learn.microsoft.com/azure/aks/monitor-aks#aks-control-planeresource-logs)
125+
- [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.insights/diagnosticsettings)

0 commit comments

Comments
 (0)