Red Hat Summit Red Hat Summit지원콘솔개발자평가판 시작연락처

11.2. 클러스터 API 시작하기

Machine API와 Cluster API는 유사한 리소스를 가진 별도의 API 그룹입니다. 이러한 API 그룹을 사용하면 OpenShift Container Platform 클러스터의 인프라 리소스 관리를 자동화할 수 있습니다.

중요

클러스터 API를 사용하여 머신을 관리하는 것은 기술 프리뷰 기능만 해당합니다. 기술 프리뷰 기능은 Red Hat 프로덕션 서비스 수준 계약(SLA)에서 지원되지 않으며 기능적으로 완전하지 않을 수 있습니다. 따라서 프로덕션 환경에서 사용하는 것은 권장하지 않습니다. 이러한 기능을 사용하면 향후 제품 기능을 조기에 이용할 수 있어 개발 과정에서 고객이 기능을 테스트하고 피드백을 제공할 수 있습니다.

Red Hat 기술 프리뷰 기능의 지원 범위에 대한 자세한 내용은 기술 프리뷰 기능 지원 범위를 참조하십시오.

3개의 제어 평면 노드, 3개의 컴퓨팅 노드가 있고 기본 구성 옵션을 사용하는 표준 OpenShift Container Platform 클러스터를 설치하는 경우 설치 프로그램은 openshift-machine-api 네임스페이스에 다음 인프라 리소스를 프로비저닝합니다.

  • 3개의 컨트롤 플레인 머신을 관리하는 하나의 컨트롤 플레인 머신 세트입니다.
  • 3개의 컴퓨팅 머신을 관리하는 하나 이상의 컴퓨팅 머신 세트입니다.
  • 스팟 인스턴스를 관리하는 하나의 머신 상태 점검입니다.

클러스터 API를 사용하여 인프라 리소스를 관리할 수 있는 클러스터를 설치하면 설치 프로그램은 openshift-cluster-api 네임스페이스에 다음 리소스를 프로비저닝합니다.

  • 하나의 클러스터 리소스.
  • 하나의 공급자별 인프라 클러스터 리소스.

머신 API 리소스를 클러스터 API 리소스로 마이그레이션하는 기능을 지원하는 클러스터에서는 양방향 동기화 컨트롤러가 이러한 기본 리소스를 자동으로 생성합니다. 자세한 내용은 머신 API 리소스를 클러스터 API 리소스로 마이그레이션을 참조하세요.

11.2.1. Cluster API 기본 리소스 생성
링크 복사

머신 API 리소스를 클러스터 API 리소스로 마이그레이션하는 것을 지원하지 않는 클러스터의 경우 openshift-cluster-api 네임스페이스에서 다음 클러스터 API 리소스를 수동으로 만들어야 합니다.

  • 컴퓨팅 머신 세트에 해당하는 하나 이상의 머신 템플릿입니다.
  • 3개의 컴퓨팅 머신을 관리하는 하나 이상의 컴퓨팅 머신 세트입니다.

11.2.1.1. 클러스터 API 머신 템플릿 생성
링크 복사

YAML 매니페스트 파일을 생성하고 OpenShift CLI(oc)로 적용하여 공급자별 머신 템플릿 리소스를 생성할 수 있습니다.

사전 요구 사항

  • OpenShift Container Platform 클러스터를 배포했습니다.
  • 클러스터 API 사용을 활성화했습니다.
  • cluster-admin 권한이 있는 계정을 사용하여 ROSA 클러스터에 액세스할 수 있습니다.
  • OpenShift CLI(oc)가 설치되어 있습니다.

프로세스

  1. 다음과 유사한 YAML 파일을 생성합니다. 이 절차에서는 & lt;machine_template_resource_file>.yaml 을 예제 파일 이름으로 사용합니다. 

    apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: <machine_template_kind>
    1 
    
metadata:
  name: <template_name>
    2 
    
  namespace: openshift-cluster-api
