mirror of https://github.com/crossplane/docs.git
Jared Watts
GitHub
commit
7b445dcff8
|
|
@ -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.
|
||||
|
||||
{{<hint "tip">}} 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.
|
||||
{{</hint>}}
|
||||
|
||||
## Enabling Change Logs
|
||||
|
||||
{{<hint "important" >}} Change logs are an alpha feature and must be explicitly
|
||||
enabled for each provider through the use of a `DeploymentRuntimeConfig`.
|
||||
{{</hint >}}
|
||||
|
||||
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]({{<ref "../software/install">}}).
|
||||
|
||||
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.
|
||||
|
||||
{{<hint "tip">}} Not all providers support the change logs feature. Check with
|
||||
your provider of choice to confirm it has added support for change logs.
|
||||
{{</hint>}}
|
||||
|
||||
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 {{<hover label="drc" line="15">}}--enable-changelogs{{</hover>}} flag is
|
||||
set on the provider.
|
||||
1. The {{<hover label="drc" line="19">}}sidecar container{{</hover>}} is added
|
||||
to the provider pod.
|
||||
1. A {{<hover label="drc" line="24">}}shared volume{{</hover>}} is declared and
|
||||
then mounted in the {{<hover label="drc" line="16">}}provider
|
||||
container{{</hover>}} and the {{<hover label="drc" line="21">}}sidecar
|
||||
container{{</hover>}}.
|
||||
|
||||
```yaml {label="drc",copy-lines="all"}
|
||||
cat <<EOF | kubectl apply -f -
|
||||
apiVersion: pkg.crossplane.io/v1beta1
|
||||
kind: DeploymentRuntimeConfig
|
||||
metadata:
|
||||
name: enable-changelogs
|
||||
spec:
|
||||
deploymentTemplate:
|
||||
spec:
|
||||
selector: {}
|
||||
template:
|
||||
spec:
|
||||
containers:
|
||||
- name: package-runtime
|
||||
args:
|
||||
- --enable-changelogs
|
||||
volumeMounts:
|
||||
- name: changelogs-vol
|
||||
mountPath: /var/run/changelogs
|
||||
- name: changelogs-sidecar
|
||||
image: xpkg.crossplane.io/crossplane/changelogs-sidecar:v0.0.1
|
||||
volumeMounts:
|
||||
- name: changelogs-vol
|
||||
mountPath: /var/run/changelogs
|
||||
volumes:
|
||||
- name: changelogs-vol
|
||||
emptyDir: {}
|
||||
serviceAccountTemplate:
|
||||
metadata:
|
||||
name: provider-kubernetes
|
||||
EOF
|
||||
```
|
||||
|
||||
### Install the provider
|
||||
|
||||
Install the {{<hover label="provider" line="7">}}provider{{</hover>}} and
|
||||
instruct it to use the {{<hover label="provider" line="8">}}DeploymentRuntimeConfig{{</hover>}}
|
||||
that was just created.
|
||||
|
||||
```yaml {label="provider",copy-lines="all"}
|
||||
cat <<EOF | kubectl apply -f -
|
||||
apiVersion: pkg.crossplane.io/v1
|
||||
kind: Provider
|
||||
metadata:
|
||||
name: provider-kubernetes
|
||||
spec:
|
||||
package: xpkg.crossplane.io/crossplane-contrib/provider-kubernetes:v0.18.0
|
||||
runtimeConfigRef:
|
||||
apiVersion: pkg.crossplane.io/v1beta1
|
||||
kind: DeploymentRuntimeConfig
|
||||
name: enable-changelogs
|
||||
EOF
|
||||
```
|
||||
|
||||
### Configure permissions
|
||||
|
||||
In order for the provider to create Kubernetes resources within the control
|
||||
plane, it must be granted the appropriate permissions. This guide only creates a
|
||||
`ConfigMap`, so only permissions for that resource type are needed.
|
||||
|
||||
{{<hint "important">}} 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).
|
||||
{{</hint>}}
|
||||
|
||||
```yaml {label="rbac",copy-lines="all"}
|
||||
cat <<EOF | kubectl apply -f -
|
||||
apiVersion: rbac.authorization.k8s.io/v1
|
||||
kind: ClusterRole
|
||||
metadata:
|
||||
name: configmap-edit
|
||||
rules:
|
||||
- apiGroups:
|
||||
- ""
|
||||
resources:
|
||||
- configmaps
|
||||
verbs:
|
||||
- "*"
|
||||
---
|
||||
apiVersion: rbac.authorization.k8s.io/v1
|
||||
kind: ClusterRoleBinding
|
||||
metadata:
|
||||
name: provider-kubernetes-configmap-edit
|
||||
subjects:
|
||||
- kind: ServiceAccount
|
||||
name: provider-kubernetes
|
||||
namespace: crossplane-system
|
||||
roleRef:
|
||||
kind: ClusterRole
|
||||
name: configmap-edit
|
||||
apiGroup: rbac.authorization.k8s.io
|
||||
---
|
||||
apiVersion: kubernetes.crossplane.io/v1alpha1
|
||||
kind: ProviderConfig
|
||||
metadata:
|
||||
name: default
|
||||
spec:
|
||||
credentials:
|
||||
source: InjectedIdentity
|
||||
EOF
|
||||
```
|
||||
|
||||
### Create a resource
|
||||
|
||||
Now that the provider is installed and configured with change logs enabled,
|
||||
create a resource that will generate change logs entries reflecting the actions
|
||||
the control plane is taking.
|
||||
|
||||
```yaml {label="provider",copy-lines="all"}
|
||||
cat <<EOF | kubectl apply -f -
|
||||
apiVersion: kubernetes.crossplane.io/v1alpha2
|
||||
kind: Object
|
||||
metadata:
|
||||
name: configmap-for-changelogs
|
||||
spec:
|
||||
forProvider:
|
||||
manifest:
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
namespace: default
|
||||
name: configmap-for-changelogs
|
||||
data:
|
||||
key-1: cool-value-1
|
||||
EOF
|
||||
```
|
||||
|
||||
### Examine the change logs
|
||||
|
||||
Check to see that the resource creation operation was recorded in the change
|
||||
logs. Examine the pod logs for `provider-kubernetes`, specifically at the
|
||||
`changelogs-sidecar` container:
|
||||
```shell {label="changelogs-output-full",copy-lines="1"}
|
||||
kubectl -n crossplane-system logs -l pkg.crossplane.io/provider=provider-kubernetes -c changelogs-sidecar | jq
|
||||
{
|
||||
"timestamp": "2025-04-25T08:23:34Z",
|
||||
"provider": "provider-kubernetes:v0.18.0",
|
||||
"apiVersion": "kubernetes.crossplane.io/v1alpha2",
|
||||
"kind": "Object",
|
||||
"name": "configmap-for-changelogs",
|
||||
"externalName": "configmap-for-changelogs",
|
||||
"operation": "OPERATION_TYPE_CREATE",
|
||||
"snapshot": {
|
||||
...(omitted for brevity)...
|
||||
```
|
||||
|
||||
Each change log entry contains rich information about the state of the resource
|
||||
when the change operation occurred. Since each entry is a structured `JSON`
|
||||
object, they can be filtered and queried to find any subset of information you
|
||||
are interested in:
|
||||
```shell {label="changelogs-output-scoped",copy-lines="1-2"}
|
||||
kubectl -n crossplane-system logs -l pkg.crossplane.io/provider=provider-kubernetes -c changelogs-sidecar \
|
||||
| jq '.timestamp + " " + .provider + " " + .kind + " " + .name + " " + .operation'
|
||||
"2025-04-25T08:23:34Z provider-kubernetes:v0.18.0 Object configmap-for-changelogs OPERATION_TYPE_CREATE"
|
||||
```
|
||||
|
||||
### Full lifecycle operations
|
||||
|
||||
In addition to change log entries that record the creation of resources, update
|
||||
and delete operations will also generate corresponding change log entries.
|
||||
|
||||
Update the resource by patching its data field `key-1` with a new value
|
||||
`cooler-value-2`:
|
||||
```shell {label="object-patch",copy-lines="1-2"}
|
||||
kubectl patch object configmap-for-changelogs --type=json \
|
||||
-p='[{"op": "replace", "path": "/spec/forProvider/manifest/data/key-1", "value": "cooler-value-2"}]'
|
||||
object.kubernetes.crossplane.io/configmap-for-changelogs patched
|
||||
```
|
||||
|
||||
Then, delete the object entirely:
|
||||
```shell {label="object-delete",copy-lines="1"}
|
||||
kubectl delete object configmap-for-changelogs
|
||||
object.kubernetes.crossplane.io "configmap-for-changelogs" deleted
|
||||
```
|
||||
|
||||
Check the change logs again to verify that both the update and delete operations
|
||||
were recorded, and the full lifecycle of the object has been captured in the
|
||||
change logs:
|
||||
```shell {label="changelogs-output-final",copy-lines="1-2"}
|
||||
kubectl -n crossplane-system logs -l pkg.crossplane.io/provider=provider-kubernetes -c changelogs-sidecar \
|
||||
| jq '.timestamp + " " + .provider + " " + .kind + " " + .name + " " + .operation'
|
||||
"2025-04-25T08:23:34Z provider-kubernetes:v0.18.0 Object configmap-for-changelogs OPERATION_TYPE_CREATE"
|
||||
"2025-04-25T08:24:21Z provider-kubernetes:v0.18.0 Object configmap-for-changelogs OPERATION_TYPE_UPDATE"
|
||||
"2025-04-25T08:24:25Z provider-kubernetes:v0.18.0 Object configmap-for-changelogs OPERATION_TYPE_DELETE"
|
||||
```
|
||||
Loading…
Reference in New Issue