crossplane
/
docs
mirror of https://github.com/crossplane/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Document Management Policies (#407)

This commit is contained in:
Hasan Turken 2023-05-02 19:01:09 +03:00 committed by GitHub
parent 857152daf6
commit 2fb64eb948
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 322 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

162
content/master/concepts/managed-resources.md
View File

@ -214,6 +214,14 @@ under `spec` should look like.
deleted when this managed resource is deleted in Kubernetes API server.
Possible values are `Delete` (the default) and `Orphan`.
* `managementPolicy`: Enum to specify the level of control Crossplane has over
the external resource.
Possible values are `FullControl` (the default) and `ObserveOnly`.
{{<hint "important">}}
`managementPolicy` is an experimental feature, see the management policies
section below for further details.
{{< /hint >}}
* `forProvider`: While the rest of the fields relate to how Crossplane should
behave, the fields under `forProvider` are solely used to configure the actual
external resource. In most of the cases, the field names correspond to the
@ -419,6 +427,26 @@ does not create the external resource until the referenced object is ready. In
this example, creation call of Azure MySQL Server will not be made until
referenced `ResourceGroup` has its `status.condition` named `Ready` to be true.
## Management Policies
Crossplane offers a set of management policies that allow you to define the
level of control it has over external resources. You can configure these
policies using the `spec.managementPolicy` field in the managed resource
definition. The available policies include:
- `FullControl (Default)`: With this policy, Crossplane fully manages and
controls the external resource.
- `ObserveOnly`: With the ObserveOnly policy, Crossplane only observes the
external resource without making any changes or deletions.
{{<hint "important" >}}
Management policies are an experimental feature, and the API is
subject to change.
{{< /hint >}}
To use management policies, you must enable them with the
`--enable-management-policies` flag when starting the provider controller.
## Importing Existing Resources
If you have some resources that are already provisioned in the cloud provider,
@ -449,6 +477,137 @@ Note that if a resource has required fields, you must fill those fields or the
creation of the managed resource will be rejected. So, in those cases, you will
need to enter the name of the resource as well as the required fields.
### Alternative Import Procedure: Start with ObserveOnly
Directly importing existing managed resources approach has the following caveats:
1. You must provide all the required fields in the spec of the resource with
correct values even though they're not used for importing the resource. A wrong
value for a required field result in a configuration update which isn't
desired.
2. Any typos in the external name annotation or mistakes in the identifying
arguments, such as the `region`, results in the creation of a new resource
instead of importing the existing one.
Instead of manually creating resources you can import the resource with an
`ObserveOnly` management policy.
Crossplane imports `ObserveOnly` resources but never changes or deletes the
resource.
{{< hint "important" >}}
Management policies including `ObserveOnly` are experimental. They must be
explicitly enabled.
See the management policies section for more details.
{{< /hint >}}
To configure an `ObserveOnly` resource:
1. Create a new resource with an {{<hover label="oo" line="8">}}ObserveOnly{{</hover>}}
management policy.
1. With the
{{<hover label="oo" line="5">}}crossplane.io/external-name{{</hover>}}
annotation set to the external name of the resource to import.
1. Only provide the identifying arguments (for example,
{{<hover label="oo" line="10">}}region{{</hover>}}) in the spec
of the resource.
```yaml {label="oo"}
apiVersion: sql.gcp.upbound.io/v1beta1
kind: DatabaseInstance
metadata:
annotations:
crossplane.io/external-name: existing-database-instance
name: existing-database-instance
spec:
managementPolicy: ObserveOnly
forProvider:
region: "us-central1"
```
Crossplane discovers the managed resource and populates the
{{<hover label="ooPopulated" line="12">}}status.atProvider{{</hover>}}
with the observed state.
```yaml {label="ooPopulated"}
apiVersion: sql.gcp.upbound.io/v1beta1
kind: DatabaseInstance
metadata:
annotations:
crossplane.io/external-name: existing-database-instance
name: existing-database-instance
spec:
managementPolicy: ObserveOnly
forProvider:
region: us-central1
status:
atProvider:
connectionName: crossplane-playground:us-central1:existing-database-instance
databaseVersion: POSTGRES_14
deletionProtection: true
firstIpAddress: 35.184.74.79
id: existing-database-instance
publicIpAddress: 35.184.74.79
region: us-central1
<truncated-for-brevity>
settings:
- activationPolicy: ALWAYS
availabilityType: REGIONAL
diskSize: 100
<truncated-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
```
To allow Crossplane to control and change the `ObserveOnly` resource, edit the
policy.
Change the {{<hover label="ooPopulated" line="8">}}ObserveOnly{{</hover>}} field
to {{<hover label="fc" line="8">}}FullControl{{</hover>}}.
Copy any required parameter values from
{{<hover label="fc" line="16">}}status.atProvider{{</hover>}} and provide them
in {{<hover label="fc" line="9">}}spec.forProvider{{</hover>}}.
```yaml {label="fc"}
apiVersion: sql.gcp.upbound.io/v1beta1
kind: DatabaseInstance
metadata:
annotations:
crossplane.io/external-name: existing-database-instance
name: existing-database-instance
spec:
managementPolicy: Full
forProvider:
databaseVersion: POSTGRES_14
region: us-central1
settings:
- diskSize: 100
tier: db-custom-4-26624
status:
atProvider:
<truncated-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
```
## Backup and Restore
Crossplane adheres to Kubernetes conventions as much as possible and one of the
@ -469,4 +628,5 @@ including Velero.
[issue-727]: https://github.com/crossplane/crossplane/issues/727
[issue-1143]: https://github.com/crossplane/crossplane/issues/1143
[managed-api-patterns]: https://github.com/crossplane/crossplane/blob/release-1.10/design/one-pager-managed-resource-api-design.md
[managed reconciler]: https://github.com/crossplane/crossplane-runtime/blob/84e629b9589852df1322ff1eae4c6e7639cf6e99/pkg/reconciler/managed/reconciler.go#L637
[managed reconciler]: https://github.com/crossplane/crossplane-runtime/blob/84e629b9589852df1322ff1eae4c6e7639cf6e99/pkg/reconciler/managed/reconciler.go#L637
[management policies]: #management-policies

