Skip to main content
Version: 3.17 (latest)

Quickstart

Big picture​

Install Calico Enterprise for Windows on your Kubernetes cluster in approximately 5 minutes.

Concepts​

Calico Enterprise for Windows is a hybrid implementation that requires a Linux control node for Calico Enterprise components and Windows nodes for Windows pods.

Before you begin​

Review the Linux requirements and the Calico Enterprise for Windows requirements.

Before beginning the quickstart, setup a Calico Enterprise cluster on Linux nodes and provision Windows machines.

How to​

Configure strict affinity for clusters using Calico Enterprise networking​

For Linux control nodes using Calico Enterprise networking, strict affinity must be set to true. This is required to prevent Linux nodes from borrowing IP addresses from Windows nodes:

kubectl patch ipamconfigurations default --type merge --patch='{"spec": {"strictAffinity": true}}'

Install Calico Enterprise for Windows manually​

The following steps install a Kubernetes cluster on a single Windows node with a minimum of 4 Linux worker nodes.

  • Kubernetes VXLAN

    The geeky details of what you get by default:

    PolicyIPAMCNIOverlayRoutingDatastore

  • Kubernetes BGP

    The geeky details of what you get by default:

    PolicyIPAMCNIOverlayRoutingDatastore

  • EKS

    The geeky details of what you get by default:

    PolicyIPAMCNIOverlayRoutingDatastore

  • AKS

    The geeky details of what you get by default:

    PolicyIPAMCNIOverlayRoutingDatastore

  1. Setup a Calico Enterprise Kubernetes cluster with Windows nodes.

  2. Ensure that BGP is disabled since you're using VXLAN. If you installed Calico using operator, you can do this by:

    kubectl patch installation default --type=merge -p '{"spec": {"calicoNetwork": {"bgp": "Disabled"}}}'

    If you installed Calico using the manifest then BGP is already disabled.

  3. Prepare the directory for Kubernetes files on Windows node.

    mkdir c:\k

  4. Copy the Kubernetes kubeconfig file from the control plane node (default, Location $HOME/.kube/config), to c:\k\config.

  5. Copy the Calico Enterprise for Windows installation zip file to c:\tigera-calico-windows.zip.

  6. Download the PowerShell script, install-calico-windows.ps1.

    Invoke-WebRequest https://docs.tigera.io/calico-enterprise/3.17/scripts/install-calico-windows.ps1 -OutFile c:\install-calico-windows.ps1

  7. Install Calico Enterprise for Windows for your datastore with using the default parameters or customize installation parameters. The PowerShell script downloads Calico Enterprise for Windows release binary, Kubernetes binaries, Windows utilities files, configures Calico Enterprise for Windows, and starts the Calico service.

    Kubernetes datastore (default)

    c:\install-calico-windows.ps1 -KubeVersion <your Kubernetes version (e.g. 1.18.6)> `
                                  -ServiceCidr <your service cidr (default 10.96.0.0/12)> `
                                  -DNSServerIPs <your DNS service IP (default 10.96.0.10)>
    note

    You do not need to pass a parameter if the default value of the parameter is correct for your cluster.

    note

    If your Windows nodes have multiple network adapters, you can configure the one used for VXLAN by editing VXLAN_ADAPTER in C:\TigeraCalico\config.ps1, then restarting Calico Enterprise for Windows.

  8. Verify that the Calico Enterprise services are running.

    Get-Service -Name CalicoNode
    Get-Service -Name CalicoFelix

  9. Install and start kubelet/kube-proxy service. Execute following PowerShell script/commands.

    C:\TigeraCalico\kubernetes\install-kube-services.ps1
    Start-Service -Name kubelet
    Start-Service -Name kube-proxy

  10. Verify kubelet/kube-proxy services are running.

    Get-Service -Name kubelet
    Get-Service -Name kube-proxy

Congratulations! You now have a Kubernetes cluster with Calico Enterprise for Windows and a Linux control node.

Install Calico Enterprise for Windows using HostProcess containers​

note

This installation method is a tech preview and should not be used for production clusters. Upgrades from a tech preview version of this installation method to the GA version might not be seamless.

With Kubernetes v1.22, a new Windows container type called "HostProcess containers" can run directly on the host with access to the host network namespace, storage, and devices. With this feature, Calico Enterprise for Windows can now be installed and managed using Kubernetes resources such as Daemonsets and ConfigMaps, instead of needing to configure and install Calico Enterprise for Windows manually on each node. Using this installation method, the Calico Enterprise for Windows services are no longer registered on the host. Instead, the services are run directly within HostProcess containers.

