github.com/qsunny/k8s@v0.0.0-20220101153623-e6dca256d5bf/examples-master/volumes/storageos/README.md (about) 1 # StorageOS Volume 2 3 - [StorageOS](#storageos) 4 - [Prerequisites](#prerequisites) 5 - [Examples](#examples) 6 - [Pre-provisioned Volumes](#pre-provisioned) 7 - [Pod](#pod) 8 - [Persistent Volumes](#persistent-volumes) 9 - [Dynamic Provisioning](#dynamic-provisioning) 10 - [Storage Class](#storage-class) 11 - [API Configuration](#api-configuration) 12 13 ## StorageOS 14 15 [StorageOS](https://www.storageos.com) can be used as a storage provider for your Kubernetes cluster. StorageOS runs as a container within your Kubernetes environment, making local storage accessible from any node within the Kubernetes cluster. Data can be replicated to protect against node failure. 16 17 At its core, StorageOS provides block storage. You may choose the filesystem type to install to make devices usable from within containers. 18 19 ## Prerequisites 20 21 The StorageOS container must be running on each Kubernetes node that wants to contribute storage or that wants to consume storage. For more information on how you can run StorageOS, consult the [StorageOS documentation](https://docs.storageos.com). 22 23 ## API Configuration 24 25 The StorageOS provider has been pre-configured to use the StorageOS API defaults, and no additional configuration is required for testing. If you have changed the API port, or have removed the default account or changed its password (recommended), you must specify the new settings. This is done using Kubernetes [Secrets](../../../docs/user-guide/secrets/). 26 27 API configuration is set by using Kubernetes secrets. The configuration secret supports the following parameters: 28 29 * `apiAddress`: The address of the StorageOS API. This is optional and defaults to `tcp://localhost:5705`, which should be correct if the StorageOS container is running using the default settings. 30 * `apiUsername`: The username to authenticate to the StorageOS API with. 31 * `apiPassword`: The password to authenticate to the StorageOS API with. 32 * `apiVersion`: Optional, string value defaulting to `1`. Only set this if requested in StorageOS documentation. 33 34 Mutiple credentials can be used by creating different secrets. 35 36 For Persistent Volumes, secrets must be created in the Pod namespace. Specify the secret name using the `secretName` parameter when attaching existing volumes in Pods or creating new persistent volumes. 37 38 For dynamically provisioned volumes using storage classes, the secret can be created in any namespace. Note that you would want this to be an admin-controlled namespace with restricted access to users. Specify the secret namespace as parameter `adminSecretNamespace` and name as parameter `adminSecretName` in storage classes. 39 40 Example spec: 41 42 ```yaml 43 apiVersion: v1 44 kind: Secret 45 metadata: 46 name: storageos-secret 47 type: "kubernetes.io/storageos" 48 data: 49 apiAddress: dGNwOi8vMTI3LjAuMC4xOjU3MDU= 50 apiUsername: c3RvcmFnZW9z 51 apiPassword: c3RvcmFnZW9z 52 ``` 53 54 Values for `apiAddress`, `apiUsername` and `apiPassword` can be generated with: 55 56 ```bash 57 $ echo -n "tcp://127.0.0.1:5705" | base64 58 dGNwOi8vMTI3LjAuMC4xOjU3MDU= 59 ``` 60 61 Create the secret: 62 63 ```bash 64 $ kubectl create -f storageos-secret.yaml 65 secret "storageos-secret" created 66 ``` 67 68 Verify the secret: 69 70 ```bash 71 $ kubectl describe secret storageos-secret 72 Name: storageos-secret 73 Namespace: default 74 Labels: <none> 75 Annotations: <none> 76 77 Type: kubernetes.io/storageos 78 79 Data 80 ==== 81 apiAddress: 20 bytes 82 apiPassword: 8 bytes 83 apiUsername: 8 bytes 84 85 ``` 86 ## Examples 87 88 These examples assume you have a running Kubernetes cluster with the StorageOS container running on each node, and that an API configuration secret called `storageos-secret` has been created in the `default` namespace. 89 90 ### Pre-provisioned Volumes 91 92 #### Pod 93 94 Pods can be created that access volumes directly. 95 96 1. Create a volume using the StorageOS UI, CLI or API. Consult the [StorageOS documentation](https://docs.storageos.com) for details. 97 1. Create a pod that refers to the new volume. In this case the volume is named `redis-vol01`. 98 99 Example spec: 100 101 ```yaml 102 apiVersion: v1 103 kind: Pod 104 metadata: 105 labels: 106 name: redis 107 role: master 108 name: test-storageos-redis 109 spec: 110 containers: 111 - name: master 112 image: kubernetes/redis:v1 113 env: 114 - name: MASTER 115 value: "true" 116 ports: 117 - containerPort: 6379 118 resources: 119 limits: 120 cpu: "0.1" 121 volumeMounts: 122 - mountPath: /redis-master-data 123 name: redis-data 124 volumes: 125 - name: redis-data 126 storageos: 127 # This volume must already exist within StorageOS 128 volumeName: redis-vol01 129 # volumeNamespace is optional, and specifies the volume scope within 130 # StorageOS. If no namespace is provided, it will use the namespace 131 # of the pod. Set to `default` or leave blank if you are not using 132 # namespaces. 133 #volumeNamespace: test-storageos 134 # The filesystem type to format the volume with, if required. 135 fsType: ext4 136 # The secret name for API credentials 137 secretName: storageos-secret 138 ``` 139 140 [Download example](storageos-pod.yaml?raw=true) 141 142 Create the pod: 143 144 ```bash 145 $ kubectl create -f examples/volumes/storageos/storageos-pod.yaml 146 ``` 147 148 Verify that the pod is running: 149 150 ```bash 151 $ kubectl get pods test-storageos-redis 152 NAME READY STATUS RESTARTS AGE 153 test-storageos-redis 1/1 Running 0 30m 154 ``` 155 156 ### Persistent Volumes 157 158 1. Create a volume using the StorageOS UI, CLI or API. Consult the [StorageOS documentation](https://docs.storageos.com) for details. 159 1. Create the persistent volume `redis-vol01`. 160 161 Example spec: 162 163 ```yaml 164 apiVersion: v1 165 kind: PersistentVolume 166 metadata: 167 name: pv0001 168 spec: 169 capacity: 170 storage: 5Gi 171 accessModes: 172 - ReadWriteOnce 173 persistentVolumeReclaimPolicy: Delete 174 storageos: 175 # This volume must already exist within StorageOS 176 volumeName: pv0001 177 # volumeNamespace is optional, and specifies the volume scope within 178 # StorageOS. Set to `default` or leave blank if you are not using 179 # namespaces. 180 #volumeNamespace: default 181 # The filesystem type to create on the volume, if required. 182 fsType: ext4 183 # The secret name for API credentials 184 secretName: storageos-secret 185 ``` 186 187 [Download example](storageos-pv.yaml?raw=true) 188 189 Create the persistent volume: 190 191 ```bash 192 $ kubectl create -f examples/volumes/storageos/storageos-pv.yaml 193 ``` 194 195 Verify that the pv has been created: 196 197 ```bash 198 $ kubectl describe pv pv0001 199 Name: pv0001 200 Labels: <none> 201 Annotations: <none> 202 StorageClass: fast 203 Status: Available 204 Claim: 205 Reclaim Policy: Delete 206 Access Modes: RWO 207 Capacity: 5Gi 208 Message: 209 Source: 210 Type: StorageOS (a StorageOS Persistent Disk resource) 211 VolumeName: pv0001 212 VolumeNamespace: 213 FSType: ext4 214 ReadOnly: false 215 Events: <none> 216 ``` 217 218 1. Create persistent volume claim 219 220 Example spec: 221 222 ```yaml 223 apiVersion: v1 224 kind: PersistentVolumeClaim 225 metadata: 226 name: pvc0001 227 spec: 228 accessModes: 229 - ReadWriteOnce 230 resources: 231 requests: 232 storage: 5Gi 233 storageClassName: fast 234 ``` 235 236 [Download example](storageos-pvc.yaml?raw=true) 237 238 Create the persistent volume claim: 239 240 ```bash 241 $ kubectl create -f examples/volumes/storageos/storageos-pvc.yaml 242 ``` 243 244 Verify that the pvc has been created: 245 246 ```bash 247 $ kubectl describe pvc pvc0001 248 Name: pvc0001 249 Namespace: default 250 StorageClass: fast 251 Status: Bound 252 Volume: pv0001 253 Labels: <none> 254 Capacity: 5Gi 255 Access Modes: RWO 256 No events. 257 ``` 258 259 1. Create pod which uses the persistent volume claim 260 261 Example spec: 262 263 ```yaml 264 apiVersion: v1 265 kind: Pod 266 metadata: 267 labels: 268 name: redis 269 role: master 270 name: test-storageos-redis-pvc 271 spec: 272 containers: 273 - name: master 274 image: kubernetes/redis:v1 275 env: 276 - name: MASTER 277 value: "true" 278 ports: 279 - containerPort: 6379 280 resources: 281 limits: 282 cpu: "0.1" 283 volumeMounts: 284 - mountPath: /redis-master-data 285 name: redis-data 286 volumes: 287 - name: redis-data 288 persistentVolumeClaim: 289 claimName: pvc0001 290 ``` 291 292 [Download example](storageos-pvcpod.yaml?raw=true) 293 294 Create the pod: 295 296 ```bash 297 $ kubectl create -f examples/volumes/storageos/storageos-pvcpod.yaml 298 ``` 299 300 Verify that the pod has been created: 301 302 ```bash 303 $ kubectl get pods 304 NAME READY STATUS RESTARTS AGE 305 test-storageos-redis-pvc 1/1 Running 0 40s 306 ``` 307 308 ### Dynamic Provisioning 309 310 Dynamic provisioning can be used to auto-create volumes when needed. They require a Storage Class, a Persistent Volume Claim, and a Pod. 311 312 #### Storage Class 313 314 Kubernetes administrators can use storage classes to define different types of storage made available within the cluster. Each storage class definition specifies a provisioner type and any parameters needed to access it, as well as any other configuration. 315 316 StorageOS supports the following storage class parameters: 317 318 * `pool`: The name of the StorageOS distributed capacity pool to provision the volume from. Uses the `default` pool which is normally present if not specified. 319 * `description`: The description to assign to volumes that were created dynamically. All volume descriptions will be the same for the storage class, but different storage classes can be used to allow descriptions for different use cases. Defaults to `Kubernetes volume`. 320 * `fsType`: The default filesystem type to request. Note that user-defined rules within StorageOS may override this value. Defaults to `ext4`. 321 * `adminSecretNamespace`: The namespace where the API configuration secret is located. Required if adminSecretName set. 322 * `adminSecretName`: The name of the secret to use for obtaining the StorageOS API credentials. If not specified, default values will be attempted. 323 324 1. Create storage class 325 326 Example spec: 327 328 ```yaml 329 kind: StorageClass 330 apiVersion: storage.k8s.io/v1 331 metadata: 332 name: sc-fast 333 provisioner: kubernetes.io/storageos 334 parameters: 335 pool: default 336 description: Kubernetes volume 337 fsType: ext4 338 adminSecretNamespace: default 339 adminSecretName: storageos-secret 340 ``` 341 342 [Download example](storageos-sc.yaml?raw=true) 343 344 Create the storage class: 345 346 ```bash 347 $ kubectl create -f examples/volumes/storageos/storageos-sc.yaml 348 ``` 349 350 Verify the storage class has been created: 351 352 ```bash 353 $ kubectl describe storageclass fast 354 Name: fast 355 IsDefaultClass: No 356 Annotations: <none> 357 Provisioner: kubernetes.io/storageos 358 Parameters: description=Kubernetes volume,fsType=ext4,pool=default,secretName=storageos-secret 359 No events. 360 ``` 361 362 1. Create persistent volume claim 363 364 Example spec: 365 366 ```yaml 367 apiVersion: v1 368 kind: PersistentVolumeClaim 369 metadata: 370 name: fast0001 371 spec: 372 storageClassName: fast 373 accessModes: 374 - ReadWriteOnce 375 resources: 376 requests: 377 storage: 5Gi 378 ``` 379 380 Create the persistent volume claim (pvc): 381 382 ```bash 383 $ kubectl create -f examples/volumes/storageos/storageos-sc-pvc.yaml 384 ``` 385 386 Verify the pvc has been created: 387 388 ```bash 389 $ kubectl describe pvc fast0001 390 Name: fast0001 391 Namespace: default 392 StorageClass: fast 393 Status: Bound 394 Volume: pvc-480952e7-f8e0-11e6-af8c-08002736b526 395 Labels: <none> 396 Capacity: 5Gi 397 Access Modes: RWO 398 Events: 399 <snip> 400 ``` 401 402 A new persistent volume will also be created and bound to the pvc: 403 404 ```bash 405 $ kubectl describe pv pvc-480952e7-f8e0-11e6-af8c-08002736b526 406 Name: pvc-480952e7-f8e0-11e6-af8c-08002736b526 407 Labels: storageos.driver=filesystem 408 StorageClass: fast 409 Status: Bound 410 Claim: default/fast0001 411 Reclaim Policy: Delete 412 Access Modes: RWO 413 Capacity: 5Gi 414 Message: 415 Source: 416 Type: StorageOS (a StorageOS Persistent Disk resource) 417 VolumeName: pvc-480952e7-f8e0-11e6-af8c-08002736b526 418 Namespace: default 419 FSType: ext4 420 ReadOnly: false 421 No events. 422 ``` 423 424 1. Create pod which uses the persistent volume claim 425 426 Example spec: 427 428 ```yaml 429 apiVersion: v1 430 kind: Pod 431 metadata: 432 labels: 433 name: redis 434 role: master 435 name: test-storageos-redis-sc-pvc 436 spec: 437 containers: 438 - name: master 439 image: kubernetes/redis:v1 440 env: 441 - name: MASTER 442 value: "true" 443 ports: 444 - containerPort: 6379 445 resources: 446 limits: 447 cpu: "0.1" 448 volumeMounts: 449 - mountPath: /redis-master-data 450 name: redis-data 451 volumes: 452 - name: redis-data 453 persistentVolumeClaim: 454 claimName: fast0001 455 ``` 456 457 [Download example](storageos-sc-pvcpod.yaml?raw=true) 458 459 Create the pod: 460 461 ```bash 462 $ kubectl create -f examples/volumes/storageos/storageos-sc-pvcpod.yaml 463 ``` 464 465 Verify that the pod has been created: 466 467 ```bash 468 $ kubectl get pods 469 NAME READY STATUS RESTARTS AGE 470 test-storageos-redis-sc-pvc 1/1 Running 0 44s 471 ``` 472 473 <!-- BEGIN MUNGE: GENERATED_ANALYTICS --> 474 []() 475 <!-- END MUNGE: GENERATED_ANALYTICS -->