Skip to content

Commit 928f0c4

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #793 from mboersma/custom-image-docs
📖 document how to use custom images
2 parents 03df29c + 2c6ec7d commit 928f0c4

File tree

2 files changed

+139
-5
lines changed

2 files changed

+139
-5
lines changed

‎docs/getting-started.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@ An Azure Service Principal is needed for populating the controller manifests. Th
7575
export AZURE_LOCATION="eastus" # this should be an Azure region that your subscription has quota for.
7676
```
7777

78-
:warning: NOTE: If your password contains single quotes (`'`), make sure to escape them. To escape a single quote, close the quoting before it, insert the single quote, and re-open the quoting.
78+
:warning: NOTE: If your password contains single quotes (`'`), make sure to escape them. To escape a single quote, close the quoting before it, insert the single quote, and re-open the quoting.
7979
For example, if your password is `foo'blah$`, you should do `export AZURE_CLIENT_SECRET='foo'\''blah$'`.
8080

8181
5. Set the name of the AzureCloud to be used, the default value that would be used by most users is "AzurePublicCloud", other values are:
@@ -93,22 +93,22 @@ export AZURE_ENVIRONMENT="AzurePublicCloud"
9393

9494
### Using images
9595

96-
By default, the code will use the Azure Marketplace "capi" offer. You can list the available images with:
96+
By default, images offered by "capi" in the Azure Marketplace are used. You can list these *reference images* with this command:
9797

9898
```bash
9999
az vm image list --publisher cncf-upstream --offer capi --all -o table
100100
```
101101

