Skip to content

Commit 2bc6a35

Browse files
jsturtevantjsturtevant
committed
Add documentation
1 parent 460b51d commit 2bc6a35

File tree

3 files changed

+135
-3
lines changed

3 files changed

+135
-3
lines changed

‎docs/book/src/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,3 +17,4 @@
1717
- [Managed Clusters (AKS)](./topics/managedcluster.md)
1818
- [Spot Virtual Machines](./topics/spot-vms.md)
1919
- [Virtual Networks](./topics/custom-vnet.md)
20+
- [Windows](./topics/windows.md)

‎docs/book/src/topics/windows.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# Windows clusters
2+
3+
## Overview
4+
5+
CAPZ enables you to create Windows Kubernetes clusters on Microsoft Azure.
6+
7+
To deploy a cluster using Windows, use the [Windows flavor template](https://raw.githubusercontent.com/kubernetes-sigs/cluster-api-provider-azure/master/templates/cluster-template-windows.yaml).
8+
9+
## Deploy a workload
10+
11+
After you Windows VM is up and running you can deploy a workload. Using the deployment file below:
12+
13+
```
14+
apiVersion: apps/v1
15+
kind: Deployment
16+
metadata:
17+
name: iis-1809
18+
labels:
19+
app: iis-1809
20+
spec:
21+
replicas: 1
22+
template:
23+
metadata:
24+
name: iis-1809
25+
labels:
26+
app: iis-1809
27+
spec:
28+
containers:
29+
- name: iis
30+
image: mcr.microsoft.com/windows/servercore/iis:windowsservercore-ltsc2019
31+
resources:
32+
limits:
33+
cpu: 1
34+
memory: 800m
35+
requests:
36+
cpu: .1
37+
memory: 300m
38+
ports:
39+
- containerPort: 80
40+
nodeSelector:
41+
"kubernetes.io/os": windows
42+
selector:
43+
matchLabels:
44+
app: iis-1809
45+
---
46+
apiVersion: v1
47+
kind: Service
48+
metadata:
49+
name: iis
50+
spec:
51+
type: LoadBalancer
52+
ports:
53+
- protocol: TCP
54+
port: 80
55+
selector:
56+
app: iis-1809
57+
```
58+
59+
Save this file to iis.yaml then deploy it:
60+
61+
```
62+
kubectl apply -f .\iis.yaml
63+
```
64+
65+
Get the Service endpoint and curl the website:
66+
67+
```
68+
kubectl get services
69+
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
70+
iis LoadBalancer 10.0.9.47 <pending> 80:31240/TCP 1m
71+
kubernetes ClusterIP 10.0.0.1 <none> 443/TCP 46m
72+
73+
74+
curl <EXTERNAL-IP>
75+
```
76+
77+
## Details
78+
79+
See the CAPI proposal for implementation details: https://github.com/kubernetes-sigs/cluster-api/blob/master/docs/proposals/20200804-windows-support.md
80+
81+
### VM and VMSS naming
82+
83+
Azure does not support creating Windows VM's with names longer than 15 characters ([see additional details historical restrictions](https://github.com/kubernetes-sigs/cluster-api/issues/2217#issuecomment-743336941)).
84+
85+
When creating a cluster with `AzureMachine` if the AzureMachine is longer than 15 characters then the first 9 characters of the cluster name and appends the last 5 characters of the machine to create a unique machine name.
86+
87+
When creating a cluster with `Machinepool` if the Machine Pool name is longer than 9 characters then the Machine pool uses the prefix `win` and appends the last 5 characters of the machine pool name.
88+
89+
### VM password and access
90+
The VM password is [random generated](https://cloudbase-init.readthedocs.io/en/latest/plugins.html#setting-password-main)
91+
by Cloudbase-init during provisioning of the VM. For Access to the VM you can use ssh which will be configured with SSH
92+
public key you provided during deployment.
93+
94+
To SSH:
95+
96+
```
97+
ssh -t -i .sshkey -o 'ProxyCommand ssh -i .sshkey -W %h:%p capi@<api-server-ip>' capi@<windows-ip> powershell.exe
98+
```
99+
100+
> There is also a [CAPZ kubectl plugin](https://github.com/kubernetes-sigs/cluster-api-provider-azure/blob/master/hack/debugging/Readme.md) that automates the ssh connection using the Management cluster
101+
102+
To RDP:
103+
104+
```
105+
ssh -L 5555:10.1.0.4:3389 [email protected]
106+
```
107+
108+
And then open an RDP client to `localhost:5555`
109+
110+
### Image creation
111+
The images are built using [image-builder](https://github.com/kubernetes-sigs/image-builder) and published the the Azure Market place. They use [Cloudbase-init](https://cloudbase-init.readthedocs.io/en/latest/) to bootstrap the machines via Kubeadm.
112+
113+
Find the latest published images:
114+
115+
```
116+
az vm image list --publisher cncf-upstream --offer capi-windows -o table --all
117+
Offer Publisher Sku Urn Version
118+
------------ ------------- ---------------------------- ------------------------------------------------------------------ ----------
119+
capi-windows cncf-upstream k8s-1dot18dot13-windows-2019 cncf-upstream:capi-windows:k8s-1dot18dot13-windows-2019:2020.12.11 2020.12.11
120+
capi-windows cncf-upstream k8s-1dot19dot5-windows-2019 cncf-upstream:capi-windows:k8s-1dot19dot5-windows-2019:2020.12.11 2020.12.11
121+
capi-windows cncf-upstream k8s-1dot20dot0-windows-2019 cncf-upstream:capi-windows:k8s-1dot20dot0-windows-2019:2020.12.11 2020.12.11
122+
```
123+
124+
If you would like customize your images please refer to the documentation on building your own [custom images](custom-images.md).
125+
126+
### Kube-proxy and CNIs
127+
128+
Kube-proxy and Windows CNIs are deployed via Cluster Resource Sets. Windows doesn't not have a kube-proxy image due
129+
to not having Privileged containers which would provide access to the host. The current solution is using wins.exe as
130+
demonstrated in the [Kubeadm support for Windows](https://kubernetes.io/docs/tasks/administer-cluster/kubeadm/adding-windows-nodes/).
131+
132+
Windows Privileged Container support is in [KEP](https://github.com/kubernetes/enhancements/pull/2037) form with plans to
133+
implement in 1.21. Kube-proxy and other CNI will then be replaced with the Privileged containers.

‎templates/flavors/windows/kustomization.yaml‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,4 @@ resources:
33
- ../base
44
- machine-deployment.yaml
55
- machine-deployment-windows.yaml
6-
patchesStrategicMerge:
7-
- kubeadm-control-plane.yaml
8-
- cluster.yaml
6+

0 commit comments

Comments
 (0)