Requirements​

In addition to the Calico Enterprise for Windows requirements, this installation method has additional requirements:

  • Kubernetes v1.22+
  • HostProcess containers support enabled: for v1.22, HostProcess containers support has to be enabled. For Kubernetes v1.23+, HostProcess containers are enabled by default.
  • ContainerD 1.6.0+
  • The Windows nodes have joined the cluster

To install ContainerD on the Windows node and configure the ContainerD service:

Invoke-WebRequest https://docs.tigera.io/calico-enterprise/3.17/scripts/Install-Containerd.ps1 -OutFile c:\Install-Containerd.ps1
c:\Install-Containerd.ps1 -ContainerDVersion 1.6.2 -CNIConfigPath "c:/etc/cni/net.d" -CNIBinPath "c:/opt/cni/bin"

If you have an existing Calico Enterprise for Windows installation using the manual method, your Windows nodes may have already joined the cluster.

To join a Windows node to a cluster provisioned with kubeadm:

  • Install kubeadm and kubelet binaries and install the kubelet service
Invoke-WebRequest https://docs.tigera.io/calico-enterprise/3.17/scripts/PrepareNode.ps1 -OutFile c:\PrepareNode.ps1
c:\PrepareNode.ps1 -KubernetesVersion v1.23.4 -ContainerRuntime ContainerD
  • Run kubeadm on a control plane host and copy the join command
kubeadm token create --print-join-command
  • Edit the join command by appending --cri-socket "npipe:////./pipe/containerd-containerd" and update the kubeadm.exe path to c:\k\kubeadm.exe. An example join command:
c:\k\kubeadm.exe join 172.16.101.139:6443 --token v8w2jt.jmc45acn85dbll1e --discovery-token-ca-cert-hash sha256:d0b7040a704d8deb805ba1f29f56bbc7cea8af6aafa78137a9338a62831739b4 --cri-socket "npipe:////./pipe/containerd-containerd"
  • Run the join command on the Windows node. Shortly after it completes successfully, the Windows node will appear in kubectl get nodes. The new node's status will be NotReady since the Calico CNI has not yet been installed.

Migrating from Calico Enterprise for Windows installed manually​

If your Windows nodes already have Calico Enterprise for Windows installed using the manual installation method, you can continue this quickstart guide to migrate to a manifest-based installation. This installation process will uninstall any existing Calico Enterprise for Windows services and overwrite the Calico Enterprise for Windows installation files with those included in the calico/windows image. If kubelet and kube-proxy were installed using C:\TigeraCalico\kubernetes\install-kube-services.ps1, those services will updated in-place and remain installed. If those services were running, they are restarted so those services will be updated in place and remain installed.

note

Before proceeding, take note of the configuration parameters in C:\TigeraCalico\config.ps1. These configuration parameters will be needed during the install.