spec:
  template:
    spec:
    3
    Copy to Clipboard Toggle word wrap
    1
    머신 템플릿 유형을 지정합니다. 이 값은 플랫폼의 값과 일치해야 합니다. 다음 값이 유효합니다.
    Expand
    클러스터 인프라 공급자현재의

    AWS(Amazon Web Services)

    AWSMachineTemplate

    GCP(Google Cloud Platform)

    GCPMachineTemplate

    Microsoft Azure

    AzureMachineTemplate

    Red Hat OpenStack Platform (RHOSP)

    OpenStackMachineTemplate

    VMware vSphere

    VSphereMachineTemplate

    베어 메탈

    Metal3MachineTemplate

    2
    머신 템플릿의 이름을 지정합니다.
    3
    환경에 대한 세부 정보를 지정합니다. 이러한 매개변수는 공급자별로 다릅니다. 자세한 내용은 공급자의 샘플 Cluster API 머신 템플릿 YAML을 참조하십시오.

  2. 다음 명령을 실행하여 머신 템플릿 CR을 생성합니다. 

    $ oc create -f <machine_template_resource_file>.yaml
    Copy to Clipboard Toggle word wrap

검증

  • 다음 명령을 실행하여 머신 템플릿 CR이 생성되었는지 확인합니다. 

    $ oc get <machine_template_kind> -n openshift-cluster-api
    Copy to Clipboard Toggle word wrap

    여기서 <machine_template_kind >는 플랫폼에 해당하는 값입니다.

    출력 예

    NAME              AGE
<template_name>   77m
    Copy to Clipboard Toggle word wrap

11.2.1.2. 클러스터 API 컴퓨팅 머신 세트 생성
링크 복사

Cluster API를 사용하여 선택한 특정 워크로드에 대한 머신 컴퓨팅 리소스를 동적으로 관리하는 컴퓨팅 머신 세트를 생성할 수 있습니다.

사전 요구 사항

  • OpenShift Container Platform 클러스터를 배포했습니다.
  • 클러스터 API 사용을 활성화했습니다.
  • cluster-admin 권한이 있는 계정을 사용하여 ROSA 클러스터에 액세스할 수 있습니다.
  • OpenShift CLI(oc)가 설치되어 있습니다.
  • 머신 템플릿 리소스가 생성되어 있습니다.

프로세스

  1. 다음과 유사한 YAML 파일을 생성합니다. 이 절차에서는 & lt;machine_set_resource_file>.yaml 을 예제 파일 이름으로 사용합니다. 

    apiVersion: cluster.x-k8s.io/v1beta1
kind: MachineSet
metadata:
  name: <machine_set_name>
    1 
    
  namespace: openshift-cluster-api
spec:
  clusterName: <cluster_name>
    2 
    
  replicas: 1
  selector:
    matchLabels:
      test: example
  template:
    metadata:
      labels:
        test: example
    spec:
    3 
    
# ...
    Copy to Clipboard Toggle word wrap
    1
    컴퓨팅 머신 세트의 이름을 지정합니다. 클러스터 ID, 머신 역할 및 리전은 < cluster_name>-<role>-<region > 형식으로 이 값에 대한 일반적인 패턴을 형성합니다.
    2
    클러스터 이름을 지정합니다. 다음 명령을 실행하여 클러스터 ID의 값을 가져옵니다. 
    $  oc get infrastructure cluster \
   -o jsonpath='{.status.infrastructureName}'
    Copy to Clipboard Toggle word wrap
    3
    환경에 대한 세부 정보를 지정합니다. 이러한 매개변수는 공급자별로 다릅니다. 자세한 내용은 공급자의 샘플 Cluster API 컴퓨팅 머신 세트 YAML을 참조하십시오.

  2. 다음 명령을 실행하여 컴퓨팅 머신 세트 CR을 생성합니다. 

    $ oc create -f <machine_set_resource_file>.yaml
    Copy to Clipboard Toggle word wrap

  3. 다음 명령을 실행하여 컴퓨팅 머신 세트 CR이 생성되었는지 확인합니다. 

    $ oc get machineset.cluster.x-k8s.io -n openshift-cluster-api
    Copy to Clipboard Toggle word wrap

    출력 예

    NAME                 CLUSTER          REPLICAS   READY   AVAILABLE   AGE   VERSION
