Provider Kubernetes

The managementPolicy field in an Object resource allows you to control the provider's interaction with the Kubernetes resource. This is useful for managing 'unmanaged external resources'—resources that are created/updated by third-party controllers (like OLM) but should be deleted by the provider when the managed Object is removed.

Note on DeletionPolicy vs managementPolicy: Crossplane's runtime DeletionPolicy (Orphan or Delete) and the provider's managementPolicy are separate. If both are defined, the Crossplane runtime policy is evaluated first:

• If DeletionOrphan is set, the resource will not be deleted by the provider regardless of the managementPolicy.
• If DeletionDelete is set, the provider's managementPolicy determines if the resource is actually deleted.

apiVersion: kubernetes.crossplane.io/v1alpha1
kind: Object
metadata:
  name: csv-kong
spec:
  managementPolicy: ObserveDelete
  forProvider:
    manifest:
      apiVersion: operators.coreos.com/v1alpha1
      kind: ClusterServiceVersion
      metadata:
        namespace: operators

By default, provider-kubernetes uses Kubernetes Server-side apply (SSA) to manage and sync resources.

Core Mechanics

• Intent Definition: The desired state of a Kubernetes object is defined in the .spec.forProvider.manifest of an Object Managed Resource (MR) (either kubernetes.crossplane.io/v1alpha1 for cluster-scoped or kubernetes.m.crossplane.io/v1alpha1 for namespace-scoped resources).
• Field Ownership: The provider uses a specific field manager named provider-kubernetes/<object-mr-name> to apply changes.
• Drift Detection: The provider only syncs and detects drift for the specific fields it manages (those explicitly defined in the .spec.forProvider.manifest) according to Kubernetes SSA mechanics.
• Conflict Resolution: Following Kubernetes recommendations, provider-kubernetes forces conflicts if they occur during field management.

WARN

Avoid having other external controllers managing the same fields as the Object MR, as this can cause race conditions over field ownership.

While discouraged, you can use multiple Object MRs to target the same Kubernetes resource, provided they manage disjoint field sets. Each MR must manage different fields to avoid racing on field ownership.

Using Partial Manifests

You can use an Object MR to partially manage an existing resource (created by another actor) by providing a partial manifest. These manifests are not valid standalone resources and cannot be used for creation.

To use partial manifests correctly, follow these requirements:

1. Lead Resource: Designate one Object MR (or an existing external resource) as the "lead" to handle the full lifecycle (creation/deletion). This lead must contain a valid, complete manifest.
2. Management Policies: For all MRs providing partial manifests, set spec.managementPolicies to ["Observe", "Update"] only.

Limitations of Partial Manifests

• Creation: Partial manifests will remain in a Synced: False state until the target Kubernetes resource already exists.
• Deletion: Deleting an Object MR with a partial manifest will not delete the target Kubernetes resource.
• Cleanup: Currently, partial MRs will not remove the specific fields they manage when the MR is deleted.

Generic References allow an Object to resolve values from other managed resources at runtime. This is essential when a resource's name or attribute (like a generated ID) is not known until the dependency is created.

You define these in the spec.references field using a syntax similar to Crossplane patches. The provider resolves these references in order; if any reference fails to resolve, reconciliation fails.

apiVersion: kubernetes.crossplane.io/v1alpha1
kind: Object
metadata:
  name: csv-kong
spec:
  references:
  - fromObject:
      apiVersion: kubernetes.crossplane.io/v1alpha1
      kind: Object
      name: sub-kong
      fieldPath: status.atProvider.manifest.status.currentCSV
    toFieldPath: spec.forProvider.manifest.metadata.name
  managementPolicy: ObserveDelete
  forProvider:
    manifest:
      apiVersion: operators.coreos.com/v1alpha1
      kind: ClusterServiceVersion
      metadata:
        namespace: operators

The provider-kubernetes provider allows you to manage any Kubernetes resource by wrapping its manifest inside a Crossplane Object resource.

Key Concepts

• Managed Resource: The Crossplane Object resource itself, which lives in the cluster where the provider is running.
• External Resource: The actual target Kubernetes resource (e.g., a Namespace, Deployment, etc.) that the provider manages on a target cluster.
• Manifest Wrapping: You define the target resource's apiVersion, kind, and metadata within spec.forProvider.manifest.
• Status Monitoring: Once reconciled, the provider watches the external resource and copies its runtime manifest and status back to the Object resource at status.atProvider.manifest.

Naming Convention

In the spec.forProvider.manifest.metadata.name field, the name is optional. If omitted, the provider defaults to using the metadata.name of the Crossplane Object resource.

apiVersion: kubernetes.crossplane.io/v1alpha1
kind: Object
metadata:
  name: sample-namespace
spec:
  forProvider:
    manifest:
      apiVersion: v1
      kind: Namespace
      metadata:
        # name in manifest is optional and defaults to Object name
        # name: some-other-name
        labels:
          example: "true"
  providerConfigRef:
    name: kubernetes-provider