Updated on 2025-05-30 GMT+08:00

ccictl Overview

Introduction to ccictl

ccictl is a CLI tool similar to kubectl. It uses APIs to communicate with CCI 2.0. It can manage various tasks of CCI 2.0 clusters.

ccictl looks for a configuration file named config in the $HOME/.kubev2 directory. You can create other config files as needed by setting the CLICONFIG environment variable or the --cliconfig parameter.

This topic describes how to use ccictl for declarative application management in CCI 2.0. It also covers some other ccictl functions.

The group and version of all resources provided by CCI 2.0 are cci and v2, the same for the resources created, queried, and deleted using ccictl. If the resource files where the group and version are used as input parameters and group/version is set to v1 or apps/v1, the commands fail to be executed.

Command Category

Most ccictl commands can be classified into the types in the following table.

Table 1 ccictl command category

Type

Purpose

Description

Declarative resource management

Deployment and O&M (such as GitOps)

The commands are used to manage workloads in CCI 2.0.

Command-based resource management

Debugging

Command-line parameters and flags are used to manage workloads in CCI 2.0.

Workload status printing

Debugging

The commands are used to print information about workloads.

Interaction with containers

Debugging

The commands are used for execution, mounting, replication, and logging.

Declarative Application Management

A preferred way to manage resources is to use a declarative file named resource together with the ccictl apply command. This command reads the local (or remote) file structure and modifies the cluster status to reflect the declared intent.

Apply

Apply is preferred for managing resources in CCI 2.0.

Workload Status Printing

ccictl provides the following commands for debugging:

  • Print container logs.
  • Print events.
  • Execute to a container.

Syntax

Run the ccictl command on the terminal using the following syntax:

ccictl [command] [TYPE] [NAME] [flags]

command, TYPE, NAME, and flags are described as follows:

  • command: specifies the operation to be performed on one or more resources, for example, create, get, describe, and delete.
  • TYPE: specifies the resource type. The resource type is case insensitive. You can use the singular or plural form, or an abbreviation. For example, the output of the following commands is the same:
ccictl get pod pod1
ccictl get pods pod1
ccictl get po pod1
  • NAME: specifies the name of a resource. The name is case sensitive. If the name is omitted, the details of all resources are displayed, for example, ccictl get pods.

    When performing operations on multiple resources, you can specify each resource by type and name, or use one or more files.

  • To specify resources by type and name:
  • To group all resources of the same type: TYPE1 name1 name2 name<#>

    Example: ccictl get pod example-pod1 example-pod2

  • To specify multiple resource types: TYPE1/name1 TYPE1/name2 TYPE2/name3 TYPE<#>/name<#>

    Example: ccictl get pod/example-pod1 deployment/example-deploy1

  • Use one or more files to specify resources: -f file1 -f file2 -f file<#&gt
  • You are advised to use YAML instead of JSON because YAML is more user-friendly, especially for configuration files.

    Example: ccictl get -f ./pod.yaml

  • flags: specifies optional parameters. For example, you can use the -s or --server parameter to specify the address and port of the API server.

Parameters specified from the command line overwrite the default values and any corresponding environment variables.

If you need help, run the ccictl help command in the terminal.

Operations

The following table contains a short description and common syntax of all ccictl operations:

Table 2 Descriptions and syntax

Operation

Syntax

Description

api-resources

ccictl api-resources [flags]

Lists available API resources.

api-versions

ccictl api-versions [flags]

Lists available API versions.

apply

ccictl apply -f FILENAME [flags]

Applies configuration changes to a resource from a file or stdin.

config

ccictl config SUBCOMMAND [flags]

Modifies the config file. For details, see the subcommand descriptions.

create

ccictl create -f FILENAME [flags]

Creates one or more resources from a file or stdin.

delete

ccictl delete (-f FILENAME | TYPE [NAME | /NAME | -l label | --all]) [flags]

Deletes a resource based on a file or stdin, or by specifying a label selector, name, resource selector, or resource itself.

describe

ccictl describe (-f FILENAME | TYPE [NAME_PREFIX | /NAME | -l label]) [flags]

Displays the status of one or more resources.

edit

ccictl edit (-f FILENAME | TYPE NAME | TYPE/NAME) [flags]

