Skip to main content

Security Groups

A security group is a set of firewall rules on a set of instances. Security groups enable to create rules that either drop or allow incoming traffic from certain ports of your instances.

Security Group Schema​

  • id String - A unique identifier for each security group. This is automatically generated.
  • name String - The human-readable name for the security group.
  • description String - The human-readable description for the security group.
  • region String - The identifier for the region this security group exists in (eg. ARC-IS-HAF-1).
  • status String - The security group status. Possible values are creating, created and deleting.
  • rules Array - The security group rules.
  • created_at String - A time value given in ISO8601 combined date and time format that represents when the security group was created.
Info for legacy projects and accounts

For legacy projects and accounts there are additional statuses updating and error.

Create Security Group​

To create a new security group, send a request to:

POST /compute/v1/security-groups (HTTP 201 - Created)

The attribute values that must be set to successfully create a security group are:

Body parameters

  • name String Required - The human-readable name set for the security group. Please Note: default and standard are not allowed names (reserved words).
  • description String Optional - The human-readable description set for the security group.
  • region String Required - The identifier for the region in which this security group should be created in, see Regions.
  • rules Array Required - The list of rules of the security group.

Rule object​

  • protocol String Required - The protocol of the rule. Possible values are icmp, tcp, udp and all.
  • direction String Required - The direction of the rule. Possible values are ingress or egress.
  • port_range_min Integer Required - The port_range_min of the rule (e.g. 8080). Optional for icmp protocol.
  • port_range_max Integer Required - The port_range_min of the rule (e.g. 8085). Optional for icmp protocol.
{
  "name": "<security group name>",
  "description": "<security group description>",
  "region": "ARC-IS-HAF-1",
  "rules": [
    {
      "protocol": "icmp",
      "port_range_min": null,
      "port_range_max": null,
      "direction": "ingress"
    },
    {
      "protocol": "tcp",
      "port_range_min": 22,
      "port_range_max": 22,
      "direction": "ingress"
    },
    {
      "protocol": "tcp",
      "port_range_min": 8080,
      "port_range_max": 8085,
      "direction": "ingress"
    },
    {
      "protocol": "all",
      "port_range_min": null,
      "port_range_max": null,
      "direction": "egress"
    }
  ]
}

Response body

The security group will be created using the provided information. The response body will contain a JSON object with standard attributes for your new security group, see Security Group Schema:

{
  "security_group": {
    "id": "<security group id>",
    "name": "<security group name>",
    "description": "<security group description>",
    "region": "ARC-IS-HAF-1",
    "status": "creating",
    "rules": [
      {
        "protocol": "icmp",
        "port_range_min": null,
        "port_range_max": null,
        "direction": "ingress"
      },
      {
        "protocol": "tcp",
        "port_range_min": 22,
        "port_range_max": 22,
        "direction": "ingress"
      },
      {
        "protocol": "tcp",
        "port_range_min": 8080,
        "port_range_max": 8085,
        "direction": "ingress"
      },
      {
        "protocol": "all",
        "port_range_min": null,
        "port_range_max": null,
        "direction": "egress"
      }
    ],
    "created_at": "2020-03-20T15:17:42.375Z"
  }
}

Update Security Group​

To update a security group, send a request to:

PUT /compute/v1/security-groups/<security_group_id> (HTTP 200)

The attribute values that must be set to successfully create a security group are:

Body parameters

  • name String Required - The human-readable name set for the security group.
  • description String Optional - The human-readable description set for the security group.
  • rules Array Required - The list of rules of the security group.

Rule object​

  • protocol String Required - The protocol of the rule. Possible values are icmp, tcp, udp and all.
  • direction String Required - The direction of the rule. Possible values are ingress or egress.
  • port_range_min Integer Required - The port_range_min of the rule (e.g. 8080). Optional for icmp protocol and null for all ports.
  • port_range_max Integer Required - The port_range_min of the rule (e.g. 8085). Optional for icmp protocol and null for all ports.
{
  "name": "<security group name>",
  "description": "<security group description>",
  "rules": [
    {
      "protocol": "icmp",
      "port_range_min": null,
      "port_range_max": null,
      "direction": "ingress"
    }
  ]
}

Response body

The security group will be updated using the provided information. The response body will contain a JSON object with standard attributes for your new security group, see Security Group Schema:

