Crossplane Composition Debugging

Crossplane 组合调试

Debug Crossplane compositions and functions by systematically identifying issues in rendering, function execution, and resource provisioning.

通过系统识别渲染、函数执行和资源供应中的问题，调试Crossplane组合与函数。

Debugging Decision Tree

调试决策树

Issue reported
    |
    v
Do you have composition files locally?
    |
    +--NO--> Extract from cluster first
    |        Run: scripts/extract-composition.sh
    |        See: "Remote Cluster Debugging"
    |
    +--YES--> Is the composition rendering correctly?
                 |
                 +--NO--> Run `crossplane beta render` locally
                 |        See: "Local Render Debugging"
                 |
                 +--YES--> Are resources being created in the cluster?
                              |
                              +--NO--> Check XR/Claim status and events
                              |        Run `crossplane beta trace`
                              |        See: "Cluster Debugging"
                              |
                              +--YES--> Are resources in Ready state?
                                           |
                                           +--NO--> Check managed resource conditions
                                           |        See: "Resource Status Debugging"
                                           |
                                           +--YES--> Issue is external to Crossplane

Issue reported
    |
    v
Do you have composition files locally?
    |
    +--NO--> Extract from cluster first
    |        Run: scripts/extract-composition.sh
    |        See: "Remote Cluster Debugging"
    |
    +--YES--> Is the composition rendering correctly?
                 |
                 +--NO--> Run `crossplane beta render` locally
                 |        See: "Local Render Debugging"
                 |
                 +--YES--> Are resources being created in the cluster?
                              |
                              +--NO--> Check XR/Claim status and events
                              |        Run `crossplane beta trace`
                              |        See: "Cluster Debugging"
                              |
                              +--YES--> Are resources in Ready state?
                                           |
                                           +--NO--> Check managed resource conditions
                                           |        See: "Resource Status Debugging"
                                           |
                                           +--YES--> Issue is external to Crossplane

Remote Cluster Debugging

远程集群调试

When compositions and functions are deployed to a remote cluster and you don't have the source files locally.

当组合和函数部署在远程集群且本地没有源文件时使用。

Quick Extract (Using Script)

快速提取（使用脚本）

Run the extraction script to pull all files needed for local debugging:

bash

undefined

运行提取脚本以拉取本地调试所需的所有文件：

bash

undefined

Extract composition, functions, and sample XR for debugging

./scripts/extract-composition.sh <composition-name> [xr-kind] [xr-name]

Examples:

./scripts/extract-composition.sh my-database-composition ./scripts/extract-composition.sh my-app-composition XMyApp my-app-instance


This creates a `debug-<composition-name>/` directory with all files needed for `crossplane beta render`.

./scripts/extract-composition.sh my-database-composition ./scripts/extract-composition.sh my-app-composition XMyApp my-app-instance


此命令会创建一个`debug-<composition-name>/`目录，包含`crossplane beta render`所需的所有文件。

Manual Extraction

手动提取

1. Extract Composition

1. 提取组合

bash

undefined

bash

undefined

List available compositions

kubectl get compositions

Extract specific composition

kubectl get composition <name> -o yaml > composition.yaml

undefined

kubectl get composition <name> -o yaml > composition.yaml

undefined

2. Extract Function Definitions

2. 提取函数定义

bash

undefined

bash

undefined

List installed functions

kubectl get functions

Extract all functions to single file

kubectl get functions -o yaml > functions.yaml

Or extract specific function

kubectl get function <name> -o yaml >> functions.yaml

undefined

kubectl get function <name> -o yaml >> functions.yaml

undefined

3. Extract Sample XR/Claim

3. 提取示例XR/Claim

bash

undefined

bash

undefined

Find XRs using this composition

kubectl get <xr-kind> -A

Extract an XR as sample input (clean up status for render)

xr.yaml

undefined

xr.yaml

undefined

4. View Inline KCL Code

4. 查看内嵌KCL代码

For compositions with embedded KCL, extract and view the code:

bash

undefined

对于包含内嵌KCL的组合，提取并查看代码：

bash

undefined

View all pipeline steps and their inputs

kubectl get composition <name> -o jsonpath='{.spec.pipeline}' | jq

Extract KCL source from specific step (adjust index [0] as needed)

kubectl get composition <name> -o jsonpath='{.spec.pipeline[0].input.source}'

Pretty print KCL from inline composition

kubectl get composition <name> -o json |
jq -r '.spec.pipeline[] | select(.functionRef.name == "function-kcl") | .input.source'

undefined

kubectl get composition <name> -o json |
jq -r '.spec.pipeline[] | select(.functionRef.name == "function-kcl") | .input.source'

undefined

View Function Logs in Cluster

查看集群中的函数日志

bash

undefined

bash

