Quickstart

note

The manual method for installing Calico for Windows is deprecated in favor of using the Operator and Windows HostProcess containers (HPC). Support for this method will be dropped in a future Calico version.

Big picture

Install Calico for Windows manually 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 Linux requirements and the Calico for Windows requirements.

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

How to

• Configure strict affinity for clusters using Calico networking
• Install Calico for Windows manually
• Configure installation parameters

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:

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

note

If the above command failed to find ipamconfigurations resource, you need to install the Calico API server. Please refer to installing the Calico API server.

Install Calico for Windows manually

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	IPAM	CNI	Overlay	Routing	Datastore

• Kubernetes BGP

  The geeky details of what you get by default:

  Policy	IPAM	CNI	Overlay	Routing	Datastore

• EKS

  The geeky details of what you get by default:

  Policy	IPAM	CNI	Overlay	Routing	Datastore

• AKS

  The geeky details of what you get by default:

  Policy	IPAM	CNI	Overlay	Routing	Datastore

Kubernetes VXLAN

1. 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.

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

   mkdir c:\k

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

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

   Invoke-WebRequest https://github.com/projectcalico/calico/releases/download/v3.29.1/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. The PowerShell script downloads Calico for Windows release binary, Kubernetes binaries, Windows utilities files, configures Calico 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)>

   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.
   • If your Windows nodes have multiple network adapters, you can configure the one used for VXLAN by editing VXLAN_ADAPTER in C:\CalicoWindows\config.ps1, then restarting Calico for Windows.

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

Kubernetes BGP

1. Enable BGP service on Windows node (instead of VXLAN). 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 control plane node (default, Location $HOME/.kube/config), to c:\k\config.

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

   Invoke-WebRequest https://github.com/projectcalico/calico/releases/download/v3.29.1/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. 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

EKS

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 commands 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://github.com/projectcalico/calico/releases/download/v3.29.1/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. 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

AKS

1. Register the EnableAKSWindowsCalico feature flag with the following Azure CLI command.

   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. Run 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

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

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.	""

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.