Quickstart

11 MINUTE READ

Big picture

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

Concepts

Calico for Windows is a hybrid implementation that requires a Linux cluster for Calico components and Linux workloads, and Windows nodes for Windows workloads.

Before you begin

Review the requirements below and setup a Calico cluster on Linux nodes and provision Windows machines.

Datastore requirements

Whether you use etcd or Kubernetes datastore (kdd), the datastore for the Windows node/Kubernetes cluster must be the same as the datastore for the Linux control node. (You cannot mix datastores in a Calico for Windows implementation.)

Kubernetes cluster requirements

  • Kubernetes clusters with versions 1.20, 1.19, or 1.18

Windows node requirements

  • Versions:
    • Windows Server 1809 (build 17763.1432 or greater)
    • Windows Server 2004 (build 19041)
    • Windows Server 20H2 (build 19042)

    Note: Windows Server version support differs for each Kubernetes version. Review the Windows OS Version Support table for the Windows Server versions supported by each Kubernetes version.

  • Container runtime: Docker or containerd installed and running. If containerd is running, it will be used as the container runtime otherwise Docker is assumed.
  • Remote access to the Windows node via Remote Desktop Protocol (RDP) or Windows Remote Management (WinRM)
  • Be able to run a command as Administrator using PowerShell.
  • Additionally, for EKS:
    • The VPC controllers must be installed to run Windows pods.
    • An instance role on the Windows instance must have permissions to get namespaces and get secrets in the calico-system namespace (or kube-system namespace if you are using a non operator-managed Calico installation.)
  • Additionally, for AKS:
    • Calico for Windows can be enabled only on newly created clusters.
    • Kubernetes version 1.20+

Linux control node requirements

  • A Linux cluster installed with Calico v3.12+
  • If Calico networking is being used:
    • Networking must be VXLAN or BGP without encapsulation. (Note: for EKS, networking is set to none since AWS VPC networking is used.)
    • Strict affinity must be set to true

How to

Configure strict affinity for clusters using Calico networking

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

calicoctl ipam configure --strictaffinity=true

Install Calico for Windows

The following steps install a Kubernetes cluster on a single Windows node, with a Linux control node.

  • Kubernetes VXLAN

    The geeky details of what you get by default:

Policy
Calico
IPAM
Calico
CNI
Calico
Overlay
VXLAN
Routing
Calico
Datastore
Kubernetes
?
  • Kubernetes BGP

    The geeky details of what you get by default:

Policy
Calico
IPAM
Calico
CNI
Calico
Overlay
No
Routing
BGP
Datastore
Kubernetes
?
  • EKS

    The geeky details of what you get by default:

Policy
Calico
IPAM
AWS
CNI
AWS
Overlay
No
Routing
VPC Native
Datastore
Kubernetes
?
  • AKS

    The geeky details of what you get by default:

Policy
Calico
IPAM
Azure
CNI
Azure
Overlay
No
Routing
VPC Native
Datastore
Kubernetes
?
  1. Ensure that BGP is disabled. 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 from https://docs.projectcalico.org/manifests/calico-vxlan.yaml then BGP is already disabled.

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

    mkdir c:\k
    
  3. Copy the Kubernetes kubeconfig file from the master node (default, Location $HOME/.kube/config), to c:\k\config.

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

    Invoke-WebRequest https://docs.projectcalico.org/scripts/install-calico-windows.ps1 -OutFile c:\install-calico-windows.ps1
    
  5. Install Calico for Windows for your datastore with using the default parameters or [customize installation parameters]. (#configure-installation-parameters). The PowerShell script downloads Calico for Windows release binary, Kubernetes binaries, Windows utilities files, configures Calico for Windows, and starts the Calico service.

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

    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)>
    

    etcd datastore

    c:\install-calico-windows.ps1 -KubeVersion <your Kubernetes version (e.g. 1.18.6)> `
                                  -Datastore etcdv3 `
                                  -EtcdEndpoints <your etcd endpoint ip> `
                                  -EtcdTlsSecretName <your etcd TLS secret name in calico-system namespace> (default no etcd TLS secret is used) `
                                  -EtcdKey <path to key file> (default not using TLS) `
                                  -EtcdCert <path to cert file> (default not using TLS) `
                                  -EtcdCaCert <path to ca cert file> (default not using TLS) `
                                  -ServiceCidr <your service cidr (default 10.96.0.0/12)> `
                                  -DNSServerIPs <your DNS server IPs (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.

  6. Verify that the Calico services are running.

    Get-Service -Name CalicoNode
    Get-Service -Name CalicoFelix
    
  7. Install and start kubelet/kube-proxy service. Execute following PowerShell script/commands.

    C:\CalicoWindows\kubernetes\install-kube-services.ps1
    Start-Service -Name kubelet
    Start-Service -Name kube-proxy
    
  8. Verify kubelet/kube-proxy services are running.

    Get-Service -Name kubelet
    Get-Service -Name kube-proxy
    
  1. Enable BGP service on Windows node. Install the RemoteAccess service using the following Powershell commands:

    Install-WindowsFeature RemoteAccess
    Install-WindowsFeature RSAT-RemoteAccess-PowerShell
    Install-WindowsFeature Routing
    

    Then restart the computer:

    Restart-Computer -Force
    

    before running:

    Install-RemoteAccess -VpnType RoutingOnly
    

    Sometimes the remote access service fails to start automatically after install. To make sure it is running, execute the following command:

    Start-Service RemoteAccess
    
  2. Prepare the directory for Kubernetes files on Windows node.

    mkdir c:\k
    
  3. Copy the Kubernetes kubeconfig file from the master node (default, Location $HOME/.kube/config), to c:\k\config.

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

    Invoke-WebRequest https://docs.projectcalico.org/scripts/install-calico-windows.ps1 -OutFile c:\install-calico-windows.ps1
    
  5. Install Calico for Windows for your datastore with using the default parameters or [customize installation parameters]. (#configure-installation-parameters). The PowerShell script downloads Calico for Windows release binary, Kubernetes binaries, Windows utilities files, configures Calico for Windows, and starts the Calico service.

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

    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)>
    

    etcd datastore

    c:\install-calico-windows.ps1 -KubeVersion <your Kubernetes version (e.g. 1.18.6)> `
                                  -Datastore etcdv3 `
                                  -EtcdEndpoints <your etcd endpoint ip> `
                                  -EtcdTlsSecretName <your etcd TLS secret name in calico-system namespace> (default no etcd TLS secret is used) `
                                  -EtcdKey <path to key file> (default not using TLS) `
                                  -EtcdCert <path to cert file> (default not using TLS) `
                                  -EtcdCaCert <path to ca cert file> (default not using TLS) `
                                  -ServiceCidr <your service cidr (default 10.96.0.0/12)> `
                                  -DNSServerIPs <your DNS server IPs (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.

  6. Verify that the Calico services are running.

    Get-Service -Name CalicoNode
    Get-Service -Name CalicoFelix
    
  7. Install and start kubelet/kube-proxy service. Execute following PowerShell script/commands.

    C:\CalicoWindows\kubernetes\install-kube-services.ps1
    Start-Service -Name kubelet
    Start-Service -Name kube-proxy
    
  8. Verify kubelet/kube-proxy services are running.

    Get-Service -Name kubelet
    Get-Service -Name kube-proxy
    
  1. Ensure that a Windows instance role has permissions to get namespaces and to get secrets in the calico-system namespace (or kube-system namespace if you are using a non operator-managed Calico installation.) One way to do this is by running the following comands to install the required permissions temporarily. Before running the commands, replace <eks_node_name> with the Kubernetes node name of the EKS Windows node, for example ip-192-168-42-34.us-west-2.compute.internal.

    Note: If you are using a non operator-managed Calico installation, replace the namespace calico-system with kube-system in the commands below.

    kubectl create clusterrole calico-install-ns --verb=get --resource=namespace
    kubectl create clusterrolebinding calico-install-ns --clusterrole=calico-install-ns --user=system:node:<eks_node_name>
    kubectl create role calico-install-token --verb=get,list --resource=secrets --namespace calico-system
    kubectl create rolebinding calico-install-token --role=calico-install-token --user=system:node:<eks_node_name> --namespace calico-system
    
  2. Prepare the directory for Kubernetes files on the Windows node.

    mkdir c:\k
    
  3. Install kubectl and move the kubectl binary to c:\k.

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

    Invoke-WebRequest https://docs.projectcalico.org/scripts/install-calico-windows.ps1 -OutFile c:\install-calico-windows.ps1
    
  5. Install Calico for Windows for your datastore with using the default parameters or [customize installation parameters]. (#configure-installation-parameters). The PowerShell script downloads Calico for Windows release binary, Kubernetes binaries, Windows utilities files, configures Calico for Windows, and starts the Calico service.

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

    Kubernetes datastore (default)

    c:\install-calico-windows.ps1 -ServiceCidr <your service cidr (default 10.96.0.0/12)> `
                                  -DNSServerIPs <your DNS service IP (default 10.96.0.10)>
    

    etcd datastore

    c:\install-calico-windows.ps1 -Datastore etcdv3 `
                                  -EtcdEndpoints <your etcd endpoint ip> `
                                  -ServiceCidr <your service cidr (default 10.96.0.0/12)> `
                                  -DNSServerIPs <your DNS server IPs (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.

  6. Verify that the Calico services are running.

    Get-Service -Name CalicoNode
    Get-Service -Name CalicoFelix
    
  7. Verify kubelet and kube-proxy services are running.

    Get-Service -Name kubelet
    Get-Service -Name kube-proxy
    
  8. If you installed temporary RBAC in the first step, remove the permissions by running the following commands.

    Note: If you are using a non operator-managed Calico installation, replace the namespace calico-system with kube-system in the commands below.

    kubectl delete clusterrolebinding calico-install-ns
    kubectl delete clusterrole calico-install-ns
    kubectl delete rolebinding calico-install-token --namespace calico-system
    kubectl delete role calico-install-token --namespace calico-system
    
  1. Register the EnableAKSWindowsCalico feature flag with the following Azure CLI commad.

    az feature register --namespace "Microsoft.ContainerService" --name "EnableAKSWindowsCalico"
    
  2. Wait until the EnableAKSWindowsCalico feature flag is registered successfully. Execute following CLI command to get current status of the feature.

    az feature list -o table --query "[?contains(name, 'Microsoft.ContainerService/EnableAKSWindowsCalico')].{Name:name,State:properties.state}"
    

    Move to next step if the output from above command matches the following output.

    Name                                               State
    -------------------------------------------------  ----------
    Microsoft.ContainerService/EnableAKSWindowsCalico  Registered
    
  3. Refresh the registration of the Microsoft.ContainerService resource provider. Execute the following command.

    az provider register --namespace Microsoft.ContainerService
    
  4. Create the AKS cluster with these settings: network-plugin to azure, and network-policy to calico. For example,

    az group create -n $your-resource-group -l $your-region
    az aks create \
     --resource-group $your-resource-group \
     --name $your-cluster-name \
     --node-count 1 \
     --enable-addons monitoring \
     --windows-admin-username azureuser \
     --windows-admin-password $your-windows-password \
     --kubernetes-version 1.20.2 \
     --vm-set-type VirtualMachineScaleSets \
     --service-principal $your-service-principal \
     --client-secret $your-client-secret \
     --load-balancer-sku standard \
     --node-vm-size Standard_D2s_v3 \
     --network-plugin azure \
     --network-policy calico
    
  5. Add a Windows node pool. For example,

    az aks nodepool add \
     --resource-group $your-resource-group \
     --cluster-name $your-cluster-name \
     --os-type Windows \
     --name $your-windows-node-pool-name \
     --node-count 1 \
     --kubernetes-version 1.20.2 \
     --node-vm-size Standard_D2s_v3
    

Configure installation parameters

Parameter Name Description Default
KubeVersion Version of Kubernetes binaries to use. If the value is an empty string (default), the Calico for Windows installation script does not download Kubernetes binaries and run Kubernetes service. Use the default for managed public cloud. ””
DownloadOnly Download without installing Calico for Windows. Set to yes to manually install and configure Calico for Windows. For example, Calico for Windows the hard way. no
Datastore Calico for Windows datastore type [kubernetes or etcdv3] for reading endpoints and policy information. kubernetes
EtcdEndpoints Comma-delimited list of etcd connection endpoints. Example: http://127.0.0.1:2379,http://127.0.0.2:2379. Valid only if Datastore is set to etcdv3. ””
EtcdTlsSecretName Name of a secret in calico-system namespace which contains etcd-key, etcd-cert, etcd-ca for automatically configuring TLS. Either use this or parameters EtcdKey, EtcdCert, EtcdCaCert below. Note: If you are not using operator-based installation, use namespace kube-system. ””
EtcdKey Path to key file for etcd TLS connection. ””
EtcdCert Path to certificate file for etcd TLS connection. ””
EtcdCaCert Path to CA certificate file for etcd TLS connection. ””
ServiceCidr Service IP range of the Kubernetes cluster. Not required for most managed Kubernetes clusters. Note: EKS has non-default value. 10.96.0.0/12
DNSServerIPs Comma-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
CalicoBackend Calico backend network type (vxlan or bgp). If the value is an empty string (default), backend network type is auto detected. ””

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

Next steps

You can now use the Calico 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.