162
content/v1.12/concepts/managed-resources.md
View File

@ -214,6 +214,14 @@ under `spec` should look like.
deleted when this managed resource is deleted in Kubernetes API server.
Possible values are `Delete` (the default) and `Orphan`.
* `managementPolicy`: Enum to specify the level of control Crossplane has over
the external resource.
Possible values are `FullControl` (the default) and `ObserveOnly`.
{{<hint "important">}}
`managementPolicy` is an experimental feature, see the management policies
section below for further details.
{{< /hint >}}
* `forProvider`: While the rest of the fields relate to how Crossplane should
behave, the fields under `forProvider` are solely used to configure the actual
external resource. In most of the cases, the field names correspond to the
@ -419,6 +427,26 @@ does not create the external resource until the referenced object is ready. In
this example, creation call of Azure MySQL Server will not be made until
referenced `ResourceGroup` has its `status.condition` named `Ready` to be true.
## Management Policies
Crossplane offers a set of management policies that allow you to define the
level of control it has over external resources. You can configure these
policies using the `spec.managementPolicy` field in the managed resource
definition. The available policies include:
- `FullControl (Default)`: With this policy, Crossplane fully manages and
controls the external resource.
- `ObserveOnly`: With the ObserveOnly policy, Crossplane only observes the
external resource without making any changes or deletions.
{{<hint "important" >}}
Management policies are an experimental feature, and the API is
subject to change.
{{< /hint >}}
To use management policies, you must enable them with the
`--enable-management-policies` flag when starting the provider controller.
## Importing Existing Resources
If you have some resources that are already provisioned in the cloud provider,
@ -449,6 +477,137 @@ Note that if a resource has required fields, you must fill those fields or the
creation of the managed resource will be rejected. So, in those cases, you will
need to enter the name of the resource as well as the required fields.
### Alternative Import Procedure: Start with ObserveOnly
Directly importing existing managed resources approach has the following caveats:
1. You must provide all the required fields in the spec of the resource with
correct values even though they're not used for importing the resource. A wrong
value for a required field result in a configuration update which isn't
desired.
2. Any typos in the external name annotation or mistakes in the identifying
arguments, such as the `region`, results in the creation of a new resource
instead of importing the existing one.
Instead of manually creating resources you can import the resource with an
`ObserveOnly` management policy.
Crossplane imports `ObserveOnly` resources but never changes or deletes the
resource.
{{< hint "important" >}}
Management policies including `ObserveOnly` are experimental. They must be
explicitly enabled.
See the management policies section for more details.
{{< /hint >}}
To configure an `ObserveOnly` resource:
1. Create a new resource with an {{<hover label="oo" line="8">}}ObserveOnly{{</hover>}}
management policy.
1. With the
{{<hover label="oo" line="5">}}crossplane.io/external-name{{</hover>}}
annotation set to the external name of the resource to import.
1. Only provide the identifying arguments (for example,
{{<hover label="oo" line="10">}}region{{</hover>}}) in the spec
of the resource.
```yaml {label="oo"}
apiVersion: sql.gcp.upbound.io/v1beta1
kind: DatabaseInstance
metadata:
annotations:
crossplane.io/external-name: existing-database-instance
name: existing-database-instance
spec:
managementPolicy: ObserveOnly
forProvider:
region: "us-central1"
```
Crossplane discovers the managed resource and populates the
{{<hover label="ooPopulated" line="12">}}status.atProvider{{</hover>}}
with the observed state.
```yaml {label="ooPopulated"}
apiVersion: sql.gcp.upbound.io/v1beta1
kind: DatabaseInstance
metadata:
annotations:
crossplane.io/external-name: existing-database-instance
name: existing-database-instance
spec:
managementPolicy: ObserveOnly
forProvider:
region: us-central1
status:
atProvider:
connectionName: crossplane-playground:us-central1:existing-database-instance
databaseVersion: POSTGRES_14
deletionProtection: true
firstIpAddress: 35.184.74.79
id: existing-database-instance
publicIpAddress: 35.184.74.79
region: us-central1
<truncated-for-brevity>
settings:
- activationPolicy: ALWAYS
availabilityType: REGIONAL
diskSize: 100
<truncated-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
```
To allow Crossplane to control and change the `ObserveOnly` resource, edit the
policy.
Change the {{<hover label="ooPopulated" line="8">}}ObserveOnly{{</hover>}} field
to {{<hover label="fc" line="8">}}FullControl{{</hover>}}.
Copy any required parameter values from
{{<hover label="fc" line="16">}}status.atProvider{{</hover>}} and provide them
in {{<hover label="fc" line="9">}}spec.forProvider{{</hover>}}.
```yaml {label="fc"}
apiVersion: sql.gcp.upbound.io/v1beta1
kind: DatabaseInstance
metadata:
annotations:
crossplane.io/external-name: existing-database-instance
name: existing-database-instance
spec:
managementPolicy: Full
forProvider:
databaseVersion: POSTGRES_14
region: us-central1
settings:
- diskSize: 100
tier: db-custom-4-26624
status:
atProvider:
<truncated-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
```
## Backup and Restore
Crossplane adheres to Kubernetes conventions as much as possible and one of the
@ -469,4 +628,5 @@ including Velero.
[issue-727]: https://github.com/crossplane/crossplane/issues/727
[issue-1143]: https://github.com/crossplane/crossplane/issues/1143
[managed-api-patterns]: https://github.com/crossplane/crossplane/blob/release-1.10/design/one-pager-managed-resource-api-design.md
[managed reconciler]: https://github.com/crossplane/crossplane-runtime/blob/84e629b9589852df1322ff1eae4c6e7639cf6e99/pkg/reconciler/managed/reconciler.go#L637
[managed reconciler]: https://github.com/crossplane/crossplane-runtime/blob/84e629b9589852df1322ff1eae4c6e7639cf6e99/pkg/reconciler/managed/reconciler.go#L637
[management policies]: #management-policies