Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

update management policies with GMP changes #510

Merged
merged 11 commits into from
Aug 7, 2023
Merged

update management policies with GMP changes #510

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
005db47
update management policies with GMP changes
lsviben Jul 31, 2023
a7ff8bd
address comments
lsviben Aug 1, 2023
032d138
add a few words to vale dictionary
lsviben Aug 1, 2023
4b5864e
fix vale
lsviben Aug 1, 2023
78b728d
rewording, moving stuff based on review suggestions
lsviben Aug 2, 2023
cdfe15d
fix Vale
lsviben Aug 2, 2023
73c3d1a
add css for dark mode tables
lsviben Aug 3, 2023
46ebbb1
applied suggestions from review
lsviben Aug 6, 2023
fbe86e6
Fix Vale by not breaking references in import existing resources
turkenh Aug 7, 2023
cc084ec
Remove duplicate late init sections & sync v1.13 with master
turkenh Aug 7, 2023
62f12d6
Fix all vale errors for management policies
turkenh Aug 7, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 19 additions & 21 deletions content/knowledge-base/guides/import-existing-resources.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,8 @@ you can import them as managed resources and let Crossplane manage them.
A managed resource's [`managementPolicy`]({{<ref "/v1.12/concepts/managed-resources#managementpolicy">}})
field enables importing external resources into Crossplane.

Crossplane can import resources either [manually]({{<ref
"#import-resources-manually">}}) or [automatically]({{<ref
"#import-resources-automatically">}}).
Crossplane can import resources either [manually]({{<ref "#import-resources-manually">}})
or [automatically]({{<ref "#import-resources-automatically">}}).

## Import resources manually

Expand Down Expand Up @@ -85,39 +84,38 @@ managed resource `spec` changes the external resource.

## Import resources automatically

Automatically import external resources with the
`ObserveOnly` [`managementPolicy`]({{<ref "/v1.12/concepts/managed-resources#managementpolicy">}}).
Automatically import external resources with an `Observe` [management policy]({{<ref "/v1.13/concepts/managed-resources#managementpolicies">}}).

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

{{<hint "important" >}}
The managed resource `managementPolicy` option is an alpha feature.
The managed resource `managementPolicies` option is an alpha feature.

Enable the `managementPolicy` in a provider with `--enable-management-policies`
Enable `managementPolicies` in a provider with `--enable-management-policies`
in a
[ControllerConfig]({{<ref "/v1.12/concepts/providers#controller-configuration" >}}).
{{< /hint >}}

<!-- vale off -->
### Apply the ObserveOnly managementPolicy
### Apply the Observe management policy
<!-- vale on -->

Create a new managed resource matching the
{{<hover label="oo-policy" line="1">}}apiVersion{{</hover>}} and
{{<hover label="oo-policy" line="2">}}kind{{</hover>}} of the resource
to import and add
{{<hover label="oo-policy" line="4">}}managementPolicy: ObserveOnly{{</hover>}} to the
{{<hover label="oo-policy" line="4">}}managementPolicies: ["Observe"]{{</hover>}} to the
{{<hover label="oo-policy" line="3">}}spec{{</hover>}}

For example, to import a GCP SQL DatabaseInstance, create a new resource with
lsviben marked this conversation as resolved.
Show resolved Hide resolved
lsviben marked this conversation as resolved.
Show resolved Hide resolved
the {{<hover label="oo-policy" line="4">}}managementPolicy: ObserveOnly{{</hover>}}
the {{<hover label="oo-policy" line="4">}}managementPolicies: ["Observe"]{{</hover>}}
set.
```yaml {label="oo-policy",copy-lines="none"}
apiVersion: sql.gcp.upbound.io/v1beta1
kind: DatabaseInstance
spec:
managementPolicy: ObserveOnly
managementPolicies: ["Observe"]
```