Uses the default editor to edit and update the definitions of one or more resources on the server.

exec

ccictl exec POD [-c CONTAINER] [-i] [-t] [flags] [-- COMMAND [args...]]

Runs commands in the containers of a pod.

explain

ccictl explain TYPE [--recursive=false] [flags]

Obtains documents of multiple resources, such as pods, Deployments, and Services.

get

ccictl get (-f FILENAME | TYPE [NAME | /NAME | -l label]) [--watch] [--sort-by=FIELD] [[-o | --output]=OUTPUT_FORMAT] [flags]

Lists one or more resources.

logs

ccictl logs POD [-c CONTAINER] [--follow] [flags]

Prints logs of containers in a pod.

rollout

ccictl rollout SUBCOMMAND [options]

Manages resource rollouts. A valid resource type is Deployment.

set

ccictl set SUBCOMMAND [options]

Configures application resources.

version

ccictl version [flags]

Displays the version of ccictl on the client.

Resource Types

Table 3 Resource types

Resource Name

Abbreviation

API Version

By Namespace

Resource Type

configmaps

cm

cci/v2

true

ConfigMap

deployments

deploy

cci/v2

true

Deployment

horizontalpodautoscalers

hpa

cci/v2

true

HorizontalPodAutoscaler

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

Resource Types lists only resource types supported by CCI 2.0. Not all resource objects in the table support all GET, POST, PUT, DELETE, PATCH APIs. For example, ReplicaSets supports only namespace-level query APIs. The APIs at different sites are also different.

If you encounter any dispute about APIs or resource types, contact the CCI service contact. CCI reserves the right to interpret the information.

Output Options

Output format

The default output format of all ccictl commands is human-readable plain text. To output detailed information in a specific format in the terminal, you can add the -o or --output parameter to the ccictl command.

Syntax

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

The following are example outputs.

Table 4

Output Format

Description

-o custom-columns=<spec>

A list of comma-separated custom columns

-o custom-columns-file=<filename>

A list of custom columns based on the template in the <filename> file.

-o json

API objects in JSON format.

-o jsonpath=<template>

Fields defined by the JSONPath expression.

-o jsonpath-file=<filename>

Fields defined by the JSONPath expression in the <filename> file.

-o name

Resource name

-o wide

The output is in plain text format and contains all additional information.

-o yaml

API objects in YAML format

Example

In this example, the command outputs the details of a single pod as an object in YAML format.

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

Custom Columns

To define custom columns and output only the required details to a list, you can use the custom-columns option. You can define an inline (-o custom-columns=<spec>) or use a template file (-o custom-columns-file=<filename>).

Example

Inline:

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

Template file:

ccictl get pods <pod-name> -o custom-columns-file=template.txt

The template.txt file contains the following information:

NAME          RSRC
metadata.name metadata.resourceVersion

The output of either of the two commands is similar to the following:

NAME           RSRC
example-name   610995

Sorting List Objects

To sort objects and output them in the terminal, you can add the --sort-by parameter to the supported ccictl command. This parameter allows you to sort objects by specifying any numeric or string field. To specify a field, use the JSONPath expression.

Syntax

ccictl [command] [TYPE] [NAME] --sort-by=<jsonpath_exp>

Example

To print a list of pods sorted by name, run the following command:

ccictl get pods --sort-by=.metadata.name

Common Operation Examples

Use the following examples to help you get familiar with common ccictl operations.

ccictl apply - Apply or update resources based on a file or stdin.

# Use the definition in example-service.yaml to create a Service.
ccictl apply -f example-service.yaml

# Use the definition in example-deployment.yaml to create a Deployment.
ccictl apply -f example-deployment.yaml

# Use any .yaml, .yml, or .json file in <directory> to create an object.
ccictl apply -f <directory>

ccictl get - List one or more resources.

# List all pods in plain text format.
ccictl get pods

# List all pods in plain text format, including additional information.
ccictl get pods -o wide

# List all pods and Services in plain text format.
ccictl get po,services

# List all pods in the Pending state.
ccictl get pods --field-selector=status.phase=Pending

ccictl describe - Display the status of one or more resources, including uninitialized resources.

# Display the details about the Service named <service-name>.
ccictl describe svc <service-name>

# Display the details about the pod named <pod-name>.
ccictl describe pods/<pod-name>

