Apigee Hybrid를 위한 Kubernetes용 Apigee 연산자 설치

이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.

Apigee Edge 문서 보기

이 페이지에서는 Apigee Hybrid를 위한 Kubernetes용 Apigee Operator를 설치하고 구성하는 데 필요한 단계를 설명합니다. Kubernetes용 Apigee Operator 사용의 이점에 대해 자세히 알아보려면 Kubernetes용 Apigee Operator 개요를 참고하세요.

Apigee Hybrid를 사용하지 않는 경우 Kubernetes용 Apigee Operator 설치를 참고하여 Apigee를 위한 Kubernetes용 Apigee Operator를 설치하세요.

시작하기 전에

시작하기 전에 다음 사항이 있는지 확인하세요.

필요한 역할

Kubernetes용 Apigee Operator를 설치하고 사용하는 데 필요한 리소스를 설정하는 데 필요한 권한을 얻으려면 관리자에게 조직에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

  • 서비스 계정 생성 및 관리: 서비스 계정 관리자(roles/iam.serviceAccountAdmin)
  • Apigee 리소스 생성 및 관리: Apigee 관리자(roles/apigee.admin)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할 또는 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

필수 설정 태스크

Kubernetes용 Apigee Operator를 설치하기 전에 다음 작업을 완료하여 이 기능을 사용하는 데 필요한 리소스를 설정해야 합니다.

  1. Apigee Hybrid 1.15.0 이상 버전을 사용하여 설치합니다. Apigee Hybrid 설치 안내는 전체 개요를 참조하세요.
  2. Istio Gateway를 지원하는 클라우드 제공업체(예: Google Cloud, Azure, Amazon)에서 Kubernetes 클러스터를 만듭니다.
  3. Kubernetes 클러스터에 Istio 게이트웨이를 설치합니다.
    • GKE 클러스터: 
      kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.1.0/standard-install.yaml
curl -L https://istio.io/downloadIstio | sh -
cd 1.6.11-asm.1
export PATH=$PWD/bin:$PATH
istioctl install --set profile=minimal --set values.global.platform=gke -y
    • 다른 제공업체의 클러스터: 
      kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.1.0/standard-install.yaml
curl -L https://istio.io/downloadIstio | sh -
cd 1.6.11-asm.1
export PATH=$PWD/bin:$PATH
istioctl install --set profile=minimal -y
  4. Kubernetes 클러스터에 Istio 게이트웨이를 배포합니다.
    1. 다음 콘텐츠를 포함한 gateway.yaml 파일을 생성하여 Istio Gateway를 배포합니다. 
      #gateway.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: istio-gateway
  namespace: default
  annotations:
    service.beta.kubernetes.io/port_80_health-probe_protocol: tcp
spec:
  gatewayClassName: istio
  listeners:
  - name: default
    hostname: "*.httpbin.com"
    port: 80
    protocol: HTTP
    allowedRoutes:
      namespaces:
        from: All
    2. 다음 명령어를 실행하여 해당 파일을 클러스터에 적용합니다.
      kubectl apply -f gateway.yaml

Istio 게이트웨이 설정 확인(선택사항)

이 가이드에서는 배포한 게이트웨이를 테스트하기 위해 기본 네임스페이스에 샘플 httpbin 애플리케이션을 배포할 것을 권장합니다.

  1. 게이트웨이를 테스트하기 위해 Kubernetes 클러스터에 백엔드 애플리케이션을 배포합니다.
    1. 다음 콘텐츠를 포함한 target.yaml 파일을 새로 만듭니다. 
      kubectl apply -f - <<EOF
apiVersion: v1
kind: ServiceAccount
metadata:
  name: httpbin
---
apiVersion: v1
kind: Service
metadata:
  name: httpbin
  labels:
    app: httpbin
    service: httpbin
