Crossplane logo
Crossplane logo

Composition 资源定义

On this page

Composite resource definitions (XRD)定义了自定义 API 的模式。 用户使用由XRD定义的 API 模式创建 Composite resources (XRs)和 Claims (XCs)。

Note

请阅读 Composition resources 页面，了解有关 Composition 资源的更多信息。

请阅读 Claims 页面获取更多有关claim的信息。

crossplane 有四个核心组件，用户通常会把它们混为一谈:

  • Composition - 用于定义如何创建资源的模板。
  • Composite Resource Definition (XRD) - 本页面。自定义 API 规范。
  • 复合资源 (XR) - 通过使用 Composition Resource Definition 中定义的自定义 API 创建。XRs 使用 Composition 模板来创建新的托管资源。
  • claim (XRC) - 类似于 Composition Resource，但具有名称空间范围。

Crossplane XRD 类似于Kubernetes 自定义资源定义。XRD 需要的字段较少，并添加了与 Crossplane 相关的选项，如 claims 和连接secret。

创建复合资源定义

创建 CompositeResourceDefinition 的步骤包括

CompositeResourceDefinitions 还支持可选项:

Composition 资源定义（“XRD”）可在 Kubernetes 集群内创建新的 API 端点。

创建新的应用程序接口需要定义一个应用程序接口组,名称和版本.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: CompositeResourceDefinition
 3metadata: 
 4  name: xmydatabases.example.org
 5spec:
 6  group: example.org
 7  names:
 8    kind: XMyDatabase
 9    plural: xmydatabases
10  versions:
11  - name: v1alpha1
12  # Removed for brevity

应用 XRD 后，crossplane 会创建一个新的 Kubernetes 自定义资源定义，以匹配所定义的 API。

例如，XRDxmydatabases.example.org创建一个自定义资源定义xmydatabases.example.org.

1kubectl api-resources
2NAME SHORTNAMES APIVERSION NAMESPACED KIND
3xmydatabases.example.org v1alpha1 false xmydatabases
4# Removed for brevity
Warning
您不能更改 XRD组或名称。您必须删除并重新创建 XRD 才能更改组或名称.

XRD 组

groups 定义了相关 API 端点的集合，“group “可以是任何值，但常见的惯例是映射到完全合格的域名。

许多 XRD 可能会被引用相同的 “组 “来创建 API 的逻辑集合。

例如，“数据库 “组可能有 “关系 “和 “nosql “两种。

Tip
组名称具有集群作用域。 选择不与 Providers 冲突的组名称。 避免在组中使用 Provider 名称。

XRD 名称

名称 “字段定义了如何引用此特定 XRD。 所需的名称字段有

  • kind - 调用此 API 时被引用的 kind 值。种类是 UpperCamelCased。crossplane 建议 XRD kinds 以 X 开头，以显示它是自定义的 crossplane API 定义。
  • plural - API URL 被引用的复数名称。复数名称必须小写。
Important

XRD元数据名称必须是复数name, .（点字符）、组.

例如 xmydatabases.example.org匹配 复数名称xmydatabases, .组名称、example.org.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: CompositeResourceDefinition
 3metadata: 
 4  name: xmydatabases.example.org
 5spec:
 6  group: example.org
 7  names:
 8    kind: XMyDatabase
 9    plural: xmydatabases
10    # Removed for brevity

XRD 版本

XRD version 就像Kubernetes 所引用的 API 版本。版本显示了 API 的成熟或稳定程度，并在更改、添加或删除 API 中的字段时递增。

crossplane 并不要求特定的版本或特定的版本命名约定，但强烈建议遵循Kubernetes API 版本指南。

  • v1alpha1 - 随时可能更改的新 API。
  • v1beta1 - 稳定的现有 API。不鼓励进行破坏性更改。
  • v1 - 没有破坏性更改的稳定 API。

定义模式

模式 “定义了参数的名称、参数的数据类型以及哪些参数是必需的，哪些是可选的。

Note
所有 “模式 “都遵循 Kubernetes 自定义资源定义OpenAPIv3 结构模式。

每个版本都有一个独特的模式.

所有 XRD 模式根据 模式进行验证。模式是 OpenAPI对象对象，具有属性属性的模式对象.

在 spec.properties是自定义 API 的定义。

在本例中，关键字 区域是一个 字符串.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: CompositeResourceDefinition
 3metadata:
 4  name: xdatabases.custom-api.example.org
 5spec:
 6  group: custom-api.example.org
 7  names:
 8    kind: xDatabase
 9    plural: xdatabases
10  versions:
11  - name: v1alpha1
12    schema:
13      openAPIV3Schema:
14        type: object
15        properties:
16          spec:
17            type: object
18            properties:
19              region:
20                type: string
21    # Removed for brevity

