docs/content/master/guides/import-existing-resources.md

title	weight	description
Import Existing Resources	200	Import existing resources into your control plane for Crossplane to manage

If you have resources that are already provisioned in a Provider, you can import them as managed resources and let Crossplane manage them. A managed resource's [managementPolicies]({{<ref "../managed-resources/managed-resources#managementpolicies">}}) field enables importing external resources into Crossplane.

Import resources in observe only mode

Start by importing external resources with an Observe [management policy]({{<ref "../managed-resources/managed-resources#managementpolicies">}}).

Crossplane imports observe only resources but never changes or deletes the resources.

{{<hint "important" >}} The managed resource managementPolicies option is a beta feature.

The Provider determines support for management policies. Refer to the Provider's documentation to see if the Provider supports management policies. {{< /hint >}}

Apply the Observe management policy

Create a new managed resource matching the {{}}apiVersion{{}} and {{}}kind{{}} of the resource to import and add {{}}managementPolicies: ["Observe"]{{}} to the {{}}spec{{}}

For example, to import a GCP SQL DatabaseInstance, create a new resource with the {{}}managementPolicies: ["Observe"]{{}} set.

apiVersion: sql.gcp.upbound.io/v1beta1
kind: DatabaseInstance
spec:
  managementPolicies: ["Observe"]

Add the external-name annotation

Add the {{}}crossplane.io/external-name{{}} annotation for the resource. This name must match the name inside the Provider.

For example, for a GCP database named {{}}my-external-database{{}}, apply the {{}}crossplane.io/external-name{{}} annotation with the value {{}}my-external-database{{}}.

apiVersion: sql.gcp.upbound.io/v1beta1
kind: DatabaseInstance
metadata:
  annotations:
    crossplane.io/external-name: my-external-database
spec:
  managementPolicies: ["Observe"]

Create a Kubernetes object name

Create a {{}}name{{}} to use for the Kubernetes object.

For example, name the Kubernetes object {{}}my-imported-database{{}}.

apiVersion: sql.gcp.upbound.io/v1beta1
kind: DatabaseInstance
metadata:
  name: my-imported-database
  annotations:
    crossplane.io/external-name: my-external-database
spec:
  managementPolicies: ["Observe"]

Identify a specific external resource

If more than one resource inside the Provider shares the same name, identify the specific resource with a unique {{}}spec.forProvider{{}} field.

For example, only import the GCP SQL database in the {{}}us-central1{{}} region.

apiVersion: sql.gcp.upbound.io/v1beta1
kind: DatabaseInstance
metadata:
  name: my-imported-database
  annotations:
    crossplane.io/external-name: my-external-database
spec:
  managementPolicies: ["Observe"]
  forProvider:
    region: "us-central1"

Apply the managed resource

Apply the new managed resource. Crossplane syncs the status of the external resource in the cloud with the newly created managed resource.

View the discovered resource

Crossplane discovers the managed resource and populates the {{}}status.atProvider{{}} fields with the values from the external resource.

apiVersion: sql.gcp.upbound.io/v1beta1
kind: DatabaseInstance
metadata:
  name: my-imported-database
  annotations:
    crossplane.io/external-name: my-external-database
spec:
  managementPolicies: ["Observe"]
  forProvider:
    region: us-central1
status:
  atProvider:
    connectionName: crossplane-playground:us-central1:my-external-database
    databaseVersion: POSTGRES_14
    deletionProtection: true
    firstIpAddress: 35.184.74.79
    id: my-external-database
    publicIpAddress: 35.184.74.79
    region: us-central1
    # Removed for brevity
    settings:
    - activationPolicy: ALWAYS
      availabilityType: REGIONAL
      diskSize: 100
      # Removed for brevity
      pricingPlan: PER_USE
      tier: db-custom-4-26624
      version: 4
  conditions:
  - lastTransitionTime: "2023-02-22T07:16:51Z"
    reason: Available
    status: "True"
    type: Ready
  - lastTransitionTime: "2023-02-22T07:16:51Z"
    reason: ReconcileSuccess
    status: "True"
    type: Synced

Control imported observe only resources

Crossplane can take active control of observe only imported resources by changing the managementPolicies after import.

Change the {{}}managementPolicies{{}} field of the managed resource to {{}}["*"]{{}}.

Copy any required parameter values from {{}}status.atProvider{{}} and provide them in {{}}spec.forProvider{{}}.

{{< hint "tip" >}} Manually copy the important spec.atProvider values to spec.forProvider. {{< /hint >}}

apiVersion: sql.gcp.upbound.io/v1beta1
kind: DatabaseInstance
metadata:
  name: my-imported-database
  annotations:
    crossplane.io/external-name: my-external-database
spec:
  managementPolicies: ["*"]
  forProvider:
    databaseVersion: POSTGRES_14
    region: us-central1
    settings:
    - diskSize: 100
      tier: db-custom-4-26624
status:
  atProvider:
    databaseVersion: POSTGRES_14
    region: us-central1
    # Removed for brevity
    settings:
    - diskSize: 100
      tier: db-custom-4-26624
      # Removed for brevity
  conditions:
    - lastTransitionTime: "2023-02-22T07:16:51Z"
      reason: Available
      status: "True"
      type: Ready
    - lastTransitionTime: "2023-02-22T11:16:45Z"
      reason: ReconcileSuccess
      status: "True"
      type: Synced

Crossplane now fully manages the imported resource. Crossplane applies any changes to the managed resource in the Provider's external resource.