Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: user tutorial for GCP NFS #332

Merged
merged 6 commits into from
Jul 16, 2024
Merged

docs: user tutorial for GCP NFS #332

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
30ea87f
docs: user tutorial for GCP NFS
abalaie Jul 10, 2024
6293376
Apply suggestions from code review
tmilos77 Jul 15, 2024
10f4e6f
docs: user tutorial for GCP NFS
abalaie Jul 10, 2024
c180c9f
Apply suggestions from code review
tmilos77 Jul 15, 2024
5a61b02
Rebase and add GCP NFS tutorial link to sidebar
abalaie Jul 15, 2024
2a38667
Merge branch 'ab-gcp-nfs-tutorial' of github.com:abalaie/cloud-resour…
abalaie Jul 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/user/00-10-glossary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,5 +17,6 @@
| IP Address | Internet Protocol address is a unique address that identifies a device on the internet or a local network. | |
| IP Address range | A set of consecutive IP addresses, usually a network routing target expressed in the CIDR notation. | |
| Network routing | The process of selecting a path from source to destination node across one or more networks. | |
| NFS | Network File System is a network file sharing protocol that defines the way files are stored and retrieved from storage devices across networks. | |
| RWX | Persistent Volume ReadWriteMany access mode. | [Kubernetes Persistent Volumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#introduction) |
| VPC Network | Virtual Private Cloud network is a virtual version of a physical network that is implemented inside the cloud provider production network by using special netowrk virtualization software. | |
1 change: 1 addition & 0 deletions docs/user/_sidebar.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,5 +7,6 @@
* [GcpNfsVolume](/cloud-manager/user/resources/04-30-10-gcp-nfs-volume.md)
* [Tutorials](/cloud-manager/user/tutorials/README.md)
* [Use RWX Volumes in AWS](/cloud-manager/user/tutorials/01-10-aws-nfs-volume.md)
* [Use RWX Volumes in GCP](/cloud-manager/user/tutorials/01-20-gcp-nfs-volume.md)
* [Glossary](/cloud-manager/user/00-10-glossary.md)
<!-- markdown-link-check-enable -->
32 changes: 17 additions & 15 deletions docs/user/resources/04-30-10-gcp-nfs-volume.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,20 +31,22 @@ This table lists the parameters of the given resource together with their descri

**Spec:**

| Parameter | Type | Description |
|-----------------------------|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **ipRange** | object | Optional IpRange reference. If omitted, default IpRange will be used, if default IpRange does not exist, it will be created |
| **ipRange.name** | string | Name of the existing IpRange to use. |
| **capacityGb** | int | Capacity of the provisioned volume. |
| **tier** | string | The GCP Filestore tier configuration option. One of `generalPurpose`, `maxIO`. Defaults to `generalPurpose`. |
| **volume** | object | The PersistentVolume options. Optional. |
| **volume.name** | string | The PersistentVolume name. Optional. Defaults to the name of the AwsNfsVolume resource. |
| **volume.labels** | map\[string\]string | The PersistentVolume labels. Optional. Defaults to nil. |
| **volume.annotations** | map\[string\]string | The PersistentVolume annotations. Optional. Defaults to nil. |
| **volumeClaim** | object | The PersistentVolumeClaim options. Optional. |
| **volumeClaim.name** | string | The PersistentVolumeClaim name. Optional. Defaults to the name of the AwsNfsVolume resource. |
| **volumeClaim.labels** | map\[string\]string | The PersistentVolumeClaim labels. Optional. Defaults to nil. |
| **volumeClaim.annotations** | map\[string\]string | The PersistentVolumeClaim annotations. Optional. Defaults to nil. |
| Parameter | Type | Description |
|-----------------------------|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
| **ipRange** | object | Optional IpRange reference. If omitted, default IpRange will be used, if default IpRange does not exist, it will be created. |
| **ipRange.name** | string | Name of the existing IpRange to use. |
| **capacityGb** | int | Capacity of the provisioned volume in GiB. |
| **location** | string | The zone (for zonal tiers) or the region (for regional tiers) where GCP Filestore will reside. |
| **tier** | string | The GCP Filestore tier configuration option. Defaults to `BASIC_HDD`. |
| **fileShareName** | string | The name of the file share option. Defaults to `vol1`. A file share is the directory on a Filestore instance where all shared files are stored. |
| **volume** | object | The PersistentVolume options. Optional. |
| **volume.name** | string | The PersistentVolume name. Optional. Defaults to the name of the AwsNfsVolume resource. |
| **volume.labels** | map\[string\]string | The PersistentVolume labels. Optional. Defaults to nil. |
| **volume.annotations** | map\[string\]string | The PersistentVolume annotations. Optional. Defaults to nil. |
| **volumeClaim** | object | The PersistentVolumeClaim options. Optional. |
| **volumeClaim.name** | string | The PersistentVolumeClaim name. Optional. Defaults to the name of the AwsNfsVolume resource. |
| **volumeClaim.labels** | map\[string\]string | The PersistentVolumeClaim labels. Optional. Defaults to nil. |
| **volumeClaim.annotations** | map\[string\]string | The PersistentVolumeClaim annotations. Optional. Defaults to nil. |

**Status:**

Expand All @@ -70,7 +72,7 @@ metadata:
name: my-vol
spec:
capacityGb: 1024
tier: ENTERPRISE
location: us-west1
---
apiVersion: v1
kind: Pod
Expand Down
189 changes: 189 additions & 0 deletions docs/user/tutorials/01-20-gcp-nfs-volume.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,189 @@
# Use RWX Volumes in GCP

This tutorial explains how to create ReadWriteMany (RWX) volumes in Google Cloud Platform (GCP). You can use the created RWX volume from multiple workloads.

## Steps <!-- {docsify-ignore} -->

1. Create a namespace and export its value as an environment variable. Run:

```shell
export NAMESPACE={NAMESPACE_NAME}
kubectl create ns $NAMESPACE
```

2. Create an GcpNfsVolume resource.

```shell
cat <<EOF | kubectl -n $NAMESPACE apply -f -
apiVersion: cloud-resources.kyma-project.io/v1beta1
kind: GcpNfsVolume
metadata:
name: my-vol
spec:
location: us-west1-a
capacityGb: 1024
EOF
```

3. Wait for the GcpNfsVolume to be in the `Ready` state.

```shell
kubectl -n $NAMESPACE wait --for=condition=Ready gcpnfsvolume/my-vol --timeout=300s
```

Once the newly created GcpNfsVolume is provisioned, you should see the following message:

```
gcpnfsvolume.cloud-resources.kyma-project.io/my-vol condition met
```

4. Observe the generated PersistentVolume:

```shell
export PV_NAME=`kubectl get gcpnfsvolume my-vol -n $NAMESPACE -o jsonpath='{.status.id}'`
kubectl get persistentvolume $PV_NAME
```

You should see the following details:

```
NAME CAPACITY ACCESS MODES RECLAIM POLICY STATUS CLAIM STORAGECLASS
{PV_NAME} 1Ti RWX Retain Bound {NAMESPACE_NAME}/my-vol
```

Note the `RWX` access mode which allows the volume to be readable and writable from multiple workloads, and the
the `Bound` status which means the PersistentVolumeClaim claiming this PV is created.

5. Observe the generated PersistentVolumeClaim:

```shell
kubectl -n $NAMESPACE get persistentvolumeclaim my-vol
```

You should see the following message:

```
NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS
my-vol Bound {PV_NAME} 1Ti RWX
```

Similarly to PV, note the `RWX` access mode and `Bound` status.

6. Create two workloads that both write to the volume. Run:

```shell
cat <<EOF | kubectl -n $NAMESPACE apply -f -
apiVersion: v1
kind: ConfigMap
metadata:
name: my-script
data:
my-script.sh: |
#!/bin/bash
for xx in {1..20}; do
echo "Hello from \$NAME: \$xx" | tee -a /mnt/data/test.log
sleep 1
done
echo "File content:"
cat /mnt/data/test.log
sleep 864000
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: gcpnfsvolume-demo
spec:
selector:
matchLabels:
app: gcpnfsvolume-demo
replicas: 2
template:
metadata:
labels:
app: gcpnfsvolume-demo
spec:
containers:
- name: my-container
image: ubuntu
command:
- "/bin/bash"
args:
- "/script/my-script.sh"
env:
- name: NAME
valueFrom:
fieldRef:
fieldPath: metadata.name
volumeMounts:
- name: my-script-volume
mountPath: /script
- name: data
mountPath: /mnt/data
volumes:
- name: my-script-volume
configMap:
name: my-script
defaultMode: 0744
- name: data
persistentVolumeClaim:
claimName: my-vol
EOF
```

This workload should print a sequence of 20 lines to stdout and a file on the NFS volume.
Then it should print the content of the file.

7. Print the logs of one of the workloads, run:

```shell
kubectl logs -n $NAMESPACE `kubectl get pod -n $NAMESPACE -l app=gcpnfsvolume-demo -o=jsonpath='{.items[0].metadata.name}'`
```

The command should print a result similar to the following one:
```
...
Hello from gcpnfsvolume-demo-557dc8cbcb-kwwjt: 19
Hello from gcpnfsvolume-demo-557dc8cbcb-kwwjt: 20
File content:
Hello from gcpnfsvolume-demo-557dc8cbcb-vg5zt: 1
Hello from gcpnfsvolume-demo-557dc8cbcb-kwwjt: 1
Hello from gcpnfsvolume-demo-557dc8cbcb-vg5zt: 2
Hello from gcpnfsvolume-demo-557dc8cbcb-kwwjt: 2
Hello from gcpnfsvolume-demo-557dc8cbcb-vg5zt: 3
Hello from gcpnfsvolume-demo-557dc8cbcb-kwwjt: 3
...
```

>[!NOTE] The `File content:` contains prints from both workloads. This demonstrates the ReadWriteMany capability of the volume.

8. Clean up:

* Remove the created workloads:
```shell
kubectl delete -n $NAMESPACE deployment gcpnfsvolume-demo
```

* Remove the created configmap:
```shell
kubectl delete -n $NAMESPACE configmap my-script
```

* Remove the created gcpnfsvolume:
```shell
kubectl delete -n $NAMESPACE gcpnfsvolume my-vol
```

* Remove the created default iprange:

> [!NOTE]
> If you have other cloud resources using the default IpRange,
> skip this step, and do not delete the default IpRange.

```shell
kubectl delete iprange default
```

* Remove the created namespace:
```shell
kubectl delete namespace $NAMESPACE
```
1 change: 1 addition & 0 deletions docs/user/tutorials/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,4 @@
Browse the Cloud Manager tutorials to learn how to create and use cloud resources.

* [Use RWX Volumes in AWS](./01-10-aws-nfs-volume.md)
* [Use RWX Volumes in GCP](./01-20-gcp-nfs-volume.md)
Loading