Crossplane logo
Crossplane logo

Composition 资源

On this page

复合资源将一组托管资源表示为一个 Kubernetes 对象。 当用户访问 CompositeResourceDefinition 中定义的自定义 API 时，crossplane 就会创建复合资源。

Tip
复合资源是托管资源的_组合_，_Composition_定义了如何将托管资源_组合_在一起。

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

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

创建 Composition 资源

创建复合资源需要 Composition 和 [CompositeResourceDefinition](https://crossplane.devops.gold/master/concepts/composite-resource-definitions/Composition 定义了要创建的资源集。 XRD 定义了用户为请求资源集而调用的自定义 API。

Crossplane组件关系图](/media/composition-how-it-works.svg)

XRD 定义了用于创建复合资源的 API。 例如，这个 复合资源定义创建了一个自定义 API 端点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

当用户调用自定义 API 时、xmydatabases.example.org时，Crossplane 会根据 Composition 的的

1apiVersion: apiextensions.crossplane.io/v1
2kind: Composition
3metadata:
4  name: my-composition
5spec:
6  compositeTypeRef:
7    apiVersion: example.org/v1alpha1
8    kind: xMyDatabase
9  # Removed for brevity

Composition 复合类型与 XRD 组和类.

crossplane 会创建匹配的 Composition 中定义的资源，并将它们表示为单一的 “复合 “资源。

1kubectl get composite
2NAME SYNCED READY COMPOSITION AGE
3my-composite-resource True True my-composition 4s

命名外部资源

默认情况下，由复合资源创建的托管资源具有复合资源的名称，后跟一个随机后缀。

例如，名为 “my-composite-resource “的 Composition 资源会创建名为 “my-composite-resource-fqvkw “的外部资源。

资源名称可以通过应用Annotations来确定资源名称。

1apiVersion: example.org/v1alpha1
2kind: xMyDatabase
3metadata:
4  name: my-composite-resource
5  annotations: 
6    crossplane.io/external-name: my-custom-name
7# Removed for brevity

在 Composition 内部，被引用一个补丁将外部名称应用到资源中。

字段路径 字段路径补丁复制了metadata.Annotations字段复制到metadata.annotations字段复制到托管资源内。

Note
如果受管资源具有 “crossplane.io/external-name “注解，则 crossplane 会使用该注解值来命名外部资源。 
 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3metadata:
 4  name: my-composition
 5spec:
 6  resources:
 7    - name: database
 8      base:
 9        # Removed for brevity
10      patches:
11      - fromFieldPath: metadata.annotations
12        toFieldPath: metadata.annotations

有关修补资源的更多信息，请参阅 Patch and Transform 文档。

Composition选择器

为复合资源选择一个特定的 Composition，以便与compositionRef

Important
所选的 Composition 必须允许复合资源使用compositeTypeRef字段。 阅读启用复合资源部分。 
1apiVersion: example.org/v1alpha1
2kind: xMyDatabase
3metadata:
4  name: my-composite-resource
5spec:
6  compositionRef:
7    name: my-other-composition
8  # Removed for brevity

composition资源还可以通过一个composition选择器.

在 matchLabels部分提供一个或多个要匹配的 Composition 标签。

1apiVersion: example.org/v1alpha1
2kind: xMyDatabase
3metadata:
4  name: my-composite-resource
5spec:
6  compositionSelector:
7    matchLabels:
8      environment: production
9  # Removed for brevity

Composition revisions 政策

