Skip to content

Commit d5ba59e

Browse files
negznegz
committed
Vale smells
Signed-off-by: Nic Cope <[email protected]>
1 parent 635ae86 commit d5ba59e

File tree

4 files changed

+77
-17
lines changed

4 files changed

+77
-17
lines changed

‎content/master/managed-resources/managed-resource-definitions.md

Lines changed: 63 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -7,14 +7,18 @@ description: ManagedResourceDefinitions enable selective activation of provider
77
---
88

99
{{<hint "important">}}
10-
Managed resource definitions are enabled by default in Crossplane v2.0+. This automatically converts provider CRDs to MRDs during installation. To disable this behavior, set `--enable-custom-to-managed-resource-conversion=false` when installing Crossplane.
10+
Crossplane v2.0+ enables managed resource definitions by default. This automatically converts provider CRDs to MRDs during installation. To disable this behavior, set `--enable-custom-to-managed-resource-conversion=false` when installing Crossplane.
1111
{{</hint>}}
1212

13-
A `ManagedResourceDefinition` (MRD) is a lightweight abstraction over Kubernetes CustomResourceDefinitions (CRDs) that enables selective activation of managed resources. MRDs solve the problem of providers installing hundreds of CRDs when you only need a few, reducing API server overhead and improving cluster performance.
13+
A `ManagedResourceDefinition` (MRD) is a lightweight abstraction over Kubernetes CustomResourceDefinitions (CRDs) that enables selective activation of managed resources. MRDs solve the problem of providers installing hundreds of CRDs when you only need some, reducing API server overhead and improving cluster performance.
1414

15+
<!-- vale Google.Headings = NO -->
16+
<!-- vale Microsoft.HeadingAcronyms = NO -->
1517
## The CRD scaling problem
18+
<!-- vale Google.Headings = YES -->
19+
<!-- vale Microsoft.HeadingAcronyms = YES -->
1620

17-
Large Crossplane providers can install 100+ managed resource CRDs. Each CRD consumes approximately 3 MiB of API server memory and creates API endpoints that affect cluster performance:
21+
Large Crossplane providers can install 100+ managed resource CRDs. Each CRD consumes about 3 MiB of API server memory and creates API endpoints that affect cluster performance:
1822

1923
- **Memory pressure**: Large providers can consume 300+ MiB of API server memory
2024
- **Slower kubectl operations**: Commands like `kubectl get managed` must query all custom resource endpoints
@@ -23,7 +27,11 @@ Large Crossplane providers can install 100+ managed resource CRDs. Each CRD cons
2327

2428
MRDs address this by allowing providers to ship resource definitions that only become active CRDs when explicitly needed.
2529

30+
<!-- vale Google.Headings = NO -->
31+
<!-- vale Microsoft.HeadingAcronyms = NO -->
2632
## How MRDs work
33+
<!-- vale Google.Headings = YES -->
34+
<!-- vale Microsoft.HeadingAcronyms = YES -->
2735

2836
An MRD contains the same schema as a CRD but adds two key fields:
2937

@@ -76,14 +84,18 @@ spec:
7684
- **Connection details documentation**: Schema for documenting available connection secrets
7785
- **One-way state transition**: MRDs can go from `Inactive` to `Active` but not back
7886

87+
<!-- vale Google.Headings = NO -->
88+
<!-- vale Microsoft.HeadingAcronyms = NO -->
7989
## MRD states
90+
<!-- vale Google.Headings = YES -->
91+
<!-- vale Microsoft.HeadingAcronyms = YES -->
8092

8193
### Inactive state
8294

8395
When `state: Inactive` (the default):
8496

8597
- No CRD exists in the cluster
86-
- No API endpoints are created
98+
- No API endpoints exist
8799
- The provider doesn't start a controller for this resource
88100
- Minimal memory and CPU overhead
89101

@@ -99,7 +111,7 @@ When `state: Active`:
99111
- Crossplane creates the corresponding CRD
100112
- API endpoints become available for the resource
101113
- The provider starts a controller to manage instances
102-
- Full functionality like traditional managed resources
114+
- Full capability like traditional managed resources
103115

