istioctl 실무 치트시트: Istio 서비스 메시 진단과 설정

💡 핵심 요약 (Executive Summary)

본 가이드는 istioctl 핵심 가이드 및 실전 아키텍처의 핵심 개념, 실전 구성 명령어 및 아키텍처 베스트 프랙티스를 다룹니다. 클라우드 네이티브 및 인프라 엔지니어링 실무에 즉시 활용 가능하도록 체계적으로 정리했습니다.

📑 Table of Contents

Linked Page

Cluster Control

install

Istio 매니페스트를 적용하여 클러스터에 Istio를 설치하거나 재구성합니다.

uninstall

클러스터에서 Istio 제거

upgrade

Istio 제어 영역을 즉시 업그레이드

manifest

Istio 매니페스트 관련 명령

bash
istioctl diff        #Compare manifests and generate diff
istioctl generate    #Generates an Istio install manifest
istioctl install     #Applies an Istio manifest, installing or reconfiguring Istio on a cluster.
operator

Istio 운영자 컨트롤러와 관련된 명령입니다.

bash
istioctl operator dump
remote-clusters

각 istiod 인스턴스가 연결된 원격 클러스터를 나열합니다.

bash
istioctl remote-clusters

Istio Management

admin

control plane (istiod) 구성관리

bash
#Aliases: admin, istiod
istioctl admin log
kube-inject

Kubernetes Pod 리소스에 Istio 사이드카 삽입

bash
Examples:
  # Update resources on the fly before applying.
  kubectl apply -f <(istioctl kube-inject -f <resource.yaml>)

  # Create a persistent version of the deployment with Istio sidecar injected.
  istioctl kube-inject -f deployment.yaml -o deployment-injected.yaml

  # Update an existing deployment.
  kubectl get deployment -o yaml | istioctl kube-inject -f - | kubectl apply -f -

  # Capture cluster configuration for later use with kube-inject
  kubectl -n istio-system get cm istio-sidecar-injector  -o jsonpath="{.data.config}" > /tmp/inj-template.tmpl
  kubectl -n istio-system get cm istio -o jsonpath="{.data.mesh}" > /tmp/mesh.yaml
  kubectl -n istio-system get cm istio-sidecar-injector -o jsonpath="{.data.values}" > /tmp/values.json

  # Use kube-inject based on captured configuration
  istioctl kube-inject -f samples/bookinfo/platform/kube/bookinfo.yaml \
    --injectConfigFile /tmp/inj-template.tmpl \
    --meshConfigFile /tmp/mesh.yaml \
    --valuesFile /tmp/values.json


Flags:
      --authority string           XDS Subject Alternative Name (for example istiod.istio-system.svc)
      --cert-dir string            XDS Endpoint certificate directory
  -f, --filename string            Input Kubernetes resource filename
  -h, --help                       help for kube-inject
      --injectConfigFile string    Injection configuration filename. Cannot be used with --injectConfigMapName
      --insecure                   Skip server certificate and domain verification. (NOT SECURE!)
      --meshConfigFile string      Mesh configuration filename. Takes precedence over --meshConfigMapName if set
      --meshConfigMapName string   ConfigMap name for Istio mesh configuration, key should be "mesh" (default "istio")
      --operatorFileName string    Path to file containing IstioOperator custom resources. If configs from files like meshConfigFile, valuesFile are provided, they will be overridden by iop config values.
  -o, --output string              Modified output Kubernetes resource filename
      --plaintext                  Use plain-text HTTP/2 when connecting to server (no TLS).
  -r, --revision string            Control plane revision
      --timeout duration           The duration to wait before failing (default 30s)
      --valuesFile string          Injection values configuration filename.
      --webhookConfig string       MutatingWebhookConfiguration name for Istio (default "istio-sidecar-injector")
      --xds-address string         XDS Endpoint
      --xds-label string           Istiod pod label selector
      --xds-port int               Istiod pod port (default 15012)
profile

Istio Configuration 프로필과 관련된 명령

bash
# 목록 조회
istioctl profile list

# 현재 프로필 조회
istioctl profile dump
# 특정 프로필 조회
istioctl profile dump $profile

# 두 프로필 비교
istioctl profile diff $profile1 $profile2
tag

개정 태그와 상호 작용하는 데 사용되는 명령 그룹

bash
istioctl tag list
create-remote-secret

Istio가 원격 Kubernetes apiserver에 액세스할 수 있도록 자격 증명이 포함된 비밀을 만듭니다.

