more detailed description in API rule replace endpoint

oxidecomputer · Jul 24, 2024 · 8d69b62 · 8d69b62
1 parent d02e474
commit 8d69b62
Show file tree

Hide file tree

Showing 3 changed files with 21 additions and 11 deletions.
diff --git a/common/src/api/external/mod.rs b/common/src/api/external/mod.rs
@@ -1496,16 +1496,17 @@ pub struct VpcFirewallRulePriority(pub u16);
 /// matching ALL filters. The maximum number of each type of filter is 256.
 #[derive(Clone, Debug, PartialEq, Deserialize, Serialize, JsonSchema)]
 pub struct VpcFirewallRuleFilter {
-    /// If present, the sources (if incoming) or destinations (if outgoing)
-    /// this rule applies to.
+    /// If present, host filters match the "other end" of traffic from the
+    /// target’s perspective: for an inbound rule, they match the source of
+    /// traffic. For an outbound rule, they match the destination.
     #[schemars(length(max = 256))]
     pub hosts: Option<Vec<VpcFirewallRuleHostFilter>>,
 
     /// If present, the networking protocols this rule applies to.
     #[schemars(length(max = 256))]
     pub protocols: Option<Vec<VpcFirewallRuleProtocol>>,
 
-    /// If present, the destination ports this rule applies to.
+    /// If present, the destination ports or port ranges this rule applies to.
     #[schemars(length(max = 256))]
     pub ports: Option<Vec<L4PortRange>>,
 }
@@ -1704,7 +1705,7 @@ impl JsonSchema for L4PortRange {
                 title: Some("A range of IP ports".to_string()),
                 description: Some(
                     "An inclusive-inclusive range of IP ports. The second port \
-                    may be omitted to represent a single port"
+                    may be omitted to represent a single port."
                         .to_string(),
                 ),
                 examples: vec!["22".into(), "6667-7000".into()],

diff --git a/nexus/src/external_api/http_entrypoints.rs b/nexus/src/external_api/http_entrypoints.rs
@@ -5378,7 +5378,6 @@ async fn vpc_subnet_list_network_interfaces(
 
 // VPC Firewalls
 
-// TODO Is the number of firewall rules bounded?
 /// List firewall rules
 #[endpoint {
     method = GET,
@@ -5415,8 +5414,18 @@ async fn vpc_firewall_rules_view(
 
 /// Replace firewall rules
 ///
-/// The maximum number of rules is 1024. The maximum number of targets and each
-/// type of filter is 256.
+/// The maximum number of rules per VPC is 1024.
+///
+/// Targets are used to specify the set of instances to which a firewall rule
+/// applies. You can target instances directly by name, or specify a VPC, VPC
+/// subnet, IP, or IP subnet, which will apply the rule to traffic going to
+/// all matching instances. Targets are additive: the rule applies to instances
+/// matching ANY target. The maximum number of targets is 256.
+///
+/// Filters reduce the scope of a firewall rule. Without filters, the rule
+/// applies to all packets to the targets (or from the targets, if it's an
+/// outbound rule). With multiple filters, the rule applies only to packets
+/// matching ALL filters. The maximum number of each type of filter is 256.
 #[endpoint {
     method = PUT,
     path = "/v1/vpc-firewall-rules",

diff --git a/openapi/nexus.json b/openapi/nexus.json
@@ -8297,7 +8297,7 @@
           "vpcs"
         ],
         "summary": "Replace firewall rules",
-        "description": "The maximum number of rules is 1024. The maximum number of targets and each type of filter is 256.",
+        "description": "The maximum number of rules per VPC is 1024.\nTargets are used to specify the set of instances to which a firewall rule applies. You can target instances directly by name, or specify a VPC, VPC subnet, IP, or IP subnet, which will apply the rule to traffic going to all matching instances. Targets are additive: the rule applies to instances matching ANY target. The maximum number of targets is 256.\nFilters reduce the scope of a firewall rule. Without filters, the rule applies to all packets to the targets (or from the targets, if it's an outbound rule). With multiple filters, the rule applies only to packets matching ALL filters. The maximum number of each type of filter is 256.",
         "operationId": "vpc_firewall_rules_update",
         "parameters": [
           {
@@ -16027,7 +16027,7 @@
       "L4PortRange": {
         "example": "22",
         "title": "A range of IP ports",
-        "description": "An inclusive-inclusive range of IP ports. The second port may be omitted to represent a single port",
+        "description": "An inclusive-inclusive range of IP ports. The second port may be omitted to represent a single port.",
         "type": "string",
         "pattern": "^[0-9]{1,5}(-[0-9]{1,5})?$",
         "minLength": 1,
@@ -20444,7 +20444,7 @@
         "properties": {
           "hosts": {
             "nullable": true,
-            "description": "If present, the sources (if incoming) or destinations (if outgoing) this rule applies to.",
+            "description": "If present, host filters match the \"other end\" of traffic from the target’s perspective: for an inbound rule, they match the source of traffic. For an outbound rule, they match the destination.",
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/VpcFirewallRuleHostFilter"
@@ -20453,7 +20453,7 @@
           },
           "ports": {
             "nullable": true,
-            "description": "If present, the destination ports this rule applies to.",
+            "description": "If present, the destination ports or port ranges this rule applies to.",
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/L4PortRange"