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.

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:

Resource Types

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.

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"}
    }
  ]
}

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'