diff --git a/content/knowledge-base/guides/import-existing-resources.md b/content/knowledge-base/guides/import-existing-resources.md index 085c94bc..693e337f 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 @@ -85,39 +84,38 @@ managed resource `spec` changes the external resource. ## Import resources automatically -Automatically import external resources with the -`ObserveOnly` [`managementPolicy`]({{}}). +Automatically import external resources with an `Observe` [management policy]({{}}). -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 `managementPolicies` in a provider with `--enable-management-policies` in a [ControllerConfig]({{}}). {{< /hint >}} -### Apply the ObserveOnly managementPolicy +### Apply the Observe management policy 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 -the {{}}managementPolicy: ObserveOnly{{}} +the {{}}managementPolicies: ["Observe"]{{}} 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 @@ -138,7 +136,7 @@ metadata: annotations: crossplane.io/external-name: my-external-database spec: - managementPolicy: ObserveOnly + managementPolicies: ["Observe"] ``` ### Create a Kubernetes object name @@ -156,7 +154,7 @@ metadata: annotations: crossplane.io/external-name: my-external-database spec: - managementPolicy: ObserveOnly + managementPolicies: ["Observe"] ``` ### Identify a specific external resource @@ -175,7 +173,7 @@ metadata: annotations: crossplane.io/external-name: my-external-database spec: - managementPolicy: ObserveOnly + managementPolicies: ["Observe"] forProvider: region: "us-central1" ``` @@ -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: @@ -233,12 +231,12 @@ status: ## Control imported ObserveOnly resources -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 {{}}managementPolicy{{}} field +Change the {{}}managementPolicies{{}} field of the managed resource to -{{}}FullControl{{}}. +{{}}["*"]{{}}. Copy any required parameter values from {{}}status.atProvider{{}} and provide them @@ -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 diff --git a/content/master/concepts/managed-resources.md b/content/master/concepts/managed-resources.md index ecc4fddb..b13006aa 100644 --- a/content/master/concepts/managed-resources.md +++ b/content/master/concepts/managed-resources.md @@ -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: + +- 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 | +|-----------------------------|------------------|---------| +| "*" (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 +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 ` to view the applied values. - #### Referencing other resources Some fields in a managed resource may depend on values from other managed @@ -208,40 +226,159 @@ resource object is deleted from Kubernetes and the `deletionPolicy` is `delete`. {{< /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. + +{{}} + +With [managementPolicies]({{}}), +this behavior can be turned off by not including the `LateInitialize` policy in +the `managementPolicies` list. + +{{< /hint >}} -### managementPolicy - +### initProvider + {{}} -The managed resource `managementPolicy` option is an alpha feature. +The managed resource `initProvider` option is an alpha feature related to +[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]({{}}). {{< /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 +{{}}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" >}} -Read the [Import Existing Resources]({{}}) -guide for more -information on using the `managementPolicy` to import existing resources. +Crossplane recommends configuring +{{}}managementPolicies{{}} 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 +``` + +### 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 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. | +{{
}} + +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 @@ -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 diff --git a/content/v1.13/concepts/managed-resources.md b/content/v1.13/concepts/managed-resources.md index ecc4fddb..b13006aa 100644 --- a/content/v1.13/concepts/managed-resources.md +++ b/content/v1.13/concepts/managed-resources.md @@ -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: + +- 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 | +|-----------------------------|------------------|---------| +| "*" (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 +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 ` to view the applied values. - #### Referencing other resources Some fields in a managed resource may depend on values from other managed @@ -208,40 +226,159 @@ resource object is deleted from Kubernetes and the `deletionPolicy` is `delete`. {{< /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. + +{{}} + +With [managementPolicies]({{}}), +this behavior can be turned off by not including the `LateInitialize` policy in +the `managementPolicies` list. + +{{< /hint >}} -### managementPolicy - +### initProvider + {{}} -The managed resource `managementPolicy` option is an alpha feature. +The managed resource `initProvider` option is an alpha feature related to +[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]({{}}). {{< /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 +{{}}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" >}} -Read the [Import Existing Resources]({{}}) -guide for more -information on using the `managementPolicy` to import existing resources. +Crossplane recommends configuring +{{}}managementPolicies{{}} 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 +``` + +### 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 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. | +{{
}} + +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 @@ -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 diff --git a/themes/geekboot/assets/scss/dark-mode.scss b/themes/geekboot/assets/scss/dark-mode.scss index 66f724cb..4335a55d 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; + } +} + + diff --git a/utils/vale/styles/Crossplane/allowed-jargon.txt b/utils/vale/styles/Crossplane/allowed-jargon.txt index bc740bd2..7a716c14 100644 --- a/utils/vale/styles/Crossplane/allowed-jargon.txt +++ b/utils/vale/styles/Crossplane/allowed-jargon.txt @@ -52,4 +52,6 @@ CRD CLI kube-controller-manager kube-apiserver -cluster-wide \ No newline at end of file +cluster-wide +autoscaler +DatabaseInstance \ 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 dc4df2fd..8347f19b 100644 --- a/utils/vale/styles/Crossplane/crossplane-words.txt +++ b/utils/vale/styles/Crossplane/crossplane-words.txt @@ -49,4 +49,8 @@ crossplane-browse InactivePackageRevision crossplane.yaml definition.yaml -composition.yaml \ No newline at end of file +composition.yaml +managementPolicies +deletionPolicy +initProvider +LateInitialize \ No newline at end of file