使用该 API 的 Composition 资源会引用组/版本和种类。的规格有区域键的字符串值。

1apiVersion: custom-api.example.org/v1alpha1
2kind: xDatabase
3metadata:
4  name: my-composite-resource
5spec: 
6  region: "US"
Tip

内定义的自定义应用程序接口spec.properties是 OpenAPIv3 规范。Swagger 文档的 data models page 提供了使用数据类型和输入限制的示例列表。

Kubernetes 文档列出了关于 OpenAPIv3 自定义 API 可以使用的 一组特殊限制。

Important
更改或扩展 XRD 模式需要重新启动 Crossplane pod 才能生效。
必填字段

默认情况下，模式中的所有字段都是可选的。属性属性将参数定义为必填项。

在本例中，X 射线衍射需要区域和尺寸但名称是可选的。

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: CompositeResourceDefinition
 3metadata:
 4  name: xdatabases.custom-api.example.org
 5spec:
 6  group: custom-api.example.org
 7  names:
 8    kind: xDatabase
 9    plural: xdatabases
10  versions:
11  - name: v1alpha1
12    schema:
13      openAPIV3Schema:
14        type: object
15        properties:
16          spec:
17            type: object
18            properties:
19              region:
20                type: string 
21              size:
22                type: string  
23              name:
24                type: string  
25            required: 
26              - region 
27              - size
28    # Removed for brevity

根据 OpenAPIv3 规范，“必要 “字段是按对象设置的。 如果模式包含多个对象，模式可能需要多个 “必要 “字段。

该 XRD 定义了两个对象:

  1. 顶级 对象对象
  2. 第二个 对象对象

规格 规格对象要求的大小和位置但名称是可选的。

所需的 位置对象、国家是是和区为可选项。

 1# Removed for brevity
 2- name: v1alpha1
 3    schema:
 4      openAPIV3Schema:
 5        type: object
 6        properties:
 7          spec:
 8            type: object
 9            properties:
10              size:
11                type: string  
12              name:
13                type: string 
14              location:
15                type: object
16                properties:
17                  country: 
18                    type: string 
19                  zone:
20                    type: string
21                required:
22                  - country
23            required:  
24              - size
25              - location

Swagger “描述参数 “文档中有更多示例。

crossplane 保留字段

crossplane 不允许在模式中使用以下字段:

  • spec.resourceRef 参数
  • spec.resourceRefs参数
  • spec.claimRef spec.writeConnectionSecretToRef.
  • spec.writeConnectionSecretToRef.
  • 状态.条件
  • 状态.连接细节

crossplane 会忽略任何与保留字段匹配的字段。

服务和引用模式

被引用的模式必须是服务: true和可引用: true.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: CompositeResourceDefinition
 3metadata:
 4  name: xdatabases.custom-api.example.org
 5spec:
 6  group: custom-api.example.org
 7  names:
 8    kind: xDatabase
 9    plural: xdatabases
10  versions:
11  - name: v1alpha1
12    served: true
13    referenceable: true
14    schema:
15      openAPIV3Schema:
16        type: object
17        properties:
18          spec:
19            type: object
20            properties:
21              region:
22                type: string

Composition 资源可以使用任何被引用为服务: true。Kubernetes会拒绝任何被引用为 “served: false “的模式版本的复合资源。

Tip
将模式版本设置为 “served:false “会导致使用旧模式的用户出错。 在删除旧模式版本之前，这可以有效地识别和升级用户。

可参考: true referenceable: true字段表示 Composition 使用模式的哪个版本。 只能有一个版本是 “可引用的”。

Note
更改哪个版本为 referenceable:true 需要更新 compositeTypeRef.apiVersion。

多个模式版本

Warning

crossplane 支持定义多个 “版本”，但每个版本的模式不能改变任何现有字段，也称为 “进行破坏性更改”。

要打破不同版本之间的模式变化，需要使用转换 webhooks。

新版本可以定义新的可选参数，但新的必填字段属于 “重大变更”。

crossplane XRD 使用 Kubernetes 自定义资源定义来进行版本控制。请阅读 Kubernetes 文档 versions in CustomResourceDefinitions，了解有关版本和中断更改的更多背景信息。

crossplane 建议将模式更改作为全新的 XRD 来实施。

对于 XRD，要创建新版本的应用程序接口，可添加一个新的名称在版本列表中添加新名称。

例如，该 XRD 版本v1alpha1只有字段区域.

第二个版本v1扩展了应用程序接口，使区域和大小.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: CompositeResourceDefinition
 3metadata:
 4  name: xdatabases.custom-api.example.org
 5spec:
 6  group: custom-api.example.org
 7  names:
 8    kind: xDatabase
 9    plural: xdatabases
