From 9e92d5b91db52eec4d7e067c847bb2e3e4e58ec7 Mon Sep 17 00:00:00 2001 From: TharinduWijewardane Date: Thu, 10 Oct 2024 12:35:23 +0530 Subject: [PATCH 1/7] Add choreo docs for retry --- .../use-a-connection-in-your-service.md | 40 ++++++++++++++++++- 1 file changed, 38 insertions(+), 2 deletions(-) diff --git a/en/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service.md b/en/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service.md index f0d19e197..cf78c2906 100644 --- a/en/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service.md +++ b/en/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service.md @@ -33,6 +33,8 @@ To integrate another service into your application, follow the steps below: to: - from: TokenURL to: + - from: ChoreoAPIKey + to: ``` @@ -58,6 +60,7 @@ To integrate another service into your application, follow the steps below: | ConsumerKey | string | Consumer key of the Choreo service | false | false | | ConsumerSecret | string | Consumer secret of the Choreo service | false | true | | TokenURL | string | Token URL of the STS | false | false | + | ChoreoAPIKey | string | API Key of the Choreo service | false | true | ### Step 2: Read configurations within the application @@ -110,11 +113,44 @@ As the service URL you can use the URL that you resolved in [step 2](#step-2-rea ``` java const response = await axios.get(serviceURL/{RESOURCE_PATH}, { headers: { - 'Authorization': `Bearer ${accessToken}` + 'Authorization': `Bearer ${accessToken}`, + 'Choreo-API-Key': `${ChoreoAPIKey}` } }); ``` !!! note If you want to consume a Choreo service at the project visibility level, you don't need to obtain a token. You can directly invoke the service using the resolved URL. - + +### Configure resiliency for the connection + +To ensure your service remains robust and responsive when consuming other Choreo services through connections, you can configure resiliency patterns. Currently, Choreo supports the retry for connections, which you can configure through the Choreo console. + +#### Configuring Retry + +To configure retry for your connection, follow these steps: + +1. Enable retry toggle button +2. Tweak the retry parameters +3. Save the configurations + + !!! note + For the retry feature to work, you need to send the `Choreo-API-Key` header with the request. + Please refer to [step 1](#step-1-add-connection-configurations) on how to obtain the Choreo API key. + +#### Retry Configuration Parameters + +- **Retry count**: Specifies how many times Choreo should attempt to retry the request if it fails. For example, setting this to 3 means Choreo will make up to 3 additional attempts after the initial failure. + +- **Retry Backoff Interval (ms)**: Defines a base value for the exponential backoff time delay between retry attempts. This helps to prevent overwhelming the target service with immediate repeated requests. + +- **Timeout Per Retry (s)**: Sets a maximum duration for each retry attempt. If a retry attempt doesn't receive a response within this time, it's considered a failure. For example, setting this to 30 means each retry will wait up to 30 seconds for a response before timing out. + +- **Condition**: Allows you to specify under what circumstances a retry should be attempted. Choreo supports the following retry conditions. You can select one or multiple conditions. + + - **5xx**: Retry on any 5xx response code, or if the upstream server does not respond at all (disconnect/reset/read timeout) (This includes connect-failure and refused-stream). + - **gateway-error**: Retry only on 502, 503, or 504 response codes. + - **reset**: Retry when the upstream server does not respond at all (disconnect/reset/read timeout). + - **connect-failure**: Retry on connection failures to the upstream server (connect timeout, etc.). + - **retriable-4xx**: Retry on retriable 4xx response codes. Currently, this only includes 409 responses. + - **refused-stream**: Retry if the upstream server resets the stream with a REFUSED_STREAM error code. From a103e5bb2e3936efa7fbb46c709cddbffd29496c Mon Sep 17 00:00:00 2001 From: Nisrin Date: Mon, 14 Oct 2024 23:07:22 +0530 Subject: [PATCH 2/7] Add docs on Third-party and GenAI services --- en/mkdocs.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/en/mkdocs.yml b/en/mkdocs.yml index d34a283d5..3d1e51018 100644 --- a/en/mkdocs.yml +++ b/en/mkdocs.yml @@ -130,6 +130,9 @@ nav: - Configure Endpoints: develop-components/configure-endpoints.md - Manage Component Source Configurations: develop-components/manage-component-source-configurations.md - Develop Components Using VS Code: develop-components/develop-components-using-vs-code.md + - Integrate and Manage External Services: + - Integrate and Manage Third-Party Services: integrate-and-manage-external-services/integrate-and-manage-third-party-services.md + - Integrate and Manage Generative AI Services: integrate-and-manage-external-services/integrate-and-manage-gen-ai-services.md - Choreo-Managed Databases and Caches: - Overview: manage-databases-and-caches/choreo-managed-databases-and-caches.md - PostgreSQL: manage-databases-and-caches/choreo-managed-postgresql-databases.md From 2785b92940dadf2cc5ae7b7dc60938bc501766c8 Mon Sep 17 00:00:00 2001 From: Nisrin Date: Mon, 14 Oct 2024 23:11:58 +0530 Subject: [PATCH 3/7] Update create-a-connection.md --- .../sharing-and-reusing/create-a-connection.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/en/docs/develop-components/sharing-and-reusing/create-a-connection.md b/en/docs/develop-components/sharing-and-reusing/create-a-connection.md index df64e82ff..e706166cf 100644 --- a/en/docs/develop-components/sharing-and-reusing/create-a-connection.md +++ b/en/docs/develop-components/sharing-and-reusing/create-a-connection.md @@ -2,12 +2,14 @@ Connections in Choreo provide a simple and uniform approach to seamlessly integrate components with services or resources. -Choreo allows you to create connections to services deployed in Choreo and to Choreo-managed databases. +Choreo allows you to create connections to services deployed in Choreo or registered as external services. It also allows you to create connections to any Choreo-managed database. To create a connection to a service or a database, follow the step-by-step instructions in the respective tab: === "Create a connection to a service" +

Create a connection to a Choreo service

+ Follow these steps to create a connection to a service deployed in Choreo: 1. In the Choreo Console, go to the top navigation menu and set the visibility level as [project](../../choreo-concepts/connections.md#project-connections) or [component](../../choreo-concepts/connections.md#component-connections) as follows: @@ -23,10 +25,18 @@ To create a connection to a service or a database, follow the step-by-step instr 7. Click **Create**. This creates the connection and displays its details for each environment, along with an inline guide on how to use the connection in your component. - - For step-by-step instructions on using a connection in your service, see [Use a Connection in Your Service](./use-a-connection-in-your-service.md). - For step-by-step instructions on using a connection in your web application, see [Use a Connection in Your Web Application](./use-a-connection-in-your-web-application.md). +

Create a connection to an external service

+ + Follow these steps to create a connection to an external service: + + 1. Follow steps 1–5 from the previous section. + 2. Expand the **Environment to Endpoint** section and verify the service endpoints assigned to the Choreo environments. + 3. Click **Create**. + + For step-by-step instructions on using a connection in your service, see [Use a Connection in Your Service](./use-a-connection-in-your-service.md). + + For step-by-step instructions on using a connection in your web application, see [Use a Connection in Your Web Application](./use-a-connection-in-your-web-application.md). === "Create a connection to a database" From ff4fafc4e9e62f004dc2c0187201ca90a07cab47 Mon Sep 17 00:00:00 2001 From: Nisrin Date: Tue, 15 Oct 2024 11:36:42 +0530 Subject: [PATCH 4/7] Update integrate-and-manage-gen-ai-services.md --- .../integrate-and-manage-gen-ai-services.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/docs/integrate-and-manage-external-services/integrate-and-manage-gen-ai-services.md b/en/docs/integrate-and-manage-external-services/integrate-and-manage-gen-ai-services.md index 8c4b1a7b3..a732fc249 100644 --- a/en/docs/integrate-and-manage-external-services/integrate-and-manage-gen-ai-services.md +++ b/en/docs/integrate-and-manage-external-services/integrate-and-manage-gen-ai-services.md @@ -61,7 +61,7 @@ If you want to remove the service from the Internal Marketplace, see [Remove a G The GenAI services you register are discoverable via the Internal Marketplace for you to consume via a Connection. -For details on consuming a GenAI service via a connection, see [Create a Connection](../develop-components/sharing-and-reusing/create-a-connection.md#create-a-connection-to-an-external-service). +For details on consuming a GenAI service via a connection, see [Create a Connection](../develop-components/sharing-and-reusing/create-a-connection.md). ## Manage GenAI services From a2352944afc4e8c8fea0d707d29a01cb84d3ffdc Mon Sep 17 00:00:00 2001 From: Nisrin Date: Fri, 18 Oct 2024 11:56:06 +0530 Subject: [PATCH 5/7] Apply review suggestions --- .../use-a-connection-in-your-service.md | 42 ++++++++++--------- 1 file changed, 23 insertions(+), 19 deletions(-) diff --git a/en/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service.md b/en/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service.md index cf78c2906..11cf8f8b7 100644 --- a/en/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service.md +++ b/en/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service.md @@ -60,7 +60,7 @@ To integrate another service into your application, follow the steps below: | ConsumerKey | string | Consumer key of the Choreo service | false | false | | ConsumerSecret | string | Consumer secret of the Choreo service | false | true | | TokenURL | string | Token URL of the STS | false | false | - | ChoreoAPIKey | string | API Key of the Choreo service | false | true | + | ChoreoAPIKey | string | API key of the Choreo service | false | true | ### Step 2: Read configurations within the application @@ -122,35 +122,39 @@ As the service URL you can use the URL that you resolved in [step 2](#step-2-rea !!! note If you want to consume a Choreo service at the project visibility level, you don't need to obtain a token. You can directly invoke the service using the resolved URL. -### Configure resiliency for the connection +## Configure resiliency for the connection -To ensure your service remains robust and responsive when consuming other Choreo services through connections, you can configure resiliency patterns. Currently, Choreo supports the retry for connections, which you can configure through the Choreo console. +To ensure your service remains robust and responsive when consuming other Choreo services through connections, you can configure resiliency patterns. Choreo supports configuring retries for connections. -#### Configuring Retry +### Configure retry To configure retry for your connection, follow these steps: -1. Enable retry toggle button -2. Tweak the retry parameters -3. Save the configurations +1. Sign in to the Choreo Console at [https://console.choreo.dev/](https://console.choreo.dev). +2. In the header, click the **Project** list. This opens the project home page. +3. In the left navigation menu, click **Dependencies** and then click **Connections**. +4. Click on a required service to view its details. +5. Enable the **Retry** toggle under **Resiliency**. +6. Set appropriate values for the retry parameters. For more information, see [Retry configuration parameters](#retry-configuration-parameters). +7. Click **Save**. !!! note - For the retry feature to work, you need to send the `Choreo-API-Key` header with the request. - Please refer to [step 1](#step-1-add-connection-configurations) on how to obtain the Choreo API key. + To use the retry feature, include the `Choreo-API-Key` header in your request. For details on obtaining the Choreo API key, see [Step 1](#step-1-add-connection-configurations). -#### Retry Configuration Parameters +### Retry configuration parameters -- **Retry count**: Specifies how many times Choreo should attempt to retry the request if it fails. For example, setting this to 3 means Choreo will make up to 3 additional attempts after the initial failure. +- **Retry count**: The number of retry attempts if a request fails. For example, setting this to 3 allows Choreo to make up to 3 additional attempts after the initial failure. -- **Retry Backoff Interval (ms)**: Defines a base value for the exponential backoff time delay between retry attempts. This helps to prevent overwhelming the target service with immediate repeated requests. +- **Retry Backoff Interval**: The base time delay for exponential backoff between retries. This prevents overwhelming the target service with rapid, repeated requests. -- **Timeout Per Retry (s)**: Sets a maximum duration for each retry attempt. If a retry attempt doesn't receive a response within this time, it's considered a failure. For example, setting this to 30 means each retry will wait up to 30 seconds for a response before timing out. +- **Timeout Per Retry**: The maximum duration in seconds for each retry attempt. If there is no response within this time, the attempt is considered a failure. For example, setting this to 30 seconds means each retry will wait up to 30 seconds before timing out. -- **Condition**: Allows you to specify under what circumstances a retry should be attempted. Choreo supports the following retry conditions. You can select one or multiple conditions. +- **Condition**: The conditions under which retries are triggered. Choreo supports the following options, and you can select one or more: - - **5xx**: Retry on any 5xx response code, or if the upstream server does not respond at all (disconnect/reset/read timeout) (This includes connect-failure and refused-stream). + - **5xx**: Retry on any 5xx response code or when the upstream server fails to respond (disconnect/reset/read timeout). This includes connection failures and refused-stream errors. - **gateway-error**: Retry only on 502, 503, or 504 response codes. - - **reset**: Retry when the upstream server does not respond at all (disconnect/reset/read timeout). - - **connect-failure**: Retry on connection failures to the upstream server (connect timeout, etc.). - - **retriable-4xx**: Retry on retriable 4xx response codes. Currently, this only includes 409 responses. - - **refused-stream**: Retry if the upstream server resets the stream with a REFUSED_STREAM error code. + - **reset**: Retry when the upstream server does not respond (disconnect/reset/read timeout). + - **connect-failure**: Retry on connection failures to the upstream server, such as connection timeouts. + - **retriable-4xx**: Retry on retriable 4xx response codes. Currently limited to 409 responses. + - **refused-stream**: Retry if the upstream server resets the stream with a `REFUSED_STREAM` error code. + From c638150b74cdecfff7dbbaf0289f9d2cdf69b11d Mon Sep 17 00:00:00 2001 From: Nisrin Date: Fri, 18 Oct 2024 12:00:22 +0530 Subject: [PATCH 6/7] Update use-a-connection-in-your-service.md --- .../use-a-connection-in-your-service.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/en/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service.md b/en/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service.md index 11cf8f8b7..0c98fc268 100644 --- a/en/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service.md +++ b/en/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service.md @@ -151,10 +151,9 @@ To configure retry for your connection, follow these steps: - **Condition**: The conditions under which retries are triggered. Choreo supports the following options, and you can select one or more: - - **5xx**: Retry on any 5xx response code or when the upstream server fails to respond (disconnect/reset/read timeout). This includes connection failures and refused-stream errors. - - **gateway-error**: Retry only on 502, 503, or 504 response codes. - - **reset**: Retry when the upstream server does not respond (disconnect/reset/read timeout). - - **connect-failure**: Retry on connection failures to the upstream server, such as connection timeouts. - - **retriable-4xx**: Retry on retriable 4xx response codes. Currently limited to 409 responses. - - **refused-stream**: Retry if the upstream server resets the stream with a `REFUSED_STREAM` error code. - + - **5xx**: Retry on any 5xx response code or when the upstream server fails to respond (disconnect/reset/read timeout). This includes connection failures and refused-stream errors. + - **gateway-error**: Retry only on 502, 503, or 504 response codes. + - **reset**: Retry when the upstream server does not respond (disconnect/reset/read timeout). + - **connect-failure**: Retry on connection failures to the upstream server, such as connection timeouts. + - **retriable-4xx**: Retry on retriable 4xx response codes. Currently limited to 409 responses. + - **refused-stream**: Retry if the upstream server resets the stream with a `REFUSED_STREAM` error code. From f9fe4db39008a1b72739d485feb3774c16ed6e7c Mon Sep 17 00:00:00 2001 From: Nisrin Date: Mon, 21 Oct 2024 12:52:32 +0530 Subject: [PATCH 7/7] Revert "Add choreo docs for retry" --- .../use-a-connection-in-your-service.md | 43 +------------------ 1 file changed, 2 insertions(+), 41 deletions(-) diff --git a/en/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service.md b/en/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service.md index 0c98fc268..f0d19e197 100644 --- a/en/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service.md +++ b/en/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service.md @@ -33,8 +33,6 @@ To integrate another service into your application, follow the steps below: to: - from: TokenURL to: - - from: ChoreoAPIKey - to: ``` @@ -60,7 +58,6 @@ To integrate another service into your application, follow the steps below: | ConsumerKey | string | Consumer key of the Choreo service | false | false | | ConsumerSecret | string | Consumer secret of the Choreo service | false | true | | TokenURL | string | Token URL of the STS | false | false | - | ChoreoAPIKey | string | API key of the Choreo service | false | true | ### Step 2: Read configurations within the application @@ -113,47 +110,11 @@ As the service URL you can use the URL that you resolved in [step 2](#step-2-rea ``` java const response = await axios.get(serviceURL/{RESOURCE_PATH}, { headers: { - 'Authorization': `Bearer ${accessToken}`, - 'Choreo-API-Key': `${ChoreoAPIKey}` + 'Authorization': `Bearer ${accessToken}` } }); ``` !!! note If you want to consume a Choreo service at the project visibility level, you don't need to obtain a token. You can directly invoke the service using the resolved URL. - -## Configure resiliency for the connection - -To ensure your service remains robust and responsive when consuming other Choreo services through connections, you can configure resiliency patterns. Choreo supports configuring retries for connections. - -### Configure retry - -To configure retry for your connection, follow these steps: - -1. Sign in to the Choreo Console at [https://console.choreo.dev/](https://console.choreo.dev). -2. In the header, click the **Project** list. This opens the project home page. -3. In the left navigation menu, click **Dependencies** and then click **Connections**. -4. Click on a required service to view its details. -5. Enable the **Retry** toggle under **Resiliency**. -6. Set appropriate values for the retry parameters. For more information, see [Retry configuration parameters](#retry-configuration-parameters). -7. Click **Save**. - - !!! note - To use the retry feature, include the `Choreo-API-Key` header in your request. For details on obtaining the Choreo API key, see [Step 1](#step-1-add-connection-configurations). - -### Retry configuration parameters - -- **Retry count**: The number of retry attempts if a request fails. For example, setting this to 3 allows Choreo to make up to 3 additional attempts after the initial failure. - -- **Retry Backoff Interval**: The base time delay for exponential backoff between retries. This prevents overwhelming the target service with rapid, repeated requests. - -- **Timeout Per Retry**: The maximum duration in seconds for each retry attempt. If there is no response within this time, the attempt is considered a failure. For example, setting this to 30 seconds means each retry will wait up to 30 seconds before timing out. - -- **Condition**: The conditions under which retries are triggered. Choreo supports the following options, and you can select one or more: - - - **5xx**: Retry on any 5xx response code or when the upstream server fails to respond (disconnect/reset/read timeout). This includes connection failures and refused-stream errors. - - **gateway-error**: Retry only on 502, 503, or 504 response codes. - - **reset**: Retry when the upstream server does not respond (disconnect/reset/read timeout). - - **connect-failure**: Retry on connection failures to the upstream server, such as connection timeouts. - - **retriable-4xx**: Retry on retriable 4xx response codes. Currently limited to 409 responses. - - **refused-stream**: Retry if the upstream server resets the stream with a `REFUSED_STREAM` error code. +