crossplane 会以 [Composition revisions] 的形式跟踪对 Composition 的修改(https://crossplane.devops.gold/knowledge-base/guides/composition-revisions/) .

复合资源可以被引用一个 compositionUpdatePolicy来手动或自动引用较新的 Composition 修订版本。

默认的compositionUpdatePolicy复合资源会自动被引用最新的 Composition 修订版本。

将政策改为手动以防止 Composition 资源自动升级。

1apiVersion: example.org/v1alpha1
2kind: xMyDatabase
3metadata:
4  name: my-composite-resource
5spec:
6  compositionUpdatePolicy: Manual
7  # Removed for brevity

Composition revisions 选择器

crossplane 会把对 Composition 的修改记录为[Composition revisions](https://crossplane.devops.gold/knowledge-base/guides/composition-revisions/复合资源可选择特定的 Composition 修订版本。

被引用 compositionRevisionRef来按名称选择特定的 Composition Revisions。

例如，要选择特定的 Composition 修订版，请使用所需的 Composition 修订版名称。

1apiVersion: example.org/v1alpha1
2kind: xMyDatabase
3metadata:
4  name: my-composite-resource
5spec:
6  compositionUpdatePolicy: Manual
7  compositionRevisionRef:
8    name: my-composition-b5aa1eb
9  # Removed for brevity
Note

从中查找 Composition 修订版名称kubectl get compositionrevision

1kubectl get compositionrevision
2NAME REVISION XR-KIND XR-APIVERSION AGE
3my-composition-5c976ad 1 xmydatabases example.org/v1alpha1 65m
4my-composition-b5aa1eb 2 xmydatabases example.org/v1alpha1 64m

composition资源还可以通过一个composition修订版选择器.

在 matchLabels部分提供一个或多个要匹配的 Composition 修订标签。

1apiVersion: example.org/v1alpha1
2kind: xMyDatabase
3metadata:
4  name: my-composite-resource
5spec:
6  compositionRevisionSelector:
7    matchLabels:
8      channel: dev
9  # Removed for brevity

管理连接secret

当复合资源创建资源时，Crossplane 会提供任何 connection secrets 提供给 Composition 资源。

Important
资源只能访问 XRD 允许的连接secret。 默认情况下，XRD 允许访问由托管资源生成的所有连接secret。 阅读更多关于管理连接secret 的更多信息，请参阅 XRD 文档。

被引用writeConnectionSecretToRef来指定 Composition 资源向何处写入连接secret。

例如，该 Composition 资源会将连接 secrets 保存在 Kubernetes secret 对象中，该对象名为我的secret的 Kubernetes secret 对象中。crossplane-system.

1apiVersion: example.org/v1alpha1
2kind: xMyDatabase
3metadata:
4  name: my-composite-resource
5spec:
6  writeConnectionSecretToRef:
7    name: my-secret
8    namespace: crossplane-system
9  # Removed for brevity

Composition 资源可将连接secret写入外部secret存储，如 HashiCorp Vault。

Important
外部secret存储是 alpha 功能，默认情况下不启用 alpha 功能。

被引用 字段将连接secret保存到外部secret存储中。字段将连接secret存储到外部secret存储区。

1apiVersion: example.org/v1alpha1
2kind: xMyDatabase
3metadata:
4  name: my-composite-resource
5spec:
6  publishConnectionDetailsTo:
7    name: my-external-secret-store
8  # Removed for brevity

请阅读外部secret存储 文档，了解更多关于使用外部secret存储的信息。

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

暂停 Composition 资源

crossplane 支持暂停复合资源。 暂停的复合资源不会检查或更改其外部资源。

要暂停 Composition 资源，请应用注解。注释。

1apiVersion: example.org/v1alpha1
2kind: xMyDatabase
3metadata:
4  name: my-composite-resource
5  annotations:
6    crossplane.io/paused: "true"
7spec:
8  # Removed for brevity

验证 Composition 资源

被引用kubectl get composite查看所有已创建的 Composition 资源。

1kubectl get composite
2NAME SYNCED READY COMPOSITION AGE
3my-composite-resource True True my-composition 4s

对特定自定义 API 端点使用 kubectl get 仅可查看这些资源。

1kubectl get xMyDatabase.example.org
2NAME SYNCED READY COMPOSITION AGE
3my-composite-resource True True my-composition 12m

被引用kubectl describe composite查看链接的Composition Ref中创建的唯一托管资源。资源引用.

 1kubectl describe composite my-composite-resource
 2Name:         my-composite-resource
 3API Version:  example.org/v1alpha1
 4Kind:         xMyDatabase
 5Spec:
 6  Composition Ref:
 7    Name:  my-composition
 8  Composition Revision Ref:
 9    Name:                     my-composition-cf2d3a7
10  Composition Update Policy:  Automatic
11  Resource Refs:
12    API Version:  s3.aws.upbound.io/v1beta1
13    Kind:         Bucket
14    Name:         my-composite-resource-fmrks
15    API Version:  dynamodb.aws.upbound.io/v1beta1
16    Kind:         Table
17    Name:         my-composite-resource-wnr9t
18# Removed for brevity

综合资源条件

Composition 资源的条件与其 managed 资源的条件相匹配。

详情请阅读托管资源文档中的条件部分 了解详情。

Composition 资源标签

Crossplane 为复合资源添加标签，以显示它们与其他 Crossplane 组件的关系。

composition标签

crossplane 添加了crossplane.io/composite标签。 该标签与composition资源的名称相匹配。 Crossplane 会将composition标签应用到由composition资源创建的任何托管资源，从而在托管资源和拥有composition资源的资源之间创建一个引用。

1kubectl describe xmydatabase.example.org/my-claimed-database-x9rx9
2Name:         my-claimed-database2-x9rx9
3Namespace:
4Labels:       crossplane.io/composite=my-claimed-database-x9rx9

claim名称标签

crossplane 添加了crossplane.io/claim-name标签，该标签表示链接到此复合资源的 claims 的名称。

1kubectl describe xmydatabase.example.org/my-claimed-database-x9rx9
2Name:         my-claimed-database2-x9rx9
3Namespace:
4Labels:       crossplane.io/claim-name=my-claimed-database

直接创建的 Composition 资源不被引用 claim，因此没有crossplane.io/claim-name标签。

claim名称空间标签

crossplane 添加了crossplane.io/claim-namespace标签，以指示与该复合资源链接的 claims 的 namespace。

1kubectl describe xmydatabase.example.org/my-claimed-database-x9rx9
2Name:         my-claimed-database2-x9rx9
3Namespace:
4Labels:       crossplane.io/claim-namespace=default

直接创建的 Composition 资源不被引用 claim，因此没有crossplane.io/claim-namespace标签。