{
  "security_group": {
    "id": "<security group id>",
    "name": "<security group name>",
    "description": "<security group description>",
    "region": "ARC-IS-HAF-1",
    "status": "creating",
    "rules": [
      {
        "protocol": "icmp",
        "port_range_min": null,
        "port_range_max": null,
        "direction": "ingress"
      }
    ],
    "created_at": "2020-03-20T15:17:42.375Z"
  }
}

List Security Groups​

List all security groups available in an account.

GET /compute/v1/security-groups (HTTP 200 - OK)

Query parameters

  • per_page Integer Optional - A positive integer lower than or equal to 100 to select the number of items to return (default: 50).
  • page Integer Optional - A positive integer to choose the page to return.

Response body

The response will be a JSON object with pagination details and a key called security_groups. This will be set to an array of security group objects, each of which will contain the security group object, see Security Group Schema:

{
  "security_groups": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "region": "ARC-IS-HAF-1",
      "rules": [
        {
          "protocol": "icmp",
          "port_range_min": null,
          "port_range_max": null,
          "direction": "ingress"
        },
        {
          "protocol": "tcp",
          "port_range_min": 22,
          "port_range_max": 22,
          "direction": "ingress"
        },
        {
          "protocol": "tcp",
          "port_range_min": 8080,
          "port_range_max": 8085,
          "direction": "ingress"
        },
        {
          "protocol": "all",
          "port_range_min": null,
          "port_range_max": null,
          "direction": "egress"
        }
      ],
      "created_at": "2020-03-20T15:17:42.375Z"
    }
  ],
  "total_count": 1,
  "page": 1,
  "per_page": 10
}

Get Security Group​

Get details of an security group with the given ID

GET /compute/v1/security-groups/<security_group_id> (HTTP 200 - OK)

Path parameters:

  • security_group_id String - Security group id

Response body

The response will be a JSON object that contains the security group attributes, see Security Group Schema:

{
  "security_group": {
    "id": "string",
    "name": "string",
    "description": "string",
    "region": "ARC-IS-HAF-1",
    "rules": [
      {
        "protocol": "icmp",
        "port_range_min": null,
        "port_range_max": null,
        "direction": "ingress"
      },
      {
        "protocol": "tcp",
        "port_range_min": 22,
        "port_range_max": 22,
        "direction": "ingress"
      },
      {
        "protocol": "tcp",
        "port_range_min": 8080,
        "port_range_max": 8085,
        "direction": "ingress"
      },
      {
        "protocol": "all",
        "port_range_min": null,
        "port_range_max": null,
        "direction": "egress"
      }
    ],
    "created_at": "2020-03-20T15:17:42.375Z"
  }
}

Delete a Security Group​

Delete a security group with the given ID

DELETE /compute/v1/security-groups/<security_group_id>  (HTTP 204 - No content)

Path parameters:

  • security_group_id String - security group id

Examples (cURL)​

# Create a new security group (egress all ports)
curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.genesiscloud.com/compute/v1/security-groups" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "name": "name",
    "description": "description",
    "region": "ARC-IS-HAF-1",
    "rules": [
      {
        "protocol": "icmp",
        "port_range_min": null,
        "port_range_max": null,
        "direction": "ingress"
      },
      {
        "protocol": "tcp",
        "port_range_min": 22,
        "port_range_max": 22,
        "direction": "ingress"
      },
      {
        "protocol": "tcp",
        "port_range_min": 8080,
        "port_range_max": 8085,
        "direction": "ingress"
      },
      {
        "protocol": "all",
        "port_range_min": null,
        "port_range_max": null,
        "direction": "egress"
      }
    ]
  }'
# Update a security group
curl -H "Authorization: Bearer $TOKEN" \
  -X PUT "https://api.genesiscloud.com/compute/v1/security-groups/<security_group_id>" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "name": "name",
    "description": "description",
    "rules": [
      {
        "protocol": "tcp",
        "port_range_min": 8080,
        "port_range_max": 8085,
        "direction": "ingress"
      },
      {
        "protocol": "all",
        "port_range_min": null,
        "port_range_max": null,
        "direction": "egress"
      }
    ]
  }'
# List security groups
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.genesiscloud.com/compute/v1/security-groups"
# Get security group by id
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.genesiscloud.com/compute/v1/security-groups/<security_group_id>"
# Destroy a security group
curl -H "Authorization: Bearer $TOKEN" \
  -X DELETE "https://api.genesiscloud.com/compute/v1/security-groups/<security_group_id>"