<machine_set_name>   <cluster_name>   1          1       1           17m
    Copy to Clipboard Toggle word wrap

    새 컴퓨팅 머신 세트가 사용 가능한 경우 REPLICAS 및 AVAILABLE 값이 일치합니다. 컴퓨팅 머신 세트를 사용할 수 없는 경우 몇 분 기다렸다가 명령을 다시 실행합니다.

검증

  • 컴퓨팅 머신 세트가 필수 구성에 따라 시스템을 생성하고 있는지 확인하려면 다음 명령을 실행하여 클러스터의 시스템 및 노드 목록을 검토합니다.

    • 클러스터 API 머신 목록을 확인합니다. 

      $ oc get machine.cluster.x-k8s.io -n openshift-cluster-api
      Copy to Clipboard Toggle word wrap

      출력 예

      NAME                             CLUSTER          NODENAME                                 PROVIDERID      PHASE     AGE     VERSION
<machine_set_name>-<string_id>   <cluster_name>   <ip_address>.<region>.compute.internal   <provider_id>   Running   8m23s
      Copy to Clipboard Toggle word wrap

    • 노드 목록을 확인합니다. 

      $ oc get node
      Copy to Clipboard Toggle word wrap

      출력 예

      NAME                                       STATUS   ROLES    AGE     VERSION
<ip_address_1>.<region>.compute.internal   Ready    worker   5h14m   v1.28.5
<ip_address_2>.<region>.compute.internal   Ready    master   5h19m   v1.28.5
<ip_address_3>.<region>.compute.internal   Ready    worker   7m      v1.28.5
      Copy to Clipboard Toggle word wrap

11.2.2. 머신 API 리소스를 클러스터 API 리소스로 마이그레이션
링크 복사

Machine API 리소스를 Cluster API 리소스로 마이그레이션하는 것을 지원하는 클러스터에서 양방향 동기화 컨트롤러는 openshift-cluster-api 네임스페이스에 다음 Cluster API 리소스를 생성합니다.

  • 컴퓨팅 머신 세트에 해당하는 하나 이상의 머신 템플릿입니다.
  • 3개의 컴퓨팅 머신을 관리하는 하나 이상의 컴퓨팅 머신 세트입니다.
  • 각 Machine API 컴퓨팅 머신에 해당하는 하나 이상의 Cluster API 컴퓨팅 머신입니다.
참고

양방향 동기화 컨트롤러는 TechPreviewNoUpgrade 기능 세트의 MachineAPIMigration 기능 게이트가 활성화된 클러스터에서만 작동합니다.

이러한 클러스터 API 리소스는 기본 구성 옵션을 사용하는 클러스터에 대한 openshift-machine-api 네임스페이스에서 설치 프로그램이 제공하는 리소스에 해당합니다. 클러스터 API 리소스는 머신 API 리소스와 동일한 이름을 가지며 리소스를 나열하는 oc get 등의 명령 출력에 나타납니다. 동기화 컨트롤러는 의도치 않은 조정을 방지하기 위해 클러스터 API 리소스를 프로비저닝되지 않은( 일시 중지 ) 상태로 만듭니다.

지원되는 구성의 경우, 어떤 API가 권위 있는 것으로 간주되는지를 변경하여 머신 API 리소스를 동등한 클러스터 API 리소스로 마이그레이션할 수 있습니다. 머신 API 리소스를 클러스터 API로 마이그레이션하면 리소스 관리도 클러스터 API로 이전됩니다.

클러스터 API를 사용하도록 머신 API 리소스를 마이그레이션하면 프로덕션 클러스터에서 클러스터 API를 사용하기로 결정하기 전에 모든 것이 예상대로 작동하는지 확인할 수 있습니다. 머신 API 리소스를 동등한 클러스터 API 리소스로 마이그레이션한 후에는 새 리소스를 검사하여 기능과 구성이 원래 머신 API 리소스와 일치하는지 확인할 수 있습니다.

