diff --git a/content/master/guides/change-logs.md b/content/master/guides/change-logs.md new file mode 100644 index 00000000..139a4367 --- /dev/null +++ b/content/master/guides/change-logs.md @@ -0,0 +1,271 @@ +--- +title: Change Logs +weight: 210 +description: "Change logs help you audit all changes made to your resources" +state: alpha +alphaVersion: "1.17" +--- + +The "change logs" feature is designed to help users of Crossplane Providers to +understand what changes a provider is making to the resources it's managing. +Whenever a provider creates, updates, or deletes a managed resource, an entry +explaining the details of the change is recorded in the provider's change log. + +Change logs are important for awareness of the changes that a provider is +making to its managed resources. Due to the nature of Crossplane's active +reconciliation, it's possible for a provider to make changes to managed +resources without any user interaction. Consider the scenario when someone +updates a resource outside of Crossplane, for example via the AWS console or +`gcloud` CLI. When Crossplane detects this configuration drift it will +enforce its source of truth to eventually correct this unexpected change +without any user interaction. + +With Crossplane acting continuously and autonomously to update critical +infrastructure, it's vital for users to have insight into the operations being +performed, so they can build and maintain a strong sense of confidence and trust +in their control planes. Change logs provide details about all changes the +provider makes, so users can remain aware of any changes, even when they aren't +explicitly expecting any. + +{{}} Change logs help you understand all the changes a provider is +making to your resources, even when changes weren't explicitly requested, for +example as a result of Crossplane's automatic correction of configuration drift. +{{}} + +## Enabling Change Logs + +{{}} Change logs are an alpha feature and must be explicitly +enabled for each provider through the use of a `DeploymentRuntimeConfig`. +{{}} + +To enable change logs for a provider, use a `DeploymentRuntimeConfig` to +configure each provider pod that should start producing change logs. The +`DeploymentRuntimeConfig` has a few important configuration details: + +1. A command line argument to the provider container that enables the change + logs feature, for example `--enable-changelogs`. +1. A [side car container](https://github.com/crossplane/changelogs-sidecar) that + collects change events and produces change log entries to the provider's pod + logs. +1. A shared volume mounted to both the provider and sidecar containers that + enables communication of change events between the two containers. + +### Prerequisites + +This guide assumes you have a control plane with [Crossplane installed]({{}}). + +It also assumes you have the [`jq` tool installed](https://jqlang.org/download/), +to perform lightweight querying and filtering of the content in the change logs. + +The only other prerequisite for enabling change logs is that the provider must +have added support for the change logs feature. This is optional and not all +providers in the Crossplane ecosystem have added this support yet. + +{{}} Not all providers support the change logs feature. Check with +your provider of choice to confirm it has added support for change logs. +{{}} + +This guide walks through a full example of generating change logs with +[`provider-kubernetes`](https://github.com/crossplane-contrib/provider-kubernetes). + +### Create a `DeploymentRuntimeConfig` + +Create a `DeploymentRuntimeConfig` that will enable change logs for +the provider when it's installed by performing the necessary configuration +steps: + +1. The {{}}--enable-changelogs{{}} flag is + set on the provider. +1. The {{}}sidecar container{{}} is added + to the provider pod. +1. A {{}}shared volume{{}} is declared and + then mounted in the {{}}provider + container{{}} and the {{}}sidecar + container{{}}. + +```yaml {label="drc",copy-lines="all"} +cat <}}provider{{}} and +instruct it to use the {{}}DeploymentRuntimeConfig{{}} +that was just created. + +```yaml {label="provider",copy-lines="all"} +cat <}} This guide grants specific permissions to the provider +for example purposes. This approach isn't intended to be representative of a +production environment. More examples on configuring `provider-kubernetes` can +be found in its [examples directory](https://github.com/crossplane-contrib/provider-kubernetes/tree/main/examples/provider). +{{}} + +```yaml {label="rbac",copy-lines="all"} +cat <