spec:
  ports:
  - name: http
    port: 8000
    targetPort: 8080
  selector:
    app: httpbin
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: httpbin
spec:
  replicas: 1
  selector:
    matchLabels:
      app: httpbin
      version: v1
  template:
    metadata:
      labels:
        app: httpbin
        version: v1
    spec:
      serviceAccountName: httpbin
      containers:
      - image: docker.io/mccutchen/go-httpbin:v2.15.0
        imagePullPolicy: IfNotPresent
        name: httpbin
        ports:
        - containerPort: 8080
EOF
    2. HTTPRoute 리소스를 클러스터에 배포하여 게이트웨이의 트래픽을 백엔드 서비스에 매핑합니다.

      이 가이드의 목적상 HTTPRoute 만들기의 단계를 수행하여 외부 게이트웨이와 HTTPRoute를 배포하는 것이 좋습니다.

      HTTPRoute 리소스에 대한 자세한 내용은 HTTPRoute 배포(내부 게이트웨이의 경우) 또는 HTTPRoute 만들기(외부 게이트웨이의 경우)를 참조하세요.

      1. 다음 yaml 구성을 사용하여 HTTPRoute 만들기의 안내에 따라 HTTPRoute를 만듭니다. 
        apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: http-bin-route
  namespace: default
spec:
  parentRefs:
  - name: istio-gateway
    namespace: default
  hostnames: ["example.httpbin.com"]
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /get
    backendRefs:
    - name: httpbin
      port: 8000
      2. 클러스터에 파일을 적용합니다. 
        kubectl apply -f httproute.yaml
    3. GKE 게이트웨이 설정이 예상대로 작동하는지 확인합니다.
      1. 다음 명령어를 사용하여 게이트웨이 세부정보를 가져옵니다. 
        kubectl get gateway global-ext-lb1

        출력은 다음과 비슷하게 표시됩니다.

        NAME            CLASS   ADDRESS        PROGRAMMED   AGE
istio-gateway   istio   34.54.193.72   True         11d

        IP 주소가 게이트웨이에 할당되어 있고 PROGRAMMED 값이 True인지 확인합니다.

      2. 경로가 연결되었는지 확인할 게이트웨이를 설명합니다. 
        kubectl describe gateway istio-gateway

        출력은 다음과 비슷하게 표시됩니다.

        ...
  Listeners:
    Attached Routes: 1
    Conditions:
      Last Transition Time:  2024-10-03T03:10:17Z
...

        연결된 경로 값이 1인지 확인합니다. 이 값은 경로가 연결되어 있음을 나타냅니다.

      3. 요청을 게이트웨이에 보냅니다. 
        curl http://GATEWAY_IP_ADDRESS/get \
  -H "Host: example.httpbin.com"

        여기서 GATEWAY_IP_ADDRESS는 게이트웨이의 IP 주소입니다. 다음 명령어를 사용하여 게이트웨이 IP 주소를 검색할 수 있습니다. 여기서 GATEWAY_NAME은 게이트웨이 이름입니다.

        kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME -o=jsonpath="{.status.addresses.value}"

        예를 들면 다음과 같습니다.

        curl http://34.54.193.72/get -H "Host: example.httpbin.com"

        다음과 비슷한 응답이 표시됩니다.

        {
    "args": {},
    "headers": {
      "Accept": "*/*",
      "Host": "http://example.httpbin.com",
      "User-Agent": "curl/8.7.1",
      "X-Cloud-Trace-Context": "2bb8a80e29e80662ff9cb89971c447d9/13083106619927322701"
    },
    "origin": "67.164.1.10,34.54.193.72",
    "url": "http://example.httpbin.com/get"
}

    Kubernetes용 Apigee Operator 설치

    이 절차에서는 Kubernetes용 Apigee Operator를 설치하고 구성하는 데 필요한 단계를 설명합니다.

    Kubernetes용 Apigee Operator 설치 및 구성

    다음 섹션에서는 Kubernetes용 Apigee Operator를 설치하고 구성하는 데 필요한 단계를 설명합니다.

    1. 환경 변수를 설정합니다.
    2. APIM 서비스 계정을 만들고 구성합니다.
    3. Kubernetes용 Apigee Operator를 설치합니다.
    4. Apigee Hybrid 환경을 만듭니다.
    5. Helm을 사용하여 Apigee Hybrid 환경을 설치합니다.

    환경 변수 설정

    Apigee 인스턴스가 포함된 Google Cloud 프로젝트에서 다음 명령어를 사용하여 환경 변수를 설정합니다.

    export PROJECT_ID=PROJECT_ID