컴퓨팅 머신 세트에 대한 권한 있는 API를 변경하면 해당 컴퓨팅 머신 세트가 관리하는 기존 컴퓨팅 머신은 원래 권한 있는 API를 그대로 유지합니다. 결과적으로, 서로 다른 권한 있는 API를 사용하는 머신을 관리하는 컴퓨팅 머신 세트는 이러한 API 유형 간 마이그레이션을 지원하는 클러스터에서 유효하고 예상되는 현상입니다.

컴퓨팅 머신의 권한 있는 API를 변경하는 경우 해당 머신을 지원하는 기본 인프라의 인스턴스는 다시 생성되거나 다시 프로비저닝되지 않습니다. 레이블, 태그, 오염 또는 주석을 수정하는 것과 같은 내부 변경 사항은 API 그룹이 머신을 지원하는 기본 인스턴스에 수행할 수 있는 유일한 변경 사항입니다.

참고

지원되는 인프라 유형에서만 일부 리소스를 마이그레이션할 수 있습니다.

Expand
표 11.1. 지원되는 리소스 변환
인프라컴퓨팅 머신컴퓨팅 머신 세트머신 상태 점검제어 평면 기계 세트Cluster autoscaler

AWS

기술 프리뷰

기술 프리뷰

사용할 수 없음

사용할 수 없음

사용할 수 없음

기타 모든 인프라 유형

사용할 수 없음

사용할 수 없음

사용할 수 없음

사용할 수 없음

사용할 수 없음

11.2.2.1. 클러스터 API를 사용하도록 머신 API 리소스 마이그레이션
링크 복사

개별 머신 API 객체를 동등한 클러스터 API 객체로 마이그레이션할 수 있습니다.

중요

클러스터 API를 사용하도록 머신 API 리소스를 마이그레이션하는 것은 기술 미리 보기 기능에 불과합니다. 기술 프리뷰 기능은 Red Hat 프로덕션 서비스 수준 계약(SLA)에서 지원되지 않으며 기능적으로 완전하지 않을 수 있습니다. 따라서 프로덕션 환경에서 사용하는 것은 권장하지 않습니다. 이러한 기능을 사용하면 향후 제품 기능을 조기에 이용할 수 있어 개발 과정에서 고객이 기능을 테스트하고 피드백을 제공할 수 있습니다.

Red Hat 기술 프리뷰 기능의 지원 범위에 대한 자세한 내용은 기술 프리뷰 기능 지원 범위를 참조하십시오.

사전 요구 사항

  • 지원되는 인프라 유형에 OpenShift Container Platform 클러스터를 배포했습니다.
  • 클러스터 API 사용을 활성화했습니다.
  • TechPreviewNoUpgrade 기능 세트에서 MachineAPIMigration 기능 게이트를 활성화했습니다.
  • cluster-admin 권한이 있는 계정을 사용하여 ROSA 클러스터에 액세스할 수 있습니다.
  • OpenShift CLI(oc)가 설치되어 있습니다.

프로세스

  1. 다음 명령을 실행하여 클러스터 API 리소스로 마이그레이션하려는 머신 API 리소스를 식별합니다. 

    $ oc get <resource_kind> -n openshift-machine-api
    Copy to Clipboard Toggle word wrap

    여기서 <resource_kind> 는 다음 값 중 하나입니다.

    machine.machine.openshift.io
    컴퓨팅 또는 제어 평면 머신의 리소스 종류의 정규화된 이름입니다.
    machineset.machine.openshift.io
    컴퓨팅 머신 세트의 리소스 종류의 정규화된 이름입니다.

  2. 다음 명령을 실행하여 리소스 사양을 편집합니다. 

    $ oc edit <resource_kind>/<resource_name> -n openshift-machine-api
    Copy to Clipboard Toggle word wrap

    다음과 같습니다.

    <resource_kind>
    machine.machine.openshift.io를 사용하여 컴퓨팅 머신을 지정하거나 machineset.machine.openshift.io 를 사용하여 컴퓨팅 머신 세트를 지정합니다.
    <resource_name>
    클러스터 API 리소스로 마이그레이션하려는 머신 API 리소스의 이름을 지정합니다.

  3. 리소스 사양에서 spec.authoritativeAPI 필드의 값을 업데이트합니다. 

    apiVersion: machine.openshift.io/v1beta1
