Skip to content

Commit 7d3b745

Browse files
v-ccolinv-ccolin
authored
Merge pull request #265852 from joemarshallmsft/joe/nexus-acls
Overview article for ACLs
2 parents c133665 + c35502a commit 7d3b745

File tree

4 files changed

+285
-0
lines changed

4 files changed

+285
-0
lines changed

‎articles/operator-nexus/TOC.yml

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,8 @@
2222
href: concepts-network-fabric-controller.md
2323
- name: Network Fabric Services
2424
href: concepts-network-fabric-services.md
25+
- name: Access Control Lists
26+
href: concepts-access-control-lists.md
2527
- name: Nexus Kubernetes
2628
href: concepts-nexus-kubernetes-cluster.md
2729
- name: Observability
@@ -215,3 +217,10 @@
215217
href: reference-near-edge-storage.md
216218
- name: Limits & quotas
217219
href: reference-limits-and-quotas.md
220+
- name: Access Control Lists
221+
expanded: false
222+
items:
223+
- name: Access Control List configuration
224+
href: reference-acl-configuration.md
225+
- name: Access Control List configuration examples
226+
href: reference-acl-examples.md

‎articles/operator-nexus/concepts-access-control-lists.md

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
---
2+
title: Azure Operator Nexus Access Control Lists Overview
3+
description: Get an overview of Access Control Lists for Azure Operator Nexus.
4+
author: joemarshallmsft
5+
ms.author: joemarshall
6+
ms.service: azure-operator-nexus
7+
ms.topic: conceptual
8+
ms.date: 02/09/2024
9+
ms.custom: template-concept
10+
---
11+
12+
# Access Control Lists Overview
13+
14+
An Access Control List (ACL) is a list of rules that control the inbound and outbound flow of packets through an interface. The interface can be an Ethernet interface, a sub interface, a port channel interface, or the switch control plane itself.
15+
16+
An ACL that is applied to incoming packets is called an **Ingress ACL**. An ACL that is applied to outgoing packets is called an **Egress ACL**.
17+
18+
An ACL has a Traffic-Policy definition including a set of match criteria and respective actions. The Traffic-Policy can match various conditions and perform actions such as count, drop, log, or police.
19+
20+
The available match criteria depend on the ACL type:
21+
22+
- IPv4 ACLs can match IPv4 source or destination addresses, with L4 modifiers including protocol, port number, and DSCP value.
23+
24+
- IPv6 ACLs can match IPv6 source or destination addresses, with L4 modifiers including protocol, port number.
25+
26+
- Standard IPv4 ACLs can match only on source IPv4 address.
27+
28+
- Standard IPv6 ACLs can match only on source IPv6 address.
29+
30+
ACLs can be either static or dynamic. Static ACLs are processed in order, beginning with the first rule and proceeding until a match is encountered. Dynamic ACLs use the payload keyword to turn an ACL into a group like PortGroups, VlanGroups, IPGroups for use in other ACLs. A dynamic ACL provides the user with the ability to enable or disable ACLs based on access session requirements.
31+
32+
ACLs can be applied to Network to Network interconnect (NNI) or External Network resources. An NNI is a child resource of a Network Fabric. ACLs can be created and linked to an NNI before the Network Fabric is provisioned. ACLs can be updated or deleted after the Network Fabric is deprovisioned.
33+
34+
This table summarizes the resources that can be associated with an ACL:
35+
36+
37+
| Resource Name | Supported | Default |
38+
|--|--|--|
39+
| NNF | Yes | All Production SKUs |
40+
| Isolation Domain | Yes on External Network with optionA | NA |
41+
| Network to network interconnect(NNI) | Yes | NA |
42+
43+
## Traffic policy
44+
45+
A traffic policy is a set of rules that control the flow of packets in and out of a network interface. This section explains the match criteria and actions available for distinct types of network resources.
46+
47+
- **Match Configuration**: The conditions that are used to match packets. You can match on various attributes, including:
48+
- IP address
49+
- Transport protocol
50+
- Port
51+
- VLAN ID
52+
- DSCP
53+
- Ethertype
54+
- IP fragmentation
55+
- TTL
56+
57+
Each match criterion has a name, a sequence number, an IP address type, and a list of match conditions. A packet matches the configuration if it meets all the criteria. For example, a match configuration of `protocol tcp, source port 100, destination port 200` matches packets that use the TCP protocol, with source port 100 and destination port 200.
58+
59+
- **Actions**: The operations that are performed on the matched packets, including:
60+
- Count
61+
- Permit
62+
- Drop
63+
64+
Each match criterion can have one or more actions associated with it.
65+
66+
- **Dynamic match configuration**: An optional feature that allows the user to define custom match conditions using field sets and user-defined fields. Field sets are named groups of values that can be used in match conditions, such as port numbers, IP addresses, VLAN IDs, etc. Dynamic match configuration can be provided inline or in a file stored in a blob container. For example, `field-set tcpport1 80, 443, 8080` defines a field set named tcpport1 with three port values, and `user-defined-field gtpv1-tid payload 0 32` defines a user-defined field named gtpv1-tid that matches the first 32 bits of the payload.

