Install calicoctl

Big picture

This guide helps you install the calicoctl command line tool to manage Calico resources and perform administrative functions.

Value

The calicoctl command line tool is required in order to use many of Calico’s features. It is used to manage Calico policies and configuration, as well as view detailed cluster status.

Concepts

API groups

All Kubernetes resources belong to an API group. The API group is indicated by the resource’s apiVersion. For example, Calico uses resources in the projectcalico.org/v3 API group for configuration, and the operator uses resources in the operator.tigera.io/v1 API group.

You can read more about API groups in the Kubernetes documentation.

calicoctl and kubectl

In order to manage Calico APIs in the projectcalico.org/v3 API group, you should use calicoctl. This is because calicoctl provides important validation and defaulting for these resources that is not available in kubectl. However, kubectl should still be used to manage other Kubernetes resources.

Install calicoctl - 图1note

If you would like to use kubectl to manage projectcalico.org/v3 API resources, you can use the Calico API server.

Install calicoctl - 图2caution

Never modify resources in the crd.projectcalico.org API group directly. These are internal data representations and modifying them directly may result in unexpected behavior. In addition to resource management, calicoctl also enables other Calico administrative tasks such as viewing IP pool utilization and BGP status.

Datastore

Calico objects are stored in one of two datastores, either etcd or Kubernetes. The choice of datastore is determined at the time Calico is installed. Typically for Kubernetes installations the Kubernetes datastore is the default.

You can run calicoctl on any host with network access to the Calico datastore as either a binary or a container. For step-by-step instructions, refer to the section that corresponds to your desired deployment.

How to

Install calicoctl - 图3note

Make sure you always install the version of calicoctl that matches the version of Calico running on your cluster.

Install calicoctl as a binary on a single host

  • Linux
  • Mac OSX
  • Windows
  • Linux PPC64le
  • Linux arm64

  1. Log into the host, open a terminal prompt, and navigate to the location where you want to install the binary.

    Install calicoctl - 图4tip

    Consider navigating to a location that’s in your PATH. For example, /usr/local/bin/.

  2. Use the following command to download the calicoctl binary.

    1. curl -L https://github.com/projectcalico/calico/releases/latest/download/calicoctl-linux-amd64 -o calicoctl

  3. Set the file to be executable.

    1. chmod +x ./calicoctl

    Install calicoctl - 图5note

    If the location of calicoctl is not already in your PATH, move the file to one that is or add its location to your PATH. This will allow you to invoke it without having to prepend its location.

  4. Log into the host, open a terminal prompt, and navigate to the location where you want to install the binary.

    Install calicoctl - 图6tip

    Consider navigating to a location that’s in your PATH. For example, /usr/local/bin/.

  5. Use the following command to download the calicoctl binary.

    1. curl -L https://github.com/projectcalico/calico/releases/latest/download/calicoctl-darwin-amd64 -o calicoctl

  6. Set the file to be executable.

    1. chmod +x calicoctl

    Install calicoctl - 图7note

    If you are faced with cannot be opened because the developer cannot be verified error when using caicoctl for the first time. go to Applications > System Prefences > Security & Privacy in the General tab at the bottom of the window click Allow anyway.

    Install calicoctl - 图8note

    If the location of calicoctl is not already in your PATH, move the file to one that is or add its location to your PATH. This will allow you to invoke it without having to prepend its location.

  7. Use the following PowerShell command to download the calicoctl binary.

    Install calicoctl - 图9tip

    Consider running PowerShell as administrator and navigating to a location that’s in your PATH. For example, C:\Windows.

  1. Invoke-WebRequest -Uri "https://github.com/projectcalico/calico/releases/latest/download/calicoctl-windows-amd64.exe" -OutFile calicoctl.exe

  1. Log into the host, open a terminal prompt, and navigate to the location where you want to install the binary.

    Install calicoctl - 图10tip

    Consider navigating to a location that’s in your PATH. For example, /usr/local/bin/.

  2. Use the following command to download the calicoctl binary.

    1. curl -L https://github.com/projectcalico/calico/releases/latest/download/calicoctl-linux-ppc64le -o calicoctl

  3. Set the file to be executable.

    1. chmod +x calicoctl

    Install calicoctl - 图11note

    If the location of calicoctl is not already in your PATH, move the file to one that is or add its location to your PATH. This will allow you to invoke it without having to prepend its location.

  4. Log into the host, open a terminal prompt, and navigate to the location where you want to install the binary.

    Install calicoctl - 图12tip

    Consider navigating to a location that’s in your PATH. For example, /usr/local/bin/.

  5. Use the following command to download the calicoctl binary.

    1. curl -L https://github.com/projectcalico/calico/releases/latest/download/calicoctl-linux-arm64 -o calicoctl

  6. Set the file to be executable.

    1. chmod +x calicoctl

    Install calicoctl - 图13note

    If the location of calicoctl is not already in your PATH, move the file to one that is or add its location to your PATH. This will allow you to invoke it without having to prepend its location.

