Import Existing Resources

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 field enables importing external resources into Crossplane.

Crossplane can import resources either manually or automatically.

Import resources manually

Crossplane can discover and import existing Provider resources by matching the crossplane.io/external-name annotation in a managed resource.

To import an existing external resource in a Provider, create a new managed resource with the crossplane.io/external-name annotation. Set the annotation value to the name of the resource in the Provider.

For example, to import an existing GCP Network named my-existing-network, create a new managed resource and use the my-existing-network in the annotation.

1apiVersion: compute.gcp.crossplane.io/v1beta1
2kind: Network
3metadata:
4  annotations:
5    crossplane.io/external-name: my-existing-network

The metadata.name field can be anything you want. For example, imported-network.

1apiVersion: compute.gcp.crossplane.io/v1beta1
2kind: Network
3metadata:
4  name: imported-network
5  annotations:
6    crossplane.io/external-name: my-existing-network

Leave the spec.forProvider field empty. Crossplane imports the settings and automatically applies them to the managed resource.

1apiVersion: compute.gcp.crossplane.io/v1beta1
2kind: Network
3metadata:
4  name: imported-network
5  annotations:
6    crossplane.io/external-name: my-existing-network
7spec:
8  forProvider: {}

Crossplane now controls and manages this imported resource. Any changes to the managed resource spec changes the external resource.

Import resources automatically

Automatically import external resources with an Observe management policy.

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

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.

1apiVersion: sql.gcp.upbound.io/v1beta1
2kind: DatabaseInstance
3spec:
4  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.

1apiVersion: sql.gcp.upbound.io/v1beta1
2kind: DatabaseInstance
3metadata:
4  annotations:
5    crossplane.io/external-name: my-external-database
6spec:
7  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.

1apiVersion: sql.gcp.upbound.io/v1beta1
2kind: DatabaseInstance
3metadata:
4  name: my-imported-database
5  annotations:
6    crossplane.io/external-name: my-external-database
7spec:
8  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.

 1apiVersion: sql.gcp.upbound.io/v1beta1
 2kind: DatabaseInstance
 3metadata:
 4  name: my-imported-database
 5  annotations:
 6    crossplane.io/external-name: my-external-database
 7spec:
 8  managementPolicies: ["Observe"]
 9  forProvider:
10    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.

 1apiVersion: sql.gcp.upbound.io/v1beta1
 2kind: DatabaseInstance
 3metadata:
 4  name: my-imported-database
 5  annotations:
 6    crossplane.io/external-name: my-external-database
 7spec:
 8  managementPolicies: ["Observe"]
 9  forProvider:
10    region: us-central1
11status:
12  atProvider:
13    connectionName: crossplane-playground:us-central1:my-external-database
14    databaseVersion: POSTGRES_14
15    deletionProtection: true
16    firstIpAddress: 35.184.74.79
17    id: my-external-database
18    publicIpAddress: 35.184.74.79
19    region: us-central1
20    # Removed for brevity
21    settings:
22    - activationPolicy: ALWAYS
23      availabilityType: REGIONAL
24      diskSize: 100
25      # Removed for brevity
26      pricingPlan: PER_USE
27      tier: db-custom-4-26624
28      version: 4
29  conditions:
30  - lastTransitionTime: "2023-02-22T07:16:51Z"
31    reason: Available
32    status: "True"
33    type: Ready
34  - lastTransitionTime: "2023-02-22T07:16:51Z"
35    reason: ReconcileSuccess
36    status: "True"
37    type: Synced

Control imported ObserveOnly 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.

 1apiVersion: sql.gcp.upbound.io/v1beta1
 2kind: DatabaseInstance
 3metadata:
 4  name: my-imported-database
 5  annotations:
 6    crossplane.io/external-name: my-external-database
 7spec:
 8  managementPolicies: ["*"]
 9  forProvider:
10    databaseVersion: POSTGRES_14
11    region: us-central1
12    settings:
13    - diskSize: 100
14      tier: db-custom-4-26624
15status:
16  atProvider:
17    databaseVersion: POSTGRES_14
18    region: us-central1
19    # Removed for brevity
20    settings:
21    - diskSize: 100
22      tier: db-custom-4-26624
23      # Removed for brevity
24  conditions:
25    - lastTransitionTime: "2023-02-22T07:16:51Z"
26      reason: Available
27      status: "True"
28      type: Ready
29    - lastTransitionTime: "2023-02-22T11:16:45Z"
30      reason: ReconcileSuccess
31      status: "True"
32      type: Synced

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