ccictl概述

ccictl介绍

ccictl是类似kubectl的，使用API与CCI 2.0服务进行通信的CLI版本命令行工具。其可胜任管理CCI 2.0集群的多种任务。

针对配置信息，ccictl 在 $HOME/.kubev2 目录中查找一个名为 config 的配置文件。 您可以通过设置 CLICONFIG 环境变量或设置 --cliconfig 参数来指定其他config文件。

本章节主要介绍如何使用ccictl在CCI 2.0中声明式管理应用，本章节还涵盖一些其他的ccictl功能。

CCI 2.0服务侧提供的所有资源所属组和版本(group/version)基本上属于cci/v2，ccictl工具创建，查询，删除等操作的资源的group/version也基本上属于cci/v2，所以直接使用group/version为v1或apps/v1的资源文件作为ccictl的入参，命令执行会失败。

命令分类

大多数 ccictl 命令通常可以分为以下几类：

声明式应用管理

管理资源的首选方法是配合 ccictl apply 命令一起使用名为资源的声明式文件。 此命令读取本地（或远程）文件结构，并修改集群状态以反映声明的意图。

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 服务器的地址和端口。

从命令行指定的参数会覆盖默认值和任何相应的环境变量。

如果您需要帮助，在终端窗口中运行 ccictl help。

操作

下表包含所有ccictl操作的简短描述和普通语法：

资源类型

资源类型仅表明CCI 2.0支持的所有资源类型，不保证上表所有资源对象都提供GET, POST, PUT, DELETE, PATCH所有API，如replicasets资源对象仅提供命名空间级别的查询API。不同局点的CCI 2.0服务也存在API偏差。

当遇到存在争议的API或者资源类型时，请优先咨询CCI服务接口人，一切解释权归CCI服务所有。

输出选项

输出格式

所有 ccictl 命令的默认输出格式都是人类可读的纯文本格式。要以特定格式在终端窗口输出详细信息， 可以将 -o 或 --output 参数添加到受支持的 ccictl 命令中。

语法

ccictl [command] [TYPE] [NAME] -o <output_format>

支持的输出格式如下：

示例

在此示例中，以下命令将单个 Pod 的详细信息输出为 YAML 格式的对象：

ccictl get pod web-pod-13je7 -o yaml

自定义列

要定义自定义列并仅将所需的详细信息输出到表中，可以使用 custom-columns 选项。 您可以选择内联定义自定义列或使用模板文件：-o custom-columns=<spec> 或 -o custom-columns-file=<filename>。

示例：

内联：

ccictl get pods <pod-name> -o custom-columns=NAME:.metadata.name,RSRC:.metadata.resourceVersion

模板文件：

ccictl get pods <pod-name> -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=<jsonpath_exp>

示例

要打印按名称排序的 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

# 使用 <directory> 路径下的任意 .yaml、.yml 或 .json 文件 创建对象。
ccictl apply -f <directory>

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-name> 的 Service 的详细信息。
ccictl describe svc <service-name>

# 显示名为 <pod-name> 的 Pod 的详细信息。
ccictl describe pods/<pod-name>

# 显示由名为 <deploy-name> 的工作负载管理的所有 Pod 的详细信息。
ccictl describe pods <deploy-name>

# 描述所有的 Pod
ccictl describe pods

ccictl get 命令通常用于检索同一资源类别的一个或多个资源。 它具有丰富的参数，允许您使用 -o 或 --output 参数自定义输出格式。 您可以指定 -w 或 --watch 参数以开始监测特定对象的更新。 ccictl describe 命令更侧重于描述指定资源的许多相关方面。它可以调用对 API 服务器 的多个 API 调用来为用户构建视图。 例如，该 ccictl describe pod 命令不仅检索有关Pod的信息，还检索与其关联生成的事件等。

ccictl delete - 基于文件、标准输入或通过指定标签选择器、名称、资源选择器或资源来删除资源。

# 使用 pod.yaml 文件中指定的类型和名称删除 Pod。
ccictl delete -f pod.yaml

# 删除所有带有 '<label-key>=<label-value>' 标签的 Pod 和 Service。
ccictl delete pods,services -l <label-key>=<label-value>

# 删除所有 Pod，包括未初始化的 Pod。
ccictl delete pods --all

ccictl exec - 对 Pod 中的容器执行命令。

# 从 Pod <pod-name> 中获取运行 'date' 的输出。默认情况下，输出来自第一个容器。
ccictl exec <pod-name> -- date

# 运行输出 'date' 获取在 Pod <pod-name> 中容器 <container-name> 的输出。
ccictl exec <pod-name> -c <container-name> -- date

# 获取一个交互 TTY 并在 Pod  <pod-name> 中运行 /bin/bash。默认情况下，输出来自第一个容器。
ccictl exec -ti <pod-name> -- /bin/bash

ccictl logs - 打印 Pod 中容器的日志。

# 返回 Pod <pod-name> 的日志快照。
ccictl logs <pod-name>

# 从 Pod <pod-name> 开始流式传输日志。这类似于 'tail -f' Linux 命令。
ccictl logs -f <pod-name>

JSONPath支持

ccictl 工具支持 JSONPath 模板作为输出格式。

JSONPath 模板由大括号 { 和 } 包起来的 JSONPath 表达式组成。 ccictl 使用 JSONPath 表达式来过滤 JSON 对象中的特定字段并格式化输出。 除了原始的 JSONPath 模板语法，以下函数和语法也是有效的:

• 使用双引号将 JSONPath 表达式内的文本引起来。
• 使用 range，end 运算符来迭代列表。
• 使用负片索引后退列表。负索引不会“环绕”列表， 并且只要 \( ( - index + listLength ) \ge 0 \) 就有效。

• $ 运算符是可选的，因为默认情况下表达式总是从根对象开始。
• 结果对象将作为其 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"}
    }
  ]
}

通过 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'