📚 Sync docs from alaudadevops/connectors-operator on c909fef091eb9590035e61e1e2e192dd1bd036fb

Source: add docs to describe connectors api by proxy (#294)
Author: chengjingtao
Ref: refs/heads/main
Commit: c909fef091eb9590035e61e1e2e192dd1bd036fb

This commit automatically syncs documentation changes from the source-docs repository.

🔗 View source commit: https://github.com/alaudadevops/connectors-operator/commit/c909fef091eb9590035e61e1e2e192dd1bd036fb
🤖 Synced on 2025-11-10 07:44:15 UTC

Author: edge-katanomi-app2[bot]

.github/SYNC_INFO.md

@@ -1,10 +1,10 @@
 # Documentation Sync Information
 
-- **Last synced**: 2025-11-07 08:50:22 UTC
+- **Last synced**: 2025-11-10 07:44:15 UTC
 - **Source repository**: alaudadevops/connectors-operator
-- **Source commit**: [7e55b6fbcddf4534f95817450833ffc488029a09](https://github.com/alaudadevops/connectors-operator/commit/7e55b6fbcddf4534f95817450833ffc488029a09)
+- **Source commit**: [c909fef091eb9590035e61e1e2e192dd1bd036fb](https://github.com/alaudadevops/connectors-operator/commit/c909fef091eb9590035e61e1e2e192dd1bd036fb)
 - **Triggered by**: edge-katanomi-app2[bot]
-- **Workflow run**: [#46](https://github.com/alaudadevops/connectors-operator/actions/runs/19163120541)
+- **Workflow run**: [#47](https://github.com/alaudadevops/connectors-operator/actions/runs/19224399099)
 
 ## Files synced:
 - docs/

docs/en/connectors/architecture/assets/arch.drawio.png

@@ -60,10 +60,16 @@ More information: [Connectors Proxy](../concepts/connectors_proxy.mdx)
 
 Developers can conveniently access resources within tools via the `Connectors API` without needing to concern themselves with specific tool addresses and authentication details.
 
+The system supports two ways to access tool resources through the API:
+
+- **Original Tool API**: When the ConnectorClass provides Proxy Service capabilities, clients can directly access the tool's original API through the Connector API. The system automatically forwards requests to the tool's Proxy Service, completes authentication injection, and returns the original data from the tool.
+- **Custom API**: Use custom APIs provided for the ConnectorClass, which offer extended capabilities beyond the tool's original API.
+
 This API is very useful in practical applications, such as:
 
 - Retrieving the list of tags for container images when creating applications
 - Getting the list of branches (References) for a code repository during a Git Clone operation
+- Accessing tool-specific APIs directly when the ConnectorClass supports Proxy Service
 
 The implementation of the `Connectors API` is based on the underlying capabilities provided by the `ConnectorClass API`.
 

docs/en/connectors/architecture/index.mdx

@@ -241,11 +241,35 @@ status:
       url: http://c-harbor.default.svc.cluster.local/namespaces/default/connectors/harbor
 ```
 
+## Status Information
 
+The status information of the Connector is recorded in the `status` field, containing proxy address, API address, and conditions:
 
-## Status Information
+- `status.conditions`: Conditions of the Connector.
+- `status.proxy`: Proxy address of the Connector.
+- `status.api`: API address of the Connector.
+
+**Proxy Address**
+
+The `proxy` field contains the proxy address of the Connector.
+
+- `status.proxy.httpAddress.url`: The HTTP address of the proxy for the current Connector.
+
+You can use this address with existing tool clients to access the tool in a secretless manner within the cluster. For more information, refer to [Connector Proxy](#connector_proxy).
+
+If the ConnectorClass has no proxy capability, the `status.proxy` field will be empty.
 
-The status information of the Connector is recorded in the `status` field, containing the following content:
+**API Address**
+
+The `api` field contains the API address of the Connector.
+
+- `status.api.path`: The API relative path for the current Connector (relative to the cluster ingress access entrypoint).
+
+You can use this path outside the cluster to access the tool's original API through the current Connector. For more information, refer to [Connector API](./connector_api.mdx).
+
+**Conditions**
+
+The `conditions` type includes:
 
 - `ConnectorClassReady`: Indicates whether the connector type is correct.
 - `SecretReady`: Indicates whether the authentication information is correctly configured.
@@ -326,8 +350,6 @@ status:
     message: ""
 ```
 
-For more information on conditions, please refer to `Connector Conditions`.
-
 ## Examples
 
 ### Git Connector with Basic Authentication

docs/en/connectors/concepts/connector.mdx

@@ -2,62 +2,105 @@
 created: '2024-12-01'
 title: Connector API
 weight: 50
-sourceSHA: 787a9663c2b07bba63b2648088abf865fb2f475cfe27d1f24fd23a68b9cca2fd
 ---
 
 # Connector API
 
 ## Overview
 
-After integrating access tools within the cluster, a RESTful API can be provided for the current ConnectorClass to conveniently acquire resources within the tool. These APIs will be uniformly exposed through the Connector API, allowing users to obtain resources from the tool pointed to by the current Connector.
+After integrating tools within the cluster, a RESTful API can be provided for the current Connector to conveniently acquire resources from the tool. These APIs are uniformly exposed through the Connector API, allowing users to obtain resources from the tool pointed to by the current Connector.
 
-The Connectors system provides a complete set of extension mechanisms, making it easier for developers to extend the API capabilities of ConnectorClass.
+The Connectors system supports two ways to access tool resources through the API:
 
-The Connectors API offers a unified request entry point. When a client initiates a resource request for the tool pointed to by a specific Connector, the system will forward the request to the corresponding API address of the ConnectorClass, which in turn will forward the request to the tool's API address to retrieve resources within the tool.
+- **Original Tool API**: Access the tool's original API through the Proxy Service
+- **Custom API**: Use a custom API provided for the ConnectorClass
 
-For example:
+When using the Connectors API, clients do not need to manage the tool's original authentication credentials. They only need to have permissions to access the Connector. The permissions for API requests to the tool are determined by the permissions of the credentials (Secret) configured in the Connector.
+
+## Connector API Address and Authentication
 
-- Retrieve the Reference list of a specific repository under the Git Connector.
-- Retrieve the Tag list of a specific artifact repository under the OIC Connector.
+### API Address
 
-## API Definition
+The Connector API address consists of three parts:
 
-**API Address**
+- Platform API or cluster ingress access entry point
+- Connector API relative path
+- Requested tool's original API path or custom API path
 
-`/connectors/v1alpha1/namespaces/{namespace}/connectors/{name}/resources/{resource-name}`
+After creating a Connector in the cluster, the Connector automatically records the current Connector's API path in `<connector>.status.api.path`. Note that this path is a relative path to the cluster access entry point.
 
-- `namespace`: The namespace where the current Connector resides.
-- `name`: The name of the current Connector.
-- `resource-name`: The name of the resource being requested, which can be understood by consulting the documentation of the corresponding ConnectorClass.
+The final Connector API address is: `{platform_api_address}/{<connector>.status.api.path}/{api-path}`
 
-**Authentication and Authorization**
+::: info
+In Alauda Container Platform, the API access entry point is typically `{platform_address}/clusters-rewrite/{cluster_name}`.
+:::
 
-Authentication complies with Kubernetes authentication standards, completed through Kubernetes' authentication and authorization mechanisms. The requesting user must have read permissions for the corresponding `connector`.
+### Authentication and Authorization
+
+Authentication complies with Kubernetes authentication standards and is completed through Kubernetes' authentication and authorization mechanisms. The requesting user must have read permissions for the corresponding `Connector`. Currently, only Bearer Token authentication is supported.
 
 When making the final request to the tool, the Secret information specified by the Connector will be used for authentication.
 
-**Query Parameters**
+For more information about Kubernetes API authentication, refer to the [Kubernetes Authentication documentation](https://kubernetes.io/docs/reference/access-authn-authz/authentication).
+
+## Accessing Original Tool API
+
+When your ConnectorClass provides Proxy Service capabilities, you can directly access the tool's original API through the Connector API.
+
+For example, if the tool's original API address is `/api/v4/projects`, you can access it through the Connector API. Assuming you have a Connector named `gitlab-connector` in the `default` namespace, and the Connector's API path is `/connectors/v1alpha1/default/gitlab-connector/path`, the request would be:
+
+```bash
+K8S_TOKEN=xxxx
+
+curl -H "Authorization: Bearer ${K8S_TOKEN}" "https://platform.example.com/connectors/v1alpha1/default/gitlab-connector/path/api/v4/projects"
+```
+
+The Proxy Service capabilities can be configured through the `ConnectorClass` specification. For configuration details, refer to [ConnectorClass Proxy](./connectorclass.mdx#connectorclass_proxy). For a deeper understanding of the `Connectors Proxy` concept, refer to [Connectors Proxy](./connectors_proxy.mdx).
+
+## Custom API
+
+When the tool's original API cannot meet your requirements or the ConnectorClass does not provide Proxy Service capabilities, you can provide a custom API service for the current ConnectorClass to meet your needs.
+
+The custom API service can be configured through the `spec.api` field of the ConnectorClass, allowing the Connectors system to discover and use it. For configuration details, refer to [ConnectorClass API](./connectorclass.mdx#connectorclass_api).
+
+Additionally, to enable the system to identify that the API is a custom API, you need to configure the OpenAPI description through the `spec.api.openapi` field.
+
+### API Definition
 
-Determined by the specific ConnectorClass API.
+#### API Path
 
-**Pagination Information**
+The API path provided by the custom API can be freely defined in the extended API service. The recommended format is `/<connectorclass-name>/xxx`. 
 
-Indicated by query parameters.
+Combined with the API address and authentication described above, here is a request example. Assuming you have a Connector named `git-connector` in the `default` namespace, and the custom API path is `/git/gitrefs`, the request would be:
 
-| Parameter Name     | Type  | Required | Description  |
-| ------------------ | ----- | -------- | ------------ |
-| page               | int   | false    | Page number   |
-| itemsPerPage      | int   | false    | Number of items per page |
+```bash
+K8S_TOKEN=xxxx
 
-**Response Information**
+curl -H "Authorization: Bearer ${K8S_TOKEN}" "https://platform.example.com/connectors/v1alpha1/default/git-connector/git/gitrefs"
+```
+
+#### Query Parameters
+
+Query parameters are determined by the specific [ConnectorClass API Specification](./connectorclass_api_spec.mdx).
+
+#### Pagination
 
-When returning a list, the structure will be as follows:
+Pagination information is indicated by query parameters:
 
-| Field Name         | Type       | Required | Description                                |
-| -------------------| ---------- | -------- | ------------------------------------------ |
-| listMeta           | ListMeta  | true     | Metadata of the list                       |
+| Parameter Name | Type | Required | Description                |
+| -------------- | ---- | -------- | -------------------------- |
+| page           | int  | false    | Page number                |
+| itemsPerPage   | int  | false    | Number of items per page    |
+
+#### Response Format
+
+When returning a list, the response structure is as follows:
+
+| Field Name         | Type      | Required | Description                                                                 |
+| ------------------ | --------- | -------- | --------------------------------------------------------------------------- |
+| listMeta           | ListMeta  | true     | Metadata of the list                                                        |
 | listMeta.totalItems| int       | true     | Total number of requested resources, usable by the client to analyze pagination information |
-| items              | \[]       | true     | Data items in the list; the data structure is determined by the ConnectorClass API |
+| items              | []        | true     | Data items in the list; the data structure is determined by the ConnectorClass API |
 
 ```json
 {
@@ -88,8 +131,50 @@ For example:
 
 Field definitions and enumeration values are consistent with [k8s status](https://pkg.go.dev/k8s.io/[email protected]/pkg/apis/meta/v1#Status).
 
-## ConnectorClass API Extension Specification
+### OpenAPI Description
+
+In addition to providing a custom API service, you need to configure the OpenAPI description information in the `spec.api.openapi` field of the ConnectorClass to enable the system to identify that the API is a custom API.
+
+Example:
+
+```yaml
+kind: ConnectorClass
+metadata:
+  name: gitlab
+spec:
+  api:
+    ref:  # Reference to the custom API service
+      name: connectors-gitlab-api
+      namespace: connectors-system
+    openapi:
+      openapi: "3.0.1"
+      info:
+        title: GitLab Custom API
+        version: "1.0.0"
+      paths:
+        /gitlab/custom-api:  # Custom API defined in the connectors-gitlab-api service
+          get:
+            x-provider-type: api  # Indicates this API is a custom API
+            summary: Request custom API
+            responses:
+              "200":
+                description: Custom API response
+```
+
+The system will automatically forward the custom API to the [ConnectorClass API Address](./connectorclass.mdx#connectorclass_api_address) based on the `spec.api.openapi` description.
+
+For configuration details about `spec.api.openapi`, refer to [ConnectorClass OpenAPI Description](./connectorclass.mdx#api_openapi). For more usage examples, refer to [Using Connectors API in Dynamic Forms](#dynamic-form-using-connectors-api).
+
+### ConnectorClass API Extension Specification
 
 Developers can extend the API capabilities for ConnectorClass to provide users with richer resource retrieval capabilities.
 
 Refer to the [ConnectorClass API Extension Specification](./connectorclass_api_spec.mdx).
+
+## Using Connectors API in Dynamic Forms \{#dynamic-form-using-connectors-api}
+
+The Connector API can be provided to UI clients, especially for dynamic form scenarios where UI clients can flexibly configure the API requests to be called.
+
+To enable this, you need to configure the OpenAPI description information through the `spec.api.openapi` field of the ConnectorClass, which works together with the dynamic form DSL to implement frontend dynamic form rendering.
+
+The dynamic form description is typically provided in the [Resource Interface](./resource_interface.mdx). For more details, refer to [Resource Interface](./resource_interface.mdx).