AKS(Azure Kubernetes Service)에서 서비스 커넥터를 사용하는 방법

아티클
10/16/2024

AKS(Azure Kubernetes Service)는 서비스 커넥터에서 지원하는 컴퓨팅 서비스 중 하나입니다. 이 문서는 다음 내용에 대한 이해를 돕기 위해 작성되었습니다.

서비스 연결을 만들 때 클러스터에서 수행되는 작업.
서비스 커넥터가 만드는 kubernetes 리소스를 사용하는 방법.
AKS 클러스터에서 서비스 커넥터의 문제를 해결하고 로그를 확인하는 방법.

필수 조건

이 가이드에서는 서비스 커넥터의 기본 개념을 이미 알고 있다고 가정합니다.

서비스 커넥터가 클러스터에서 수행하는 작업

서비스 연결을 만들 때 선택한 다양한 대상 서비스 및 인증 유형에 따라 서비스 커넥터는 AKS 클러스터에서 서로 다른 작업을 수행합니다. 다음은 서비스 커넥터가 수행할 수 있는 작업을 나열합니다.

서비스 커넥터 kubernetes 확장 프로그램 추가

서비스 연결을 처음 만들 때 sc-extension이라고 명명된 kubernetes 확장 프로그램이 클러스터에 추가됩니다. 나중에 이 확장 프로그램은 서비스 연결 요청이 서비스 커넥터로 올 때마다 사용자의 클러스터에서 kubernetes 리소스를 만드는 데 도움이 됩니다. Azure Portal의 AKS 클러스터에 있는 이 확장 프로그램은 확장 프로그램 + 애플리케이션 메뉴에서 찾을 수 있습니다.

AKS 확장 프로그램을 확인하는 Azure Portal의 스크린샷.

또한 이 확장 프로그램은 클러스터 연결 메타데이터가 저장되는 위치이기도 합니다. 이 확장 프로그램을 제거하면 클러스터의 모든 연결을 사용할 수 없게 됩니다. 확장 연산자는 클러스터 네임스페이스 sc-system에서 호스트됩니다.

Kubernetes 리소스 만들기

서비스 커넥터는 서비스 연결을 만들 때 사용자가 지정한 네임스페이스에 일부 kubernetes 리소스를 만듭니다. Kubernetes 리소스는 사용자의 워크로드 정의 또는 애플리케이션 코드가 대상 서비스와 통신하는 데 필요한 연결 정보를 저장합니다. 다양한 인증 유형에 따라 서로 다른 kubernetes 리소스가 만들어집니다. Connection String 및 Service Principal 인증 유형의 경우 kubernetes 비밀이 만들어집니다. Workload Identity 인증 유형의 경우 kubernetes 비밀 외에 kubernetes 서비스 계정도 만들어집니다.

Kubernetes 리소스의 Azure Portal에서 각 서비스 연결에 대해 서비스 커넥터가 만든 kubernetes 리소스는 서비스 커넥터 메뉴에서 찾을 수 있습니다.

서비스 커넥터가 만든 kubernetes 리소스를 확인하는 Azure Portal의 스크린샷.

서비스 연결을 삭제해도 연결된 Kubernetes 리소스는 삭제되지 않습니다. 필요한 경우 kubectl delete 같은 명령을 사용하여 리소스를 수동으로 제거합니다.

`azureKeyvaultSecretsProvider` 추가 기능 사용

대상 서비스가 Azure Key Vault이고 서비스 연결을 만들 때 비밀 저장소 CSI 드라이버를 사용하도록 설정된 경우, 서비스 커넥터는 해당 클러스터에 대해 azureKeyvaultSecretsProvider 추가 기능을 사용하도록 설정합니다.

연결을 만들 때 Keyvault에 대해 CSI 드라이버를 사용하도록 설정하는 Azure Portal의 스크린샷.

CSI 드라이버를 사용하여 Azure Key Vault에 연결하기에 대한 자습서를 따라서, 비밀 저장소 CSI 드라이버를 사용하여 Azure Key Vault에 대한 연결을 설정합니다.

워크로드 ID 및 OIDC(OpenID Connect) 발급자 사용

서비스 연결을 만들 때 인증 유형이 Workload Identity인 경우 서비스 커넥터는 클러스터에 대한 워크로드 ID 및 OIDC 발급자를 사용하도록 설정합니다.

연결을 만들기 위해 워크로드 ID를 사용하는 Azure Portal의 스크린샷.

인증 유형이 Workload Identity인 경우 페더레이션 ID 자격 증명을 만들려면 사용자가 할당한 관리 ID가 필요합니다. 워크로드 ID는 무엇인가에서 자세히 알아보거나, 해당 자습서를 따라서 워크로드 ID를 사용하여 Azure Storage에 대한 연결을 설정합니다.

서비스 커넥터가 만든 kubernetes 리소스를 사용하는 방법

대상 서비스 유형 및 인증 유형이 다양한 경우 서로 다른 kubernetes 리소스가 만들어집니다. 다음 섹션은 클러스터 워크로드 정의 및 애플리케이션 코드에서, 서비스 커넥터가 만든 kubernetes 리소스를 사용하는 방법을 보여 줍니다.

