firewalls

Creates, updates, deletes, gets or lists a firewalls resource.

Overview

Name	firewalls
Type	Resource
Id	digitalocean.compute.firewalls

Fields

The following fields are returned by SELECT queries:

firewalls_get

The response will be a JSON object with a firewall key. This will be set to an object containing the standard firewall attributes.

Firewalls responses will include only the resources that you are granted to see. Ensure that your API token includes all necessary <resource>:read permissions for requested firewall.

Name	Datatype	Description
id	string	A unique ID that can be used to identify and reference a firewall. (example: bb4b2611-3d72-467b-8602-280330ecd65c)
name	string	A human-readable name for a firewall. The name must begin with an alphanumeric character. Subsequent characters must either be alphanumeric characters, a period (.), or a dash (-). (pattern: ^[a-zA-Z0-9][a-zA-Z0-9.-]+$, example: firewall)
created_at	string (date-time)	A time value given in ISO8601 combined date and time format that represents when the firewall was created. (example: 2020-05-23T21:24:00Z)
droplet_ids	array	An array containing the IDs of the Droplets assigned to the firewall. Requires droplet:read scope.
inbound_rules	array
outbound_rules	array
pending_changes	array	An array of objects each containing the fields "droplet_id", "removing", and "status". It is provided to detail exactly which Droplets are having their security policies updated. When empty, all changes have been successfully applied.
status	string	A status string indicating the current state of the firewall. This can be "waiting", "succeeded", or "failed". (example: waiting)
tags	array	A flat array of tag names as strings to be applied to the resource. Tag names must exist in order to be referenced in a request. Requires tag:create and tag:read scopes.

firewalls_list

To list all of the firewalls available on your account, send a GET request to /v2/firewalls.

Firewalls responses will include only the resources that you are granted to see. Ensure that your API token includes all necessary <resource>:read permissions for requested firewall.

Name	Datatype	Description
id	string	A unique ID that can be used to identify and reference a firewall. (example: bb4b2611-3d72-467b-8602-280330ecd65c)
name	string	A human-readable name for a firewall. The name must begin with an alphanumeric character. Subsequent characters must either be alphanumeric characters, a period (.), or a dash (-). (pattern: ^[a-zA-Z0-9][a-zA-Z0-9.-]+$, example: firewall)
created_at	string (date-time)	A time value given in ISO8601 combined date and time format that represents when the firewall was created. (example: 2020-05-23T21:24:00Z)
droplet_ids	array	An array containing the IDs of the Droplets assigned to the firewall. Requires droplet:read scope.
inbound_rules	array
outbound_rules	array
pending_changes	array	An array of objects each containing the fields "droplet_id", "removing", and "status". It is provided to detail exactly which Droplets are having their security policies updated. When empty, all changes have been successfully applied.
status	string	A status string indicating the current state of the firewall. This can be "waiting", "succeeded", or "failed". (example: waiting)
tags	array	A flat array of tag names as strings to be applied to the resource. Tag names must exist in order to be referenced in a request. Requires tag:create and tag:read scopes.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
firewalls_get	select	firewall_id		To show information about an existing firewall, send a GET request to /v2/firewalls/$FIREWALL_ID.
firewalls_list	select		per_page, page	To list all of the firewalls available on your account, send a GET request to /v2/firewalls.
firewalls_create	insert	data__name		To create a new firewall, send a POST request to /v2/firewalls. The request must contain at least one inbound or outbound access rule.
firewalls_update	replace	firewall_id, data__name		To update the configuration of an existing firewall, send a PUT request to /v2/firewalls/$FIREWALL_ID. The request should contain a full representation of the firewall including existing attributes. Note that any attributes that are not provided will be reset to their default values. You must have read access (e.g. droplet:read) to all resources attached to the firewall to successfully update the firewall.
firewalls_delete	delete	firewall_id		To delete a firewall send a DELETE request to /v2/firewalls/$FIREWALL_ID. No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.
firewalls_assign_droplets	exec	firewall_id, droplet_ids		To assign a Droplet to a firewall, send a POST request to /v2/firewalls/$FIREWALL_ID/droplets. In the body of the request, there should be a droplet_ids attribute containing a list of Droplet IDs. No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.
firewalls_delete_droplets	exec	firewall_id, droplet_ids		To remove a Droplet from a firewall, send a DELETE request to /v2/firewalls/$FIREWALL_ID/droplets. In the body of the request, there should be a droplet_ids attribute containing a list of Droplet IDs. No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
firewall_id	string (uuid)	A unique ID that can be used to identify and reference a firewall. (example: bb4b2611-3d72-467b-8602-280330ecd65c)
page	integer	Which 'page' of paginated results to return. (example: 1)
per_page	integer	Number of items returned per page (example: 2)