‎articles/operator-nexus/reference-acl-configuration.md

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
---
2+
title: Azure Operator Nexus Access Control Lists Configuration
3+
description: Detailed configuration for Azure Operator Nexus Access Control Lists.
4+
author: joemarshallmsft
5+
ms.author: joemarshall
6+
ms.service: azure-operator-nexus
7+
ms.topic: reference
8+
ms.date: 02/09/2024
9+
---
10+
11+
# Access Control List Configuration
12+
13+
A traffic policy MATCHING CONFIGURATION defines the conditions and parameters for matching criteria in a traffic policy. A traffic policy is used by an Access Control List (ACL) to control the flow of packets into or out of network interfaces based on match criteria and the related actions. A traffic policy can match packets using properties including:
14+
15+
- **dot1q**: the VLAN ID in the 802.1Q tag.
16+
17+
- **ethertype**: the EtherType field in the Ethernet header.
18+
19+
- **fragment**: whether the packet is an IP fragment.
20+
21+
- **protocol**: the transport protocol type, such as TCP, UDP, ICMP, or IGMP.
22+
23+
- **source**: the source IP address, port number or port range.
24+
25+
- **destination**: the destination IP address, port number or port range.
26+
27+
- **ttl**: the time-to-live (TTL) value in the IP header.
28+
29+
- **dscp**: the differentiated services code point (DSCP) value in the IP header.
30+
31+
## Example match conditions
32+
33+
- **Match on source and destination IP prefixes**: You can use the source prefix and destination prefix conditions to match on the IP addresses of a packet. For example, `source prefix 10.0.0.0/24` matches any packet with a source IP address in the range of 10.0.0.0 to 10.0.0.255. You can also use the longest prefix option to match the most specific prefix. For example, `destination longest-prefix 10.0.0.0/24 10.0.0.128/25` will match any packet with a destination IP address in the range of 10.0.0.128 to 10.0.0.255, but not 10.0.0.0. to 10.0.0.127.
34+
35+
- **Match on protocol**: You can use the protocol condition to match on the transport protocol of a packet, such as TCP, UDP, or ICMP. You can also specify the protocol number, such as 1 for ICMP, 6 for TCP, and 17 for UDP. For example, `protocol tcp` will match any packet with TCP as the protocol.
36+
- **Match on port numbers**: When the transport protocol uses ports (multiplexing), you can use the source port and destination port conditions to match the port numbers of the packets. For example, `protocol tcp destination port 80` will match any packet with TCP as the protocol and 80 as the destination port number. You can also use a list of ports, a range of ports, or a field-set name to match on multiple port numbers. For example, `protocol udp source port 53, 67-69, field-set udpport1` will match any packet with UDP as the protocol and 53, 67, 68, 69, or any port number in the field-set `udpport1` as the source port number.
37+
38+
- **Match on DSCP value**: You can use the dscp condition to match on the differentiated services code point (DSCP) value of the packets. The DSCP value is a 6-bit field in the IP header that indicates the quality of service (QoS) level of the packets.
39+
40+
## Dynamic match configuration
41+
42+
Dynamic match configuration uses field-sets to simplify and reuse the match conditions for user-defined fields. You can store the user-defined field and the field-set definitions in a file in your own Azure storage account blob container and provide the blob URL in the aclsUrl property in the ACL payload. The file content needs to be sent to the Southbound utility service separately after generating the base config.
43+
44+
Dynamic match configuration makes it easier to handle complex matching scenarios like these:
45+
46+
- **Match on VLAN and DSCP values using field-sets**: You can use the dot1q and dscp conditions to match on the VLAN and DSCP values of the packets. You can also use field-sets to simplify and reuse the match conditions for VLAN and DSCP values. For example, you can define a field-set named `voice-vlan` with a list of VLAN IDs that are used for voice traffic, such as 100, 200, and 300. Then, you can use the field-set name in the match condition, such as `dot1q vlan field-set voice-vlan`, to match any packet with a VLAN ID in the voice-vlan field-set. Similarly, you can define a field-set named `voice-dscp` with a list of DSCP values that are used for voice traffic, such as 40, 46, and 48. Then, you can use the field-set name in the match condition, such as `dscp field-set voice-dscp`, to match any packet with a DSCP value in the `voice-dscp` field-set.
47+
48+
- **Match on source and destination IP prefixes using field-sets**: You can also use field-sets to simplify and reuse the match conditions for IP prefixes. For example, you can define a field-set named `internal-networks` with a list of IP prefixes that belong to your internal network, such as 10.0.0.0/24 or 172.16.0.0/24. Then, you can use the field-set name in the match condition, such as `source prefix field-set internal-networks`, to match any packet with a source IP address in the internal network.
49+
50+
You can store the field-set definition in a file in your own Azure storage account blob container and provide the blob URL in the aclsUrl property in the ACL payload.
51+
52+
## Configuration parameters for an Access Control List
53+
54+
| Parameter | Description | Example |
55+
|--|--|--|
56+
| **resource-group** |The name of the resource group where the network fabric is located. | `example-rg` |
57+
| **location** | The location of the network fabric | `eastus2euap` |
58+
| **resource-name** | The name of the ACL. | `example-Ipv4ingressACL` |
59+
| **configuration-type** | The type of configuration for the ACL. It can be either `Inline` or `File`. | `Inline` |
60+
| **default-action** | The default action to be taken for the ACL. It can be either `Permit` or `Deny`. | `Permit` |
61+
| **match-configurations** | The list of match configurations for the ACL. Each match configuration has a name, a sequence number, an IP address type, a list of match conditions, and a list of actions. | `[{matchConfigurationName:'example-match',sequenceNumber:123,ipAddressType:IPv4,matchConditions:[...],actions:[...]}]` |
62+
| **dynamic-match-configurations** | The list of dynamic match configurations for the ACL. Each dynamic match configuration has a list of IP groups, VLAN groups, and port groups. | `[{ipGroups:[...],vlanGroups:[...],portGroups:[...]}]` |
63+
| **acls-url** | The URL of the ACLs file. This parameter is required only if the configuration-type is `File`. | `https://ACL-Storage-URL` |
64+
| **annotation** | An optional annotation for the ACL. | `annotation` |