Kubernetes 비밀

인증 유형이 Connection String 또는 Service Principal인 경우 kubernetes 비밀이 만들어집니다. 클러스터 워크로드 정의는 비밀을 직접 참조할 수 있습니다. 다음 코드 조각은 예제입니다.

apiVersion: batch/v1
kind: Job
metadata:
  namespace: default
  name: sc-sample-job
spec:
  template:
    spec:
      containers:
      - name: raw-linux
        image: alpine
        command: ['printenv']
        envFrom:
          - secretRef:
              name: <SecretCreatedByServiceConnector>
      restartPolicy: OnFailure

그런 다음 애플리케이션 코드는 환경 변수의 비밀에 있는 연결 문자열을 사용할 수 있습니다. 샘플 코드를 확인하면, 환경 변수 이름에 대해 그리고 애플리케이션 코드 에서 해당 이름을 사용하여 다른 대상 서비스에 인증하는 방법에 대해 자세히 알아볼 수 있습니다.

Kubernetes 서비스 계정

인증 유형이 Workload Identity이면 kubernetes 서비스 계정과 비밀이 모두 만들어집니다. 클러스터 워크로드 정의는 이런 서비스 계정과 비밀을 참조하여 워크로드 ID를 통해 인증할 수 있습니다. 다음의 코드 조각이 예를 제공합니다.

apiVersion: batch/v1
kind: Job
metadata:
  namespace: default
  name: sc-sample-job
  labels:
    azure.workload.identity/use: "true"
spec:
  template:
    spec:
      serviceAccountName: <ServiceAccountCreatedByServiceConnector>
      containers:
      - name: raw-linux
        image: alpine
        command: ['printenv']
        envFrom:
          - secretRef:
              name: <SecretCreatedByServiceConnector>
      restartPolicy: OnFailure

워크로드 ID를 사용하여 Azure Storage에 연결하는 방법을 알아보려면 해당 자습서를 확인할 수 있습니다.

문제 해결 및 로그 확인 방법

서비스 연결을 만들 때 오류가 발생하고 다시 시도해도 완화할 수 없는 경우, 다음 방법을 사용하면 문제 해결을 위한 자세한 정보를 수집하는 데 도움이 될 수 있다.

서비스 커넥터 kubernetes 확장 프로그램 확인

서비스 커넥터 kubernetes 확장 프로그램은 Azure Arc 지원 Kubernetes 클러스터 확장 프로그램을 기반으로 구축됩니다. 다음 명령을 사용하여 확장 프로그램의 설치 또는 업데이트 중에 오류가 발생했는지 조사합니다.

k8s-extension Azure CLI 확장을 설치합니다.

az extension add --name k8s-extension

서비스 커넥터 확장 프로그램 상태를 가져옵니다. 명령 출력의 statuses 속성을 확인하여 오류가 있는지 확인합니다.

az k8s-extension show \
    --resource-group MyClusterResourceGroup \
    --cluster-name MyCluster \
    --cluster-type managedClusters \
    --name sc-extension

Kubernetes 클러스터 로그 확인

확장 프로그램 설치 중에 오류가 발생하고 statuses 속성의 오류 메시지가 발생한 일에 대한 충분한 정보를 제공하지 않는 경우, 다음 단계를 사용하여 kubernetes 로그를 추가로 확인할 수 있습니다.

AKS 클러스터에 연결합니다.

az aks get-credentials \
    --resource-group MyClusterResourceGroup \
    --name MyCluster

서비스 커넥터 확장 프로그램은 helm 차트를 통해 네임스페이스 sc-system에 설치되며, 다음 명령을 통해 네임스페이스 및 helm 릴리스를 확인합니다.
- 네임스페이스가 존재하는지 확인합니다.
```
kubectl get ns
```
- Helm 릴리스 상태를 확인합니다.
```
helm list -n sc-system
```
확장 프로그램의 설치 또는 업데이트 중에 sc-job이라는 kubernetes 작업은 서비스 연결을 위해 kubernetes 리소스를 만듭니다. 일반적으로 작업 실행이 실패하면 확장 프로그램의 오류가 발생합니다. 다음 명령을 실행하여 작업 상태를 확인합니다. sc-job이 sc-system 네임스페이스에 없으면 해당 작업은 성공적으로 실행되었을 것입니다. 이 작업은 성공적으로 실행된 후 자동으로 삭제되도록 설계되었습니다.
- 작업이 존재하는지 확인합니다.
```
kubectl get job -n sc-system
```
- 작업 상태를 가져옵니다.
```
kubectl describe job/sc-job -n sc-system
```
- 작업 로그를 확인합니다.
```
kubectl logs job/sc-job -n sc-system
```

일반적인 오류 및 완화

충돌

오류 메시지:Operation returned an invalid status code: Conflict.

이유: 이 오류는 일반적으로 AKS(Azure Kubernetes Service) 클러스터가 업데이트 상태인 동안 서비스 연결을 만들려고 할 때 발생합니다. 서비스 연결 업데이트가 진행 중인 업데이트와 충돌합니다. 구독이 리소스 공급자에 Microsoft.KubernetesConfiguration 대해 등록되지 않은 경우에도 발생할 수 있습니다.