bash
Examples:
  # Create a secret to access cluster c0's apiserver and install it in cluster c1.
  istioctl --kubeconfig=c0.yaml create-remote-secret --name c0 \
    | kubectl --kubeconfig=c1.yaml apply -f -

  # Delete a secret that was previously installed in c1
  istioctl --kubeconfig=c0.yaml create-remote-secret --name c0 \
    | kubectl --kubeconfig=c1.yaml delete -f -

  # Create a secret access a remote cluster with an auth plugin
  istioctl --kubeconfig=c0.yaml create-remote-secret --name c0 --auth-type=plugin --auth-plugin-name=gcp \
    | kubectl --kubeconfig=c1.yaml apply -f -

Flags:
      --auth-plugin-config stringToString   Authenticator plug-in configuration. --auth-type=plugin must be set with this option (default [])
      --auth-plugin-name string             Authenticator plug-in name. --auth-type=plugin must be set with this option
      --auth-type RemoteSecretAuthType      Type of authentication to use. supported values = [bearer-token plugin] (default bearer-token)
      --create-service-account              If true, the service account needed for creating the remote secret will be created if it doesn't exist. (default true)
  -h, --help                                help for create-remote-secret
  -d, --manifests string                    Specify a path to a directory of charts and profiles
                                            (e.g. ~/Downloads/istio-1.21.1/manifests).
      --name string                         Name of the local cluster whose credentials are stored in the secret. If a name is not specified the kube-system namespace's UUID of the local cluster will be used.
      --secret-name string                  The name of the specific secret to use from the service-account. Needed when there are multiple secrets in the service account.
      --server string                       The address and port of the Kubernetes API server.
      --service-account string              Create a secret with this service account's credentials. Default value is "istio-reader-service-account" if --type is "remote", "istiod" if --type is "config".
      --type SecretType                     Type of the generated secret. supported values = [remote config] (default remote)
dashboard

Istio 웹 UI에 대한 액세스

sql
#Aliases: d

istioctl d controlz      -- Open ControlZ web UI
istioctl d istiod-debug  -- Open Istio debug web UI
istioctl d envoy         -- Open Envoy admin web UI
istioctl d proxy         -- Open admin web UI for a proxy

istioctl d grafana       -- Open Grafana web UI using "app.kubernetes.io/name=grafana"
istioctl d jaeger        -- Open Jaeger web UI using "app=jaeger"
istioctl d kiali         -- Open Kiali web UI
istioctl d prometheus    -- Open Prometheus web UI
istioctl d skywalking    -- Open SkyWalking UI
istioctl d zipkin        -- Open Zipkin web UI
bash
#istiod
istioctl dashboard controlz deploy/istiod
istioctl dashboard istiod-debug deploy/istiod

#envoy description #pod
istioctl dashboard envoy postgresql-0.datastore
Test Commands
bash
## Istio 설치 상태 확인
istioctl verify-install

## 클러스터 정보 및 로그 캡처 지원 도구입니다.
istioctl bug-report

## Istio 구성 분석 및 검증 메시지 인쇄
istioctl analyze -n $namespace

## Istio policy 및 rules 파일 검증
#Aliases: validate, v
istioctl validate -f $policy_or_rules_yaml
istioctl v -f $policy_or_rules_yaml

Proxy

proxy-config

Aliases: proxy-config, pc

Envoy에서 프록시 구성에 대한 정보 검색[kube에만 해당]

cluster
bash
#gateway pod로 cluster proxy config 조회
#Aliases: cluster, clusters, c
## 전체 조회
istioctl pc c -n $namespace $gatewayPod
istioctl pc c -n $namespace $gatewayPod -o json | jq '.[]'
Reference & Guidelines (NOTE)

Table Description

  • SERVICE FQDN: Fully Qualified Domain Name
  • DIRECTION
  • outbound:
  • TYPE
  • EDS:
  • STATIC:
  • STRICT_DNS:
  • PORT / SUBSET / DESTINATION RULE
listener
bash
#Pod Listener proxy config 조회
#Aliases: listener, listeners, l
## 전체 조회
istioctl pc l -n $namespace $pod
## Listner filter address
istioctl pc l -n $namespace $pod --address $address
istioctl pc l -n $namespace $pod --address $address -o json | jq '.[]'
## Listner filter port
istioctl pc l -n $namespace $pod --port $port
istioctl pc l -n $namespace $pod --port $port -o json | jq '.[]'
Reference & Guidelines (NOTE)