# Display the details about all pods for the workload named <deploy-name>.
ccictl describe pods <deploy-name>

# Describe all pods.
ccictl describe pods

The ccictl get command is usually used to retrieve one or more resources of the same resource class. You can specify the output format using the -o or --output parameter. You can also specify the -w or --watch parameter to start monitoring updates for a specific object. The ccictl describe command focuses more on describing many relevant aspects of a specified resource. It can invoke multiple API calls to the API server to build views for users. For example, the ccictl describe pod command retrieves information about the pod and the events generated for the pod.

ccictl delete - Delete a resource based on a file or stdin, or by specifying a label selector, name, resource selector, or resource itself.

# Use the type and name specified in the pod.yaml file to delete a pod.
ccictl delete -f pod.yaml

# Delete all pods and Services with the <label-key>=<label-value> label.
ccictl delete pods,services -l <label-key>=<label-value>

# Delete all pods, including uninitialized pods.
ccictl delete pods --all

ccictl exec - Run commands in the containers of a pod.

# Obtain the output by running 'date' from pod <pod-name>. By default, the output comes from the first container.
ccictl exec <pod-name> -- date

# Obtain the output by running 'date' from container <container-name> in pod <pod-name>.
ccictl exec <pod-name> -c <container-name> -- date

# Obtain an interactive TTY and run /bin/bash in pod <pod-name>. By default, the output comes from the first container.
ccictl exec -ti <pod-name> -- /bin/bash

ccictl logs - Print logs of containers in a pod.

# Return the log snapshot of pod <pod-name>.
ccictl logs <pod-name>

# Start to transfer logs in streaming mode from pod <pod-name>. This is similar to the tail -f Linux command.
ccictl logs -f <pod-name>

JSONPath Support

ccictl supports the JSONPath template as the output format.

A JSONPath template consists of a JSONPath expression enclosed by braces ({}). ccictl uses the JSONPath expression to filter specific fields in a JSON object and format the output. In addition to the original JSONPath template syntax, the following functions and syntax are also valid:

  • Use double quotation marks to enclose the text in the JSONPath expression.
  • Use the range and end operators to iterate the list.
  • Back up a list using a negative index. A negative index does not "surround" the list and is valid as long as the \( ( - index + listLength ) \ge 0 \) is valid.
  • The $ operator is optional because the expression always starts from the root object by default.
  • The result object is output as its String() function.

Functions in JSONPath

Given JSON input:

{
  "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"}
    }
  ]
}
Table 5

Function

Description

Example

Result

text

Text only

kind is {.kind}

kind is List

@

Current object

{@}

Same as the input

. or []

Operator

{.kind}, {['kind']}, or {['name\.type']}

List

..

Recursive descent

{..name}

127.0.0.1 127.0.0.2 myself e2e

*

Wildcard mask. All objects are obtained.

{.items[*].metadata.name}

[127.0.0.1 127.0.0.2]

[start:end:step]

Indicator operator

{.users[0].name}

myself

[,]

Union operator

{.items[*]['metadata.name', 'status.capacity']}

127.0.0.1 127.0.0.2 map[cpu:4] map[cpu:8]

?()

Filter

{.users[?(@.name=="e2e")].user.password}

secret

range, end

Iteration list

{range .items[*]}[{.metadata.name}, {.status.capacity}] {end}

[127.0.0.1, map[cpu:4]] [127.0.0.2, map[cpu:8]]

''

Reference explanation execution string

{range .items[*]}{.metadata.name}{'\t'}{end}

127.0.0.1 127.0.0.2

\

Escape terminator

{.items[0].metadata.labels.kubernetes\.io/hostname}

127.0.0.1

Using JSONPath Expressions Through ccictl

The following is an example of using ccictl and JSONPath expressions:

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}'

Regular expression in JSONPath

JSONPath regular expressions are not supported. To use regular expressions for matching, you can use tools such as jq.

# The JSONPath output of ccictl does not support regular expressions.
# The following command does not take effect.
ccictl get pods -o jsonpath='{.items[?(@.metadata.name=~/^test$/)].metadata.name}'

# The following command can obtain the required result.
ccictl get pods -o json | jq -r '.items[] | select(.metadata.name | test("test-")).metadata.name'