Quickstart

8 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 control node for Calico components, and a Windows cluster for Windows nodes.

Before you begin

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.18, 1.17, or 1.16

Windows node requirements

  • Versions:
    • Windows Server 1809 (build Build 17763.1432 or greater)
    • Windows Server 1903 (AKA 19H1 build 18362.1049 or greater)
    • Windows Server 1909 (AKA 19H2 build 18362.1049 or greater), with Docker service enabled
  • 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 be installed to run Windows pods.
    • The Windows instance role must have access to secrets in the calico-system namespace or kube-system namespace if you are using a non operator-managed Calico installation.

Linux control node requirements

  • 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
?
  1. Ensure that BGP is disabled.

    kubectl patch installation default --type=merge -p '{"spec": {"calicoNetwork": {"bgp": "Disabled"}}}'
    
  2. Prepare 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 you 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 you 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 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 you 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 you 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. Prepare directory for Kubernetes files on the Windows node.

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

  3. 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
    
  4. 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 you 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 you cluster.

  5. Verify that the Calico services are running.

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

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

Configure installation parameters

Parameter Name Description Default
KubeVersion Version of Kubernetes binaries to use. If value is 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 value is 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.