Docker container install

Big picture

Install Calico on non-cluster hosts using a Docker container for both networking and policy.

Value

Installing Calico with a Docker container includes everything you need for both networking and policy. It also automatically adds the appropriate per-node configuration to the datastore.

Before you begin…

  1. Ensure Docker is installed
  2. Ensure the Calico datastore is up and accessible from the host
  3. Ensure the host meets the minimum system requirements

How to

The calico/node container should be started at boot time by your init system and the init system must be configured to restart it if stopped. Calico relies on that behavior for certain configuration changes.

This section describes how to run calico/node as a Docker container.

Docker container install - 图1note

We include examples for systemd, but the commands can be applied to other init daemons such as upstart.

Step 1: Create environment file

Use the following guidelines and sample file to define the environment variables for starting Calico on the host. For more help, see the calico/node configuration reference

  • Kubernetes datastore
  • etcd datastore
  • Either datastore

For a Kubernetes datastore (default) set the following:

VariableConfiguration guidance
FELIX_DATASTORETYPESet to kubernetes
KUBECONFIGPath to kubeconfig file to access the Kubernetes API Server

Docker container install - 图2note

You will need to volume mount the kubeconfig file into the container at the location specified by the paths mentioned above.

For an etcdv3 datastore set the following:

VariableConfiguration guidance
DATASTORE_TYPESet to etcdv3
ETCD_ENDPOINTSComma separated list of etcdv3 cluster URLs, e.g. https://calico-datastore.example.com:2379
ETCD_CA_CERT_FILEPath to CA certificate to validate etcd’s server cert. Required if using TLS and not using a public CA.
ETCD_CERT_FILE
ETCD_KEY_FILE
Paths to certificate and keys used for client authentication to the etcd cluster, if enabled.

Docker container install - 图3note

If using certificates and keys, you will need to volume mount them into the container at the location specified by the paths mentioned above.

For either datastore set the following:

VariableConfiguration guidance
CALICO_NODENAMEIdentifies the node. If a value is not specified, the compute server hostname is used to identify the Calico node.
CALICO_IP or CALICO_IP6If values are not specified for both, Calico uses the currently-configured values for the next hop IP addresses for this node—these can be configured through the Node resource. If no next hop addresses are configured, Calico automatically determines an IPv4 next hop address by querying the host interfaces (and configures this value in the Node resource). You can set CALICO_IP to autodetect for force auto-detection of IP address every time the node starts. If you set IP addresses through these environment variables, it reconfigures any values currently set through the Node resource.
CALICO_ASIf not specified, Calico uses the currently configured value for the AS Number for the node BGP client—this can be configured through the Node resource. If the Node resource value is not set, Calico inherits the AS Number from the global default value. If you set a value through this environment variable, it reconfigures any value currently set through the Node resource.
NO_DEFAULT_POOLSSet to true to prevent Calico from creating a default pool if one does not exist. Pools are used for workload endpoints and not required for non-cluster hosts.
CALICO_NETWORKING_BACKENDThe networking backend to use. In bird mode, Calico will provide BGP networking using the BIRD BGP daemon; VXLAN networking can also be used. In vxlan mode, only VXLAN networking is provided; BIRD and BGP are disabled. If you want to run Calico for policy only, set to none.

Sample EnvironmentFile - save to /etc/calico/calico.env

  1. DATASTORE_TYPE=etcdv3
  2. ETCD_ENDPOINTS=https://calico-datastore.example.com:2379
  3. ETCD_CA_CERT_FILE="/pki/ca.pem"
  4. ETCD_CERT_FILE="/pki/client-cert.pem"
  5. ETCD_KEY_FILE="/pki/client-key.pem"
  6. CALICO_NODENAME=""
  7. NO_DEFAULT_POOLS="true"
  8. CALICO_IP=""
  9. CALICO_IP6=""
  10. CALICO_AS=""
  11. CALICO_NETWORKING_BACKEND=bird

Step 2: Configure the init system

Use an init daemon (like systemd or upstart) to start the the calico/node image as a service using the EnvironmentFile values.

Sample systemd service file: calico-node.service

  1. [Unit]
  2. Description=calico-node
  3. After=docker.service
  4. Requires=docker.service
  5. [Service]
  6. EnvironmentFile=/etc/calico/calico.env
  7. ExecStartPre=-/usr/bin/docker rm -f calico-node
  8. ExecStart=/usr/bin/docker run --net=host --privileged \
  9. --name=calico-node \
  10. -e NODENAME=${CALICO_NODENAME} \
  11. -e IP=${CALICO_IP} \
  12. -e IP6=${CALICO_IP6} \
  13. -e CALICO_NETWORKING_BACKEND=${CALICO_NETWORKING_BACKEND} \
  14. -e AS=${CALICO_AS} \
  15. -e NO_DEFAULT_POOLS=${NO_DEFAULT_POOLS} \
  16. -e DATASTORE_TYPE=${DATASTORE_TYPE} \
  17. -e ETCD_ENDPOINTS=${ETCD_ENDPOINTS} \
  18. -e ETCD_CA_CERT_FILE=${ETCD_CA_CERT_FILE} \
  19. -e ETCD_CERT_FILE=${ETCD_CERT_FILE} \
  20. -e ETCD_KEY_FILE=${ETCD_KEY_FILE} \
  21. -e KUBECONFIG=${KUBECONFIG} \
  22. -v /var/log/calico:/var/log/calico \
  23. -v /var/lib/calico:/var/lib/calico \
  24. -v /var/run/calico:/var/run/calico \
  25. -v /run/docker/plugins:/run/docker/plugins \
  26. -v /lib/modules:/lib/modules \
  27. -v /etc/pki:/pki \
  28. calico/node:v3.25.0 /bin/calico-node -felix
  29. ExecStop=-/usr/bin/docker stop calico-node
  30. Restart=on-failure
  31. StartLimitBurst=3
  32. StartLimitInterval=60s
  33. [Install]
  34. WantedBy=multi-user.target

Upon start, the systemd service:

  • Confirms Docker is installed under the [Unit] section
  • Gets environment variables from the environment file above
  • Removes existing calico/node container (if it exists)
  • Starts calico/node

The script also stops the calico/node container when the service is stopped.

Docker container install - 图4note

Depending on how you’ve installed Docker, the name of the Docker service under the [Unit] section may be different (such as docker-engine.service). Be sure to check this before starting the service.