Azure Kubernetes Service (AKS) 서비스 커넥터 사용

Azure Kubernetes Service (AKS) Service Connector에서 지원하는 컴퓨팅 서비스 중 하나입니다.

이 문서에서는 다음을 다룹니다.

AKS용 서비스 커넥터와 다른 컴퓨팅 서비스의 차이점
서비스 연결을 만드는 동안 클러스터에서 실행되는 작업입니다.
서비스 연결을 만드는 동안 대상 서비스에서 실행되는 작업입니다.
서비스 커넥터에서 만들어진 Kubernetes 리소스를 사용합니다.
AKS 클러스터에서 서비스 커넥터 로그 문제를 해결하고 확인합니다.

필수 구성 요소

이 가이드에서는 Service Connector의 기본 개념을 이미 알고 있다고 가정합니다.

AKS용 서비스 커넥터와 다른 컴퓨팅 서비스의 차이점

AKS용 서비스 커넥터는 여러 가지 방법으로 Service Connector에서 지원하는 다른 컴퓨팅 서비스와 작동하는 방식과 다릅니다. 다음은 각 API 작업에 대한 AKS 관련 옵션과 동작을 간략하게 설명합니다.

창작

AKS별 만들기 옵션은 아래와 같습니다. AKS에서 새 연결을 만드는 방법을 알아보려면 Azure 포털 또는 Azure CLI 빠른 시작을 참조하세요.

AKS용 서비스 커넥터에는 Kubernetes namespaceKubernetes 리소스를 만들 위치를 지정하는 매개 변수가 필요합니다. 기본적으로 네임스페이스를 default 사용합니다.
AKS용 서비스 커넥터는 보안 자격 증명 인증 옵션으로 Workload Identity을 지원하며, 다른 컴퓨팅 서비스는 System Managed Identity 및 User Managed Identity 옵션을 제공합니다.
비밀 저장소 CSI 드라이버를 사용하도록 설정된 대상 서비스로 Azure Key Vault 사용하는 경우 Service Connector는 사용자가 인증 유형을 지정할 필요 없이 인증을 위해 AKS azure-keyvault-secrets-provider 추가 기능의 사용자 할당 관리 ID를 사용합니다.
AKS용 서비스 커넥터는 Firewall Rules 네트워킹 옵션만 지원하는 반면, 다른 컴퓨팅 서비스는 Private Link 및 Virtual Network 옵션을 지원할 수 있습니다.

목록 구성

AKS용 서비스 커넥터는 목록 구성 보기에 자격 증명이 아닌 구성만 표시합니다. 사용자는 필요한 경우 연결된 Kubernetes 리소스 에서 자격 증명을 수동으로 확인해야 합니다.

Azure CLI 명령 az aks connection list-configuration을 사용하면 자격 증명 구성의 값이 빈 문자열입니다. Azure 포털에서 아래와 같이 자격 증명 구성의 값이 숨겨집니다.

AKS 연결 목록 구성의 스크린샷

유효성 검사

AKS용 서비스 커넥터는 자격 증명 구성이든 자격 증명이 아닌 구성이든 사용자 클러스터 내에서 변경된 구성 값의 유효성을 검사하지 않습니다. 그러나 서비스 커넥터는 다른 컴퓨팅 서비스와 마찬가지로 다음과 같은 유효성 검사를 수행합니다.

대상 서비스의 존재 여부 확인
대상 서비스에 액세스하기 위한 IP 방화벽 규칙 확인
대상 서비스에 액세스하기 위해 워크로드 ID에 대한 역할 할당 보장

Azure CLI 명령 az aks 연결 유효성 검사 출력은 항상 success. 아래와 같이 Azure 포털에도 동일하게 적용됩니다.

AKS 연결 유효성 검사의 스크린샷.

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

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

서비스 커넥터 Kubernetes 확장 추가

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

Azure 포털의 AKS 확장 뷰 스크린샷입니다.

클러스터 연결의 메타데이터도 확장에 저장됩니다. 확장을 제거하면 클러스터의 모든 연결을 사용할 수 없게 됩니다. 확장 연산자는 클러스터 네임스페이스에서 호스트됩니다 sc-system.

Kubernetes 리소스 만들기

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

Azure Portal의 Kubernetes 리소스 내 Service Connector 메뉴에서 각 서비스 연결에 대해 Service Connector에서 생성한 Kubernetes 리소스를 찾을 수 있습니다.

Azure 포털의 스크린샷으로, Service Connector에서 생성한 Kubernetes 리소스를 확인하는 모습입니다.

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

추가 기능 `azureKeyvaultSecretsProvider` 사용 설정

대상 서비스가 Azure Key Vault 비밀 저장소 CSI 드라이버를 사용하는 경우 Service Connector는 클러스터에 azureKeyvaultSecretsProvider 추가 기능을 사용하도록 설정합니다.

Azure 포털의 스크린샷으로, 연결을 생성할 때 keyvault에 대해 CSI 드라이버를 사용하도록 설정합니다.

CSI 드라이버 자습서 Azure Key Vault 연결 방법을 따라 Secret Store CSI 드라이버를 사용하여 Azure Key Vault에 대한 연결을 설정합니다.

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

인증 유형인 경우 Service Connector는 Workload Identity클러스터에 대한 워크로드 ID 및 OIDC 발급자를 사용하도록 설정합니다.

