Composition에서 연결 정보(Connection Details) 노출하기

원문 보기 위키 갱신 2026.10.03

Composition에서 연결 정보(Connection Details) 노출하기 (Connection Details Composition)

이 가이드는 복합 리소스(XR)의 연결 정보(connection details)를 노출하는 방법을 보여 줍니다. 복합 리소스는 여러 리소스를 구성(compose)할 수 있기 때문에 노출하는 연결 정보는 종종 구성된 리소스(composed resources)들의 연결 정보를 합친 집계(aggregate) 형태가 됩니다.

출처: 문서

본문

권장하는 방법은 Composition에 쿠버네티스 Secret 리소스를 포함하여 다른 리소스들의 연결 정보를 집계하고 XR을 위해 노출하는 것입니다.

참고 Crossplane v1은 XR을 위한 연결 정보를 자동으로 생성하는 기능을 포함했습니다. Crossplane v2는 이 기능을 XR에 대해서만 제거합니다. 관리 리소스(MR)는 이 변경의 영향을 받지 않으며 여전히 writeConnectionSecretToRef 필드를 통해 연결 정보를 지원합니다.

Crossplane v1에서 XR 연결 정보를 지정하는 방법에 대해 더 알아보려면 v1 connection details 문서 페이지를 참고하세요.

예시 개요 (Example overview)

이 가이드는 UserAccessKey 복합 리소스를 생성하여 복합 리소스가 연결 정보를 노출하는 방법을 보여 줍니다. 이 XR은 여러 액세스 키를 가진 AWS IAM 사용자를 나타냅니다.

사용자가 UserAccessKey를 생성하면 크로스플레인은 AWS에 IAM User와 두 개의 AccessKeys를 프로비저닝합니다. 각 AccessKey는 username과 password 같은 자체 연결 정보를 생성합니다. UserAccessKey는 또한 composed resources의 집계된 연결 정보를 노출하는 Secret 리소스를 구성하여, 사용자와 애플리케이션이 그것을 소비할 수 있게 합니다.

UserAccessKey XR 예시는 다음과 같습니다.

apiVersion: example.org/v1alpha1
kind: UserAccessKey
metadata:
  namespace: default
  name: my-keys

배후에서 크로스플레인은:

AWS IAM User와 두 개의 AccessKeys(composed resources)를 생성합니다.
두 AccessKeys의 연결 정보를 수집합니다.
그것들을 Secret에서 UserAccessKey의 연결 정보로 노출합니다.

복합 리소스의 연결 정보 Secret은 다음과 같습니다.

apiVersion: v1
kind: Secret
metadata:
  namespace: default
  name: my-keys-connection-details
data:
  user-0: 
  password-0: 
  user-1: 
  password-1:

사용자와 애플리케이션은 이 Secret을 읽어 UserAccessKey 연결 정보를 소비할 수 있습니다.

팁 이 가이드의 패턴은 연결 정보를 노출해야 하는 모든 복합 리소스에 적용됩니다. 예를 들어:

데이터베이스 연결 문자열과 자격 증명

클러스터 클라이언트 인증서와 키 데이터

서비스와 ingress의 애플리케이션 엔드포인트

사전 요구 사항 (Prerequisites)

이 가이드에는 다음이 필요합니다.

쿠버네티스 클러스터
쿠버네티스 클러스터에 설치된 크로스플레인
자격 증명과 함께 설치·구성된 provider-aws-iam

팁 AWS 프로바이더를 설정하려면 Get Started with Managed Resources 가이드를 따르되, provider provider-aws-iam:v2.3.0을 사용하세요. 프로바이더 설치와 자격 증명 구성 단계를 완료한 후 이 가이드로 돌아오세요.

복합 리소스 빌드 (Build the composite resource)

연결 정보를 노출하는 복합 리소스를 만들려면 다음 단계를 따르세요.

복합 리소스의 스키마 정의
사용할 Composition 함수 설치
Composition이 연결 정보를 노출하는 방법 구성

이 단계를 완료한 후 복합 리소스를 사용할 수 있습니다.

스키마 정의 (Define the schema)

CompositeResourceDefinition(XRD)은 복합 리소스를 정의합니다.

이 예시에서는 UserAccessKey 복합 리소스에 대한 XRD를 만듭니다.

apiVersion: apiextensions.crossplane.io/v2
kind: CompositeResourceDefinition
metadata:
  name: useraccesskeys.example.org
spec:
  group: example.org
  names:
    kind: UserAccessKey
    plural: useraccesskeys
  scope: Namespaced
  versions:
  - name: v1alpha1
    served: true
    referenceable: true
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              writeConnectionSecretToRef:
                type: object
                properties:
                  name:
                    type: string