104116
```yaml
105117
spec:
@@ -112,7 +124,7 @@ MRD state transitions are one-way only. Once an MRD becomes `Active`, it can't r
112124

113125
## Connection details documentation
114126

115-
MRDs can document what connection details a managed resource provides. This helps users understand what data will be available in connection secrets without having to create test resources.
127+
MRDs can document what connection details a managed resource provides. This helps users understand what data is available in connection secrets without having to create test resources.
116128

117129
```yaml
118130
spec:
@@ -128,12 +140,20 @@ spec:
128140
```
129141

130142
{{<hint "note">}}
131-
Connection details documentation is currently a schema-only feature. Most providers don't yet populate the `connectionDetails` field in their MRDs, but the structure is available for future implementation.
143+
Connection details documentation is a schema-only feature. Most providers don't populate the `connectionDetails` field in their MRDs, but the structure is available for implementation.
132144
{{</hint>}}
133145

146+
<!-- vale Google.Headings = NO -->
147+
<!-- vale Microsoft.HeadingAcronyms = NO -->
134148
## Working with MRDs
149+
<!-- vale Google.Headings = YES -->
150+
<!-- vale Microsoft.HeadingAcronyms = YES -->
135151

152+
<!-- vale Google.Headings = NO -->
153+
<!-- vale Microsoft.HeadingAcronyms = NO -->
136154
### Viewing MRDs
155+
<!-- vale Google.Headings = YES -->
156+
<!-- vale Microsoft.HeadingAcronyms = YES -->
137157

138158
List all MRDs in your cluster:
139159

@@ -147,7 +167,11 @@ View MRD details:
147167
kubectl describe mrd buckets.s3.aws.crossplane.io
148168
```
149169

170+
<!-- vale Google.Headings = NO -->
171+
<!-- vale Microsoft.HeadingAcronyms = NO -->
150172
### Checking MRD status
173+
<!-- vale Google.Headings = YES -->
174+
<!-- vale Microsoft.HeadingAcronyms = YES -->
151175

152176
MRDs provide status information about their lifecycle:
153177

@@ -163,30 +187,34 @@ status:
163187
**Status conditions:**
164188

165189
- **`Established: False, Reason: InactiveManagedResource`**: MRD is inactive, no CRD created
166-
- **`Established: Unknown, Reason: PendingManagedResource`**: CRD is being created
190+
- **`Established: Unknown, Reason: PendingManagedResource`**: CRD is under creation
167191
- **`Established: True, Reason: EstablishedManagedResource`**: CRD exists and is ready
168-
- **`Healthy: True, Reason: Running`**: MRD controller operating normally
192+
- **`Healthy: True, Reason: Running`**: MRD controller operating
169193
- **`Healthy: Unknown, Reason: EncounteredErrors`**: MRD controller experiencing issues
170194

195+
<!-- vale Google.Headings = NO -->
196+
<!-- vale Microsoft.HeadingAcronyms = NO -->
171197
### Manually activating MRDs
198+
<!-- vale Google.Headings = YES -->
199+
<!-- vale Microsoft.HeadingAcronyms = YES -->
172200

173201
You can manually activate an MRD by changing its state:
174202

175203
```shell
176204
kubectl patch mrd buckets.s3.aws.crossplane.io --type='merge' -p='{"spec":{"state":"Active"}}'
177205
```
178206

179-
However, the recommended approach is to use [ManagedResourceActivationPolicies]({{<ref "managed-resource-activation-policies">}}) for systematic activation.
207+
The recommended approach is to use [ManagedResourceActivationPolicies]({{<ref "managed-resource-activation-policies">}}) for systematic activation.
180208

181209
## How providers work with MRDs
182210

183211
Crossplane v2.0+ automatically converts all provider CRDs to MRDs during package installation, regardless of the provider's age or original format. The provider's `safe-start` capability determines the default MRD state:
184212

185213
### Providers with `safe-start` capability
186-
- MRDs are created with `state: Inactive` by default
214+
- MRDs start with `state: Inactive` by default
187215
- Support selective activation via [ManagedResourceActivationPolicies]({{<ref "managed-resource-activation-policies">}})
188216
- Reduced resource overhead for unused resources
189-
- Provider can safely start without all CRDs being active
217+
- Provider can start without all CRDs being active
190218

