# ccictl概述 #### ccictl介绍 ccictl是类似kubectl的，使用API与CCI 2.0服务进行通信的CLI版本命令行工具。其可胜任管理CCI 2.0集群的多种任务。 针对配置信息，ccictl 在 $HOME/.kubev2 目录中查找一个名为 config 的配置文件。 您可以通过设置 CLICONFIG 环境变量或设置 --cliconfig 参数来指定其他config文件。 本章节主要介绍如何使用ccictl在CCI 2.0中声明式管理应用，本章节还涵盖一些其他的ccictl功能。 ![](https://support.huaweicloud.com/devg-cci2/public_sys-resources/caution_3.0-zh-cn.png) CCI 2.0服务侧提供的所有资源所属组和版本(group/version)基本上属于cci/v2，ccictl工具创建，查询，删除等操作的资源的group/version也基本上属于cci/v2，所以直接使用group/version为v1或apps/v1的资源文件作为ccictl的入参，命令执行会失败。 #### 命令分类 大多数 ccictl 命令通常可以分为以下几类： 表1ccictl命名分类 | 类型 | 用途 | 描述 | |:---|:---|:---| | 声明式资源管理 | 部署和运维（如 GitOps） | 使用资源管理声明式管理CCI 2.0工作负载。 | | 命令式资源管理 | 调试 | 使用命令行参数和标志来管理CCI 2.0工作负载。 | | 打印工作负载状态 | 调试 | 打印有关工作负载的信息。 | | 与容器交互 | 调试 | 执行、挂接、复制、日志。 | #### 声明式应用管理 管理资源的首选方法是配合 ccictl apply 命令一起使用名为资源的声明式文件。 此命令读取本地（或远程）文件结构，并修改集群状态以反映声明的意图。 ![](https://support.huaweicloud.com/devg-cci2/public_sys-resources/note_3.0-zh-cn.png) **Apply** Apply 是在CCI 2.0集群中管理资源的首选机制。 #### 打印工作负载状态 ccictl 支持通过提供以下命令进行调试： - 打印 Container 日志 - 打印事件 - 执行到 Container #### 语法 使用以下语法从终端窗口运行ccictl命令： ``` ccictl [command] [TYPE] [NAME] [flags] ``` 其中 command、TYPE、NAME 和 flags 分别是： - command：指定要对一个或多个资源执行的操作，例如 create、get、describe、delete。 - TYPE：指定[资源类型]。资源类型不区分大小写， 可以指定单数、复数或缩写形式。例如，以下命令输出相同的结果： ``` ccictl get pod pod1 ccictl get pods pod1 ccictl get po pod1 ``` - NAME：指定资源的名称。名称区分大小写。 如果省略名称，则显示所有资源的详细信息。例如：ccictl get pods。 在对多个资源执行操作时，您可以按类型和名称指定每个资源，或指定一个或多个文件： - 要按类型和名称指定资源： - 要对所有类型相同的资源进行分组，请执行以下操作：TYPE1 name1 name2 name\<#\>。 示例：ccictl get pod example-pod1 example-pod2 - 分别指定多个资源类型：TYPE1/name1 TYPE1/name2 TYPE2/name3 TYPE\<#\>/name\<#\>。 示例：ccictl get pod/example-pod1 deployment/example-deploy1 - 用一个或多个文件指定资源：-f file1 -f file2 -f file\<#\> - 建议使用 YAML 而不是 JSON， 因为 YAML 对用户更友好, 特别是对于配置文件。 示例：ccictl get -f ./pod.yaml - flags： 指定可选的参数。例如，可以使用 -s 或 --server 参数指定 API 服务器的地址和端口。 ![](https://support.huaweicloud.com/devg-cci2/public_sys-resources/caution_3.0-zh-cn.png) 从命令行指定的参数会覆盖默认值和任何相应的环境变量。 如果您需要帮助，在终端窗口中运行 ccictl help。 #### 操作 下表包含所有ccictl操作的简短描述和普通语法： 表2描述和语法 | 操作 | 语法 | 描述 | |:---|:---|:---| | api-resources | ccictl api-resources \[flags\] | 列出可用的 API 资源。 | | api-versions | ccictl api-versions \[flags\] | 列出可用的 API 版本。 | | apply | ccictl apply -f FILENAME \[flags\] | 从文件或 stdin 对资源应用配置更改。 | | config | ccictl config SUBCOMMAND \[flags\] | 修改 config 文件。有关详细信息，请参阅各个子命令。 | | create | ccictl create -f FILENAME \[flags\] | 从文件或 stdin 创建一个或多个资源。 | | delete | ccictl delete (-f FILENAME \| TYPE \[NAME \| /NAME \| -l label \| --all\]) \[flags\] | 基于文件、标准输入或通过指定标签选择器、名称、资源选择器或资源本身，删除资源。 | | describe | ccictl describe (-f FILENAME \| TYPE \[NAME_PREFIX \| /NAME \| -l label\]) \[flags\] | 显示一个或多个资源的详细状态。 | | edit | ccictl edit (-f FILENAME \| TYPE NAME \| TYPE/NAME) \[flags\] | 使用默认编辑器编辑和更新服务器上一个或多个资源的定义。 | | exec | ccictl exec POD \[-c CONTAINER\] \[-i\] \[-t\] \[flags\] \[-- COMMAND \[args...\]\] | 对 Pod 中的容器执行命令。 | | explain | ccictl explain TYPE \[--recursive=false\] \[flags\] | 获取多种资源的文档。例如 Pod、Deployment、Service 等。 | | get | ccictl get (-f FILENAME \| TYPE \[NAME \| /NAME \| -l label\]) \[--watch\] \[--sort-by=FIELD\] \[\[-o \| --output\]=OUTPUT_FORMAT\] \[flags\] | 列出一个或多个资源。 | | logs | ccictl logs POD \[-c CONTAINER\] \[--follow\] \[flags\] | 打印 Pod 中容器的日志。 | | rollout | ccictl rollout SUBCOMMAND \[options\] | 管理资源的上线。有效的资源类型：Deployment | | set | ccictl set SUBCOMMAND \[options\] | 配置应用资源。 | | version | ccictl version \[flags\] | 显示运行在客户端的 ccictl 版本。 | #### 资源类型 表3资源类型 | 资源名 | 缩写名 | API版本 | 按命名空间 | 资源类型 | |:---|:---|:---|:---|:---| | configmaps | cm | cci/v2 | true | ConfigMap | | deployments | deploy | cci/v2 | true | Deployment | | horizontalpodautoscalers | hpa | cci/v2 | true | HorizontalPodAutoscaler | | imagesnapshots | is | cci/v2 | false | ImageSnapshot | | namespaces | ns | cci/v2 | false | Namespace | | persistentvolumeclaims | pvc | cci/v2 | true | PersistentVolumeClaim | | persistentvolumes | pv | cci/v2 | false | PersistentVolume | | pods | po | cci/v2 | true | Pod | | replicasets | rs | cci/v2 | true | ReplicaSet | | secrets | - | cci/v2 | true | Secret | | services | svc | cci/v2 | true | Service | | storageclasses | - | cci/v2 | false | StorageClass | | networks | - | yangtse/v2 | true | Network | ![](https://support.huaweicloud.com/devg-cci2/public_sys-resources/caution_3.0-zh-cn.png) [资源类型]仅表明CCI 2.0支持的所有资源类型，不保证上表所有资源对象都提供GET, POST, PUT, DELETE, PATCH所有API，如replicasets资源对象仅提供命名空间级别的查询API，imagesnapshots的API需开通CCI 2.0白名单后才可使用。不同局点的CCI 2.0服务也存在API偏差。 当遇到存在争议的API或者资源类型时，请优先咨询CCI服务接口人，一切解释权归CCI服务所有。 #### 输出选项 **输出格式** 所有 ccictl 命令的默认输出格式都是人类可读的纯文本格式。要以特定格式在终端窗口输出详细信息， 可以将 -o 或 --output 参数添加到受支持的 ccictl 命令中。 **语法** ``` ccictl [command] [TYPE] [NAME] -o ``` 支持的输出格式如下： 表4 | 输出格式 | 描述 | |:---|:---| | -o custom-columns=\ | 使用逗号分隔的[自定义列]列表打印表。 | | -o custom-columns-file=\ | 使用 \ 文件中的[自定义列]模板打印表。 | | -o json | 输出 JSON 格式的 API 对象 | | -o jsonpath=\ | 打印 [JSONPath] 表达式定义的字段 | | -o jsonpath-file=\ | 打印 \ 文件中 [JSONPath] 表达式定义的字段。 | | -o name | 仅打印资源名称而不打印任何其他内容。 | | -o wide | 以纯文本格式输出，包含所有附加信息。 | | -o yaml | 输出 YAML 格式的 API 对象。 | **示例** 在此示例中，以下命令将单个 Pod 的详细信息输出为 YAML 格式的对象： ``` ccictl get pod web-pod-13je7 -o yaml ``` #### 自定义列 要定义自定义列并仅将所需的详细信息输出到表中，可以使用 custom-columns 选项。 您可以选择内联定义自定义列或使用模板文件：-o custom-columns=\ 或 -o custom-columns-file=\。 **示例：** 内联： ``` ccictl get pods -o custom-columns=NAME:.metadata.name,RSRC:.metadata.resourceVersion ``` 模板文件： ``` ccictl get pods -o custom-columns-file=template.txt ``` 其中，template.txt 文件包含： ``` NAME RSRC metadata.name metadata.resourceVersion ``` 运行这两个命令之一的结果类似于： ``` NAME RSRC example-name 610995 ``` #### 排序列表对象 要将对象排序后输出到终端窗口，可以将 --sort-by 参数添加到支持的 ccictl 命令。 通过使用 --sort-by 参数指定任何数字或字符串字段来对对象进行排序。 要指定字段，请使用 [JSONPath] 表达式。 **语法** ``` ccictl [command] [TYPE] [NAME] --sort-by= ``` **示例** 要打印按名称排序的 Pod 列表，请运行： ``` ccictl get pods --sort-by=.metadata.name ``` #### 示例：常见操作 使用以下示例集来帮助您熟悉运行常用 ccictl 操作： ccictl apply - 以文件或标准输入为准应用或更新资源。 ``` # 使用 example-service.yaml 中的定义创建 Service。 ccictl apply -f example-service.yaml # 使用 example-deployment.yaml 中的定义创建 deployment。 ccictl apply -f example-deployment.yaml # 使用 路径下的任意 .yaml、.yml 或 .json 文件 创建对象。 ccictl apply -f ``` ccictl get - 列出一个或多个资源。 ``` # 以纯文本输出格式列出所有 Pod。 ccictl get pods # 以纯文本输出格式列出所有 Pod，并包含附加信息。 ccictl get pods -o wide # 以纯文本输出格式列出所有Pod和 Service。 ccictl get po,services # 列出所有状态为 Pending 的 Pod ccictl get pods --field-selector=status.phase=Pending ``` ccictl describe - 显示一个或多个资源的详细状态，默认情况下包括未初始化的资源。 ``` # 显示名为 的 Service 的详细信息。 ccictl describe svc # 显示名为 的 Pod 的详细信息。 ccictl describe pods/ # 显示由名为 的工作负载管理的所有 Pod 的详细信息。 ccictl describe pods # 描述所有的 Pod ccictl describe pods ``` ![](https://support.huaweicloud.com/devg-cci2/public_sys-resources/note_3.0-zh-cn.png) ccictl get 命令通常用于检索同一资源类别的一个或多个资源。 它具有丰富的参数，允许您使用 -o 或 --output 参数自定义输出格式。 您可以指定 -w 或 --watch 参数以开始监测特定对象的更新。 ccictl describe 命令更侧重于描述指定资源的许多相关方面。它可以调用对 API 服务器 的多个 API 调用来为用户构建视图。 例如，该 ccictl describe pod 命令不仅检索有关Pod的信息，还检索与其关联生成的事件等。 ccictl delete - 基于文件、标准输入或通过指定标签选择器、名称、资源选择器或资源来删除资源。 ``` # 使用 pod.yaml 文件中指定的类型和名称删除 Pod。 ccictl delete -f pod.yaml # 删除所有带有 '=' 标签的 Pod 和 Service。 ccictl delete pods,services -l = # 删除所有 Pod，包括未初始化的 Pod。 ccictl delete pods --all ``` ccictl exec - 对 Pod 中的容器执行命令。 ``` # 从 Pod 中获取运行 'date' 的输出。默认情况下，输出来自第一个容器。 ccictl exec -- date # 运行输出 'date' 获取在 Pod 中容器 的输出。 ccictl exec -c -- date # 获取一个交互 TTY 并在 Pod 中运行 /bin/bash。默认情况下，输出来自第一个容器。 ccictl exec -ti -- /bin/bash ``` ccictl logs - 打印 Pod 中容器的日志。 ``` # 返回 Pod 的日志快照。 ccictl logs # 从 Pod 开始流式传输日志。这类似于 'tail -f' Linux 命令。 ccictl logs -f ``` #### JSONPath支持 ccictl 工具支持 JSONPath 模板作为输出格式。 JSONPath 模板由大括号 { 和 } 包起来的 JSONPath 表达式组成。 ccictl 使用 JSONPath 表达式来过滤 JSON 对象中的特定字段并格式化输出。 除了原始的 JSONPath 模板语法，以下函数和语法也是有效的: - 使用双引号将 JSONPath 表达式内的文本引起来。 - 使用 range，end 运算符来迭代列表。 - 使用负片索引后退列表。负索引不会"环绕"列表， 并且只要 \\( ( - index + listLength ) \\ge 0 \\) 就有效。 ![](https://support.huaweicloud.com/devg-cci2/public_sys-resources/note_3.0-zh-cn.png) - $ 运算符是可选的，因为默认情况下表达式总是从根对象开始。 - 结果对象将作为其 String() 函数输出。 **JSONPath 中的函数** 给定 JSON 输入: ``` { "kind": "List", "items":[ { "kind":"None", "metadata":{ "name":"127.0.0.1", "labels":{ "kubernetes.io/hostname":"127.0.0.1" } }, "status":{ "capacity":{"cpu":"4"}, "addresses":[{"type": "LegacyHostIP", "address":"127.0.0.1"}] } }, { "kind":"None", "metadata":{"name":"127.0.0.2"}, "status":{ "capacity":{"cpu":"8"}, "addresses":[ {"type": "LegacyHostIP", "address":"127.0.0.2"}, {"type": "another", "address":"127.0.0.3"} ] } } ], "users":[ { "name": "myself", "user": {} }, { "name": "e2e", "user": {"username": "admin", "password": "secret"} } ] } ``` 表5函数说明 | 函数 | 描述 | 示例 | 结果 | |:---|:---|:---|:---| | text | 纯文本 | kind is {.kind} | kind is List | | @ | 当前对象 | {@} | 与输入相同 | | . 或 \[\] | 子运算符 | {.kind}、{\['kind'\]} 或 {\['name\\.type'\]} | List | | .. | 递归下降 | {..name} | 127.0.0.1 127.0.0.2 myself e2e | | \* | 通配符。获取所有对象 | {.items\[\*\].metadata.name} | \[127.0.0.1 127.0.0.2\] | | \[start:end:step\] | 下标运算符 | {.users\[0\].name} | myself | | \[,\] | 并集运算符 | {.items\[\*\]\['metadata.name', 'status.capacity'\]} | 127.0.0.1 127.0.0.2 map\[cpu:4\] map\[cpu:8\] | | ?() | 过滤 | {.users\[?(@.name=="e2e")\].user.password} | secret | | range，end | 迭代列表 | {range .items\[\*\]}\[{.metadata.name}, {.status.capacity}\] {end} | \[127.0.0.1, map\[cpu:4\]\] \[127.0.0.2, map\[cpu:8\]\] | | '' | 引用解释执行字符串 | {range .items\[\*\]}{.metadata.name}{'\\t'}{end} | 127.0.0.1 127.0.0.2 | | \\ | 转义终止符 | {.items\[0\].metadata.labels.kubernetes\\.io/hostname} | 127.0.0.1 | **通过 ccictl 使用 JSONPath 表达式** 使用 ccictl 和 JSONPath 表达式的示例： ``` ccictl get pods -o json ccictl get pods -o=jsonpath='{@}' ccictl get pods -o=jsonpath='{.items[0]}' ccictl get pods -o=jsonpath='{.items[0].metadata.name}' ccictl get pods -o=jsonpath="{.items[*]['metadata.name', 'status.capacity']}" ccictl get pods -o=jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.startTime}{"\n"}{end}' ccictl get pods -o=jsonpath='{.items[0].metadata.labels.kubernetes\.io/hostname}' ``` JSONPath 中的正则表达式 不支持 JSONPath 正则表达式。如需使用正则表达式进行匹配操作，您可以使用如 jq 之类的工具。 ``` # ccictl 的 JSONpath 输出不支持正则表达式 # 下面的命令不会生效 ccictl get pods -o jsonpath='{.items[?(@.metadata.name=~/^test$/)].metadata.name}' # 下面的命令可以获得所需的结果 ccictl get pods -o json | jq -r '.items[] | select(.metadata.name | test("test-")).metadata.name' ```