Quickstart

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
Kubernetes BGP
EKS
AKS

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.
Prepare the directory for Kubernetes files on Windows node.
```
mkdir c:\k
```
Copy the Kubernetes kubeconfig file from the control plane node (default, Location $HOME/.kube/config), to c:\k\config.

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

Invoke-WebRequest https://github.com/projectcalico/calico/releases/download/v3.28.2/install-calico-windows.ps1 -OutFile c:\install-calico-windows.ps1

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.

Verify that the Calico services are running.

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

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

Verify kubelet/kube-proxy services are running.

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

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
```
Prepare the directory for Kubernetes files on Windows node.
```
mkdir c:\k
```
Copy the Kubernetes kubeconfig file from the control plane node (default, Location $HOME/.kube/config), to c:\k\config.

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

Invoke-WebRequest https://github.com/projectcalico/calico/releases/download/v3.28.2/install-calico-windows.ps1 -OutFile c:\install-calico-windows.ps1

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.

Verify that the Calico services are running.

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

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

Verify kubelet/kube-proxy services are running.

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

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
```
Prepare the directory for Kubernetes files on the Windows node.
```
mkdir c:\k
```
Install kubectl and move the kubectl binary to c:\k.

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

Invoke-WebRequest https://github.com/projectcalico/calico/releases/download/v3.28.2/install-calico-windows.ps1 -OutFile c:\install-calico-windows.ps1

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.

Verify that the Calico services are running.

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

Verify kubelet and kube-proxy services are running.

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

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

az feature register --namespace "Microsoft.ContainerService" --name "EnableAKSWindowsCalico"

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

Refresh the registration of the Microsoft.ContainerService resource provider. Run the following command.
```
az provider register --namespace Microsoft.ContainerService
```

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

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.