이 문서에서는 신규 및 기존 클러스터에서 노드 에이전트를 사용하여 더 안전한 클러스터 작업을 제공하는 방법을 설명합니다. 버전 1.33부터 베어메탈용 Google Distributed Cloud는 클러스터 작업에 SSH를 통해 Ansible을 사용하는 것에서 노드 에이전트를 사용하는 더 안전한 에이전트 기반 모델로 전환하는 기능을 제공합니다. 노드 에이전트를 사용하여 클러스터 작업을 관리하면 민감한 환경에서 고객 노드에 대한 SSH 액세스가 필요하다는 보안 문제가 해결됩니다.
새 모델에서는 각 노드에서 노드 에이전트 바이너리가 실행됩니다. 노드 에이전트는 보안 gRPC 채널을 통해 컨트롤러와 같은 클라이언트와 통신하여 모든 노드 구성 활동을 관리합니다. Google Distributed Cloud는 gRPC 연결의 인증 및 암호화를 위해 클러스터 컨트롤러와 노드 에이전트 간, bmctl와 노드 에이전트 간에 상호 전송 계층 보안 (mTLS)을 적용합니다.
bmctl nodeagent 명령어를 사용하면 기존 클러스터를 노드 에이전트를 사용하도록 마이그레이션하는 프로세스가 간단하고 안정적입니다. 이 명령어를 사용하면 수동 작업이 줄어들고, 노드 간 일관성이 개선되며, 인증서 생성 및 순환과 같은 주요 작업이 자동화됩니다. bmctl 명령어는 주로 SSH를 통해 작동합니다. 이를 통해 관리자는 클러스터 컨트롤러가 비정상적이거나 표준 통신 채널이 손상된 경우에도 에이전트를 배포하거나 재배포할 수 있습니다.
노드 에이전트와 해당 bmctl nodeagent 명령어는 베어메탈용 Google Distributed Cloud 버전 1.33.0 이상을 지원합니다. 기존 버전 1.33 이상 클러스터에 또는 버전 1.33 이상 클러스터를 만들 때 노드 에이전트를 사용 설정할 수 있습니다.
이 페이지는 기본 기술 인프라 수명 주기를 관리하는 관리자, 설계자, 운영자를 대상으로 합니다. Google Cloud 콘텐츠에서 참조하는 일반적인 역할과 예시 태스크에 대한 자세한 내용은 일반 GKE Enterprise 사용자 역할 및 태스크를 참조하세요.
시작하기 전에
클러스터를 노드 에이전트 모드로 마이그레이션하기 전에 모든 클러스터 노드가 다음 요구사항을 충족하는지 확인하세요.
각 노드에는 노드 에이전트 전용으로 열린 포트가 있습니다. 기본적으로 노드 에이전트는 포트 9192를 사용하지만 배포, 사용 설정 또는 새 클러스터 설치 중에 이 포트를 구성할 수 있습니다. 자세한 내용은 노드 에이전트 포트 맞춤설정을 참고하세요.
각 노드에 containerd 버전 1.7 이상이 설치되어 있습니다.
노드 에이전트 모드로 이전
노드 에이전트 모드로 마이그레이션하는 과정은 두 단계로 이루어집니다.
노드 에이전트 배포: 노드 에이전트 구성요소를 클러스터 내 모든 노드에 배포합니다.
노드 에이전트 모드 사용 설정:
- 기존 클러스터의 경우
bmctl nodeagent명령어를 사용하여 모드를 사용 설정합니다. - 새 클러스터의 경우 생성 전에 사용 설정 주석과 해당 사용자 인증 정보 경로를 클러스터 구성 파일에 추가합니다.
- 기존 클러스터의 경우
노드 에이전트 배포
bmctl nodeagent deploy 명령어는 SSH를 사용하여 지정된 클러스터 내의 하나 이상의 타겟 노드에 노드 에이전트 서비스를 배포합니다. 이 명령어는 노드 에이전트를 설치하거나 재설치합니다. SSH를 통해 연결하고 바이너리 전송, 선택적으로 인증서 생성 및 전송, systemd 서비스 설정 등 필요한 단계를 실행합니다. 타겟 노드에 대한 SSH 액세스 및 sudo 권한이 필요합니다.
--nodes 플래그를 통해 직접, --cluster 플래그를 사용하여 클러스터 구성 파일을 통해 또는 클러스터 커스텀 리소스를 참조하여 여러 방법으로 타겟 노드를 지정할 수 있습니다. 노드 에이전트 명령어 및 옵션에 대한 자세한 내용은 bmctl 명령어 참조를 참고하세요.
새 환경에 배포
초기 배포의 경우 nodeagentd 바이너리를 다운로드하고 새 인증 기관 (CA)을 생성합니다. 다음 명령어는 클러스터 구성 파일에서 노드 목록을 가져옵니다. --sa-key 플래그는 Cloud Storage 버킷에서 nodeagentd 바이너리를 다운로드하는 데 필요한 사용자 인증 정보를 제공합니다.
새 클러스터에 처음으로 노드 에이전트를 배포하려면 다음 명령어를 사용하세요.
bmctl nodeagent deploy \ --pull-binaries true \ --generate-ca-creds true \ --cluster CLUSTER_NAME \ --ssh-user USERNAME \ --ssh-key SSH_KEY_PATH \ --sa-key SERVICE_ACCOUNT_KEY_PATH다음을 바꿉니다.
CLUSTER_NAME: 노드 에이전트를 배포하려는 노드가 있는 클러스터의 이름입니다.USERNAME: 노드에 대한 SSH 액세스가 구성된 사용자 이름입니다. 기본적으로 SSH는root로 구성되지만 로그인 사용자를 설정한 경우 해당 사용자 이름을 사용합니다.SSH_KEY_PATH: SSH 비공개 키 파일의 경로입니다.SERVICE_ACCOUNT_KEY_PATH: 레지스트리 이미지를 가져올 권한이 있는 서비스 계정 키 파일의 경로입니다. 기본적으로 이는anthos-baremetal-gcr서비스 계정의 JSON 키 파일입니다.
명령어 출력은 다음 예시와 비슷합니다.
Please check the logs at bmctl-workspace/demo-cluster/log/nodeagent_deploy-20250819-175703/nodeagent_deploy.log [2025-08-19 17:57:03+0000] INFO: Executing 'nodeagent deploy'... [2025-08-19 17:57:05+0000] -------------------- Deployment Plan -------------------- [2025-08-19 17:57:05+0000] Target Cluster: demo-cluster [2025-08-19 17:57:05+0000] SSH User: root [2025-08-19 17:57:05+0000] SSH Key: rootSSH [2025-08-19 17:57:05+0000] Concurrency: 25 [2025-08-19 17:57:05+0000] Generate Credentials: true [2025-08-19 17:57:05+0000] Deploy Credentials: true [2025-08-19 17:57:05+0000] Server Cert Validity Days: 1825 [2025-08-19 17:57:05+0000] Verify SSH Host Keys: true [2025-08-19 17:57:05+0000] Node Agent pull version: 1.33.0-gke.799 [2025-08-19 17:57:05+0000] Target Nodes Source: cluster YAML [2025-08-19 17:57:05+0000] Nodes Port: 9192 [2025-08-19 17:57:05+0000] Target Nodes (4): 10.200.0.2, 10.200.0.3, 10.200.0.4, 10.200.0.5 [2025-08-19 17:57:05+0000] --------------------------------------------------------- Proceed with deployment? [y/N]: y [2025-08-19 17:57:07+0000] INFO: User confirmed. [2025-08-19 17:57:07+0000] Downloading Node Agent binary (1.33.0-gke.799)... OK [2025-08-19 17:57:08+0000] INFO: Node Agent binary pulled and stored at bmctl-workspace/bins/nodeagentd [2025-08-19 17:57:08+0000] INFO: Starting generate credentials (CAs and client credentials) phase... [2025-08-19 17:57:08+0000] Generating credentials for the cluster: demo-cluster, 2025-08-19T17:57:08Z [2025-08-19 17:57:08+0000] ------------ Credentials Options ------------ [2025-08-19 17:57:08+0000] Cluster Name: demo-cluster [2025-08-19 17:57:08+0000] Key Algorithm: rsa [2025-08-19 17:57:08+0000] Key Length: 4096 [2025-08-19 17:57:08+0000] CA Validity (days): 3650 [2025-08-19 17:57:08+0000] Client Validity (days): 1825 [2025-08-19 17:57:08+0000] Server CA CN: Node Agent Server CA [2025-08-19 17:57:08+0000] Client CA CN: Node Agent Client CA [2025-08-19 17:57:08+0000] Creds path: bmctl-workspace/demo-cluster/nodeagent-creds [2025-08-19 17:57:08+0000] -------------------------------------------- [2025-08-19 17:57:08+0000] Generating credentials... OK [2025-08-19 17:57:19+0000] Certificates have been created and stored in bmctl-workspace/demo-cluster/nodeagent-creds [2025-08-19 17:57:19+0000] INFO: Attempting to load CAs from: bmctl-workspace/demo-cluster/nodeagent-creds [2025-08-19 17:57:19+0000] INFO: Server CA loaded successfully. Subject: CN=Node Agent Server CA,O=GCD-SO,L=Sunnyvale,ST=California,C=US, Key Type: *rsa.PrivateKey [2025-08-19 17:57:19+0000] INFO: Client CA loaded successfully. Subject: CN=Node Agent Client CA,O=GCD-SO,L=Sunnyvale,ST=California,C=US, Key Type: *rsa.PrivateKey [2025-08-19 17:57:19+0000] =============================================== [2025-08-19 17:57:19+0000] --- Starting Artifact Preparation --- [2025-08-19 17:57:19+0000] Starting artifact preparation for 4 nodes (concurrency: 25)... [2025-08-19 17:57:23+0000] --- Finished Artifact Preparation --- [2025-08-19 17:57:23+0000] INFO: Preparation SUCCEEDED for node 10.200.0.2 [2025-08-19 17:57:23+0000] INFO: Preparation SUCCEEDED for node 10.200.0.3 [2025-08-19 17:57:23+0000] INFO: Preparation SUCCEEDED for node 10.200.0.4 [2025-08-19 17:57:23+0000] INFO: Preparation SUCCEEDED for node 10.200.0.5 [2025-08-19 17:57:23+0000] =============================================== [2025-08-19 17:57:23+0000] --- Starting Deployment Phase --- [2025-08-19 17:57:23+0000] INFO: Starting deployment to 4 nodes (Concurrency: 25)... [2025-08-19 17:57:36+0000] INFO: All host deployments finished. [2025-08-19 17:57:36+0000] INFO: --- Deployment Phase Completed Successfully --- [2025-08-19 17:57:36+0000] =============================================== --- Deployment Summary --- Host: 10.200.0.2, Status: SUCCESS Host: 10.200.0.3, Status: SUCCESS Host: 10.200.0.4, Status: SUCCESS Host: 10.200.0.5, Status: SUCCESS ----------------------------------------------- Total Nodes Attempted: 4 | SUCCESS: 4 | FAILED: 0 ===============================================
노드 에이전트 버전 업그레이드
노드 에이전트 업그레이드는 클러스터 업그레이드와 별개입니다. 노드 에이전트를 업그레이드하려면 bmctl nodeagent deploy 명령어를 사용하고 --pull-binaries을 true로 설정합니다. 노드 에이전트를 업그레이드할 때 --generate-ca-creds를 false로 설정하여 CA를 재생성하는 대신 기존 CA를 사용합니다. CA를 재생성하려면 해당 클러스터 사용자 인증 정보를 업데이트해야 하며, 이 프로세스는 사용자 인증 정보 순환을 위해 예약되어 있습니다. 출력은 CA 생성 로그가 없는 새 배포와 유사합니다.
노드 에이전트를 업그레이드하면 노드 에이전트 프로세스가 다시 시작되어 실행 중인 작업이 중단될 수 있습니다. 대부분의 작업은 재시도 메커니즘을 통해 복구되지만 잠재적인 중단을 최소화하려면 다음 단계를 따르세요.
클러스터 업그레이드 또는 기타 설치 후 구성 활동이 진행 중이 아닌지 확인합니다.
클러스터가 실행 상태인지 확인합니다.
노드 에이전트 업그레이드를 시작합니다.
bmctl nodeagent deploy \ --pull-binaries true \ --generate-ca-creds false \ --cluster CLUSTER_NAME \ --ssh-user USERNAME \ --ssh-key SSH_KEY_PATH \ --sa-key SERVICE_ACCOUNT_KEY_PATH다음을 바꿉니다.
CLUSTER_NAME: 노드 에이전트를 배포하려는 노드가 있는 클러스터의 이름입니다.USERNAME: 노드에 대한 SSH 액세스가 구성된 사용자 이름입니다. 기본적으로 SSH는root로 구성되지만 로그인 사용자를 설정한 경우 해당 사용자 이름을 사용합니다.SSH_KEY_PATH: SSH 비공개 키 파일의 경로입니다.SERVICE_ACCOUNT_KEY_PATH: 레지스트리 이미지를 가져올 권한이 있는 서비스 계정 키 파일의 경로입니다. 기본적으로 이는anthos-baremetal-gcr서비스 계정의 JSON 키 파일입니다.
명령어 출력은 다음 예시와 비슷합니다.
Please check the logs at bmctl-workspace/demo-cluster/log/nodeagent_deploy-20250819-180416/nodeagent_deploy.log [2025-08-19 18:04:16+0000] INFO: Executing 'nodeagent deploy'... [2025-08-19 18:04:18+0000] -------------------- Deployment Plan -------------------- [2025-08-19 18:04:18+0000] Target Cluster: demo-cluster [2025-08-19 18:04:18+0000] SSH User: root [2025-08-19 18:04:18+0000] SSH Key: rootSSH [2025-08-19 18:04:18+0000] Concurrency: 25 [2025-08-19 18:04:18+0000] Generate Credentials: false [2025-08-19 18:04:18+0000] Deploy Credentials: true [2025-08-19 18:04:18+0000] Server Cert Validity Days: 1825 [2025-08-19 18:04:18+0000] Verify SSH Host Keys: true [2025-08-19 18:04:18+0000] Node Agent pull version: 1.33.0-gke.799 [2025-08-19 18:04:18+0000] Target Nodes Source: cluster YAML [2025-08-19 18:04:18+0000] Nodes Port: 9192 [2025-08-19 18:04:18+0000] Target Nodes (4): 10.200.0.2, 10.200.0.3, 10.200.0.4, 10.200.0.5 [2025-08-19 18:04:18+0000] --------------------------------------------------------- Proceed with deployment? [y/N]: y [2025-08-19 18:04:20+0000] INFO: User confirmed. [2025-08-19 18:04:20+0000] Downloading Node Agent binary (1.33.0-gke.799)... OK [2025-08-19 18:04:22+0000] INFO: Node Agent binary pulled and stored at bmctl-workspace/bins/nodeagentd [2025-08-19 18:04:22+0000] INFO: Attempting to load CAs from: bmctl-workspace/demo-cluster/nodeagent-creds [2025-08-19 18:04:22+0000] INFO: Server CA loaded successfully. Subject: CN=Node Agent Server CA,O=gcd-SO,L=Sunnyvale,ST=California,C=US, Key Type: *rsa.PrivateKey [2025-08-19 18:04:22+0000] INFO: Client CA loaded successfully. Subject: CN=Node Agent Client CA,O=gcd-SO,L=Sunnyvale,ST=California,C=US, Key Type: *rsa.PrivateKey [2025-08-19 18:04:22+0000] =============================================== [2025-08-19 18:04:22+0000] --- Starting Artifact Preparation --- [2025-08-19 18:04:22+0000] Starting artifact preparation for 4 nodes (concurrency: 25)...
특정 노드에 배포 또는 재배포
클러스터 노드를 추가하거나 복구하는 경우 클러스터의 모든 노드에 배포하는 대신 노드 에이전트 배포를 위해 특정 노드를 타겟팅할 수 있습니다. --nodes 플래그를 사용하여 배포할 노드를 지정합니다.
특정 노드에 노드 에이전트를 배포하려면 다음 명령어를 사용하세요.
bmctl nodeagent deploy \ --pull-binaries true \ --cluster CLUSTER_NAME \ --ssh-user USERNAME \ --ssh-key SSH_KEY_PATH \ --sa-key SERVICE_ACCOUNT_KEY_PATH \ --nodes NODE_IP_ADDRESS_LIST다음을 바꿉니다.
CLUSTER_NAME: 노드 에이전트를 배포하려는 노드가 있는 클러스터의 이름입니다.USERNAME: 노드에 대한 SSH 액세스가 구성된 사용자 이름입니다. 기본적으로 SSH는root로 구성되지만 로그인 사용자를 설정한 경우 해당 사용자 이름을 사용합니다.SSH_KEY_PATH: SSH 비공개 키 파일의 경로입니다.SERVICE_ACCOUNT_KEY_PATH: 레지스트리 이미지를 가져올 권한이 있는 서비스 계정 키 파일의 경로입니다. 기본적으로 이는anthos-baremetal-gcr서비스 계정의 JSON 키 파일입니다.NODE_IP_ADDRESS_LIST: Node Agent를 배포할 노드의 IP 주소를 쉼표로 구분한 목록입니다.
명령어 출력은 다음 예시와 비슷합니다.
Please check the logs at bmctl-workspace/demo-cluster/log/nodeagent_deploy-20250819-181751/nodeagent_deploy.log [2025-08-19 18:17:51+0000] INFO: Executing 'nodeagent deploy'... [2025-08-19 18:17:54+0000] -------------------- Deployment Plan -------------------- [2025-08-19 18:17:54+0000] Target Cluster: demo-cluster [2025-08-19 18:17:54+0000] SSH User: user [2025-08-19 18:17:54+0000] SSH Key: SSH_KEY_PATH [2025-08-19 18:17:54+0000] Concurrency: 25 [2025-08-19 18:17:54+0000] Generate Credentials: false [2025-08-19 18:17:54+0000] Deploy Credentials: true [2025-08-19 18:17:54+0000] Server Cert Validity Days: 1825 [2025-08-19 18:17:54+0000] Verify SSH Host Keys: true [2025-08-19 18:17:54+0000] Node Agent pull version: 1.33.0-gke.799 [2025-08-19 18:17:54+0000] Target Nodes Source: nodes flag [2025-08-19 18:17:54+0000] Nodes Port: 9192 [2025-08-19 18:17:54+0000] Target Nodes (3): 10.200.0.2, 10.200.0.3 [2025-08-19 18:17:54+0000] --------------------------------------------------------- Proceed with deployment? [y/N]:
bmctl nodeagent deploy 명령어 옵션의 전체 목록은 bmctl 명령어 참조의 nodeagent deploy를 참고하세요.
노드 에이전트 사용 설정
enable 명령어는 클러스터 내의 모든 노드에 노드 에이전트를 배포한 후 실행 중인 기존 클러스터 내에서 노드 에이전트 모드를 활성화합니다. 이 명령어는 클러스터 내에서 노드 에이전트 사용자 인증 정보를 만들거나 업데이트하기도 합니다.
실행 중인 기존 클러스터에 노드 에이전트 사용 설정
기존 버전 1.33 이상 클러스터에서 노드 에이전트를 사용 설정할 수 있습니다.
기존 클러스터에서 노드 에이전트를 사용 설정하려면 다음 명령어를 사용하세요.
./bmctl nodeagent enable \ --kubeconfig KUBECONFIG \ --cluster CLUSTER_NAME \ --ensure-status=true다음을 바꿉니다.
KUBECONFIG: 노드 에이전트를 사용 설정할 클러스터의 kubeconfig 파일 경로입니다.CLUSTER_NAME: 노드 에이전트를 배포하려는 노드가 있는 클러스터의 이름입니다.
명령어 출력은 다음 예시와 비슷합니다.
Please check the logs at bmctl-workspace/demo-cluster/log/nodeagent_enable-20250819-183058/nodeagent_enable.log [2025-08-19 18:30:58+0000] Enable Node Agent for cluster: demo-cluster [2025-08-19 18:31:00+0000] Update Node Agent credentials [2025-08-19 18:31:00+0000] ---------------------------------------------------------- [2025-08-19 18:31:00+0000] Server CA certificate path: bmctl-workspace/demo-cluster/nodeagent-creds/server_ca_cert.pem [2025-08-19 18:31:00+0000] Server CA private key path: bmctl-workspace/demo-cluster/nodeagent-creds/server_ca_key.pem [2025-08-19 18:31:00+0000] Client CA certificate path: bmctl-workspace/demo-cluster/nodeagent-creds/client_ca_cert.pem [2025-08-19 18:31:00+0000] Client CA private key path: bmctl-workspace/demo-cluster/nodeagent-creds/client_ca_key.pem [2025-08-19 18:31:00+0000] Client certificate path: bmctl-workspace/demo-cluster/nodeagent-creds/client_cert.pem [2025-08-19 18:31:00+0000] Client private key path: bmctl-workspace/demo-cluster/nodeagent-creds/client_key.pem [2025-08-19 18:31:00+0000] ---------------------------------------------------------- [2025-08-19 18:31:00+0000] Node Agent client credentials secret has been created/updated [2025-08-19 18:31:00+0000] Node Agent server CA secret has been created/updated [2025-08-19 18:31:00+0000] Node Agent client CA secret has been created/updated [2025-08-19 18:31:00+0000] Successfully created/updated Node Agent credentials secrets in namespace cluster-demo-cluster [2025-08-19 18:31:00+0000] Annotation 'baremetal.cluster.gke.io/node-agent-port' not found on cluster cluster-demo-cluster/demo-cluster, no removal needed. [2025-08-19 18:31:00+0000] Successfully enable Node Agent for cluster: demo-cluster [2025-08-19 18:31:00+0000] ---------------------------------------------------------- [2025-08-19 18:31:00+0000] Verifying Node Agent status on all nodes... [2025-08-19 18:31:00+0000] --------------------- Total nodes: 3 ---------------------- [2025-08-19 18:31:00+0000] node: control-0--893f0567cb79efc-9b9ec55816170dcf.lab.anthos, version: 1.33.0-gke.799, OS: linux, uptime (seconds): 1577 [2025-08-19 18:31:00+0000] node: control-1--893f0567cb79efc-9b9ec55816170dcf.lab.anthos, version: 1.33.0-gke.799, OS: linux, uptime (seconds): 1578 [2025-08-19 18:31:00+0000] node: control-2--893f0567cb79efc-9b9ec55816170dcf.lab.anthos, version: 1.33.0-gke.799, OS: linux, uptime (seconds): 1581 [2025-08-19 18:31:00+0000] ---------------------------------------------------------- [2025-08-19 18:31:00+0000] Verified Node Agent status on all nodes in cluster
새 클러스터 설치
버전 1.33 이상의 클러스터를 만들 때 노드 에이전트를 사용 설정할 수 있습니다.
새 클러스터에 노드 에이전트를 사용 설정하려면 다음 단계를 따르세요.
새 관리자 클러스터의 경우 관리자 클러스터 구성 파일의 상단 섹션에 다음 사용자 인증 정보 파일 경로를 추가합니다.
nodeAgentServerCACertificatePath: bmctl-workspace/demo-cluster/nodeagent-creds/server_ca_cert.pem nodeAgentServerCAPrivateKeyPath: bmctl-workspace/demo-cluster/nodeagent-creds/server_ca_key.pem nodeAgentClientCACertificatePath: bmctl-workspace/demo-cluster/nodeagent-creds/client_ca_cert.pem nodeAgentClientCAPrivateKeyPath: bmctl-workspace/demo-cluster/nodeagent-creds/client_ca_key.pem nodeAgentClientCertificatePath: bmctl-workspace/demo-cluster/nodeagent-creds/client_cert.pem nodeAgentClientPrivateKeyPath: bmctl-workspace/demo-cluster/nodeagent-creds/client_key.pem클러스터 구성 파일의 클러스터 메타데이터 섹션에 노드 에이전트 사용 설정 주석을 포함합니다.
kind: Cluster metadata: annotations: baremetal.cluster.gke.io/enable-node-agent: ""표준 안내에 따라 클러스터를 만듭니다.
bmctl nodeagent enable 명령어 옵션의 전체 목록은 bmctl 명령어 참조에서 nodeagent enable을 참고하세요.
사용자 인증 정보 순환
rotate-credentials 명령어는 노드와 클러스터 내에서 노드 에이전트 사용자 인증 정보를 순환합니다. 여기에는 인증 기관 (CA)을 순환하는 기능이 포함됩니다. --generate-ca-creds 플래그는 명령어가 CA를 재생성하고 새로 생성된 CA를 사용하여 서버 (노드)와 클라이언트 (컨트롤러) 모두의 인증서에 서명하도록 지시합니다.
인증 정보를 순환하고 새 CA를 재생성하고 사용하려면 다음 명령어를 사용하세요.
bmctl nodeagent rotate-credentials \ --kubeconfig KUBECONFIG \ --generate-ca-creds true \ --cluster CLUSTER_NAME \ --ssh-user USERNAME \ --ssh-key SSH_KEY_PATH다음을 바꿉니다.
KUBECONFIG: 노드 에이전트를 사용 설정할 클러스터의 kubeconfig 파일 경로입니다.CLUSTER_NAME: 노드 에이전트를 배포하려는 노드가 있는 클러스터의 이름입니다.USERNAME: 노드에 대한 SSH 액세스가 구성된 사용자 이름입니다. 기본적으로 SSH는root로 구성되지만 로그인 사용자를 설정한 경우 해당 사용자 이름을 사용합니다.SSH_KEY_PATH: SSH 비공개 키 파일의 경로입니다.
명령어 출력은 다음 예시와 비슷합니다.
Please check the logs at bmctl-workspace/demo-cluster/log/nodeagent_rotate_credentials-20250819-184216/nodeagent_rotate_credentials.log [2025-08-19 18:42:16+0000] INFO: Executing 'nodeagent rotate-credentials'... [2025-08-19 18:42:18+0000] ------------------- Credentials Rotation ------------------- [2025-08-19 18:42:18+0000] Target Cluster: demo-cluster [2025-08-19 18:42:18+0000] SSH User: root [2025-08-19 18:42:18+0000] SSH Key: rootSSH [2025-08-19 18:42:18+0000] Concurrency: 25 [2025-08-19 18:42:18+0000] Generate Credentials: true [2025-08-19 18:42:18+0000] Deploy Credentials: true [2025-08-19 18:42:18+0000] Server Cert Validity Days: 1825 [2025-08-19 18:42:18+0000] Verify SSH Host Keys: true [2025-08-19 18:42:18+0000] Target Nodes Source: cluster CR [2025-08-19 18:42:18+0000] Nodes Port: 9192 [2025-08-19 18:42:18+0000] Target Nodes (3): 10.200.0.2, 10.200.0.3, 10.200.0.4 [2025-08-19 18:42:18+0000] --------------------------------------------------------- Proceed with credentials rotation? [y/N]: [2025-08-19 18:42:18+0000] INFO: Non-interactive mode enabled; automatically confirming. [2025-08-19 18:42:18+0000] INFO: Starting generate credentials (CAs and client credentials) phase... [2025-08-19 18:42:18+0000] Generating credentials for the cluster: demo-cluster, 2025-08-19T18:42:18Z [2025-08-19 18:42:18+0000] ------------ Credentials Options ------------ [2025-08-19 18:42:18+0000] Cluster Name: demo-cluster [2025-08-19 18:42:18+0000] Key Algorithm: rsa [2025-08-19 18:42:18+0000] Key Length: 4096 [2025-08-19 18:42:18+0000] CA Validity (days): 3650 [2025-08-19 18:42:18+0000] Client Validity (days): 1825 [2025-08-19 18:42:18+0000] Server CA CN: Node Agent Server CA [2025-08-19 18:42:18+0000] Client CA CN: Node Agent Client CA [2025-08-19 18:42:18+0000] Creds path: bmctl-workspace/demo-cluster/nodeagent-creds [2025-08-19 18:42:18+0000] -------------------------------------------- [2025-08-19 18:42:18+0000] Generating credentials... OK Credential directory 'bmctl-workspace/demo-cluster/nodeagent-creds' already exists. Do you want to back it up and continue? (y/N): y [2025-08-19 18:42:27+0000] INFO: User confirmed. [2025-08-19 18:42:27+0000] Credentials backup to bmctl-workspace/demo-cluster/nodeagent-creds_backup_20250819_184227 [2025-08-19 18:42:27+0000] Certificates have been created and stored in bmctl-workspace/demo-cluster/nodeagent-creds [2025-08-19 18:42:27+0000] INFO: Attempting to load CAs from: bmctl-workspace/demo-cluster/nodeagent-creds [2025-08-19 18:42:27+0000] INFO: Server CA loaded successfully. Subject: CN=Node Agent Server CA,O=gcd-SO,L=Sunnyvale,ST=California,C=US, Key Type: *rsa.PrivateKey [2025-08-19 18:42:27+0000] INFO: Client CA loaded successfully. Subject: CN=Node Agent Client CA,O=gcd-SO,L=Sunnyvale,ST=California,C=US, Key Type: *rsa.PrivateKey [2025-08-19 18:42:27+0000] =============================================== [2025-08-19 18:42:34+0000] INFO: All host deployments finished. [2025-08-19 18:42:34+0000] INFO: --- Deployment Phase Completed Successfully --- [2025-08-19 18:42:34+0000] =============================================== --- Deployment Summary --- Host: 10.200.0.2, Status: SUCCESS Host: 10.200.0.3, Status: SUCCESS Host: 10.200.0.4, Status: SUCCESS ----------------------------------------------- Total Nodes Attempted: 3 | SUCCESS: 3 | FAILED: 0 ===============================================
bmctl nodeagent rotate-credentials 명령어 옵션의 전체 목록은 bmctl 명령어 참조의 nodeagent rotate-credentials를 참고하세요.
상태 확인
status 명령어는 노드에서 실행 중인 노드 에이전트의 상태에 관한 정보를 제공합니다. --nodes 플래그를 통해, --cluster 플래그를 사용하는 클러스터 구성 파일을 통해 또는 클러스터의 커스텀 리소스를 참조하여 대상 노드를 직접 지정할 수 있습니다.
클러스터 구성 파일 또는 --nodes 플래그에서 노드를 가져오면 시스템이 로컬 파일 시스템에서 사용자 인증 정보를 가져옵니다. 노드 소스가 클러스터 커스텀 리소스인 경우 시스템은 클러스터에서 사용자 인증 정보를 가져옵니다.
다음 우선순위에 따라 노드 에이전트 포트가 결정됩니다.
--port플래그- kubeconfig 파일
- 클러스터 구성 파일
노드 에이전트 상태 확인
--cluster 플래그만 사용하여 클러스터 구성 파일에 지정된 내용을 기반으로 노드 에이전트 상태를 확인할 수 있습니다.
클러스터 구성 파일을 기반으로 노드 에이전트 상태를 확인하려면 다음 명령어를 사용하세요.
./bmctl nodeagent status \ --cluster CLUSTER_NAMECLUSTER_NAME을 확인할 클러스터의 이름으로 바꿉니다.명령어 출력은 다음 예시와 비슷합니다.
Please check the logs at bmctl-workspace/demo-cluster/log/nodeagent_status-20250819-205707/nodeagent_status.log [2025-08-19 20:57:07+0000] Check Node Agent for cluster: demo-cluster [2025-08-19 20:57:09+0000] ---------------------------------------------------------- [2025-08-19 20:57:09+0000] Verifying Node Agent status on all nodes... [2025-08-19 20:57:09+0000] Target Nodes Source: cluster YAML [2025-08-19 20:57:09+0000] --------------------- Total nodes: 4 ---------------------- [2025-08-19 20:57:09+0000] node: control-0--893f0567cb79efc-9b9ec55816170dcf.lab.anthos, version: 1.33.0-gke.799, OS: linux, uptime (seconds): 1175 [2025-08-19 20:57:09+0000] node: control-1--893f0567cb79efc-9b9ec55816170dcf.lab.anthos, version: 1.33.0-gke.799, OS: linux, uptime (seconds): 1174 [2025-08-19 20:57:09+0000] node: control-2--893f0567cb79efc-9b9ec55816170dcf.lab.anthos, version: 1.33.0-gke.799, OS: linux, uptime (seconds): 1176 [2025-08-19 20:57:09+0000] node: worker-0--893f0567cb79efc-9b9ec55816170dcf.lab.anthos, version: 1.33.0-gke.799, OS: linux, uptime (seconds): 1179 [2025-08-19 20:57:09+0000] ---------------------------------------------------------- [2025-08-19 20:57:09+0000] Verified Node Agent status on all nodes in cluster
클러스터에서 노드 에이전트 상태 확인
--cluster 플래그를 --kubeconfig 플래그와 함께 사용하여 클러스터 커스텀 리소스에 따라 노드 에이전트 상태를 확인할 수 있습니다.
클러스터 커스텀 리소스를 기반으로 노드 에이전트 상태를 확인하려면 다음 명령어를 사용하세요.
./bmctl nodeagent status \ --cluster CLUSTER_NAME \ --kubeconfig KUBECONFIG다음을 바꿉니다.
CLUSTER_NAME: 노드 에이전트를 배포하려는 노드가 있는 클러스터의 이름입니다.KUBECONFIG: 노드 에이전트를 사용 설정할 클러스터의 kubeconfig 파일 경로입니다.
명령어 출력은 다음 예시와 비슷합니다.
Please check the logs at bmctl-workspace/demo-cluster/log/nodeagent_status-20250819-205712/nodeagent_status.log [2025-08-19 20:57:12+0000] Check Node Agent for cluster: demo-cluster [2025-08-19 20:57:14+0000] ---------------------------------------------------------- [2025-08-19 20:57:14+0000] Verifying Node Agent status on all nodes... [2025-08-19 20:57:14+0000] Target Nodes Source: cluster CR [2025-08-19 20:57:14+0000] --------------------- Total nodes: 3 ---------------------- [2025-08-19 20:57:14+0000] node: control-0--893f0567cb79efc-9b9ec55816170dcf.lab.anthos, version: 1.33.0-gke.799, OS: linux, uptime (seconds): 1180 [2025-08-19 20:57:14+0000] node: control-1--893f0567cb79efc-9b9ec55816170dcf.lab.anthos, version: 1.33.0-gke.799, OS: linux, uptime (seconds): 1179 [2025-08-19 20:57:14+0000] node: control-2--893f0567cb79efc-9b9ec55816170dcf.lab.anthos, version: 1.33.0-gke.799, OS: linux, uptime (seconds): 1180 [2025-08-19 20:57:14+0000] ---------------------------------------------------------- [2025-08-19 20:57:14+0000] Verified Node Agent status on all nodes in cluster
노드에서 노드 에이전트 상태 확인
--cluster 플래그를 --nodes 플래그와 함께 사용하면 특정 클러스터 노드의 노드 에이전트 상태를 확인할 수 있습니다.
특정 노드의 노드 에이전트 상태를 확인하려면 다음 명령어를 사용하세요.
./bmctl nodeagent status \ --cluster CLUSTER_NAME \ --nodes NODE_IP_ADDRESS_LIST다음을 바꿉니다.
CLUSTER_NAME: 노드 에이전트를 배포하려는 노드가 있는 클러스터의 이름입니다.NODE_IP_ADDRESS_LIST: Node Agent를 배포할 노드의 IP 주소를 쉼표로 구분한 목록입니다.
명령어 출력은 다음 예시와 비슷합니다.
Please check the logs at bmctl-workspace/demo-cluster/log/nodeagent_status-20250819-210050/nodeagent_status.log [2025-08-19 21:00:50+0000] Check Node Agent for cluster: demo-cluster [2025-08-19 21:00:53+0000] ---------------------------------------------------------- [2025-08-19 21:00:53+0000] Verifying Node Agent status on all nodes... [2025-08-19 21:00:53+0000] Target Nodes Source: nodes flag [2025-08-19 21:00:53+0000] --------------------- Total nodes: 1 ---------------------- [2025-08-19 21:00:53+0000] node: control-0--893f0567cb79efc-9b9ec55816170dcf.lab.anthos, version: 1.33.0-gke.799, OS: linux, uptime (seconds): 1399 [2025-08-19 21:00:53+0000] ---------------------------------------------------------- [2025-08-19 21:00:53+0000] Verified Node Agent status on all nodes in cluster
bmctl nodeagent status 명령어 옵션의 전체 목록은 bmctl 명령어 참조의 nodeagent status를 참고하세요.
SSH 사용자 권한
루트가 아닌 사용자는 bmctl nodeagent 명령어를 실행할 수 있습니다. 이를 위해서는 사용자에게 비밀번호 없는 전체 sudo 권한이 있거나 명시적인 비밀번호 없는 sudo 허용 목록이 있어야 합니다.
노드 에이전트의 명시적 비밀번호 없는 sudo 허용 목록에는 다음 권한이 있습니다.
# Permission to create the necessary folders and set permissions.
/bin/mkdir -p /etc/nodeagentd
/bin/chmod 0755 /etc/nodeagentd
/bin/mkdir -p /usr/local/bin
/bin/chmod 0755 /usr/local/bin
/bin/mkdir -p /etc/systemd/system
/bin/chmod 0755 /etc/systemd/system
# Permission to place the main application executable and link it.
/bin/rm -f /usr/local/bin/nodeagentd-*
/bin/touch /usr/local/bin/nodeagentd-*
/bin/cp -f /home/deployer/.deploy_tmp_*/* /usr/local/bin/nodeagentd-*
/bin/chmod 0755 /usr/local/bin/nodeagentd-*
/bin/rm -f /usr/local/bin/nodeagentd
/bin/ln -s /usr/local/bin/nodeagentd-* /usr/local/bin/nodeagentd
# Permission to place configuration files in /etc/nodeagentd and set permissions.
/bin/rm -f /etc/nodeagentd/*
/bin/touch /etc/nodeagentd/*
/bin/cp -f /home/deployer/.deploy_tmp_*/* /etc/nodeagentd/*
/bin/chmod 0600 /etc/nodeagentd/*
/bin/chmod 0644 /etc/nodeagentd/*
# Permission to place the systemd unit file.
/bin/rm -f /etc/systemd/system/nodeagentd.service
/bin/touch /etc/systemd/system/nodeagentd.service
/bin/cp -f /home/deployer/.deploy_tmp_*/* /etc/systemd/system/nodeagentd.service
/bin/chmod 0644 /etc/systemd/system/nodeagentd.service
# Permission to interact with systemd service.
/bin/systemctl daemon-reload
/bin/systemctl stop nodeagentd
/bin/systemctl start nodeagentd
/bin/systemctl enable --now nodeagentd
# Permission to remove the temporary files used for the deployment.
/bin/rm -f /home/deployer/.deploy_tmp_*/*
SSH 호스트 키 확인
모든 노드가 관리자 워크스테이션의 known_hosts 파일에 추가되었는지 확인합니다.
그렇지 않으면 --enforce-host-key-verify=false 플래그를 사용하여 배포 (nodeagent
deploy) 및 사용자 인증 정보 순환(nodeagent
rotate-credentials) 중에 호스트 키 확인을 사용 중지합니다.
노드 에이전트 포트 맞춤설정
노드 에이전트를 사용하면 포트를 맞춤설정할 수 있습니다. 배포 중에 --port 플래그를 사용하여 이 맞춤 포트를 지정합니다. 이렇게 하면 각 노드의 노드 에이전트 구성에 설정이 전파됩니다. 맞춤설정된 포트는 다음 메서드에 자세히 설명된 대로 클라이언트 측 구성과 일치해야 합니다.
기존 클러스터의 경우
실행 중인 기존 클러스터를 업데이트하려면 --port 플래그를 사용하여 새 맞춤 포트를 지정합니다. 이 설정은 클라이언트 (컨트롤러)에 전파됩니다.
새 클러스터의 경우
새 클러스터를 만들 때 클러스터 구성에 다음 주석을 추가하여 노드 에이전트의 맞춤 포트를 지정합니다.
kind: Cluster
metadata:
annotations:
baremetal.cluster.gke.io/node-agent-port: "10086"
성능
배포 및 사용 설정은 1분 이내에 완료됩니다. 인증 정보 순환 런타임은 표준 배포와 비슷하거나 더 빠릅니다.