From 4b9753de30fca22c59e4836ae2c01fc7ae5a2e37 Mon Sep 17 00:00:00 2001 From: Slawek Kaplonski Date: Mon, 29 May 2023 11:12:57 +0200 Subject: [PATCH] [API REF] Add api-ref documentation for default SG rules API Related-Bug: #1983053 Change-Id: I0053337686d49229b44e157977b2607051ad1604 --- api-ref/source/v2/index.rst | 1 + api-ref/source/v2/parameters.yaml | 89 ++++++++ ...ity-group-default-rule-create-request.json | 9 + ...ty-group-default-rule-create-response.json | 16 ++ ...-default-rule-delete-request-json-http.txt | 3 + ...default-rule-delete-response-json-http.txt | 1 + ...up-default-rule-show-request-json-http.txt | 2 + ...rity-group-default-rule-show-response.json | 16 ++ ...p-default-rules-list-request-json-http.txt | 2 + ...ity-group-default-rules-list-response.json | 88 ++++++++ .../v2/security_groups_default_rules.inc | 206 ++++++++++++++++++ 11 files changed, 433 insertions(+) create mode 100644 api-ref/source/v2/samples/security-group-default-rules/security-group-default-rule-create-request.json create mode 100644 api-ref/source/v2/samples/security-group-default-rules/security-group-default-rule-create-response.json create mode 100644 api-ref/source/v2/samples/security-group-default-rules/security-group-default-rule-delete-request-json-http.txt create mode 100644 api-ref/source/v2/samples/security-group-default-rules/security-group-default-rule-delete-response-json-http.txt create mode 100644 api-ref/source/v2/samples/security-group-default-rules/security-group-default-rule-show-request-json-http.txt create mode 100644 api-ref/source/v2/samples/security-group-default-rules/security-group-default-rule-show-response.json create mode 100644 api-ref/source/v2/samples/security-group-default-rules/security-group-default-rules-list-request-json-http.txt create mode 100644 api-ref/source/v2/samples/security-group-default-rules/security-group-default-rules-list-response.json create mode 100644 api-ref/source/v2/security_groups_default_rules.inc diff --git a/api-ref/source/v2/index.rst b/api-ref/source/v2/index.rst index 39d8684c1..fc8ee0c2f 100644 --- a/api-ref/source/v2/index.rst +++ b/api-ref/source/v2/index.rst @@ -44,6 +44,7 @@ Security .. include:: rbac-policy.inc .. include:: security-group-rules.inc .. include:: security-groups.inc +.. include:: security_groups_default_rules.inc .. include:: vpnaas.inc ################### Resource Management diff --git a/api-ref/source/v2/parameters.yaml b/api-ref/source/v2/parameters.yaml index 640cf9878..4407b1c5a 100644 --- a/api-ref/source/v2/parameters.yaml +++ b/api-ref/source/v2/parameters.yaml @@ -67,6 +67,12 @@ conntrack_helper_id-path: in: path required: true type: string +default_security_group_rule-id-path: + description: | + The ID of the security group default rule. + in: path + required: true + type: string dscp_rule_id: description: | The ID of the DSCP rule. @@ -1355,6 +1361,20 @@ rbac_action-query: in: query required: false type: string +remote_address_group_id-query: + description: | + Filter the security group rule list result by the ID of the remote address + group that associates with this security group rule. + in: query + required: false + type: string +remote_address_group_id-request: + description: | + UUID of the remote address group that associates with the security group + rule created from this template. + in: query + required: false + type: string remote_group_id-query: description: | Filter the security group rule list result by the ID of the remote group @@ -1362,6 +1382,16 @@ remote_group_id-query: in: query required: false type: string +remote_group_id_template-query: + description: | + Filter the security group rule list result by the ID of the remote group + that associates with this security group rule. This field can contains uuid + of the security group or special word ``PARENT`` which means that in the + real rule created from this template, uuid of the owner Security Group will + be put as ``remote_group_id``. + in: query + required: false + type: string remote_ip_prefix-query: description: | Filter the list result by the remote IP prefix that is matched by @@ -2658,6 +2688,12 @@ default_quota: in: body required: false type: integer +default_security_group_rule-id: + description: | + The ID of the security group default rule. + in: body + required: true + type: string description: description: | A human-readable description for the resource. @@ -5798,6 +5834,13 @@ rbac_policy_id: in: body required: true type: string +remote_address_group_id: + description: | + The remote address group UUID to associate with this + security group rule. + in: body + required: true + type: string remote_group_id: description: | The remote group UUID to associate with this @@ -5816,6 +5859,17 @@ remote_group_id-request: in: body required: false type: string +remote_group_id_template: + description: | + The remote group UUID to associate with this + security group rule. You can specify either the + ``remote_group_id`` or ``remote_ip_prefix`` attribute in the + request body. Special word ``PARENT`` can be specified and it means that + in the real rule created from this template, uuid of the owner Security + Group will be put as ``remote_group_id``. + in: body + required: false + type: string remote_ip_prefix: description: | The remote IP prefix that is matched by this security group rule. @@ -6303,6 +6357,12 @@ security_group-shared-response: in: body required: true type: boolean +security_group_default_rule: + description: | + A ``default_security_group_rule`` object. + in: body + required: true + type: object security_group_id: description: | The security group UUID to associate with this @@ -6943,6 +7003,35 @@ use_default_subnetpool: in: body required: false type: boolean +used_in_default_sg: + description: | + Whether this security group rule template should be used in default + security group created automatically for each new project. Default value + is ``False``. + in: body + required: false + type: boolean +used_in_default_sg-query: + description: | + Fiter by security group rule templates which should be used in default + security group created automatically for each new project. + in: body + required: false + type: boolean +used_in_non_default_sg: + description: | + Whether this security group rule template should be used in custom + security groups created by project user. Default value is ``True``. + in: body + required: false + type: boolean +used_in_non_default_sg-query: + description: | + Fiter by security group rule templates which should be used in custom + security groups created by project users. + in: body + required: false + type: boolean used_ips: description: | The number of used IP addresses of all subnets in diff --git a/api-ref/source/v2/samples/security-group-default-rules/security-group-default-rule-create-request.json b/api-ref/source/v2/samples/security-group-default-rules/security-group-default-rule-create-request.json new file mode 100644 index 000000000..4a2acd370 --- /dev/null +++ b/api-ref/source/v2/samples/security-group-default-rules/security-group-default-rule-create-request.json @@ -0,0 +1,9 @@ +{ + "default_security_group_rule": { + "direction": "ingress", + "port_range_min": "80", + "ethertype": "IPv4", + "port_range_max": "80", + "protocol": "tcp" + } +} diff --git a/api-ref/source/v2/samples/security-group-default-rules/security-group-default-rule-create-response.json b/api-ref/source/v2/samples/security-group-default-rules/security-group-default-rule-create-response.json new file mode 100644 index 000000000..3ea1608b9 --- /dev/null +++ b/api-ref/source/v2/samples/security-group-default-rules/security-group-default-rule-create-response.json @@ -0,0 +1,16 @@ +{ + "default_security_group_rule": { + "direction": "ingress", + "ethertype": "IPv4", + "id": "2bc0accf-312e-429a-956e-e4407625eb62", + "port_range_max": 80, + "port_range_min": 80, + "protocol": "tcp", + "remote_group_id": null, + "remote_ip_prefix": null, + "remote_address_group_id": null, + "used_in_default_sg": false, + "used_in_non_default_sg": true, + "description": "" + } +} diff --git a/api-ref/source/v2/samples/security-group-default-rules/security-group-default-rule-delete-request-json-http.txt b/api-ref/source/v2/samples/security-group-default-rules/security-group-default-rule-delete-request-json-http.txt new file mode 100644 index 000000000..920073aa7 --- /dev/null +++ b/api-ref/source/v2/samples/security-group-default-rules/security-group-default-rule-delete-request-json-http.txt @@ -0,0 +1,3 @@ +DELETE /v2.0/security-group-rules/fc3c327a-b5b5-4cd3-9577-52893289ce08 +Content-Type: application/json +Accept: application/json \ No newline at end of file diff --git a/api-ref/source/v2/samples/security-group-default-rules/security-group-default-rule-delete-response-json-http.txt b/api-ref/source/v2/samples/security-group-default-rules/security-group-default-rule-delete-response-json-http.txt new file mode 100644 index 000000000..f81fef7d2 --- /dev/null +++ b/api-ref/source/v2/samples/security-group-default-rules/security-group-default-rule-delete-response-json-http.txt @@ -0,0 +1 @@ +status: 204 \ No newline at end of file diff --git a/api-ref/source/v2/samples/security-group-default-rules/security-group-default-rule-show-request-json-http.txt b/api-ref/source/v2/samples/security-group-default-rules/security-group-default-rule-show-request-json-http.txt new file mode 100644 index 000000000..3a4bc6c22 --- /dev/null +++ b/api-ref/source/v2/samples/security-group-default-rules/security-group-default-rule-show-request-json-http.txt @@ -0,0 +1,2 @@ +GET /v2.0/default-security-group-rules/3c0e45ff-adaf-4124-b083-bf390e5482ff +Accept: application/json diff --git a/api-ref/source/v2/samples/security-group-default-rules/security-group-default-rule-show-response.json b/api-ref/source/v2/samples/security-group-default-rules/security-group-default-rule-show-response.json new file mode 100644 index 000000000..3ea1608b9 --- /dev/null +++ b/api-ref/source/v2/samples/security-group-default-rules/security-group-default-rule-show-response.json @@ -0,0 +1,16 @@ +{ + "default_security_group_rule": { + "direction": "ingress", + "ethertype": "IPv4", + "id": "2bc0accf-312e-429a-956e-e4407625eb62", + "port_range_max": 80, + "port_range_min": 80, + "protocol": "tcp", + "remote_group_id": null, + "remote_ip_prefix": null, + "remote_address_group_id": null, + "used_in_default_sg": false, + "used_in_non_default_sg": true, + "description": "" + } +} diff --git a/api-ref/source/v2/samples/security-group-default-rules/security-group-default-rules-list-request-json-http.txt b/api-ref/source/v2/samples/security-group-default-rules/security-group-default-rules-list-request-json-http.txt new file mode 100644 index 000000000..a9068fc92 --- /dev/null +++ b/api-ref/source/v2/samples/security-group-default-rules/security-group-default-rules-list-request-json-http.txt @@ -0,0 +1,2 @@ +GET /v2.0/default-security-group-rules/ +Accept: application/json diff --git a/api-ref/source/v2/samples/security-group-default-rules/security-group-default-rules-list-response.json b/api-ref/source/v2/samples/security-group-default-rules/security-group-default-rules-list-response.json new file mode 100644 index 000000000..00646f7a6 --- /dev/null +++ b/api-ref/source/v2/samples/security-group-default-rules/security-group-default-rules-list-response.json @@ -0,0 +1,88 @@ +{ + "default_security_group_rules": [ + { + "direction": "egress", + "ethertype": "IPv6", + "id": "3c0e45ff-adaf-4124-b083-bf390e5482ff", + "port_range_max": null, + "port_range_min": null, + "protocol": null, + "remote_group_id": null, + "remote_ip_prefix": null, + "remote_address_group_id": null, + "used_in_default_sg": true, + "used_in_default_non_sg": true, + "description": "" + }, + { + "direction": "egress", + "ethertype": "IPv4", + "id": "93aa42e5-80db-4581-9391-3a608bd0e448", + "port_range_max": null, + "port_range_min": null, + "protocol": null, + "remote_group_id": null, + "remote_ip_prefix": null, + "remote_address_group_id": null, + "used_in_default_sg": true, + "used_in_default_non_sg": true, + "description": "" + }, + { + "direction": "ingress", + "ethertype": "IPv6", + "id": "333e64bf-cab0-47ed-8303-fca711b74433", + "port_range_max": null, + "port_range_min": null, + "protocol": null, + "remote_group_id": "PARENT", + "remote_ip_prefix": null, + "remote_address_group_id": null, + "used_in_default_sg": true, + "used_in_default_non_sg": true, + "description": "" + }, + { + "direction": "ingress", + "ethertype": "IPv4", + "id": "91eff177-4e20-4407-a7ac-843c625316e3", + "port_range_max": null, + "port_range_min": null, + "protocol": null, + "remote_group_id": "PARENT", + "remote_ip_prefix": null, + "remote_address_group_id": null, + "used_in_default_sg": true, + "used_in_default_non_sg": true, + "description": "" + }, + { + "direction": "ingress", + "ethertype": "IPv6", + "id": "d41fc3d7-46bc-405e-a4f6-029cbb63c5c4", + "port_range_max": 22, + "port_range_min": 22, + "protocol": null, + "remote_group_id": null, + "remote_ip_prefix": null, + "remote_address_group_id": null, + "used_in_default_sg": false, + "used_in_default_non_sg": true, + "description": "Allow SSH connections over IPv6" + }, + { + "direction": "ingress", + "ethertype": "IPv4", + "id": "03315f60-52dd-40e0-a769-04360cb3e6c1", + "port_range_max": 22, + "port_range_min": 22, + "protocol": null, + "remote_group_id": null, + "remote_ip_prefix": null, + "remote_address_group_id": null, + "used_in_default_sg": false, + "used_in_default_non_sg": true, + "description": "Allow SSH connections over IPv4" + } + ] +} diff --git a/api-ref/source/v2/security_groups_default_rules.inc b/api-ref/source/v2/security_groups_default_rules.inc new file mode 100644 index 000000000..1d8ae01ff --- /dev/null +++ b/api-ref/source/v2/security_groups_default_rules.inc @@ -0,0 +1,206 @@ +.. -*- rst -*- + +.. _security_group_default_rules: + +=========================================================== +Security group default rules (security-group-default-rules) +=========================================================== + +Lists, creates, shows information for, and deletes security group +default rules. + +List security group default rules +================================= + +.. rest_method:: GET /v2.0/default-security-group-rules + +Lists a summary of all OpenStack Networking security group rules that are used +for every newly created Security Group. + +The list provides the ID for each security group default rule. + +Use the ``fields`` query parameter to control which fields are +returned in the response body. Additionally, you can filter results +by using query string parameters. For information, see `Filtering +and Column Selection `__. + +Normal response codes: 200 + +Error response codes: 401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - remote_group_id: remote_group_id_template-query + - direction: direction-query + - protocol: protocol-query + - ethertype: ethertype-query + - port_range_max: port_range_max-query + - port_range_min: port_range_min-query + - remote_ip_prefix: remote_ip_prefix-query + - remote_address_group_id: remote_address_group_id-query + - used_in_default_sg: used_in_default_sg-query + - used_in_non_default_sg: used_in_non_default_sg-query + - id: id-query + - description: description-query + - sort_dir: sort_dir + - sort_key: security_group_rule-sort_key + - fields: fields + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - security_group_rules: security_group_rules + - remote_group_id: remote_group_id_template-query + - direction: direction + - protocol: protocol + - ethertype: ethertype + - port_range_max: port_range_max + - port_range_min: port_range_min + - remote_ip_prefix: remote_ip_prefix + - remote_address_group_id: remote_address_group_id + - used_in_default_sg: used_in_default_sg + - used_in_non_default_sg: used_in_non_default_sg + - id: default_security_group_rule-id + - description: description + +Response Example +---------------- + +.. literalinclude:: samples/security-group-default-rules/security-group-default-rules-list-response.json + :language: javascript + +Create security group default rule +================================== + +.. rest_method:: POST /v2.0/default-security-group-rules + +Creates an OpenStack Networking templale of the security group rule. + +Normal response codes: 201 + +Error response codes: 400, 401, 404, 409 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - default_security_group_rule: security_group_default_rule + - remote_group_id: remote_group_id-request + - direction: direction + - protocol: protocol-request + - ethertype: ethertype-request + - port_range_max: port_range_max-request + - port_range_min: port_range_min-request + - remote_ip_prefix: remote_ip_prefix-request + - remote_address_group_id: remote_address_group_id-request + - used_in_default_sg: used_in_default_sg + - used_in_non_default_sg: used_in_non_default_sg + - description: description-request + +Request Example +--------------- + +.. literalinclude:: samples/security-group-default-rules/security-group-default-rule-create-request.json + :language: javascript + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - remote_group_id: remote_group_id + - direction: direction + - protocol: protocol + - ethertype: ethertype + - port_range_max: port_range_max + - port_range_min: port_range_min + - remote_ip_prefix: remote_ip_prefix + - remote_address_group_id: remote_address_group_id + - used_in_default_sg: used_in_default_sg + - used_in_non_default_sg: used_in_non_default_sg + - id: default_security_group_rule-id + - description: description + +Response Example +---------------- + +.. literalinclude:: samples/security-group-default-rules/security-group-default-rule-create-response.json + :language: javascript + +Show security group default rule +================================ + +.. rest_method:: GET /v2.0/default-security-group-rules/{default_security_group_rule_id} + +Shows detailed information for a security group default rule. + +The response body contains the following information about the +security group rule: + +Normal response codes: 200 + +Error response codes: 401, 404 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - default_security_group_rule_id: default_security_group_rule-id-path + - verbose: verbose + - fields: fields + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - default_security_group_rule: security_group_default_rule + - remote_group_id: remote_group_id + - direction: direction + - protocol: protocol + - ethertype: ethertype + - port_range_max: port_range_max + - port_range_min: port_range_min + - remote_ip_prefix: remote_ip_prefix + - remote_address_group_id: remote_address_group_id + - used_in_default_sg: used_in_default_sg + - used_in_non_default_sg: used_in_non_default_sg + - id: default_security_group_rule-id + - description: description + +Response Example +---------------- + +.. literalinclude:: samples/security-group-default-rules/security-group-default-rule-show-response.json + :language: javascript + +Delete security group default rule +================================== + +.. rest_method:: DELETE /v2.0/default-security-group-rules/{default_security_group_rule_id} + +Deletes an OpenStack Networking security group rule template. + +Normal response codes: 204 + +Error response codes: 401, 404, 412 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - default_security_group_rule_id: default_security_group_rule-id-path + +Response +-------- + +There is no body content is returned on a successful DELETE request.