이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Google Distributed Cloud(에어 갭 적용형) API 개요

Google Distributed Cloud (GDC) 에어 갭 적용형 애플리케이션 프로그래밍 인터페이스 (API)는 GDC 플랫폼 서비스의 프로그래매틱 인터페이스입니다. Google은 Kubernetes 리소스 모델 (KRM)을 사용하여 Kubernetes 위에 컨트롤 플레인 API를 빌드합니다. 컨트롤 플레인은 생성, 삭제, 업데이트와 같은 서비스의 리소스 관리를 실행합니다.

특정 서비스에는 이러한 API와 자체 데이터 영역 API(XML, JSON 또는 gRPC 기반)가 있습니다. 이 페이지에서는 각 섹션에서 이러한 서비스를 다룹니다.

GDC API 정보

GDC API에는 Kubernetes 기반 API와 그렇지 않은 API의 두 가지 유형이 있습니다. 많은 GDC API는 오픈소스 Kubernetes API의 확장 프로그램입니다. Kubernetes 커스텀 리소스를 사용하고 KRM을 사용합니다. 이러한 API는 Kubernetes API와 마찬가지로 HTTP 기반 RESTful API이며, JSON을 기본값으로 또는 Protobuf로 허용하고 반환합니다. API 엔드포인트는 관련 Kubernetes 서버입니다.

Vertex 사전 학습된 AI API와 같은 Kubernetes 기반이 아닌 다른 GDC API에는 자체 엔드포인트가 있습니다. HTTP를 지원하는 것 외에도 이러한 API 중 일부는 오픈소스 원격 프로시저 호출 프레임워크인 gRPC를 통해 액세스할 수도 있습니다. 특정 API에 관한 자세한 내용은 세로 탐색 메뉴의 전용 문서를 참고하세요.

GDC API에 액세스하려면 gdcloud CLI 도구 또는 GDC 콘솔을 사용하세요.

Kubernetes API 및 KRM 정보

많은 GDC API가 Kubernetes API의 확장 프로그램이고 KRM을 사용하므로 이러한 개념을 이해하면 GDC API를 최대한 활용할 수 있습니다.

Kubernetes API는 완전히 선언적이며 Kubernetes API의 모든 항목은 KRM을 따르는 리소스입니다. 인간과 머신 모두 API 클라이언트는 이러한 리소스에 대해 작동하며, 종종 만들기, 읽기, 업데이트, 삭제(CRUD) 작업을 사용합니다. Kubernetes 데이터베이스는 리소스를 저장하고 시스템의 상태를 나타냅니다. Kubernetes는 이러한 리소스를 지속적으로 감시하고 시스템의 실제 상태를 원하는 상태와 조정합니다. 예를 들어 Deployment 리소스를 업데이트하여 컨테이너의 복제본을 4개가 아닌 5개로 지정하면 Kubernetes는 원하는 복제본 수의 변경사항을 감지하고 컨테이너를 하나 더 만듭니다.

핵심 Kubernetes API의 경우 Kubernetes는 원하는 상태와 실제 상태 간의 조정을 직접 실행합니다. Kubernetes API 확장 프로그램은 핵심 Kubernetes API에 포함되지 않는 맞춤 리소스입니다. 맞춤 소프트웨어는 Kubernetes API를 지속적으로 감시하고 상호작용하며 조정을 실행합니다.

Kubernetes API 및 Kubernetes 리소스 모델에 대해 자세히 알아보려면 공식 Kubernetes 문서를 참고하세요.