export APIGEE_ORG=APIGEE_ORG

    각 항목의 의미는 다음과 같습니다.

    • PROJECT_ID는 Apigee Hybrid 인스턴스가 있는 프로젝트의 ID입니다.
    • APIGEE_ORG는 Apigee Hybrid 인스턴스의 조직 이름입니다.

    다음 명령어를 사용하여 환경 변수가 올바르게 설정되었는지 확인합니다.

    echo $PROJECT_ID $APIGEE_ORG

    APIM 서비스 계정 만들기 및 구성

    Apigee Hybrid 구성 영역에 연결하기 위한 서비스 계정을 만듭니다.

    1. Google Cloud 서비스에 연결하기 위해 apigee-apim-gsa 서비스 계정을 만듭니다.
      2. gcloud iam service-accounts create apigee-apim-gsa
    2. 다음 명령어를 사용하여 만든 서비스 계정에 Apigee 관리자 역할을 부여합니다. 이 역할은 Apigee 리소스를 만들고 관리하는 데 필요합니다. 
      gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com" \
  --role "roles/apigee.admin"
    3. 서비스 계정에 대한 해당 JSON 키 파일을 다운로드합니다.
      1. 다음 명령어를 사용하여 $PROJECT_ID-apigee-apim-gsa.json 키 파일을 만들고 다운로드합니다. 
        gcloud iam service-accounts keys create $PROJECT_ID-apigee-apim-gsa.json \
  --iam-account=apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com
  --project=$PROJECT_ID
      2. 파일이 올바르게 다운로드되었는지 확인합니다. 
        ls $PROJECT_ID-apigee-apim-gsa.json

    Kubernetes용 Apigee Operator 설치

    Kubernetes 커스텀 리소스 정의(CRD)와 Kubernetes용 Apigee Operator를 설치합니다.

    1. Kubernetes용 Apigee Operator의 네임스페이스를 만듭니다. 
      kubectl create namespace apim
    2. Kubernetes용 Apigee Operator의 커스텀 리소스 정의(CRD)를 설치합니다. 
      helm install apigee-apim-crds -n apim \
  oci://us-docker.pkg.dev/apigee-release/apigee-k8s-tooling-helm-charts/apigee-apim-operator-crds \
  --version 1.1.0 \
  --atomic
    3. Kubernetes용 Apigee Operator를 설치합니다. 
      helm install apigee-apim-operator -n apim \
  oci://us-docker.pkg.dev/apigee-release/apigee-k8s-tooling-helm-charts/apigee-apim-operator-helm \
  --version 1.1.0 \
  --set serviceAccount=apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com \
  --set apigeeOrg=$APIGEE_ORG \
  --set apigeeEnv=ENV_NAME \
  --set-file serviceAccountKeyFileContent=$PROJECT_ID-apigee-apim-gsa-key.json \
  --atomic

      여기서 ENV_NAME은 Kubernetes용 Apigee Operator를 설치하려는 Apigee Hybrid 환경의 이름입니다.

    4. 설치가 성공적으로 완료되었는지 확인합니다. 
      helm list -n apim

      출력은 다음과 비슷하게 표시됩니다.

      NAME  NAMESPACE  REVISION  UPDATED  STATUS  CHART  APP VERSION
