For AI agents: The documentation index is at https://docs.digitalocean.com/llms.txt. Markdown versions of pages use the same URL with index.html.md in place of the HTML page (for example, append index.html.md to the directory path instead of opening the HTML document).

Usage

client.firewalls.create(
    body={
        "name": "firewall",
        "droplet_ids": [...],
        "tags": {...},
        ...,
    },
)

Description

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

Parameters

id string optional read-only

Example: bb4b2611-3d72-467b-8602-280330ecd65c

A unique ID that can be used to identify and reference a firewall.

status string optional read-only

A status string indicating the current state of the firewall. This can be "waiting", "succeeded", or "failed".

One of: waiting, succeeded, failed

created_at string optional read-only

Example: 2020-05-23T21:24:00Z

A time value given in ISO8601 combined date and time format that represents when the firewall was created.

pending_changes array of objects optional read-only

Example: [{'droplet_id': 8043964, 'removing': False, 'status': 'waiting'}]

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.

Show child properties

droplet_id integer optional

Example: 8043964

removing boolean optional

Example: False

status string optional

Example: waiting

name string optional

Example: firewall

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 (-).

droplet_ids array of integers or null optional

Example: [8043964]

An array containing the IDs of the Droplets assigned to the firewall.

Requires droplet:read scope.

tags object optional

inbound_rules array of objects or null optional

Show child properties

protocol string required

The type of traffic to be allowed. This may be one of tcp, udp, or icmp.

One of: tcp, udp, icmp

ports string required

Example: 8000

The ports on which traffic will be allowed specified as a string containing a single port, a range (e.g. "8000-9000"), or "0" when all ports are open for a protocol. For ICMP rules this parameter will always return "0".

sources object required

Show child properties

addresses array of strings optional

Example: ['1.2.3.4', '18.0.0.0/8']

An array of strings containing the IPv4 addresses, IPv6 addresses, IPv4 CIDRs, and/or IPv6 CIDRs to which the firewall will allow traffic.

droplet_ids array of integers optional

Example: [8043964]

An array containing the IDs of the Droplets to which the firewall will allow traffic.

load_balancer_uids array of strings optional

Example: ['4de7ac8b-495b-4884-9a69-1050c6793cd6']

An array containing the IDs of the load balancers to which the firewall will allow traffic.

kubernetes_ids array of strings optional

Example: ['41b74c5d-9bd0-5555-5555-a57c495b81a3']

An array containing the IDs of the Kubernetes clusters to which the firewall will allow traffic.

tags object optional

outbound_rules array of objects or null optional

Show child properties

protocol string required

The type of traffic to be allowed. This may be one of tcp, udp, or icmp.

One of: tcp, udp, icmp

ports string required

Example: 8000

The ports on which traffic will be allowed specified as a string containing a single port, a range (e.g. "8000-9000"), or "0" when all ports are open for a protocol. For ICMP rules this parameter will always return "0".

destinations object required

Show child properties

addresses array of strings optional

Example: ['1.2.3.4', '18.0.0.0/8']

An array of strings containing the IPv4 addresses, IPv6 addresses, IPv4 CIDRs, and/or IPv6 CIDRs to which the firewall will allow traffic.

droplet_ids array of integers optional

Example: [8043964]

An array containing the IDs of the Droplets to which the firewall will allow traffic.

load_balancer_uids array of strings optional

Example: ['4de7ac8b-495b-4884-9a69-1050c6793cd6']

An array containing the IDs of the load balancers to which the firewall will allow traffic.

kubernetes_ids array of strings optional

Example: ['41b74c5d-9bd0-5555-5555-a57c495b81a3']

An array containing the IDs of the Kubernetes clusters to which the firewall will allow traffic.

tags object optional

Request Sample

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

req = {
  "name": "firewall",
  "inbound_rules": [
    {
      "protocol": "tcp",
      "ports": "80",
      "sources": {
        "load_balancer_uids": [
          "4de7ac8b-495b-4884-9a69-1050c6793cd6"
        ]
      }
    },
    {
      "protocol": "tcp",
      "ports": "22",
      "sources": {
        "tags": [
          "gateway"
        ],
        "addresses": [
          "18.0.0.0/8"
        ]
      }
    }
  ],
  "outbound_rules": [
    {
      "protocol": "tcp",
      "ports": "80",
      "destinations": {
        "addresses": [
          "0.0.0.0/0",
          "::/0"
        ]
      }
    }
  ],
  "droplet_ids": [
    8043964
  ]
}

resp = client.firewalls.create(body=req)

Response Example

{
  "firewall": {
    "id": "bb4b2611-3d72-467b-8602-280330ecd65c",
    "name": "firewall",
    "status": "waiting",
    "inbound_rules": [
      {
        "protocol": "tcp",
        "ports": "80",
        "sources": {
          "load_balancer_uids": [
            "4de7ac8b-495b-4884-9a69-1050c6793cd6"
          ]
        }
      },
      {
        "protocol": "tcp",
        "ports": "22",
        "sources": {
          "tags": [
            "gateway"
          ],
          "addresses": [
            "18.0.0.0/8"
          ]
        }
      }
    ],
    "outbound_rules": [
      {
        "protocol": "tcp",
        "ports": "80",
        "destinations": {
          "addresses": [
            "0.0.0.0/0",
            "::/0"
          ]
        }
      }
    ],
    "created_at": "2017-05-23T21:24:00Z",
    "droplet_ids": [
      8043964
    ],
    "tags": [],
    "pending_changes": [
      {
        "droplet_id": 8043964,
        "removing": false,
        "status": "waiting"
      }
    ]
  }
}

More Information

See /v2/firewalls in the API reference for additional detail on responses, headers, parameters, and more.