## Overview

If you already have an AWS Elastic Block Store (EBS) volume to import into
GKE on AWS, you can create a PersistentVolume (PV) object and
reserve it for a specific PersistentVolumeClaim (PVC).

This page explains how to create a PV by using an existing EBS volume
populated with data, and how to use the PV in a Pod.

## Before you begin

- From your `anthos-aws` directory, use `anthos-gke` to switch context to your user cluster.

  ```sh
  cd anthos-aws
  env HTTPS_PROXY=http://localhost:8118 \
    anthos-gke aws clusters get-credentials CLUSTER_NAME
  ```
  Replace <var translate="no">CLUSTER_NAME</var> with your user cluster name.

### Creating a PersistentVolume for a pre-existing EBS volume

You can import an existing EBS volume by specifying a new PV.

1. Copy the following YAML into a file named `existing-volume.yaml` and complete
   your configuration by replacing the values:

   - <var translate="no">volume-capacity</var>: size of the volume. For example, `30Gi`. For more information on specifying volume capacity in Kubernetes, see the [Meaning of memory](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-memory).
   - <var translate="no">storage-class-name</var>: the name of the StorageClass that
     provisions the volume.
     For example, you can use the default `standard-rwo`.

     > [!NOTE]
     > **Note:** A StorageClass is required to reference other attributes like `allowVolumeExpansion`, even if a volume is not dynamically provisioned.

   - <var translate="no">ebs-id</var>: EBS [volume id](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-volumes.html#examples).
     For example, `vol-05786ec9ec9526b67`.

   - <var translate="no">fs-type</var>: The
     [file system](https://github.com/kubernetes-sigs/aws-ebs-csi-driver#createvolume-parameters)
     of the volume. For example, `ext4`.

   - <var translate="no">zone</var>: The AWS Availability Zone that hosts the EBS volume.
     For example, `us-east-1c`.

   ```yaml
   apiVersion: v1
   kind: PersistentVolume
   metadata:
     name: volume-name
     annotations:
       pv.kubernetes.io/provisioned-by: ebs.csi.aws.com
   spec:
     capacity:
       storage: volume-capacity
     accessModes:
       - ReadWriteOnce
     persistentVolumeReclaimPolicy: Retain
     storageClassName: storage-class-name
     claimRef:
       name: my-pvc
       namespace: default
     csi:
       driver: ebs.csi.aws.com
       volumeHandle: ebs-volume-id
       fsType: file-system-type
     nodeAffinity:
       required:
         nodeSelectorTerms:
         - matchExpressions:
           - key: topology.ebs.csi.aws.com/zone
             operator: In
             values:
             - zone
   ```
2. Apply the YAML to your cluster

   ```bash
   kubectl apply -f existing-volume.yaml
   ```
3. Confirm the creation of your PV

   ```bash
   kubectl describe pv volume-name
   ```

   The output of this command contains the status of the PV.

## Using the volume with a PersistentVolumeClaim and Pod

After you have imported your volume, you can create a PVC and a Pod that
attaches the PVC.

The YAML below creates a PVC and attaches it to a Pod running the Nginx web
server. Copy it into a file named `nginx.yaml` and complete your configuration
by replacing the values:

- <var translate="no">storage-class</var>: The name of the StorageClass from the PersistentVolume you created previously. For example, `standard-rwo`.
- <var translate="no">volume-name</var>: The name of the volume you created previously.
- <var translate="no">volume-capacity</var>: size of the volume. For example, `30Gi`.

```yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-pvc
spec:
  storageClassName: storage-class-name
  volumeName: volume-name
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: volume-capacity
---

apiVersion: v1
kind: Pod
metadata:
  name: web-server
spec:
  containers:
   - name: web-server
     image: nginx
     volumeMounts:
       - mountPath: /var/lib/www/html
         name: data
  volumes:
   - name: data
     persistentVolumeClaim:
       claimName: my-pvc
```

1. Apply the YAML to your cluster

   ```bash
   kubectl apply -f nginx.yaml
   ```
2. Check the status of your Nginx instance with `kubectl describe`. The output
   should have a `STATUS` of `Running`.

   ```bash
   kubectl describe pod web-server
   ```

## Using encrypted EBS volumes

If your EBS volume is encrypted with the AWS Key Management Service (KMS), you
need to grant the GKE on AWS control plane AWS IAM role access to
your KMS key.

To get the AWS IAM role name, perform the following steps:

1. Change to the directory with your GKE on AWS configuration.
   You created this directory when
   [Installing the management service](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/installing-management.md.txt).

   ```sh
   cd anthos-aws
   ```

   <br />

2. Choose if you created your GKE on AWS environment with the
   `anthos-gke` tool or if you created your AWS IAM profiles manually.

   ### anthos-gke tool

   Use the `terraform output` command and search for the value of
   `iamInstanceProfile`.

   ```bash
   terraform output | grep iamInstanceProfile
   ```

   If you created your GKE on AWS environment with the `anthos-
   gke` tool, the output looks like the following:

         iamInstanceProfile: gke-CLUSTER_ID-controlplane
         iamInstanceProfile: gke-CLUSTER_ID-nodepool

   Where <var translate="no">CLUSTER_ID</var> is your cluster's ID. Copy the value of
   `gke-CLUSTER_ID-controlplane` for the following step.

   ### Manually created

   Examine the output of `terraform output` with the following command:

   ```bash
   terraform output | less
   ```

   Scroll through the output and find the iamInstanceProfile after the
   AWSCluster definition.

   ```yaml
   kind: AWSCluster
   metadata:
     name: cluster-0
   spec:
     ...
     controlPlane:
      ...
       iamInstanceProfile: INSTANCE_PROFILE_NAME
   ```

   Copy the value of `INSTANCE_PROFILE_NAME` for the following
   step.
3. To grant the control plane access to your EBS volumes, add the
   `gke-xxxxxx-controlplane` AWS IAM profile as a
   [Key User](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-default.html#key-policy-default-allow-users)
   to the AWS KMS key used to encrypt your EBS volume.

## What's next

- Use additional [storage drivers](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/storage-drivers.md.txt) with GKE on AWS.