해결 방법:

다음 명령을 실행하여 구독이 Microsoft.KubernetesConfiguration 리소스 공급자에 등록되었는지 확인합니다.
```
az provider register -n Microsoft.KubernetesConfiguration
```
클러스터가 "성공" 상태인지 확인하고 만들기를 다시 시도하세요.

시간 제한

오류 메시지:

Long running operation failed with status 'Failed'. Unable to get a response from the Agent in time.
Timed out waiting for the resource to come to a ready/completed state

이유: 이 오류는 리소스 제한 또는 기타 문제로 인해 Service Connector 클러스터 확장을 만들거나 업데이트하는 데 사용되는 Kubernetes 작업이 예약되지 않을 때 종종 발생합니다.

완화: Kubernetes 클러스터 로그를 확인하여 자세한 이유를 식별하고 해결합니다. 일반적인 문제는 선점으로 인해 사용할 수 있는 노드가 없다는 것입니다. 이 경우 노드를 더 추가하거나 노드에 대해 자동 스케일링을 사용하도록 설정하는 것이 좋습니다.

권한 없는 리소스 액세스

오류 메시지:You do not have permission to perform ... If access was recently granted, please refresh your credentials.

이유: 서비스 커넥터는 사용자를 대신하여 연결 작업을 수행하기 위해 연결하려는 Azure 리소스를 작동할 수 있는 권한이 필요합니다. 이 오류는 일부 Azure 리소스에 필요한 권한이 부족함을 나타냅니다.

완화: 오류 메시지에 지정된 Azure 리소스에 대한 사용 권한을 확인합니다. 필요한 권한을 얻고 만들기를 다시 시도합니다.

누락된 구독 등록

오류 메시지The subscription is not registered to use namespace 'Microsoft.KubernetesConfiguration':

이유: 서비스 커넥터를 사용하려면 Azure Arc 지원 Kubernetes 클러스터 확장 리소스 공급자인 Microsoft.KubernetesConfiguration의 구독을 등록해야 합니다.

완화: 다음 명령을 실행하여 Microsoft.KubernetesConfiguration 리소스 공급자를 등록합니다. 리소스 공급자 등록 오류에 대한 자세한 내용은 이 자습서를 참조하세요.

az provider register -n Microsoft.KubernetesConfiguration

기타 문제

위의 완화 방법으로 문제가 해결되지 않으면 서비스 커넥터 클러스터 확장을 제거한 다음 만들기를 다시 시도하여 다시 설정해 보세요. 이 메서드는 서비스 커넥터 클러스터 확장과 관련된 대부분의 문제를 해결하기 위한 것입니다.

다음 CLI 명령을 사용하여 확장을 다시 설정합니다.

az extension add --name k8s-extension

az k8s-extension delete \
    --resource-group <MyClusterResourceGroup> \
    --cluster-name <MyCluster> \
    --cluster-type managedClusters \
    --name sc-extension

다음 단계

다른 대상 서비스를 통합하는 방법을 알아보고 해당 구성 설정 및 인증 방법에 대해 읽어보세요.

스토리지 BLOB을 통합하는 방법 알아보기

다음을 통해 공유

AKS(Azure Kubernetes Service)에서 서비스 커넥터를 사용하는 방법

필수 조건

서비스 커넥터가 클러스터에서 수행하는 작업

서비스 커넥터 kubernetes 확장 프로그램 추가

Kubernetes 리소스 만들기

`azureKeyvaultSecretsProvider` 추가 기능 사용

워크로드 ID 및 OIDC(OpenID Connect) 발급자 사용

서비스 커넥터가 만든 kubernetes 리소스를 사용하는 방법

Kubernetes 비밀

Kubernetes 서비스 계정

문제 해결 및 로그 확인 방법

서비스 커넥터 kubernetes 확장 프로그램 확인

Kubernetes 클러스터 로그 확인

일반적인 오류 및 완화

충돌

시간 제한

권한 없는 리소스 액세스

누락된 구독 등록

기타 문제

다음 단계

피드백

추가 리소스

다음을 통해 공유

AKS(Azure Kubernetes Service)에서 서비스 커넥터를 사용하는 방법

필수 조건

서비스 커넥터가 클러스터에서 수행하는 작업

서비스 커넥터 kubernetes 확장 프로그램 추가

Kubernetes 리소스 만들기

azureKeyvaultSecretsProvider 추가 기능 사용

워크로드 ID 및 OIDC(OpenID Connect) 발급자 사용

서비스 커넥터가 만든 kubernetes 리소스를 사용하는 방법

Kubernetes 비밀

Kubernetes 서비스 계정

문제 해결 및 로그 확인 방법

서비스 커넥터 kubernetes 확장 프로그램 확인

Kubernetes 클러스터 로그 확인

일반적인 오류 및 완화

충돌

시간 제한

권한 없는 리소스 액세스

누락된 구독 등록

기타 문제

다음 단계

피드백

추가 리소스

`azureKeyvaultSecretsProvider` 추가 기능 사용