undefined

Find function pods

kubectl get pods -n crossplane-system -l pkg.crossplane.io/function

Logs for specific function

kubectl logs -n crossplane-system -l pkg.crossplane.io/function=function-kcl -f --tail=100

All function logs

kubectl logs -n crossplane-system -l pkg.crossplane.io/revision --tail=50

undefined

kubectl logs -n crossplane-system -l pkg.crossplane.io/revision --tail=50

undefined

Debug Without Local Functions

无本地函数时调试

If you can't run functions locally, use cluster-side debugging:

bash

undefined

如果无法在本地运行函数，使用集群端调试：

bash

undefined

1. Check function health

kubectl get functions kubectl describe function <name>

2. Check function pod status

kubectl get pods -n crossplane-system -l pkg.crossplane.io/function=<name>

3. View function errors in XR events

kubectl describe <xr-kind> <xr-name> | grep -A5 "Events:"

4. Check crossplane core logs for function errors

kubectl logs -n crossplane-system deploy/crossplane --tail=100 | grep -i function

undefined

kubectl logs -n crossplane-system deploy/crossplane --tail=100 | grep -i function

undefined

Local Render Debugging

本地渲染调试

Use

crossplane beta render

to test composition rendering without applying to cluster.

使用

crossplane beta render

测试组合渲染，无需应用到集群。

Basic Render Command

基础渲染命令

bash

crossplane beta render <xr-file.yaml> <composition.yaml> <functions.yaml>

Required files:

```
xr-file.yaml
```
- Example XR or Claim with spec values
```
composition.yaml
```
- The Composition to test
```
functions.yaml
```
- Function definitions (can combine multiple)

bash

crossplane beta render <xr-file.yaml> <composition.yaml> <functions.yaml>

所需文件：

```
xr-file.yaml
```
- 包含spec值的示例XR或Claim
```
composition.yaml
```
- 要测试的组合
```
functions.yaml
```
- 函数定义（可合并多个）

Functions File for Cluster-Deployed Functions

集群部署函数的函数文件

When functions are in the cluster but not running locally, use

Default

runtime to pull from registry:

yaml

---
apiVersion: pkg.crossplane.io/v1beta1
kind: Function
metadata:
  name: function-kcl
  annotations:
    render.crossplane.io/runtime: Default
---
apiVersion: pkg.crossplane.io/v1beta1
kind: Function
metadata:
  name: function-auto-ready
  annotations:
    render.crossplane.io/runtime: Default

当函数在集群中但未在本地运行时，使用

Default

运行时从镜像仓库拉取：

yaml

---
apiVersion: pkg.crossplane.io/v1beta1
kind: Function
metadata:
  name: function-kcl
  annotations:
    render.crossplane.io/runtime: Default
---
apiVersion: pkg.crossplane.io/v1beta1
kind: Function
metadata:
  name: function-auto-ready
  annotations:
    render.crossplane.io/runtime: Default

Functions File for Local Development

本地开发的函数文件

When running functions locally in Docker:

yaml

---
apiVersion: pkg.crossplane.io/v1beta1
kind: Function
metadata:
  name: function-kcl
  annotations:
    render.crossplane.io/runtime: Development
    render.crossplane.io/runtime-development-target: localhost:9443
---
apiVersion: pkg.crossplane.io/v1beta1
kind: Function
metadata:
  name: function-auto-ready

当在Docker中本地运行函数时：

yaml

---
apiVersion: pkg.crossplane.io/v1beta1
kind: Function
metadata:
  name: function-kcl
  annotations:
    render.crossplane.io/runtime: Development
    render.crossplane.io/runtime-development-target: localhost:9443
---
apiVersion: pkg.crossplane.io/v1beta1
kind: Function
metadata:
  name: function-auto-ready

Running KCL Function Locally

本地运行KCL函数

Start the KCL function in development mode:

bash

undefined

以开发模式启动KCL函数：

bash

undefined

Terminal 1: Run KCL function server

docker run --rm -p 9443:9443 xpkg.upbound.io/crossplane-contrib/function-kcl:latest --insecure --debug


```bash

docker run --rm -p 9443:9443 xpkg.upbound.io/crossplane-contrib/function-kcl:latest --insecure --debug


```bash

Terminal 2: Render with local function

crossplane beta render xr.yaml composition.yaml functions.yaml

undefined

crossplane beta render xr.yaml composition.yaml functions.yaml

undefined

Interpreting Render Output

解读渲染输出

The output shows the desired state after all functions run. Check for:

Missing resources - Function didn't generate expected output
Wrong resource values - Function logic error
Function errors - Check stderr for stack traces

输出显示所有函数运行后的期望状态。检查以下内容：

缺失资源 - 函数未生成预期输出
资源值错误 - 函数逻辑错误
函数错误 - 检查stderr获取堆栈跟踪

