diff --git a/api-ref/source/api/index.rst b/api-ref/source/api/index.rst new file mode 100644 index 0000000..8b615ca --- /dev/null +++ b/api-ref/source/api/index.rst @@ -0,0 +1,14 @@ +:original_name: asm_api_0012.html + +.. _asm_api_0012: + +API +=== + +- :ref:`Service Mesh APIs ` + +.. toctree:: + :maxdepth: 1 + :hidden: + + service_mesh_apis/index diff --git a/api-ref/source/api/service_mesh_apis/creating_a_service_mesh.rst b/api-ref/source/api/service_mesh_apis/creating_a_service_mesh.rst new file mode 100644 index 0000000..43fd482 --- /dev/null +++ b/api-ref/source/api/service_mesh_apis/creating_a_service_mesh.rst @@ -0,0 +1,466 @@ +:original_name: asm_api_0101.html + +.. _asm_api_0101: + +Creating a Service Mesh +======================= + +Function +-------- + +This API is used to create a service mesh. + +URI +--- + +POST /v1/meshes + +Request Parameters +------------------ + +.. table:: **Table 1** Request header parameters + + +-------------------+-----------+--------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Parameter | Mandatory | Type | Description | + +===================+===========+========+=====================================================================================================================================================================================+ + | Content-Type | Yes | String | Message body type or format. | + +-------------------+-----------+--------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | X-Auth-Token | Yes | String | Requests for calling an API can be authenticated using either a token or AK/SK. If token-based authentication is used, this parameter is mandatory and must be set to a user token. | + +-------------------+-----------+--------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | X-Apply-ProjectID | Yes | String | ID of the project that the service mesh belongs to. | + +-------------------+-----------+--------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. table:: **Table 2** Parameters in the request body + + +------------+-----------+-------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+ + | Parameter | Mandatory | Type | Description | + +============+===========+=========================================================================+================================================================================================+ + | apiVersion | Yes | String | API version. The value is fixed at **v1** and cannot be changed. | + +------------+-----------+-------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+ + | kind | Yes | String | API type. The value is fixed at **Mesh** or **mesh** and cannot be changed. | + +------------+-----------+-------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+ + | metadata | Yes | :ref:`Table3 MeshMetadata ` object | Basic information about the service mesh. Metadata is a collection of attributes. | + +------------+-----------+-------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+ + | spec | Yes | :ref:`Table 4 MeshSpec ` object | Detailed description of the service mesh. ASM creates or updates the service mesh by **spec**. | + +------------+-----------+-------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+ + +.. _asm_api_0101___request_meshmetadata: + +.. table:: **Table 3** MeshMetadata + + +-----------------+-----------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Parameter | Mandatory | Type | Description | + +=================+=================+=================+===================================================================================================================================================================+ + | name | Yes | String | Service mesh name. | + | | | | | + | | | | Enter 4 to 64 characters. The name must start with a lowercase letter and not end with a hyphen (-). Only lowercase letters, digits, and hyphens (-) are allowed. | + +-----------------+-----------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. _asm_api_0101___request_meshspec: + +.. table:: **Table 4** MeshSpec + + +-----------------+-----------------+----------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+ + | Parameter | Mandatory | Type | Description | + +=================+=================+==================================================================================+=====================================================================================================================================+ + | region | Yes | String | Region where the control plane components of the service mesh are located. | + +-----------------+-----------------+----------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+ + | type | Yes | String | Service mesh type. | + | | | | | + | | | | **InCluster**: service mesh with an in-cluster control plane. The value is **InCluster** for the service mesh of the Basic edition. | + +-----------------+-----------------+----------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+ + | version | Yes | String | Service mesh version. | + +-----------------+-----------------+----------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+ + | extendParams | Yes | :ref:`Table 5 MeshExtendParams ` object | Extensions of the service mesh. | + +-----------------+-----------------+----------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+ + +.. _asm_api_0101___request_meshextendparams: + +.. table:: **Table 5** MeshExtendParams + + +-----------+-----------+----------------------------------------------------------------------------------+----------------------------------------------------------------------------+ + | Parameter | Mandatory | Type | Description | + +===========+===========+==================================================================================+============================================================================+ + | clusters | Yes | Array of :ref:`Table 6 MeshCluster ` objects | Information about clusters in service meshes (only for the Basic edition). | + +-----------+-----------+----------------------------------------------------------------------------------+----------------------------------------------------------------------------+ + +.. _asm_api_0101___request_meshcluster: + +.. table:: **Table 6** MeshCluster + + +--------------+-----------+--------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | Parameter | Mandatory | Type | Description | + +==============+===========+======================================================================================+===============================================================================+ + | clusterID | Yes | String | Cluster ID, which is unique and can be used to query the cluster to be added. | + +--------------+-----------+--------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | projectID | Yes | String | ID of the project that the cluster belongs to. | + +--------------+-----------+--------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | injection | No | :ref:`Table 7 InjectionConfig ` object | Sidecar injection configuration. | + +--------------+-----------+--------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | installation | Yes | :ref:`Table 8 InstallationConfig ` object | Installation configuration of service mesh components. | + +--------------+-----------+--------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + +.. _asm_api_0101___request_injectionconfig: + +.. table:: **Table 7** InjectionConfig + + +------------+-----------+------------------------------------------------------------------+-------------------------------------------+ + | Parameter | Mandatory | Type | Description | + +============+===========+==================================================================+===========================================+ + | namespaces | No | :ref:`Table 9 Selector ` object | Namespaces where sidecars to be injected. | + +------------+-----------+------------------------------------------------------------------+-------------------------------------------+ + +.. _asm_api_0101___request_installationconfig: + +.. table:: **Table 8** InstallationConfig + + +-----------+-----------+------------------------------------------------------------------+----------------------------------------------------+ + | Parameter | Mandatory | Type | Description | + +===========+===========+==================================================================+====================================================+ + | nodes | Yes | :ref:`Table 9 Selector ` object | Nodes where service mesh components are installed. | + +-----------+-----------+------------------------------------------------------------------+----------------------------------------------------+ + +.. _asm_api_0101___request_selector: + +.. table:: **Table 9** Selector + + +---------------+-----------+-----------------------------------------------------------------------------+-----------------+ + | Parameter | Mandatory | Type | Description | + +===============+===========+=============================================================================+=================+ + | fieldSelector | Yes | :ref:`Table 10 FieldSelector ` object | Field selector. | + +---------------+-----------+-----------------------------------------------------------------------------+-----------------+ + +.. _asm_api_0101___request_fieldselector: + +.. table:: **Table 10** FieldSelector + + +-----------+-----------+------------------+-----------------------------------------+ + | Parameter | Mandatory | Type | Description | + +===========+===========+==================+=========================================+ + | key | Yes | String | Key. | + +-----------+-----------+------------------+-----------------------------------------+ + | operator | Yes | String | Operator. The value can only be **In**. | + +-----------+-----------+------------------+-----------------------------------------+ + | values | Yes | Array of strings | Values. | + +-----------+-----------+------------------+-----------------------------------------+ + +Response Parameters +------------------- + +**Status code: 201** + +.. table:: **Table 11** Parameters in the response body + + +-----------------------+-------------------------------------------------------------+------------------------------------------------------------------------------------------------+ + | Parameter | Type | Description | + +=======================+=============================================================+================================================================================================+ + | apiVersion | String | API version. The value is fixed at **v1** and cannot be changed. | + +-----------------------+-------------------------------------------------------------+------------------------------------------------------------------------------------------------+ + | kind | String | API type. The value is fixed at **Mesh** or **mesh** and cannot be changed. | + +-----------------------+-------------------------------------------------------------+------------------------------------------------------------------------------------------------+ + | metadata | :ref:`Table 12 MeshMetadata ` object | Basic information about the service mesh. Metadata is a collection of attributes. | + +-----------------------+-------------------------------------------------------------+------------------------------------------------------------------------------------------------+ + | spec | :ref:`Table 13 MeshSpec ` object | Detailed description of the service mesh. ASM creates or updates the service mesh by **spec**. | + +-----------------------+-------------------------------------------------------------+------------------------------------------------------------------------------------------------+ + | status | :ref:`Table 20 MeshStatus ` object | Service mesh status, | + | | | | + | | | which is automatically generated by ASM. | + +-----------------------+-------------------------------------------------------------+------------------------------------------------------------------------------------------------+ + +.. _asm_api_0101___d1e904: + +.. table:: **Table 12** MeshMetadata + + +-------------------+--------+-------------------------------------------------------------------------------------------------+ + | Parameter | Type | Description | + +===================+========+=================================================================================================+ + | name | String | Service mesh name. | + +-------------------+--------+-------------------------------------------------------------------------------------------------+ + | uid | String | Service mesh ID, which is unique and automatically generated after the service mesh is created. | + +-------------------+--------+-------------------------------------------------------------------------------------------------+ + | creationTimestamp | String | Time when the service mesh was created. | + +-------------------+--------+-------------------------------------------------------------------------------------------------+ + +.. _asm_api_0101___d1e979: + +.. table:: **Table 13** MeshSpec + + +-----------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+ + | Parameter | Type | Description | + +=======================+=================================================================+=====================================================================================================================================+ + | region | String | Region where the control plane components of the service mesh are located. | + +-----------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+ + | type | String | Service mesh type. | + | | | | + | | | **InCluster**: service mesh with an in-cluster control plane. The value is **InCluster** for the service mesh of the Basic edition. | + +-----------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+ + | version | String | Service mesh version. | + +-----------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+ + | extendParams | :ref:`Table14 MeshExtendParams ` object | Extensions of the service mesh. | + +-----------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+ + +.. _asm_api_0101___d1e1042: + +.. table:: **Table 14** MeshExtendParams + + +-----------+----------------------------------------------------------------------+----------------------------------------------------------------------------+ + | Parameter | Type | Description | + +===========+======================================================================+============================================================================+ + | clusters | Array of :ref:`Table15 MeshCluster ` objects | Information about clusters in service meshes (only for the Basic edition). | + +-----------+----------------------------------------------------------------------+----------------------------------------------------------------------------+ + +.. _asm_api_0101___d1e1074: + +.. table:: **Table 15** MeshCluster + + +--------------+-------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | Parameter | Type | Description | + +==============+===================================================================+===============================================================================+ + | clusterID | String | Cluster ID, which is unique and can be used to query the cluster to be added. | + +--------------+-------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | projectID | String | ID of the project that the cluster belongs to. | + +--------------+-------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | injection | :ref:`Table16 InjectionConfig ` object | Sidecar injection configuration. | + +--------------+-------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | installation | :ref:`Table17 InstallationConfig ` object | Installation configuration of service mesh components. | + +--------------+-------------------------------------------------------------------+-------------------------------------------------------------------------------+ + +.. _asm_api_0101___d1e1137: + +.. table:: **Table 16** InjectionConfig + + +------------+----------------------------------------------------------+-------------------------------------------+ + | Parameter | Type | Description | + +============+==========================================================+===========================================+ + | namespaces | :ref:`Table 18 Selector ` object | Namespaces where sidecars to be injected. | + +------------+----------------------------------------------------------+-------------------------------------------+ + +.. _asm_api_0101___d1e1168: + +.. table:: **Table 17** InstallationConfig + + +-----------+----------------------------------------------------------+----------------------------------------------------+ + | Parameter | Type | Description | + +===========+==========================================================+====================================================+ + | nodes | :ref:`Table 18 Selector ` object | Nodes where service mesh components are installed. | + +-----------+----------------------------------------------------------+----------------------------------------------------+ + +.. _asm_api_0101___d1e1199: + +.. table:: **Table 18** Selector + + +---------------+---------------------------------------------------------------+-----------------+ + | Parameter | Type | Description | + +===============+===============================================================+=================+ + | fieldSelector | :ref:`Table 19 FieldSelector ` object | Field selector. | + +---------------+---------------------------------------------------------------+-----------------+ + +.. _asm_api_0101___d1e1230: + +.. table:: **Table 19** FieldSelector + + ========= ================ ======================================= + Parameter Type Description + ========= ================ ======================================= + key String Key. + operator String Operator. The value can only be **In**. + values Array of strings Values. + ========= ================ ======================================= + +.. _asm_api_0101___d1e1280: + +.. table:: **Table 20** MeshStatus + + +-----------------------+-----------------------+------------------------------------------------------------------+ + | Parameter | Type | Description | + +=======================+=======================+==================================================================+ + | phase | String | Service mesh status. The options are as follows: | + | | | | + | | | - **Running**: The service mesh is running. | + | | | - **Creating**: The service mesh is being created. | + | | | - **CreateFailed**: The service mesh fails to be created. | + | | | - **Deleting**: The service mesh is being deleted. | + | | | - **DeleteFailed**: The service mesh fails to be deleted. | + | | | - **Upgrading**: The service mesh is being upgraded. | + | | | - **UpgradeFailed**: The service mesh fails to be upgraded. | + | | | - **RollingBack**: The service mesh is being rolled back. | + | | | - **RollbackFailed**: The service mesh fails to be rolled back. | + +-----------------------+-----------------------+------------------------------------------------------------------+ + | updateTimestamp | String | Time when the service mesh was updated. | + +-----------------------+-----------------------+------------------------------------------------------------------+ + +**Status code: 400** + +.. table:: **Table 21** Parameters in the response body + + +-----------------------+-----------------------+-------------------------+ + | Parameter | Type | Description | + +=======================+=======================+=========================+ + | errorCode | String | Error code. | + | | | | + | | | Minimum length: **8** | + | | | | + | | | Maximum length: **36** | + +-----------------------+-----------------------+-------------------------+ + | errorMsg | String | Error message. | + | | | | + | | | Minimum length: **2** | + | | | | + | | | Maximum length: **512** | + +-----------------------+-----------------------+-------------------------+ + +**Status code: 409** + +.. table:: **Table 22** Parameters in the response body + + +-----------------------+-----------------------+-------------------------+ + | Parameter | Type | Description | + +=======================+=======================+=========================+ + | errorCode | String | Error code. | + | | | | + | | | Minimum length: **8** | + | | | | + | | | Maximum length: **36** | + +-----------------------+-----------------------+-------------------------+ + | errorMsg | String | Error message. | + | | | | + | | | Minimum length: **2** | + | | | | + | | | Maximum length: **512** | + +-----------------------+-----------------------+-------------------------+ + +**Status code: 500** + +.. table:: **Table 23** Parameters in the response body + + +-----------------------+-----------------------+-------------------------+ + | Parameter | Type | Description | + +=======================+=======================+=========================+ + | errorCode | String | Error code. | + | | | | + | | | Minimum length: **8** | + | | | | + | | | Maximum length: **36** | + +-----------------------+-----------------------+-------------------------+ + | errorMsg | String | Error message. | + | | | | + | | | Minimum length: **2** | + | | | | + | | | Maximum length: **512** | + +-----------------------+-----------------------+-------------------------+ + +Example Request +--------------- + +Creating a service mesh + +.. code-block:: text + + POST /v1/meshes + + { + "apiVersion" : "v1", + "kind" : "Mesh", + "metadata" : { + "name" : "mesh-test-api" + }, + "spec" : { + "type" : "InCluster", + "version" : "1.15.7-r1", + "region": "eu-de-01", + "extendParams" : { + "clusters" : [ { + "clusterID" : "8df4c986-b052-xxxx-xxxx-0255ac101231", + "projectID" : "719217bc273743eaxxxxxxxx8bc34480", + "installation" : { + "nodes" : { + "fieldSelector" : { + "key" : "UID", + "operator" : "In", + "values" : [ "b07b6512-b053-xxxx-xxxx-0255ac101231" ] + } + } + }, + "injection" : { + "namespaces" : { + "fieldSelector" : { + "key" : "UID", + "operator" : "In", + "values" : [ "xxxx" ] + } + } + } + } ] + } + } + } + +Example Response +---------------- + +**Status code: 201** + +The service mesh creation task is delivered and the service mesh creation starts. + +.. code-block:: + + { + "apiVersion" : "v1", + "kind" : "Mesh", + "metadata" : { + "name" : "mesh-test-api", + "uid" : "2789682f-7e1b-11ee-9662-0255ac10080a", + "creationTimestamp" : "2023-11-08T09:42:39Z" + }, + "spec" : { + "domainID": "06e6bafb794746xxxxxxxx536497ea95", + "type" : "InCluster", + "version" : "1.15.7-r1", + "region": "eu-de-01", + "extendParams" : { + "clusters" : [ { + "clusterID" : "8df4c986-b052-xxxx-xxxx-0255ac101231", + "region": "eu-de-01", + "projectID" : "719217bc273743eaxxxxxxxx8bc34480", + "provider": "CCE", + "proxyMode": "sidecar", + "installation" : { + "nodes" : { + "fieldSelector" : { + "key" : "UID", + "operator" : "In", + "values" : [ "b07b6512-b053-xxxx-xxxx-0255ac101231" ] + } + } + }, + "injection" : { + "namespaces" : { + "fieldSelector" : { + "key" : "UID", + "operator" : "In", + "values" : [ "xxxx" ] + } + } + } + } ] + } + }, + "status" : { + "phase" : "Creating" + } + } + +Status Codes +------------ + ++-------------+-----------------------------------------------------------------------------------+ +| Status Code | Description | ++=============+===================================================================================+ +| 201 | The service mesh creation task is delivered and the service mesh creation starts. | ++-------------+-----------------------------------------------------------------------------------+ +| 400 | Verification failed due to incorrect parameters for creating the service mesh. | ++-------------+-----------------------------------------------------------------------------------+ +| 409 | The service mesh to be created conflicts with an existing service mesh. | ++-------------+-----------------------------------------------------------------------------------+ +| 500 | An error occurs during the service mesh creation. | ++-------------+-----------------------------------------------------------------------------------+ diff --git a/api-ref/source/api/service_mesh_apis/deleting_a_service_mesh.rst b/api-ref/source/api/service_mesh_apis/deleting_a_service_mesh.rst new file mode 100644 index 0000000..96d968f --- /dev/null +++ b/api-ref/source/api/service_mesh_apis/deleting_a_service_mesh.rst @@ -0,0 +1,255 @@ +:original_name: asm_api_0102.html + +.. _asm_api_0102: + +Deleting a Service Mesh +======================= + +Function +-------- + +This API is used to delete a service mesh. + +URI +--- + +DELETE /v1/meshes/{mesh_id} + +.. table:: **Table 1** Path parameters + + ========= ========= ====== ================ + Parameter Mandatory Type Description + ========= ========= ====== ================ + mesh_id Yes String Service mesh ID. + ========= ========= ====== ================ + +Request Parameters +------------------ + +.. table:: **Table 2** Request header parameters + + +-------------------+-----------+--------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Parameter | Mandatory | Type | Description | + +===================+===========+========+=====================================================================================================================================================================================+ + | X-Auth-Token | Yes | String | Requests for calling an API can be authenticated using either a token or AK/SK. If token-based authentication is used, this parameter is mandatory and must be set to a user token. | + +-------------------+-----------+--------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | X-Apply-ProjectID | Yes | String | ID of the project that the service mesh belongs to. | + +-------------------+-----------+--------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +Response Parameters +------------------- + +**Status code: 200** + +.. table:: **Table 3** Parameters in the response body + + +-----------------------+------------------------------------------------------------+------------------------------------------------------------------------------------------------+ + | Parameter | Type | Description | + +=======================+============================================================+================================================================================================+ + | apiVersion | String | API version. The value is fixed at **v1** and cannot be changed. | + +-----------------------+------------------------------------------------------------+------------------------------------------------------------------------------------------------+ + | kind | String | API type. The value is fixed at **Mesh** or **mesh** and cannot be changed. | + +-----------------------+------------------------------------------------------------+------------------------------------------------------------------------------------------------+ + | metadata | :ref:`Table4 MeshMetadata ` object | Basic information about the service mesh. Metadata is a collection of attributes. | + +-----------------------+------------------------------------------------------------+------------------------------------------------------------------------------------------------+ + | spec | :ref:`Table 5 MeshSpec ` object | Detailed description of the service mesh. ASM creates or updates the service mesh by **spec**. | + +-----------------------+------------------------------------------------------------+------------------------------------------------------------------------------------------------+ + | status | :ref:`Table 12 MeshStatus ` object | Service mesh status, | + | | | | + | | | which is automatically generated by ASM. | + +-----------------------+------------------------------------------------------------+------------------------------------------------------------------------------------------------+ + +.. _asm_api_0102___d1e1754: + +.. table:: **Table 4** MeshMetadata + + +-------------------+--------+-------------------------------------------------------------------------------------------------+ + | Parameter | Type | Description | + +===================+========+=================================================================================================+ + | name | String | Service mesh name. | + +-------------------+--------+-------------------------------------------------------------------------------------------------+ + | uid | String | Service mesh ID, which is unique and automatically generated after the service mesh is created. | + +-------------------+--------+-------------------------------------------------------------------------------------------------+ + | creationTimestamp | String | Time when the service mesh was created. | + +-------------------+--------+-------------------------------------------------------------------------------------------------+ + +.. _asm_api_0102___d1e1829: + +.. table:: **Table 5** MeshSpec + + +-----------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+ + | Parameter | Type | Description | + +=======================+=================================================================+=====================================================================================================================================+ + | region | String | Region where the control plane components of the service mesh are located. | + +-----------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+ + | type | String | Service mesh type. | + | | | | + | | | **InCluster**: service mesh with an in-cluster control plane. The value is **InCluster** for the service mesh of the Basic edition. | + +-----------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+ + | version | String | Service mesh version. | + +-----------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+ + | extendParams | :ref:`Table 6 MeshExtendParams ` object | Extensions of the service mesh. | + +-----------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+ + +.. _asm_api_0102___d1e1892: + +.. table:: **Table 6** MeshExtendParams + + +-----------+----------------------------------------------------------------------+----------------------------------------------------------------------------+ + | Parameter | Type | Description | + +===========+======================================================================+============================================================================+ + | clusters | Array of :ref:`Table 7 MeshCluster ` objects | Information about clusters in service meshes (only for the Basic edition). | + +-----------+----------------------------------------------------------------------+----------------------------------------------------------------------------+ + +.. _asm_api_0102___d1e1924: + +.. table:: **Table 7** MeshCluster + + +-----------+--------+-------------------------------------------------------------------------------+ + | Parameter | Type | Description | + +===========+========+===============================================================================+ + | clusterID | String | Cluster ID, which is unique and can be used to query the cluster to be added. | + +-----------+--------+-------------------------------------------------------------------------------+ + | projectID | String | ID of the project that the cluster belongs to. | + +-----------+--------+-------------------------------------------------------------------------------+ + +.. _asm_api_0102___d1e2130: + +.. table:: **Table 8** MeshStatus + + +-----------------------+-----------------------+------------------------------------------------------------------+ + | Parameter | Type | Description | + +=======================+=======================+==================================================================+ + | phase | String | Service mesh status. The options are as follows: | + | | | | + | | | - **Running**: The service mesh is running. | + | | | - **Creating**: The service mesh is being created. | + | | | - **CreateFailed**: The service mesh fails to be created. | + | | | - **Deleting**: The service mesh is being deleted. | + | | | - **DeleteFailed**: The service mesh fails to be deleted. | + | | | - **Upgrading**: The service mesh is being upgraded. | + | | | - **UpgradeFailed**: The service mesh fails to be upgraded. | + | | | - **RollingBack**: The service mesh is being rolled back. | + | | | - **RollbackFailed**: The service mesh fails to be rolled back. | + +-----------------------+-----------------------+------------------------------------------------------------------+ + | updateTimestamp | String | Time when the service mesh was updated. | + +-----------------------+-----------------------+------------------------------------------------------------------+ + +**Status code: 400** + +.. table:: **Table 9** Parameters in the response body + + +-----------------------+-----------------------+-------------------------+ + | Parameter | Type | Description | + +=======================+=======================+=========================+ + | errorCode | String | Error code. | + | | | | + | | | Minimum length: **8** | + | | | | + | | | Maximum length: **36** | + +-----------------------+-----------------------+-------------------------+ + | errorMsg | String | Error message. | + | | | | + | | | Minimum length: **2** | + | | | | + | | | Maximum length: **512** | + +-----------------------+-----------------------+-------------------------+ + +**Status code: 404** + +.. table:: **Table 10** Parameters in the response body + + +-----------------------+-----------------------+-------------------------+ + | Parameter | Type | Description | + +=======================+=======================+=========================+ + | errorCode | String | Error code. | + | | | | + | | | Minimum length: **8** | + | | | | + | | | Maximum length: **36** | + +-----------------------+-----------------------+-------------------------+ + | errorMsg | String | Error message. | + | | | | + | | | Minimum length: **2** | + | | | | + | | | Maximum length: **512** | + +-----------------------+-----------------------+-------------------------+ + +**Status code: 500** + +.. table:: **Table 11** Parameters in the response body + + +-----------------------+-----------------------+-------------------------+ + | Parameter | Type | Description | + +=======================+=======================+=========================+ + | errorCode | String | Error code. | + | | | | + | | | Minimum length: **8** | + | | | | + | | | Maximum length: **36** | + +-----------------------+-----------------------+-------------------------+ + | errorMsg | String | Error message. | + | | | | + | | | Minimum length: **2** | + | | | | + | | | Maximum length: **512** | + +-----------------------+-----------------------+-------------------------+ + +Example Request +--------------- + +None + +Example Response +---------------- + +**Status code: 200** + +The service mesh deletion task is delivered and the service mesh deletion starts. + +.. code-block:: + + { + "kind" : "Mesh", + "apiVersion" : "v1", + "metadata" : { + "name" : "mesh-test-api1", + "uid" : "b0906529-5871-xxxx-xxxx-8f93784d267c", + "creationTimestamp" : "2024-12-10T07:29:37Z" + }, + "spec" : { + "domainID": "06e6bafb794746xxxxxxxx536497ea95", + "region" : "eu-de-01", + "type" : "InCluster", + "version" : "1.15.7-r4", + "extendParams" : { + "clusters" : [ { + "clusterID" : "8df4c986-b052-xxxx-xxxx-0255ac101231", + "meshID": "b0906529-5871-xxxx-xxxx-8f93784d267c", + "region": "eu-de-01", + "projectID" : "719217bc273743xxxxxxxxae8bc34480" , + "provider": "CCE", + "proxyMode": "sidecar" + } ] + } + }, + "status" : { + "phase" : "Deleting", + "updateTimestamp" : "2024-12-10T07:36:42Z" + } + } + +Status Codes +------------ + ++-------------+------------------------------------------------------------------------------------------+ +| Status Code | Description | ++=============+==========================================================================================+ +| 200 | The service mesh deletion task is delivered and the service mesh deletion starts. | ++-------------+------------------------------------------------------------------------------------------+ +| 400 | Verification failed due to incorrect parameters for deleting the specified service mesh. | ++-------------+------------------------------------------------------------------------------------------+ +| 404 | The specified service mesh is not found. | ++-------------+------------------------------------------------------------------------------------------+ +| 500 | An error occurs during the service mesh deletion. | ++-------------+------------------------------------------------------------------------------------------+ diff --git a/api-ref/source/api/service_mesh_apis/index.rst b/api-ref/source/api/service_mesh_apis/index.rst new file mode 100644 index 0000000..c35c8b0 --- /dev/null +++ b/api-ref/source/api/service_mesh_apis/index.rst @@ -0,0 +1,20 @@ +:original_name: asm_api_0100.html + +.. _asm_api_0100: + +Service Mesh APIs +================= + +- :ref:`Creating a Service Mesh ` +- :ref:`Deleting a Service Mesh ` +- :ref:`Querying a Service Mesh ` +- :ref:`Querying the Service Mesh List ` + +.. toctree:: + :maxdepth: 1 + :hidden: + + creating_a_service_mesh + deleting_a_service_mesh + querying_a_service_mesh + querying_the_service_mesh_list diff --git a/api-ref/source/api/service_mesh_apis/querying_a_service_mesh.rst b/api-ref/source/api/service_mesh_apis/querying_a_service_mesh.rst new file mode 100644 index 0000000..cc5782f --- /dev/null +++ b/api-ref/source/api/service_mesh_apis/querying_a_service_mesh.rst @@ -0,0 +1,255 @@ +:original_name: asm_api_0103.html + +.. _asm_api_0103: + +Querying a Service Mesh +======================= + +Function +-------- + +This API is used to obtain details about a service mesh. + +URI +--- + +GET /v1/meshes/{mesh_id} + +.. table:: **Table 1** Path parameters + + ========= ========= ====== ================ + Parameter Mandatory Type Description + ========= ========= ====== ================ + mesh_id Yes String Service mesh ID. + ========= ========= ====== ================ + +Request Parameters +------------------ + +.. table:: **Table 2** Request header parameters + + +-------------------+-----------+--------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Parameter | Mandatory | Type | Description | + +===================+===========+========+=====================================================================================================================================================================================+ + | X-Auth-Token | Yes | String | Requests for calling an API can be authenticated using either a token or AK/SK. If token-based authentication is used, this parameter is mandatory and must be set to a user token. | + +-------------------+-----------+--------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | X-Apply-ProjectID | Yes | String | ID of the project that the service mesh belongs to. | + +-------------------+-----------+--------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +Response Parameters +------------------- + +**Status code: 200** + +.. table:: **Table 3** Parameters in the response body + + +-----------------------+------------------------------------------------------------+------------------------------------------------------------------------------------------------+ + | Parameter | Type | Description | + +=======================+============================================================+================================================================================================+ + | apiVersion | String | API version. The value is fixed at **v1** and cannot be changed. | + +-----------------------+------------------------------------------------------------+------------------------------------------------------------------------------------------------+ + | kind | String | API type. The value is fixed at **Mesh** or **mesh** and cannot be changed. | + +-----------------------+------------------------------------------------------------+------------------------------------------------------------------------------------------------+ + | metadata | :ref:`Table4 MeshMetadata ` object | Basic information about the service mesh. Metadata is a collection of attributes. | + +-----------------------+------------------------------------------------------------+------------------------------------------------------------------------------------------------+ + | spec | :ref:`Table 5 MeshSpec ` object | Detailed description of the service mesh. ASM creates or updates the service mesh by **spec**. | + +-----------------------+------------------------------------------------------------+------------------------------------------------------------------------------------------------+ + | status | :ref:`Table 8 MeshStatus ` object | Service mesh status, | + | | | | + | | | which is automatically generated by ASM. | + +-----------------------+------------------------------------------------------------+------------------------------------------------------------------------------------------------+ + +.. _asm_api_0103___d1e2597: + +.. table:: **Table 4** MeshMetadata + + +-------------------+--------+-------------------------------------------------------------------------------------------------+ + | Parameter | Type | Description | + +===================+========+=================================================================================================+ + | name | String | Service mesh name. | + +-------------------+--------+-------------------------------------------------------------------------------------------------+ + | uid | String | Service mesh ID, which is unique and automatically generated after the service mesh is created. | + +-------------------+--------+-------------------------------------------------------------------------------------------------+ + | creationTimestamp | String | Time when the service mesh was created. | + +-------------------+--------+-------------------------------------------------------------------------------------------------+ + +.. _asm_api_0103___d1e2672: + +.. table:: **Table 5** MeshSpec + + +-----------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+ + | Parameter | Type | Description | + +=======================+=================================================================+=====================================================================================================================================+ + | region | String | Region where the control plane components of the service mesh are located. | + +-----------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+ + | type | String | Service mesh type. | + | | | | + | | | **InCluster**: service mesh with an in-cluster control plane. The value is **InCluster** for the service mesh of the Basic edition. | + +-----------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+ + | version | String | Service mesh version. | + +-----------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+ + | extendParams | :ref:`Table 6 MeshExtendParams ` object | Extensions of the service mesh. | + +-----------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+ + +.. _asm_api_0103___d1e2735: + +.. table:: **Table 6** MeshExtendParams + + +-----------+----------------------------------------------------------------------+----------------------------------------------------------------------------+ + | Parameter | Type | Description | + +===========+======================================================================+============================================================================+ + | clusters | Array of :ref:`Table 7 MeshCluster ` objects | Information about clusters in service meshes (only for the Basic edition). | + +-----------+----------------------------------------------------------------------+----------------------------------------------------------------------------+ + +.. _asm_api_0103___d1e2767: + +.. table:: **Table 7** MeshCluster + + +-----------+--------+-------------------------------------------------------------------------------+ + | Parameter | Type | Description | + +===========+========+===============================================================================+ + | clusterID | String | Cluster ID, which is unique and can be used to query the cluster to be added. | + +-----------+--------+-------------------------------------------------------------------------------+ + | projectID | String | ID of the project that the cluster belongs to. | + +-----------+--------+-------------------------------------------------------------------------------+ + +.. _asm_api_0103___d1e2973: + +.. table:: **Table 8** MeshStatus + + +-----------------------+-----------------------+------------------------------------------------------------------+ + | Parameter | Type | Description | + +=======================+=======================+==================================================================+ + | phase | String | Service mesh status. The options are as follows: | + | | | | + | | | - **Running**: The service mesh is running. | + | | | - **Creating**: The service mesh is being created. | + | | | - **CreateFailed**: The service mesh fails to be created. | + | | | - **Deleting**: The service mesh is being deleted. | + | | | - **DeleteFailed**: The service mesh fails to be deleted. | + | | | - **Upgrading**: The service mesh is being upgraded. | + | | | - **UpgradeFailed**: The service mesh fails to be upgraded. | + | | | - **RollingBack**: The service mesh is being rolled back. | + | | | - **RollbackFailed**: The service mesh fails to be rolled back. | + +-----------------------+-----------------------+------------------------------------------------------------------+ + | updateTimestamp | String | Time when the service mesh was updated. | + +-----------------------+-----------------------+------------------------------------------------------------------+ + +**Status code: 400** + +.. table:: **Table 9** Parameters in the response body + + +-----------------------+-----------------------+-------------------------+ + | Parameter | Type | Description | + +=======================+=======================+=========================+ + | errorCode | String | Error code. | + | | | | + | | | Minimum length: **8** | + | | | | + | | | Maximum length: **36** | + +-----------------------+-----------------------+-------------------------+ + | errorMsg | String | Error message. | + | | | | + | | | Minimum length: **2** | + | | | | + | | | Maximum length: **512** | + +-----------------------+-----------------------+-------------------------+ + +**Status code: 404** + +.. table:: **Table 10** Parameters in the response body + + +-----------------------+-----------------------+-------------------------+ + | Parameter | Type | Description | + +=======================+=======================+=========================+ + | errorCode | String | Error code. | + | | | | + | | | Minimum length: **8** | + | | | | + | | | Maximum length: **36** | + +-----------------------+-----------------------+-------------------------+ + | errorMsg | String | Error message. | + | | | | + | | | Minimum length: **2** | + | | | | + | | | Maximum length: **512** | + +-----------------------+-----------------------+-------------------------+ + +**Status code: 500** + +.. table:: **Table 11** Parameters in the response body + + +-----------------------+-----------------------+-------------------------+ + | Parameter | Type | Description | + +=======================+=======================+=========================+ + | errorCode | String | Error code. | + | | | | + | | | Minimum length: **8** | + | | | | + | | | Maximum length: **36** | + +-----------------------+-----------------------+-------------------------+ + | errorMsg | String | Error message. | + | | | | + | | | Minimum length: **2** | + | | | | + | | | Maximum length: **512** | + +-----------------------+-----------------------+-------------------------+ + +Example Request +--------------- + +None + +Example Response +---------------- + +**Status code: 200** + +The details about the service mesh are obtained. + +.. code-block:: + + { + "kind" : "Mesh", + "apiVersion" : "v1", + "metadata" : { + "name" : "mesh-test-api1", + "uid" : "b0906529-5871-xxxx-xxxx-8f93784d267c", + "creationTimestamp" : "2024-12-10T07:29:37Z" + }, + "spec" : { + "domainID": "06e6bafb794746xxxxxxxx536497ea95", + "region" : "eu-de-01", + "type" : "InCluster", + "version" : "1.15.7-r4", + "extendParams" : { + "clusters" : [ { + "clusterID" : "8df4c986-b052-xxxx-xxxx-0255ac101231", + "meshID": "729f4f96-5790-xxxx-xxxx-f9afaac38726", + "region": "eu-de-01", + "projectID" : "719217bc273743xxxxxxxxae8bc34480" + "provider": "CCE", + "proxyMode": "sidecar" + } ] + } + }, + "status" : { + "phase" : "Running", + "updateTimestamp" : "2024-12-10T07:36:42Z" + } + } + +Status Codes +------------ + ++-------------+---------------------------------------------------------------------------------------------------+ +| Status Code | Description | ++=============+===================================================================================================+ +| 200 | The details about the service mesh are obtained. | ++-------------+---------------------------------------------------------------------------------------------------+ +| 400 | Verification failed due to incorrect parameters for obtaining the details about the service mesh. | ++-------------+---------------------------------------------------------------------------------------------------+ +| 404 | The specified service mesh is not found. | ++-------------+---------------------------------------------------------------------------------------------------+ +| 500 | An error occurs during the service mesh query. | ++-------------+---------------------------------------------------------------------------------------------------+ diff --git a/api-ref/source/api/service_mesh_apis/querying_the_service_mesh_list.rst b/api-ref/source/api/service_mesh_apis/querying_the_service_mesh_list.rst new file mode 100644 index 0000000..c82d679 --- /dev/null +++ b/api-ref/source/api/service_mesh_apis/querying_the_service_mesh_list.rst @@ -0,0 +1,271 @@ +:original_name: asm_api_0104.html + +.. _asm_api_0104: + +Querying the Service Mesh List +============================== + +Function +-------- + +This API is used to obtain details about all service meshes. + +URI +--- + +GET /v1/meshes + +Request Parameters +------------------ + +.. table:: **Table 1** Request header parameters + + +-------------------+-----------+--------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Parameter | Mandatory | Type | Description | + +===================+===========+========+=====================================================================================================================================================================================+ + | X-Auth-Token | Yes | String | Requests for calling an API can be authenticated using either a token or AK/SK. If token-based authentication is used, this parameter is mandatory and must be set to a user token. | + +-------------------+-----------+--------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | X-Apply-ProjectID | Yes | String | ID of the project that the service mesh belongs to. | + +-------------------+-----------+--------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +Response Parameters +------------------- + +**Status code: 200** + +.. table:: **Table 2** Parameters in the response body + + +------------+---------------------------------------------------------------+---------------------------------------------------------------------+ + | Parameter | Type | Description | + +============+===============================================================+=====================================================================+ + | apiVersion | String | API version. The value is fixed at **v1** and cannot be changed. | + +------------+---------------------------------------------------------------+---------------------------------------------------------------------+ + | kind | String | API type. The value is fixed at **MeshList** and cannot be changed. | + +------------+---------------------------------------------------------------+---------------------------------------------------------------------+ + | items | Array of :ref:`Table 3 Mesh ` objects | Service mesh list. | + +------------+---------------------------------------------------------------+---------------------------------------------------------------------+ + +.. _asm_api_0104___d1e3384: + +.. table:: **Table 3** Mesh + + +-----------------------+-------------------------------------------------------------+------------------------------------------------------------------------------------------------+ + | Parameter | Type | Description | + +=======================+=============================================================+================================================================================================+ + | apiVersion | String | API version. The value is fixed at **v1** and cannot be changed. | + +-----------------------+-------------------------------------------------------------+------------------------------------------------------------------------------------------------+ + | kind | String | API type. The value is fixed at **Mesh** or **mesh** and cannot be changed. | + +-----------------------+-------------------------------------------------------------+------------------------------------------------------------------------------------------------+ + | metadata | :ref:`Table 4 MeshMetadata ` object | Basic information about the service mesh. Metadata is a collection of attributes. | + +-----------------------+-------------------------------------------------------------+------------------------------------------------------------------------------------------------+ + | spec | :ref:`Table 5 MeshSpec ` object | Detailed description of the service mesh. ASM creates or updates the service mesh by **spec**. | + +-----------------------+-------------------------------------------------------------+------------------------------------------------------------------------------------------------+ + | status | :ref:`Table 8 MeshStatus ` object | Service mesh status, | + | | | | + | | | which is automatically generated by ASM. | + +-----------------------+-------------------------------------------------------------+------------------------------------------------------------------------------------------------+ + +.. _asm_api_0104___d1e3461: + +.. table:: **Table 4** MeshMetadata + + +-------------------+--------+-------------------------------------------------------------------------------------------------+ + | Parameter | Type | Description | + +===================+========+=================================================================================================+ + | name | String | Service mesh name. | + +-------------------+--------+-------------------------------------------------------------------------------------------------+ + | uid | String | Service mesh ID, which is unique and automatically generated after the service mesh is created. | + +-------------------+--------+-------------------------------------------------------------------------------------------------+ + | creationTimestamp | String | Time when the service mesh was created. | + +-------------------+--------+-------------------------------------------------------------------------------------------------+ + +.. _asm_api_0104___d1e3536: + +.. table:: **Table 5** MeshSpec + + +-----------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+ + | Parameter | Type | Description | + +=======================+=================================================================+=====================================================================================================================================+ + | region | String | Region where the control plane components of the service mesh are located. | + +-----------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+ + | type | String | Service mesh type. | + | | | | + | | | **InCluster**: service mesh with an in-cluster control plane. The value is **InCluster** for the service mesh of the Basic edition. | + +-----------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+ + | version | String | Service mesh version. | + +-----------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+ + | extendParams | :ref:`Table 6 MeshExtendParams ` object | Extensions of the service mesh. | + +-----------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+ + +.. _asm_api_0104___d1e3599: + +.. table:: **Table 6** MeshExtendParams + + +-----------+----------------------------------------------------------------------+----------------------------------------------------------------------------+ + | Parameter | Type | Description | + +===========+======================================================================+============================================================================+ + | clusters | Array of :ref:`Table 7 MeshCluster ` objects | Information about clusters in service meshes (only for the Basic edition). | + +-----------+----------------------------------------------------------------------+----------------------------------------------------------------------------+ + +.. _asm_api_0104___d1e3631: + +.. table:: **Table 7** MeshCluster + + +-----------+--------+-------------------------------------------------------------------------------+ + | Parameter | Type | Description | + +===========+========+===============================================================================+ + | clusterID | String | Cluster ID, which is unique and can be used to query the cluster to be added. | + +-----------+--------+-------------------------------------------------------------------------------+ + | projectID | String | ID of the project that the cluster belongs to. | + +-----------+--------+-------------------------------------------------------------------------------+ + +.. _asm_api_0104___d1e3837: + +.. table:: **Table 8** MeshStatus + + +-----------------------+-----------------------+------------------------------------------------------------------+ + | Parameter | Type | Description | + +=======================+=======================+==================================================================+ + | phase | String | Service mesh status. The options are as follows: | + | | | | + | | | - **Running**: The service mesh is running. | + | | | - **Creating**: The service mesh is being created. | + | | | - **CreateFailed**: The service mesh fails to be created. | + | | | - **Deleting**: The service mesh is being deleted. | + | | | - **DeleteFailed**: The service mesh fails to be deleted. | + | | | - **Upgrading**: The service mesh is being upgraded. | + | | | - **UpgradeFailed**: The service mesh fails to be upgraded. | + | | | - **RollingBack**: The service mesh is being rolled back. | + | | | - **RollbackFailed**: The service mesh fails to be rolled back. | + +-----------------------+-----------------------+------------------------------------------------------------------+ + | updateTimestamp | String | Time when the service mesh was updated. | + +-----------------------+-----------------------+------------------------------------------------------------------+ + +**Status code: 400** + +.. table:: **Table 9** Parameters in the response body + + +-----------------------+-----------------------+-------------------------+ + | Parameter | Type | Description | + +=======================+=======================+=========================+ + | errorCode | String | Error code. | + | | | | + | | | Minimum length: **8** | + | | | | + | | | Maximum length: **36** | + +-----------------------+-----------------------+-------------------------+ + | errorMsg | String | Error message. | + | | | | + | | | Minimum length: **2** | + | | | | + | | | Maximum length: **512** | + +-----------------------+-----------------------+-------------------------+ + +**Status code: 500** + +.. table:: **Table 10** Parameters in the response body + + +-----------------------+-----------------------+-------------------------+ + | Parameter | Type | Description | + +=======================+=======================+=========================+ + | errorCode | String | Error code. | + | | | | + | | | Minimum length: **8** | + | | | | + | | | Maximum length: **36** | + +-----------------------+-----------------------+-------------------------+ + | errorMsg | String | Error message. | + | | | | + | | | Minimum length: **2** | + | | | | + | | | Maximum length: **512** | + +-----------------------+-----------------------+-------------------------+ + +Example Request +--------------- + +None + +Example Response +---------------- + +**Status code: 200** + +The details about all service meshes are obtained. + +.. code-block:: + + { + "kind" : "MeshList", + "apiVersion" : "v1", + "items" : [ { + "kind" : "Mesh", + "apiVersion" : "v1", + "metadata" : { + "name" : "mesh-test-api1", + "uid" : "b0906529-5871-xxxx-xxxx-8f93784d267c", + "creationTimestamp" : "2024-12-10T07:29:37Z" + }, + "spec" : { + "domainID": "06e6bafb794746xxxxxxxx536497ea95", + "region" : "eu-de-01", + "type" : "InCluster", + "version" : "1.15.7-r4", + "extendParams" : { + "clusters" : [ { + "clusterID" : "8df4c986-b052-xxxx-xxxx-0255ac101231", + "meshID": "b0906529-5871-xxxx-xxxx-8f93784d267c", + "region": "eu-de-01", + "projectID" : "719217bc273743xxxxxxxxae8bc34480" + "provider": "CCE", + "proxyMode": "sidecar" + } ] + } + }, + "status" : { + "phase" : "Running", + "updateTimestamp" : "2024-12-10T07:36:42Z" + } + }, { + "kind" : "Mesh", + "apiVersion" : "v1", + "metadata" : { + "name" : "mesh-test-api1", + "uid" : "b6b976fa-8c96-xxxx-xxxx-42e03a0cb8ab", + "creationTimestamp" : "2024-12-03T11:37:50Z" + }, + "spec" : { + "domainID": "06e6bafb794746xxxxxxxx536497ea95", + "region" : "eu-de-01", + "type" : "InCluster", + "version" : "1.18.7-r4", + "extendParams" : { + "clusters" : [ { + "clusterID" : "12ce3034-294c-xxxx-xxxx-0255ac1001ba", + "meshID": "b6b976fa-8c96-xxxx-xxxx-42e03a0cb8ab", + "region": "eu-de-01", + "projectID" : "719217bc273743xxxxxxxxae8bc34480", + "provider": "CCE", + "proxyMode": "sidecar" + } ] + } + }, + "status" : { + "phase" : "Running", + "updateTimestamp" : "2024-12-10T07:36:42Z" + } + } ] + } + +Status Codes +------------ + ++-------------+-----------------------------------------------------------------------------------------------------+ +| Status Code | Description | ++=============+=====================================================================================================+ +| 200 | The details about all service meshes are obtained. | ++-------------+-----------------------------------------------------------------------------------------------------+ +| 400 | Verification failed due to incorrect parameters for obtaining the details about all service meshes. | ++-------------+-----------------------------------------------------------------------------------------------------+ +| 500 | An error occurs during the service mesh query. | ++-------------+-----------------------------------------------------------------------------------------------------+ diff --git a/api-ref/source/api_usage_guidelines.rst b/api-ref/source/api_usage_guidelines.rst new file mode 100644 index 0000000..536fdff --- /dev/null +++ b/api-ref/source/api_usage_guidelines.rst @@ -0,0 +1,12 @@ +:original_name: asm_api_0027.html + +.. _asm_api_0027: + +API Usage Guidelines +==================== + +Public cloud APIs comply with the RESTful API design principles. REST-based web services are organized into resources. Each resource is identified by one or more Uniform Resource Identifiers (URIs). An application accesses a resource based on the resource's Uniform Resource Locator (URL). A URL is usually in the following format: *https://Endpoint/URI*. In the URL, **uri** indicates the resource path, that is, the API access path. + +Public cloud APIs use HTTPS as the transmission protocol. Requests/Responses are transmitted by using JSON messages, with media type represented by **application/json**. + +For details about how to use APIs, see `API Usage Guidelines `__. diff --git a/api-ref/source/appendix/error_codes.rst b/api-ref/source/appendix/error_codes.rst new file mode 100644 index 0000000..4b80267 --- /dev/null +++ b/api-ref/source/appendix/error_codes.rst @@ -0,0 +1,45 @@ +:original_name: asm_api_0018.html + +.. _asm_api_0018: + +Error Codes +=========== + +If an API fails to be called, no service data will be returned. You can identify the cause based on the error code of each API. If an error occurs in API calling, HTTP status code 4\ *xx* or 5\ *xx* will be returned. The response body contains the specific error code and information. + +Error Response Body Format +-------------------------- + +If an error occurs during API calling, an error code and a message will be displayed. The following shows an error response body. + +.. code-block:: + + { + "errorMsg": Modify the request body based on the returned message and the ASM API documentation, or contact technical support. + "errorCode": "ASM.01400001" + } + +In the preceding information, **error_code** indicates an error code, and **error_msg** describes the error. + +Error Code Description +---------------------- + +.. table:: **Table 1** Error codes + + +-------------+--------------+------------------------------------+--------------------------------------------+--------------------------------------------------------------------------------------------------------------------+ + | Status Code | Error Code | Error Message | Description | Troubleshooting | + +=============+==============+====================================+============================================+====================================================================================================================+ + | 400 | ASM.01400001 | Invalid request. | The request body is invalid. | Modify the request body based on the returned message and the ASM API documentation, or contact technical support. | + +-------------+--------------+------------------------------------+--------------------------------------------+--------------------------------------------------------------------------------------------------------------------+ + | 401 | ASM.01401001 | Authorization failed. | The authentication failed. | See the returned message or contact technical support. | + +-------------+--------------+------------------------------------+--------------------------------------------+--------------------------------------------------------------------------------------------------------------------+ + | 403 | ASM.01403001 | Forbidden. | The access is denied. | See the returned message or contact technical support. | + +-------------+--------------+------------------------------------+--------------------------------------------+--------------------------------------------------------------------------------------------------------------------+ + | 404 | ASM.01404001 | Resource not found. | The resource is not found. | Check whether the resource to be accessed has been deleted. | + +-------------+--------------+------------------------------------+--------------------------------------------+--------------------------------------------------------------------------------------------------------------------+ + | 409 | ASM.01409001 | The resource already exists. | The resource already exists. | Delete the resource and try again. | + +-------------+--------------+------------------------------------+--------------------------------------------+--------------------------------------------------------------------------------------------------------------------+ + | 429 | ASM.01429001 | Resource locked by other requests. | The resource is locked by another request. | See the returned message or contact technical support. | + +-------------+--------------+------------------------------------+--------------------------------------------+--------------------------------------------------------------------------------------------------------------------+ + | 500 | ASM.01500001 | Internal error. | An internal error occurred. | See the returned message or contact technical support. | + +-------------+--------------+------------------------------------+--------------------------------------------+--------------------------------------------------------------------------------------------------------------------+ diff --git a/api-ref/source/appendix/index.rst b/api-ref/source/appendix/index.rst new file mode 100644 index 0000000..54fe4fd --- /dev/null +++ b/api-ref/source/appendix/index.rst @@ -0,0 +1,18 @@ +:original_name: asm_api_0016.html + +.. _asm_api_0016: + +Appendix +======== + +- :ref:`Status Codes ` +- :ref:`Error Codes ` +- :ref:`Obtaining a Project ID ` + +.. toctree:: + :maxdepth: 1 + :hidden: + + status_codes + error_codes + obtaining_a_project_id diff --git a/api-ref/source/appendix/obtaining_a_project_id.rst b/api-ref/source/appendix/obtaining_a_project_id.rst new file mode 100644 index 0000000..235b202 --- /dev/null +++ b/api-ref/source/appendix/obtaining_a_project_id.rst @@ -0,0 +1,51 @@ +:original_name: asm_api_0019.html + +.. _asm_api_0019: + +Obtaining a Project ID +====================== + +Obtaining a Project ID by Calling an API +---------------------------------------- + +A project ID can be obtained by calling a specific API. For details, see `Querying Project Information Based on the Specified Criteria `__. + +The API used to obtain a project ID is **GET https://**\ *{Endpoint}*\ **/v3/projects/**, where *{Endpoint}* indicates the IAM endpoint. You can obtain the IAM endpoint from `Regions and Endpoints `__. + +In the following example, **id** indicates the project ID. + +.. code-block:: + + { + "projects": [ + { + "domain_id": "65382450e8f64ac0870cd180d14e684b", + "is_domain": false, + "parent_id": "65382450e8f64ac0870cd180d14e684b", + "name": "eu-de", + "description": "", + "links": { + "next": null, + "previous": null, + "self": "https://www.example.com/v3/projects/a4a5d4098fb4474fa22cd05f897d6b99" + }, + "id": "a4a5d4098fb4474fa22cd05f897d6b99", + "enabled": true + } + ], + "links": { + "next": null, + "previous": null, + "self": "https://www.example.com/v3/projects" + } + } + +Obtaining a Project ID from the Console +--------------------------------------- + +A project ID is required for some URLs when an API is called. To obtain a project ID, perform the following operations: + +#. Log in to the management console. +#. Click the username and select **My Credentials** from the drop-down list. On the **API Credentials** page, view the project ID in the project list. + +If a project contains multiple sub-projects, click the plus (+) sign to view sub-project IDs. diff --git a/api-ref/source/appendix/status_codes.rst b/api-ref/source/appendix/status_codes.rst new file mode 100644 index 0000000..0837411 --- /dev/null +++ b/api-ref/source/appendix/status_codes.rst @@ -0,0 +1,122 @@ +:original_name: asm_api_0017.html + +.. _asm_api_0017: + +Status Codes +============ + +:ref:`Table 1 ` describes status codes. + +.. _asm_api_0017__t42cb9dbc087b455fbcc522195c172e5b: + +.. table:: **Table 1** Status codes + + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Status Code | Message Title | Description | + +=======================+=================================+======================================================================================================================================================================================================================================================================================================================================================================+ + | 100 | Continue | The client continues sending the request. | + | | | | + | | | The server has received the initial part of the request and the client should continue sending the remaining part. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 101 | Switching Protocols | The protocol should be switched and can only be switched to a more advanced protocol. | + | | | | + | | | For example, the current HTTP protocol is switched to a later version. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 201 | Created | The request for creating a resource has been fulfilled. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 202 | Accepted | The request has been accepted, but the processing has not been completed. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 203 | Non-Authoritative Information | The server successfully processed the request, but is returning information that may be from another source. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 204 | NoContent | The server has successfully processed the request, but is not returning any response body. | + | | | | + | | | The status code is returned in response to an HTTP **OPTIONS** request. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 205 | Reset Content | The server has fulfilled the request, but the requester is required to reset the content. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 206 | Partial Content | The server has successfully processed a part of a **GET** request. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 300 | Multiple Choices | There are multiple options for the requested resource. The response contains a list of resource characteristics and addresses from which the user or user agent (such as a browser) can choose the most appropriate one. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 301 | Moved Permanently | The requested resource has been assigned a new permanent URI, and the new URI is contained in the response. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 302 | Found | The requested resource resides temporarily under a different URI. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 303 | See Other | The response to the request can be found under a different URI. | + | | | | + | | | It should be retrieved using a GET or POST method. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 304 | Not Modified | The requested resource has not been modified. If the server returns this status code, no resource will be returned. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 305 | Use Proxy | The requested resource must be accessed through a proxy. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 306 | Unused | The HTTP status code is no longer used. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 400 | BadRequest | The request is invalid. | + | | | | + | | | The client should modify the request instead of re-initiating it. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 401 | Unauthorized | The authorization information provided by the client is incorrect or invalid. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 402 | Payment Required | This status code is reserved for future use. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 403 | Forbidden | The request is denied. | + | | | | + | | | The server has received the request and understood it, but the server is refusing to respond to it. The client should not repeat the request without modifications. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 404 | NotFound | The requested resource could not be found. | + | | | | + | | | The client should modify the request instead of re-initiating it. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 405 | MethodNotAllowed | The method specified in the request is not supported for the requested resource. | + | | | | + | | | The client should modify the request instead of re-initiating it. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 406 | Not Acceptable | The server cannot fulfill the request based on the content characteristics of the request. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 407 | Proxy Authentication Required | This status code is similar to 401, but the client must first authenticate itself with the proxy. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 408 | Request Time-out | The server times out when waiting for the request. | + | | | | + | | | The client may repeat the request without modifications at any later time. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 409 | Conflict | The request could not be completed due to a conflict. | + | | | | + | | | The resource that the client attempts to create already exits, or the request fails to be processed because of the update of the conflict request. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 410 | Gone | The requested resource could not be found. | + | | | | + | | | The requested resource has been deleted permanently. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 411 | Length Required | The server refuses to process the request without a defined **Content-Length**. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 412 | Precondition Failed | The server does not meet one of the preconditions that the requester puts on the request. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 413 | Request Entity Too Large | The request is larger than the server is willing or able to process. The server may disable the connection to prevent the client from sending requests consecutively. If the server cannot process the request temporarily, the response will contain a **Retry-After** header field. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 414 | Request-URI Too Large | The request URI is too long for the server to process. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 415 | Unsupported Media Type | The server is unable to process the media format in the request. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 416 | Requested range not satisfiable | The requested range is invalid. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 417 | Expectation Failed | The server fails to meet the requirements of the **Expect** request header field. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 422 | UnprocessableEntity | The request is well-formed but is unable to be processed due to semantic errors. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 429 | TooManyRequests | The client sends excessive requests to the server within a given time (exceeding the limit on the access frequency of the client), or the server receives excessive requests within a given time (beyond its processing capability). In this case, the client should repeat requests after the time specified in the **Retry-After** header of the response expires. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 500 | InternalServerError | The server is able to receive the request, but it could not understand the request. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 501 | Not Implemented | The server does not support the functionality required to fulfill the request. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 502 | Bad Gateway | The server was acting as a gateway or proxy and received an invalid response from the upstream server. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 503 | ServiceUnavailable | The requested service is invalid. | + | | | | + | | | The client should modify the request instead of re-initiating it. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 504 | ServerTimeout | The request cannot be fulfilled within a given time. This status code is returned to the client only when the **Timeout** parameter is specified in the request. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 505 | HTTP Version not supported | The server does not support the HTTP protocol version used in the request. | + +-----------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ diff --git a/api-ref/source/change_history.rst b/api-ref/source/change_history.rst new file mode 100644 index 0000000..ebfaef4 --- /dev/null +++ b/api-ref/source/change_history.rst @@ -0,0 +1,19 @@ +:original_name: asm_api_0021.html + +.. _asm_api_0021: + +Change History +============== + ++-----------------------------------+------------------------------------------------------------------+ +| Release On | Description | ++===================================+==================================================================+ +| 2025-03-07 | Deleted duplicate links in :ref:`API `. | ++-----------------------------------+------------------------------------------------------------------+ +| 2024-12-11 | Based on review comments, this document is optimized as follows: | +| | | +| | - Modified the API parameters. | +| | - Added response examples. | ++-----------------------------------+------------------------------------------------------------------+ +| 2024-10-25 | First release. | ++-----------------------------------+------------------------------------------------------------------+ diff --git a/api-ref/source/conf.py b/api-ref/source/conf.py old mode 100755 new mode 100644 diff --git a/api-ref/source/docutils.conf b/api-ref/source/docutils.conf new file mode 100644 index 0000000..7cbe4c1 --- /dev/null +++ b/api-ref/source/docutils.conf @@ -0,0 +1,2 @@ +[html writers] +table-style: table, caption-top \ No newline at end of file diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index 5069b16..eb18394 100644 --- a/api-ref/source/index.rst +++ b/api-ref/source/index.rst @@ -1,3 +1,11 @@ -======================================================== -Welcome to the documentation of application-service-mesh -======================================================== +======================================== +Application Service Mesh - API Reference +======================================== + +.. toctree:: + :maxdepth: 1 + + api_usage_guidelines + api/index + appendix/index + change_history