102-
You can also [build your own image](https://image-builder.sigs.k8s.io/capi/providers/azure.html) and specify the image ID in the manifests generated in the AzureMachine specs.
102+
For more control over your nodes, you can use a [*custom image*][custom-images].
103103

104104
## Troubleshooting
105105

106106
Please refer to the [troubleshooting guide][troubleshooting].
107107

108-
[troubleshooting]: /docs/troubleshooting.md
109-
110108
## Building from master
111109

112110
If you're interested in developing cluster-api-provider-azure and getting the latest version from `master`, please follow the [development guide][development].
113111

112+
[custom-images]: /docs/topics/custom-images.md
114113
[development]: /docs/development.md
114+
[troubleshooting]: /docs/troubleshooting.md

‎docs/topics/custom-images.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# Custom images
2+
3+
This document will help you get a CAPZ Kubernetes cluster up and running with your custom image.
4+
5+
## Reference images
6+
7+
An *image* defines the operating system and Kubernetes components that will populate the disk of each node in your cluster.
8+
9+
By default, images offered by "capi" in the [Azure Marketplace][azure-marketplace] are used. You can list these *reference images* with this command:
10+
11+
```bash
12+
az vm image list --publisher cncf-upstream --offer capi --all -o table
13+
```
14+
15+
But for more control over your nodes, you should build and use a *custom image*.
16+
17+
## Building a custom image
18+
19+
Cluster API uses the Kubernetes [Image Builder][image-builder] tools. You should use the [Azure images][image-builder-azure] from that project as a starting point for your custom image.
20+
21+
[The Image Builder Book][capi-images] explains how to build the images defined in that repository, with instructions for [Azure CAPI Images][azure-capi-images] in particular.
22+
23+
### Operating system requirements
24+
25+
For your custom image to work with Cluster API, it must meet the operating system requirements of the bootstrap provider. For example, the default `kubeadm` bootstrap provider has a set of [`preflight checks`][kubeadm-preflight-checks] that a VM is expected to pass before it can join the cluster.
26+
27+
### Kubernetes version requirements
28+
29+
The reference images are each built to support a specific version of Kubernetes. When using your custom images based on them, take care to match the image to the `version:` field of the `KubeadmControlPlane` and `MachineDeployment` in the YAML template for your workload cluster.
30+
31+
To upgrade to a new Kubernetes release with custom images requires this preparation:
32+
33+
- create a new custom image which supports the Kubernetes release version
34+
- copy the existing `AzureMachineTemplate` and change its `image:` section to reference the new custom image
35+
- create the new `AzureMachineTemplate` on the management cluster
36+
- modify the existing `KubeadmControlPlane` and `MachineDeployment` to reference the new `AzureMachineTemplate` and update the `version:` field to match
37+
38+
See [Upgrading workload clusters][upgrading-workload-clusters] for more details.
39+
40+
## Creating a cluster from a custom image
41+
42+
To use a custom image, it needs to be referenced in an `image:` section of your `AzureMachineTemplate`. See below for more specific examples.
43+
44+
### Using Shared Image Gallery (Recommended)
45+
46+
To use an image from the [Shared Image Gallery][shared-image-gallery], fill in the `resourceGroup`, `name`, `subscriptionID`, `gallery`, and `version` fields:
47+
48+
```yaml
49+
apiVersion: infrastructure.cluster.x-k8s.io/v1alpha3
50+
kind: AzureMachineTemplate
51+
metadata:
52+
name: capz-shared-gallery-example
53+
spec:
54+
template:
55+
spec:
56+
image:
57+
resourceGroup: "cluster-api-images"
58+
name: "capi-1234567890"
59+
subscriptionID: "01234567-89ab-cdef-0123-4567890abcde"
60+
gallery: "ClusterAPI"
61+
version: "0.3.1234567890"
62+
```
63+
64+
If you build Azure CAPI images with the `make` targets in Image Builder, these required values are printed after a successful build. For example:
65+
66+
```bash
67+
$ make -C images/capi/ build-azure-sig-ubuntu-1804
68+
# many minutes later...
69+
==> sig-ubuntu-1804:
70+
Build 'sig-ubuntu-1804' finished.
71+
72+
==> Builds finished. The artifacts of successful builds are:
73+
--> sig-ubuntu-1804: Azure.ResourceManagement.VMImage:
74+
75+
OSType: Linux
76+
ManagedImageResourceGroupName: cluster-api-images
77+
ManagedImageName: capi-1234567890
78+
ManagedImageId: /subscriptions/01234567-89ab-cdef-0123-4567890abcde/resourceGroups/cluster-api-images/providers/Microsoft.Compute/images/capi-1234567890
79+
ManagedImageLocation: southcentralus
80+
ManagedImageSharedImageGalleryId: /subscriptions/01234567-89ab-cdef-0123-4567890abcde/resourceGroups/cluster-api-images/providers/Microsoft.Compute/galleries/ClusterAPI/images/capi-ubuntu-1804/versions/0.3.1234567890
81+
```
82+
83+
Please also see the [replication recommendations][replication-recommendations] for the Shared Image Gallery.
84+
85+
### Using image ID
86+
87+
To use a managed image resource by ID, only the `id` field must be set:
88+
89+
```yaml
90+
apiVersion: infrastructure.cluster.x-k8s.io/v1alpha3
91+
kind: AzureMachineTemplate
92+
metadata:
93+
name: capz-image-id-example
94+
spec:
95+
template:
96+
spec:
97+
image:
98+
id: "/subscriptions/01234567-89ab-cdef-0123-4567890abcde/resourceGroups/myResourceGroup/providers/Microsoft.Compute/images/myImage"
99+
```
100+
101+
A managed image resource can be created from a Virtual Machine. Please refer to Azure documentation on [creating a managed image][creating-managed-image] for more detail.
102+
103+
Managed images support only 20 simultaneous deployments, so for most use cases Shared Image Gallery is recommended.
104+
105+
### Using Azure Marketplace
106+
107+
To use an image from [Azure Marketplace][azure-marketplace], populate the `publisher`, `offer`, `sku`, and `version` fields:
108+
109+
```yaml
110+
apiVersion: infrastructure.cluster.x-k8s.io/v1alpha3
111+
kind: AzureMachineTemplate
112+
metadata:
113+
name: capz-marketplace-example
114+
spec:
115+
template:
116+
spec:
117+
image:
118+
publisher: "example-publisher"
119+
offer: "example-offer"
120+
sku: "k8s-1dot18dot6-ubuntu-1804"
121+
version: "2020-07-25"
122+
```
123+
124+
[azure-marketplace]: https://docs.microsoft.com/azure/marketplace/marketplace-publishers-guide
125+
[azure-capi-images]: https://image-builder.sigs.k8s.io/capi/providers/azure.html
126+
[capi-images]: https://image-builder.sigs.k8s.io/capi/capi.html
127+
[creating-managed-image]: https://docs.microsoft.com/azure/virtual-machines/linux/capture-image
128+
[creating-vm-offer]: https://docs.azure.cn/en-us/articles/azure-marketplace/imagepublishguide#5-azure-
129+
[image-builder]: https://github.com/kubernetes-sigs/image-builder
130+
[image-builder-azure]: https://github.com/kubernetes-sigs/image-builder/tree/master/images/capi/packer/azure
131+
[kubeadm-preflight-checks]: https://github.com/kubernetes/kubeadm/blob/master/docs/design/design_v1.10.md#preflight-checks
132+
[replication-recommendations]: https://docs.microsoft.com/azure/virtual-machines/linux/shared-image-galleries#scaling
133+
[shared-image-gallery]: https://docs.microsoft.com/azure/virtual-machines/linux/shared-image-galleries
134+
[upgrading-workload-clusters]: https://cluster-api.sigs.k8s.io/tasks/kubeadm-control-plane.html#upgrading-workload-clusters

0 commit comments

Comments
 (0)