10  versions:
11  - name: v1alpha1
12    schema:
13      openAPIV3Schema:
14        type: object
15        properties:
16          spec:
17            type: object
18            properties:
19              region:
20                type: string  
21  - name: v1
22    schema:
23      openAPIV3Schema:
24        type: object
25        properties:
26          spec:
27            type: object
28            properties:
29              region:
30                type: string 
31              size:
32                type: string
Important
更改或扩展 XRD 模式需要重新启动 Crossplane pod 才能生效。

启用claim

作为选项，XRD 可以允许 claims 使用 XRD API。

Note
请阅读 Claims 页面获取更多有关claim的信息。

XRD 为claim提供了一个claim名称对象的claim。

claim名称 名称定义了种类和复数就像 XRD名称也像 XRD名称一样，被引用的种类使用大写，而复数.

claims种类和复数必须是唯一的，不能与任何其他claim或其他 XRD种类.

Tip
常见的 crossplane 惯例是使用claim名称与 XRD名称但不以 “x “开头。 
 1apiVersion: apiextensions.crossplane.io/v1
 2kind: CompositeResourceDefinition
 3metadata:
 4  name: xdatabases.custom-api.example.org
 5spec:
 6  group: custom-api.example.org
 7  names:
 8    kind: xDatabase
 9    plural: xdatabases
10  claimNames:
11    kind: Database
12    plural: databases
13  versions:
14  # Removed for brevity
Important
您不能更改claim名称您必须删除并重新创建 XRD 才能更改claim名称.

管理连接secret

当复合资源创建托管资源时，Crossplane 会提供任何 connection secrets 提供给复合资源或 claims。 这就要求复合资源和 claims 的创建者知道受管资源提供的secret。 在其他情况下，Crossplane 管理员可能不想公开部分或全部生成的连接secret。

XRD 可以定义一个连接秘钥来限制提供给 Compider 资源或 Claim 的内容。

crossplane 只提供连接秘钥（connectionSecretKeys）中列出的密钥。中列出的密钥。中列出的密钥，其他任何连接secret都不会被引用到复合资源或 claims。

Important

中列出的密钥连接密钥中列出的密钥名称必须与 Composition 的 “connectionDetails “中列出的密钥名称一致。

XRD 会忽略列出的任何非托管资源创建的键。

更多信息，请阅读 Composition documentation.

例如，XRD 传递的键是用户名,密码和地址.

Composition 资源或 claims 会将这些内容保存在由其 writeConnectionSecretToRef 字段定义的 secret 中。

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: CompositeResourceDefinition
 3metadata:
 4  name: xdatabases.custom-api.example.org
 5spec:
 6  group: custom-api.example.org
 7  names:
 8    kind: xDatabase
 9    plural: xdatabases
10  connectionSecretKeys:
11    - username
12    - password
13    - address
14  versions:
15  # Removed for brevity
Warning
您不能更改 XRD 的 “connectionSecretKeys”，必须删除并重新创建 XRD 才能更改 “connectionSecretKeys”。

有关连接secret的更多信息，请阅读连接secret知识库文章.

设置 Composition 资源默认值

XRD 可以为 Composition 资源和claim设置默认参数。

defaultCompositeDeletePolicy

如果用户在创建claim时没有指定值，“defaultCompositeDeletePolicy “会定义claim的 “compositeDeletePolicy “属性的默认值。 claim控制器会使用 “compositeDeletePolicy “属性来指定删除关联composition时的传播策略。 compositeDeletePolicy “不适用于没有关联claim的独立composition。

使用 “defaultCompositeDeletePolicy: Background “策略会使claim的 CRD 的 “compositeDeletePolicy “属性的默认值为 “Background”。 当删除的claim的 “compositeDeletePolicy “属性设置为 “Background “时，claim控制器会使用传播策略 “background “删除复合资源并返回，依靠 Kubernetes 删除剩余的子对象，如托管资源、嵌套的复合资源和secret。

使用 defaultCompositeDeletePolicy: Foreground 会使claim的 CRD 具有 compositeDeletePolicy 的默认值 Foreground。 当删除的claim的 compositeDeletePolicy 属性设置为 Foreground时，控制器会使用传播策略 foreground 删除相关的 Composition。 这会导致 Kubernetes 使用前台级联删除，即在删除父资源之前删除所有子资源。 claim控制器会等待 Composition 删除完成后再返回。

在创建claim时，用户可以通过包含具有 “Background “或 “Foreground “值的 “spec.compositeDeletePolicy “属性来覆盖 “defaultCompositeDeletePolicy”。

默认值为 defaultCompositeDeletePolicy: Background。