kubectl apply -f https://docs.crossplane.io/latest/manifests/guides/connection-details-composition/xrd.yaml

팁 이 XRD 스키마는 사용자가 XR 연결 정보 secret의 이름을 선택적으로 설정할 수 있게 해 주는 .spec.writeConnectionSecretToRef.name 필드를 정의합니다. Cluster 범위 XRD의 경우 .spec.writeConnectionSecretToRef.namespace 필드를 추가하여 사용자가 secret의 네임스페이스도 지정할 수 있게 할 수 있습니다.

이제 쿠버네티스 API가 UserAccessKey 복합 리소스에 대한 요청을 서비스합니다.

함수 설치 (Install the function)

Composition 함수는 리소스를 구성하고 연결 정보를 노출하는 데 도움이 되는 일반적인 기능을 제공합니다. 이 가이드는 여러 함수로 연결 정보를 구성하는 방법을 보여 줍니다. 아래 탭에서 사용할 언어를 선택하세요.

YAML — YAML 지원을 설치하려면 이 Composition 함수를 만드세요.

apiVersion: pkg.crossplane.io/v1
kind: Function
metadata:
  name: function-patch-and-transform
spec:
  package: xpkg.crossplane.io/crossplane-contrib/function-patch-and-transform:v0.10.0

kubectl apply -f https://docs.crossplane.io/latest/manifests/guides/connection-details-composition/fn-patch-and-transform.yaml

크로스플레인이 함수를 설치했는지 확인하세요.

kubectl get -f https://docs.crossplane.io/latest/manifests/guides/connection-details-composition/fn-patch-and-transform.yaml
NAME                              INSTALLED   HEALTHY   PACKAGE                                                                      AGE
function-patch-and-transform      True        True      xpkg.crossplane.io/crossplane-contrib/function-patch-and-transform:v0.10.0   8s

Templated YAML — Helm 차트 작성에 익숙하다면 Templated YAML이 좋은 선택입니다. 템플릿 YAML 지원을 설치하려면 이 Composition 함수를 만드세요.

apiVersion: pkg.crossplane.io/v1
kind: Function
metadata:
  name: function-go-templating
spec:
  package: xpkg.crossplane.io/crossplane-contrib/function-go-templating:v0.11.2

kubectl apply -f https://docs.crossplane.io/latest/manifests/guides/connection-details-composition/fn-go-templating.yaml

kubectl get -f https://docs.crossplane.io/latest/manifests/guides/connection-details-composition/fn-go-templating.yaml
NAME                     INSTALLED   HEALTHY   PACKAGE                                                                AGE
function-go-templating   True        True      xpkg.crossplane.io/crossplane-contrib/function-go-templating:v0.11.2   15s

Python — Python 지원을 설치하려면 이 Composition 함수를 만드세요.

apiVersion: pkg.crossplane.io/v1
kind: Function
metadata:
  name: function-python
spec:
  package: xpkg.crossplane.io/crossplane-contrib/function-python:v0.2.0

kubectl apply -f https://docs.crossplane.io/latest/manifests/guides/connection-details-composition/fn-python.yaml

kubectl get -f https://docs.crossplane.io/latest/manifests/guides/connection-details-composition/fn-python.yaml
NAME                                 INSTALLED   HEALTHY   PACKAGE                                                        AGE
function-python                      True        True      xpkg.crossplane.io/crossplane-contrib/function-python:v0.2.0   12s

KCL — KCL 지원을 설치하려면 이 Composition 함수를 만드세요.

apiVersion: pkg.crossplane.io/v1
kind: Function
metadata:
  name: function-kcl
spec:
  package: xpkg.crossplane.io/crossplane-contrib/function-kcl:v0.11.6

kubectl apply -f https://docs.crossplane.io/latest/manifests/guides/connection-details-composition/fn-kcl.yaml

kubectl get -f https://docs.crossplane.io/latest/manifests/guides/connection-details-composition/fn-kcl.yaml
NAME                              INSTALLED   HEALTHY   PACKAGE                                                      AGE
function-kcl                      True        True      xpkg.crossplane.io/crossplane-contrib/function-kcl:v0.11.6   6s

