A Cloud Storage plugin lets you use
[Containerized Data Importer (CDI)](https://kubevirt.io/user-guide/operations/containerized_data_importer/)
to import virtual machine (VM) images from Cloud Storage buckets into
VM Runtime on GDC. After configuring credentials to authenticate
with Cloud Storage, you can create virtual disks from these images and
attach them to VMs running in your cluster. CDI is automatically enabled in
clusters that run VM Runtime on GDC.

## Before you begin

To complete this document, you need access to the following resources:

- Access to Google Distributed Cloud version 1.12.0 (`anthosBareMetalVersion: 1.12.0`) or higher cluster. You can use any cluster type capable of running workloads. If needed, [try Google Distributed Cloud on Compute Engine](https://docs.cloud.google.com/kubernetes-engine/distributed-cloud/bare-metal/docs/try/gce-vms.md.txt) or see the [cluster creation overview](https://docs.cloud.google.com/kubernetes-engine/distributed-cloud/bare-metal/docs/installing/creating-clusters/create-clusters-overview.md.txt).
- A service account and service account key you want to use for Cloud Storage access. If needed, [configure a service account that can access a Cloud Storage bucket](https://docs.cloud.google.com/kubernetes-engine/distributed-cloud/bare-metal/docs/installing/configure-sa.md.txt#bucket-sa).

## Credentials overview

To access Cloud Storage, you use a service account that provides
credentials to the storage bucket. The service account requires different
privileges to successfully access a storage bucket:

- **Public storage bucket**: You use a service account for self-identification, but no specific permissions are required.
- **Private storage bucket** : The storage account requires the *viewer* or *admin* privilege to the storage bucket.

There are two ways to provide the service account credentials to CDI:

- Configure the Google Application Default Credentials (ADC) on the nodes in your cluster. For more information, see [Set up ADC for on-premises or another cloud provider](https://docs.cloud.google.com/docs/authentication/set-up-adc-on-premises.md.txt).
- Provide a Secret that contains the key of the service account to access Cloud Storage. The rest of this document shows you how to create a service account key and Secret.

## Create a Secret

You pass the service account key to Kubernetes using a Secret created in the
namespace of the Data Volume. The `data` section of the Secret contains an entry
for `creds-gcp.json`. The value is the base64 encoded data of the service
account key file. The CLI creates this base64 encoded data for you. If you use a
YAML manifest to create the Secret, first create a base64 hash of the contents
of your service account key file.

### CLI

- Create the Secret using `kubectl`:

  ```bash
  kubectl create secret generic SECRET_NAME \
    --from-file=creds-gcp.json=SERVICE_ACCOUNT_KEY_PATH \
    --namespace NAMESPACE_NAME
  ```

  Replace the following values:
  - `SECRET_NAME`: the name for your Secret.
  - `SERVICE_ACCOUNT_KEY_PATH`: the path to your service account key file.
  - `NAMESPACE_NAME`: the namespace for your Secret.
    - Create your Secret in the cluster where CDI runs and in the same namespace as the Data Volume. CDI is automatically enabled in a cluster that runs VM Runtime on GDC.

### Manifest

1. Create a `Secret` manifest, such as *my-secret.yaml*, in the editor of your
   choice:

   ```bash
   nano my-secret.yaml
   ```
2. Copy and paste the following YAML manifest:

   ```yaml
   apiVersion: v1
   data:
     creds-gcp.json: BASE64_SERVICE_ACCOUNT_FILE
   kind: Secret
   metadata:
     name: SECRET_NAME
     namespace: NAMESPACE_NAME
   type: Opaque
   ```

   Replace the following values:
   - `BASE64_SERVICE_ACCOUNT_FILE`: the base64 hash of the contents of your service account key file.
   - `SECRET_NAME`: the name for your Secret.
   - `NAMESPACE_NAME`: the namespace for your Secret.
     - Create your Secret in the cluster where CDI runs and in the same namespace as the Data Volume. CDI is automatically enabled in a cluster that runs VM Runtime on GDC.
3. Save and close the Secret manifest in your editor.

4. Apply the Secret manifest using `kubectl`:

   ```bash
   kubectl apply -f my-secret.yaml
   ```

## Forward an existing Secret

Instead of creating a Secret, you can create a `SecretForwarder` to forward
an existing Secret for use. The `SecretForwarder` supports forwarding Secrets
within the same cluster, or across clusters, such as from the admin cluster to a
user cluster.

To use the target Secret to access Cloud Storage, the source Secret must
have a `creds-gcp.json` key in its `data` section.

### Same cluster

The following example `SecretForwarder` manifest forwards a secret in the same
cluster:

```yaml
apiVersion: baremetal.cluster.gke.io/v1
kind: SecretForwarder
metadata:
  name: cdi-gcs
  namespace: default
spec:
  inClusterTargetSecrets:
    name: gcs-sa
    namespaces:
    - default
  sourceSecret:
    name: gke-connect
    namespace: anthos-creds
```

This example does the following:

- Creates a `SecretForwarder` named `cdi-gcs` in the `default` namespace.
- Forwards the secret named `gke-connect` in the `anthos-creds` namespace to a new secret named `gcs-sa` in the `default` namespace.
- Creates the new secret in the same cluster.

To forward a Secret in the same cluster, complete the following steps:

1. Create a `SecretForwarder` manifest, such as *my-forwarded-secret.yaml*, in
   the editor of your choice:

   ```bash
   nano my-forwarded-secret.yaml
   ```
2. Copy and paste the following YAML manifest:

   ```yaml
   apiVersion: baremetal.cluster.gke.io/v1
   kind: SecretForwarder
   metadata:
     name: SECRET_FORWARDER_NAME
     namespace: NAMESPACE_NAME
   spec:
     inClusterTargetSecrets:
       name: TARGET_SECRET_NAME
       namespaces:
       - TARGET_NAMESPACE_NAME
     sourceSecret:
       name: SOURCE_SECRET_NAME
       namespace: SOURCE_NAMESPACE_NAME
   ```

   Replace the following values:
   - `SECRET_FORWARDER_NAME`: the name for your SecretForwarder.
   - `NAMESPACE_NAME`: the namespace for your SecretForwarder.
   - `TARGET_SECRET_NAME`: the name for your new Secret.
   - `TARGET_NAMESPACE_NAME`: the namespace(s) for your new Secret.
     - Create your Secret in the cluster where CDI runs and in the same namespace as the Data Volume. CDI is automatically enabled in a cluster that runs VM Runtime on GDC.
   - `SOURCE_SECRET_NAME`: the name of your source Secret to forward.
   - `SOURCE_NAMESPACE_NAME`: the namespace of your source Secret to forward.
3. Save and close the `SecretForwarder` manifest in your editor.

4. Apply the `SecretForwarder` manifest using `kubectl`:

   ```bash
   kubectl apply -f my-forwarded-secret.yaml
   ```

### Across clusters

The following example `SecretForwarder` manifest forwards a secret across
clusters:

```yaml
apiVersion: baremetal.cluster.gke.io/v1
kind: SecretForwarder
metadata:
  name: cdi-gcs
  namespace: cluster-user1
spec:
  RemoteClusterTargetSecrets:
    name: gcs-sa
    namespaces:
    - default
  sourceSecret:
    name: gke-connect
    namespace: anthos-creds
```

This example does the following:

- Creates a `SecretForwarder` named `cdi-gcs` in the `cluster-user1` namespace.
- Forwards the secret named `gke-connect` in the `anthos-creds` namespace to a new secret named `gcs-sa` in the `default` namespace.
- Creates the new secret in the cluster named `user1`.

To forward a Secret in the same cluster, complete the following steps:

1. Create a `SecretForwarder` manifest, such as *my-forwarded-secret.yaml*, in
   the editor of your choice:

   ```bash
   nano my-forwarded-secret.yaml
   ```
2. Copy and paste the following YAML manifest:

   ```yaml
   apiVersion: baremetal.cluster.gke.io/v1
   kind: SecretForwarder
   metadata:
     name: SECRET_FORWARDER_NAME
     namespace: NAMESPACE_NAME
   spec:
     RemoteClusterTargetSecrets:
       name: TARGET_SECRET_NAME
       namespaces:
       - TARGET_NAMESPACE_NAME
     sourceSecret:
       name: SOURCE_SECRET_NAME
       namespace: SOURCE_NAMESPACE_NAME
   ```

   Replace the following values:
   - `SECRET_FORWARDER_NAME`: the name for your SecretForwarder in the remote cluster.
   - `NAMESPACE_NAME`: the namespace for your SecretForwarder in the remote cluster.
   - `TARGET_SECRET_NAME`: the name for your new Secret in the remote cluster.
   - `TARGET_NAMESPACE_NAME`: the namespace(s) for your new Secret in the remote cluster.
     - Create your Secret in the cluster where CDI runs and in the same namespace as the Data Volume. CDI is automatically enabled in a cluster that runs VM Runtime on GDC.
   - `SOURCE_SECRET_NAME`: the name of your source Secret to forward.
   - `SOURCE_NAMESPACE_NAME`: the namespace of your source Secret to forward.
3. Save and close the `SecretForwarder` manifest in your editor.

4. Apply the `SecretForwarder` manifest in the admin cluster using `kubectl`
   with the `KUBECONFIG` of the admin cluster:

   ```bash
   kubectl apply -f my-forwarded-secret.yaml
   ```

## Use a Secret to import an image

To use the Secret to import an image from Cloud Storage when you create a
virtual disk and VM, complete the following steps:

1. Create a manifest that defines a `VirtualMachineDisk` and `VirtualMachine`,
   such as *my-vm.yaml,* in the editor of your choice:

   ```bash
   nano my-vm.yaml
   ```
2. Copy and paste the following YAML definition:

   ```yaml
   apiVersion: vm.cluster.gke.io/v1
   kind: VirtualMachineDisk
   metadata:
     name: VM_NAME-boot-dv
   spec:
     size: 20Gi
     source:
       gcs:
         url: IMAGE_URL
         secretRef: SECRET_NAME
   ---
   apiVersion: vm.cluster.gke.io/v1
   kind: VirtualMachine
   metadata:
     name: VM_NAME
   spec:
     interfaces:
       - name: eth0
         networkName: pod-network
         default: true
     disks:
       - boot: true
         virtualMachineDiskName: VM_NAME-boot-dv
   ```

   Replace the following values:
   - `VM_NAME` - the name of your VM.
   - `IMAGE_URL` - the URL to your disk image Cloud Storage, such as `gs://my-images-bucket/disk.qcow2`.
   - `SECRET_NAME` - the name of your secret.
3. Save and close the manifest in your editor.

4. Create the VM and disk using `kubectl`:

   ```bash
   kubectl apply -f my-vm.yaml
   ```

## What's next

- [Create and manage virtual disks](https://docs.cloud.google.com/kubernetes-engine/distributed-cloud/bare-metal/docs/vm-runtime/create-manage-disks.md.txt).