Add guides for the storage version migration library - #719
Conversation
Signed-off-by: Sergen Yalçın <yalcinsergen97@gmail.com>
📝 WalkthroughWalkthroughChangesStorage Version Migration
Estimated code review effort: 2 (Simple) | ~10 minutes Suggested reviewers: 🚥 Pre-merge checks | ✅ 7✅ Passed checks (7 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/applying-storage-version-migration.md`:
- Around line 173-188: Update Step 5 to instruct users to remove or change the
Provider’s spec.runtimeConfigRef.name reference, apply the change, and wait for
the provider to become healthy before deleting the temporary
DeploymentRuntimeConfig. Clarify that shared RBAC resources must remain until
every migration sub-provider using them has completed.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 6aabf01a-812c-44fc-b86f-73b18434934a
📒 Files selected for processing (2)
docs/applying-storage-version-migration.mddocs/storage-version-migration.md
| ## Step 5 — Clean Up | ||
|
|
||
| The migration only needs to run once for a given storage version change. | ||
|
|
||
| After the provider is healthy and the migration has been verified, the | ||
| `DeploymentRuntimeConfig` and the temporary RBAC resources are no longer needed | ||
| and can be removed. | ||
|
|
||
| Crossplane restarts the provider one final time without the init container. | ||
|
|
||
| --- | ||
|
|
||
| If multiple sub-providers are being upgraded (for example `provider-gcp-storage` | ||
| and `provider-gcp-compute`), the same process applies to each provider. Each | ||
| sub-provider uses its own `DeploymentRuntimeConfig`, while the RBAC resources | ||
| can be shared. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Locate and inspect the relevant documentation and any schema/references around DeploymentRuntimeConfig.
printf '===== file list =====\n'
git ls-files | rg '(^docs/|RuntimeConfig|Provider|^.*\.go$|.*\.md$)' | head -200
printf '\n===== target document excerpt =====\n'
sed -n '1,230p' docs/applying-storage-version-migration.md | nl -ba | sed -n '130,210p'
printf '\n===== references to runtimeConfigRef / DeploymentRuntimeConfig / RBAC =====\n'
rg -n "runtimeConfigRef|DeploymentRuntimeConfig|sv-migration|provider-migration|RBAC|roles|clusterroles|clusterrole" docs -S
printf '\n===== all docs Markdown files =====\n'
git ls-files 'docs/**/*.md' 'docs/*.md' | sed -n '1,120p'Repository: crossplane/upjet
Length of output: 6656
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '===== repository search for migration storage version docs patterns =====\n'
rg -n "storage version|storage-version|applying-storage-version-migration|provider-gcp-storage|provider-gcp-compute|DeploymentRuntimeConfig|runtimeConfigRef" . -S --glob '!vendor/**' --glob '!*.lock' --glob '!node_modules/**' | head -300
printf '\n===== inspect likely schema/models around Provider spec runtimeConfigRef =====\n'
rg -n "type Provider|runtimeConfigRef|DeploymentRuntimeConfig" -S --glob '*.go' --glob '*.yaml' --glob '!vendor/**' | head -400Repository: crossplane/upjet
Length of output: 12620
🌐 Web query:
Crossplane DeploymentRuntimeConfig runtimeConfigRef can't be deleted while referenced by Provider
💡 Result:
In Crossplane, the inability to delete a DeploymentRuntimeConfig while it is referenced by a Provider is consistent with Kubernetes' standard resource lifecycle management, where objects often block the deletion of their dependencies through finalizers or admission control to ensure system stability [1][2]. If you are attempting to delete a DeploymentRuntimeConfig and are blocked, it is because at least one Provider or Function still references it via the spec.runtimeConfigRef field [3][1]. To successfully delete or remove the reference, follow these steps: 1. Identify referencing Providers: Use kubectl to find which Providers (or Functions) are currently using the DeploymentRuntimeConfig. kubectl get providers -A -o jsonpath='{range.items[*]}{.metadata.name}{"\t"}{.spec.runtimeConfigRef.name}{"\n"}{end}' | grep <NAME_OF_YOUR_RUNTIME_CONFIG> 2. Update or remove the reference: You must either remove the runtimeConfigRef block from the Provider's specification or point it to a different DeploymentRuntimeConfig [4][1]. kubectl edit provider <PROVIDER_NAME> 3. Delete the DeploymentRuntimeConfig: Once no active resources reference the configuration, you should be able to delete it normally [4]. kubectl delete deploymentruntimeconfig <NAME_OF_YOUR_RUNTIME_CONFIG> Note that Crossplane provides a default runtime configuration named "default" [3][1]. If your Provider is not explicitly configured, it may be using this default, which Crossplane ensures is always present in the cluster [1]. Additionally, if you are experiencing issues with Provider revisions not updating after changing a runtimeConfigRef, ensure your Crossplane version is up to date, as recent improvements have addressed how package revisions react to changes in their runtime configuration [5][6].
Citations:
- 1: https://docs.crossplane.io/latest/packages/providers/
- 2: https://github.com/crossplane/crossplane/blob/8f231230/cluster/crds/pkg.crossplane.io_providers.yaml
- 3: https://github.com/crossplane/crossplane/blob/master/design/one-pager-package-runtime-config.md
- 4: https://github.com/crossplane/docs/blob/master/content/v2.0/guides/troubleshoot-crossplane.md
- 5: Changing a provider's
runtimeConfigRefdoesn't create a newProviderRevisioncrossplane#5068 - 6: pkg: include package generation in revision ID crossplane#7473
Clear the Provider reference before deleting the runtime configuration.
Step 3 leaves spec.runtimeConfigRef.name: sv-migration in place, but Step 5 tells users to delete the DeploymentRuntimeConfig. Since a referenced runtime config can block deletion and keeps using the migration init container, remove or change the Provider reference, apply it, wait for the provider to become healthy, then delete the temporary DeploymentRuntimeConfig. Retain shared RBAC resources until all migration sub-providers using them are complete.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/applying-storage-version-migration.md` around lines 173 - 188, Update
Step 5 to instruct users to remove or change the Provider’s
spec.runtimeConfigRef.name reference, apply the change, and wait for the
provider to become healthy before deleting the temporary
DeploymentRuntimeConfig. Clarify that shared RBAC resources must remain until
every migration sub-provider using them has completed.
There was a problem hiding this comment.
Valid point from coderabbit, the runtime config reference needs to be first changed to a different DeploymentRuntimeConfig before the deletion
There was a problem hiding this comment.
@jonasz-lasut, thank you for confirming. Updating the Provider to use a different
DeploymentRuntimeConfig first prevents a dangling reference and ensures the provider restarts
without the migration init container.
You are interacting with an AI system.
jonasz-lasut
left a comment
jonasz-lasut
left a comment
There was a problem hiding this comment.
One small nit, commented under coderabbit's analysis. Other than that LGTM! Thank you @sergenyalcin
| ## Step 5 — Clean Up | ||
|
|
||
| The migration only needs to run once for a given storage version change. | ||
|
|
||
| After the provider is healthy and the migration has been verified, the | ||
| `DeploymentRuntimeConfig` and the temporary RBAC resources are no longer needed | ||
| and can be removed. | ||
|
|
||
| Crossplane restarts the provider one final time without the init container. | ||
|
|
||
| --- | ||
|
|
||
| If multiple sub-providers are being upgraded (for example `provider-gcp-storage` | ||
| and `provider-gcp-compute`), the same process applies to each provider. Each | ||
| sub-provider uses its own `DeploymentRuntimeConfig`, while the RBAC resources | ||
| can be shared. |
There was a problem hiding this comment.
Valid point from coderabbit, the runtime config reference needs to be first changed to a different DeploymentRuntimeConfig before the deletion
2 participants
Description of your changes
This PR adds guides for the storage version migration library. They describe what is the flow and usage.
I have:
make reviewableto ensure this PR is ready for review.backport release-x.ylabels to auto-backport this PR if necessary.How has this code been tested