Pythonic — Pythonic(https://github.com/crossplane-contrib/function-pythonic) 지원을 설치하려면 이 Composition 함수를 만드세요.

apiVersion: pkg.crossplane.io/v1
kind: Function
metadata:
  name: function-pythonic
spec:
  package: xpkg.crossplane.io/crossplane-contrib/function-pythonic:v0.3.0

kubectl apply -f https://docs.crossplane.io/latest/manifests/guides/connection-details-composition/fn-pythonic.yaml

kubectl get -f https://docs.crossplane.io/latest/manifests/guides/connection-details-composition/fn-pythonic.yaml
NAME               INSTALLED  HEALTHY  PACKAGE                                                         AGE
function-pythonic  True       True     xpkg.crossplane.io/crossplane-contrib/function-pythonic:v0.3.0  1m

이 가이드는 또한 function-auto-ready를 사용합니다. 이 함수는 composed resources가 건강할 때 자동으로 ready로 표시합니다.

apiVersion: pkg.crossplane.io/v1
kind: Function
metadata:
  name: function-auto-ready
spec:
  package: xpkg.crossplane.io/crossplane-contrib/function-auto-ready:v0.6.0

kubectl apply -f https://docs.crossplane.io/latest/manifests/guides/connection-details-composition/fn-auto-ready.yaml

Composition 구성 (Configure the composition)

Composition은 복합 리소스에 대한 리소스 구성 방법을 크로스플레인에 알려줍니다. 이 가이드는 또한 복합 리소스의 연결 정보를 노출하기 위한 composed Secret 리소스를 포함합니다.

일반적인 패턴은:

Composed resources가 자신의 연결 정보를 개별 Secrets에 씁니다.
Composition이 함수 실행 시 그 연결 정보를 읽습니다.
Composition이 XR을 위한 집계된 연결 정보를 나타내는 composed Secret을 만듭니다.

팁 복합 리소스의 연결 정보 secret은 원하는 모든 데이터를 포함할 수 있고 필요에 따라 변환할 수 있습니다. 관리 리소스의 연결 정보에만 국한되지 않습니다. ConfigMaps나 Services 같은 임의의 쿠버네티스 리소스를 포함한 모든 composed resource의 데이터를 포함할 수 있습니다.

UserAccessKey 복합 리소스에 대한 연결 정보를 노출하는 Composition을 만듭니다.

이 예시에서 Composition은 두 개의 AccessKey 관리 리소스를 생성하고 그 자격 증명을 복합 리소스의 연결 정보 Secret으로 노출합니다.

YAML:

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
  name: useraccesskeys-patch-and-transform
spec:
  compositeTypeRef:
    apiVersion: example.org/v1alpha1
    kind: UserAccessKey
  mode: Pipeline
  pipeline:
  - step: patch-and-transform
    functionRef:
      name: function-patch-and-transform
    input:
      apiVersion: pt.fn.crossplane.io/v1beta1
      kind: Resources
      writeConnectionSecretToRef:
        patches:
        - type: FromCompositeFieldPath
          fromFieldPath: spec.writeConnectionSecretToRef.name
          toFieldPath: name
      resources:
      - name: user
        base:
          apiVersion: iam.aws.m.upbound.io/v1beta1
          kind: User
          spec:
            forProvider: {}
      - name: accesskey-0
        base:
          apiVersion: iam.aws.m.upbound.io/v1beta1
          kind: AccessKey
          spec:
            forProvider:
              userSelector:
                matchControllerRef: true
            writeConnectionSecretToRef:
              name: accesskey-secret-0
        connectionDetails:
        - name: user-0
          type: FromConnectionSecretKey
          fromConnectionSecretKey: username
        - name: password-0
          type: FromConnectionSecretKey
          fromConnectionSecretKey: password
        patches:
        - type: FromCompositeFieldPath
          fromFieldPath: metadata.name
          toFieldPath: spec.writeConnectionSecretToRef.name
          transforms:
          - type: string
            string:
              type: Format
              fmt: "%s-accesskey-secret-0"
      - name: accesskey-1
        base:
          apiVersion: iam.aws.m.upbound.io/v1beta1
          kind: AccessKey
          spec:
            forProvider:
              userSelector:
                matchControllerRef: true
            writeConnectionSecretToRef:
              name: accesskey-secret-1
        connectionDetails:
        - name: user-1
          type: FromConnectionSecretKey
          fromConnectionSecretKey: username
        - name: password-1
          type: FromConnectionSecretKey
          fromConnectionSecretKey: password
        patches:
        - type: FromCompositeFieldPath
          fromFieldPath: metadata.name
          toFieldPath: spec.writeConnectionSecretToRef.name
          transforms:
          - type: string
            string:
              type: Format
              fmt: "%s-accesskey-secret-1"
  - step: ready
    functionRef:
      name: function-auto-ready

kubectl apply -f https://docs.crossplane.io/latest/manifests/guides/connection-details-composition/composition-patch-and-transform.yaml