Azure 포털의 스크린샷, 워크로드 ID를 사용하여 연결을 생성하는 모습.

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

대상 서비스에서 서비스 커넥터가 수행하는 작업

AKS용 서비스 커넥터는 다른 컴퓨팅 서비스와 동일한 작업을 대상 서비스에서 수행합니다. 하지만 작업은 대상 서비스 형식과 인증 방법에 따라 달라집니다. 다음은 가능한 몇 가지 작업입니다.

연결 구성 가져오기

서비스 커넥터는 대상 서비스에서 필요한 연결 구성을 검색하여 사용자 클러스터의 Kubernetes 비밀로 설정합니다. 연결 구성은 대상 서비스 형식 및 인증 방법에 따라 달라집니다.

Connection String 인증 유형의 경우 구성에는 일반적으로 서비스 비밀 또는 connection string 포함됩니다.
Workload Identity 인증 유형의 경우 일반적으로 서비스 엔드포인트가 포함됩니다.
Service Principal 인증 유형의 경우 서비스 주체의 테넌트 ID, 클라이언트 ID 및 클라이언트 암호를 포함합니다.

특정 대상 서비스에 대한 자세한 내용은 Foundry 도구 가이드와 같은 해당 설명서를 참조하세요.

IP 기반 방화벽 규칙 만들기

서비스 커넥터는 AKS 클러스터에서 아웃바운드 공용 IP를 검색하고 대상 서비스에 IP 방화벽 규칙을 만들어 클러스터에서의 네트워크 액세스를 허용합니다.

Microsoft Entra ID 역할 할당 만들기

인증 유형을 사용하는 Workload Identity 경우 Service Connector는 ID에 대한 역할 할당을 자동으로 만듭니다. 적절한 액세스를 보장하기 위해 할당된 역할은 대상 서비스에 따라 다릅니다. 사용자는 필요에 따라 역할 할당을 사용자 지정할 수도 있습니다. 자세한 내용은 역할 사용자 지정을 참조하세요.

서비스 커넥터에서 만들어진 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
```

일반적인 오류 및 완화

확장 만들기 오류

오류 메시지:

Unable to get a response from the agent in time;
Extension pods can't be scheduled if all the node pools in the cluster are "CriticalAddonsOnly" tainted

완화:

확장 만들기 오류를 참조하세요.

Helm 오류

오류 메시지:

Unable to download the Helm chart from the repo URL

이 오류는 송신 차단 문제 외에도 클러스터와 방화벽 간에 발생하는 연결 문제로 인해 발생합니다. 이 문제를 해결하려면 Azure Kubernetes Service (AKS) 클러스터에 대한 아웃바운드 네트워크 및 FQDN 규칙을 참조하고 서비스 커넥터 Helm 차트를 끌어오는 데 필요한 FQDN을 추가합니다. mcr.microsoft.com

오류 메시지:

Timed out waiting for resource readiness
Helm chart rendering failed with given values
Resource already exists in your cluster
Operation is already in progress for Helm

완화:

Helm 오류 참조

충돌

오류 메시지:

Operation returned an invalid status code: Conflict;

이유:

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

완화:

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

권한 없는 리소스 액세스

오류 메시지:

You do not have permission to perform ... If access was recently granted, please refresh your credentials;

이유:

Service Connector를 사용하려면 사용자 대신 연결 작업을 수행하기 위해 연결하려는 Azure 리소스를 작동할 수 있는 권한이 필요합니다. 이 오류는 일부 Azure 리소스에 필요한 권한이 없음을 나타냅니다.

완화:

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

누락된 구독 등록

오류 메시지:

The subscription is not registered to use namespace 'Microsoft.KubernetesConfiguration'

이유:

서비스 커넥터를 사용하려면 구독이 Microsoft.KubernetesConfiguration에 등록되어야 합니다. Microsoft.KubernetesConfiguration는 Azure Arc 사용 가능한 Kubernetes 클러스터 확장을 위한 리소스 공급자입니다.

완화:

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

az provider register -n Microsoft.KubernetesConfiguration

다음 단계

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

스토리지 Blob을 통합하는 방법에 대해 알아보기

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-03-11

Azure Kubernetes Service (AKS) 서비스 커넥터 사용

필수 구성 요소

AKS용 서비스 커넥터와 다른 컴퓨팅 서비스의 차이점

창작

목록 구성

유효성 검사

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

서비스 커넥터 Kubernetes 확장 추가

Kubernetes 리소스 만들기

추가 기능 azureKeyvaultSecretsProvider 사용 설정

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

대상 서비스에서 서비스 커넥터가 수행하는 작업

연결 구성 가져오기

IP 기반 방화벽 규칙 만들기

Microsoft Entra ID 역할 할당 만들기

서비스 커넥터에서 만들어진 Kubernetes 리소스를 사용합니다.

Kubernetes 비밀

Kubernetes 서비스 계정

문제 해결 및 로그 보기

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

Kubernetes 클러스터 로그 확인

일반적인 오류 및 완화

확장 만들기 오류

Helm 오류

충돌

권한 없는 리소스 액세스

누락된 구독 등록

다음 단계

피드백

추가 리소스

추가 기능 `azureKeyvaultSecretsProvider` 사용 설정