kind: <resource_kind>
    1 
    
metadata:
  name: <resource_name>
    2 
    
  [...]
spec:
  authoritativeAPI: ClusterAPI
    3 
    
  [...]
status:
  authoritativeAPI: MachineAPI
    4 
    
  [...]
    Copy to Clipboard Toggle word wrap
    1
    리소스 종류는 리소스 종류에 따라 다릅니다. 예를 들어, 컴퓨팅 머신 세트의 리소스 종류는 MachineSet 이고 컴퓨팅 머신의 리소스 종류는 Machine 입니다.
    2
    마이그레이션하려는 리소스의 이름입니다.
    3
    이 리소스에 사용할 권한 있는 API를 지정하세요. 예를 들어, Machine API 리소스를 Cluster API로 마이그레이션하려면 ClusterAPI를 지정합니다.
    4
    현재 권한 있는 API의 값입니다. 이 값은 현재 어떤 API가 이 리소스를 관리하는지 나타냅니다. 이 사양의 이 부분에 있는 값은 변경하지 마세요.

검증

  • 다음 명령을 실행하여 변환 상태를 확인하세요. 

    $ oc -n openshift-machine-api get <resource_kind>/<resource_name> -o json | jq .status.authoritativeAPI
    Copy to Clipboard Toggle word wrap

    다음과 같습니다.

    <resource_kind>
    machine.machine.openshift.io를 사용하여 컴퓨팅 머신을 지정하거나 machineset.machine.openshift.io 를 사용하여 컴퓨팅 머신 세트를 지정합니다.
    <resource_name>
    클러스터 API 리소스로 마이그레이션하려는 머신 API 리소스의 이름을 지정합니다.
    • 변환이 진행되는 동안 이 명령은 Migrating 값을 반환합니다. 이 값이 오랫동안 지속되면 openshift-cluster-api 네임스페이스에서 cluster-capi-operator 배포에 대한 로그를 확인하여 자세한 정보를 얻고 잠재적인 문제를 파악하세요.
    • 변환이 완료되면 이 명령은 ClusterAPI 값을 반환합니다.

클러스터 API 컴퓨팅 머신을 배포하기 위해 머신 API 컴퓨팅 머신 세트를 구성할 수 있습니다. 이 프로세스를 사용하면 클러스터 API 컴퓨팅 머신 세트를 만들고 확장하지 않고도 클러스터 API 컴퓨팅 머신 생성 워크플로를 테스트할 수 있습니다.

이 구성을 사용하는 Machine API 컴퓨팅 머신 세트는 Cluster API를 권한 있는 것으로 사용하는 비권한 Machine API 컴퓨팅 머신을 생성합니다. 그런 다음 양방향 동기화 컨트롤러는 기본 인프라에서 프로비저닝하는 해당 권한 있는 클러스터 API 머신을 생성합니다.

중요

Machine API 컴퓨팅 머신 세트를 사용하여 클러스터 API 컴퓨팅 머신을 배포하는 것은 기술 미리 보기 기능에 불과합니다. 기술 프리뷰 기능은 Red Hat 프로덕션 서비스 수준 계약(SLA)에서 지원되지 않으며 기능적으로 완전하지 않을 수 있습니다. 따라서 프로덕션 환경에서 사용하는 것은 권장하지 않습니다. 이러한 기능을 사용하면 향후 제품 기능을 조기에 이용할 수 있어 개발 과정에서 고객이 기능을 테스트하고 피드백을 제공할 수 있습니다.

Red Hat 기술 프리뷰 기능의 지원 범위에 대한 자세한 내용은 기술 프리뷰 기능 지원 범위를 참조하십시오.

