We are excited to share support for Crossplane v2 in the Crossplane Provider for OCI. The Crossplane Provider for OCI lets teams manage Oracle Cloud Infrastructure (OCI) resources as Kubernetes resources. This means teams can use the same Kubernetes-based control plane for both apps and infrastructure.
The latest release of the Crossplane Provider for OCI is an important milestone for teams building Kubernetes-native control planes on OCI. It brings the provider in line with Crossplane v2, adding the namespaced resource model needed for multi-team platforms, and gives operators more control over how resources are observed and reconciled. With this release, teams can:
- Use namespaced managed resources
- Control how reconciliation runs
- Observe existing OCI resources without managing them
- Plan safer upgrades from older versions
Why Crossplane?
Modern applications often span both Kubernetes resources and cloud infrastructure services. When application developers switch between Kubernetes manifests and infrastructure-as-code tools, workflows can become fragmented, requiring teams to spend valuable time managing gaps between the infrastructure and application layers. Crossplane is an open-source framework that extends Kubernetes to allow teams to manage cloud infrastructure through Kubernetes APIs. The Crossplane Provider for OCI simplifies building secure and scalable workflows for managing Kubernetes applications on OCI by enabling Crossplane to manage OCI resources.
Why does this release matter?
Crossplane v2 expands the control plane model for platform teams by making namespaced resources a first-class pattern. A namespaced resource exists within a specific namespace and is typically used by application teams for isolated, self-service management, while cluster-scoped resources exist at the cluster level and are generally used by platform teams to manage shared infrastructure and underlying cloud resources.
For OCI users, the latest release helps align the provider with this model. Instead of choosing between a fully centralized provider configuration and isolated application workflows, platform teams can combine shared cluster-level configuration with namespace-level resource definitions and credentials. The result is a more Kubernetes-native way to offer OCI resources to application teams.
What is new?
- Crossplane v2 support: The provider has moved to Crossplane v2, enabling the latest Crossplane platform patterns.
- Dual-scope managed resources: OCI managed resources can be used in both legacy cluster-scoped and new namespaced forms, making it easier to adopt v2 without forcing every workflow to change at once.
- Namespaced resource isolation: Teams can create managed resources in their own Kubernetes namespaces and, where appropriate, use namespace-scoped ProviderConfig objects for separate credentials and access boundaries.
- Management policies: Resources can be observed without being changed or deleted by Crossplane, which is useful for bringing existing OCI resources into Kubernetes-level visibility.
- Configurable reconciliation behavior: Provider polling and reconciliation rate controls can now be tuned for different scale and operational requirements.
- Updated examples and quickstarts: The project includes dual-scope examples and migration guidance to help teams evaluate the new model.
How do I get started?
The provider family architecture lets you install the OCI service providers you need. The example below installs the family provider and the Object Storage provider at v1.0.1. Install the family provider first so Crossplane resolves provider dependencies predictably.
apiVersion:pkg.crossplane.io/v1
kind:Provider
metadata:
name: oracle-provider-family-oci
spec:
package: ghcr.io/oracle/provider-family-oci:v1.0.1
---
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
name: provider-oci-objectstorage
spec:
package: ghcr.io/oracle/provider-oci-objectstorage:v1.0.1 After applying the manifest, verify that the providers are installed and healthy:
kubectl get providers Example 1: Use namespaced resources for team isolation
Namespaced managed resources are one of the most important changes enabled by Crossplane v2. In this example, an application team creates an Object Storage bucket in its own Kubernetes namespace. The API group includes .m., which indicates the modern namespaced managed resource API.
apiVersion: objectstorage.oci.m.upbound.io/v1alpha1
kind: Bucket
metadata:
name: app-team-a-bucket
namespace: app-team-a
spec:
forProvider:
compartmentId: <compartment-ocid>
name: app-team-a-crossplane
namespace: <oci-object-storage-namespace>
providerConfigRef:
kind: ProviderConfig
name: app-team-a This pattern is useful when different teams need to manage similarly named resources independently, or when each namespace should use a different OCI credential boundary. If providerConfigRef is omitted, namespaced managed resources use the default ClusterProviderConfig, which is useful for shared platform-controlled access.
Example 2: Observe existing OCI resources without taking ownership
Many teams already have OCI resources created through Terraform, the OCI Console, or other automation. With management policies, Crossplane can observe those resources without mutating or deleting them. The following example shows the pattern for observing an existing OCI KMS Vault.
apiVersion: kms.oci.m.upbound.io/v1alpha1
kind: Vault
metadata:
name: shared-vault
namespace: app-team-a
annotations:
crossplane.io/external-name: <existing-vault-external-name>
spec:
managementPolicies:
- Observe
forProvider:
compartmentId: <compartment-ocid>
displayName: shared-vault
providerConfigRef:
kind: ProviderConfig
name: app-team-a With managementPolicies set to Observe, Crossplane reads the state of the external resource and reports status through Kubernetes, but does not correct drift, update settings, or delete the resource. This gives platform teams a safer way to expose existing OCI infrastructure to application teams through a familiar Kubernetes API.
Example 3: Tune reconciliation behavior
Large environments may need to balance reconciliation speed with API usage and controller resource consumption. The release adds support for configuring the provider poll interval and reconciliation rate. The following example attaches a DeploymentRuntimeConfig to the Object Storage provider.
apiVersion: pkg.crossplane.io/v1beta1
kind: DeploymentRuntimeConfig
metadata:
name: oci-provider-runtime
spec:
deploymentTemplate:
spec:
selector: {}
template:
spec:
containers:
- name: package-runtime
args:
- --poll=10m
- --max-reconcile-rate=4
---
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
name: provider-oci-objectstorage
spec:
package: ghcr.io/oracle/provider-oci-objectstorage:v1.0.1
runtimeConfigRef:
name: oci-provider-runtime Use shorter poll intervals when you want Crossplane to detect external drift faster. Use longer intervals or lower reconcile rates when you want to reduce steady-state controller activity. As with any controller tuning, test these settings in a non-production environment before applying them broadly.
Upgrade considerations
Because this release includes the move to Crossplane v2, teams should plan upgrades carefully. The release includes breaking changes and migration notes that are worth reviewing before production rollout.
- Test upgrades in a non-production environment first.
- Crossplane v1 claims are no longer supported in the new v2 pattern. Use namespaced composite resources for new v2 workflows.
- Use the namespaced API group, such as objectstorage.oci.m.upbound.io, for new namespaced resources. Existing cluster-scoped resources can continue to use the legacy API group while you plan migration.
- Review provider names, ProviderConfig objects, secrets, and managed resources before making changes to avoid orphaning resources.
Get started
As a next step, try the updated quickstart in a test cluster, create a namespaced Object Storage bucket, and evaluate where observe-only management policies can help you bring existing OCI resources into your platform workflow. Share feedback through the GitHub project and subscribe to releases to stay current with the provider roadmap.
Resources