apigee-apim-crds  apim  1  2025-09-01 00:17:03.399810627 +0000 UTC  deployed  apigee-apim-operator-crds-1.1.0  1.1.0
apigee-apim-operator  apim  1  2025-09-01 00:15:00.362829981 +0000 UTC  deployed  apigee-apim-operator-helm-1.1.0  1.1.0
    5. 필요한 주석이 포함된 Kubernetes 서비스 계정(KSA)이 생성되었는지 확인합니다. 
      kubectl describe serviceaccounts apim-ksa -n apim

      출력은 다음과 비슷하게 표시됩니다.

      Name:                apim-ksa
Namespace:           apim
...
Annotations:         iam.gke.io/gcp-service-account: apigee-apim-gsa@my-project-id.iam.gserviceaccount.com
    6. Kubernetes 클러스터의 포드에서 Apigee 연산자가 실행되는지 확인합니다. 
      kubectl get pods -n apim

      출력은 다음과 비슷하게 표시됩니다.

      NAME  READY  STATUS  RESTARTS  AGE
apigee-apim-operator-8559d4994b-h55fl   1/1     Running   0   8m34s

      STATUS가 Running이 아니거나 READY에 1/1이 표시되지 않으면, 설치 문제 해결을 위해 Kubernetes용 Apigee 연산자 문제 해결을 참조하세요.

    Apigee Hybrid 환경 만들기

    Apigee Hybrid에서 Kubernetes용 Apigee 연산자를 사용하려면 서비스 확장을 위한 특수 플래그가 포함된 환경을 만들어야 합니다.

    1. Apigee API에 인증하기 위한 토큰을 가져옵니다.

      다음 예시와 같이 명령줄에서 gcloud 인증 사용자 인증 정보를 가져옵니다.

      TOKEN=$(gcloud auth print-access-token)

      토큰이 입력되었는지 확인하려면 다음 예시와 같이 echo를 사용합니다.

      echo $TOKEN

      그러면 토큰이 인코딩된 문자열로 표시됩니다.

      자세한 내용은 gcloud 명령줄 도구 개요를 참조하세요.

    2. 다음 명령어 중 하나를 사용하여 환경을 만듭니다.
      • 2021년 구독 조직의 경우:
        curl -X POST "https://apigee.googleapis.com/v1/organizations/$APIGEE_ORG/environments" -H \
  "Authorization: Bearer $TOKEN" -H "content-type:application/json" \
    -d '{
      "name": "ENV_NAME",
      "displayName": "ENV_DISPLAY_NAME",
      "state": "ACTIVE",
      "deploymentType": "PROXY",
      "apiProxyType": "PROGRAMMABLE",
      "properties": {
        "property": [
          {
            "name": "apigee-service-extension-enabled",
            "value": "true"
          }
        ]
      }
    }'

        여기서 ENV_NAME은 만들려는 환경의 이름입니다.

      • 2024년 구독 및 사용한 만큼만 지불 조직의 경우: 
        curl -i -X POST -H "Authorization: Bearer $TOKEN"  "https://apigee.googleapis.com/v1/organizations/$APIGEE_ORG/environments" -H "Content-Type:application/json" -d '{
  "name": "ENV_NAME",
  "displayName": "ENV_NAME",
  "state": "ACTIVE",
  "deploymentType": "PROXY",
  "apiProxyType": "PROGRAMMABLE",
  "type" : "ENV_TYPE",
  "properties": {
    "property": [
      {
        "name": "apigee-service-extension-enabled",
        "value": "true"
      }
    ]
  }
}'

        각 항목의 의미는 다음과 같습니다.

        • ENV_NAME은 만들려는 환경의 이름입니다.
        • ENV_TYPE은 만들려는 환경의 유형입니다. 예를 들면 INTERMEDIATE 또는 COMPREHENSIVE입니다.

      환경이 성공적으로 생성되었는지 확인합니다.

      curl -i -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$APIGEE_ORG/environments"

      자세한 내용은 Apigee Hybrid 설치 안내에서 환경 만들기를 참조하세요.

    3. 다음 명령어를 사용하여 환경 그룹을 만듭니다. 
      curl -i -X POST -H "Authorization: Bearer $TOKEN"  "https://apigee.googleapis.com/v1/organizations/$APIGEE_ORG/envgroups" -H "Content-Type:application/json" -d '{
     "name": "'"$ENV_GROUP"'",
     "hostnames":["'"$DOMAIN"'"]
   }'

      각 항목의 의미는 다음과 같습니다.

      • ENV_GROUP (필수) 환경 이름은 소문자, 대시, 숫자를 포함할 수 있으며 소문자로 시작해야 합니다. 이 이름은 식별자로 사용되며 생성 후에는 변경할 수 없습니다.
      • DOMAIN (필수) 이 그룹 내의 환경에 배포되는 모든 프록시에 사용될 호스트 이름입니다. 관리하는 도메인이어야 합니다. 주소는 example.com과 같은 도메인 자체일 수도 있고, my-proxies.example.com과 같이 하위 도메인을 포함할 수도 있습니다. 관리형 도메인이 없다면, 지금은 자리표시자를 입력해도 됩니다. 나중에 도메인 주소를 변경할 수 있습니다.

      자세한 내용은 Apigee Hybrid 설치 안내에서 환경 그룹 만들기를 참조하세요.

    4. 방금 만든 환경 그룹에 환경을 연결하려면 다음 명령어를 실행합니다. 
      curl -i -X POST -H "Authorization: Bearer $TOKEN"  "https://apigee.googleapis.com/v1/organizations/$APIGEE_ORG/envgroups/$ENV_GROUP/attachments" -H "Content-Type:application/json" -d '{
     "environment": "'"$ENV_NAME"'",
   }'

    Helm을 사용하여 Apigee Hybrid 환경 설치

    Apigee Hybrid 클러스터에 새 환경을 설치하는 절차는 기존에 다른 환경을 설치했던 방식과 유사합니다. 이 단계는 Apigee Hybrid가 설치된 Kubernetes 클러스터에 새 환경 및 환경 그룹 세부정보를 추가하는 데 필요합니다.

    1. 환경 그룹 도메인에 대한 TLS 인증서를 생성하려면 다음 명령어를 실행합니다. 
      openssl req -nodes -new -x509 -keyout $APIGEE_HELM_CHARTS_HOME/apigee-virtualhost/certs/keystore_$ENV_GROUP.key -out $APIGEE_HELM_CHARTS_HOME/apigee-virtualhost/certs/keystore_$ENV_GROUP.pem -subj "/CN=$DOMAIN" -addext "subjectAltName = DNS:$DOMAIN" -days 3650

      각 항목의 의미는 다음과 같습니다.

      • APIGEE_HELM_CHARTS_HOME (필수) Apigee Hybrid 설치 중에 Apigee Helm 차트를 다운로드한 디렉터리입니다.
    2. 다음 명령어를 사용하여 TLS 공개 인증서를 Base64로 인코딩합니다. 
      cat $APIGEE_HELM_CHARTS_HOME/apigee-virtualhost/certs/keystore_$ENV_GROUP.pem | base64 -w0 > $APIGEE_HELM_CHARTS_HOME/apigee-virtualhost/certs/keystore_$ENV_GROUP.pem.base64
    3. envs 아래에 다음 항목을 추가하여 overrides.yaml 파일을 업데이트합니다. 
      - name: ENV_NAME
  serviceAccountPaths:
    # Provide the path relative to the apigee-env chart directory.
    synchronizer: SYNCHRONIZER_SERVICE_ACCOUNT_FILEPATH
    # For example: "PROJECT_ID-apigee-synchronizer.json"
    runtime: RUNTIME_SERVICE_ACCOUNT_FILEPATH
    # For example: "PROJECT_ID-apigee-runtime.json"
    udca: UDCA_SERVICE_ACCOUNT_FILEPATH
    # For example: "PROJECT_ID-apigee-udca.json"

      여기서 *_SERVICE_ACCOUNT_FILEPATH(필수)는 Apigee Hybrid 설치 중에 사용한 서비스 계정의 json 키 파일입니다. 자세한 내용은 Apigee Hybrid 설치 안내의 재정의 만들기를 참조하세요.

    4. virtualhosts 아래에 다음 항목을 추가하여 overrides.yaml 파일을 수정합니다. 
      - name: 
  selector:
    app: apigee-ingressgateway
    ingress_name: INGRESS_NAME
  sslCertPath: certs/keystore_$ENV_GROUP.pem
  sslKeyPath: certs/keystore_$ENV_GROUP.key

      여기서 INGRESS_NAME(필수)은 배포에 사용되는 Apigee 인그레스 게이트웨이의 이름입니다. 자세한 내용은 여기를 참조하세요.

    5. 환경과 환경 그룹을 설치합니다.

      1. 환경을 설치합니다.

        한 번에 환경 하나만 설치해야 합니다. --set env=ENV_NAME으로 환경을 지정합니다. 셸에서 $ENV_NAME 환경 변수를 설정한 경우 이를 다음 명령어에 사용할 수 있습니다.

        테스트 실행을 수행합니다.

        helm upgrade ENV_RELEASE_NAME apigee-env/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  --set env=$ENV_NAME \
  -f overrides.yaml \
  --dry-run=server

          ENV_RELEASE_NAME은 apigee-env 차트 설치 및 업그레이드를 추적하는 데 사용되는 이름입니다. 이 이름은 설치 내 다른 Helm 출시 이름과 다르게 고유해야 합니다. 일반적으로 ENV_NAME과 동일합니다. 그러나 환경 이름이 환경 그룹 이름과 같으면 환경과 환경 그룹에 서로 다른 출시 이름(예: dev-env-release 및 dev-envgroup-release)을 사용해야 합니다. Helm의 출시에 관한 자세한 내용은 Helm 문서의 주요 개념 3가지를 참조하세요.

        차트를 설치합니다.

        helm upgrade ENV_RELEASE_NAME apigee-env/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  --set env=$ENV_NAME \
  -f overrides.yaml

        해당 환경의 상태를 확인하여 실행 중인지 확인합니다.

        kubectl -n APIGEE_NAMESPACE get apigeeenv

        NAME                    STATE       AGE   GATEWAYTYPE
