Skip to content

Commit 7ef7887

Browse files
chengjingtaochengjingtao
committed
📚 Sync docs from alaudadevops/connectors-operator on 87239bc21b9097700d12edec8aad5ec5973908e7
Source: add docs about connectors-k8s and about 1.2.0 (#158) Author: chengjingtao Ref: refs/heads/release-1.2 Commit: 87239bc21b9097700d12edec8aad5ec5973908e7 This commit automatically syncs documentation changes from the source-docs repository. 🔗 View source commit: AlaudaDevops/connectors-operator@87239bc 🤖 Synced on 2025-08-21 08:29:02 UTC
1 parent b8bf3a3 commit 7ef7887

File tree

19 files changed

+873
-113
lines changed

19 files changed

+873
-113
lines changed

‎.github/SYNC_INFO.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
# Documentation Sync Information
22

3-
- **Last synced**: 2025-08-15 11:02:14 UTC
3+
- **Last synced**: 2025-08-21 08:29:02 UTC
44
- **Source repository**: alaudadevops/connectors-operator
5-
- **Source commit**: [d4e3ec4657ec05dae428d89f513d54c1e774e3b1](https://github.com/alaudadevops/connectors-operator/commit/d4e3ec4657ec05dae428d89f513d54c1e774e3b1)
5+
- **Source commit**: [87239bc21b9097700d12edec8aad5ec5973908e7](https://github.com/alaudadevops/connectors-operator/commit/87239bc21b9097700d12edec8aad5ec5973908e7)
66
- **Triggered by**: chengjingtao
7-
- **Workflow run**: [#16](https://github.com/alaudadevops/connectors-operator/actions/runs/16988648854)
7+
- **Workflow run**: [#17](https://github.com/alaudadevops/connectors-operator/actions/runs/17121495152)
88

99
## Files synced:
1010
- docs/

‎docs/en/connectors-k8s/.gitkeep‎

Whitespace-only changes.

‎docs/en/connectors-k8s/.syncignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
development/**
2+
keps/**
3+
godocs/**

‎docs/en/connectors-k8s/concepts/index.mdx‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
weight: 40
3+
i18n:
4+
title:
5+
en: Concepts
6+
title: Concepts
7+
---
8+
9+
# Kubernetes Connector
10+
11+
<Overview />

‎docs/en/connectors-k8s/concepts/k8s_connectorclass.mdx‎

Lines changed: 234 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,234 @@
1+
---
2+
weight: 20
3+
---
4+
5+
# Kubernetes Connector
6+
7+
The Kubernetes connector is a platform-agnostic connector that you can use to connect to any Kubernetes cluster.
8+
9+
You can use the Kubernetes Connector to securely perform kubernetes operations in CICD pipelines, or use it in kubernetes workloads to perform kubernetes operations without credentials.
10+
11+
Additionally, you can centralize the management of kubernetes access configurations across namespaces, avoiding the need to repeat the kubernetes credentials in each namespace.
12+
13+
## Overview
14+
15+
This document covers:
16+
17+
- **Integration Requirements**: Prerequisites for target Kubernetes clusters
18+
- **Creating Kubernetes connector**
19+
- **Advanced Features**: Proxy capabilities and configuration capabilities about Kubernetes connector
20+
21+
## Integration Requirements
22+
23+
Target Kubernetes clusters must meet the following prerequisites:
24+
25+
- **CNCF Certification**: The cluster must be [CNCF Certified Kubernetes](https://www.cncf.io/training/certification/software-conformance/) compliant
26+
27+
## Creating a simple Kubernetes connector
28+
29+
Here's how to create a basic Kubernetes Connector:
30+
31+
```yaml
32+
# Authentication Secret
33+
apiVersion: v1
34+
kind: Secret
35+
metadata:
36+
name: k8s-secret
37+
type: connectors.cpaas.io/bearer-token
38+
stringData:
39+
token: eyJhbGciOiJSUzI1NiIxxxxxxxx # Replace with your actual bearer token
40+
---
41+
# Kubernetes Connector
42+
apiVersion: connectors.alauda.io/v1alpha1
43+
kind: Connector
44+
metadata:
45+
name: k8s-connector
46+
spec:
47+
connectorClassName: k8s
48+
address: https://192.168.1.100:6443
49+
auth:
50+
name: bearerTokenAuth
51+
secretRef:
52+
name: k8s-secret
53+
```
54+
55+
## Fields Reference
56+
57+
**spec.connectorClassName**:
58+
59+
`k8s` (constant), specifies the ConnectorClass name for Kubernetes integration.
60+
61+
**spec.address**:
62+
63+
Target Kubernetes cluster API server endpoint, for example: `https://192.168.1.100:6443`.
64+
65+
It also supports url with path, for example: `https://192.168.1.100:6443/kubernetes/global`, it is useful when the kubernetes cluster API server is exposed behind a proxy.
66+
67+
**spec.auth**:
68+
69+
specifies the authentication method of the kubernetes cluster
70+
71+
- `spec.auth.name`: should be `bearerTokenAuth` for kubernetes connector.
72+
73+
- `spec.auth.secretRef`: specifies the secret that contains the authentication information of the kubernetes cluster, the secret should be created in the same namespace as the connector.
74+
75+
**Optional Metadata fields**:
76+
77+
- `cpaas.io/description`: Description information for the kubernetes connector, for example:
78+
79+
```yaml
80+
apiVersion: connectors.alauda.io/v1alpha1
81+
kind: Connector
82+
metadata:
83+
name: k8s-connector
84+
annotations:
85+
cpaas.io/description: "Connect to team development kubernetes cluster"
86+
```
87+
88+
## Capabilities of Kubernetes Connector
89+
90+
### Authentication
91+
92+
The Kubernetes connector supports the following authentication types:
93+
94+
- `bearerTokenAuth`: Bearer token-based authentication, corresponding secret type: `connectors.cpaas.io/bearer-token`
95+
96+
For example:
97+
98+
```yaml
99+
apiVersion: v1
100+
stringData:
101+
token: your-k8s-bearer-token
102+
kind: Secret
103+
metadata:
104+
name: k8s-secret
105+
type: connectors.cpaas.io/bearer-token
106+
```
107+
108+
If the secret is not correct, the `status.conditions` field in the kubernetes connector will show the error message.
109+
110+
```yaml
111+
apiVersion: connectors.alauda.io/v1alpha1
112+
kind: Connector
113+
metadata:
114+
name: k8s-connector
115+
spec: {}
116+
status:
117+
conditions:
118+
- type: Ready
119+
status: False
120+
reason: "xxxxx"
121+
message: "xxxx"
122+
```
123+
124+
For comprehensive status information, see [Connector Status Documentation](../../connectors/concepts/connector.mdx#status-information).
125+
126+
### Proxy and Kubeconfig Configuration
127+
128+
To provide clients with the ability to access kubernetes resources without credentials, the Kubernetes connector provides a proxy server to automatically inject authentication information.
129+
130+
Clients can use this proxy server to access kubernetes resources without needing to configure credentials on the client side.
131+
132+
To simplify usage, the Kubernetes connectorclass provides `kubeconfig` files that can be mounted into Pods via CSI. In the Pod, when executing kubernetes operations, the proxy service can be automatically inject authentication information.
133+
134+
#### Proxy Address
135+
136+
Upon Connector creation, the system automatically provisions a proxy service for the target cluster.
137+
138+
The proxy endpoint is recorded in `status.proxy.httpAddress`:
139+
140+
For example:
141+
142+
```yaml
143+
apiVersion: connectors.alauda.io/v1alpha1
144+
kind: Connector
145+
metadata:
146+
name: k8s-connector
147+
spec:
148+
# connector spec fields
149+
status:
150+
conditions:
151+
# status conditions
152+
proxy:
153+
httpAddress:
154+
url: http://c-k8s-connector.default.svc.cluster.local
155+
```
156+
157+
#### kubeconfig configuration file {#kubeconfig-configuration-file}
158+
159+
The Kubernetes connector provides the following configuration:
160+
161+
**kubeconfig**:
162+
163+
- Provides a `kubeconfig` configuration file. Combined with the connector-csi-driver, this configuration file will be mounted into the Pod, allowing access to the kubernetes cluster through the proxy without needing to configure credentials on the client side.
164+
165+
Example of the configuration file generated in the Pod:
166+
167+
``` yaml
168+
apiVersion: v1
169+
kind: Config
170+
clusters:
171+
- name: k8s
172+
cluster:
173+
server: https://192.168.1.100:6443
174+
proxy-url: http://connector-namespace%2Fconnector-name:temporary-token@c-k8s-connector.connector-namespace.svc.cluster.local
175+
certificate-authority-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0xxxxxQo=
176+
contexts:
177+
- name: k8s
178+
context:
179+
cluster: k8s
180+
user: k8s
181+
users:
182+
- name: k8s
183+
user:
184+
token: fake-token
185+
current-context: k8s
186+
```
187+
188+
**Key Fields**:
189+
- **`server`**: Target Kubernetes API server endpoint
190+
- **`proxy-url`**: Connector proxy address with embedded proxy authentication
191+
- **`certificate-authority-data`**: Proxy server certificate for TLS validation
192+
193+
For detailed proxy mechanics, see [How It Works](../quick_start.mdx#what-happens-under-the-hood) in the Quick Start guide.
194+
195+
#### Using Connectors CSI Driver to mount kubeconfig file \{#using-connectors-csi-driver-to-mount-kubeconfig-file}
196+
197+
The Kubernetes connector provides a `kubeconfig` configuration file that can be mounted into the Pod via Connector CSI Driver.
198+
199+
For example:
200+
201+
``` yaml
202+
spec:
203+
volumes:
204+
- name: kubeconfig
205+
csi:
206+
readOnly: true
207+
driver: connectors-csi
208+
volumeAttributes:
209+
connector.name: "k8s-connector"
210+
configuration.names: "kubeconfig"
211+
```
212+
213+
parameter descriptions:
214+
215+
- `csi.readOnly`: Fixed value `true`
216+
- `csi.driver`: The Connector CSI Driver, fixed as `connectors-csi`.
217+
- `csi.volumeAttributes`: CSI Volume attributes
218+
- `connector.name`: Name of the Kubernetes Connector
219+
- `connector.namespace`: Namespace of the Kubernetes Connector; if not specified, the Pod's namespace is used
220+
- `configuration.names`: Configuration name, provide by the Kubernetes Connector. As above, `kubeconfig` is supported.
221+
222+
For detailed information about how to use the `kubeconfig` file in the Pod by connectors-csi-driver, please refer to [Using Kubernetes Connectors in kubernetes jobs](../quick_start.mdx)
223+
224+
## Further Reading
225+
226+
- [Using Kubernetes Connectors in kubernetes jobs](../quick_start.mdx)
227+
- [Using Kubernetes Connectors in tektoncd pipelines](../how_to/using-in-tekton-task.mdx)
228+
229+
## References
230+
231+
- [Concepts of Connector](../../connectors/concepts/connector.mdx)
232+
- [Connector Proxy](../../connectors/concepts/connectors_proxy.mdx)
233+
- [Connector CSI Driver](../../connectors/concepts/connectors_csi.mdx)
234+
- [Kubernetes CSI Volume](https://kubernetes.io/docs/concepts/storage/volumes/#csi)

‎docs/en/connectors-k8s/how_to/index.mdx‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
weight: 60
3+
i18n:
4+
title:
5+
en: How To
6+
title: How To
7+
---
8+
9+
# Practical Guide
10+
11+
<Overview />

‎docs/en/connectors-k8s/how_to/using-in-tekton-task.mdx‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
weight: 10
3+
title: Using Kubernetes Connector in Tekton Task
4+
---
5+
6+
# Using Kubernetes Connector in Tekton Task
7+
8+
Using Kubernetes Connector in Tekton Tasks enables centralized management of tool integration information and secure access to Kubernetes clusters during Tekton Task execution.
9+
10+
## Requirements for Tekton Task
11+
12+
Not all Tekton Tasks can use Kubernetes Connector.
13+
14+
Kubernetes Connector essentially injects temporary Kubernetes credentials through a Connector CSI Driver. It provides a configuration named `kubeconfig` that generates a `kubeconfig` file with temporary authentication.
15+
16+
Therefore, Tekton Tasks must meet the following requirements to use Kubernetes Connector:
17+
18+
**Support mounting a `kubeconfig` file via Workspace, and the Workspace must support providing only the `kubeconfig` file**
19+
20+
## Usage Instructions
21+
22+
After confirming that your Tekton Task can use Kubernetes Connector, you can add Kubernetes Connector to the TaskRun YAML file:
23+
24+
For example:
25+
26+
```yaml
27+
apiVersion: tekton.dev/v1
28+
kind: TaskRun
29+
metadata:
30+
name: k8s-connector-demo
31+
spec:
32+
# . . .
33+
workspaces:
34+
- name: kubeconfig
35+
csi:
36+
driver: connectors-csi
37+
readOnly: true
38+
volumeAttributes:
39+
connector.name: k8s-connector
40+
connector.namespace: ""
41+
configuration.names: "kubeconfig"
42+
```
43+
44+
For workspaces parameters, please refer to [Using Connectors CSI Driver to mount kubeconfig file](../concepts/k8s_connectorclass.mdx#using-connectors-csi-driver-to-mount-kubeconfig-file) in Kubernetes Connector Concepts document.
45+
46+
For more information about Connectors CSI Driver, please refer to [Connectors CSI Configuration](../../connectors/concepts/connectors_csi.mdx).
47+
48+
## Further Reading
49+
50+
- [Using Kubernetes Connector in kubernetes jobs](../quick_start.mdx)
51+
52+
## References
53+
54+
- [Using CSI Volumes in Tekton](https://tekton.dev/docs/pipelines/workspaces/#csi)
55+
- [Connectors CSI Configuration](../../connectors/concepts/connectors_csi.mdx)

‎docs/en/connectors-k8s/index.mdx‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Kubernetes Connector
2+
3+
<Overview overviewHeaders={[]} />

‎docs/en/connectors-k8s/intro.mdx‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
weight: 10
3+
---
4+
5+
# Introduction
6+
7+
## What is Kubernetes Connector
8+
9+
Kubernetes Connector is a specialized connector component that enables secure and convenient integration with Kubernetes clusters, allowing users to interact with Kubernetes clusters secretlessly in clients like `kubectl`.
10+
11+
Once Kubernetes Connector Component is deployed, users can:
12+
13+
- Create Kubernetes connectors to integrate with various Kubernetes clusters
14+
- Perform kubernetes operations in CI/CD pipelines or kubernetes workloads without directly handling credentials.
15+
16+
## Application Scenarios
17+
18+
The Kubernetes Connector allows you to perform kubernetes operations securely by:
19+
20+
- Managing credentials centrally rather than hardcoding them in clients
21+
- Automatically injecting authentication during the kubernetes operations
22+
23+
This approach is particularly useful for:
24+
25+
- `CI/CD pipelines` or `kubernetes jobs` requiring access kubernetes resources
26+
- Teams sharing kubernetes cluster access without sharing credentials
27+
- Environments requiring centralized management of kubernetes credentials without distributing credentials to each client

0 commit comments

Comments
 (0)