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.
Create security groups
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.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 areicmp
,tcp
,udp
andall
.direction
String Required - The direction of the rule. Possible values areingress
oregress
.port_range_min
Integer Required - The port_range_min of the rule (e.g.8080
). Optional foricmp
protocol.port_range_max
Integer Required - The port_range_min of the rule (e.g.8085
). Optional foricmp
protocol.
{"name":"<security group name>","description":"<security group description>","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"}]}
Body response
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:
id
String - A unique identifier for each security group. This is automatically generated.name
String - The human-readable name set for the security group.description
String - The human-readable description set for the security group.status
String - The security group status. Possible values areenqueued
,creating
,created
,updating
,deleting
anderror
.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.
{"security_group":{"id":"<security group id>","name":"<security group name>","description":"<security group description>","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 groups
To update a new 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 areicmp
,tcp
,udp
andall
.direction
String Required - The direction of the rule. Possible values areingress
oregress
.port_range_min
Integer Required - The port_range_min of the rule (e.g.8080
). Optional foricmp
protocol andnull
for all ports.port_range_max
Integer Required - The port_range_min of the rule (e.g.8085
). Optional foricmp
protocol andnull
for all ports.
{"name":"<security group name>","description":"<security group description>","rules":[{"protocol":"icmp","port_range_min":null,"port_range_max":null,"direction":"ingress"}]}
Body response
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:
id
String - A unique identifier for each security group. This is automatically generated.name
String - The human-readable name set for the security group.description
String - The human-readable description set for the security group.status
String - The security group status. Possible values areenqueued
,creating
,created
,updating
,deleting
anderror
.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.
{"security_group":{"id":"<security group id>","name":"<security group name>","description":"<security group description>","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:
id
String - A unique identifier that can be used to reference a specific image.name
String - The display name for security group.description
String - The descripton name for a security group.rules
Array - The security group rules.created_at
String - A time value given in ISO8601 combined date and time format that represents when the image was created.
{"security_groups":[{"id":"string","name":"string","description":"string","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-group/{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:
id
String - A unique identifier that can be used to reference a specific image.name
String - The display name for security group.description
String - The descripton name for a security group.rules
Array - The security group rules.created_at
String - A time value given in ISO8601 combined date and time format that represents when the image was created.
{"security_group":{"id":"string","name":"string","description":"string","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 portscurl --request POST \-H 'X-Auth-Token: <TOKEN>' -H 'Content-Type: application/json' \'https://api.genesiscloud.com/compute/v1/security_groups' \--data-raw '{"name":"name","description":"description","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 new security groupcurl --request POST \-H 'X-Auth-Token: <TOKEN>' -H 'Content-Type: application/json' \'https://api.genesiscloud.com/compute/v1/security_groups' \--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 groupscurl -H 'X-Auth-Token: <TOKEN>' -H 'Content-Type: application/json' \'https://api.genesiscloud.com/compute/v1/security-groups'
# Get security group by idcurl -H 'X-Auth-Token: <TOKEN>' \'https://api.genesiscloud.com/compute/v1/security-groups/<security_group_id>'
# Delete a security group by idcurl --request DELETE \-H 'X-Auth-Token: <TOKEN>' \'https://api.genesiscloud.com/compute/v1/security_group/<security_group_id>'