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. NORD-NO-KRS-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.

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": "NORD-NO-KRS-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": "NORD-NO-KRS-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": "NORD-NO-KRS-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": "NORD-NO-KRS-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": "NORD-NO-KRS-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": "NORD-NO-KRS-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>"