Skip to content

Commit 7a1cd1c

Browse files
andywgarciaandywgarcia
authored
Merge pull request #1 from andywgarcia/garcia/change-to-operator
Garcia/change to operator
2 parents 21f8e11 + de6c9e7 commit 7a1cd1c

File tree

161 files changed

+4134
-493
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

161 files changed

+4134
-493
lines changed

‎README.md‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,14 @@ This repository contains a reference architecture utilizing [Kubernetes](https:/
44

55
Once the architecture is fully stood up, you'll have:
66

7-
- An Apollo Router running utilizing:
7+
- An Apollo Router running and managed by the [Apollo GraphOS Operator](https://www.apollographql.com/docs/apollo-operator/), utilizing:
88
- [Persisted Queries for safelisting operations](https://www.apollographql.com/docs/router/configuration/persisted-queries/#differences-from-automatic-persisted-queries)
99
- [A coprocessor for handling customizations outside of the router](https://www.apollographql.com/docs/router/customizations/coprocessor)
1010
- [Rhai scripts to do basic customizations within the router container](https://www.apollographql.com/docs/router/customizations/rhai)
1111
- [Authorization/Authentication directives](https://www.apollographql.com/docs/router/configuration/authorization)
12-
- Eight subgraphs, each handling a portion of the overall supergraph schema
12+
- Eight subgraphs, each handling a portion of the overall supergraph schema, with schemas automatically published to GraphOS via the operator
1313
- A React-based frontend application utilizing Apollo Client
14-
- GitHub Actions to automate image building and GraphOS-specific implementations, including schema publishing and persisted query manifest creation/publishing
14+
- Apollo GraphOS Operator for automated schema publishing, composition, and deployment
1515
- Tools to run k6 load tests against the architecture from within the same cluster
1616

1717
### The ending architecture
@@ -45,6 +45,14 @@ During setup, you'll be:
4545
- Provisioning resources
4646
- Deploying the applications, including router, subgraphs, client, and observability tools
4747

48+
### [Operator Guide](/docs/operator-guide.md)
49+
50+
Learn how the Apollo GraphOS Operator works in this architecture, including:
51+
- Schema publishing and composition flow
52+
- Monitoring operator-managed resources
53+
- Troubleshooting common issues
54+
- Updating router configuration
55+
4856
### [Cleanup](/docs/cleanup.md)
4957

5058
Once finished, you can cleanup your environments following the above document.

‎deploy/client/values.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
replicaCount: 3
22

33
image:
4-
repository: ghcr.io/apollosolutions/reference-architecture/client
4+
repository: ghcr.io/${GITHUB_ORG}/reference-architecture/client
55
pullPolicy: Always
66
tag: main
77

‎deploy/coprocessor/values.yaml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
1+
namespace: apollo
2+
13
replicaCount: 3
24

35
image:
4-
repository: ghcr.io/apollosolutions/reference-architecture/coprocessor
6+
repository: ghcr.io/${GITHUB_ORG}/reference-architecture/coprocessor
57
pullPolicy: Always
68
tag: main
79

‎deploy/operator-resources/ROUTER_CONFIG_MIGRATION.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
# Router Configuration Migration Guide
2+
3+
This document describes how the router configuration from `deploy/router/values.yaml` was migrated to operator-managed Supergraph CRDs.
4+
5+
## Migration Summary
6+
7+
All router configuration has been moved from Helm values (`deploy/router/values.yaml`) into the Supergraph CRD specifications:
8+
- `deploy/operator-resources/supergraph-dev.yaml` (dev environment)
9+
- `deploy/operator-resources/supergraph-prod.yaml` (prod environment)
10+
11+
## Configuration Mapping
12+
13+
### Core Router Settings (Both Dev and Prod)
14+
15+
| Previous Location | New Location | Value |
16+
|-------------------|--------------|-------|
17+
| `router.configuration.health_check` | `spec.podTemplate.router.configuration.health_check` | `listen: 0.0.0.0:8080` |
18+
| `router.configuration.sandbox` | `spec.podTemplate.router.configuration.sandbox` | `enabled: true` |
19+
| `router.configuration.homepage` | `spec.podTemplate.router.configuration.homepage` | `enabled: false` |
20+
| `router.configuration.supergraph` | `spec.podTemplate.router.configuration.supergraph` | `introspection: true` |
21+
| `router.configuration.include_subgraph_errors` | `spec.podTemplate.router.configuration.include_subgraph_errors` | `all: true` |
22+
| `router.configuration.plugins` | `spec.podTemplate.router.configuration.plugins` | `experimental.expose_query_plan: true` |
23+
24+
### Authentication & Authorization
25+
26+
- **JWKS Authentication**: Points to `http://graphql.users.svc.cluster.local:4001/.well-known/jwks.json`
27+
- **Authorization Preview Directives**: Enabled for all subgraphs
28+
29+
### Coprocessor Configuration
30+
31+
- **URL**: `http://coprocessor.coprocessor.svc.cluster.local:8081`
32+
- **Timeout**: 2s
33+
- **Router Request Headers**: Enabled
34+
- **Subgraph Request/Response Headers**: Enabled
35+
36+
### Rhai Scripts
37+
38+
Rhai scripts are handled via ConfigMap and volume mounts:
39+
- **Scripts Location**: `/dist/rhai` (mounted from ConfigMap)
40+
- **Main Script**: `main.rhai`
41+
- **Helper Scripts**: `client_id.rhai`
42+
43+
The ConfigMap must be created separately:
44+
```bash
45+
kubectl create configmap rhai-config --from-file=deploy/router/rhai/ -n apollo
46+
```
47+
48+
### Prod-Only Configuration
49+
50+
The following configurations are only present in `supergraph-prod.yaml`:
51+
52+
#### Persisted Queries
53+
54+
```yaml
55+
persisted_queries:
56+
enabled: true
57+
log_unknown: true
58+
safelist:
59+
enabled: false
60+
require_id: false
61+
```
62+
63+
#### Telemetry
64+
65+
- **Apollo Field-Level Instrumentation**: Sampler 0.5
66+
- **OTLP Tracing**: gRPC endpoint `http://collector.monitoring:4317`
67+
- **OTLP Metrics**: gRPC endpoint `http://collector.monitoring:4317`
68+
- **Service Name**: "router"
69+
- **Service Namespace**: "router"
70+
71+
## How to Update Router Configuration
72+
73+
To update router configuration without redeploying subgraphs:
74+
75+
1. Edit the appropriate Supergraph CRD file:
76+
- Dev: `deploy/operator-resources/supergraph-dev.yaml`
77+
- Prod: `deploy/operator-resources/supergraph-prod.yaml`
78+
79+
2. Update the `spec.podTemplate.router.configuration` section
80+
81+
3. Apply the changes:
82+
```bash
83+
kubectl apply -f deploy/operator-resources/supergraph-{dev|prod}.yaml
84+
```
85+
86+
4. The operator will automatically trigger a router rollover with the new configuration
87+
88+
## Resources
89+
90+
Dev environment uses minimal resources:
91+
- CPU: 100m
92+
- Memory: 256Mi
93+
- Replicas: 1
94+
95+
Prod environment uses production-grade resources:
96+
- CPU: 500m
97+
- Memory: 512Mi
98+
- Replicas: 3
99+
100+
## Differences from Helm Chart
101+
102+
The operator-managed approach differs from the Helm chart in several ways:
103+
104+
1. **No Helm templates**: Configuration is defined in Kubernetes-native CRDs
105+
2. **Automatic rollover**: The operator handles rolling out changes to the router
106+
3. **Declarative**: All configuration is version-controlled in YAML files
107+
4. **Condition-based**: Can monitor router status via `kubectl get supergraph`
108+
109+
## Troubleshooting
110+
111+
### Router not picking up changes
112+
113+
Check the Supergraph status:
114+
```bash
115+
kubectl describe supergraph reference-architecture-{dev|prod} -n apollo
116+
```
117+
118+
Look for:
119+
- `SchemaLoaded`: Should be `True`
120+
- `Progressing`: Shows deployment status
121+
- `Ready`: Should be `True` when fully deployed
122+
123+
### Rhai scripts not working
124+
125+
Verify the ConfigMap exists and is mounted:
126+
```bash
127+
kubectl get configmap rhai-config -n apollo
128+
kubectl describe pod <router-pod> -n apollo | grep rhai-volume
129+
```
130+
131+
### Coprocessor connection issues
132+
133+
Ensure coprocessor is running and accessible:
134+
```bash
135+
kubectl get pods -n coprocessor
136+
kubectl get svc -n coprocessor
137+
```
138+
139+
## Current Configuration Status
140+
141+
The Supergraph CRDs in this repository use a **simplified configuration** that does not include all the advanced router settings from the original Helm chart. This is because the current Apollo GraphOS Operator CRD does not support all configuration fields.
142+
143+
### Supported Configuration
144+
- ✅ Replicas count
145+
- ✅ Router version
146+
- ✅ Resource limits/requests
147+
- ✅ Schema source (SupergraphSchema resource reference)
148+
149+
### Not Currently Supported in Supergraph CRD
150+
- ❌ Custom router configuration (JWKS auth, coprocessor, CORS, etc.)
151+
- ❌ Rhai scripts via ConfigMap volumes
152+
- ❌ Custom ingress configuration
153+
- ❌ Service type customization
154+
- ❌ Telemetry exporters
155+
- ❌ Advanced authentication/authorization
156+
157+
### Operator API Key Setup
158+
159+
The operator requires an **Operator API key** (not a personal API key). To create one:
160+
161+
1. Go to GraphOS Studio
162+
2. Navigate to your graph → Settings → API Keys
163+
3. Create a new API key with "Operator" role
164+
4. Update the `apollo-api-key` secret with the Operator API key:
165+
```bash
166+
kubectl create secret generic apollo-api-key \
167+
--from-literal="APOLLO_KEY=<your-operator-api-key>" \
168+
-n apollo-operator \
169+
--dry-run=client -o yaml | kubectl apply -f -
170+
```
171+
172+
### TODO: Advanced Router Configuration
173+
174+
The advanced router configuration (JWKS, coprocessor, Rhai scripts, telemetry, persisted queries) from the original `deploy/router/values.yaml` has not been migrated yet. This would need to be implemented either:
175+
176+
1. Via router configuration YAML file in a ConfigMap (if supported)
177+
2. Through GraphOS Studio router configuration
178+
3. By extending the operator to support these fields
179+
4. By using a custom router deployment instead of the operator-managed one
180+
181+
### Current Status
182+
183+
- Graph is created ✅
184+
- Dev and prod variants created ✅
185+
- Subgraphs deployed and CRDs created ✅
186+
- Operator API key needs to be set up ⚠️
187+
- Advanced router configuration not yet migrated ⏳
188+

‎deploy/operator-resources/apply-resources.sh‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
#!/bin/bash
2+
set -euo pipefail
3+
4+
# This script applies the operator resources with the correct graph ID
5+
# Usage: ./apply-resources.sh {dev|prod}
6+
7+
ENVIRONMENT=${1:-dev}
8+
9+
if [[ "$ENVIRONMENT" != "dev" && "$ENVIRONMENT" != "prod" ]]; then
10+
echo "Error: Environment must be 'dev' or 'prod'"
11+
exit 1
12+
fi
13+
14+
# Check if TF_VAR_apollo_graph_id is set
15+
if [[ -z "${TF_VAR_apollo_graph_id:-}" ]]; then
16+
echo "Error: TF_VAR_apollo_graph_id is not set. Please source .env file from your terraform directory."
17+
exit 1
18+
fi
19+
20+
echo "Deploying operator resources for ${ENVIRONMENT} environment with graph ID: ${TF_VAR_apollo_graph_id}"
21+
22+
# Apply SupergraphSchema with graph ID substitution
23+
if command -v envsubst &> /dev/null; then
24+
envsubst < "supergraphschema-${ENVIRONMENT}.yaml" | kubectl apply -f -
25+
else
26+
# Fallback if envsubst not available
27+
sed "s|\${TF_VAR_apollo_graph_id}|${TF_VAR_apollo_graph_id}|g" "supergraphschema-${ENVIRONMENT}.yaml" | kubectl apply -f -
28+
fi
29+
30+
# Apply Supergraph
31+
kubectl apply -f "supergraph-${ENVIRONMENT}.yaml"
32+
33+
# Apply Ingress
34+
kubectl apply -f "ingress-${ENVIRONMENT}.yaml"
35+
36+
echo "Operator resources deployed successfully for ${ENVIRONMENT} environment"
37+

‎deploy/operator-resources/ingress-dev.yaml‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
apiVersion: networking.k8s.io/v1
2+
kind: Ingress
3+
metadata:
4+
name: router
5+
namespace: apollo
6+
spec:
7+
defaultBackend:
8+
service:
9+
name: router
10+
port:
11+
number: 80
12+

‎deploy/operator-resources/ingress-prod.yaml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
apiVersion: networking.k8s.io/v1
2+
kind: Ingress
3+
metadata:
4+
name: router
5+
namespace: apollo
6+
annotations:
7+
cloud.google.com/backend-config: '{"default": "http-hc-config"}'
8+
spec:
9+
defaultBackend:
10+
service:
11+
name: router
12+
port:
13+
number: 80
14+

‎deploy/operator-resources/supergraph-dev.yaml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
apiVersion: apollographql.com/v1alpha2
2+
kind: Supergraph
3+
metadata:
4+
name: reference-architecture-dev
5+
namespace: apollo
6+
spec:
7+
replicas: 1
8+
serviceName: router
9+
podTemplate:
10+
routerVersion: 1.37.0
11+
resources:
12+
requests:
13+
cpu: 100m
14+
memory: 256Mi
15+
schema:
16+
resource:
17+
name: reference-architecture-dev
18+
namespace: apollo
19+

‎deploy/operator-resources/supergraph-prod.yaml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
apiVersion: apollographql.com/v1alpha2
2+
kind: Supergraph
3+
metadata:
4+
name: reference-architecture-prod
5+
namespace: apollo
6+
spec:
7+
replicas: 3
8+
serviceName: router
9+
podTemplate:
10+
routerVersion: 1.37.0
11+
resources:
12+
requests:
13+
cpu: 500m
14+
memory: 512Mi
15+
schema:
16+
resource:
17+
name: reference-architecture-prod
18+
namespace: apollo
19+

‎deploy/operator-resources/supergraphschema-dev.yaml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
apiVersion: apollographql.com/v1alpha2
2+
kind: SupergraphSchema
3+
metadata:
4+
name: reference-architecture-dev
5+
namespace: apollo
6+
spec:
7+
graphRef: ${TF_VAR_apollo_graph_id}@dev
8+
selectors:
9+
- matchExpressions:
10+
- key: apollo.io/subgraph
11+
operator: Exists
12+
partial: false
13+

0 commit comments

Comments
 (0)
⚡