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

     1  # System Fetcher
     2  
     3  ## Overview
     4  
     5  This application fetches customer systems from an external service. Then, the fetched systems are synchronized with the Compass database.
     6  
     7  The purpose of the system fetcher is to populate customer systems automatically, instead of creating these systems manually using the UI, or using the Director GraphQL API.
     8  
     9  ## Details
    10  
    11  This section describes the API schema that must be implemented on the server side to integrate with the System Fetcher.
    12  
    13  ### Authorization
    14  
    15  The External System Registry API uses either OAuth 2.0 client credentials authorization flow or mTLS, and comprises preconfigured trust for the externally issued client certificate of Compass.
    16  
    17  ### Systems Endpoint
    18  
    19  The endpoint must return a specific payload and must accept the following type of query parameters:
    20  - **global.systemFetcher.systemsAPIFilterCriteria** - Specifies the filtering criteria for the systems. For example, the system type (mapped to an application template in Compass).
    21  - **global.systemFetcher.systemsAPIFilterTenantCriteriaPattern** - Specifies the filtering criteria for the systems, based on a tenant from Compass.
    22  
    23  #### Response
    24  
    25  The response of the system API returns the following response:
    26  
    27  ```json
    28  [
    29      {
    30          "systemNumber": "<unique-id>",
    31  	    "displayName": "<name>",
    32  	    "productDescription": "<description>",
    33  	    "baseUrl": "<baseURL>",
    34  	    "infrastructureProvider": "<provider>",
    35  	    "additionalUrls": "<additional-urls>",
    36  	    "additionalAttributes": "<additional-attributes>"
    37      }
    38  ]
    39  ```
    40  Then, using the input, the System Fetcher can create a system by template.
    41  
    42  ## Configuration
    43  
    44  The System Fetcher binary allows you to override some configuration parameters. To get a list of the configurable parameters, see [main.go](https://github.com/kyma-incubator/compass/blob/75aff5226d4a105f4f04608416c8fa9a722d3534/components/director/cmd/systemfetcher/main.go#L48).
    45  
    46  ## Local Development
    47  ### Prerequisites
    48  The System Fetcher requires access to:
    49  1. Configured PostgreSQL database with the imported Director's database schema.
    50  1. API that can be called to fetch systems. For details about implementing the System Registry API that the System Fetcher can consume, see the [Systems Endpoint](#systems-endpoint) section in this document. 
    51  
    52  ### Run
    53  There is a `./runSystemFetcher.sh` script that automatically runs system fetcher locally with the necessary configuration and environment variables. The script requires a started local director (run.sh). In addition, you can use the following flags:
    54  - `--tenant <TENANT_IDENTIFIER>` - Tenant identifier that is used for the current local execution.
    55  - `--skip-tenant-creation` - A flag that does not register the tenant in director again during subsequent executions.
    56  - `--debug` - Starts system fetcher in debugging mode on default port `40001`.
    57  - `--debug-port <PORT_NUMBER>` - Sets the debug port to specific value.
    58     
    59