Install​

  1. Ensure that BGP is disabled.
    • If you installed Calico Enterprise using the manifest, BGP is already disabled.
    • If you installed Calico Enterprise using the operator, run this command:

      • kubectl patch installation default --type=merge -p '{"spec": {"calicoNetwork": {"bgp": "Disabled"}}}'

  2. Download the Calico Enterprise for Windows installation manifest.

    curl https://downloads.tigera.io/ee/v3.17.3/manifests/calico-windows-vxlan.yaml -o calico-windows.yaml

  3. Get the cluster's Kubernetes API server host and port, which will be used to update the Calico Enterprise for Windows config map. The API server host and port is required so that the Calico Enterprise for Windows installation script can create a kubeconfig file for Calico Enterprise services. If your Windows nodes already have Calico Enterprise for Windows installed manually, skip this step. The installation script will use the API server host and port from your node's existing kubeconfig file if the KUBERNETES_SERVICE_HOST and KUBERNETES_SERVICE_PORT variables are not provided in the calico-windows-config ConfigMap.

    First, make a note of the address of the API server:

    • If you have a single API server with a static IP address, you can use its IP address and port. The IP can be found by running:

      kubectl get endpoints kubernetes -o wide

      The output should look like the following, with a single IP address and port under "ENDPOINTS":

      NAME         ENDPOINTS             AGE
      kubernetes   172.16.101.157:6443   40m

      If there are multiple entries under "ENDPOINTS", then your cluster must have more than one API server. In this case, use the appropriate load balancing option below for your cluster.

    • If using DNS load balancing (as used by kops), use the FQDN and port of the API server api.internal.<clustername>.

    • If you have multiple API servers with a load balancer in front, you should use the IP and port of the load balancer.

      • tip

      If your cluster uses a ConfigMap to configure kube-proxy you can find the "right" way to reach the API server by examining the config map. For example:

      kubectl get configmap -n kube-system kube-proxy -o yaml | grep server`
      server: https://d881b853ae312e00302a84f1e346a77.gr7.us-west-2.eks.amazonaws.com

      In this case, the server is d881b853aea312e00302a84f1e346a77.gr7.us-west-2.eks.amazonaws.com and the port is 443 (the standard HTTPS port).

  4. Edit the calico-windows-config ConfigMap in the downloaded manifest and ensure the required variables are correct for your cluster.

    • CALICO_NETWORKING_BACKEND: This should be set to vxlan.
    • KUBERNETES_SERVICE_HOST and KUBERNETES_SERVICE_PORT: The Kubernetes API server host and port (discovered in the previous step) used to create a kubeconfig file for Calico Enterprise services. If your node already has an existing kubeconfig file, leave these variables blank.
    • K8S_SERVICE_CIDR: The Kubernetes service clusterIP range configured in your cluster. This must match the service-cluster-ip-range used by kube-apiserver.
    • CNI_BIN_DIR: Path where Calico Enterprise CNI binaries will be installed. This must match the CNI bin value in the ContainerD service configuration. If you used the provided Install-Containerd.ps1 script, you should use the CNI bin path value you provided to that script.
    • CNI_CONF_DIR: Path where Calico Enterprise CNI configuration will be installed. This must match the CNI conf value in the ContainerD service configuration. If you used the provided Install-Containerd.ps1 script, you should use the CNI conf path value you provided to that script.
    • DNS_NAME_SERVERS: The DNS nameservers that will be used in the CNI configuration.
    • FELIX_HEALTHENABLED: The Felix health check server must be enabled.

  5. Apply the Calico Enterprise for Windows installation manifest.

    kubectl create -f calico-windows.yaml

  6. Monitor the installation.

    kubectl logs -f -n calico-system -l k8s-app=calico-node-windows -c install

    After the log Calico for Windows installed appears, installation is complete. Next, the Calico Enterprise for Windows services are started in separate containers:

    kubectl logs -f -n calico-system -l k8s-app=calico-node-windows -c node
    kubectl logs -f -n calico-system -l k8s-app=calico-node-windows -c felix
  7. Install kube-proxy.

    Depending on your platform, you may already have kube-proxy running on your Windows nodes. If kube-proxy is already running on your Windows nodes, skip this step. If kube-proxy is not running, you must install and run kube-proxy on each of the Windows nodes in your cluster. Note: The provided manifest depends on the kubeconfig provided by the kube-proxy ConfigMap in the kube-system namespace.

    • Download the kube-proxy manifest:

      curl https://downloads.tigera.io/ee/v3.17.3/manifests/windows-kube-proxy.yaml -o windows-kube-proxy.yaml
    • Edit the downloaded manifest
      • Replace VERSION with your Windows nodes' server version. E.g. 1809.
      • Update the K8S_VERSION env variable value with your Kubernetes cluster version.

    • Apply the manifest

      kubectl apply -f windows-kube-proxy.yaml

    • Verify the kube-proxy-windows daemonset is running

      kubectl describe ds -n kube-system kube-proxy-windows

Congratulations! You now have a Kubernetes cluster with Calico Enterprise for Windows and a Linux control node.

Configure installation parameters​

Parameter NameDescriptionDefault
KubeVersionVersion of Kubernetes binaries to use. If the value is an empty string (default), the Calico Enterprise for Windows installation script does not download Kubernetes binaries and run Kubernetes service. Use the default for managed public cloud.""
DownloadOnlyDownload without installing Calico Enterprise for Windows. Set to yes to manually install and configure Calico Enterprise for Windows. For example, Calico Enterprise for Windows the hard way.no
DatastoreCalico Enterprise for Windows datastore type [kubernetes] for reading endpoints and policy information.kubernetes
ServiceCidrService IP range of the Kubernetes cluster. Not required for most managed Kubernetes clusters. Note: EKS has non-default value.10.96.0.0/12
DNSServerIPsComma-delimited list of DNS service IPs used by Windows pod. Not required for most managed Kubernetes clusters. Note: EKS has a non-default value.10.96.0.10
CalicoBackendCalico backend network type (vxlan or bgp). If the value is an empty string (default), backend network type is auto detected.""

Next steps​

You can now use the Calico Enterprise Linux-based docs site for your documentation. Before you continue, review the Limitations and known issues to understand the features (and sections of documentation) that do not apply to Windows.