‎articles/operator-nexus/reference-acl-examples.md

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
title: Azure Operator Nexus Access Control Lists Examples
3+
description: Examples of configuring and creating Azure Operator Nexus Access Control Lists.
4+
author: joemarshallmsft
5+
ms.author: joemarshall
6+
ms.service: azure-operator-nexus
7+
ms.topic: reference
8+
ms.date: 02/09/2024
9+
---
10+
11+
# Access Control List Creation and Configuration Examples
12+
13+
This article gives examples of how to create and update Access Control Lists (ACLS).
14+
15+
## Overview of the ACL create flow
16+
17+
Creating an Access Control List (ACL) associated with a Network-to-Network Interconnect (NNI) involves these steps:
18+
19+
- Create a Network Fabric resource and add an NNI child resource to it.
20+
21+
- Create ingress and egress ACL resources using the `az networkfabric acl create` command. You can provide match configurations and the default action for the ACL. You can also provide dynamic match configurations either inline, or in a file stored in your Azure storage account blob container.
22+
23+
- Update the NNI resource with the ingress and egress ACL IDs using the `az networkfabric nni update` command. You need to provide valid ACL resource IDs in the `--ingress-acl-id` and `--egress-acl-id` parameters.
24+
25+
- Provision the Network Fabric resource using the `az networkfabric fabric provision` command. This generates the base configuration and the dynamic match configuration for the ACLs and sends them to the devices.
26+
27+
## Overview of the ACL update flow
28+
29+
- Create ingress and egress ACL resources using `az networkfabric acl create` as described in the previous section.
30+
31+
- Update the ingress or egress ACL using the `az networkfabric acl update` command.
32+
33+
- Verify the configuration state of the ACL is `accepted`.
34+
35+
- Verify the configuration state of the fabric is `accepted`.
36+
37+
- Execute Fabric Commit to update the ACL.
38+
39+
## Example commands
40+
41+
### Access Control list on a Network-to-Network Interconnect
42+
43+
This example shows you how to create an NNI with two ACLs - one for ingress and one for egress.
44+
45+
The ACLs must be applied before provisioning the Network Fabric. This limitation is temporary and will be removed in future release. The ingress and egress ACLs are created before the NNI resource and referenced when the NNI is created, which also triggers the creation of the ACLs. This configuration must be done before provisioning the network fabric.
46+
47+
#### Create ingress ACL: example command
48+
49+
```azurecli
50+
az networkfabric acl create \
51+
--resource-group "example-rg"
52+
--location "eastus2euap" \
53+
--resource-name "example-Ipv4ingressACL" \
54+
--configuration-type "Inline" \
55+
--default-action "Permit" \
56+
--dynamic-match-configurations "[{ipGroups:[{name:'example-ipGroup',ipAddressType:IPv4,ipPrefixes:['10.20.3.1/20']}],vlanGroups:[{name:'example-vlanGroup',vlans:['20-30']}],portGroups:[{name:'example-portGroup',ports:['100-200']}]}]" \
57+
--match-configurations "[{matchConfigurationName:'example-match',sequenceNumber:123,ipAddressType:IPv4,matchConditions:[{etherTypes:['0x1'],fragments:['0xff00-0xffff'],ipLengths:['4094-9214'],ttlValues:[23],dscpMarkings:[32],portCondition:{flags:[established],portType:SourcePort,layer4Protocol:TCP,ports:['1-20']},protocolTypes:[TCP],vlanMatchCondition:{vlans:['20-30'],innerVlans:[30]},ipCondition:{type:SourceIP,prefixType:Prefix,ipPrefixValues:['10.20.20.20/12']}}],actions:[{type:Count,counterName:'example-counter'}]}]"
58+
```
59+
60+
#### Create egress ACL: example command
61+
62+
```azurecli
63+
az networkfabric acl create \
64+
--resource-group "example-rg" \
65+
--location "eastus2euap" \
66+
--resource-name "example-Ipv4egressACL" \
67+
--configuration-type "File" \
68+
--acls-url "https://ACL-Storage-URL" \
69+
--default-action "Permit" \
70+
--dynamic-match-configurations "[{ipGroups:[{name:'example-ipGroup',ipAddressType:IPv4,ipPrefixes:['10.20.3.1/20']}],vlanGroups:[{name:'example-vlanGroup',vlans:['20-30']}],portGroups:[{name:'example-portGroup',ports:['100-200']}]}]"
71+
```
72+
73+
### Access Control List on an isolation domain external network
74+
75+
Use the `az networkfabric acl create` command to create ingress and egress ACLs for the external network. In the example, we specify the resource group, name, location, network fabric ID, external network ID, and other parameters. You can also specify the match conditions and actions for the ACL rules using the `--match` and `--action` parameters.
76+
77+
This command creates an ingress ACL named `acl-ingress` that allows ICMP traffic from any source to the external network:
78+
79+
```azurecli
80+
az networkfabric acl create \
81+
--resource-group myResourceGroup \
82+
--name acl-ingress \
83+
--location eastus \
84+
--network-fabric-id /subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/myResourceGroup/providers/Microsoft.NetworkFabric/networkFabrics/myNetworkFabric \
85+
--external-network-id /subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/myResourceGroup/providers/Microsoft.NetworkFabric/externalNetworks/ext-net \
86+
--match "ip protocol icmp" \
87+
--action allow
88+
```
89+
90+
Use the `az networkfabric externalnetwork update` command to update the external network with the resource group, name, and network fabric ID. You also need to specify the ingress and egress ACL IDs using the `--ingress-acl-id` and `--egress-acl-id` parameters. For example, the following command updates the external network named `ext-net` to reference the ingress ACL named `acl-ingress`:
91+
92+
```azurecli
93+
az networkfabric externalnetwork update \
94+
--resource-group myResourceGroup \
95+
--name ext-net \
96+
--network-fabric-id /subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/myResourceGroup/providers/Microsoft.NetworkFabric/networkFabrics/myNetworkFabric \
97+
--ingress-acl-id /subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/myResourceGroup/providers/Microsoft.NetworkFabric/acls/acl-ingress
98+
```
99+
100+
### More example scenarios and commands
101+
102+
To create an egress ACL for an NNI that denies all traffic except for HTTP and HTTPS, you can use this command:
103+
104+
```azurecli
105+
az networkfabric acl create \
106+
--name acl-egress \
107+
--resource-group myResourceGroup \
108+
--nni-id /subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/myResourceGroup/providers/Microsoft.NetworkFabric/networkInterfaces/myNni \
109+
--match "ip protocol tcp destination port 80 or 443" \
110+
--action allow \
111+
--default-action deny
112+
```
113+
114+
To update an existing ACL to add a new match condition and action, you can use this command:
115+
116+
```azurecli
117+
az networkfabric acl update \
118+
--name acl-ingress \
119+
--resource-group myResourceGroup \
120+
--match "ip protocol icmp" \
121+
--action allow \
122+
--append-match-configurations
123+
```
124+
125+
To list all the ACLs in a resource group, you can use this command:
126+
127+
```azurecli
128+
az networkfabric acl list --resource-group myResourceGroup
129+
```
130+
131+
To show the details of a specific ACL, you can use this command:
132+
133+
```azurecli
134+
az networkfabric acl show \
135+
--name acl-ingress \
136+
--resource-group myResourceGroup
137+
```
138+
139+
To delete an ACL, you can use this command:
140+
141+
```azurecli
142+
az networkfabric acl delete \
143+
--name acl-egress \
144+
--resource-group myResourceGroup
145+
```
146+

0 commit comments

Comments
 (0)