From 568b566fb3615179fef63ffb4e9bee64bf8a6ff7 Mon Sep 17 00:00:00 2001 From: Dan Brian Date: Thu, 28 Dec 2023 07:21:48 -0800 Subject: [PATCH] Docs audit: Firewalls (#1480) * Clarifies doc strings for Cloud Firewall commands * further clarifications and better formatting * further clarifications * corrects firewall update and create command doc strings and examples --------- Co-authored-by: danaelhe <42972711+danaelhe@users.noreply.github.com> --- commands/firewalls.go | 80 +++++++++++++++++++++++++++---------------- 1 file changed, 51 insertions(+), 29 deletions(-) diff --git a/commands/firewalls.go b/commands/firewalls.go index 25f7ef44e..4478034e7 100644 --- a/commands/firewalls.go +++ b/commands/firewalls.go @@ -35,7 +35,9 @@ func Firewall() *Command { Short: "Display commands to manage cloud firewalls", Long: `The sub-commands of ` + "`" + `doctl compute firewall` + "`" + ` manage DigitalOcean cloud firewalls. -Cloud firewalls provide the ability to restrict network access to and from a Droplet, allowing you to define which ports accept inbound or outbound connections. With these commands, you can list, create, or delete Cloud firewalls, as well as modify access rules. +Cloud firewalls allow you to restrict network access to and from a Droplet by defining which ports accept inbound or outbound connections. With these commands, you can list, create, or delete Cloud firewalls, as well as modify access rules. + +Note: Cloud firewalls are not internal Droplet firewalls on Droplets, such as UFW or FirewallD. A firewall's ` + "`" + `inbound_rules` + "`" + ` and ` + "`" + `outbound_rules` + "`" + ` attributes contain arrays of objects as their values. These objects contain the standard attributes of their associated types, which can be found below. @@ -44,64 +46,84 @@ Inbound access rules specify the protocol (TCP, UDP, or ICMP), ports, and source } fwDetail := ` - - The firewall's ID - - The firewall's name - - The status of the firewall. This can be ` + "`" + `waiting` + "`" + `, ` + "`" + `succeeded` + "`" + `, or ` + "`" + `failed` + "`" + `. - - The firewall's creation date, in ISO8601 combined date and time format. - - Any pending changes to the firewall. These can be ` + "`" + `droplet_id` + "`" + `, ` + "`" + `removing` + "`" + `, and ` + "`" + `status` + "`" + `. +- The firewall's UUID +- The firewall's name +- The status of the firewall. Possible values: ` + "`" + `waiting` + "`" + `, ` + "`" + `succeeded` + "`" + `, ` + "`" + `failed` + "`" + `. +- The firewall's creation date, in ISO8601 combined date and time format. +- Any pending changes to the firewall. Possible values:` + "`" + `droplet_id` + "`" + `, ` + "`" + `removing` + "`" + `, ` + "`" + `status` + "`" + `. When empty, all changes have been successfully applied. - - The inbound rules for the firewall. - - The outbound rules for the firewall. - - The IDs of Droplets assigned to the firewall. - - The tags assigned to the firewall. +- The inbound rules for the firewall +- The outbound rules for the firewall +- The IDs of Droplets assigned to the firewall +- The tags assigned to the firewall ` - inboundRulesTxt := "A comma-separated key-value list that defines an inbound rule, e.g.: `protocol:tcp,ports:22,droplet_id:123`. Use a quoted string of space-separated values for multiple rules." - outboundRulesTxt := "A comma-separate key-value list the defines an outbound rule, e.g.: `protocol:tcp,ports:22,address:0.0.0.0/0`. Use a quoted string of space-separated values for multiple rules." - dropletIDRulesTxt := "A comma-separated list of Droplet IDs to place behind the cloud firewall, e.g.: `123,456`" - tagNameRulesTxt := "A comma-separated list of tag names to apply to the cloud firewall, e.g.: `frontend,backend`" + inboundRulesTxt := `A comma-separated key-value list that defines an inbound rule. The rule must define a communication protocol, a port number, and a traffic source location, such as a Droplet ID, IP address, or a tag. For example, the following rule defines that resources can only receive TCP traffic on port 22 from addresses in the specified CIDR: ` + "`" + `protocol:tcp,ports:22,address:192.0.2.0/24` + "`" + `. + +Available source keys are: ` + "`" + `address` + "`" + `, ` + "`" + `droplet_id` + "`" + `, ` + "`" + `load_balancer_uid` + "`" + `, ` + "`" + `kubernetes_id` + "`" + `, and ` + "`" + `tag` + "`" + `. + +Use a quoted string of space-separated values for multiple rules.` + outboundRulesTxt := `A comma-separate key-value list that defines an outbound rule. The rule must define a communication protocol, a port number, and a destination location, such as a Droplet ID, IP address, or a tag. For example, the following rule defines that the firewall only allows traffic to be sent to port 22 of any IPv4 address on the internet: ` + "`" + `protocol:tcp,ports:22,address:0.0.0.0/0` + "`" + `. + +Available destination keys are: ` + "`" + `address` + "`" + `, ` + "`" + `droplet_id` + "`" + `, ` + "`" + `load_balancer_uid` + "`" + `, ` + "`" + `kubernetes_id` + "`" + `, and ` + "`" + `tag` + "`" + `. + +Use a quoted string of space-separated values for multiple rules.` + dropletIDRulesTxt := "A comma-separated list of Droplet IDs to place behind the cloud firewall, for example: `386734086,391669331`" + tagNameRulesTxt := "A comma-separated list of tag names to apply to the cloud firewall, for example: `frontend,backend`" - CmdBuilder(cmd, RunFirewallGet, "get ", "Retrieve information about a cloud firewall", `Use this command to get information about an existing cloud firewall, including:`+fwDetail, Writer, aliasOpt("g"), displayerType(&displayers.Firewall{})) + cmdFirewallGet := CmdBuilder(cmd, RunFirewallGet, "get ", "Retrieve information about a cloud firewall", `Retrieves information about an existing cloud firewall, including:`+fwDetail, Writer, aliasOpt("g"), displayerType(&displayers.Firewall{})) + cmdFirewallGet.Example = `The following example retrieves information about the cloud firewall with the ID ` + "`" + `f81d4fae-7dec-11d0-a765-00a0c91e6bf6` + "`" + `: doctl compute firewall get f81d4fae-7dec-11d0-a765-00a0c91e6bf6` - cmdFirewallCreate := CmdBuilder(cmd, RunFirewallCreate, "create", "Create a new cloud firewall", `Use this command to create a cloud firewall. This command must contain at least one inbound or outbound access rule.`, Writer, aliasOpt("c"), displayerType(&displayers.Firewall{})) - AddStringFlag(cmdFirewallCreate, doctl.ArgFirewallName, "", "", "Firewall name", requiredOpt()) + cmdFirewallCreate := CmdBuilder(cmd, RunFirewallCreate, "create", "Create a new cloud firewall", `Creates a cloud firewall. This command must contain at least one inbound or outbound access rule.`, Writer, aliasOpt("c"), displayerType(&displayers.Firewall{})) + AddStringFlag(cmdFirewallCreate, doctl.ArgFirewallName, "", "", "The firewall's name", requiredOpt()) AddStringFlag(cmdFirewallCreate, doctl.ArgInboundRules, "", "", inboundRulesTxt) AddStringFlag(cmdFirewallCreate, doctl.ArgOutboundRules, "", "", outboundRulesTxt) AddStringSliceFlag(cmdFirewallCreate, doctl.ArgDropletIDs, "", []string{}, dropletIDRulesTxt) AddStringSliceFlag(cmdFirewallCreate, doctl.ArgTagNames, "", []string{}, tagNameRulesTxt) + cmdFirewallCreate.Example = `The following example creates a cloud firewall named ` + "`" + `example-firewall` + "`" + ` that contains an inbound rule and an outbound rule and applies them to the specified Droplet: doctl compute firewall create --name "example-firewall" --inbound-rules "protocol:tcp,ports:22,droplet_id:386734086" --outbound-rules "protocol:tcp,ports:22,address:0.0.0.0/0" --droplet-ids "386734086,391669331"` - cmdFirewallUpdate := CmdBuilder(cmd, RunFirewallUpdate, "update ", "Update a cloud firewall's configuration", `Use this command to update the configuration of an existing cloud firewall. The request should contain a full representation of the Firewall, including existing attributes. Note: Any attributes that are not provided will be reset to their default values.`, Writer, aliasOpt("u"), displayerType(&displayers.Firewall{})) - AddStringFlag(cmdFirewallUpdate, doctl.ArgFirewallName, "", "", "Firewall name", requiredOpt()) + cmdFirewallUpdate := CmdBuilder(cmd, RunFirewallUpdate, "update ", "Update a cloud firewall's configuration", `Updates the configuration of an existing cloud firewall. The request should contain a full representation of the firewall, including existing attributes. Any attributes that are not provided are reset to their default values.`, Writer, aliasOpt("u"), displayerType(&displayers.Firewall{})) + AddStringFlag(cmdFirewallUpdate, doctl.ArgFirewallName, "", "", "The firewall's name", requiredOpt()) AddStringFlag(cmdFirewallUpdate, doctl.ArgInboundRules, "", "", inboundRulesTxt) AddStringFlag(cmdFirewallUpdate, doctl.ArgOutboundRules, "", "", outboundRulesTxt) AddStringSliceFlag(cmdFirewallUpdate, doctl.ArgDropletIDs, "", []string{}, dropletIDRulesTxt) AddStringSliceFlag(cmdFirewallUpdate, doctl.ArgTagNames, "", []string{}, tagNameRulesTxt) + cmdFirewallUpdate.Example = `The following example updates a cloud firewall named ` + "`" + `example-firewall` + "`" + ` that contains an inbound rule and an outbound rule and applies them to the specified Droplet: doctl compute firewall update f81d4fae-7dec-11d0-a765-00a0c91e6bf6 --name "example-firewall" --inbound-rules "protocol:tcp,ports:22,droplet_id:386734086" --outbound-rules "protocol:tcp,ports:22,address:0.0.0.0/0" --droplet-ids "386734086,391669331"` - CmdBuilder(cmd, RunFirewallList, "list", "List the cloud firewalls on your account", `Use this command to retrieve a list of cloud firewalls.`, Writer, aliasOpt("ls"), displayerType(&displayers.Firewall{})) + cmdFirewallList := CmdBuilder(cmd, RunFirewallList, "list", "List the cloud firewalls on your account", `Retrieves a list of cloud firewalls on your account.`, Writer, aliasOpt("ls"), displayerType(&displayers.Firewall{})) + cmdFirewallList.Example = `The following example lists all cloud firewalls on your account and uses the ` + "`" + `--format` + "`" + ` flag to return only the ID, name and inbound rules for each firewall: doctl compute firewall list --format ID,Name,InboundRules` - CmdBuilder(cmd, RunFirewallListByDroplet, "list-by-droplet ", "List firewalls by Droplet", `Use this command to list cloud firewalls by the ID of a Droplet assigned to the firewall.`, Writer, displayerType(&displayers.Firewall{})) + cmdirewallListByDroplet := CmdBuilder(cmd, RunFirewallListByDroplet, "list-by-droplet ", "List firewalls by Droplet", `Lists the cloud firewalls assigned to a Droplet.`, Writer, displayerType(&displayers.Firewall{})) + cmdirewallListByDroplet.Example = `The following example lists all cloud firewalls assigned to the Droplet with the ID ` + "`" + `386734086` + "`" + `: doctl compute firewall list-by-droplet 386734086` - cmdRunRecordDelete := CmdBuilder(cmd, RunFirewallDelete, "delete ...", "Permanently delete a cloud firewall", `Use this command to permanently delete a cloud firewall. This is irreversible, but does not delete any Droplets assigned to the cloud firewall.`, Writer, aliasOpt("d", "rm")) - AddBoolFlag(cmdRunRecordDelete, doctl.ArgForce, doctl.ArgShortForce, false, "Delete firewall without confirmation prompt") + cmdRunRecordDelete := CmdBuilder(cmd, RunFirewallDelete, "delete ...", "Permanently delete a cloud firewall", `Permanently deletes a cloud firewall. This is irreversible, but does not delete any Droplets assigned to the cloud firewall.`, Writer, aliasOpt("d", "rm")) + AddBoolFlag(cmdRunRecordDelete, doctl.ArgForce, doctl.ArgShortForce, false, "Deletes the firewall without a confirmation prompt") + cmdRunRecordDelete.Example = `The following example deletes a cloud firewall with the ID ` + "`" + `f81d4fae-7dec-11d0-a765-00a0c91e6bf6` + "`" + `: doctl compute firewall delete f81d4fae-7dec-11d0-a765-00a0c91e6bf6` - cmdAddDroplets := CmdBuilder(cmd, RunFirewallAddDroplets, "add-droplets ", "Add Droplets to a cloud firewall", `Use this command to add Droplets to the cloud firewall.`, Writer) + cmdAddDroplets := CmdBuilder(cmd, RunFirewallAddDroplets, "add-droplets ", "Add Droplets to a cloud firewall", `Assigns Droplets to a cloud firewall on your account.`, Writer) AddStringSliceFlag(cmdAddDroplets, doctl.ArgDropletIDs, "", []string{}, dropletIDRulesTxt) + cmdAddDroplets.Example = `The following example assigns two Droplets to the cloud firewall with the ID ` + "`" + `f81d4fae-7dec-11d0-a765-00a0c91e6bf6` + "`" + `: doctl compute firewall add-droplets f81d4fae-7dec-11d0-a765-00a0c91e6bf6 --droplet-ids "386734086,391669331"` - cmdRemoveDroplets := CmdBuilder(cmd, RunFirewallRemoveDroplets, "remove-droplets ", "Remove Droplets from a cloud firewall", `Use this command to remove Droplets from a cloud firewall.`, Writer) + cmdRemoveDroplets := CmdBuilder(cmd, RunFirewallRemoveDroplets, "remove-droplets ", "Remove Droplets from a cloud firewall", `Removes Droplets from a cloud firewall.`, Writer) AddStringSliceFlag(cmdRemoveDroplets, doctl.ArgDropletIDs, "", []string{}, dropletIDRulesTxt) + cmdRemoveDroplets.Example = `The following example removes two Droplets from a cloud firewall with the ID ` + "`" + `f81d4fae-7dec-11d0-a765-00a0c91e6bf6` + "`" + `: doctl compute firewall remove-droplets f81d4fae-7dec-11d0-a765-00a0c91e6bf6 --droplet-ids "386734086,391669331"` - cmdAddTags := CmdBuilder(cmd, RunFirewallAddTags, "add-tags ", "Add tags to a cloud firewall", `Use this command to add tags to a cloud firewall. This adds all assets using that tag to the firewall`, Writer) + cmdAddTags := CmdBuilder(cmd, RunFirewallAddTags, "add-tags ", "Add tags to a cloud firewall", `Add tags to a cloud firewall. This adds all assets using that tag to the firewall.`, Writer) AddStringSliceFlag(cmdAddTags, doctl.ArgTagNames, "", []string{}, tagNameRulesTxt) + cmdAddTags.Example = `The following example adds two tags to a cloud firewall with the ID ` + "`" + `f81d4fae-7dec-11d0-a765-00a0c91e6bf6` + "`" + `: doctl compute firewall add-tags f81d4fae-7dec-11d0-a765-00a0c91e6bf6 --tag-names "frontend,backend"` - cmdRemoveTags := CmdBuilder(cmd, RunFirewallRemoveTags, "remove-tags ", "Remove tags from a cloud firewall", `Use this command to remove tags from a cloud firewall. This removes all assets using that tag from the firewall.`, Writer) + cmdRemoveTags := CmdBuilder(cmd, RunFirewallRemoveTags, "remove-tags ", "Remove tags from a cloud firewall", `Removes tags from a cloud firewall. This removes all assets using that tag from the firewall.`, Writer) AddStringSliceFlag(cmdRemoveTags, doctl.ArgTagNames, "", []string{}, tagNameRulesTxt) + cmdRemoveTags.Example = `The following example removes two tags from a cloud firewall with the ID ` + "`" + `f81d4fae-7dec-11d0-a765-00a0c91e6bf6` + "`" + `: doctl compute firewall remove-tags f81d4fae-7dec-11d0-a765-00a0c91e6bf6 --tag-names "frontend,backend"` - cmdAddRules := CmdBuilder(cmd, RunFirewallAddRules, "add-rules ", "Add inbound or outbound rules to a cloud firewall", `Use this command to add inbound or outbound rules to a cloud firewall.`, Writer) + cmdAddRules := CmdBuilder(cmd, RunFirewallAddRules, "add-rules ", "Add inbound or outbound rules to a cloud firewall", `Add inbound or outbound rules to a cloud firewall.`, Writer) AddStringFlag(cmdAddRules, doctl.ArgInboundRules, "", "", inboundRulesTxt) AddStringFlag(cmdAddRules, doctl.ArgOutboundRules, "", "", outboundRulesTxt) + cmdAddRules.Example = `The following example adds an inbound rule and an outbound rule to a cloud firewall with the ID ` + "`" + `f81d4fae-7dec-11d0-a765-00a0c91e6bf6` + "`" + `: doctl compute firewall add-rules f81d4fae-7dec-11d0-a765-00a0c91e6bf6 --inbound-rules "protocol:tcp,ports:22,droplet_id:386734086" --outbound-rules "protocol:tcp,ports:22,address:0.0.0.0/0"` - cmdRemoveRules := CmdBuilder(cmd, RunFirewallRemoveRules, "remove-rules ", "Remove inbound or outbound rules from a cloud firewall", `Use this command to remove inbound or outbound rules from a cloud firewall.`, Writer) + cmdRemoveRules := CmdBuilder(cmd, RunFirewallRemoveRules, "remove-rules ", "Remove inbound or outbound rules from a cloud firewall", `Remove inbound or outbound rules from a cloud firewall.`, Writer) AddStringFlag(cmdRemoveRules, doctl.ArgInboundRules, "", "", inboundRulesTxt) AddStringFlag(cmdRemoveRules, doctl.ArgOutboundRules, "", "", outboundRulesTxt) + cmdRemoveRules.Example = `The following example removes an inbound rule and an outbound rule from a cloud firewall with the ID ` + "`" + `f81d4fae-7dec-11d0-a765-00a0c91e6bf6` + "`" + `: doctl compute firewall remove-rules f81d4fae-7dec-11d0-a765-00a0c91e6bf6 --inbound-rules "protocol:tcp,ports:22,droplet_id:386734086" --outbound-rules "protocol:tcp,ports:22,address:0.0.0.0/0"` return cmd }