Install calicoctl as a kubectl plugin on a single host

  • Linux
  • Mac OSX
  • Windows
  • Linux PPC64le
  • Linux arm64

  1. Log into the host, open a terminal prompt, and navigate to the location where you want to install the binary.

    Install calicoctl - 图14tip

    Consider navigating to a location that’s in your PATH. For example, /usr/local/bin/.

  2. Use the following command to download the calicoctl binary.

    1. curl -L https://github.com/projectcalico/calico/releases/latest/download/calicoctl-linux-amd64 -o kubectl-calico

  3. Set the file to be executable.

    1. chmod +x kubectl-calico

    Install calicoctl - 图15note

    If the location of kubectl-calico is not already in your PATH, move the file to one that is or add its location to your PATH. This is required in order for kubectl to detect the plugin and allow you to use it.

  4. Log into the host, open a terminal prompt, and navigate to the location where you want to install the binary.

    Install calicoctl - 图16tip

    Consider navigating to a location that’s in your PATH. For example, /usr/local/bin/.

  5. Use the following command to download the calicoctl binary.

    1. curl -L https://github.com/projectcalico/calico/releases/latest/download/calicoctl-darwin-amd64 -o kubectl-calico

  6. Set the file to be executable.

    1. chmod +x kubectl-calico

    Install calicoctl - 图17note

    If you are faced with cannot be opened because the developer cannot be verified error when using caicoctl for the first time. go to Applications > System Prefences > Security & Privacy in the General tab at the bottom of the window click Allow anyway.

    If the location of kubectl-calico is not already in your PATH, move the file to one that is or add its location to your PATH. This is required in order for kubectl to detect the plugin and allow you to use it.

  7. Use the following PowerShell command to download the calicoctl binary.

    Install calicoctl - 图18tip

    Consider running PowerShell as administrator and navigating to a location that’s in your PATH. For example, C:\Windows.

  1. Invoke-WebRequest -Uri "https://github.com/projectcalico/calico/releases/latest/download/calicoctl-windows-amd64.exe -OutFile kubectl-calico.exe

  1. Log into the host, open a terminal prompt, and navigate to the location where you want to install the binary.

    Install calicoctl - 图19tip

    Consider navigating to a location that’s in your PATH. For example, /usr/local/bin/.

  2. Use the following command to download the calicoctl binary.

    1. curl -L https://github.com/projectcalico/calico/releases/latest/download/calicoctl-linux-ppc64le -o kubectl-calico

  3. Set the file to be executable.

    1. chmod +x kubectl-calico

    Install calicoctl - 图20note

    If the location of kubectl-calico is not already in your PATH, move the file to one that is or add its location to your PATH. This is required in order for kubectl to detect the plugin and allow you to use it.

  4. Log into the host, open a terminal prompt, and navigate to the location where you want to install the binary.

    Install calicoctl - 图21tip

    Consider navigating to a location that’s in your PATH. For example, /usr/local/bin/.

  5. Use the following command to download the calicoctl binary.

    1. curl -L https://github.com/projectcalico/calico/releases/latest/download/calicoctl-linux-arm64 -o kubectl-calico

  6. Set the file to be executable.

    1. chmod +x kubectl-calico

    Install calicoctl - 图22note

    If the location of kubectl-calico is not already in your PATH, move the file to one that is or add its location to your PATH. This is required in order for kubectl to detect the plugin and allow you to use it.

Verify the plugin works.

  1. kubectl calico -h

You can now run any calicoctl subcommands through kubectl calico.

Install calicoctl - 图23note

If you run these commands from your local machine (instead of a host node), some of the node related subcommands will not work (like node status).

Install calicoctl as a container on a single host

To install calicoctl as a container on a single host, log into the target host and issue the following command.

  1. docker pull calico/ctl:v3.25.0

Install calicoctl as a Kubernetes pod

Use the YAML that matches your datastore type to deploy the calicoctl container to your nodes.

  • etcd

    1. kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.25.0/manifests/calicoctl-etcd.yaml

    Install calicoctl - 图24note

    You can also view the YAML in a new tab.

  • Kubernetes API datastore

    1. kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.25.0/manifests/calicoctl.yaml

    Install calicoctl - 图25note

    You can also view the YAML in a new tab.

You can then run commands using kubectl as shown below.

  1. kubectl exec -ti -n kube-system calicoctl -- /calicoctl get profiles -o wide

An example response follows.

  1. NAME                 TAGS
  2. kns.default          kns.default
  3. kns.kube-system      kns.kube-system

We recommend setting an alias as follows.

  1. alias calicoctl="kubectl exec -i -n kube-system calicoctl -- /calicoctl"

Install calicoctl - 图26note

In order to use the calicoctl alias when reading manifests, redirect the file into stdin, for example:

  1. calicoctl create -f - < my_manifest.yaml

Next step:

Configure calicoctl to connect to your datastore.