:warning: oci-volume-provisioner is now being maintained at https://github.com/oracle/oci-cloud-controller-manager/tree/master/pkg/volume. This repository will be archived soon.

OCI Volume Provisioner

The OCI Volume Provisioner enables dynamic provisioning of storage resources when running Kubernetes on Oracle Cloud Infrastructure. It uses the OCI Flexvolume Driver to bind storage resources to Kubernetes nodes. The volume provisioner offers support for

• Block Volumes

Prerequisites

• Install the OCI flexvolume driver
• Kubernetes 1.6 +

Install

The oci-volume-provisioner is provided as a Kubernetes deployment.

Submit configuration as a Kubernetes secret

Create a config.yaml file with contents similar to the following. This file will contain authentication information necessary to authenticate with the OCI APIs and provision block storage volumes. The passphrase field can be left out if your key has no passphrase.

auth:
  tenancy: ocid1.tenancy.oc1..aaaaaaaatyn7scrtwt...
  user: ocid1.user.oc1..aaaaaaaao235lbcxvdrrqlr...
  key: |
    -----BEGIN RSA PRIVATE KEY-----
    MIIEowIBAAKCAQEUjVBnOgC4wA3j6CeTc6hIA9B3iwuJKyR8i7w...
    -----END RSA PRIVATE KEY-----
  passphrase: supersecretpassphrase
  fingerprint: aa:bb:cc:dd:ee:ff:gg:hh:ii:jj:kk:ll:mm:nn:oo:pp
  region: us-phoenix-1

Submit this as a Kubernetes Secret.

kubectl create secret generic oci-volume-provisioner \
    -n kube-system \
    --from-file=config.yaml=config.yaml

OCI Permissions

Please ensure that the credentials used in the secret have the following privileges in the OCI API by creating a policy tied to a group or user.

Allow group <name> to manage volumes in compartment <compartment>
Allow group <name> to manage file-systems in compartment <compartment>

Deploy the OCI Volume Provisioner

First select the release to deploy. These are listed here. (https://github.com/oracle/oci-volume-provisioner/releases/latest)

If your cluster is configured to use RBAC you will need to submit the following, replacing the <VERSION> placeholder with the selected version:

kubectl apply -f https://github.com/oracle/oci-volume-provisioner/releases/download/<VERSION>/oci-volume-provisioner-rbac.yaml

Deploy the volume provisioner into your Kubernetes cluster:

kubectl apply -f https://github.com/oracle/oci-volume-provisioner/releases/download/<VERSION>/oci-volume-provisioner.yaml

Deploy the volume provisioner storage classes:

kubectl apply -f https://github.com/oracle/oci-volume-provisioner/releases/download/<VERSION>/storage-class.yaml
kubectl apply -f https://github.com/oracle/oci-volume-provisioner/releases/download/<VERSION>/storage-class-ext3.yaml

Lastly, verify that the oci-volume-provisioner is running in your cluster. By default it runs in the 'kube-system' namespace.

kubectl -n kube-system get po | grep oci-volume-provisioner

Below is an example of deploying version '1.0.0'

kubectl apply -f https://github.com/oracle/oci-volume-provisioner/releases/download/1.0.0/oci-volume-provisioner.yaml
kubectl apply -f https://github.com/oracle/oci-volume-provisioner/releases/download/1.0.0/oci-volume-provisioner.yaml
kubectl apply -f https://github.com/oracle/oci-volume-provisioner/releases/download/1.0.0/storage-class.yaml
kubectl apply -f https://github.com/oracle/oci-volume-provisioner/releases/download/1.0.0/storage-class-ext3.yaml

Tutorial

In this example we'll use the OCI Volume Provisioner to create persistent storage for an NGINX Pod.

Create a PVC

Next we'll create a PersistentVolumeClaim (PVC).

The storageClassName must match the "oci" storage class supported by the provisioner.

The matchLabels should contain the (shortened) Availability Domain (AD) within which you want to provision the volume. For example in Phoenix that might be PHX-AD-1, in Ashburn US-ASHBURN-AD-1, in Frankfurt EU-FRANKFURT-1-AD-1, and in London UK-LONDON-1-AD-1.

kind: PersistentVolumeClaim
apiVersion: v1
metadata:
  name: nginx-volume
spec:
  storageClassName: "oci"
  selector:
    matchLabels:
      failure-domain.beta.kubernetes.io/zone: "PHX-AD-1"
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 50Gi

After submitting the PVC, you should see a block storage volume available in your OCI tenancy.

Create a Kubernetes Pod that references the PVC

Now you have a PVC, you can create a Kubernetes Pod that will consume the storage.

kind: Pod
apiVersion: v1
metadata:
  name: nginx
spec:
  volumes:
    - name: nginx-storage
      persistentVolumeClaim:
        claimName: nginx-volume
  containers:
    - name: nginx
      image: nginx
      ports:
        - containerPort: 80
      volumeMounts:
      - mountPath: "/usr/share/nginx/html"
        name: nginx-storage

Create a block volume from a backup

You can use annotations to create a volume from an existing backup. Simply use an annotation and reference the volume OCID.

kind: PersistentVolumeClaim
apiVersion: v1
metadata:
  name: block-volume-from-backup
  annotations:
    volume.beta.kubernetes.io/oci-volume-source: ocid...
spec:
  storageClassName: "oci"
  selector:
    matchLabels:
      failure-domain.beta.kubernetes.io/zone: "PHX-AD-1"
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 50Gi

Misc

You can add a prefix to volume display names by setting an OCI_VOLUME_NAME_PREFIX environment variable.

Contributing

oci-volume-provisioner is an open source project. See CONTRIBUTING for details.

Oracle gratefully acknowledges the contributions to this project that have been made by the community.

License

Copyright (c) 2017, Oracle and/or its affiliates. All rights reserved.

oci-volume-provisioner is licensed under the Apache License 2.0.

See LICENSE for more details.