191219
```yaml
192220
# Provider package metadata
@@ -202,20 +230,30 @@ Crossplane uses fuzzy matching for capabilities, so `safe-start`, `safe_start`,
202230
{{</hint>}}
203231

204232
### Providers without `safe-start` capability
205-
- MRDs are created with `state: Active` by default (legacy behavior)
206-
- All CRDs are created immediately for backward compatibility
233+
- MRDs start with `state: Active` by default (legacy behavior)
234+
- All CRDs become available for backward compatibility
207235
- Full resource overhead like traditional providers
208236

209237

238+
<!-- vale Google.Headings = NO -->
239+
<!-- vale Microsoft.HeadingAcronyms = NO -->
210240
## Troubleshooting MRDs
241+
<!-- vale Google.Headings = YES -->
242+
<!-- vale Microsoft.HeadingAcronyms = YES -->
211243

244+
<!-- vale Google.Headings = NO -->
245+
<!-- vale Microsoft.HeadingAcronyms = NO -->
212246
### MRD exists but no CRD appears
247+
<!-- vale Google.Headings = YES -->
248+
<!-- vale Microsoft.HeadingAcronyms = YES -->
213249

250+
<!-- vale Google.Colons = NO -->
214251
**Symptoms**: MRD is present but `kubectl get <resource>` shows "no resources found"
215252

216253
**Cause**: MRD is in `Inactive` state
217254

218255
**Solution**: Activate the MRD using an [ManagedResourceActivationPolicy]({{<ref "managed-resource-activation-policies">}}) or manually patch the state
256+
<!-- vale Google.Colons = YES -->
219257

220258
```shell
221259
# Check MRD state
@@ -225,21 +263,27 @@ kubectl get mrd <name> -o jsonpath='{.spec.state}'
225263
kubectl patch mrd <name> --type='merge' -p='{"spec":{"state":"Active"}}'
226264
```
227265

266+
<!-- vale Google.Headings = NO -->
267+
<!-- vale Microsoft.HeadingAcronyms = NO -->
228268
### MRD activation fails
269+
<!-- vale Google.Headings = YES -->
270+
<!-- vale Microsoft.HeadingAcronyms = YES -->
229271

272+
<!-- vale Google.Colons = NO -->
230273
**Symptoms**: MRD state is `Active` but `Established` condition remains `False`
231274

232275
**Cause**: CRD creation failed due to schema issues or conflicts
233276

234277
**Solution**: Check MRD events and status for error details
278+
<!-- vale Google.Colons = YES -->
235279

236280
```shell
237281
kubectl describe mrd <name>
238282
```
239283

240-
**Additional status conditions for troubleshooting:**
284+
**Other status conditions for troubleshooting:**
241285
- **`Established: False, Reason: BlockedManagedResourceActivationPolicy`**: Blocked by activation policy issues
242-
- **`Established: False, Reason: TerminatingManagedResource`**: MRD is being deleted
286+
- **`Established: False, Reason: TerminatingManagedResource`**: MRD is under deletion
243287

244288
**Common events you might see:**
245289
- `Normal CreateCustomResourceDefinition` - CRD successfully created
@@ -249,17 +293,19 @@ kubectl describe mrd <name>
249293
- `Warning Reconcile` - General reconciliation errors
250294

251295
Common issues:
252-
- Invalid OpenAPI schema in the MRD
296+
- Malformed OpenAPI schema in the MRD
253297
- CRD name conflicts with existing resources
254298
- Insufficient RBAC permissions for Crossplane
255299

256300
### Provider doesn't support activation
257301

302+
<!-- vale Google.Colons = NO -->
258303
**Symptoms**: Provider starts all controllers regardless of MRD states
259304

260305
**Cause**: Provider doesn't implement late activation support
261306

262307
**Solution**: Check provider capabilities and use a compatible provider version
308+
<!-- vale Google.Colons = YES -->
263309

264310
```shell
265311
# Check if provider supports late activation

‎utils/vale/styles/Crossplane/allowed-jargon.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ command-line
2222
ConfigMap
2323
ConfigMaps
2424
CRD
25+
CustomResourceDefinitions
2526
cron
2627
CronJobs
2728
crt
@@ -57,6 +58,7 @@ kubectl
5758
kv
5859
KV
5960
metrics-server
61+
MiB
6062
minikube
6163
multi-platform
6264
namespace

‎utils/vale/styles/Crossplane/crossplane-words.txt

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,16 @@ initProvider
6161
KCL
6262
LateInitialize
6363
managementPolicies
64+
ManagedResourceActivationPolicies
65+
ManagedResourceActivationPolicy
66+
ManagedResourceDefinition
67+
ManagedResourceDefinitions
6468
MR
69+
MRD
70+
MRD's
71+
MRDs
72+
MRAP
73+
MRAPs
6574
MRs
6675
Operation-specific
6776
PatchSet

‎utils/vale/styles/Crossplane/spelling-exceptions.txt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,8 +43,10 @@ namespace-scoped
4343
non-empty
4444
non-Kubernetes
4545
non-production
46+
One-way
4647
one-time
4748
One-time
49+
one-way
4850
Operation-level
4951
per-element
5052
performant
@@ -62,6 +64,7 @@ resource-intensive
6264
resource-specific
6365
right-hand
6466
run-time
67+
schema-only
6568
self-service
6669
self-signed
6770
space-delimited

0 commit comments

Comments
 (0)