> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macstadium.com/llms.txt
> Use this file to discover all available pages before exploring further.

# K8s Native: Persistent Volumes

> Use Kubernetes persistent volumes in Orka custom pod namespaces. Request a PV from MacStadium, set up kubectl access, create PVCs, and deploy pods.

How to tap into Kubernetes persistent volumes for your Orka environment.

For security reasons, Orka does not let you configure [persistent volumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) yourself. The MacStadium team needs to do that for you. However, when a persistent volume is configured for your environment, you can create persistent volume claims and deploy pods that consume the respective persistent volume.

**Quick command summary**

```bash theme={null}
brew install kubectl
orka3 login OR orka3 user set-token <TOKEN>
orka3 ns create <NAMESPACE> --enable-custom-pods
orka3 node namespace <NODE> <NAMESPACE>
orka3 rb add-subject --namespace <NAMESPACE> --user <USER>
kubectl apply -f *.yaml --namespace=<NAMESPACE>
kubectl get [pods / pvc]
kubectl describe
kubectl delete
```

## Limitations

Persistent volumes are not applicable to standard Orka VMs. They can be consumed only by pods deployed with `kubectl`, and are called by functions such as `attach-disk`.

If you want to persist the storage of a standard Orka VM, use the VM commit, save, or push operations.

## Step 1: Request a Persistent Volume

Contact the MacStadium team and request a persistent volume (PV) for your Orka environment. Work closely with the team to help them create a PV that matches your requirements. Note that at this step, you need to decide on the name of the namespace where the PV will be created.

## Step 2: Get Kubernetes-Ready

You need to install `kubectl` and configure a namespace with permissions to run custom pods.

1. If not already installed, install `kubectl` locally. For example:

```bash theme={null}
brew install kubectl
```

2. Authenticate with the Orka cluster.

```bash theme={null}
orka3 login

OR

orka user set-token <TOKEN>
```

3. Set up the namespace for the PV. The name must match the name confirmed with the MacStadium team when requesting the PV. The namespace must have custom pods enabled. Next, you need to move computational resources to the namespace and you need to grant namespace access to the users or service accounts which will be working with the namespace.

```bash theme={null}
orka3 namespace create <NAME> --enable-custom-pods

orka3 node namespace <NODE> <NAMESPACE>

orka3 rb add-subject --namespace <NAMESPACE> --user <USER>
```

## Step 3: Create the Persistent Volume Claim

A persistent volume claim (PVC) lets you tap into your persistent volume and consume it. You need to create a basic yaml manifest for the PVC and apply it to the environment.

1. Create the PVC manifest. For more information, see [Kubernetes Documentation: PersistentVolumeClaims](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims). For example:

**pvc.yaml**

```yaml theme={null}
# pvc.yaml
kind: PersistentVolumeClaim
apiVersion: v1
metadata:
  name: mypvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 20Gi
```

The values for `metadata.name` and `metadata.namespace` must match the values for `claimRef.name` and `claimRef.namespace` declared in the manifest of the persistent volume. Double-check with the MacStadium team for these values.

2. Apply the PVC. Replace `pvc.yaml` with the complete file path to your own PVC manifest. Replace `<NAMESPACE>` with the namespace you created earlier.

```bash theme={null}
kubectl apply -f pvc.yaml --namespace=<NAMESPACE>
```

3. Verify that the persistent volume claim is bound to the persistent volume.

```bash theme={null}
kubectl get pvc
```

If the persistent volume claim works as expected, you will see a similar output:

<img src="https://mintcdn.com/macstadiuminc/9E4UGn8KwDOik0d3/images/attachments/28335737308059.png?fit=max&auto=format&n=9E4UGn8KwDOik0d3&q=85&s=6b25bbae67222fc7bcaccac0d35ba021" alt="kubectl get pvc output showing PVC bound to persistent volume" width="1586" height="194" data-path="images/attachments/28335737308059.png" />

<Note>
  **Status Pending?** If the status is `Pending` instead of `Bound`, double-check your PVC manifest, fix any naming issues, remove the old PVC with `kubectl delete pvc <NAME>`, and re-apply the fixed manifest. If the problem persists, contact the MacStadium team.
</Note>

## Step 4: Deploy a Pod That Uses the Persistent Volume

Now that you have created a PVC and bound it to the PV, you can deploy a pod that uses the PV. Create a pod manifest and apply it.

1. Create the pod manifest. The pod needs to reference both the PV and the PVC. For example:

**mypod.yaml**

```yaml theme={null}
apiVersion: v1
kind: Pod
metadata:
  name: mypod
spec:
  volumes:
    - name: my-pv
      persistentVolumeClaim:
        claimName: mypvc
  containers:
    - name: mypod
      image: ubuntu
      command: ["/bin/bash", "-ec", "while :; do echo '.'; sleep 5 ; done"]
      volumeMounts:
        - mountPath: "/usr/share/mypod"
          name: my-pv
  restartPolicy: Never
  tolerations:
    - key: orka.macstadium.com/namespace-reserved
      value: <NAMESPACE>
```

This example deploys a Linux VM. Pay attention to the command line and the tolerations section. Without the command line, the state of your Linux VM will become Stopped. Without the tolerations section, you won't be able to create the pod.

2. Apply the pod. Replace `mypod.yaml` with the complete file path to your pod manifest.

```bash theme={null}
kubectl apply -f mypod.yaml --namespace=<NAMESPACE>
```

3. Verify that the pod is deployed and running.

```bash theme={null}
kubectl get pods
```

If the pod works as expected, you will see a similar output:

<img src="https://mintcdn.com/macstadiuminc/9E4UGn8KwDOik0d3/images/attachments/28335737311003.png?fit=max&auto=format&n=9E4UGn8KwDOik0d3&q=85&s=120b612b3df0df1226928a61cbce2753" alt="kubectl get pods output showing pod running" width="1594" height="192" data-path="images/attachments/28335737311003.png" />

4. Verify that the pod uses the claim and the persistent volume. Look for the data listed for Volumes.

```bash theme={null}
kubectl describe pod <NAME>
```

## (Optional) Step 5: Deploy a Service to Handle the Networking Between Your Pods and Your Orka VMs

If you want to have connectivity between your Orka VMs and any pods deployed with `kubectl`, you need to deploy a networking service. For more information, see [Kubernetes Documentation: Service](https://kubernetes.io/docs/concepts/services-networking/service/).

Make sure to use the networking information provided in your [Orka IP Plan](/macstadium/macstadium-overview/ip-plan) when assigning IPs.

## What's Next: Delete the PVC and Release the PV

When you no longer need to use a PVC and the respective PV, you can delete the PVC to release the PV.

1. Delete the PVC.

```bash theme={null}
kubectl delete pvc <NAME>
```

2. Contact the MacStadium team.

   * If you want to reclaim the storage, an administrator might need to clean it up and verify that it's available for use again. This would depend on the provisioning type and the reclaim policy for the PV.
   * If you no longer need the storage, an administrator can remove the PV.