From 005db477b6efcf5693ff828f59a3e32cc2eeaa4a Mon Sep 17 00:00:00 2001 From: lsviben Date: Mon, 31 Jul 2023 14:32:11 +0200 Subject: [PATCH 01/11] update management policies with GMP changes Signed-off-by: lsviben --- .../guides/import-existing-resources.md | 30 ++--- content/master/concepts/managed-resources.md | 102 ++++++++++++++--- content/v1.13/concepts/managed-resources.md | 103 +++++++++++++++--- 3 files changed, 192 insertions(+), 43 deletions(-) diff --git a/content/knowledge-base/guides/import-existing-resources.md b/content/knowledge-base/guides/import-existing-resources.md index 085c94bc5..d4aec9b06 100644 --- a/content/knowledge-base/guides/import-existing-resources.md +++ b/content/knowledge-base/guides/import-existing-resources.md @@ -85,29 +85,29 @@ managed resource `spec` changes the external resource. ## Import resources automatically -Automatically import external resources with the -`ObserveOnly` [`managementPolicy`]({{}}). +Automatically import external resources with the granular management polices +[`spec.managementPolicies: ["Observe"]`]({{}}). -Crossplane imports `ObserveOnly` resources but never changes or deletes the +Crossplane imports `Observe` only resources but never changes or deletes the resources. {{}} -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 the `managementPolicies` in a provider with `--enable-management-policies` in a [ControllerConfig]({{}}). {{< /hint >}} -### Apply the ObserveOnly managementPolicy +### Apply the ["Observe"] managementPolicies Create a new managed resource matching the {{}}apiVersion{{}} and {{}}kind{{}} of the resource to import and add -{{}}managementPolicy: ObserveOnly{{}} to the +{{}}managementPolicies: ["Observe"]{{}} to the {{}}spec{{}} For example, to import a GCP SQL DatabaseInstance, create a new resource with @@ -117,7 +117,7 @@ set. apiVersion: sql.gcp.upbound.io/v1beta1 kind: DatabaseInstance spec: - managementPolicy: ObserveOnly + managementPolicies: ["Observe"] ``` ### Add the external-name annotation @@ -138,7 +138,7 @@ metadata: annotations: crossplane.io/external-name: my-external-database spec: - managementPolicy: ObserveOnly + managementPolicies: ["Observe"] ``` ### Create a Kubernetes object name @@ -156,7 +156,7 @@ metadata: annotations: crossplane.io/external-name: my-external-database spec: - managementPolicy: ObserveOnly + managementPolicies: ["Observe"] ``` ### Identify a specific external resource @@ -175,7 +175,7 @@ metadata: annotations: crossplane.io/external-name: my-external-database spec: - managementPolicy: ObserveOnly + managementPolicies: ["Observe"] forProvider: region: "us-central1" ``` @@ -198,7 +198,7 @@ metadata: crossplane.io/external-name: existing-database-instance name: existing-database-instance spec: - managementPolicy: ObserveOnly + managementPolicies: ["Observe"] forProvider: region: us-central1 status: @@ -234,11 +234,11 @@ status: Crossplane can take active control of `ObserveOnly` imported resources by -changing the `managementPolicy` after import. +changing the `managementPolicies` after import. Change the {{}}managementPolicy{{}} field of the managed resource to -{{}}FullControl{{}}. +{{}}["*"]{{}}. Copy any required parameter values from {{}}status.atProvider{{}} and provide them @@ -256,7 +256,7 @@ metadata: crossplane.io/external-name: existing-database-instance name: existing-database-instance spec: - managementPolicy: FullControl + managementPolicies: ["*"] forProvider: databaseVersion: POSTGRES_14 region: us-central1 diff --git a/content/master/concepts/managed-resources.md b/content/master/concepts/managed-resources.md index ecc4fddbf..9ad3a3a75 100644 --- a/content/master/concepts/managed-resources.md +++ b/content/master/concepts/managed-resources.md @@ -211,37 +211,111 @@ resource object is deleted from Kubernetes and the `deletionPolicy` is -### managementPolicy +### managementPolicies {{}} -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 the `managementPolicies` in a provider with `--enable-management-policies` in a [ControllerConfig]({{}}). {{< /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 +Granular `managementPolicies` determine what actions Crossplane can take on a +managed and its external resource. `managementPolicies` is an array of actions +(`Observe`, `Create`, `Update`, `Delete`, `LateInitialize`, `*`), and there are +multiple combinations that Crossplane supports based on the use case. For +example, setting `["Observe"]` makes Crossplane treat the resource as an +`ObserveOnly` resource, importing the 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 `["Observe"]` policy can also place existing resources under the control of Crossplane. {{< hint "tip" >}} Read the [Import Existing Resources]({{}}) guide for more -information on using the `managementPolicy` to import existing resources. +information on using the `managementPolicies` to import existing resources. {{< /hint >}} +Furthermore, granular `managementPolicies` can be used to skip the late +initialization of the managed resource, by not including `LateInitialize` in the +`managementPolicies`, which is useful when there are conflicting fields between +the managed resource and the external resource, due to some external resource +field being controlled externally. + +{{< hint "tip" >}} +Read the [initProvider]({{}}) section +for more info about how we can use `LateInitialize` and `initProvider` together +to ignore changes to fields that are controlled externally. +{{< /hint >}} + +The `"Delete"` action replaces the [deletionPolicy]({{}}) +field in the managed resource. For now the `deletionPolicy` is still supported, +but only if it's set to a non default value, which is `Orphan`. If it's set to +`Orphan`, and the `managementPolicies` is set to `["*"]`, which is default, +then the external resource will be orphaned when the managed resource is +deleted. In other cases, non default `managementPolicies` take precedence over +the `deletionPolicy` field. + #### 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. +* `*` - ** Default ** - Crossplane can observe, create, change, delete the + external resource and update the managed resource object with late init + parameters. +* `Observe` - managed resource `status.atProvider` will be updated with the + external resource state. +* `Create` - external resource will be created using the managed resource + `spec.initProvider` and `spec.forProvider`. +* `Update` - external resource will be updated using the managed resource + `spec.forProvider`. +* `Delete` - the external resource will be deleted when the managed resource is + deleted. +* `LateInitialize` - select fields of the managed resource + `spec.forProvider` will be updated with the external resource state. + + +### initProvider + + +{{}} +The managed resource `initProvider` option is an alpha feature related to +[managementPolicies]({{}}). + +Enable the `initProvider` in a provider with `--enable-management-policies` +in a +[ControllerConfig]({{}}). +{{< /hint >}} + +The `spec.initProvider` is a subset of the `spec.forProvider` fields that +Crossplane merges with `forProvider` to create the external resource, but +ignores when updating it. This allows users to create a resource with all the +required fields which may then be controlled externally. For example, a user may +want to create a `NodeGroup` with the required `desiredSize` field, but then +let an autoscaler control the field. If the `desiredSize` field is included +in the`forProvider` field, Crossplane will attempt to update the field, which +will conflict with the autoscaler. + +```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 +``` +It's suggested to use a combination of `managementPolicies` without +`LateInitialize` with `initProvider` to avoid late initialization of fields +in `forProvider`. ### providerConfigRef diff --git a/content/v1.13/concepts/managed-resources.md b/content/v1.13/concepts/managed-resources.md index ecc4fddbf..6deb1bfaf 100644 --- a/content/v1.13/concepts/managed-resources.md +++ b/content/v1.13/concepts/managed-resources.md @@ -211,37 +211,112 @@ resource object is deleted from Kubernetes and the `deletionPolicy` is -### managementPolicy +### managementPolicies {{}} -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 the `managementPolicies` in a provider with `--enable-management-policies` in a [ControllerConfig]({{}}). {{< /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 +Granular `managementPolicies` determine what actions Crossplane can take on a +managed and its external resource. `managementPolicies` is an array of actions +(`Observe`, `Create`, `Update`, `Delete`, `LateInitialize`, `*`), and there are +multiple combinations that Crossplane supports based on the use case. For +example, setting `["Observe"]` makes Crossplane treat the resource as an +`ObserveOnly` resource, importing the 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 `["Observe"]` policy can also place existing resources under the control of Crossplane. {{< hint "tip" >}} Read the [Import Existing Resources]({{}}) guide for more -information on using the `managementPolicy` to import existing resources. +information on using the `managementPolicies` to import existing resources. {{< /hint >}} +Furthermore, granular `managementPolicies` can be used to skip the late +initialization of the managed resource, by not including `LateInitialize` in the +`managementPolicies`, which is useful when there are conflicting fields between +the managed resource and the external resource, due to some external resource +field being controlled externally. + +{{< hint "tip" >}} +Read the [initProvider]({{}}) section +for more info about how we can use `LateInitialize` and `initProvider` together +to ignore changes to fields that are controlled externally. +{{< /hint >}} + +The `"Delete"` action replaces the [deletionPolicy]({{}}) +field in the managed resource. For now the `deletionPolicy` is still supported, +but only if it's set to a non default value, which is `Orphan`. If it's set to +`Orphan`, and the `managementPolicies` is set to `["*"]`, which is default, +then the external resource will be orphaned when the managed resource is +deleted. In other cases, non default `managementPolicies` take precedence over +the `deletionPolicy` field. + #### 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. +* `*` - ** Default ** - Crossplane can observe, create, change, delete the + external resource and update the managed resource object with late init + parameters. +* `Observe` - managed resource `status.atProvider` will be updated with the + external resource state. +* `Create` - external resource will be created using the managed resource + `spec.initProvider` and `spec.forProvider`. +* `Update` - external resource will be updated using the managed resource + `spec.forProvider`. +* `Delete` - the external resource will be deleted when the managed resource is + deleted. +* `LateInitialize` - select fields of the managed resource + `spec.forProvider` will be updated with the external resource state. + + + +### initProvider + + +{{}} +The managed resource `initProvider` option is an alpha feature related to +[managementPolicies]({{}}). + +Enable the `initProvider` in a provider with `--enable-management-policies` +in a +[ControllerConfig]({{}}). +{{< /hint >}} + +The `spec.initProvider` is a subset of the `spec.forProvider` fields that +Crossplane merges with `forProvider` to create the external resource, but +ignores when updating it. This allows users to create a resource with all the +required fields which may then be controlled externally. For example, a user may +want to create a `NodeGroup` with the required `desiredSize` field, but then +let an autoscaler control the field. If the `desiredSize` field is included +in the`forProvider` field, Crossplane will attempt to update the field, which +will conflict with the autoscaler. + +```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 +``` +It's suggested to use a combination of `managementPolicies` without +`LateInitialize` with `initProvider` to avoid late initialization of fields +in `forProvider`. ### providerConfigRef From a7ff8bd284344102e692afe7150943c4a7308e43 Mon Sep 17 00:00:00 2001 From: lsviben Date: Tue, 1 Aug 2023 14:54:52 +0200 Subject: [PATCH 02/11] address comments Signed-off-by: lsviben --- content/master/concepts/managed-resources.md | 91 +++++++++++++------- content/v1.13/concepts/managed-resources.md | 74 +++++++++++----- 2 files changed, 111 insertions(+), 54 deletions(-) diff --git a/content/master/concepts/managed-resources.md b/content/master/concepts/managed-resources.md index 9ad3a3a75..6d8000a98 100644 --- a/content/master/concepts/managed-resources.md +++ b/content/master/concepts/managed-resources.md @@ -208,7 +208,19 @@ resource object is deleted from Kubernetes and the `deletionPolicy` is `delete`. {{< /hint >}} - + +#### Late Initialization + +For some of the optional fields, users rely on the default that the cloud +provider chooses for them. Since Crossplane treats the managed resource as the +source of the truth, values of those fields need to exist in `spec` of the +managed resource. So, in each reconciliation, Crossplane will fill the value of +a field that is left empty by the user but is assigned a value by the provider. +For example, there could be two fields like `region` and `availabilityZone` and +you might want to give only `region` and leave the availability zone to be +chosen by the cloud provider. In that case, if the provider assigns an +availability zone, Crossplane gets that value and fills `availabilityZone`. Note +that if the field is already filled, the controller won't override its value. ### managementPolicies @@ -222,33 +234,35 @@ in a [ControllerConfig]({{}}). {{< /hint >}} -Granular `managementPolicies` determine what actions Crossplane can take on a +Granular `managementPolicies` determine what actions Crossplane can take on a managed and its external resource. `managementPolicies` is an array of actions (`Observe`, `Create`, `Update`, `Delete`, `LateInitialize`, `*`), and there are -multiple combinations that Crossplane supports based on the use case. For -example, setting `["Observe"]` makes Crossplane treat the resource as an -`ObserveOnly` resource, importing the 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 `["Observe"]` policy can also place existing resources under the control of -Crossplane. +multiple combinations that Crossplane supports based on the use case. + +For example, setting just `["Observe"]` makes Crossplane treat the resource as +a read-only resource, importing the external resources not originally created +by Crossplane. This allows other managed resources to reference the read-only +resource, for example, a shared database or network. Importing a resource as +read-only is convenient since Crossplane will not attempt to take control and +only identifier parameters are needed to be specified in the managed resource. {{< hint "tip" >}} -Read the [Import Existing Resources]({{}}) +Read the [Import Existing Resources]({{}}) guide for more information on using the `managementPolicies` to import existing resources. {{< /hint >}} -Furthermore, granular `managementPolicies` can be used to skip the late -initialization of the managed resource, by not including `LateInitialize` in the -`managementPolicies`, which is useful when there are conflicting fields between -the managed resource and the external resource, due to some external resource -field being controlled externally. +Another application of `managementPolicies` is to skip the [Late Initialization]({{}}) +of the managed resource, by not including `LateInitialize` in the +`managementPolicies`, which is useful when there are fields in the resource, +that we would not like Crossplane to control, but would usually be filled in +by Late Initialization. {{< hint "tip" >}} Read the [initProvider]({{}}) section -for more info about how we can use `LateInitialize` and `initProvider` together -to ignore changes to fields that are controlled externally. +for more info about how we can use management policies without `LateInitialize` +and `initProvider` together to ignore changes to fields that are controlled +externally. {{< /hint >}} The `"Delete"` action replaces the [deletionPolicy]({{}}) @@ -257,22 +271,36 @@ but only if it's set to a non default value, which is `Orphan`. If it's set to `Orphan`, and the `managementPolicies` is set to `["*"]`, which is default, then the external resource will be orphaned when the managed resource is deleted. In other cases, non default `managementPolicies` take precedence over -the `deletionPolicy` field. +the `deletionPolicy` field. Keep in mind that this behavior is only applicable +if the management policy alpha feature is enabled. To sum it up in a table: + +{{< table >}} +| managementPolicies | deletionPolicy | result | +|-----------------------------|------------------|---------| +| "*" (default) | Delete (default) | Delete | +| "*" (default) | Orphan | Orphan | +| contains "Delete" | Delete (default) | Delete | +| contains "Delete" | Orphan | Delete | +| does not contain "Delete" | Delete (default) | Orphan | +| does not contain "Delete" | Orphan | Orphan | +{{< /table >}} #### Options -* `*` - ** Default ** - Crossplane can observe, create, change, delete the - external resource and update the managed resource object with late init - parameters. -* `Observe` - managed resource `status.atProvider` will be updated with the - external resource state. +* `*` - ** Default ** - Crossplane can observe, create, change, delete the + external resource and update the managed resource spec with late init + parameters. +* `Observe` - managed resource `status.atProvider` will be updated with the + external resource state. * `Create` - external resource will be created using the managed resource - `spec.initProvider` and `spec.forProvider`. + `spec.initProvider` and `spec.forProvider`. * `Update` - external resource will be updated using the managed resource - `spec.forProvider`. + `spec.forProvider`. * `Delete` - the external resource will be deleted when the managed resource is - deleted. -* `LateInitialize` - select fields of the managed resource - `spec.forProvider` will be updated with the external resource state. + deleted. +* `LateInitialize` - Unprovided spec fields are late-initialized to + `spec.forProvider` with the default values from the cloud provider. This + enables Crossplane to take full control of the external resource, even those + values not provided by the user upfront. Read more about [Late Initialization]({{}}) ### initProvider @@ -313,9 +341,9 @@ spec: minSize: 1 ``` -It's suggested to use a combination of `managementPolicies` without -`LateInitialize` with `initProvider` to avoid late initialization of fields -in `forProvider`. +It's suggested to use a combination of `managementPolicies` without the +`LateInitialize` action when using `initProvider` to avoid late initialization +of fields in `forProvider`. Read more about [Late Initialization]({{}}) ### providerConfigRef @@ -511,7 +539,6 @@ Read the guide for details on using StoreConfig objects. {{< /hint >}} - ## Annotations Crossplane applies a standard set of Kubernetes `annotations` to managed diff --git a/content/v1.13/concepts/managed-resources.md b/content/v1.13/concepts/managed-resources.md index 6deb1bfaf..a85c41973 100644 --- a/content/v1.13/concepts/managed-resources.md +++ b/content/v1.13/concepts/managed-resources.md @@ -208,7 +208,21 @@ resource object is deleted from Kubernetes and the `deletionPolicy` is `delete`. {{< /hint >}} - + + +#### Late Initialization + + +For some of the optional fields, users rely on the default that the cloud +provider chooses for them. Since Crossplane treats the managed resource as the +source of the truth, values of those fields need to exist in `spec` of the +managed resource. So, in each reconciliation, Crossplane will fill the value of +a field that is left empty by the user but is assigned a value by the provider. +For example, there could be two fields like `region` and `availabilityZone` and +you might want to give only `region` and leave the availability zone to be +chosen by the cloud provider. In that case, if the provider assigns an +availability zone, Crossplane gets that value and fills `availabilityZone`. Note +that if the field is already filled, the controller won't override its value. ### managementPolicies @@ -225,13 +239,14 @@ in a Granular `managementPolicies` determine what actions Crossplane can take on a managed and its external resource. `managementPolicies` is an array of actions (`Observe`, `Create`, `Update`, `Delete`, `LateInitialize`, `*`), and there are -multiple combinations that Crossplane supports based on the use case. For -example, setting `["Observe"]` makes Crossplane treat the resource as an -`ObserveOnly` resource, importing the 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 `["Observe"]` policy can also place existing resources under the control of -Crossplane. +multiple combinations that Crossplane supports based on the use case. + +For example, setting just `["Observe"]` makes Crossplane treat the resource as +a read-only resource, importing the external resources not originally created +by Crossplane. This allows other managed resources to reference the read-only +resource, for example, a shared database or network. Importing a resource as +read-only is convenient since Crossplane will not attempt to take control and +only identifier parameters are needed to be specified in the managed resource. {{< hint "tip" >}} Read the [Import Existing Resources]({{}}) @@ -239,16 +254,17 @@ guide for more information on using the `managementPolicies` to import existing resources. {{< /hint >}} -Furthermore, granular `managementPolicies` can be used to skip the late -initialization of the managed resource, by not including `LateInitialize` in the -`managementPolicies`, which is useful when there are conflicting fields between -the managed resource and the external resource, due to some external resource -field being controlled externally. +Another application of `managementPolicies` is to skip the [Late Initialization]({{}}) +of the managed resource, by not including `LateInitialize` in the +`managementPolicies`, which is useful when there are fields in the resource, +that we would not like Crossplane to control, but would usually be filled in +by Late Initialization. {{< hint "tip" >}} Read the [initProvider]({{}}) section -for more info about how we can use `LateInitialize` and `initProvider` together -to ignore changes to fields that are controlled externally. +for more info about how we can use management policies without `LateInitialize` +and `initProvider` together to ignore changes to fields that are controlled +externally. {{< /hint >}} The `"Delete"` action replaces the [deletionPolicy]({{}}) @@ -257,11 +273,23 @@ but only if it's set to a non default value, which is `Orphan`. If it's set to `Orphan`, and the `managementPolicies` is set to `["*"]`, which is default, then the external resource will be orphaned when the managed resource is deleted. In other cases, non default `managementPolicies` take precedence over -the `deletionPolicy` field. +the `deletionPolicy` field. Keep in mind that this behavior is only applicable +if the management policy alpha feature is enabled. To sum it up in a table: + +{{< table >}} +| managementPolicies | deletionPolicy | result | +|-----------------------------|------------------|---------| +| "*" (default) | Delete (default) | Delete | +| "*" (default) | Orphan | Orphan | +| contains "Delete" | Delete (default) | Delete | +| contains "Delete" | Orphan | Delete | +| does not contain "Delete" | Delete (default) | Orphan | +| does not contain "Delete" | Orphan | Orphan | +{{< /table >}} #### Options * `*` - ** Default ** - Crossplane can observe, create, change, delete the - external resource and update the managed resource object with late init + external resource and update the managed resource spec with late init parameters. * `Observe` - managed resource `status.atProvider` will be updated with the external resource state. @@ -271,8 +299,10 @@ the `deletionPolicy` field. `spec.forProvider`. * `Delete` - the external resource will be deleted when the managed resource is deleted. -* `LateInitialize` - select fields of the managed resource - `spec.forProvider` will be updated with the external resource state. +* `LateInitialize` - Unprovided spec fields are late-initialized to + `spec.forProvider` with the default values from the cloud provider. This + enables Crossplane to take full control of the external resource, even those + values not provided by the user upfront. Read more about [Late Initialization]({{}}) @@ -314,9 +344,9 @@ spec: minSize: 1 ``` -It's suggested to use a combination of `managementPolicies` without -`LateInitialize` with `initProvider` to avoid late initialization of fields -in `forProvider`. +It's suggested to use a combination of `managementPolicies` without the +`LateInitialize` action when using `initProvider` to avoid late initialization +of fields in `forProvider`. Read more about [Late Initialization]({{}}) ### providerConfigRef From 032d138f16fa77a5dd85a7e418db3ba99599c326 Mon Sep 17 00:00:00 2001 From: lsviben Date: Tue, 1 Aug 2023 14:56:56 +0200 Subject: [PATCH 03/11] add a few words to vale dictionary Signed-off-by: lsviben --- utils/vale/styles/Crossplane/allowed-jargon.txt | 3 ++- utils/vale/styles/Crossplane/crossplane-words.txt | 5 ++++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/utils/vale/styles/Crossplane/allowed-jargon.txt b/utils/vale/styles/Crossplane/allowed-jargon.txt index bc740bd23..76a88d751 100644 --- a/utils/vale/styles/Crossplane/allowed-jargon.txt +++ b/utils/vale/styles/Crossplane/allowed-jargon.txt @@ -52,4 +52,5 @@ CRD CLI kube-controller-manager kube-apiserver -cluster-wide \ No newline at end of file +cluster-wide +autoscaler \ No newline at end of file diff --git a/utils/vale/styles/Crossplane/crossplane-words.txt b/utils/vale/styles/Crossplane/crossplane-words.txt index dc4df2fd3..845f2fc9d 100644 --- a/utils/vale/styles/Crossplane/crossplane-words.txt +++ b/utils/vale/styles/Crossplane/crossplane-words.txt @@ -49,4 +49,7 @@ crossplane-browse InactivePackageRevision crossplane.yaml definition.yaml -composition.yaml \ No newline at end of file +composition.yaml +managementPolicies +deletionPolicy +initProvider \ No newline at end of file From 4b5864eda45195a0ca6a8dd2fa2ef0848c6fa57c Mon Sep 17 00:00:00 2001 From: lsviben Date: Tue, 1 Aug 2023 15:23:46 +0200 Subject: [PATCH 04/11] fix vale Signed-off-by: lsviben --- content/master/concepts/managed-resources.md | 12 ++++++------ content/v1.13/concepts/managed-resources.md | 12 ++++++------ 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/content/master/concepts/managed-resources.md b/content/master/concepts/managed-resources.md index 6d8000a98..34c504de5 100644 --- a/content/master/concepts/managed-resources.md +++ b/content/master/concepts/managed-resources.md @@ -214,8 +214,8 @@ resource object is deleted from Kubernetes and the `deletionPolicy` is For some of the optional fields, users rely on the default that the cloud provider chooses for them. Since Crossplane treats the managed resource as the source of the truth, values of those fields need to exist in `spec` of the -managed resource. So, in each reconciliation, Crossplane will fill the value of -a field that is left empty by the user but is assigned a value by the provider. +managed resource. In each reconciliation, Crossplane will fill the value of +a field that's left empty by the user but is assigned a value by the provider. For example, there could be two fields like `region` and `availabilityZone` and you might want to give only `region` and leave the availability zone to be chosen by the cloud provider. In that case, if the provider assigns an @@ -243,7 +243,7 @@ For example, setting just `["Observe"]` makes Crossplane treat the resource as a read-only resource, importing the external resources not originally created by Crossplane. This allows other managed resources to reference the read-only resource, for example, a shared database or network. Importing a resource as -read-only is convenient since Crossplane will not attempt to take control and +read-only is convenient since Crossplane wont attempt to take control and only identifier parameters are needed to be specified in the managed resource. {{< hint "tip" >}} @@ -281,8 +281,8 @@ if the management policy alpha feature is enabled. To sum it up in a table: | "*" (default) | Orphan | Orphan | | contains "Delete" | Delete (default) | Delete | | contains "Delete" | Orphan | Delete | -| does not contain "Delete" | Delete (default) | Orphan | -| does not contain "Delete" | Orphan | Orphan | +| doesn't contain "Delete" | Delete (default) | Orphan | +| doesn't contain "Delete" | Orphan | Orphan | {{< /table >}} #### Options @@ -297,7 +297,7 @@ if the management policy alpha feature is enabled. To sum it up in a table: `spec.forProvider`. * `Delete` - the external resource will be deleted when the managed resource is deleted. -* `LateInitialize` - Unprovided spec fields are late-initialized to +* `LateInitialize` - Unprovided spec fields are late initialized to `spec.forProvider` with the default values from the cloud provider. This enables Crossplane to take full control of the external resource, even those values not provided by the user upfront. Read more about [Late Initialization]({{}}) diff --git a/content/v1.13/concepts/managed-resources.md b/content/v1.13/concepts/managed-resources.md index a85c41973..8797daac0 100644 --- a/content/v1.13/concepts/managed-resources.md +++ b/content/v1.13/concepts/managed-resources.md @@ -216,8 +216,8 @@ resource object is deleted from Kubernetes and the `deletionPolicy` is For some of the optional fields, users rely on the default that the cloud provider chooses for them. Since Crossplane treats the managed resource as the source of the truth, values of those fields need to exist in `spec` of the -managed resource. So, in each reconciliation, Crossplane will fill the value of -a field that is left empty by the user but is assigned a value by the provider. +managed resource. In each reconciliation, Crossplane will fill the value of +a field that's left empty by the user but is assigned a value by the provider. For example, there could be two fields like `region` and `availabilityZone` and you might want to give only `region` and leave the availability zone to be chosen by the cloud provider. In that case, if the provider assigns an @@ -245,7 +245,7 @@ For example, setting just `["Observe"]` makes Crossplane treat the resource as a read-only resource, importing the external resources not originally created by Crossplane. This allows other managed resources to reference the read-only resource, for example, a shared database or network. Importing a resource as -read-only is convenient since Crossplane will not attempt to take control and +read-only is convenient since Crossplane wont attempt to take control and only identifier parameters are needed to be specified in the managed resource. {{< hint "tip" >}} @@ -283,8 +283,8 @@ if the management policy alpha feature is enabled. To sum it up in a table: | "*" (default) | Orphan | Orphan | | contains "Delete" | Delete (default) | Delete | | contains "Delete" | Orphan | Delete | -| does not contain "Delete" | Delete (default) | Orphan | -| does not contain "Delete" | Orphan | Orphan | +| doesn't contain "Delete" | Delete (default) | Orphan | +| doesn't contain "Delete" | Orphan | Orphan | {{< /table >}} #### Options @@ -299,7 +299,7 @@ if the management policy alpha feature is enabled. To sum it up in a table: `spec.forProvider`. * `Delete` - the external resource will be deleted when the managed resource is deleted. -* `LateInitialize` - Unprovided spec fields are late-initialized to +* `LateInitialize` - Unprovided spec fields are late initialized to `spec.forProvider` with the default values from the cloud provider. This enables Crossplane to take full control of the external resource, even those values not provided by the user upfront. Read more about [Late Initialization]({{}}) From 78b728d100ec727585e5fedc5356a67da78732f5 Mon Sep 17 00:00:00 2001 From: lsviben Date: Wed, 2 Aug 2023 17:04:35 +0200 Subject: [PATCH 05/11] rewording, moving stuff based on review suggestions Signed-off-by: lsviben --- .../guides/import-existing-resources.md | 15 +- content/master/concepts/managed-resources.md | 219 +++++++++------- content/v1.13/concepts/managed-resources.md | 238 ++++++++++-------- .../vale/styles/Crossplane/allowed-jargon.txt | 3 +- 4 files changed, 261 insertions(+), 214 deletions(-) diff --git a/content/knowledge-base/guides/import-existing-resources.md b/content/knowledge-base/guides/import-existing-resources.md index d4aec9b06..f6c1f0985 100644 --- a/content/knowledge-base/guides/import-existing-resources.md +++ b/content/knowledge-base/guides/import-existing-resources.md @@ -85,22 +85,21 @@ managed resource `spec` changes the external resource. ## Import resources automatically -Automatically import external resources with the granular management polices -[`spec.managementPolicies: ["Observe"]`]({{}}). +Automatically import external resources with an `Observe` [management policy]({{}}). -Crossplane imports `Observe` only resources but never changes or deletes the +Crossplane imports observe only resources but never changes or deletes the resources. {{}} The managed resource `managementPolicies` option is an alpha feature. -Enable the `managementPolicies` in a provider with `--enable-management-policies` +Enable `managementPolicies` in a provider with `--enable-management-policies` in a [ControllerConfig]({{}}). {{< /hint >}} -### Apply the ["Observe"] managementPolicies +### Apply the Observe management policy Create a new managed resource matching the @@ -111,7 +110,7 @@ to import and add {{}}spec{{}} For example, to import a GCP SQL DatabaseInstance, create a new resource with -the {{}}managementPolicy: ObserveOnly{{}} +the {{}}managementPolicies: ["Observe"]{{}} set. ```yaml {label="oo-policy",copy-lines="none"} apiVersion: sql.gcp.upbound.io/v1beta1 @@ -233,10 +232,10 @@ status: ## Control imported ObserveOnly resources -Crossplane can take active control of `ObserveOnly` imported resources by +Crossplane can take active control of observe only imported resources by changing the `managementPolicies` after import. -Change the {{}}managementPolicy{{}} field +Change the {{}}managementPolicies{{}} field of the managed resource to {{}}["*"]{{}}. diff --git a/content/master/concepts/managed-resources.md b/content/master/concepts/managed-resources.md index 34c504de5..f548985f3 100644 --- a/content/master/concepts/managed-resources.md +++ b/content/master/concepts/managed-resources.md @@ -56,7 +56,24 @@ 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 +If a resource configures a Crossplane +[management policy](#managementpolicies) and the related management policy alpha +feature is enabled, the managment policy takes precedence over the +`deletionPolicy` setting, unless it is the default management policy. + +{{< table >}} +| 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 >}} ### forProvider @@ -96,8 +113,11 @@ 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. +#### Late Initialization + +After the external resource creation, providers add some provider defaulted +settings not manually set to the `forProvider` field of the created managed +resource object into their respected `forProvider` fields. Use `kubectl describe ` to view the applied values. #### Referencing other resources @@ -223,107 +243,50 @@ availability zone, Crossplane gets that value and fills `availabilityZone`. Note that if the field is already filled, the controller won't override its value. -### managementPolicies - +### initProvider + {{}} -The managed resource `managementPolicies` option is an alpha feature. +The managed resource `initProvider` option is an alpha feature related to +[managementPolicies]({{}}). -Enable the `managementPolicies` in a provider with `--enable-management-policies` -in a +Enable the `initProvider` in a provider with `--enable-management-policies` +in a [ControllerConfig]({{}}). {{< /hint >}} -Granular `managementPolicies` determine what actions Crossplane can take on a -managed and its external resource. `managementPolicies` is an array of actions -(`Observe`, `Create`, `Update`, `Delete`, `LateInitialize`, `*`), and there are -multiple combinations that Crossplane supports based on the use case. - -For example, setting just `["Observe"]` makes Crossplane treat the resource as -a read-only resource, importing the external resources not originally created -by Crossplane. This allows other managed resources to reference the read-only -resource, for example, a shared database or network. Importing a resource as -read-only is convenient since Crossplane wont attempt to take control and -only identifier parameters are needed to be specified in the managed resource. - -{{< hint "tip" >}} -Read the [Import Existing Resources]({{}}) -guide for more -information on using the `managementPolicies` to import existing resources. -{{< /hint >}} - -Another application of `managementPolicies` is to skip the [Late Initialization]({{}}) -of the managed resource, by not including `LateInitialize` in the -`managementPolicies`, which is useful when there are fields in the resource, -that we would not like Crossplane to control, but would usually be filled in -by Late Initialization. - -{{< hint "tip" >}} -Read the [initProvider]({{}}) section -for more info about how we can use management policies without `LateInitialize` -and `initProvider` together to ignore changes to fields that are controlled -externally. -{{< /hint >}} - -The `"Delete"` action replaces the [deletionPolicy]({{}}) -field in the managed resource. For now the `deletionPolicy` is still supported, -but only if it's set to a non default value, which is `Orphan`. If it's set to -`Orphan`, and the `managementPolicies` is set to `["*"]`, which is default, -then the external resource will be orphaned when the managed resource is -deleted. In other cases, non default `managementPolicies` take precedence over -the `deletionPolicy` field. Keep in mind that this behavior is only applicable -if the management policy alpha feature is enabled. To sum it up in a table: +The +{{}}initProvider{{}} defines +settings Crossplane applies only when creating a new managed resource. +Crossplane ignores settings defined in the +{{}}initProvider{{}} +field that change after creation. -{{< table >}} -| 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 >}} +{{}} +Settings in `forProvider` are always enforced by Crossplane. Crossplane reverts +any changes to a `forProvider` field in the external resource. -#### Options -* `*` - ** Default ** - Crossplane can observe, create, change, delete the - external resource and update the managed resource spec with late init - parameters. -* `Observe` - managed resource `status.atProvider` will be updated with the - external resource state. -* `Create` - external resource will be created using the managed resource - `spec.initProvider` and `spec.forProvider`. -* `Update` - external resource will be updated using the managed resource - `spec.forProvider`. -* `Delete` - the external resource will be deleted when the managed resource is - deleted. -* `LateInitialize` - Unprovided spec fields are late initialized to - `spec.forProvider` with the default values from the cloud provider. This - enables Crossplane to take full control of the external resource, even those - values not provided by the user upfront. Read more about [Late Initialization]({{}}) +Settings in `initProvider` aren't enforced by Crossplane. Crossplane ignores any +changes to a `initProvider` field in the external resource. +{{}} - -### initProvider - +Using `initProvider` is useful for setting initial values that a Provider may +automatically change, like an auto scaling group. -{{}} -The managed resource `initProvider` option is an alpha feature related to -[managementPolicies]({{}}). +For example, creating a +{{}}NodeGroup{{}} +with an initial +{{}}desiredSize{{}}. +Crossplane doesn't change the +{{}}desiredSize{{}} +setting back when an autoscaler scales the Node Group external resource. -Enable the `initProvider` in a provider with `--enable-management-policies` -in a -[ControllerConfig]({{}}). +{{< hint "tip" >}} +Crossplane recommends configuring +{{}}managementPolicies{{}} without +`LateInitialize` to avoid conflicts with `initProvider` settings. {{< /hint >}} -The `spec.initProvider` is a subset of the `spec.forProvider` fields that -Crossplane merges with `forProvider` to create the external resource, but -ignores when updating it. This allows users to create a resource with all the -required fields which may then be controlled externally. For example, a user may -want to create a `NodeGroup` with the required `desiredSize` field, but then -let an autoscaler control the field. If the `desiredSize` field is included -in the`forProvider` field, Crossplane will attempt to update the field, which -will conflict with the autoscaler. - ```yaml {label="initProvider",copy-lines="none"} apiVersion: eks.aws.upbound.io/v1beta1 kind: NodeGroup @@ -341,9 +304,77 @@ spec: minSize: 1 ``` -It's suggested to use a combination of `managementPolicies` without the -`LateInitialize` action when using `initProvider` to avoid late initialization -of fields in `forProvider`. Read more about [Late Initialization]({{}}) + +### managementPolicies + + +{{}} +The managed resource `managementPolicies` option is an alpha feature. + +Enable `managementPolicies` in a provider with `--enable-management-policies` +in a +[ControllerConfig]({{}}). +{{< /hint >}} + +Crossplane +{{}}managementPolicies{{}} +determine which actions Crossplane can take on a +managed resource and its corresponding external resource. +Apply one or more +{{}}managementPolicies{{}} +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 +{{}}["Create", "Delete"]{{}}. + +```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. + +{{}} +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: +{{}} +| 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 imports some external resource settings not defined in the `spec.forProvider` of the managed resource. | +| `Observe` | Crossplane only observes the resource and doesn't make any changes. Used for [observe only resources]({{}}). | +| `Update` | Crossplane changes the external resource when changing the managed resource. | +{{
}} + +The following is a list of common policy combinations: +{{}} +| 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]({{}}). | +| | | | | | No policy set. An alternative method for [pausing](#paused) a resource. | +{{< /table >}} ### providerConfigRef diff --git a/content/v1.13/concepts/managed-resources.md b/content/v1.13/concepts/managed-resources.md index 8797daac0..fc631575f 100644 --- a/content/v1.13/concepts/managed-resources.md +++ b/content/v1.13/concepts/managed-resources.md @@ -58,6 +58,24 @@ Provider deletes the managed resource but doesn't delete the external resource. * `deletionPolicy: Delete` - **Default** - Delete the external resource when deleting the managed resource. * `deletionPolicy: Orphan` - Leave the external resource when deleting the managed resource. +#### Interaction with management policies + +If a resource configures a Crossplane +[management policy](#managementpolicies) and the related management policy alpha +feature is enabled, the managment policy takes precedence over the +`deletionPolicy` setting, unless it is the default management policy. + +{{< table >}} +| 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 >}} + ### forProvider @@ -96,10 +114,13 @@ 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 ` to view the applied values. - +#### Late Initialization + +After the external resource creation, providers add some provider defaulted +settings not manually set to the `forProvider` field of the created managed +resource object into their respected `forProvider` fields. +Use `kubectl describe ` to view the applied values. + #### Referencing other resources Some fields in a managed resource may depend on values from other managed @@ -209,102 +230,6 @@ resource object is deleted from Kubernetes and the `deletionPolicy` is {{< /hint >}} - -#### Late Initialization - - -For some of the optional fields, users rely on the default that the cloud -provider chooses for them. Since Crossplane treats the managed resource as the -source of the truth, values of those fields need to exist in `spec` of the -managed resource. In each reconciliation, Crossplane will fill the value of -a field that's left empty by the user but is assigned a value by the provider. -For example, there could be two fields like `region` and `availabilityZone` and -you might want to give only `region` and leave the availability zone to be -chosen by the cloud provider. In that case, if the provider assigns an -availability zone, Crossplane gets that value and fills `availabilityZone`. Note -that if the field is already filled, the controller won't override its value. - - -### managementPolicies - - -{{}} -The managed resource `managementPolicies` option is an alpha feature. - -Enable the `managementPolicies` in a provider with `--enable-management-policies` -in a -[ControllerConfig]({{}}). -{{< /hint >}} - -Granular `managementPolicies` determine what actions Crossplane can take on a -managed and its external resource. `managementPolicies` is an array of actions -(`Observe`, `Create`, `Update`, `Delete`, `LateInitialize`, `*`), and there are -multiple combinations that Crossplane supports based on the use case. - -For example, setting just `["Observe"]` makes Crossplane treat the resource as -a read-only resource, importing the external resources not originally created -by Crossplane. This allows other managed resources to reference the read-only -resource, for example, a shared database or network. Importing a resource as -read-only is convenient since Crossplane wont attempt to take control and -only identifier parameters are needed to be specified in the managed resource. - -{{< hint "tip" >}} -Read the [Import Existing Resources]({{}}) -guide for more -information on using the `managementPolicies` to import existing resources. -{{< /hint >}} - -Another application of `managementPolicies` is to skip the [Late Initialization]({{}}) -of the managed resource, by not including `LateInitialize` in the -`managementPolicies`, which is useful when there are fields in the resource, -that we would not like Crossplane to control, but would usually be filled in -by Late Initialization. - -{{< hint "tip" >}} -Read the [initProvider]({{}}) section -for more info about how we can use management policies without `LateInitialize` -and `initProvider` together to ignore changes to fields that are controlled -externally. -{{< /hint >}} - -The `"Delete"` action replaces the [deletionPolicy]({{}}) -field in the managed resource. For now the `deletionPolicy` is still supported, -but only if it's set to a non default value, which is `Orphan`. If it's set to -`Orphan`, and the `managementPolicies` is set to `["*"]`, which is default, -then the external resource will be orphaned when the managed resource is -deleted. In other cases, non default `managementPolicies` take precedence over -the `deletionPolicy` field. Keep in mind that this behavior is only applicable -if the management policy alpha feature is enabled. To sum it up in a table: - -{{< table >}} -| 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 >}} - -#### Options -* `*` - ** Default ** - Crossplane can observe, create, change, delete the - external resource and update the managed resource spec with late init - parameters. -* `Observe` - managed resource `status.atProvider` will be updated with the - external resource state. -* `Create` - external resource will be created using the managed resource - `spec.initProvider` and `spec.forProvider`. -* `Update` - external resource will be updated using the managed resource - `spec.forProvider`. -* `Delete` - the external resource will be deleted when the managed resource is - deleted. -* `LateInitialize` - Unprovided spec fields are late initialized to - `spec.forProvider` with the default values from the cloud provider. This - enables Crossplane to take full control of the external resource, even those - values not provided by the user upfront. Read more about [Late Initialization]({{}}) - - ### initProvider @@ -318,14 +243,37 @@ in a [ControllerConfig]({{}}). {{< /hint >}} -The `spec.initProvider` is a subset of the `spec.forProvider` fields that -Crossplane merges with `forProvider` to create the external resource, but -ignores when updating it. This allows users to create a resource with all the -required fields which may then be controlled externally. For example, a user may -want to create a `NodeGroup` with the required `desiredSize` field, but then -let an autoscaler control the field. If the `desiredSize` field is included -in the`forProvider` field, Crossplane will attempt to update the field, which -will conflict with the autoscaler. +The +{{}}initProvider{{}} defines +settings Crossplane applies only when creating a new managed resource. +Crossplane ignores settings defined in the +{{}}initProvider{{}} +field that change after creation. + +{{}} +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. +{{}} + +Using `initProvider` is useful for setting initial values that a Provider may +automatically change, like an auto scaling group. + +For example, creating a +{{}}NodeGroup{{}} +with an initial +{{}}desiredSize{{}}. +Crossplane doesn't change the +{{}}desiredSize{{}} +setting back when an autoscaler scales the Node Group external resource. + +{{< hint "tip" >}} +Crossplane recommends configuring +{{}}managementPolicies{{}} without +`LateInitialize` to avoid conflicts with `initProvider` settings. +{{< /hint >}} ```yaml {label="initProvider",copy-lines="none"} apiVersion: eks.aws.upbound.io/v1beta1 @@ -344,9 +292,77 @@ spec: minSize: 1 ``` -It's suggested to use a combination of `managementPolicies` without the -`LateInitialize` action when using `initProvider` to avoid late initialization -of fields in `forProvider`. Read more about [Late Initialization]({{}}) + +### managementPolicies + + +{{}} +The managed resource `managementPolicies` option is an alpha feature. + +Enable `managementPolicies` in a provider with `--enable-management-policies` +in a +[ControllerConfig]({{}}). +{{< /hint >}} + +Crossplane +{{}}managementPolicies{{}} +determine which actions Crossplane can take on a +managed resource and its corresponding external resource. +Apply one or more +{{}}managementPolicies{{}} +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 +{{}}["Create", "Delete"]{{}}. + +```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. + +{{}} +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: +{{
}} +| 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 imports some external resource settings not defined in the `spec.forProvider` of the managed resource. | +| `Observe` | Crossplane only observes the resource and doesn't make any changes. Used for [observe only resources]({{}}). | +| `Update` | Crossplane changes the external resource when changing the managed resource. | +{{
}} + +The following is a list of common policy combinations: +{{}} +| 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]({{}}). | +| | | | | | No policy set. An alternative method for [pausing](#paused) a resource. | +{{< /table >}} ### providerConfigRef diff --git a/utils/vale/styles/Crossplane/allowed-jargon.txt b/utils/vale/styles/Crossplane/allowed-jargon.txt index 76a88d751..7a716c144 100644 --- a/utils/vale/styles/Crossplane/allowed-jargon.txt +++ b/utils/vale/styles/Crossplane/allowed-jargon.txt @@ -53,4 +53,5 @@ CLI kube-controller-manager kube-apiserver cluster-wide -autoscaler \ No newline at end of file +autoscaler +DatabaseInstance \ No newline at end of file From cdfe15d76460e2c09487d1aa477df9daf302e527 Mon Sep 17 00:00:00 2001 From: lsviben Date: Wed, 2 Aug 2023 17:13:08 +0200 Subject: [PATCH 06/11] fix Vale Signed-off-by: lsviben --- content/master/concepts/managed-resources.md | 5 +++-- content/v1.13/concepts/managed-resources.md | 4 ++-- utils/vale/styles/Crossplane/crossplane-words.txt | 3 ++- 3 files changed, 7 insertions(+), 5 deletions(-) diff --git a/content/master/concepts/managed-resources.md b/content/master/concepts/managed-resources.md index f548985f3..e1fc809fa 100644 --- a/content/master/concepts/managed-resources.md +++ b/content/master/concepts/managed-resources.md @@ -59,10 +59,11 @@ Provider deletes the managed resource but doesn't delete the external resource. * `deletionPolicy: Orphan` - Leave the external resource when deleting the managed resource. #### Interaction with management policies + If a resource configures a Crossplane [management policy](#managementpolicies) and the related management policy alpha -feature is enabled, the managment policy takes precedence over the -`deletionPolicy` setting, unless it is the default management policy. +feature is enabled, the management policy takes precedence over the +`deletionPolicy` setting, unless it's the default management policy. {{< table >}} | managementPolicies | deletionPolicy | result | diff --git a/content/v1.13/concepts/managed-resources.md b/content/v1.13/concepts/managed-resources.md index fc631575f..60521d0d2 100644 --- a/content/v1.13/concepts/managed-resources.md +++ b/content/v1.13/concepts/managed-resources.md @@ -62,8 +62,8 @@ Provider deletes the managed resource but doesn't delete the external resource. If a resource configures a Crossplane [management policy](#managementpolicies) and the related management policy alpha -feature is enabled, the managment policy takes precedence over the -`deletionPolicy` setting, unless it is the default management policy. +feature is enabled, the management policy takes precedence over the +`deletionPolicy` setting, unless it's the default management policy. {{< table >}} | managementPolicies | deletionPolicy | result | diff --git a/utils/vale/styles/Crossplane/crossplane-words.txt b/utils/vale/styles/Crossplane/crossplane-words.txt index 845f2fc9d..8347f19bf 100644 --- a/utils/vale/styles/Crossplane/crossplane-words.txt +++ b/utils/vale/styles/Crossplane/crossplane-words.txt @@ -52,4 +52,5 @@ definition.yaml composition.yaml managementPolicies deletionPolicy -initProvider \ No newline at end of file +initProvider +LateInitialize \ No newline at end of file From 73c3d1ae079e23df21f185cf1362471089d8e9b6 Mon Sep 17 00:00:00 2001 From: lsviben Date: Thu, 3 Aug 2023 11:44:51 +0200 Subject: [PATCH 07/11] add css for dark mode tables Signed-off-by: lsviben --- themes/geekboot/assets/scss/dark-mode.scss | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/themes/geekboot/assets/scss/dark-mode.scss b/themes/geekboot/assets/scss/dark-mode.scss index 66f724cbf..4335a55d8 100644 --- a/themes/geekboot/assets/scss/dark-mode.scss +++ b/themes/geekboot/assets/scss/dark-mode.scss @@ -122,4 +122,11 @@ } } } -} \ No newline at end of file + + //Striped table font color + .table-striped-columns > :not(caption) > tr > :nth-child(even){ + color: inherit !important; + } +} + + From 46ebbb1461b4f025ede0fd05a4edf27b7ce24c67 Mon Sep 17 00:00:00 2001 From: lsviben Date: Sun, 6 Aug 2023 16:14:38 +0200 Subject: [PATCH 08/11] applied suggestions from review Signed-off-by: lsviben --- content/master/concepts/managed-resources.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/content/master/concepts/managed-resources.md b/content/master/concepts/managed-resources.md index e1fc809fa..5a6846a74 100644 --- a/content/master/concepts/managed-resources.md +++ b/content/master/concepts/managed-resources.md @@ -61,11 +61,10 @@ Provider deletes the managed resource but doesn't delete the external resource. #### Interaction with management policies If a resource configures a Crossplane -[management policy](#managementpolicies) and the related management policy alpha -feature is enabled, the management policy takes precedence over the -`deletionPolicy` setting, unless it's the default management policy. +[management policy](#managementpolicies), the management policy takes precedence +over the `deletionPolicy` setting, unless it's the default management policy. -{{< table >}} +{{< table "table table-sm table-hover">}} | managementPolicies | deletionPolicy | result | |-----------------------------|------------------|---------| | "*" (default) | Delete (default) | Delete | @@ -114,7 +113,7 @@ inside a Provider's web console, Crossplane reverts that change back to what's configured in the `forProvider` setting. {{< /hint >}} -#### Late Initialization +#### Late initialization After the external resource creation, providers add some provider defaulted settings not manually set to the `forProvider` field of the created managed From fbe86e68fe566dbac3f5e80da3d8b2a41150be95 Mon Sep 17 00:00:00 2001 From: Hasan Turken Date: Mon, 7 Aug 2023 16:34:42 +0300 Subject: [PATCH 09/11] Fix Vale by not breaking references in import existing resources Signed-off-by: Hasan Turken --- content/knowledge-base/guides/import-existing-resources.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/content/knowledge-base/guides/import-existing-resources.md b/content/knowledge-base/guides/import-existing-resources.md index f6c1f0985..693e337f2 100644 --- a/content/knowledge-base/guides/import-existing-resources.md +++ b/content/knowledge-base/guides/import-existing-resources.md @@ -8,9 +8,8 @@ you can import them as managed resources and let Crossplane manage them. A managed resource's [`managementPolicy`]({{}}) field enables importing external resources into Crossplane. -Crossplane can import resources either [manually]({{}}) or [automatically]({{}}). +Crossplane can import resources either [manually]({{}}) +or [automatically]({{}}). ## Import resources manually From cc084ecec6e190feaee33a3464e895e933fdc8f5 Mon Sep 17 00:00:00 2001 From: Hasan Turken Date: Mon, 7 Aug 2023 17:03:39 +0300 Subject: [PATCH 10/11] Remove duplicate late init sections & sync v1.13 with master Signed-off-by: Hasan Turken --- content/master/concepts/managed-resources.md | 20 ++++++---------- content/v1.13/concepts/managed-resources.md | 25 ++++++++++++-------- 2 files changed, 22 insertions(+), 23 deletions(-) diff --git a/content/master/concepts/managed-resources.md b/content/master/concepts/managed-resources.md index 5a6846a74..2acdaa984 100644 --- a/content/master/concepts/managed-resources.md +++ b/content/master/concepts/managed-resources.md @@ -61,8 +61,9 @@ Provider deletes the managed resource but doesn't delete the external resource. #### Interaction with management policies If a resource configures a Crossplane -[management policy](#managementpolicies), the management policy takes precedence -over the `deletionPolicy` setting, unless it's the default management policy. +[management policy](#managementpolicies) and the related management policy alpha +feature is enabled, the management policy takes precedence over the +`deletionPolicy` setting, unless it's the default management policy. {{< table "table table-sm table-hover">}} | managementPolicies | deletionPolicy | result | @@ -113,13 +114,6 @@ inside a Provider's web console, Crossplane reverts that change back to what's configured in the `forProvider` setting. {{< /hint >}} -#### Late initialization - -After the external resource creation, providers add some provider defaulted -settings not manually set to the `forProvider` field of the created managed -resource object into their respected `forProvider` fields. -Use `kubectl describe ` to view the applied values. - #### Referencing other resources Some fields in a managed resource may depend on values from other managed @@ -229,7 +223,7 @@ resource object is deleted from Kubernetes and the `deletionPolicy` is {{< /hint >}} -#### Late Initialization +#### Late initialization For some of the optional fields, users rely on the default that the cloud provider chooses for them. Since Crossplane treats the managed resource as the @@ -309,10 +303,10 @@ spec: {{}} -The managed resource `managementPolicies` option is an alpha feature. +The managed resource `managementPolicies` option is an alpha feature. -Enable `managementPolicies` in a provider with `--enable-management-policies` -in a +Enable `managementPolicies` in a provider with `--enable-management-policies` +in a [ControllerConfig]({{}}). {{< /hint >}} diff --git a/content/v1.13/concepts/managed-resources.md b/content/v1.13/concepts/managed-resources.md index 60521d0d2..2acdaa984 100644 --- a/content/v1.13/concepts/managed-resources.md +++ b/content/v1.13/concepts/managed-resources.md @@ -56,7 +56,7 @@ 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 @@ -65,7 +65,7 @@ If a resource configures a Crossplane feature is enabled, the management policy takes precedence over the `deletionPolicy` setting, unless it's the default management policy. -{{< table >}} +{{< table "table table-sm table-hover">}} | managementPolicies | deletionPolicy | result | |-----------------------------|------------------|---------| | "*" (default) | Delete (default) | Delete | @@ -114,13 +114,6 @@ inside a Provider's web console, Crossplane reverts that change back to what's configured in the `forProvider` setting. {{< /hint >}} -#### Late Initialization - -After the external resource creation, providers add some provider defaulted -settings not manually set to the `forProvider` field of the created managed -resource object into their respected `forProvider` fields. -Use `kubectl describe ` to view the applied values. - #### Referencing other resources Some fields in a managed resource may depend on values from other managed @@ -230,6 +223,19 @@ resource object is deleted from Kubernetes and the `deletionPolicy` is {{< /hint >}} +#### Late initialization + +For some of the optional fields, users rely on the default that the cloud +provider chooses for them. Since Crossplane treats the managed resource as the +source of the truth, values of those fields need to exist in `spec` of the +managed resource. In each reconciliation, Crossplane will fill the value of +a field that's left empty by the user but is assigned a value by the provider. +For example, there could be two fields like `region` and `availabilityZone` and +you might want to give only `region` and leave the availability zone to be +chosen by the cloud provider. In that case, if the provider assigns an +availability zone, Crossplane gets that value and fills `availabilityZone`. Note +that if the field is already filled, the controller won't override its value. + ### initProvider @@ -558,7 +564,6 @@ Read the guide for details on using StoreConfig objects. {{< /hint >}} - ## Annotations Crossplane applies a standard set of Kubernetes `annotations` to managed From 62f12d6f4af90f61c5fff7c327d3fc2590197c14 Mon Sep 17 00:00:00 2001 From: Hasan Turken Date: Mon, 7 Aug 2023 17:33:35 +0300 Subject: [PATCH 11/11] Fix all vale errors for management policies Signed-off-by: Hasan Turken --- content/master/concepts/managed-resources.md | 40 ++++++++++++-------- content/v1.13/concepts/managed-resources.md | 40 ++++++++++++-------- 2 files changed, 50 insertions(+), 30 deletions(-) diff --git a/content/master/concepts/managed-resources.md b/content/master/concepts/managed-resources.md index 2acdaa984..b13006aad 100644 --- a/content/master/concepts/managed-resources.md +++ b/content/master/concepts/managed-resources.md @@ -60,10 +60,14 @@ Provider deletes the managed resource but doesn't delete the external resource. #### Interaction with management policies -If a resource configures a Crossplane -[management policy](#managementpolicies) and the related management policy alpha -feature is enabled, the management policy takes precedence over the -`deletionPolicy` setting, unless it's the default management policy. +The [management policy](#managementpolicies) takes precedence over the +`deletionPolicy` when: + +- The related management policy alpha feature is enabled. + +- 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 | @@ -225,16 +229,22 @@ resource object is deleted from Kubernetes and the `deletionPolicy` is #### Late initialization -For some of the optional fields, users rely on the default that the cloud -provider chooses for them. Since Crossplane treats the managed resource as the -source of the truth, values of those fields need to exist in `spec` of the -managed resource. In each reconciliation, Crossplane will fill the value of -a field that's left empty by the user but is assigned a value by the provider. -For example, there could be two fields like `region` and `availabilityZone` and -you might want to give only `region` and leave the availability zone to be -chosen by the cloud provider. In that case, if the provider assigns an -availability zone, Crossplane gets that value and fills `availabilityZone`. Note -that if the field is already filled, the controller won't override its value. +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. + +{{}} + +With [managementPolicies]({{}}), +this behavior can be turned off by not including the `LateInitialize` policy in +the `managementPolicies` list. + +{{< /hint >}} ### initProvider @@ -349,7 +359,7 @@ Crossplane supports the following policies: | `*` | _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 imports some external resource settings not defined in the `spec.forProvider` of the managed resource. | +| `LateInitialize` | Crossplane initializes some external resource settings not defined in the `spec.forProvider` of the managed resource. See [the late initialization]({{}}) section for more details. | | `Observe` | Crossplane only observes the resource and doesn't make any changes. Used for [observe only resources]({{}}). | | `Update` | Crossplane changes the external resource when changing the managed resource. | {{
}} diff --git a/content/v1.13/concepts/managed-resources.md b/content/v1.13/concepts/managed-resources.md index 2acdaa984..b13006aad 100644 --- a/content/v1.13/concepts/managed-resources.md +++ b/content/v1.13/concepts/managed-resources.md @@ -60,10 +60,14 @@ Provider deletes the managed resource but doesn't delete the external resource. #### Interaction with management policies -If a resource configures a Crossplane -[management policy](#managementpolicies) and the related management policy alpha -feature is enabled, the management policy takes precedence over the -`deletionPolicy` setting, unless it's the default management policy. +The [management policy](#managementpolicies) takes precedence over the +`deletionPolicy` when: + +- The related management policy alpha feature is enabled. + +- 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 | @@ -225,16 +229,22 @@ resource object is deleted from Kubernetes and the `deletionPolicy` is #### Late initialization -For some of the optional fields, users rely on the default that the cloud -provider chooses for them. Since Crossplane treats the managed resource as the -source of the truth, values of those fields need to exist in `spec` of the -managed resource. In each reconciliation, Crossplane will fill the value of -a field that's left empty by the user but is assigned a value by the provider. -For example, there could be two fields like `region` and `availabilityZone` and -you might want to give only `region` and leave the availability zone to be -chosen by the cloud provider. In that case, if the provider assigns an -availability zone, Crossplane gets that value and fills `availabilityZone`. Note -that if the field is already filled, the controller won't override its value. +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. + +{{}} + +With [managementPolicies]({{}}), +this behavior can be turned off by not including the `LateInitialize` policy in +the `managementPolicies` list. + +{{< /hint >}} ### initProvider @@ -349,7 +359,7 @@ Crossplane supports the following policies: | `*` | _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 imports some external resource settings not defined in the `spec.forProvider` of the managed resource. | +| `LateInitialize` | Crossplane initializes some external resource settings not defined in the `spec.forProvider` of the managed resource. See [the late initialization]({{}}) section for more details. | | `Observe` | Crossplane only observes the resource and doesn't make any changes. Used for [observe only resources]({{}}). | | `Update` | Crossplane changes the external resource when changing the managed resource. | {{}}