Skip to content

Commit e332a37

Browse files
vertex451vertex451
committed
improved docs
1 parent dfa9b29 commit e332a37

12 files changed

+464
-383
lines changed

‎README.md‎

Lines changed: 8 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -16,37 +16,17 @@ This repository contains two main components:
1616
- [Listener](./docs/listener.md): watches a cluster and stores its openAPI spec in a directory.
1717
- [Gateway](./docs/gateway.md): exposes the openAPI spec as a GraphQL endpoints.
1818

19-
## MultiCluster Support
19+
## Operation Modes
2020

21-
The system supports three modes of operation:
21+
The system supports two modes of operation:
2222

23-
1. **Single Cluster** (`ENABLE_KCP=false`, `MULTICLUSTER=false`): Gateway connects to the same cluster as the listener
24-
2. **KCP Mode** (`ENABLE_KCP=true`): Designed for KCP-based multi-cluster scenarios
25-
3. **MultiCluster Mode** (`ENABLE_KCP=false`, `MULTICLUSTER=true`): Gateway connects to multiple external clusters via ClusterAccess resources
23+
1. **KCP Mode** (`ENABLE_KCP=true`): Designed for KCP-based multi-cluster scenarios
24+
- See [Virtual Workspaces](./docs/virtual-workspaces.md) for advanced KCP configuration
25+
2. **ClusterAccess Mode** (`ENABLE_KCP=false`): Designed for support of multiple standard clusters.
2626

27-
### MultiCluster with ClusterAccess
27+
## ClusterAccess
2828

29-
In MultiCluster mode, the system uses ClusterAccess resources to store kubeconfig data and connection information. The listener processes these resources and embeds connection metadata into schema files, which the gateway then uses to establish cluster-specific connections.
30-
31-
For complete setup instructions, see:
32-
- [ClusterAccess documentation](./docs/clusteraccess.md) - Manual setup
33-
- [MultiCluster Kubeconfig Flow](./docs/multicluster-kubeconfig-flow.md) - Detailed flow explanation
34-
35-
### Quick Setup Scripts
36-
37-
```bash
38-
# Create ClusterAccess with secure token authentication
39-
./scripts/create-clusteraccess.sh --target-kubeconfig ~/.kube/prod-config
40-
41-
# Test end-to-end integration
42-
./scripts/test-clusteraccess-integration.sh
43-
```
44-
45-
### Gateway Requirements
46-
47-
- **Single Cluster Mode**: Requires KUBECONFIG to connect to the local cluster
48-
- **KCP Mode**: Requires KUBECONFIG to connect to KCP management cluster
49-
- **MultiCluster Mode**: Does NOT require KUBECONFIG - gets all connection info from schema files
29+
For detailed information, see [Clusteraccess](./docs/clusteraccess.md) section.
5030

5131
## Authorization
5232

@@ -71,3 +51,4 @@ If you find any bug that may be a security problem, please follow our instructio
7151
## Licensing
7252