### Add the external-name annotation
Expand All @@ -138,7 +136,7 @@ metadata:
annotations:
crossplane.io/external-name: my-external-database
spec:
managementPolicy: ObserveOnly
managementPolicies: ["Observe"]
```

### Create a Kubernetes object name
Expand All @@ -156,7 +154,7 @@ metadata:
annotations:
crossplane.io/external-name: my-external-database
spec:
managementPolicy: ObserveOnly
managementPolicies: ["Observe"]
```

### Identify a specific external resource
Expand All @@ -175,7 +173,7 @@ metadata:
annotations:
crossplane.io/external-name: my-external-database
spec:
managementPolicy: ObserveOnly
managementPolicies: ["Observe"]
forProvider:
region: "us-central1"
```
Expand All @@ -198,7 +196,7 @@ metadata:
crossplane.io/external-name: existing-database-instance
name: existing-database-instance
spec:
managementPolicy: ObserveOnly
managementPolicies: ["Observe"]
forProvider:
region: us-central1
status:
Expand Down Expand Up @@ -233,12 +231,12 @@ status:
## Control imported ObserveOnly resources
<!-- vale on -->

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

Change the {{<hover label="fc" line="8">}}managementPolicy{{</hover>}} field
Change the {{<hover label="fc" line="8">}}managementPolicies{{</hover>}} field
of the managed resource to
{{<hover label="fc" line="8">}}FullControl{{</hover>}}.
{{<hover label="fc" line="8">}}["*"]{{</hover>}}.

Copy any required parameter values from
{{<hover label="fc" line="16">}}status.atProvider{{</hover>}} and provide them
Expand All @@ -256,7 +254,7 @@ metadata:
crossplane.io/external-name: existing-database-instance
name: existing-database-instance
spec:
managementPolicy: FullControl
managementPolicies: ["*"]
forProvider:
databaseVersion: POSTGRES_14
region: us-central1
Expand Down
190 changes: 163 additions & 27 deletions content/master/concepts/managed-resources.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,29 @@ Provider deletes the managed resource but doesn't delete the external resource.

#### Options
* `deletionPolicy: Delete` - **Default** - Delete the external resource when deleting the managed resource.
* `deletionPolicy: Orphan` - Leave the external resource when deleting the managed resource.
* `deletionPolicy: Orphan` - Leave the external resource when deleting the managed resource.

#### Interaction with management policies

The [management policy](#managementpolicies) takes precedence over the
`deletionPolicy` when:
<!-- vale write-good.Passive = NO -->
- The related management policy alpha feature is enabled.
<!-- vale write-good.Passive = YES -->
- The resource configures a management policy other than the default value.

See the table below for more details.

{{< table "table table-sm table-hover">}}
| managementPolicies | deletionPolicy | result |
|-----------------------------|------------------|---------|
| "*" (default) | Delete (default) | Delete |
| "*" (default) | Orphan | Orphan |
| contains "Delete" | Delete (default) | Delete |
| contains "Delete" | Orphan | Delete |
| doesn't contain "Delete" | Delete (default) | Orphan |
| doesn't contain "Delete" | Orphan | Orphan |
{{< /table >}}

<!-- vale off -->
### forProvider
Expand Down Expand Up @@ -96,10 +118,6 @@ inside a Provider's web console, Crossplane reverts that change back to what's
configured in the `forProvider` setting.
{{< /hint >}}

Providers add any settings not manually set to the `forProvider` field of the
created managed resource object.
Use `kubectl describe <managed_resource>` to view the applied values.

#### Referencing other resources

Some fields in a managed resource may depend on values from other managed
Expand Down Expand Up @@ -208,40 +226,159 @@ resource object is deleted from Kubernetes and the `deletionPolicy` is
`delete`.
<!-- vale write-good.Passive = YES -->
{{< /hint >}}


#### Late initialization

Crossplane treats the managed resource as the source of truth by default;
it expects to have all values under `spec.forProvider` including the
optional ones. If not provided, Crossplane populates the empty fields with
the values assigned by the provider. For example, consider fields such as
`region` and `availabilityZone`. You might specify only the region and let the
cloud provider choose the availability zone. In this case, if the provider
assigns an availability zone, Crossplane uses that value to populate the
`spec.forProvider.availabilityZone` field.

{{<hint "note" >}}
<!-- vale write-good.Passive = NO -->
With [managementPolicies]({{<ref "./managed-resources#managementpolicies" >}}),
this behavior can be turned off by not including the `LateInitialize` policy in
the `managementPolicies` list.
<!-- vale write-good.Passive = YES -->
{{< /hint >}}

<!-- vale off -->
### managementPolicy
<!-- vale on -->
### initProvider
<!-- vale on -->
lsviben marked this conversation as resolved.
Show resolved Hide resolved

{{<hint "important" >}}
The managed resource `managementPolicy` option is an alpha feature.
The managed resource `initProvider` option is an alpha feature related to
[managementPolicies]({{<ref "./managed-resources#managementpolicies" >}}).

Enable the `managementPolicy` in a provider with `--enable-management-policies`
in a
Enable the `initProvider` in a provider with `--enable-management-policies`
in a
[ControllerConfig]({{<ref "./providers#controller-configuration" >}}).
{{< /hint >}}

A `managementPolicy` determines if Crossplane can make changes to managed
resources. The `ObserveOnly` policy imports existing external resources not
originally created by Crossplane.
This allows new managed resources to reference
the `ObserveOnly` resource, for example, a shared database or network.
The `ObserveOnly` policy can also place existing resources under the control of
Crossplane.
The
{{<hover label="initProvider" line="7">}}initProvider{{</hover>}} defines
settings Crossplane applies only when creating a new managed resource.
Crossplane ignores settings defined in the
{{<hover label="initProvider" line="7">}}initProvider{{</hover>}}
field that change after creation.

{{<hint "note" >}}
Settings in `forProvider` are always enforced by Crossplane. Crossplane reverts
any changes to a `forProvider` field in the external resource.

Settings in `initProvider` aren't enforced by Crossplane. Crossplane ignores any
changes to a `initProvider` field in the external resource.
{{</hint >}}

Using `initProvider` is useful for setting initial values that a Provider may
automatically change, like an auto scaling group.

For example, creating a
{{<hover label="initProvider" line="2">}}NodeGroup{{</hover>}}
with an initial
{{<hover label="initProvider" line="9">}}desiredSize{{</hover>}}.
Crossplane doesn't change the
{{<hover label="initProvider" line="9">}}desiredSize{{</hover>}}
setting back when an autoscaler scales the Node Group external resource.

{{< hint "tip" >}}
Read the [Import Existing Resources]({{<ref "/knowledge-base/guides/import-existing-resources" >}})
guide for more
information on using the `managementPolicy` to import existing resources.
Crossplane recommends configuring
{{<hover label="initProvider" line="6">}}managementPolicies{{</hover>}} without
`LateInitialize` to avoid conflicts with `initProvider` settings.
{{< /hint >}}

#### Options
* `managementPolicy: FullControl` - **Default** - Crossplane can create, change
and delete the managed resource.
* `managementPolicy: ObserveOnly` - Crossplane only imports the details of the
external resource, but doesn't make any changes to the managed resource.
```yaml {label="initProvider",copy-lines="none"}
apiVersion: eks.aws.upbound.io/v1beta1
kind: NodeGroup
metadata:
name: sample-eks-ng
spec:
managementPolicies: ["Observe", "Create", "Update", "Delete"]
initProvider:
scalingConfig:
- desiredSize: 1
forProvider:
region: us-west-1
scalingConfig:
- maxSize: 4
minSize: 1
```

<!-- vale off -->
### managementPolicies
<!-- vale on -->

{{<hint "important" >}}
The managed resource `managementPolicies` option is an alpha feature.

Enable `managementPolicies` in a provider with `--enable-management-policies`
in a
[ControllerConfig]({{<ref "./providers#controller-configuration" >}}).
{{< /hint >}}

Crossplane
{{<hover label="managementPol1" line="4">}}managementPolicies{{</hover>}}
determine which actions Crossplane can take on a
managed resource and its corresponding external resource.
Apply one or more
{{<hover label="managementPol1" line="4">}}managementPolicies{{</hover>}}
to a managed resource to determine what permissions
Crossplane has over the resource.

For example, give Crossplane permission to create and delete an external resource,
but not make any changes set the policies to
{{<hover label="managementPol1" line="4">}}["Create", "Delete"]{{</hover>}}.

```yaml {label="managementPol1"}
apiVersion: ec2.aws.upbound.io/v1beta1
kind: Subnet
spec:
managementPolicies: ["Create", "Delete"]
forProvider:
# Removed for brevity
```

The default policy grants Crossplane full control over the resources.
Defining the `managementPolicies` field with an empty array [pauses](#paused)
the resource.

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

Crossplane supports the following policies:
{{<table "table table-sm table-hover">}}
| Policy | Description |
| --- | --- |
| `*` | _Default policy_. Crossplane has full control over a resource. |
| `Create` | If the external resource doesn't exist, Crossplane creates it based on the managed resource settings. |
| `Delete` | Crossplane can delete the external resource when deleting the managed resource. |
| `LateInitialize` | Crossplane initializes some external resource settings not defined in the `spec.forProvider` of the managed resource. See [the late initialization]({{<ref "./managed-resources#late-initialization" >}}) section for more details. |
| `Observe` | Crossplane only observes the resource and doesn't make any changes. Used for [observe only resources]({{<ref "/knowledge-base/guides/import-existing-resources#import-resources-automatically">}}). |
| `Update` | Crossplane changes the external resource when changing the managed resource. |
{{</table >}}

The following is a list of common policy combinations:
{{<table "table table-sm table-hover table-striped-columns" >}}
| Create | Delete | LateInitialize | Observe | Update | Description |
| :---: | :---: | :---: | :---: | :---: | --- |
| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | _Default policy_. Crossplane has full control over the resource. |
| ✔️ | ✔️ | ✔️ | ✔️ | | After creation any changes made to the managed resource aren't passed to the external resource. Useful for immutable external resources. |
| ✔️ | ✔️ | | ✔️ | ✔️ | Prevent Crossplane from managing any settings not defined in the managed resource. Useful for immutable fields in an external resource. |
| ✔️ | ✔️ | | ✔️ | | Crossplane doesn't import any settings from the external resource and doesn't push changes to the managed resource. Crossplane recreates the external resource if it's deleted. |
| ✔️ | | ✔️ | ✔️ | ✔️ | Crossplane doesn't delete the external resource when deleting the managed resource. |
| ✔️ | | ✔️ | ✔️ | | Crossplane doesn't delete the external resource when deleting the managed resource. Crossplane doesn't apply changes to the external resource after creation. |
| ✔️ | | | ✔️ | ✔️ | Crossplane doesn't delete the external resource when deleting the managed resource. Crossplane doesn't import any settings from the external resource. |
| ✔️ | | | ✔️ | | Crossplane creates the external resource but doesn't apply any changes to the external resource or managed resource. Crossplane can't delete the resource. |
| | | | ✔️ | | Crossplane only observes a resource. Used for [observe only resources]({{<ref "/knowledge-base/guides/import-existing-resources#import-resources-automatically">}}). |
| | | | | | No policy set. An alternative method for [pausing](#paused) a resource. |
{{< /table >}}

<!-- vale off -->
### providerConfigRef
Expand Down Expand Up @@ -437,7 +574,6 @@ Read the
guide for details on using StoreConfig objects.
{{< /hint >}}


## Annotations

Crossplane applies a standard set of Kubernetes `annotations` to managed
Expand Down
Loading