SELECT examples

firewalls_get

To show information about an existing firewall, send a GET request to /v2/firewalls/$FIREWALL_ID.

SELECT
id,
name,
created_at,
droplet_ids,
inbound_rules,
outbound_rules,
pending_changes,
status,
tags
FROM digitalocean.compute.firewalls
WHERE firewall_id = '{{ firewall_id }}' -- required;

firewalls_list

To list all of the firewalls available on your account, send a GET request to /v2/firewalls.

SELECT
id,
name,
created_at,
droplet_ids,
inbound_rules,
outbound_rules,
pending_changes,
status,
tags
FROM digitalocean.compute.firewalls
WHERE per_page = '{{ per_page }}'
AND page = '{{ page }}';

INSERT examples

firewalls_create

To create a new firewall, send a POST request to /v2/firewalls. The request
must contain at least one inbound or outbound access rule.

INSERT INTO digitalocean.compute.firewalls (
data__name,
data__droplet_ids,
data__tags,
data__inbound_rules,
data__outbound_rules
)
SELECT 
'{{ name }}' --required,
'{{ droplet_ids }}',
'{{ tags }}',
'{{ inbound_rules }}',
'{{ outbound_rules }}'
RETURNING
firewall
;

Manifest

# Description fields are for documentation purposes
- name: firewalls
  props:
    - name: name
      value: string
      description: >
        A human-readable name for a firewall. The name must begin with an alphanumeric character. Subsequent characters must either be alphanumeric characters, a period (.), or a dash (-).
        
    - name: droplet_ids
      value: array
      description: >
        An array containing the IDs of the Droplets assigned to the firewall. <br><br>Requires `droplet:read` scope.
        
    - name: tags
      value: array
      description: >
        A flat array of tag names as strings to be applied to the resource. Tag names must exist in order to be referenced in a request. <br><br>Requires `tag:create` and `tag:read` scopes.
        
    - name: inbound_rules
      value: array
    - name: outbound_rules
      value: array

REPLACE examples

firewalls_update

To update the configuration of an existing firewall, send a PUT request to
/v2/firewalls/$FIREWALL_ID. The request should contain a full representation
of the firewall including existing attributes. Note that any attributes that
are not provided will be reset to their default values.


You must have read access (e.g. droplet:read) to all resources attached
to the firewall to successfully update the firewall.

REPLACE digitalocean.compute.firewalls
SET 
data__name = '{{ name }}',
data__droplet_ids = '{{ droplet_ids }}',
data__tags = '{{ tags }}',
data__inbound_rules = '{{ inbound_rules }}',
data__outbound_rules = '{{ outbound_rules }}'
WHERE 
firewall_id = '{{ firewall_id }}' --required
AND data__name = '{{ name }}' --required
RETURNING
firewall;

DELETE examples

firewalls_delete

To delete a firewall send a DELETE request to /v2/firewalls/$FIREWALL_ID.

No response body will be sent back, but the response code will indicate
success. Specifically, the response code will be a 204, which means that the
action was successful with no returned body data.

DELETE FROM digitalocean.compute.firewalls
WHERE firewall_id = '{{ firewall_id }}' --required;

Lifecycle Methods

firewalls_assign_droplets

To assign a Droplet to a firewall, send a POST request to
/v2/firewalls/$FIREWALL_ID/droplets. In the body of the request, there
should be a droplet_ids attribute containing a list of Droplet IDs.

No response body will be sent back, but the response code will indicate
success. Specifically, the response code will be a 204, which means that the
action was successful with no returned body data.

EXEC digitalocean.compute.firewalls.firewalls_assign_droplets 
@firewall_id='{{ firewall_id }}' --required 
@@json=
'{
"droplet_ids": "{{ droplet_ids }}"
}';

firewalls_delete_droplets

To remove a Droplet from a firewall, send a DELETE request to
/v2/firewalls/$FIREWALL_ID/droplets. In the body of the request, there should
be a droplet_ids attribute containing a list of Droplet IDs.

No response body will be sent back, but the response code will indicate
success. Specifically, the response code will be a 204, which means that the
action was successful with no returned body data.

EXEC digitalocean.compute.firewalls.firewalls_delete_droplets 
@firewall_id='{{ firewall_id }}' --required 
@@json=
'{
"droplet_ids": "{{ droplet_ids }}"
}';