사전 요구 사항

  • 지원되는 인프라 유형에 OpenShift Container Platform 클러스터를 배포했습니다.
  • 클러스터 API 사용을 활성화했습니다.
  • TechPreviewNoUpgrade 기능 세트에서 MachineAPIMigration 기능 게이트를 활성화했습니다.
  • cluster-admin 권한이 있는 계정을 사용하여 ROSA 클러스터에 액세스할 수 있습니다.
  • OpenShift CLI(oc)가 설치되어 있습니다.

프로세스

  1. 다음 명령을 실행하여 클러스터에 있는 Machine API 컴퓨팅 머신 세트를 나열하세요. 

    $ oc get machineset.machine.openshift.io -n openshift-machine-api
    Copy to Clipboard Toggle word wrap

  2. 다음 명령을 실행하여 리소스 사양을 편집합니다. 

    $ oc edit machineset.machine.openshift.io <machine_set_name> \
  -n openshift-machine-api
    Copy to Clipboard Toggle word wrap

    여기서 <machine_set_name> 은 클러스터 API 컴퓨팅 머신을 배포하기 위해 구성하려는 머신 API 컴퓨팅 머신 세트의 이름입니다.

  3. 리소스 사양에서 spec.template.spec.authoritativeAPI 필드의 값을 업데이트합니다. 

    apiVersion: machine.openshift.io/v1beta1
kind: MachineSet
metadata:
  [...]
  name: <machine_set_name>
  [...]
spec:
  authoritativeAPI: MachineAPI
    1 
    
  [...]
  template:
    [...]
    spec:
      authoritativeAPI: ClusterAPI
    2 
    
status:
  authoritativeAPI: MachineAPI
    3 
    
  [...]
    Copy to Clipboard Toggle word wrap
    1
    Machine API 컴퓨팅 머신 세트의 변환되지 않은 값입니다. 이 사양의 이 부분에 있는 값은 변경하지 마세요.
    2
    ClusterAPI를 지정하여 Cluster API 컴퓨팅 머신을 배포하도록 컴퓨팅 머신 세트를 구성합니다.
    3
    Machine API 컴퓨팅 머신 세트의 현재 값입니다. 이 사양의 이 부분에 있는 값은 변경하지 마세요.

검증

  1. 다음 명령을 실행하여 업데이트된 컴퓨팅 머신 세트에서 관리하는 머신을 나열합니다. 

    $ oc get machines.machine.openshift.io \
  -n openshift-machine-api \
  -l machine.openshift.io/cluster-api-machineset=<machine_set_name>
    Copy to Clipboard Toggle word wrap

  2. 업데이트된 머신 세트에서 생성된 머신이 올바른 구성을 가지고 있는지 확인하려면 다음 명령을 실행하여 새 머신 중 하나에 대한 CR의 status.authoritativeAPI 필드를 조사하세요. 

    $ oc describe machines.machine.openshift.io <machine_name> \
  -n openshift-machine-api
    Copy to Clipboard Toggle word wrap

    클러스터 API 컴퓨팅 머신의 경우 필드 값은 ClusterAPI 입니다.

맨 위로 이동
Red Hat logoGithubredditYoutubeTwitter

자세한 정보

평가판, 구매 및 판매

커뮤니티

Red Hat 문서 정보

Red Hat을 사용하는 고객은 신뢰할 수 있는 콘텐츠가 포함된 제품과 서비스를 통해 혁신하고 목표를 달성할 수 있습니다. 최신 업데이트를 확인하세요.

보다 포괄적 수용을 위한 오픈 소스 용어 교체

Red Hat은 코드, 문서, 웹 속성에서 문제가 있는 언어를 교체하기 위해 최선을 다하고 있습니다. 자세한 내용은 다음을 참조하세요.Red Hat 블로그.

Red Hat 소개

Red Hat은 기업이 핵심 데이터 센터에서 네트워크 에지에 이르기까지 플랫폼과 환경 전반에서 더 쉽게 작업할 수 있도록 강화된 솔루션을 제공합니다.

Theme

© 2025 Red Hat