Os-security-groups
Support management of security group in OS API 1.1 or later version same as it is present in the EC2 API.
Design
| Sr No. | verb | URI | Request |
| 1 | GET | /os-security-groups | No Request body |
| 2 | GET | /os-security-groups/{id} | No Request body |
| 3 | POST | /os-security-groups | Request body |
| 4 | DELETE | /os-security-groups/{id} | No Request body |
| 5 | POST | /os-security-groups/{id}/authorize_ingress | Request body |
| 6 | POST | /os-security-groups/{id}/revoke_ingress | Request body |
| 7 | POST | /os-security-groups/detail | n/a |
API Operations
Create Security Group API
URL : http://10.2.3.150:8774/v1.1/os-security-groups
| Verb | URI |
| POST | /os-security-groups |
Normal Response Code(s): 200
Error Response Code(s): 500, unauthorized(401), badRequest(400)
This operation creates a new security group into your account.
Error Handling
| Name | Description | Error Description |
| name | Name of the security group | Security group name is mandatory |
| Security group name is an empty string | ||
| Security group name should not be greater than 255 characters | ||
| description | Description of the security group | Security group description is mandatory |
| Security group description is an empty string | ||
| Security group description should not be greater than 255 characters |
In all of the above error cases, it returns HTTP status code 400.
Request XML
<securityGroup name="test"> <description>test</description> </securityGroup>
Response XML
<securityGroup id="34" name="test" userId="admin" xmlns="http://docs.openstack.org/ext/securitygroups/api/v1.1">
<description>
test
</description>
</securityGroup>
- Note: UserId will be the project Id.
Request JSON
{
"securityGroup" :
{
"name" : "test12",
"description" : "security group description"
}
}
Response JSON
{
"securityGroup":{
"name": "test12",
"userId": "admin",
"id": 1,
"description": "security group description"
}
}
Get Security Group
URL: http://10.2.3.150:8774/v1.1/os-security-groups/<id>
| Verb | URI |
| GET | /os-security-groups/id |
Normal Response Code(s): 200
Error Response Code(s): unauthorized(401), ItemNotFound(404)
This operation returns the details of a security group bu its ID
This operation does not require a request body
Response XML
<securityGroup id="2" name="default" userId="admin" xmlns="http://docs.openstack.org/compute/api/v1.1">
<permissions>
<permission>
<toPort>
22
</toPort>
<fromPort>
22
</fromPort>
<sourceGroups/>
<protocol>
tcp
</protocol>
<ipRanges>
<ipRange>
<cidrIp>
10.2.3.0/24
</cidrIp>
</ipRange>
</ipRanges>
</permission>
<permission>
<toPort>
22
</toPort>
<fromPort>
22
</fromPort>
<sourceGroups/>
<protocol>
tcp
</protocol>
<ipRanges>
<ipRange>
<cidrIp>
10.2.3.124/24
</cidrIp>
</ipRange>
</ipRanges>
</permission>
<permission>
<toPort>
None
</toPort>
<fromPort>
None
</fromPort>
<sourceGroups>
<sourceGroup>
<userId>
admin
</userId>
<groupId>
20
</groupId>
</sourceGroup>
</sourceGroups>
<protocol>
None
</protocol>
<ipRanges/>
</permission>
</permissions>
<description>
default
</description>
</securityGroup>
Response JSON
Response JSON
{
"securityGroup":
{
"permissions":
[
{
"toPort": 22,
"fromPort": 22,
"sourceGroups": [],
"protocol": "tcp",
"ipRanges":
[
{
"cidrIp": "10.2.3.0/24"
}
]
},
{
"toPort": 22,
"fromPort": 22,
"sourceGroups": [],
"protocol": "tcp",
"ipRanges":
[
{
"cidrIp": "10.2.3.124/24"
}
]
},
{
"toPort": ,
"fromPort": ,
"sourceGroups":
[
{
"userId": "admin",
"groupId": 20
}
],
"protocol": ,
"ipRanges": []
}
],
"userId": "admin",
"id": 2,
"name": "default",
"description": "default"
}
}
List security groups
URL : http://10.2.3.150:8774/v1.1/os-security-groups
| Verb | URI |
| GET | /os-security-groups |
Normal Response Code(s): 200
Error Response Code(s): unauthorized(401)
This operation provides a list of security groups with your account. Security groups that have been deleted are not included in this list. The list of security groups doesn't support filtering in this version. The list returned is sorted based on the id, if you are a admin user then the list returned is sorted based on the userID (ProjectID) and IDs of the security groups.
This operation does not require a request body.
Response XML
<securityGroups xmlns="http://docs.openstack.org/compute/api/v1.1">
<securityGroup id="2" name="default" userId="admin">
<description>
default
</description>
</securityGroup>
<securityGroup id="20" name="test" userId="admin">
<description>
test
</description>
</securityGroup>
</securityGroups>
Response JSON
{
"securityGroups":
[
{
"userId": "admin",
"id": 2,
"name": "default",
"description": "default"
},
{
"userId": "admin",
"id": 20,
"name": "test",
"description": "test"
}
]
}
Detail security groups
URL: http://10.2.3.150:8774/v1.1/os-security-groups/detail
| Verb | URI |
| GET | /os-security-groups/detail |
Normal Response Code(s): 200
Error Response Code(s): unauthorized(401)
This operation is slightly different from "List of security groups" operation. In this operation the list is returned with more details of each security group. This operation provides a list of security groups with your account. Security groups that have been deleted are not included in this list.The list of security groups doesn't support filtering in this version. The list returned is sorted based on the id, if you are a admin user then the list returned is sorted based on the userID (ProjectID) and IDs of the security groups.
This operation does not require a request body.
Response XML
<securityGroups xmlns="http://docs.openstack.org/compute/api/v1.1">
<securityGroup id="2" name="default" userId="admin">
<permissions>
<permission>
<toPort>
22
</toPort>
<fromPort>
22
</fromPort>
<sourceGroups/>
<protocol>
tcp
</protocol>
<ipRanges>
<ipRange>
<cidrIp>
10.2.3.0/24
</cidrIp>
</ipRange>
</ipRanges>
</permission>
<permission>
<toPort>
22
</toPort>
<fromPort>
22
</fromPort>
<sourceGroups/>
<protocol>
tcp
</protocol>
<ipRanges>
<ipRange>
<cidrIp>
10.2.3.124/24
</cidrIp>
</ipRange>
</ipRanges>
</permission>
<permission>
<toPort>
None
</toPort>
<fromPort>
None
</fromPort>
<sourceGroups>
<sourceGroup>
<userId>
admin
</userId>
<groupId>
20
</groupId>
</sourceGroup>
</sourceGroups>
<protocol>
None
</protocol>
<ipRanges/>
</permission>
</permissions>
<description>
default
</description>
</securityGroup>
<securityGroup id="20" name="test" userId="admin">
<permissions/>
<description>
test
</description>
</securityGroup>
</securityGroups>
Response JSON
{
"securityGroups":
[
{
"permission":
[
{
"toPort": 22,
"fromPort": 22,
"sourceGroups": [],
"protocol": "tcp",
"ipRanges":
[
{
"cidrIp": "10.2.3.0/24"
}
]
}
],
"userId": "admin",
"id": 2,
"name": "default",
"description": "default"
},
{
"permission":
[
{
"toPort": 22,
"fromPort": 22,
"sourceGroups": [],
"protocol": "tcp",
"ipRanges":
[
{
"cidrIp": "10.2.3.0/24"
}
]
}
],
"userId": "admin",
"id": 3,
"name": "test1",
"description": "test1 description"
}
]
}
Delete Security Group
| verb | URI |
| DELETE | /os-security-groups/id |
Normal Response Code(s): 204
Error Response Code(s): unauthorized (401), itemNotFound (404)
This operation does not require a request or a response body.
Authorize Security Group Ingress
| Verb | URI |
| POST | /os-security-groups/id/authorize_ingress |
Normal Response Code(s): 202
Error Response Code(s): computeFault(500), unauthorized(401), BadRequest(400), UnprocessableEntity(422), itemNotfound(400)
This operation adds one or more ingress rules to a security group. this action gives one or more CIDR IP address ranges permission to access a security group in your account, or gives one or more other security groups permissions to access a securit group in your account. A source group can be in your own account or another.
This operation does not send a response body.
Questions
- Should there be any restrictions on the numbers of rules allowed per security group?
In amazon EC2, you can have up to 100 rules per group.
Example 1 Request XML
<authorizeIngressSecurityGroup>
<permissions>
<permission>
<protocol>tcp</protocol>
<fromPort>22</fromPort>
<toPort>22</toPort>
<sourceGroups/>
<ipRanges>
<ipRange>
<cidrIp>10.2.3.0/24</cidrIp>
</ipRange>
</ipRanges>
</permission>
</permissions>
</authorizeIngressSecurityGroup>
Example 2 Request XML
<authorizeIngressSecurityGroup>
<permissions>
<permission>
<sourceGroups>
<sourceGroup>
<userId>admin</userId>
<groupId>20</groupId>
</sourceGroup>
</sourceGroups>
</ipRanges>
</permission>
</permissions>
</authorizeIngressSecurityGroup>
Example 1 Request JSON
{
"authorizeIngressSecurityGroup" : {
"permissions" : [
{
"sourceGroups" : [
{
"userId" : "admin",
"groupId" : "20"
}
]
}
]
}
}
Example 2 Request JSON
{
"authorizeIngressSecurityGroup" : {
"permissions" : [
{
"protocol" : "tcp",
"fromPort" : "22",
"toPort" : "22",
"ipRanges" : [
{
"cidrIp" : "10.2.3.124/24"
}
]
}
]
}
}
Revoke Security Group Ingress
| Verb | URI |
| POST | /os-security-groups/id/revoke_ingress |
Normal Response Code(s): 202
Error Response Code(s): computeFault(500), unauthorized(401), BadRequest(400), UnprocessableEntity(422), itemNotfound(400)
This operation removes one or more ingress rules from a security group.
This operation does not send a response body.
Example 1 Request XML
<revokeIngressSecurityGroup>
<permissions>
<permission>
<protocol>tcp</protocol>
<fromPort>22</fromPort>
<toPort>22</toPort>
<sourceGroups/>
<ipRanges>
<ipRange>
<cidrIp>10.2.3.0/24</cidrIp>
</ipRange>
</ipRanges>
</permission>
</permissions>
</revokeIngressSecurityGroup>
Example 2 Request XML
<revokeIngressSecurityGroup>
<permissions>
<permission>
<sourceGroups>
<sourceGroup>
<userId>admin</userId>
<groupId>20</groupId>
</sourceGroup>
</sourceGroups>
</ipRanges>
</permission>
</permissions>
</revokeIngressSecurityGroup>
Example 1 Request JSON
{
"revokeIngressSecurityGroup" : {
"permissions" : [
{
"sourceGroups" : [
{
"userId" : "admin",
"groupId" : "20"
}
]
}
]
}
}
Example 2 Request JSON
{
"revokeIngressSecurityGroup" : {
"permissions" : [
{
"protocol" : "tcp",
"fromPort" : "22",
"toPort" : "22",
"ipRanges" : [
{
"cidrIp" : "10.2.3.124/24"
}
]
}
]
}
}
