API 설정

IBM Cloud® Kubernetes Service API를 사용하여 커뮤니티 Kubernetes 또는 Red Hat OpenShift 클러스터를 작성하고 관리할 수 있습니다. CLI를 사용하려면 CLI 설정을 참조하십시오.

API 정보

IBM Cloud Kubernetes Service API는 앱에서 사용자에게 제공해야 하는 컴퓨팅, 네트워킹 및 스토리지 리소스를 보유하도록 IBM Cloud 인프라 리소스의 프로비저닝 및 관리를 자동화합니다.

이 API는 사용자가 클러스터를 생성할 수 있도록 지원하는 다양한 인프라 제공업체를 지원합니다. 자세한 정보는 인프라 제공자 개요 를 참조하십시오.

버전 2(v2) API를 사용하여 클래식 및 VPC 클러스터를 모두 관리할 수 있습니다. v2 API는 가능한 경우 기존 기능의 중단을 방지하도록 디자인되었습니다. 그러나 v1과 v2 API 간의 다음 차이점을 검토해야 합니다.

API 엔드포인트 접두부
v1 API: https://containers.cloud.ibm.com/global/v1
v2 API: https://containers.cloud.ibm.com/global/v2
v3 API: https://containers.cloud.ibm.com/global/v3
API 참조 문서
v1 및 v2 API
v3 API.
API 아키텍처 스타일
v1 API: GET, POST, PUT, PATCH 및 DELETE와 같은 HTTP 메소드를 통해 상호작용하는 리소스에 초점을 맞추는 REST(Representational State Transfer)입니다.
v2 API: GET 및 POST HTTP 메소드를 통한 조치에만 초점을 맞추는 원격 프로시저 호출(RPC)입니다.
지원되는 컨테이너 플랫폼
v1 API: IBM Cloud Kubernetes Service API를 사용하여 커뮤니티 Kubernetes 및 Red Hat OpenShift 클러스터 모두에 대해 작업자 노드와 같은 IBM Cloud 인프라 리소스를 관리합니다.
v2 API: IBM Cloud Kubernetes Service v2 API를 사용하여 커뮤니티 Kubernetes 및 Red Hat OpenShift VPC 클러스터 모두에 대해 작업자 노드와 같은 IBM Cloud 인프라 리소스를 관리합니다.
Kubernetes API
v1 API: Kubernetes API를 사용하여 팟(Pod) 또는 네임스페이스와 같은 클러스터 내에서 Kubernetes 리소스를 관리하려면 Kubernetes API를 사용하여 클러스터 작업을 참조하십시오.
v2 API: v1과(와) 동일합니다. Kubernetes API를 사용한 클러스터 작업을 참조하십시오.
인프라 유형별 지원되는 API
v1 API: classic
v2 API: vpc 및 classic
  • vpc 제공자는 다수의 VPC 하위 제공자를 지원하도록 디자인되었습니다. 지원되는 VPC 하위 제공자는 vpc-gen2이며, 2세대 컴퓨팅 리소스에 대한 VPC 클러스터에 해당합니다.
  • 제공자 특정 요청에는 URL의 경로 매개변수(예: v2/vpc/createCluster)가 포함되어 있습니다. 일부 API는 특정 제공자에서만 사용할 수 있습니다(예: 클래식의 경우, GET vlan 또는 VPC의 경우, GET vpcs).
  • 지정된 제공자에 대해서만 응답을 리턴하려는 경우, 제공자 중립 요청에는 일반적으로 JSON(예: {"provider": "vpc"} 형식으로 제공자 특정 본문 매개변수가 포함될 수 있습니다.
GET 응답
v1 API: 리소스 콜렉션에 대한 GET 메소드(예: GET v1/clusters)는 목록의 각 리소스에 대해 개별 리소스의 GET 메소드(예: GET v1/clusters/{idOrName})와 동일한 세부사항을 리턴합니다.
v2 API: 응답을 더 빠르게 리턴하기 위해 리소스 콜렉션에 대한 v2 GET 메소드(예: GET v2/clusters)는 개별 리소스에 대한 GET 메소드(예: GET v2/clusters/{idOrName})에 자세히 설명된 정보의 서브세트만 리턴합니다. 일부 목록 응답에는 리턴된 항목이 클래식 또는 VPC 인프라에 적용되는지 여부를 식별하기 위한 제공자 특성이 포함됩니다. 예를 들어, GET zones 목록은 클래식 인프라 제공자에서만 사용할 수 있는 mon01과 같은 일부 결과를 리턴하지만 us-south-01과 같은 다른 결과는 VPC 인프라 제공자에서만 사용할 수 있습니다.
클러스터, 작업자 노드 및 작업자 풀 응답
v1 API: 응답에는 GET 클러스터의 VLAN 및 작업자 응답과 같은 클래식 인프라 제공자와 관련된 정보만 포함됩니다.
v2 API: 리턴되는 정보는 인프라 제공자에 따라 다릅니다. 이러한 제공자 특정 응답의 경우, 요청에 제공자를 지정할 수 있습니다. 예를 들어, VPC 클러스터에는 VLAN이 없으므로 VLAN 정보를 리턴하지 않습니다. 대신, 서브넷 및 CIDR 네트워크 정보를 리턴합니다.

API로 클러스터 배치 자동화

IBM Cloud Kubernetes Service API를 사용하여 Kubernetes 클러스터의 작성, 배치 및 관리를 자동화할 수 있습니다.

IBM Cloud Kubernetes Service API는 헤더 정보가 필요합니다. 이 헤더 정보는 API 요청에 사용자가 제공해야 하며 사용하려는 API에 따라 다를 수 있습니다. API에 필요한 헤더 정보를 확인하려면 ‘ IBM Cloud Kubernetes Service ’ API 문서를 참조하십시오.

IBM Cloud Kubernetes Service의 인증을 수행하려면 IBM Cloud 인증 정보를 사용하여 생성되었으며 클러스터가 작성된 IBM Cloud 계정 ID가 포함된 IBM Cloud IAM(Identity and Access Management) 토큰을 제공해야 합니다. IBM Cloud의 인증 방법에 따라 IBM Cloud IAM 토큰의 작성을 자동화하기 위한 다음 옵션 중에서 선택할 수 있습니다.

비연합 ID
  • IBM Cloud API 키 생성: IBM Cloud 의 사용자 이름과 비밀번호를 사용하는 대신, IBM Cloud API 키를 사용할 수 있습니다. IBM Cloud API 키는 해당 키가 생성된 IBM Cloud 계정에 종속됩니다. IBM Cloud API 키를 동일한 IBM Cloud IAM 토큰의 다른 계정 ID와 결합할 수 없습니다. IBM Cloud API 키의 기반이 되는 계정 이외의 계정으로 작성된 클러스터에 액세스하려면 계정에 로그인하여 새 API 키를 생성해야 합니다.
  • IBM Cloud 사용자 이름 및 비밀번호: 이 주제의 단계에 따라 IBM Cloud IAM 액세스 토큰의 작성을 완전히 자동화할 수 있습니다.
연합 ID
  • IBM Cloud API 키 생성: IBM Cloud API 키는 생성된 IBM Cloud 계정에 따라 다릅니다. IBM Cloud API 키를 동일한 IBM Cloud IAM 토큰의 다른 계정 ID와 결합할 수 없습니다. IBM Cloud API 키의 기반이 되는 계정 이외의 계정으로 작성된 클러스터에 액세스하려면 계정에 로그인하여 새 API 키를 생성해야 합니다.
  • 일회성 패스코드 사용: 일회성 패스코드를 사용하여 IBM Cloud를 인증하는 경우, 일회성 패스코드를 검색하려면 웹 브라우저와의 수동 상호작용이 필요하므로 IBM Cloud IAM 토큰 작성을 완전히 자동화할 수 없습니다. IBM Cloud IAM 토큰 작성을 완전히 자동화하려면 대신 IBM Cloud API 키를 작성해야 합니다.
  • API 키: API 키를 생성하려면 IBM Cloud API 키를 생성하려면 다음과 같이 하세요.
    1. 메뉴 표시줄에서 관리 > **액세스(IAM)**를 클릭하십시오.
    2. 사용자 페이지를 클릭한 후 자신을 선택하십시오.
    3. API 키 분할창에서 IBM Cloud API 키 작성을 클릭하십시오.
    4. API 키의 이름 및 설명을 입력하고 작성을 클릭하십시오.
    5. 표시를 클릭하여 생성된 API를 보십시오.
    6. 새 IBM Cloud IAM 액세스 토큰의 검색에 사용할 수 있도록 API 키를 복사하십시오.

  1. IBM Cloud IAM 액세스 토큰을 작성하십시오. 요청에 포함되는 본문 정보는 사용하는 IBM Cloud 인증 방법에 따라 다릅니다.

    POST https://iam.cloud.ibm.com/identity/token
    헤더
    • Content-Type: application/x-www-form-urlencoded
    • Authorization: Basic Yng6Yng=: 여기서 Yng6Yng=은(는) 사용자 이름 bx 및 비밀번호 bx에 대한 URL로 인코딩된 권한과 동일합니다.
    IBM Cloud 사용자 이름 및 암호에 대한 본문
    • grant_type: password
    • username: IBM Cloud 사용자 이름입니다.
    • password: 사용자의 IBM Cloud 비밀번호입니다.
    IBM Cloud API 키에 대한 본문
    • grant_type: urn:ibm:params:oauth:grant-type:apikey
    • apikey: 사용자의 IBM Cloud API 키입니다.
    IBM Cloud 일회성 패스코드에 대한 본문
    • grant_type: urn:ibm:params:oauth:grant-type:passcode
    • passcode: 사용자의 IBM Cloud 일회성 패스코드입니다. ibmcloud login --sso를 실행하고 CLI 출력의 지시사항에 따라 웹 브라우저를 사용하여 일회성 패스코드를 검색하십시오.

    다음 예제는 이전 요청의 출력을 표시합니다.

    {
"access_token": "<iam_access_token>",
"refresh_token": "<iam_refresh_token>",
"token_type": "Bearer",
"expires_in": 3600,
"expiration": 1493747503
"scope": "ibm openid"
}

    API 출력의 ‘ access_token ’ 필드에서 ‘ IBM Cloud ’ IAM 토큰을 확인할 수 있습니다. 다음 단계에서 추가 헤더 정보를 검색할 수 있도록 IBM Cloud IAM 토큰을 기록해 두십시오.

  2. 작업하려는 IBM Cloud 계정의 ID를 검색하십시오. TOKEN 을 이전 단계에서 API 출력 결과의 access_token 필드에서 가져온 IBM Cloud IAM 토큰으로 대체하십시오. API 출력의 resources/metadata/guid 필드에서 IBM Cloud 계정의 ID를 찾을 수 있습니다.

    GET https://accounts.cloud.ibm.com/coe/v2/accounts
    헤더
    • Content-Type: application/json
    • Authorization: bearer TOKEN
    • Accept: application/json

    다음 예제는 이전 요청의 출력을 표시합니다.

    {
"next_url": null,
"total_results": 5,
"resources": [
    {
        "metadata": {
            "guid": "<account_ID>",
            "url": "/coe/v2/accounts/<account_ID>",
            "created_at": "2016-09-29T02:49:41.842Z",
            "updated_at": "2018-08-16T18:56:00.442Z",
            "anonymousId": "1111a1aa1a1111a1aa11aa11111a1111"
        },
        "entity": {
            "name": "<account_name>",

  3. 작업하려는 IBM Cloud 인증 정보 및 계정 ID가 포함된 새 IBM Cloud IAM 토큰을 생성하십시오.

    IBM Cloud API 키를 사용하는 경우에는 API 키가 작성된 IBM Cloud 계정 ID를 사용해야 합니다. 다른 계정의 클러스터에 액세스하려면, 이 계정에 로그인한 후 이 계정을 기반으로 한 IBM Cloud API 키를 생성하십시오.

    POST https://iam.cloud.ibm.com/identity/token
    헤더
    • Content-Type: application/x-www-form-urlencoded
    • Authorization: Basic Yng6Yng=: 여기서 Yng6Yng=은(는) 사용자 이름 bx 및 비밀번호 bx에 대한 URL로 인코딩된 권한과 동일합니다.
    IBM Cloud 사용자 이름 및 암호에 대한 본문
    • grant_type: password
    • username: IBM Cloud 사용자 이름입니다.
    • password: 사용자의 IBM Cloud 비밀번호입니다.
    • bss_account: 이전 단계에서 검색한 IBM Cloud 계정 ID입니다.
    IBM Cloud API 키에 대한 본문
    • grant_type: urn:ibm:params:oauth:grant-type:apikey
    • apikey: 사용자의 IBM Cloud API 키입니다.
    • bss_account: 이전 단계에서 검색한 IBM Cloud 계정 ID입니다.
    IBM Cloud 일회성 패스코드에 대한 본문
    • grant_type: urn:ibm:params:oauth:grant-type:passcode
    • passcode: 사용자의 IBM Cloud 패스코드입니다.
    • bss_account: 이전 단계에서 검색한 IBM Cloud 계정 ID입니다.

    다음 예제는 API 요청의 출력을 표시합니다.

    {
    "access_token": "<iam_token>",
    "refresh_token": "<iam_refresh_token>",
    "token_type": "Bearer",
    "expires_in": 3600,
    "expiration": 1493747503
}

    API 출력 결과의 ‘ access_token ’ 필드에서 ‘ IBM Cloud ’ IAM 토큰을, ‘ refresh_token ’ 필드에서 리프레시 토큰을 확인할 수 있습니다.

  4. 계정의 모든 클래식 또는 VPC 클러스터를 나열하십시오. 클러스터에 대해 Kubernetes API 요청을 실행하려는 경우, 작업할 클러스터의 ID 또는 이름을 기록해 두십시오. 클래식 클러스터를 나열하기 위한 예제 요청입니다.

    GET https://containers.cloud.ibm.com/global/v2/classic/getClusters
    헤더
    Authorization: bearer <iam_token>

    VPC 클러스터를 나열하는 예제 명령입니다.

    GET https://containers.cloud.ibm.com/global/v2/vpc/getClusters?provider=vpc-gen2
    헤더
    Authorization: IBM Cloud IAM 액세스 토큰(bearer <iam_token>).

  5. 지원되는 API 목록을 확인하려면 IBM Cloud Kubernetes Service API 설명서를 참조하세요.

자동화를 위해 API를 사용하는 경우 해당 응답 내의 파일이 아닌 API의 응답을 따라야 합니다. 예를 들어, 클러스터 텍스트에 대한 Kubernetes 구성 파일은 변경될 수 있으므로 GET /v1/clusters/{idOrName}/config 호출을 사용하는 경우 이 파일의 특정 컨텐츠를 기반으로 자동화를 빌드하지 마십시오.

Kubernetes API를 사용하여 클러스터 관련 작업 수행

IBM Cloud Kubernetes Service 에서 Kubernetes API 를 사용하여 클러스터와 상호 작용할 수 있습니다.

다음 지시사항을 수행하기 위해서는 Kubernetes 마스터의 퍼블릭 클라우드 서비스 엔드포인트에 연결하기 위한 클러스터의 공용 네트워크 액세스 권한이 필요합니다.

  1. “API를 사용하여 클러스터 배포 자동화” 문서의 단계에 따라 IBM Cloud IAM 액세스 토큰, IBM Cloud API 키, Kubernetes API 요청을 실행할 클러스터의 ID, 그리고 클러스터가 위치한 IBM Cloud Kubernetes Service 리전을 확인하십시오.

  2. IBM Cloud API 키를 사용하여 IBM Cloud IAM ID, IAM 액세스 및 IAM 새로 고침 토큰을 검색합니다. API 출력 결과에서 ‘ id_token ’ 필드에는 IAM ID 토큰이, ‘ access_token ’ 필드에는 IAM 액세스 토큰이, ‘ refresh_token ’ 필드에는 IAM 리프레시 토큰이 표시됩니다.

    POST https://iam.cloud.ibm.com/identity/token
    헤더
    • Content-Type: application/x-www-form-urlencoded
    • Authorization: Basic a3ViZTprdWJl a3ViZTprdWJl 이는 사용자 이름 kube 및 비밀번호 kube 에 대한 URL 로 인코딩된 인증 정보와 동일합니다.
    본문
    • grant_type: urn:ibm:params:oauth:grant-type:apikey
    • apikey: IBM Cloud API 키.

    다음 예제는 이전 API 요청의 출력을 표시합니다.

    {
"access_token": "<iam_access_token>",
"id_token": "<iam_id_token>",
"refresh_token": "<iam_refresh_token>",
"token_type": "Bearer",
"expires_in": 3600,
"expiration": 1553629664,
"refresh_token_expiration": 1761334993,
"scope": "ibm openid containers-kubernetes"
}

    또는 ibmcloud ks cluster config --cluster <cluster_name> --output json CLI 명령을 사용하면 id_token 및 refresh_token.

  3. 현재 ID로 클러스터에 액세스하려면 먼저 다음 요청을 실행해야 합니다.

    POST https://containers.cloud.ibm.com/global/v2/applyRBAC
    헤더
    Authorization: bearer <TOKEN> IBM Cloud 의 IAM 액세스 토큰
    본문
    cluster: <cluster_name_or_ID>

  4. RBAC 동기화는 비동기식이므로 동기화될 때까지 다음 요청을 실행하세요.

    GET https://containers.cloud.ibm.com/global/v2/getRBACStatus?cluster=<cluster_name_or_ID>

-H "권한 부여: ${BEARER2} " ``` Header : Authorization: bearer <TOKEN> Your IBM Cloud IAM access token

Example response. Ensure the output shows `synchronized:true`.

```json {: screen}
{"synchronized":true,"error":false}
```

  1. IAM 액세스 토큰 및 클러스터의 이름 또는 ID를 사용하여 Kubernetes 마스터에 대한 기본 서비스 엔드포인트의 URL을 검색하십시오. API 출력의 **masterURL**에서 URL을 찾을 수 있습니다.

    클러스터에 대해 퍼블릭 클라우드 서비스 엔드포인트만 또는 프라이빗 클라우드 서비스 엔드포인트만 사용으로 설정된 경우 masterURL에 대해 해당 엔드포인트가 나열됩니다. 클러스터에 대해 퍼블릭 및 프라이빗 클라우드 서비스 엔드포인트가 둘 다 사용으로 설정된 경우 masterURL에 대해 기본적으로 퍼블릭 클라우드 서비스 엔드포인트가 나열됩니다. 대신 프라이빗 클라우드 서비스 엔드포인트를 사용하려면 출력의 privateServiceEndpointURL 필드에서 URL을 찾으십시오.

    GET https://containers.cloud.ibm.com/global/v2/getCluster?cluster=<cluster_name_or_ID>
    헤더
    • Authorization: 사용자의 IBM Cloud IAM 액세스 토큰입니다.
    경로
    • <cluster_name_or_ID>: API를 사용하여 클러스터 배치 자동화에서 GET https://containers.cloud.ibm.com/global/v2/classic/getClusters 또는 GET https://containers.cloud.ibm.com/global/v2/vpc/getClusters?provider=vpc-gen2 API로 검색한 클러스터의 이름 또는 ID입니다.

    다음 예제는 퍼블릭 클라우드 서비스 엔드포인트 요청의 출력을 표시합니다.

    ...
"etcdPort": "31593",
"masterURL": "https://c2.us-south.containers.cloud.ibm.com:30422",
"ingress": {
    ...}

    다음 예제는 프라이빗 클라우드 서비스 엔드포인트 요청의 출력을 표시합니다.

    ...
"etcdPort": "31593",
"masterURL": "https://c2.private.us-south.containers.cloud.ibm.com:30422",
"ingress": {
    ...}

  2. 프라이빗 클라우드 서비스 엔드포인트를 사용하려면 먼저 VPN 연결에서 사설 네트워크로 라우팅할 수 있는 로드 밸런서 IP를 사용하여 프라이빗 클라우드 서비스 엔드포인트를 노출해야 합니다.

  3. 이전에 검색한 IAM ID 토큰을 사용하여 클러스터에 대한 Kubernetes API 요청을 실행하십시오. 예를 들어, 클러스터에서 실행되는 Kubernetes 버전을 나열하십시오.

    API 테스트 프레임워크에서 SSL 인증서 확인을 사용으로 설정한 경우 이 기능을 사용 안함으로 설정해야 합니다.

    GET <masterURL>/api
    헤더
    • Authorization: bearer <id_token>
    경로
    • <masterURL>: 이전 단계에서 검색한 Kubernetes 마스터의 서비스 엔드포인트입니다.

    다음 예제는 이전 API 요청의 출력을 표시합니다.

    {
	"kind": "APIVersions",
	"versions": [
		"v1"
	],
	"serverAddressByClientCIDRs": [
		{
			"clientCIDR": "0.0.0.0/0",
			"serverAddress": "xxx.xx.x.x:xxxx"
		}
	]
 }

  4. 최신 버전의 ‘ Kubernetes ’에서 지원되는 API 목록을 확인하려면 ‘ Kubernetes ’ API 문서를 참조하십시오. 클러스터의 Kubernetes 버전과 일치하는 API 문서를 사용해야 합니다. 최신 Kubernetes 버전을 사용하지 않는 경우 URL 끝에 사용자 버전을 추가하십시오. 예를 들어, 버전 1.12용 API 문서에 액세스하려면 v1.12를 추가하십시오.

API를 사용하여 IAM 액세스 토큰 새로 고침

API를 통해 발행된 모든 IBM Cloud IAM(Identity and Access Management) 액세스 토큰은 한 시간 후에 만료됩니다. IBM Cloud API에 대한 액세스가 보장되도록 사용자는 정기적으로 액세스 토큰을 새로 고쳐야 합니다.

시작하기 전에 새 액세스 토큰을 요청하는 데 사용할 수 있는 IBM Cloud API 키가 있는지 확인하세요.

새 IBM Cloud IAM 토큰을 받으려면 다음 단계를 따르세요.

  1. IBM Cloud API 키를 사용하여 새 IBM Cloud IAM 액세스 토큰을 생성합니다.

    POST https://iam.cloud.ibm.com/identity/token
    헤더
    • Content-Type: application/x-www-form-urlencoded
    본문
    • grant_type: urn:ibm:params:oauth:grant-type:apikey
    • apikey: IBM Cloud API 키.

    다음 예제는 이전 API 요청의 출력을 표시합니다.

    {
    "access_token": "<iam_token>",
    "refresh_token": "<iam_refresh_token>",
    "token_type": "Bearer",
    "expires_in": 3600,
    "expiration": 1493747503,
    "scope": "ibm openid"
}

    API 출력 결과의 ‘ access_token ’ 필드에서 새로운 IBM Cloud IAM 토큰을 확인할 수 있습니다.

  2. 이전 단계에서 생성한 토큰을 사용하여 IBM Cloud Kubernetes Service API 문서를 계속 살펴보십시오.