7353
Copyright 2025 SAP SE or an SAP affiliate company and platform-mesh contributors. Please see our [LICENSE](LICENSE) for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available [via the REUSE tool](https://api.reuse.software/info/github.com/platform-mesh/kubernetes-graphql-gateway).
54+

‎docs/authorization.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
All requests must contain an `Authorization` header with a valid Bearer token by default:
44
```shell
55
{
6-
"Authorization": $YOUR_TOKEN
6+
"Authorization": "Bearer $YOUR_TOKEN"
77
}
88
```
99
You can disable authorization by setting the following environment variable:
@@ -14,21 +14,21 @@ This is useful for local development and testing purposes.
1414

1515
## Introspection authentication
1616

17-
By default, introspection requests (i.e. the requests that are made to fetch the GraphQL schema) are **not** protected by authorization.
17+
By default, introspection requests (i.e., the requests that are made to fetch the GraphQL schema) are **not** protected by authorization.
1818

1919
You can protect those requests by setting the following environment variable:
2020
```shell
21-
export INTROSPECTION_AUTHENTICATION=true
21+
export GATEWAY_INTROSPECTION_AUTHENTICATION=true
2222
```
2323

24-
### Error fetching schema
24+
### Error fetching schema in documentation explorer
2525

26-
When GraphiQL page is loaded, it makes a request to fetch the GraphQL schema and there is no way to add the `Authorization` header to that request.
26+
When the GraphiQL page is loaded, it makes a request to fetch the GraphQL schema, and there is no way to add the `Authorization` header to that request.
2727

2828
We have this [issue](https://github.com/openmfp/kubernetes-graphql-gateway/issues/217) open to fix this.
2929

3030
But for now, you can use the following workaround:
3131
1. Open the GraphiQL page in your browser.
32-
2. Add the `Authorization` header in the `Headers` section of the GraphiQL user interface like so:
33-
3. Press `Re-fetch GraphQL schema` button in the left sidebar(third button from the top).
34-
4. Now the GraphQL schema should be fetched, and you can use the GraphiQL interface as usual.
32+
2. Add the `Authorization` header in the `Headers` section of the GraphiQL user interface.
33+
3. Press the `Re-fetch GraphQL schema` button in the left sidebar (third button from the top).
34+
4. The GraphQL schema should now be fetched, and you can use the GraphiQL interface as usual.

‎docs/clusteraccess-setup.md‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
# ClusterAccess Resource Setup
2+
3+
To enable the gateway to access external Kubernetes clusters, you need to create ClusterAccess resources. This section provides both an automated script and manual step-by-step instructions.
4+
5+
## Quick Setup (Recommended)
6+
7+
For development purposes, use the provided script to automatically create ClusterAccess resources:
8+
9+
**Example:**
10+
```bash
11+
./hack/create-clusteraccess.sh --target-kubeconfig ~/.kube/platform-mesh-config --management-kubeconfig ~/.kube/platform-mesh-config
12+
```
13+
14+
The script will:
15+
- Extract cluster name, server URL, and CA certificate from the target kubeconfig
16+
- Create a ServiceAccount with cluster-admin access in the target cluster
17+
- Generate a long-lived token for the ServiceAccount
18+
- Create the admin kubeconfig and CA secrets in the management cluster
19+
- Create the ClusterAccess resource with kubeconfig-based authentication
20+
- Output a copy-paste ready bearer token for direct API access
21+
22+
## Manual Setup
23+
24+
## Prerequisites
25+
26+
- Access to the target cluster (the cluster you want to expose via GraphQL)
27+
- Access to the management cluster (the cluster where the gateway runs)
28+
- ClusterAccess CRDs installed in the management cluster
29+
- Target cluster kubeconfig file
30+
31+
## Step 1: Create ServiceAccount with Admin Access in Target Cluster
32+
33+
```bash
34+
# Switch to target cluster
35+
export KUBECONFIG=/path/to/target-cluster-kubeconfig
36+
37+
# Create ServiceAccount with cluster-admin access
38+
cat <<EOF | kubectl apply -f -
39+
apiVersion: v1
40+
kind: ServiceAccount
41+
metadata:
42+
name: kubernetes-graphql-gateway-admin
43+
namespace: default
44+
---
45+
apiVersion: rbac.authorization.k8s.io/v1
46+
kind: ClusterRoleBinding
47+
metadata:
48+
name: kubernetes-graphql-gateway-admin-cluster-admin
49+
roleRef:
50+
apiGroup: rbac.authorization.k8s.io
51+
kind: ClusterRole
52+
name: cluster-admin
53+
subjects:
54+
- kind: ServiceAccount
55+
name: kubernetes-graphql-gateway-admin
56+
namespace: default
57+
---
58+
apiVersion: v1
59+
kind: Secret
60+
metadata:
61+
name: kubernetes-graphql-gateway-admin-token
62+
namespace: default
63+
annotations:
64+
kubernetes.io/service-account.name: kubernetes-graphql-gateway-admin
65+
type: kubernetes.io/service-account-token
66+
EOF
67+
```
68+
69+
## Step 2: Extract CA Certificate from Target Cluster
70+
71+
```bash
72+
# Extract CA certificate from kubeconfig
73+
kubectl config view --raw --minify -o jsonpath='{.clusters[0].cluster.certificate-authority-data}' | base64 -d
74+
```
75+
76+
Copy the output (should start with `-----BEGIN CERTIFICATE-----` and end with `-----END CERTIFICATE-----`).
77+
78+
## Step 3: Get Target Cluster Server URL
79+
80+
```bash
81+
# Get the server URL
82+
kubectl config view --raw --minify -o jsonpath='{.clusters[0].cluster.server}'
83+
```
84+
85+
Copy the server URL (e.g., `https://127.0.0.1:58308`).
86+
87+
## Step 4: Switch Back to Management Cluster
88+
89+
```bash
90+
# Switch to the cluster where you'll create ClusterAccess
91+
export KUBECONFIG=/path/to/management-cluster-kubeconfig
92+
93+
# Install ClusterAccess CRD if not already installed
94+
kubectl apply -f config/crd/
95+
```
96+
97+
## Step 5: Create Secrets and ClusterAccess in Management Cluster
98+
99+
Create a file called `my-cluster-access.yaml`:
100+
101+
```yaml
102+
# Secret containing CA certificate for target-cluster
103+
apiVersion: v1
104+
kind: Secret
105+
metadata:
106+
name: my-target-cluster-ca
107+
namespace: default
108+
type: Opaque
109+
stringData:
110+
ca.crt: |
111+
PASTE_CA_CERTIFICATE_FROM_STEP_2_HERE
112+
113+
---
114+
# Secret containing admin kubeconfig for target-cluster
115+
apiVersion: v1
116+
kind: Secret
117+
metadata:
118+
name: my-target-cluster-admin-kubeconfig
119+
namespace: default
120+
type: Opaque
121+
data:
122+
kubeconfig: BASE64_ENCODED_TARGET_KUBECONFIG_HERE
123+
124+
---
125+
# ClusterAccess resource for target-cluster
126+
apiVersion: gateway.platform-mesh.io/v1alpha1
127+
kind: ClusterAccess
128+
metadata:
129+
name: my-target-cluster
130+
spec:
131+
path: my-target-cluster # This becomes the filename in bin/definitions/
132+
host: PASTE_SERVER_URL_FROM_STEP_3_HERE
133+
ca:
134+
secretRef:
135+
name: my-target-cluster-ca
136+
namespace: default
137+
key: ca.crt
138+
auth:
139+
kubeconfigSecretRef:
140+
name: my-target-cluster-admin-kubeconfig
141+
namespace: default
142+
```
143+
144+
To encode the kubeconfig:
145+
```bash
146+
cat /path/to/target-cluster-kubeconfig | base64
147+
```
148+
149+
## Step 6: Apply the Configuration
150+
151+
```bash
152+
kubectl apply -f my-cluster-access.yaml
153+
```
154+
155+
## Step 7: Verify Resources
156+
157+
```bash
158+
# Check if ClusterAccess was created
159+
kubectl get clusteraccess
160+
161+
# Check if secrets were created
162+
kubectl get secret my-target-cluster-admin-kubeconfig my-target-cluster-ca
163+
```
164+
165+
## Step 8: Test with Listener
166+
167+
```bash
168+
export ENABLE_KCP=false
169+
export GATEWAY_SHOULD_IMPERSONATE=false
170+
export LOCAL_DEVELOPMENT=false
171+
export KUBECONFIG=/path/to/management-cluster-kubeconfig
172+
task listener
173+
```
174+
175+
## Key Points
176+
177+
- **ServiceAccount**: Created in the target cluster with cluster-admin access for full permissions
178+
- **Kubeconfig**: Stored as a secret in the management cluster for authentication
179+
- **CA Certificate**: Essential for TLS verification - without it you'll get certificate errors
180+
- **Server URL**: Must match exactly from the target cluster's kubeconfig
181+
- **Path**: Becomes the schema filename (e.g., `my-target-cluster`) in `bin/definitions/`
182+
- **Secrets**: Keep them in the same namespace as the ClusterAccess resource
183+
184+
The listener will detect the ClusterAccess resource and generate schema files with metadata that the gateway can use to access the target cluster.

0 commit comments

Comments
 (0)