设置defaultCompositeDeletePolicy: Foreground来更改 XRD 删除策略。

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: CompositeResourceDefinition
 3metadata:
 4  name: xdatabases.custom-api.example.org
 5spec:
 6  defaultCompositeDeletePolicy: Foreground
 7  group: custom-api.example.org
 8  names:
 9  # Removed for brevity
10  versions:
11  # Removed for brevity

defaultCompositionRef

多个 [Composition](https://crossplane.devops.gold/master/concepts/compositions/如果有多个 Composition 引用同一个 XRD，复合资源或 claims 必须选择使用哪个 Composition。

XRD 可以使用 defaultCompositionRef 值定义要使用的默认 Composition。

设置一个defaultCompositionRef以设置默认 Composition。

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: CompositeResourceDefinition
 3metadata:
 4  name: xdatabases.custom-api.example.org
 5spec:
 6  defaultCompositionRef: 
 7    name: myComposition
 8  group: custom-api.example.org
 9  names:
10  # Removed for brevity
11  versions:
12  # Removed for brevity

defaultCompositionUpdatePolicy

对 Composition 的更改会生成新的 Composition 修订版。 默认情况下，所有复合资源和claim都会被引用更新后的 Composition 修订版。

将 XRD 的 “defaultCompositionUpdatePolicy “设置为 “Manual”，以防止composition资源和 claims 自动被引用新修订。

默认值为 defaultCompositionUpdatePolicy: Automatic。

设置 defaultCompositionUpdatePolicy: Manual可为被引用此 XRD 的复合资源和 claims 设置默认的 Composition 更新策略。

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: CompositeResourceDefinition
 3metadata:
 4  name: xdatabases.custom-api.example.org
 5spec:
 6  defaultCompositionUpdatePolicy: Manual
 7  group: custom-api.example.org
 8  names:
 9  # Removed for brevity
10  versions:
11  # Removed for brevity

enforcedCompositionRef

要要求所有复合资源或 claims 使用特定 Composition，请使用 XRD 中的 “enforcedCompositionRef “设置。

例如，要求使用该 XRD 的所有复合资源和claim都使用 Composition我的composition设置enforcedCompositionRef.name: myComposition.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: CompositeResourceDefinition
 3metadata:
 4  name: xdatabases.custom-api.example.org
 5spec:
 6  enforcedCompositionRef: 
 7    name: myComposition
 8  group: custom-api.example.org
 9  names:
10  # Removed for brevity
11  versions:
12  # Removed for brevity

验证复合资源定义

使用 kubectl get compositeresourcedefinition 或简写形式验证 XRD、kubectl get xrd.

1kubectl get xrd                                
2NAME ESTABLISHED OFFERED AGE
3xdatabases.custom-api.example.org True True 22m

ESTABLISHED “字段表示 crossplane 为该 XRD 安装了 Kubernetes 自定义资源定义。

OFFERED “字段表示该 XRD 提供了一个 claims，并且 crossplane 为该 Claim 安装了 Kubernetes 自定义资源定义。

XRD 条件

crossplane 对 XRD 使用一套标准的 “Conditions”（条件）。 使用 “kubectl describe xrd “查看 XRD 的 “Status”（状态）下的条件。

 1kubectl describe xrd
 2Name:         xpostgresqlinstances.database.starter.org
 3API Version:  apiextensions.crossplane.io/v1
 4Kind:         CompositeResourceDefinition
 5# Removed for brevity
 6Status:
 7  Conditions:
 8    Reason:                WatchingCompositeResource
 9    Status:                True
10    Type:                  Established
11    Reason:                WatchingCompositeResourceClaim
12    Status:                True
13    Type:                  Offered
14# Removed for brevity

WatchingCompositeResource

Reason: WatchingCompositeResource 表示 crossplane 定义了与 Composite 资源相关的新 Kubernetes 自定义资源定义，并正在观察新 Composite 资源的创建。

1Type: Established
2Status: True
3Reason: WatchingCompositeResource

终止复合资源

Reason: TerminatingCompositeResource “表示 crossplane 正在删除与 Composite 资源相关的自定义资源定义，并正在终止 Composite 资源控制器。

1Type: Established
2Status: False
3Reason: TerminatingCompositeResource

WatchingCompositeResourceClaim

Reason: WatchingCompositeResourceClaim 表示 crossplane 定义了与所提供的 Claims 相关的新 Kubernetes 自定义资源定义，并正在观察新 Claims 的创建。

1Type: Offered
2Status: True
3Reason: WatchingCompositeResourceClaim

TerminatingCompositeResourceClaim

Reason: TerminatingCompositeResourceClaim “表示 crossplane 正在删除与提供的claim相关的自定义资源定义，并终止claim控制器。

1Type: Offered
2Status: False
3Reason: TerminatingCompositeResourceClaim