Kubernetes API 개요(https://kubernetes.io/docs/reference/using-api/)
Kubernetes API 개념(https://kubernetes.io/docs/reference/using-api/api-concepts/)
Kubernetes 리소스 모델(KRM)(https://github.com/kubernetes/design-proposals-archive/blob/main/architecture/resource-management.md)

전역 및 영역별 API

GDC 에어갭의 리소스는 영역 리소스 또는 전역 리소스입니다. 영역별 리소스는 단일 영역 내에서 독립적으로 작동하며 영역별 서비스 중단은 해당 영역의 일부 또는 전체 리소스에 영향을 줄 수 있습니다. 전역 리소스는 내결함성을 위해 여러 영역에서 중복으로 작동합니다.

GDC 에어 갭은 GDC 리소스 유형을 모두 만들고 관리할 수 있는 두 가지 수준의 관리 플레인 API(전역 API 및 영역 API)를 제공합니다.

전역 API와 영역 API는 모두 서로 다른 엔드포인트에서 제공되는 Kubernetes 선언적 API이며 GDC 리소스는 API 서버에서 Kubernetes 커스텀 리소스로 표현됩니다. 전역 API 서버는 영역에 분산된 단일 etcd 클러스터를 공유하여 영역 API 서버에 비해 지연 시간이 길고 초당 쓰기 쿼리 수 (QPS)가 감소하는 대신 내결함성과 강력한 일관성을 제공합니다. 모든 조직에서 영역 관리 API 서버는 관리자와 개발자가 영역 리소스를 관리할 수 있는 영역 API를 제공하고, 전역 관리 API 서버는 다중 영역 리소스를 관리할 수 있는 전역 API를 제공합니다.

GDC API 액세스

gdcloud CLI 도구와 GDC 콘솔은 모두 GDC API를 활용합니다. GDC를 탐색하거나 일회성 작업을 실행하는 데 사용하는 것이 좋습니다. 하지만 GDC에 대한 자동 또는 프로그래매틱 액세스를 사용하는 경우 Google에서는 GDC API를 직접 사용하는 것이 좋습니다.

HTTP 및 gRPC 지원

대부분의 GDC API는 직접 호출하는 JSON HTTP 인터페이스를 제공합니다. Kubernetes 기반 API는 Kubernetes 클라이언트 라이브러리를 사용합니다. 일부 비 Kubernetes GDC API에는 성능과 사용성이 개선된 gRPC 인터페이스가 있습니다. Google에서는 Kubernetes를 기반으로 하지 않는 GDC API용 클라이언트 라이브러리도 제공합니다. gRPC에 대해 자세히 알아보려면 https://grpc.io/로 이동하세요.

TLS 암호화

모든 GDC API는 전송 계층 보안 (TLS) 암호화를 사용하는 요청을 수락합니다.

Kubernetes 또는 GDC 클라이언트 라이브러리 중 하나를 사용하는 경우 라이브러리에서 전송 중인 데이터 암호화를 처리합니다.
자체 HTTP 또는 gRPC 클라이언트를 사용하는 경우 TLS가 필요한 GDC로 인증해야 합니다. gRPC의 경우 https://grpc.io/docs/guides/auth/의 gRPC 인증 가이드에 나온 안내를 따르세요.

Kubernetes API 및 Kubernetes 기반 API 액세스

kubectl Kubernetes CLI는 Kubernetes API 및 Kubernetes 기반 API와 직접 상호작용하는 기본 방법입니다.

kubectl로 액세스

Kubernetes API에 처음 액세스할 때는 Kubernetes 명령줄 도구인 kubectl을 사용하세요.

클러스터에 액세스하려면 클러스터 위치 정보와 액세스할 수 있는 사용자 인증 정보가 필요합니다. 사용자 인증 정보에 액세스하는 방법을 알아보려면 로그인 섹션을 참고하세요.

현재 kubectl 구성을 검사하고 액세스할 수 있는 클러스터를 확인합니다.

kubectl config view

HTTP 클라이언트로 API에 직접 액세스

다음은 curl, wget 또는 브라우저와 같은 HTTP 클라이언트로 REST API에 직접 액세스하는 방법입니다.

프록시 모드에서 kubectl를 사용하여 인증을 처리합니다.
인증을 직접 처리합니다.

kubectl 프록시 실행

kubectl proxy 명령어는 역방향 프록시 역할을 하는 모드에서 kubectl를 실행합니다. 이 명령어는 apiserver에 연결하고 인증을 관리합니다.

프록시 모드에서 kubectl을 실행하면 저장된 API 서버 위치가 사용되고 인증서를 사용하여 API 서버의 ID가 확인됩니다. 이 메서드는 중간자 (MITM) 공격을 방지합니다.

다음 예는 kubectl proxy 명령어를 사용하는 방법을 보여줍니다.

kubectl proxy --port=8080 &

kubectl 프록시가 실행되면 다음과 같이 curl, wget 또는 브라우저로 API를 탐색할 수 있습니다.

$ curl http://localhost:8080/api/
{
  "versions": [
    "v1"
  ],
  "serverAddressByClientCIDRs": [
    {
      "clientCIDR": "0.0.0.0/0",
      "serverAddress": "10.0.1.149:443"
    }
  ]
}

kubectl 프록시 없이 실행

프록시 모드에서 kubectl를 실행하지 않으려면 인증 토큰을 API 서버에 직접 전달하면 됩니다.

kubeconfig 파일에 컨텍스트가 여러 개 있을 수 있으므로 액세스할 수 있는 모든 Kubernetes 클러스터를 나열합니다.
```
kubectl config view \
    -o jsonpath='{"Cluster name\tServer\n"}{range.clusters[*]}{.name}{"\t"}{.cluster.server}{"\n"}{end}'
```
이전 출력에서 상호작용할 Kubernetes 클러스터의 이름을 내보냅니다.
```
export CLUSTER_NAME="CLUSTER_NAME"
```

Kubernetes 클러스터 이름을 참조하는 API 서버를 설정합니다.

APISERVER=$(kubectl config view -o jsonpath="{.clusters[?(@.name==\"$CLUSTER_NAME\")].cluster.server}")

기본 서비스 계정의 토큰을 포함할 보안 비밀을 만듭니다.

kubectl apply -n NAMESPACE -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: default-token
  annotations:
    kubernetes.io/service-account.name: default
type: kubernetes.io/service-account-token
EOF

토큰 컨트롤러가 토큰으로 보안 비밀을 채울 때까지 기다립니다.

while ! kubectl describe secret default-token | grep -E '^token' >/dev/null; do
  echo "waiting for token..." >&2
  sleep 1
done

토큰 값을 설정합니다.

TOKEN=$(kubectl get secret $(kubectl get secrets | grep default | cut -f1 -d ' ')  \
    -o jsonpath='{.data.token}' | base64 --decode)

API에 액세스하려면 다음 예와 같이 HTTP 헤더 Authorization: Bearer $TOKEN을 추가하여 curl과 같은 도구로 토큰을 사용합니다.

$ curl -k $APISERVER/api --header "Authorization: Bearer $TOKEN"

출력은 다음과 비슷합니다.

{
  "kind": "APIVersions",
  "versions": [
    "v1"
  ],
  "serverAddressByClientCIDRs": [
    {
      "clientCIDR": "0.0.0.0/0",
      "serverAddress": "10.0.1.149:443"
    }
  ]
}