Common Render Issues

常见渲染问题

Symptom	Likely Cause	Action
Empty output	Function not matched or no resources generated	Check function name matches pipeline step
KCL syntax error	Invalid KCL in composition	See references/kcl-patterns.md
"function not found"	Function not in functions.yaml	Add function definition
Wrong resource apiVersion	KCL schema mismatch	Update KCL imports

症状	可能原因	操作
空输出	函数未匹配或未生成资源	检查函数名称是否与流水线步骤匹配
KCL语法错误	组合中的KCL无效	查看references/kcl-patterns.md
"function not found"	函数不在functions.yaml中	添加函数定义
资源apiVersion错误	KCL schema不匹配	更新KCL导入

Cluster Debugging

集群调试

Trace Resource Relationships

跟踪资源关系

bash

undefined

bash

undefined

Trace from claim to all managed resources

crossplane beta trace <claim-kind>/<claim-name> -n <namespace>

Trace from XR

crossplane beta trace <xr-kind>/<xr-name>


Output shows the resource tree with status of each resource.

crossplane beta trace <xr-kind>/<xr-name>


输出显示资源树及每个资源的状态。

Check XR Status

检查XR状态

bash

kubectl get <xr-kind> <xr-name> -o yaml

Key fields to inspect:

```
status.conditions
```
- Synced, Ready, and custom conditions
```
status.connectionDetails
```
- Connection secret propagation
```
spec.compositionRef
```
- Which composition is being used
```
spec.resourceRefs
```
- List of composed resources

bash

kubectl get <xr-kind> <xr-name> -o yaml

需检查的关键字段：

```
status.conditions
```
- 已同步、就绪和自定义条件
```
status.connectionDetails
```
- 连接密钥传播
```
spec.compositionRef
```
- 当前使用的组合
```
spec.resourceRefs
```
- 组合资源列表

Check Claim Status

检查Claim状态

bash

kubectl describe <claim-kind> <claim-name> -n <namespace>

Look for:

Events showing errors
```
status.conditions
```
with False values
Missing
```
status.connectionDetails
```

bash

kubectl describe <claim-kind> <claim-name> -n <namespace>

查找以下内容：

显示错误的事件
值为False的
```
status.conditions
```
缺失的
```
status.connectionDetails
```

View Composition Revisions

查看组合修订版本

bash

kubectl get compositionrevision -l crossplane.io/composition-name=<composition-name>

bash

kubectl get compositionrevision -l crossplane.io/composition-name=<composition-name>

Resource Status Debugging

资源状态调试

Check Managed Resource

检查托管资源

bash

kubectl describe <managed-resource-kind> <name>

Key sections:

Conditions: Look for
```
Synced=False
```
or
```
Ready=False
```
Events: Provider-specific errors
Status.AtProvider: Actual state from cloud provider

bash

kubectl describe <managed-resource-kind> <name>

关键部分：

Conditions：查找
```
Synced=False
```
或
```
Ready=False
```
Events：提供商特定错误
Status.AtProvider：来自云提供商的实际状态

Common Managed Resource Issues

常见托管资源问题

Condition	Message Pattern	Cause
Synced=False	"cannot create"	Missing permissions or invalid spec
Synced=False	"rate limit"	API throttling, retry later
Ready=False	"pending"	Resource still provisioning
Ready=False	"failed"	External creation error

条件	消息模式	原因
Synced=False	"cannot create"	权限缺失或spec无效
Synced=False	"rate limit"	API限流，稍后重试
Ready=False	"pending"	资源仍在供应中
Ready=False	"failed"	外部创建错误

Provider Logs

提供商日志

bash

undefined

bash

undefined

Find provider pod

kubectl get pods -n crossplane-system | grep provider

View logs

kubectl logs -n crossplane-system <provider-pod> -f

undefined

kubectl logs -n crossplane-system <provider-pod> -f

undefined

Function-Specific Debugging

特定函数调试

KCL Functions

KCL函数

See references/kcl-patterns.md for:

Common KCL syntax patterns
Reading composite resource inputs
Generating multiple resources
Conditional logic

Quick KCL debugging:

bash

undefined

查看references/kcl-patterns.md获取：

常见KCL语法模式
读取复合资源输入
生成多个资源
条件逻辑

快速KCL调试：

bash

undefined

Extract and validate inline KCL

kubectl get composition <name> -o json |
jq -r '.spec.pipeline[] | select(.functionRef.name == "function-kcl") | .input.source' \

extracted.k kcl extracted.k

kubectl get composition <name> -o json |
jq -r '.spec.pipeline[] | select(.functionRef.name == "function-kcl") | .input.source' \

extracted.k kcl extracted.k

Run with debug output

