diff --git a/api-ref/source/v2/index.rst b/api-ref/source/v2/index.rst index 160e94b7b..0b4ab6169 100644 --- a/api-ref/source/v2/index.rst +++ b/api-ref/source/v2/index.rst @@ -74,4 +74,8 @@ BGP/MPLS VPN Interconnection .. include:: bgpvpn-bgpvpns.inc .. include:: bgpvpn-network_associations.inc .. include:: bgpvpn-router_associations.inc -.. include:: bgpvpn-port_associations.inc \ No newline at end of file +.. include:: bgpvpn-port_associations.inc +####### +Logging +####### +.. include:: logging.inc diff --git a/api-ref/source/v2/logging.inc b/api-ref/source/v2/logging.inc new file mode 100644 index 000000000..309bd8735 --- /dev/null +++ b/api-ref/source/v2/logging.inc @@ -0,0 +1,271 @@ +.. -*- rst -*- + +============ +Log resource +============ + +The ``logging`` extension lists, creates, shows information for, and updates +log resource. + +List logs +========= + +.. rest_method:: GET /v2.0/log/logs + +Lists all log resources associated with your project. + +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 `__. + +The list might be empty. + +Normal response codes: 200 + +Error response codes: 401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - fields: fields + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - logs: logs + - id: log_id + - name: name + - description: description + - tenant_id: project_id + - project_id: project_id + - event: log_event + - resource_type: resource_log_type + - resource_id: resource_log_id + - target_id: resource_target_log_id + - enabled: log_enabled + +Response Example +---------------- + +.. literalinclude:: samples/logs/log-list-response.json + :language: javascript + +Create log +========== + +.. rest_method:: POST /v2.0/log/logs + +Creates a log resource. + +Creates a log resource by using the configuration that you define in +the request object. A response object is returned. The object +contains a unique ID. + +If the caller is not an administrative user, this call returns the +HTTP ``Forbidden (403)`` response code. + +Users with an administrative role can create policies on behalf of +other projects by specifying a project ID that is different than +their own. + +Normal response codes: 201 + +Error response codes: 400, 401, 403, 409 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - log: log + - name: name-request + - description: description-request + - tenant_id: project_id-request + - project_id: project_id-request + - event: log_event-request + - resource_type: resource_log_type + - resource_id: resource_log_id-request + - target_id: resource_target_log_id-request + - enabled: log_enabled-request + +Request Example +--------------- + +.. literalinclude:: samples/logs/log-create-request.json + :language: javascript + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - log: log + - id: log_id + - name: name + - description: description + - tenant_id: project_id + - project_id: project_id + - event: log_event + - resource_type: resource_log_type + - resource_id: resource_log_id + - target_id: resource_target_log_id + - enabled: log_enabled + +Request Example +--------------- + +.. literalinclude:: samples/logs/log-create-response.json + :language: javascript + +Show log +======== + +.. rest_method:: GET /v2.0/log/logs/{log_id} + +Shows details log resource. + +Normal response codes: 200 + +Error response codes: 401, 404 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - log_id: log_id-path + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - log: log + - id: log_id + - name: name + - description: description + - tenant_id: project_id + - project_id: project_id + - event: log_event + - resource_type: resource_log_type + - resource_id: resource_log_id + - target_id: resource_target_log_id + - enabled: log_enabled + +Response Example +---------------- + +.. literalinclude:: samples/logs/log-show-response.json + :language: javascript + +Update log +========== + +.. rest_method:: PUT /v2.0/log/logs/{log_id} + +Updates a log resource. + +Normal response codes: 200 + +Error response codes: 400, 401, 404 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - log_id: log_id-path + - log: log + - name: name-request + - description: description-request + - enabled: log_enabled-request-put + +Request Example +--------------- + +.. literalinclude:: samples/logs/log-update-request.json + :language: javascript + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - log: log + - id: log_id + - name: name + - description: description + - tenant_id: project_id + - project_id: project_id + - event: log_event + - resource_type: resource_log_type + - resource_id: resource_log_id + - target_id: resource_target_log_id + - enabled: log_enabled + +Response Example +---------------- + +.. literalinclude:: samples/logs/log-update-response.json + :language: javascript + +Delete log +========== + +.. rest_method:: DELETE /v2.0/log/logs/{log_id} + +Deletes a log resource. + +Normal response codes: 204 + +Error response codes: 400, 401, 404 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - log_id: log_id-path + +Response +-------- + +There is no body content for the response of a successful DELETE request. + +================= +Loggable resource +================= + +List loggable resources +======================= + +.. rest_method:: GET /v2.0/log/loggable-resources + +Lists all resource log types are supporting. + +Normal response codes: 200 + +Error response codes: 401 + +Request +------- + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - loggable_resources: loggable_resources + - type: resource_log_type + +Response Example +---------------- + +.. literalinclude:: samples/logs/loggable_resources-list-response.json + :language: javascript \ No newline at end of file diff --git a/api-ref/source/v2/parameters.yaml b/api-ref/source/v2/parameters.yaml index 595caad31..086e13d45 100644 --- a/api-ref/source/v2/parameters.yaml +++ b/api-ref/source/v2/parameters.yaml @@ -133,6 +133,12 @@ loadbalancer-id-path: in: path required: true type: string +log_id-path: + description: | + The ID of the log resource. + in: path + required: true + type: string logging_resource_id: description: | The ID of the logging resource. @@ -3126,6 +3132,58 @@ location: in: body required: true type: string +log: + description: | + A ``log`` object. + in: body + required: true + type: object +log_enabled: + description: | + Indicates whether this log object is enabled or disabled. + in: body + required: true + type: boolean +log_enabled-request: + description: | + Indicates whether this log object is enabled or disabled. + Default is true. + in: body + required: false + type: boolean +log_enabled-request-put: + description: | + Indicates whether this log object is enabled or disabled. + in: body + required: false + type: boolean +log_event: + description: | + Type of security events to log. + ``ACCEPT``, ``DROP``, or ``ALL``. + in: body + required: true + type: string +log_event-request: + description: | + Type of security events to log. + ``ACCEPT``, ``DROP``, or ``ALL``. + Default is ``ALL``. + in: body + required: false + type: string +log_id: + description: | + The ID of the log object. + in: body + required: true + type: string +loggable_resources: + description: | + A list of ``loggable_resource`` object. + in: body + required: true + type: object logging_resource: description: | A ``logging_resource`` object. @@ -3163,6 +3221,12 @@ logging_resources: in: body required: true type: array +logs: + description: | + A list of ``log`` objects. + in: body + required: true + type: array mac_address: description: | The MAC address of the port. @@ -4575,6 +4639,36 @@ resource-rel: in: body required: true type: string +resource_log_id: + description: | + The ID of resource log (e.g security group ID). + in: body + required: true + type: string +resource_log_id-request: + description: | + The ID of resource log (e.g security group ID). + in: body + required: false + type: string +resource_log_type: + description: | + The resource log type such as 'security_group'. + in: body + required: true + type: string +resource_target_log_id: + description: | + The ID of resource target log such as port ID. + in: body + required: true + type: string +resource_target_log_id-request: + description: | + The ID of resource target log such as port ID. + in: body + required: false + type: string resources: description: | List of resource objects. diff --git a/api-ref/source/v2/samples/logs/log-create-request.json b/api-ref/source/v2/samples/logs/log-create-request.json new file mode 100644 index 000000000..3f94feb5b --- /dev/null +++ b/api-ref/source/v2/samples/logs/log-create-request.json @@ -0,0 +1,7 @@ +{ + "log": { + "name": "security group log", + "description": "Log for project demo.", + "resource_type": "security_group" + } +} diff --git a/api-ref/source/v2/samples/logs/log-create-response.json b/api-ref/source/v2/samples/logs/log-create-response.json new file mode 100644 index 000000000..38e1c8417 --- /dev/null +++ b/api-ref/source/v2/samples/logs/log-create-response.json @@ -0,0 +1,14 @@ +{ + "log": { + "name": "security group log", + "description": "Log for project demo.", + "id": "46ebaec0-0570-43ac-82f6-60d2b03168c4", + "project_id": "92a5a4f4245a4abbafacb7ca73b027b0", + "tenant_id": "92a5a4f4245a4abbafacb7ca73b027b0", + "enabled": true, + "resource_type": "security_group", + "resource_id": null, + "target_id": null, + "event": "ALL" + } +} diff --git a/api-ref/source/v2/samples/logs/log-list-response.json b/api-ref/source/v2/samples/logs/log-list-response.json new file mode 100644 index 000000000..011760a87 --- /dev/null +++ b/api-ref/source/v2/samples/logs/log-list-response.json @@ -0,0 +1,16 @@ +{ + "logs": [ + { + "name": "security group log", + "description": "Log for project demo.", + "id": "46ebaec0-0570-43ac-82f6-60d2b03168c4", + "project_id": "92a5a4f4245a4abbafacb7ca73b027b0", + "tenant_id": "92a5a4f4245a4abbafacb7ca73b027b0", + "enabled": true, + "resource_type": "security_group", + "resource_id": null, + "target_id": null, + "event": "ALL" + } + ] +} diff --git a/api-ref/source/v2/samples/logs/log-show-response.json b/api-ref/source/v2/samples/logs/log-show-response.json new file mode 100644 index 000000000..c5040ee03 --- /dev/null +++ b/api-ref/source/v2/samples/logs/log-show-response.json @@ -0,0 +1,14 @@ +{ + "log": { + "name": "security group log", + "description": "Log for project demo.", + "id": "46ebaec0-0570-43ac-82f6-60d2b03168c4", + "project_id": "8d4c70a21fed4aeba121a1a429ba0d04", + "tenant_id": "8d4c70a21fed4aeba121a1a429ba0d04", + "enabled": true, + "resource_type": "security_group", + "resource_id": null, + "target_id": null, + "event": "ACCEPT" + } +} diff --git a/api-ref/source/v2/samples/logs/log-update-request.json b/api-ref/source/v2/samples/logs/log-update-request.json new file mode 100644 index 000000000..6f39545a9 --- /dev/null +++ b/api-ref/source/v2/samples/logs/log-update-request.json @@ -0,0 +1,5 @@ +{ + "log": { + "enabled": false + } +} diff --git a/api-ref/source/v2/samples/logs/log-update-response.json b/api-ref/source/v2/samples/logs/log-update-response.json new file mode 100644 index 000000000..270da5dbf --- /dev/null +++ b/api-ref/source/v2/samples/logs/log-update-response.json @@ -0,0 +1,14 @@ +{ + "log": { + "name": "security group log", + "description": "Log for project demo.", + "id": "46ebaec0-0570-43ac-82f6-60d2b03168c4", + "project_id": "8d4c70a21fed4aeba121a1a429ba0d04", + "tenant_id": "8d4c70a21fed4aeba121a1a429ba0d04", + "enabled": false, + "resource_type": "security_group", + "resource_id": null, + "target_id": null, + "event": "DROP" + } +} diff --git a/api-ref/source/v2/samples/logs/loggable_resources-list-response.json b/api-ref/source/v2/samples/logs/loggable_resources-list-response.json new file mode 100644 index 000000000..10a8da3d1 --- /dev/null +++ b/api-ref/source/v2/samples/logs/loggable_resources-list-response.json @@ -0,0 +1,7 @@ +{ + "loggable_resources": [ + { + "type": "security_group" + } + ] +} diff --git a/releasenotes/notes/logging-api-ref-fafb884367ca60a2.yaml b/releasenotes/notes/logging-api-ref-fafb884367ca60a2.yaml new file mode 100644 index 000000000..50d291dc7 --- /dev/null +++ b/releasenotes/notes/logging-api-ref-fafb884367ca60a2.yaml @@ -0,0 +1,3 @@ +--- +features: + - API reference for the logging extension for ``security_group`` resource.