|
| 1 | +// Module included in the following assemblies: |
| 2 | +// |
| 3 | +// * machine_management/creating_machinesets/creating-machineset-azure.adoc |
| 4 | +// * storage/persistent_storage/persistent-storage-azure.adoc |
| 5 | +// * storage/persistent_storage/persistent-storage-csi-azure.adoc |
| 6 | + |
| 7 | +ifeval::["{context}" == "creating-machineset-azure"] |
| 8 | +:mapi: |
| 9 | +endif::[] |
| 10 | +ifeval::["{context}" == "persistent-storage-azure"] |
| 11 | +:pvc: |
| 12 | +endif::[] |
| 13 | +ifeval::["{context}" == "persistent-storage-csi-azure"] |
| 14 | +:pvc: |
| 15 | +endif::[] |
| 16 | + |
| 17 | +:_content-type: PROCEDURE |
| 18 | +[id="machineset-creating-azure-ultra-disk_{context}"] |
| 19 | += Creating machines on ultra disks by using machine sets |
| 20 | + |
| 21 | +You can deploy machines on ultra disks on Azure by editing your machine set YAML file. |
| 22 | + |
| 23 | +.Prerequisites |
| 24 | + |
| 25 | +* Have an existing Microsoft Azure cluster. |
| 26 | +
|
| 27 | +.Procedure |
| 28 | + |
| 29 | +ifdef::mapi[] |
| 30 | +. Create a custom secret in the `openshift-machine-api` namespace using the worker data secret by running the following command: |
| 31 | ++ |
| 32 | +[source,terminal] |
| 33 | +---- |
| 34 | +$ oc -n openshift-machine-api \ |
| 35 | +get secret worker-user-data \ |
| 36 | +--template='{{index .data.userData | base64decode}}' | jq > userData.txt |
| 37 | +---- |
| 38 | ++ |
| 39 | +where `userData.txt` is the name of the new custom secret. |
| 40 | + |
| 41 | +. In a text editor, open the `userData.txt` file and locate the final `}` character in the file. |
| 42 | + |
| 43 | +.. On the immediately preceding line, add a `,`. |
| 44 | + |
| 45 | +.. Create a new line after the `,` and add the following configuration details: |
| 46 | ++ |
| 47 | +[source,json] |
| 48 | +---- |
| 49 | +"storage": { |
| 50 | + "disks": [ <1> |
| 51 | + { |
| 52 | + "device": "/dev/disk/azure/scsi1/lun0", <2> |
| 53 | + "partitions": [ <3> |
| 54 | + { |
| 55 | + "label": "lun0p1", <4> |
| 56 | + "sizeMiB": 1024, <5> |
| 57 | + "startMiB": 0 |
| 58 | + } |
| 59 | + ] |
| 60 | + } |
| 61 | + ], |
| 62 | + "filesystems": [ <6> |
| 63 | + { |
| 64 | + "device": "/dev/disk/by-partlabel/lun0p1", |
| 65 | + "format": "xfs", |
| 66 | + "path": "/var/lib/lun0p1" |
| 67 | + } |
| 68 | + ] |
| 69 | +}, |
| 70 | +"systemd": { |
| 71 | + "units": [ <7> |
| 72 | + { |
| 73 | + "contents": "[Unit]\nBefore=local-fs.target\n[Mount]\nWhere=/var/lib/lun0p1\nWhat=/dev/disk/by-partlabel/lun0p1\nOptions=defaults,pquota\n[Install]\nWantedBy=local-fs.target\n", <8> |
| 74 | + "enabled": true, |
| 75 | + "name": "var-lib-lun0p1.mount" |
| 76 | + } |
| 77 | + ] |
| 78 | +} |
| 79 | +---- |
| 80 | +<1> The configuration details for the disk that you want to attach to a node as an ultra disk. |
| 81 | +<2> Specify the `lun` value that is defined in the `dataDisks` stanza of the machine set you are using. For example, if the machine set contains `lun: 0`, specify `lun0`. You can initialize multiple data disks by specifying multiple `"disks"` entries in this configuration file. If you specify multiple `"disks"` entries, ensure that the `lun` value for each matches the value in the machine set. |
| 82 | +<3> The configuration details for a new partition on the disk. |
| 83 | +<4> Specify a label for the partition. You might find it helpful to use hierarchical names, such as `lun0p1` for the first partition of `lun0`. |
| 84 | +<5> Specify the total size in MiB of the partition. |
| 85 | +<6> Specify the filesystem to use when formatting a partition. Use the partition label to specify the partition. |
| 86 | +<7> Specify a `systemd` unit to mount the partition at boot. Use the partition label to specify the partition. You can create multiple partitions by specifying multiple `"partitions"` entries in this configuration file. If you specify multiple `"partitions"` entries, you must specify a `systemd` unit for each. |
| 87 | +<8> For `Where`, specify the value of `storage.filesystems.path`. For `What`, specify the value of `storage.filesystems.device`. |
| 88 | + |
| 89 | +. Extract the disabling template value to a file called `disableTemplating.txt` by running the following command: |
| 90 | ++ |
| 91 | +[source,terminal] |
| 92 | +---- |
| 93 | +$ oc -n openshift-machine-api get secret worker-user-data \ |
| 94 | +--template='{{index .data.disableTemplating | base64decode}}' | jq > disableTemplating.txt |
| 95 | +---- |
| 96 | + |
| 97 | +. Combine the `userData.txt` file and `disableTemplating.txt` file to create a data secret file by running the following command: |
| 98 | ++ |
| 99 | +[source,terminal] |
| 100 | +---- |
| 101 | +$ oc -n openshift-machine-api create secret generic worker-user-data-x5 \ |
| 102 | +--from-file=userData=userData.txt \ |
| 103 | +--from-file=disableTemplating=disableTemplating.txt |
| 104 | +---- |
| 105 | ++ |
| 106 | +where `worker-user-data-x5` is the name of the secret. |
| 107 | +endif::mapi[] |
| 108 | + |
| 109 | +. Copy an existing Azure `MachineSet` custom resource (CR) and edit it by running the following command: |
| 110 | ++ |
| 111 | +[source,terminal] |
| 112 | +---- |
| 113 | +$ oc edit machineset <machine-set-name> |
| 114 | +---- |
| 115 | ++ |
| 116 | +where `<machine-set-name>` is the machine set that you want to provision machines on ultra disks. |
| 117 | + |
| 118 | +. Add the following lines in the positions indicated: |
| 119 | ++ |
| 120 | +[source,yaml] |
| 121 | +---- |
| 122 | +apiVersion: machine.openshift.io/v1beta1 |
| 123 | +kind: MachineSet |
| 124 | + ... |
| 125 | +spec: |
| 126 | + ... |
| 127 | + template: |
| 128 | + ... |
| 129 | + spec: |
| 130 | + metadata: |
| 131 | + ... |
| 132 | + labels: |
| 133 | + ... |
| 134 | + disk: ultrassd <1> |
| 135 | + ... |
| 136 | + providerSpec: |
| 137 | + value: |
| 138 | + ... |
| 139 | + ultraSSDCapability: Enabled <2> |
| 140 | +ifdef::mapi[] |
| 141 | + dataDisks: <2> |
| 142 | + - nameSuffix: ultrassd |
| 143 | + lun: 0 |
| 144 | + diskSizeGB: 4 |
| 145 | + deletionPolicy: Delete |
| 146 | + cachingType: None |
| 147 | + managedDisk: |
| 148 | + storageAccountType: UltraSSD_LRS |
| 149 | + userDataSecret: |
| 150 | + name: worker-user-data-x5 <3> |
| 151 | +endif::mapi[] |
| 152 | + ... |
| 153 | +---- |
| 154 | ++ |
| 155 | +<1> Specify a label to use to select a node that is created by this machine set. This procedure uses `disk.ultrassd` for this value. |
| 156 | +<2> These lines enable the use of ultra disks. |
| 157 | +ifdef::mapi[] |
| 158 | +For `dataDisks`, include the entire stanza. |
| 159 | +<3> Specify the user data secret created earlier. |
| 160 | +endif::mapi[] |
| 161 | + |
| 162 | +. Create a machine set using the updated configuration by running the following command: |
| 163 | ++ |
| 164 | +[source,terminal] |
| 165 | +---- |
| 166 | +$ oc create -f <machine-set-name>.yaml |
| 167 | +---- |
| 168 | + |
| 169 | +ifdef::pvc[] |
| 170 | +. Create a storage class that contains the following YAML definition: |
| 171 | ++ |
| 172 | +[source,yaml] |
| 173 | +---- |
| 174 | +apiVersion: storage.k8s.io/v1 |
| 175 | +kind: StorageClass |
| 176 | +metadata: |
| 177 | + name: ultra-disk-sc <1> |
| 178 | +parameters: |
| 179 | + cachingMode: None |
| 180 | + diskIopsReadWrite: "2000" <2> |
| 181 | + diskMbpsReadWrite: "320" <3> |
| 182 | + kind: managed |
| 183 | + skuname: UltraSSD_LRS |
| 184 | +provisioner: disk.csi.azure.com <4> |
| 185 | +reclaimPolicy: Delete |
| 186 | +volumeBindingMode: WaitForFirstConsumer <5> |
| 187 | +---- |
| 188 | +<1> Specify the name of the storage class. This procedure uses `ultra-disk-sc` for this value. |
| 189 | +<2> Specify the number of IOPS for the storage class. |
| 190 | +<3> Specify the throughput in MBps for the storage class. |
| 191 | +<4> For Azure Kubernetes Service (AKS) version 1.21 or later, use `disk.csi.azure.com`. For earlier versions of AKS, use `kubernetes.io/azure-disk`. |
| 192 | +<5> Optional: Specify this parameter to wait for the creation of the pod that will use the disk. |
| 193 | + |
| 194 | +. Create a persistent volume claim (PVC) to reference the `ultra-disk-sc` storage class that contains the following YAML definition: |
| 195 | ++ |
| 196 | +[source,yaml] |
| 197 | +---- |
| 198 | +apiVersion: v1 |
| 199 | +kind: PersistentVolumeClaim |
| 200 | +metadata: |
| 201 | + name: ultra-disk <1> |
| 202 | +spec: |
| 203 | + accessModes: |
| 204 | + - ReadWriteOnce |
| 205 | + storageClassName: ultra-disk-sc <2> |
| 206 | + resources: |
| 207 | + requests: |
| 208 | + storage: 4Gi <3> |
| 209 | +---- |
| 210 | +<1> Specify the name of the PVC. This procedure uses `ultra-disk` for this value. |
| 211 | +<2> This PVC references the `ultra-disk-sc` storage class. |
| 212 | +<3> Specify the size for the storage class. The minimum value is `4Gi`. |
| 213 | + |
| 214 | +. Create a pod that contains the following YAML definition: |
| 215 | ++ |
| 216 | +[source,yaml] |
| 217 | +---- |
| 218 | +apiVersion: v1 |
| 219 | +kind: Pod |
| 220 | +metadata: |
| 221 | + name: nginx-ultra |
| 222 | +spec: |
| 223 | + nodeSelector: |
| 224 | + disk: ultrassd <1> |
| 225 | + containers: |
| 226 | + - name: nginx-ultra |
| 227 | + image: alpine:latest |
| 228 | + command: |
| 229 | + - "sleep" |
| 230 | + - "infinity" |
| 231 | + volumeMounts: |
| 232 | + - mountPath: "/mnt/azure" |
| 233 | + name: volume |
| 234 | + volumes: |
| 235 | + - name: volume |
| 236 | + persistentVolumeClaim: |
| 237 | + claimName: ultra-disk <2> |
| 238 | +---- |
| 239 | +<1> Specify the label of the machine set that enables the use of ultra disks. This procedure uses `disk.ultrassd` for this value. |
| 240 | +<2> This pod references the `ultra-disk` PVC. |
| 241 | +endif::pvc[] |
| 242 | + |
| 243 | +.Verification |
| 244 | + |
| 245 | +. Validate that the machines are created by running the following command: |
| 246 | ++ |
| 247 | +[source,terminal] |
| 248 | +---- |
| 249 | +$ oc get machines |
| 250 | +---- |
| 251 | ++ |
| 252 | +The machines should be in the `Running` state. |
| 253 | + |
| 254 | +. For a machine that is running and has a node attached, validate the partition by running the following command: |
| 255 | ++ |
| 256 | +[source,terminal] |
| 257 | +---- |
| 258 | +$ oc debug node/<node-name> -- chroot /host lsblk |
| 259 | +---- |
| 260 | ++ |
| 261 | +In this command, `oc debug node/<node-name>` starts a debugging shell on the node `<node-name>` and passes a command with `--`. The passed command `chroot /host` provides access to the underlying host OS binaries, and `lsblk` shows the block devices that are attached to the host OS machine. |
| 262 | + |
| 263 | +.Next steps |
| 264 | + |
| 265 | +* To use an ultra disk from within a pod, create workload that uses the mount point. Create a YAML file similar to the following example: |
| 266 | ++ |
| 267 | +[source,yaml] |
| 268 | +---- |
| 269 | +apiVersion: v1 |
| 270 | +kind: Pod |
| 271 | +metadata: |
| 272 | + name: ssd-benchmark1 |
| 273 | +spec: |
| 274 | + containers: |
| 275 | + - name: ssd-benchmark1 |
| 276 | + image: nginx |
| 277 | + ports: |
| 278 | + - containerPort: 80 |
| 279 | + name: "http-server" |
| 280 | + volumeMounts: |
| 281 | + - name: lun0p1 |
| 282 | + mountPath: "/tmp" |
| 283 | + volumes: |
| 284 | + - name: lun0p1 |
| 285 | + hostPath: |
| 286 | + path: /var/lib/lun0p1 |
| 287 | + type: DirectoryOrCreate |
| 288 | + nodeSelector: |
| 289 | + disktype: ultrassd |
| 290 | +---- |
| 291 | +
|
| 292 | +ifeval::["{context}" == "creating-machineset-azure"] |
| 293 | +:!mapi: |
| 294 | +endif::[] |
| 295 | +ifeval::["{context}" == "persistent-storage-azure"] |
| 296 | +:!pvc: |
| 297 | +endif::[] |
| 298 | +ifeval::["{context}" == "persistent-storage-csi-azure"] |
| 299 | +:!pvc: |
| 300 | +endif::[] |
0 commit comments