crossplane beta render xr.yaml composition.yaml functions.yaml 2>&1 | head -100

undefined

crossplane beta render xr.yaml composition.yaml functions.yaml 2>&1 | head -100

undefined

Go Template Functions

Go模板函数

Check template syntax:

Ensure
```
{{ }}
```
delimiters are correct
Verify
```
.observed.composite.resource.spec
```
paths
Check for nil pointer access

检查模板语法：

确保
```
{{ }}
```
分隔符正确
验证
```
.observed.composite.resource.spec
```
路径
检查空指针访问

Patch and Transform

补丁与转换

Common issues:

```
fromFieldPath
```
pointing to non-existent field
```
toFieldPath
```
targeting immutable field
Transform type mismatch

常见问题：

```
fromFieldPath
```
指向不存在的字段
```
toFieldPath
```
指向不可变字段
转换类型不匹配

Auto-Ready Function

自动就绪函数

Must be last in pipeline. Issues:

Not detecting composed resources correctly
Ready condition not propagating

必须位于流水线最后。问题：

未正确检测组合资源
就绪条件未传播

Validation

验证

bash

undefined

bash

undefined

Validate composition against schema

crossplane beta validate <composition.yaml>

Validate with extensions

crossplane beta validate <composition.yaml> --extensions=<extensions-dir>

undefined

crossplane beta validate <composition.yaml> --extensions=<extensions-dir>

undefined

Quick Reference Commands

快速参考命令

bash

undefined

bash

undefined

Remote cluster: Extract for local debugging

kubectl get composition <name> -o yaml > composition.yaml kubectl get functions -o yaml > functions.yaml kubectl get <xr> <name> -o yaml > xr.yaml

Full debugging session

crossplane beta trace <kind>/<name> # See resource tree kubectl get events --field-selector involvedObject.name=<name> # Recent events kubectl get <xr> -o jsonpath='{.status.conditions}' # XR conditions

Function debugging

crossplane beta render xr.yaml comp.yaml funcs.yaml # Local render crossplane beta render xr.yaml comp.yaml funcs.yaml -o json | jq # Parse output

View inline KCL

kubectl get composition <name> -o json | jq -r '.spec.pipeline[].input.source'

Provider debugging

kubectl logs -n crossplane-system deploy/<provider> --tail=100

undefined

kubectl logs -n crossplane-system deploy/<provider> --tail=100

undefined

References

参考资料

references/kcl-patterns.md - KCL syntax patterns for compositions
references/common-errors.md - Error messages and solutions

references/kcl-patterns.md - 组合的KCL语法模式
references/common-errors.md - 错误消息与解决方案

crossplane-debug

Original

Translation

Crossplane Composition Debugging

Crossplane 组合调试

Debugging Decision Tree

调试决策树

Remote Cluster Debugging

远程集群调试

Quick Extract (Using Script)

快速提取（使用脚本）

Extract composition, functions, and sample XR for debugging

Extract composition, functions, and sample XR for debugging

Examples:

Examples:

Manual Extraction

手动提取

1. Extract Composition

1. 提取组合

List available compositions

List available compositions

Extract specific composition

Extract specific composition

2. Extract Function Definitions

2. 提取函数定义

List installed functions

List installed functions

Extract all functions to single file

Extract all functions to single file

Or extract specific function

Or extract specific function

3. Extract Sample XR/Claim

3. 提取示例XR/Claim

Find XRs using this composition

Find XRs using this composition

Extract an XR as sample input (clean up status for render)

Extract an XR as sample input (clean up status for render)

4. View Inline KCL Code

4. 查看内嵌KCL代码

View all pipeline steps and their inputs

View all pipeline steps and their inputs

Extract KCL source from specific step (adjust index [0] as needed)

Extract KCL source from specific step (adjust index [0] as needed)

Pretty print KCL from inline composition

Pretty print KCL from inline composition

View Function Logs in Cluster

查看集群中的函数日志

Find function pods

Find function pods

Logs for specific function

Logs for specific function

All function logs

All function logs

Debug Without Local Functions

无本地函数时调试

1. Check function health

1. Check function health

2. Check function pod status

2. Check function pod status

3. View function errors in XR events

3. View function errors in XR events

4. Check crossplane core logs for function errors

4. Check crossplane core logs for function errors

Local Render Debugging

本地渲染调试

Basic Render Command

基础渲染命令

Functions File for Cluster-Deployed Functions

集群部署函数的函数文件

Functions File for Local Development

本地开发的函数文件

Running KCL Function Locally

本地运行KCL函数

Terminal 1: Run KCL function server

Terminal 1: Run KCL function server

Terminal 2: Render with local function

Terminal 2: Render with local function

Interpreting Render Output

解读渲染输出

Common Render Issues