Table Description

  • Listener 대상
  • ADDRESSES: Listener IP
    • Service IP or 0.0.0.0
  • PORT: Listener Port
  • Listener 규칙
    • MATCH:

      • Trans

        – raw_buffer
        – tls

      • App

        – http/1.1,h2c
        – istio-http/1.0,istio-http/1.1,istio-h2
        – TCP

      • Addr

        – 0.0.0.0/0

      • ALL
    • DESTINATION: 목적지

      • PassthroughCluster:
      • InboundPassthroughClusterIpv4:
      • Route: $PORT:
      • Route: $SERVICE_FQDN:$PORT:
      • Cluster: outbound|$PORT||$SERVICE_FQDN:
      • Cluster: inbound|$PORT||:
      • Non-HTTP/Non-TCP:
proxy-status

Aliases: proxy-status, ps

메시에 있는 각 Envoy의 동기화 상태를 검색합니다. [kube만 해당]

https://istio.io/latest/docs/ops/diagnostic-tools/proxy-cmd/

bash
istioctl proxy-status
istioctl ps
Reference & Guidelines (NOTE)

용어설명

  • Columns
  • CDS: Cluster Discovery Service
  • LDS: Listener Discovery Service
  • EDS: Endpoint Discovery Service
  • RDS: Route Discovery Service
  • ECDS: Extension Config Discovery Service
  • Values
  • SYNCED: Envoy가 Istiod가 보낸 마지막 구성을 확인했음을 의미합니다.
  • NOT SENT: Istiod가 Envoy에 아무 것도 보내지 않았다는 의미입니다. 이는 일반적으로 Istiod에 보낼 것이 없기 때문입니다.
  • STALE: Istiod가 Envoy에 업데이트를 보냈지만 승인을 받지 못했다는 뜻입니다. 이는 일반적으로 Envoy와 Istiod 간의 네트워킹 문제 또는 Istio 자체의 버그를 나타냅니다.

ETC

authz

(인증은 실험적입니다. istioctl 실험적 인증을 사용하세요)

experimental

수정되거나 더 이상 사용되지 않을 수 있는 실험적 명령

bash
authz           (Inspect Istio AuthorizationPolicy)
check-inject    (Check the injection status or inject-ability of a given resource, explains why it is (or will be) injected or not)
config          (Configure istioctl defaults)
describe        (Describe resource and related Istio configuration)
envoy-stats     (Retrieves Envoy metrics in the specified pod)
injector        (List sidecar injector and sidecar versions)
internal-debug  (Retrieves the debug information of istio)
metrics         (Prints the metrics for the specified workload(s) when running in Kubernetes.)
precheck        (Check whether Istio can safely be installed or upgraded)
proxy-status    (Retrieves the synchronization status of each Envoy in the mesh)
version         (Prints out build version information)
wait            (Wait for an Istio resource)
waypoint        (Manage waypoint configuration)
workload        (Commands to assist in configuring and deploying workloads running on VMs and other non-Kubernetes environments)
mhkim@fredric:~/playgrounds-fredric/iac/2.helm/cicd/argo-workflows$ istioctl experimental
authz           (Inspect Istio AuthorizationPolicy)
check-inject    (Check the injection status or inject-ability of a given resource, explains why it is (or will be) injected or not)
config          (Configure istioctl defaults)
describe        (Describe resource and related Istio configuration)
envoy-stats     (Retrieves Envoy metrics in the specified pod)
injector        (List sidecar injector and sidecar versions)
internal-debug  (Retrieves the debug information of istio)
metrics         (Prints the metrics for the specified workload(s) when running in Kubernetes.)
precheck        (Check whether Istio can safely be installed or upgraded)
proxy-status    (Retrieves the synchronization status of each Envoy in the mesh)
version         (Prints out build version information)
wait            (Wait for an Istio resource)
waypoint        (Manage waypoint configuration)
workload        (Commands to assist in configuring and deploying workloads running on VMs and other non-Kubernetes environments)

Flags

bash
--context string          Kubernetes configuration context
  -h, --help                    help for istioctl
  -i, --istioNamespace string   Istio system namespace (default "istio-system")
  -c, --kubeconfig string       Kubernetes configuration file
  -n, --namespace string        Kubernetes namespace
      --vklog Level             number for the log level verbosity. Like -v flag. ex: --vklog=9

Features

Comments

Leave a Reply

Your email address will not be published. Required fields are marked *