apigee-org1-dev-1       running     2d
      2. 환경 그룹(virtualhosts)을 설치합니다.
        1. 한 번에 환경 그룹(virtualhost) 하나만 설치해야 합니다. --set envgroup=ENV_GROUP으로 환경 그룹을 지정합니다. 셸에서 $ENV_GROUP 환경 변수를 설정한 경우 이를 다음 명령어에 사용할 수 있습니다. overrides.yaml 파일에 언급된 환경 그룹마다 다음 명령어를 반복합니다.

          테스트 실행을 수행합니다.

          helm upgrade ENV_GROUP_RELEASE_NAME apigee-virtualhost/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  --set envgroup=$ENV_GROUP \
  -f overrides.yaml \
  --dry-run=server

            ENV_GROUP_RELEASE_NAME은 apigee-virtualhosts 차트 설치 및 업그레이드를 추적하는 데 사용되는 이름입니다. 이 이름은 설치 내 다른 Helm 출시 이름과 다르게 고유해야 합니다. 일반적으로 ENV_GROUP과 동일합니다. 그러나 환경 그룹 이름이 설치의 환경 이름과 같으면 환경 그룹과 환경에 서로 다른 출시 이름(예: dev-envgroup-release 및 dev-env-release)을 사용해야 합니다. Helm의 출시 버전에 대한 자세한 내용은 Helm 문서의 세 가지 주요 개념을 참조하세요.

          차트를 설치합니다.

          helm upgrade $ENV_GROUP_RELEASE_NAME apigee-virtualhost/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  --set envgroup=$ENV_GROUP \
  -f overrides.yaml

      이제 Apigee Hybrid 조직이 서비스 확장을 테스트할 새 환경과 함께 준비되었습니다.

      확장 정책을 만들려면 APIMExtensionPolicy 만들기의 절차를 계속 진행하세요.