github.com/kyma-incubator/compass/components/director@v0.0.0-20230623144113-d764f56ff805/cmd/ns-adapter/README.md (about)

     1  # Notification Service Adapter (NS-Adapter)
     2  
     3  ## Overview of terms
     4  
     5  - *SAP Cloud Connector (SCC)* - A component, which runs on-premise in a customer data center. It provides connectivity between Cloud and on-premise systems.
     6  - *Notification Service (NS)* - A Cloud service where various SCCs are registered. Cloud applications connect to on-premise systems, which are exposed by these registered SCCs. An SCC registers in the NS in the context of a subaccount. Multiple SCCs can be registered in the NS of a single subaccount, as well as, a single SCC can be registered in the NS of multiple subaccounts. Only applications that are running in the subaccount where the SCC is registered can access the on-premise systems exposed by the SCC.
     7  - *Full report* - NS reports to CMP all SCCs that are currently registered in the NS. The report includes all on-premise systems exposed by the SCCs.
     8  - *Delta (incremental) report* - NS reports to CMP only the SCCs, which changed since the previous report.
     9  
    10  ## Details
    11  
    12  This section describes the API schema that a Notification Service must implement to integrate with the NS-Adapter.
    13  
    14  ### Authorization
    15  
    16  In case of a local installation, using the run.sh script, a valid JSON Web Token (JWT) with `tenant.consumerTenant` and `tenant.externalTenant` claims should be provided. The `tenant.consumerTenant` and `tenant.externalTenant` should contain the internal ID and the external ID from the existing `business_tenant_mappings` record in the Compass database.
    17  
    18  ### Reports
    19  The NS-Adapter gets the following types of reports: 
    20  - `delta` - A regular incremental report on short time intervals, for example, once in 5 minutes.
    21  - `full` - A regular full report on long time periods, for example once per hour.
    22  
    23  Each report comprises a list of SCCs. Each SCC contains a list of exposed on-premise systems. When a report comes, the NS-Adapter tries to identify for each SCC the following:
    24  
    25  - The systems that are new, to create new entities in CMP for them.
    26  - The systems that are missing, to mark them unreachable in CMP.
    27  - The systems that were updated, to update them in CMP too.
    28  
    29  Additionally, when a full report comes, the NS-Adapter identifies if there are SCCs, which are missing in the report, and then, marks all their systems as unreachable.
    30  
    31  Each on-premise system stored in CMP is labeled with an `SCC` label with value `{"Subaccount":"{{subaccount of the SCC}}", "LocationID":"{{location-id of the SCC}}", "Host":"{{virtual host of the on-premise system}}"}`. The SCC label is used as a unique identifier for the on-premise systems stored in CMP.
    32  
    33  | | |
    34  |---------------------|--------------------------------------|
    35  |**Description**      | Upsert `ExposedSystems` is a bulk `create-or-update` operation on exposed on-premise systems. It takes a list of fully described exposed systems, and then, creates the systems that are new to CMP or updates the metadata for the existing ones.|
    36  |**URL**              | /api/v1/notifications                                  |
    37  |**Query Params**     | reportType=full,delta                                  |
    38  |**HTTP Method**      | PUT                                                    |
    39  |**HTTP Headers**     | Content-Type: application/json                         |
    40  |**HTTP Codes**       | [204 No Content](#204-no-content)                      |
    41  |                     | [200 OK](#200-ok)                                      |
    42  |                     | [400 Bad Request](#400-bad-request)                    |
    43  |                     | [401 Unauthorized](#401-unauthorized)                  |
    44  |                     | [408 Request Timeout](#408-request-timeout)            |
    45  |                     | [500 Internal Server Error](#500-internal-server-error)|
    46  |                     | [502 Bad Gateway](#502-bad-gateway)                    |
    47  |                     | [413 Payload Too Large](#413-payload-too-large)        |
    48  |**Response Formats** | json                                                   |
    49  |**Authentication**   | OAuth 2 via XSUAA                                      |
    50  
    51  
    52  Example request with `delta` report:
    53  ```
    54  curl -v --request PUT \
    55    --url http://{domain}/api/v1/notifications/?reportType=delta \
    56    --header 'content-type: application/json' \
    57    --data \
    58  '
    59  {
    60    "type": "notification-service",
    61    "value": [
    62      {
    63        "subaccount": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    64        "locationId": "location-id-1",
    65        "exposedSystems": [
    66          {
    67            "protocol": "HTTP",
    68            "host": "127.0.0.1:8080",
    69            "type": "on-premise-system",
    70            "status": "disabled",
    71            "description": "system description",
    72            "systemNumber": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"
    73          }
    74        ]
    75      },
    76       {
    77        "subaccount": "cccccccc-cccc-cccc-cccc-cccccccccccc"
    78        "locationId": "location-id-2",
    79        "exposedSystems": [
    80          {
    81            "protocol": "HTTP",
    82            "host": "127.0.0.1:8080",
    83            "type": "on-premise-system",
    84            "status": "disabled",
    85            "description": "system description",
    86            "systemNumber": "dddddddd-dddd-dddd-dddd-dddddddddddd"
    87          }
    88        ]
    89      }
    90    ]
    91  }
    92  '
    93  ```
    94  
    95  Example request with `full` report:
    96  ```
    97  curl -v --request PUT \
    98    --url http://{domain}/api/v1/notifications/?reportType=full \
    99    --header 'content-type: application/json' \
   100    --data \
   101  '
   102  {
   103    "type": "notification-service",
   104    "value": [
   105      {
   106        "subaccount": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
   107        "locationId": "location-id-1",
   108        "exposedSystems": [
   109          {
   110            "protocol": "HTTP",
   111            "host": "127.0.0.1:8080",
   112            "type": "on-premise-system",
   113            "status": "disabled",
   114            "description": "system description",
   115            "systemNumber": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"
   116          }
   117        ]
   118      },
   119       {
   120        "subaccount": "cccccccc-cccc-cccc-cccc-cccccccccccc"
   121        "locationId": "location-id-2",
   122        "exposedSystems": [
   123          {
   124            "protocol": "HTTP",
   125            "host": "127.0.0.1:8080",
   126            "type": "on-premise-system",
   127            "status": "disabled",
   128            "description": "system description",
   129            "systemNumber": "dddddddd-dddd-dddd-dddd-dddddddddddd"
   130          }
   131        ]
   132      }
   133    ]
   134  }
   135  '
   136  ```
   137  
   138  ### NS-Adapter Response
   139  
   140  #### 204 No Content
   141  
   142  This response is returned when all exposed systems in the list are either successfully created or updated. Note that in case of a `full` report, this is the only possible returned response. That is, for a `full` report, the response is returned regardless of whether the `create-or-update` has failed for any SCCs, as these SCCs will be reported again next time.
   143  
   144  ```
   145  HTTP/1.1 204 No Content
   146  ```
   147  
   148  #### 200 OK
   149  
   150  This response is returned if upsert for one or more on-premise systems has failed. The response is returned only by `delta` reports. It is not returned by a `full` report, as the full report does not return SCCs, for which the update has failed.
   151  
   152  ```
   153  HTTP/1.1 200 OK
   154  {
   155    "error": {
   156      "code": "200",
   157      "message": "Update/create failed for some on-premise systems",
   158      "details": [{
   159        "message": "Creation failed",
   160        "subaccount": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
   161        "locationId": "loc-id1"
   162      }]
   163    }
   164  }
   165  ```
   166  
   167  #### 400 Bad Request
   168  
   169  ##### Failed deserialization
   170  
   171  This response is returned if the service cannot deserialize the request.
   172  
   173  ```
   174  HTTP/1.1 400 Bad Request
   175  Content-Type: application/json
   176  
   177  {
   178    "error": {
   179      "code": 400,
   180      "message": "failed to parse request body"
   181    }
   182  }
   183  ```
   184  
   185  ##### Failed to read request body
   186  
   187  This response is returned if the service cannot read the request body from the stream.
   188  
   189  ```
   190  HTTP/1.1 400 Bad Request
   191  Content-Type: application/json
   192  
   193  {
   194    "error": {
   195      "code": 400,
   196      "message": "faild to retrieve request body"
   197    }
   198  }
   199  ```
   200  
   201  ##### Missing required property
   202  
   203  This response is returned in case any of the required properties is not provided, for example, a subaccount.
   204  
   205  ```
   206  HTTP/1.1 400 Bad Request
   207  Content-Type: application/json
   208  
   209  {
   210    "error": {
   211      "code": 400,
   212      "message": "subaccount key is required"
   213    }
   214  }
   215  ```
   216  
   217  ##### Missing query parameter
   218  This response is returned in case the mandatory query parameter `reportType` is missing.
   219  ```
   220  HTTP/1.1 400 Bad Request
   221  Content-Type: application/json
   222  
   223  {
   224    "error": {
   225      "code": 400,
   226      "message": "the query parameter 'reportType' is missing or invalid"
   227    }
   228  }
   229  ```
   230  #### 401 Unauthorized
   231  
   232  This response is returned in the event of a failed authentication.
   233  
   234  ```
   235  HTTP/1.1 401 Unauthoriezd
   236  Content-Type: application/json
   237  
   238  {
   239    "error": {
   240      "code": 401,
   241      "message": "unauthorized"
   242    }
   243  }
   244  ```
   245  #### 408 Request Timeout
   246  
   247  This response is returned in the event of a request timeout in the CMP infrastructure.
   248  ```
   249  HTTP/1.1 408 Request Timeout
   250  Content-Type: application/json
   251  
   252  {
   253    "error": {
   254      "code": 408,
   255      "message": "timeout"
   256    }
   257  }
   258  ```
   259  #### 500 Internal Server Error
   260  
   261  In the event of any internal failure during processing.
   262  
   263  ```
   264  HTTP/1.1 500 Internal Server Error
   265  Content-Type: application/json
   266  
   267  {
   268    "error": {
   269      "code": 500,
   270      "message": "Update failed"
   271    }
   272  }
   273  ```
   274  #### 502 Bad Gateway
   275  
   276  This response is returned in the event of a communication error in the CMP infrastructure.
   277  ```
   278  HTTP/1.1 502 Bad Gateway
   279  Content-Type: text/plain
   280  
   281  <content>
   282  ```
   283  #### 413 Payload Too Large
   284  
   285  This response is returned in the event of a request body larger than 5 MB.
   286  ```
   287  HTTP/1.1 413 Payload Too Large
   288  Content-Type: text/plain
   289  
   290  <content>
   291  ```
   292  
   293  ## Configuration
   294  
   295  NS-Adapter binary allows you to override some configuration parameters. To get a list of the configurable parameters of NS-Adapter, see [configuration.go](https://github.com/kyma-incubator/compass/blob/66754e58f6d23f233a6905fa9e4577b6666c98e7/components/director/internal/nsadapter/adapter/configuration.go#L13)
   296  
   297  ## Local Development
   298  
   299  ### Prerequisites
   300  
   301  NS-Adapter requires access to:
   302  1. A configured PostgreSQL database with imported Director's database schema.
   303  2. A service that exposes endpoint for fetching JWKSs.
   304  
   305  ### Run
   306  You can start the NS-Adapter via the designated `run.sh` script in Director:
   307  ```bash
   308  ./run.sh --ns-adapter --jwks-endpoint {your_JWKS_endpoint}
   309  
   310  ```
   311  
   312  This brings up a PostgreSQL database with Director's schema.
   313  
   314  The up-to-date properties supported by the `run.sh` script can be found in the Director component local documentation: [Director](../../README.md#local-development).