COS を利用するアプリのデプロイ

クラスターで IBM Cloud Object Storage をプロビジョンするために、永続ボリューム請求 (PVC) を作成します。

PVC で選択した設定に応じて、以下の方法で IBM Cloud Object Storage をプロビジョンすることができます。

動的プロビジョニング ：PVC を作成すると、対応する永続ボリューム（PV）と、 IBM Cloud Object Storage サービスインスタンス内のバケットが自動的に作成されます。
静的プロビジョニング ：PVC内で、 IBM Cloud Object Storage サービスインスタンス内の既存のバケットを参照することができます。 PVC を作成すると、一致する PV のみが自動的に作成され、IBM Cloud Object Storage の既存のバケットにリンクされます。

始める前に

クラスターに IBM Cloud Object Storage を追加するには、以下のようにします。

永続ボリューム請求 (PVC) を定義した構成ファイルを作成します。 IBM Cloud Object Storage の認証情報をデフォルトのストレージクラスに追加する場合は、PVCにシークレットを記載しないでください。
```
kind: PersistentVolumeClaim
apiVersion: v1
metadata:
  name: <name> # Enter the name of the PVC.
  namespace: <namespace> # Enter the namespace where you want to create the PVC. The PVC must be created in the same namespace where you created the Kubernetes secret for your service credentials and where you want to run your pod.
  annotations:
    ibm.io/auto-create-bucket: "<true_or_false>"
    ibm.io/auto-delete-bucket: "<true_or_false>"
    ibm.io/bucket: "<bucket_name>"
    ibm.io/object-path: "<bucket_subdirectory>"
    ibm.io/quota-limit: "true/false" # Disable or enable a quota limit for your PVC. To use this annotation you must specify the -set quotaLimit=true option during installation.
    ibm.io/endpoint: "https://<s3fs_service_endpoint>"
    ibm.io/tls-cipher-suite: "default"
    ibm.io/secret-name: "<secret_name>" # The name of your Kubernetes secret that you created.
    ibm.io/secret-namespace: "<secret-namespace>" # By default, the COS plug-in searches for your secret in the same namespace where you create the PVC. If you created your secret in a namespace other than the namespace where you want to create your PVC, enter the namespace where you created your secret.
    ibm.io/add-mount-param: "<option-1>,<option-2>" # s3fs mount options
    ibm.io/access-policy-allowed-ips: "XX.XXX.XX.XXX, XX.XX.XX.XXX, XX.XX.XX.XX" # A csv of allow listed IPs.
    ibm.io/bucket-versioning: "false" # Set to true to enable bucket versioning.
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: <size>
  storageClassName: <storage_class>
```
ibm.io/auto-create-bucket

次のいずれかのオプションを選択します。

true: PVC を作成すると、IBM Cloud Object Storage サービス・インスタンス内の PV とバケットが自動的に作成されます。 IBM Cloud Object Storage サービス・インスタンスに新規バケットを作成するには、このオプションを選択します。サービス資格情報には、バケットを自動的に作成するための Writer 権限が必要です。

false: 既存のバケット内のデータにアクセスする場合は、このオプションを選択します。 PVC を作成すると、PV が自動的に作成され、ibm.io/bucket で指定したバケットにリンクされます。

ibm.io/auto-delete-bucket

次のいずれかのオプションを選択します。

true: PVC を削除すると、データ、バケット、および PV が自動的に削除されます。 IBM Cloud Object Storage サービス・インスタンスは維持され、削除されません。このオプションを true に設定する場合は、ibm.io/auto-create-bucket: true および ibm.io/bucket: "" を設定して、tmp-s3fs-xxxx の形式の名前でバケットが自動的に作成されるようにする必要があります。

false: PVC を削除すると、PV は自動的に削除されますが、IBM Cloud Object Storage サービス・インスタンス内のデータとバケットは残ります。データにアクセスするには、既存のバケットの名前を持つ新しい PVC を作成する必要があります。

ibm.io/bucket

次のいずれかのオプションを選択します。

ibm.io/auto-create-bucketがtrueに設定されている場合: IBM Cloud Object Storage で作成するバケットの名前を入力します。さらに ibm.io/auto-delete-bucket が true に設定されている場合は、tmp-s3fs-xxxx の形式の名前が自動的にバケットに割り当てられるように、このフィールドをブランクのままにする必要があります。この名前は、IBM Cloud Object Storage において固有でなければなりません。

ibm.io/auto-create-bucketがfalseに設定されている場合: クラスター内でアクセスする既存のバケットの名前を入力します。

ibm.io/object-path

オプション: マウントするバケットの既存のサブディレクトリーの名前を入力します。このオプションは、1 つのサブディレクトリーのみをマウントし、バケット全体をマウントしない場合に使用します。サブディレクトリーをマウントするには、ibm.io/auto-create-bucket: "false" を設定し、ibm.io/bucket にバケットの名前を指定する必要があります。

ibm.io/quota-limit

このアノテーションを使用するには、インストール時に --set quotaLimit=true オプションを指定する必要があります。このアノテーションを使用するが、インストール時に --set quotaLimit=true を指定しなかった場合は、 helm チャートを再インストールします。

ibm.io/quota-limit がに設定されている場合、PVC は、指定したサイズに基づいて、バケットで利用可能な最大ストレージ容量（バイト単位）を設定します。 true storage: <size>

ibm.io/quota-limit が false に設定されている場合、割り当て量は PVC に適用されません。つまり、実際のストレージ量 (バイト単位) は、アプリに応じて指定した storage: <size> を超える可能性があります。

ibm.io/endpoint

クラスターとは異なるロケーションに IBM Cloud Object Storage サービス・インスタンスを作成した場合は、使用する IBM Cloud Object Storage サービス・インスタンスのプライベート・クラウド・サービス・エンドポイントまたはパブリック・クラウド・サービス・エンドポイントを入力します。使用可能なサービス・エンドポイントの詳細および概要については、追加のエンドポイント情報を参照してください。デフォルトでは、ibmc Helm プラグインにより、クラスター・ロケーションが自動的に取得され、クラスター・ロケーションに一致する IBM Cloud Object Storage プライベート・クラウド・サービス・エンドポイントを使用して、ストレージ・クラスが作成されます。クラシッククラスターが、 dal10 のようなマルチゾーンメトロにある場合、ダラスなどのマルチゾーンメトロ向けの「 IBM Cloud Object Storage 」プライベートクラウドサービスエンドポイントが使用されます。ストレージ・クラス内のサービス・エンドポイントが、サービス・インスタンスのサービス・エンドポイントと一致することを確認するには、oc describe storageclass <storageclassname>を実行します。サービスエンドポイントは、プライベート・クラウド・サービス・エンドポイント用のhttps://<s3fs_private_service_endpoint>フォーマット、またはパブリック・クラウド・サービス・エンドポイント用のhttp://<s3fs_public_service_endpoint>フォーマットで入力していることを確認してください。ストレージ・クラス内のサービス・エンドポイントが IBM Cloud Object Storage サービス・インスタンスのサービス・エンドポイントと一致する場合は、PVC YAML ファイルにibm.io/endpointオプションを含めないでください。

ibm.io/add-mount-param

s3fs Fuse ボリュームのマウント・オプションを入力します。例えば、 ibm.io/add-mount-param: "del_cache,retries=6" などです。オプションのリストについては、 s3fs マニュアル・ページを参照してください。

ibm.io/access-policy-allowed-ips

ボリュームにアクセスできる IP のコンマ区切りリストを入力します。例えば、ibm.io/access-policy-allowed-ips: "XX.XXX.XX.XXX, XX.XX.XX.XXX, XX.XX.XX.XX" です。

storage

「リソースのリクエスト」セクションで、 IBM Cloud Object Storage バケットのサイズをギガバイト単位で入力してください。 IBM Cloud Object Storage で実際にご利用になる容量は異なる場合があり、料金表に基づいて課金されます。プラグインのインストール時に割り当て量を有効にした場合、バケットの割り当て量はこのサイズと等しくなります。

storageClassName

次のいずれかのオプションを選択します。

の場合ibm.io/auto-create-bucket: "true": 新規バケットに使用するストレージ・クラスを入力します。

の場合ibm.io/auto-create-bucket: "false": 既存のバケットを作成するために使用したストレージ・クラスを入力します。

もし IBM Cloud Object Storage サービス・インスタンスでバケットを手動で作成した場合、または使用したストレージ・クラスを覚えていない場合は、 IBM Cloud ダッシュボードでサービス・インスタンスを探し、既存のバケットの Class と Location を確認します。次に、適切なストレージ・クラスを使用します。ご使用のストレージ・クラスに設定されている IBM Cloud Object Storage API エンドポイントは、クラスターのあるリージョンに基づいています。クラスターが配置されているリージョンとは異なるリージョンにあるバケットにアクセスしたい場合は、独自のストレージクラスを作成し、そのバケットに適したAPIエンドポイントを使用する必要があります。

ibm.io/secret-name

以前に作成した IBM Cloud Object Storage 資格情報を保持するシークレットの名前を入力します。 IBM Cloud Object Storage 資格情報をデフォルトのストレージ・クラスに追加する場合は、PVC 内のシークレットをリストしないでください。クラスター内の PVC から新規バケットを作成するときに Key Protect 暗号化を統合する場合は、 IBM Cloud Object Storage シークレットを作成するときにルート・キー CRN を含める必要があります。 Key Protect の暗号化を既存のバケットに追加することはできません。

secret-namespace

デフォルトでは、COS プラグインは、PVC を作成した名前空間と同じ名前空間で機密事項を検索します。 PVC を作成する名前空間以外の名前空間に機密事項を作成した場合は、機密事項を作成した名前空間を入力します。

ibm.io/bucket-versioning

バケットのバージョン管理は、デフォルトで「 false 」に設定されています。バケツのバージョニングを有効にするには、 true に設定します。バージョニングが有効になっているバケツでバージョニングを無効にするには、 false に設定します。バケツのバージョニングを有効にしたり無効にしたりするには、サービスの認証情報に Manager または Writer の権限が必要であることに注意してください。詳細については、「バージョン管理の始め方」を参照してください。
クラスター内に PVC を作成します。
```
oc apply -f filepath/pvc.yaml
```

PVC が作成され、PV にバインドされたことを確認します。

oc get pvc

出力例

NAME                  STATUS    VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS                     AGE
s3fs-test-pvc         Bound     pvc-b38b30f9-1234-11e8-ad2b-t910456jbe12   8Gi        RWO            ibmc-s3fs-standard-cross-region  1h

オプション: 非 root ユーザーとしてデータにアクセスする場合、または既存の IBM Cloud Object Storage バケットに追加されたファイルにコンソールまたは API を使用して直接アクセスする場合は、アプリが正常にファイルを読み取り、必要に応じて更新できるように、ファイルに正しい権限が割り当てられていることを確認します。
PV をデプロイメントにマウントするには、構成.yamlファイルを作成し、PV をバインドする PVC を指定します。
```
apiVersion: apps/v1
kind: Deployment
metadata:
  name: <deployment_name>
  labels:
    app: <deployment_label>
spec:
  selector:
    matchLabels:
      app: <app_name>
  template:
    metadata:
      labels:
        app: <app_name>
    spec:
      containers:
      - image: <image_name>
        name: <container_name>
        securityContext:
          runAsUser: <non_root_user>
        volumeMounts:
        - name: <volume_name>
          mountPath: /<file_path>
      volumes:
      - name: <volume_name>
        persistentVolumeClaim:
          claimName: <pvc_name>
```
app

metadata セクションで、デプロイメントのラベルを入力します。

matchLabels.app および labels.app

spec の selector セクションおよび spec の template の metadata セクションで、アプリのラベルを入力します。

image

使用するコンテナー・イメージの名前。 IBM Cloud Container Registry アカウント内の使用可能なイメージをリストするには、ibmcloud cr image-list を実行します。

name

クラスターにデプロイするコンテナーの名前。

runAsUser

spec の containers の securityContext セクションでは、オプションで実行ユーザーの値を設定することができます。

mountPath

spec の containers の volumeMounts セクションで、コンテナー内でボリュームがマウントされるディレクトリーの絶対パスを入力します。異なるアプリ間でボリュームを共有したい場合は、各アプリごとにボリュームのサブパスを指定することができます。

volumeMounts.name

spec の containers の volumeMounts セクションで、ポッドにマウントするボリュームの名前を入力します。

volumes.name

volumes セクションで、ポッドにマウントするボリュームの名前を入力します。通常、この名前は volumeMounts/name と同じです。

claimName

volumes の persistentVolumeClaim セクションで、使用する PV をバインドする PVC の名前を入力します。

デプロイメントの作成

PVC とデプロイメントの構成ファイルを作成したら、クラスターにデプロイメントを作成します。

デプロイメントを作成します。
```
oc apply -f <local_yaml_path>
```

PV が正常にマウントされたことを確認します。

oc describe deployment <deployment_name>

マウント・ポイントは Volume Mounts フィールドにあり、ボリュームは Volumes フィールドにあります。

Volume Mounts:
      /var/run/secrets/kubernetes.io/serviceaccount from default-token-tqp61 (ro)
      /volumemount from myvol (rw)
...
Volumes:
    myvol:
    Type:    PersistentVolumeClaim (a reference to a PersistentVolumeClaim in the same namespace)
    ClaimName:    mypvc
    ReadOnly:    false

アプリ・ポッドにログインしてデータを書き込むことで、IBM Cloud Object Storage サービス・インスタンスにデータを書き込めることを確認します。 PV をマウントするポッドにログインします。
```
oc exec <pod_name> -it bash
```
アプリ・デプロイメントで定義したボリューム・マウント・パスにナビゲートします。
テキスト・ファイルを作成します。
```
echo "This is a test" > test.txt
```
IBM Cloud コンソールから、 IBM Cloud Object Storage サービスインスタンスに移動します。
メニューから、**「バケット」**を選択します。
バケットを開いて、作成した test.txt を表示できることを確認します。

ステートフル・セットでのオブジェクト・ストレージの使用

データベースなどのステートフルなアプリがある場合は、そのアプリのデータを保管するために、IBM Cloud Object Storage を使用するステートフル・セットを作成することができます。別の方法として、IBM Cloud Database as a Service (IBM Cloudant など) を使用し、クラウドにデータを保管することもできます。

作業を開始する前に、このトピックの冒頭に記載されている前提条件の手順を完了してください。

オブジェクト・ストレージを使用するステートフル・セットをデプロイするには、以下のようにします。

ステートフル・セットと、そのステートフル・セットを公開するために使用するサービスに関する、構成ファイルを作成します。次の例は、3 つのレプリカからなるステートフル・セットとして NGINX をデプロイする方法を示しています。レプリカごとに別個のバケットを使用する場合と、すべてのレプリカで同じバケットを共有する場合の例を示しています。

レプリカごとに別のバケットを使用して、3 つのレプリカを配備するステートフル・セットを作成する例。

apiVersion: v1
kind: Service
metadata:
  name: nginx-v01
  namespace: default
  labels:
    app: nginx-v01 # must match spec.template.metadata.labels and spec.selector.matchLabels in stateful set YAML
spec:
  ports:
  - port: 80
    name: web
  clusterIP: None
  selector:
    app: nginx-v01 # must match spec.template.metadata.labels and spec.selector.matchLabels in stateful set YAML
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: web-v01
  namespace: default
spec:
  selector:
    matchLabels:
      app: nginx-v01 # must match spec.template.metadata.labels in stateful set YAML and metadata.labels in service YAML
  serviceName: "nginx-v01"
  replicas: 3
  template:
    metadata:
      labels:
        app: nginx-v01 # must match spec.selector.matchLabels in stateful set YAML and metadata.labels in service YAML
    spec:
      terminationGracePeriodSeconds: 10
      containers:
      - name: nginx
        image: registry.k8s.io/nginx-slim:0.8
        ports:
        - containerPort: 80
          name: web
        volumeMounts:
        - name: mypvc
          mountPath: /usr/share/nginx/html
  volumeClaimTemplates:
  - metadata:
      name: mypvc
      annotations:
        ibm.io/auto-create-bucket: "true"
        ibm.io/auto-delete-bucket: "true"
        ibm.io/bucket: ""
        ibm.io/secret-name: mysecret
        volume.beta.kubernetes.io/storage-class: ibmc-s3fs-standard-perf-cross-region
        volume.beta.kubernetes.io/storage-provisioner: ibm.io/ibmc-s3fs
    spec:
      accessModes: [ "ReadWriteOnce" ]
      storageClassName: "ibmc-s3fs-standard-perf-cross-region"
      resources:
        requests:
          storage: 1Gi

mybucket という 1 つのバケットを共有する、3 つのレプリカからなるステートフル・セットを作成する例。

apiVersion: v1
kind: Service
metadata:
  name: nginx-v01
  namespace: default
  labels:
    app: nginx-v01 # must match spec.template.metadata.labels and spec.selector.matchLabels in stateful set YAML
spec:
  ports:
  - port: 80
    name: web
  clusterIP: None
  selector:
    app: nginx-v01 # must match spec.template.metadata.labels and spec.selector.matchLabels in stateful set YAML
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: web-v01
  namespace: default
spec:
  selector:
    matchLabels:
      app: nginx-v01 # must match spec.template.metadata.labels in stateful set YAML and metadata.labels in service YAML
  serviceName: "nginx-v01"
  replicas: 3
  template:
    metadata:
      labels:
        app: nginx-v01 # must match spec.selector.matchLabels in stateful set YAML and metadata.labels in service YAML
    spec:
      terminationGracePeriodSeconds: 10
      containers:
      - name: nginx
        image: registry.k8s.io/nginx-slim:0.8
        ports:
        - containerPort: 80
          name: web
        volumeMounts:
        - name: mypvc
          mountPath: /usr/share/nginx/html
  volumeClaimTemplates:
  - metadata:
      name: mypvc
      annotations:
        ibm.io/auto-create-bucket: "false"
        ibm.io/auto-delete-bucket: "false"
        ibm.io/bucket: mybucket
        ibm.io/secret-name: mysecret
        volume.beta.kubernetes.io/storage-class: ibmc-s3fs-standard-perf-cross-region
        volume.beta.kubernetes.io/storage-provisioner: ibm.io/ibmc-s3fs
    spec:
      accessModes: [ "ReadOnlyMany" ]
      storageClassName: "ibmc-s3fs-standard-perf-cross-region"
      resources:
        requests:
          storage: 1Gi

name

ステートフル・セットに対する名前を入力します。入力した名前は、<volume_name>-< statefulset_name>-<replica_number>という形式で PVC の名前を作成するために使用されます。

serviceName

ステートフル・セットを公開するために使用するサービスの名前を入力します。

replicas

ステートフル・セットのレプリカの数を入力します。

matchLabels

spec の selector の matchLabels セクションで、ステートフル・セットと PVC に含めるすべてのラベルを入力します。ステートフル・セットの volumeClaimTemplates に含めたラベルは、Kubernetes によって認識されません。代わりに、それらのラベルをステートフル・セット YAML の spec.selector.matchLabels および spec.template.metadata.labels セクションで定義する必要があります。すべてのステートフル・セット・レプリカが、サービスのロード・バランシングに含まれるようにするには、サービス YAML のspec.selectorセクションで使用したラベルと同じラベルを含めます。

labels

spec の metadata の labels セクションで、ステートフル・セット YAML の spec.selector.matchLabels セクションに追加したラベルと同じラベルを入力します。

terminationGracePeriodSeconds

kubelet が、ステートフルセットのレプリカを実行しているポッドを安全に終了させるために必要な秒数を入力してください。詳しくは、ポッドの削除を参照してください。

VolumeClaimTemplates.name

spec の volumeClaimTemplates の metadata セクションで、ボリュームの名前を入力します。 spec.containers.volumeMount.name セクションで定義した名前と同じ名前を使用します。ここに入力する名前は、<volume_name>-<statefulset_name>-<replica_number>という形式で PVC の名前を作成するために使用されます。

ibm.io/auto-create-bucket

spec の volumeClaimTemplates の metadata セクションで、アノテーションを設定してバケットの作成方法を構成します。次のいずれかのオプションを選択します。

**true: **ステートフル・セット・レプリカごとにバケットを自動的に作成するには、このオプションを選択します。サービス資格情報には、バケットを自動的に作成するための Writer 権限が必要です。
**false: **既存のバケットの 1 つをステートフル・セット・レプリカ間で共有する場合は、このオプションを選択します。ステートフル・セット YAML の spec.volumeClaimTemplates.metadata.annotions.ibm.io/bucket セクションでバケットの名前を定義してください。

ibm.io/auto-delete-bucket

spec の volumeClaimTemplates の metadata セクションで、アノテーションを設定してバケットの削除方法を構成します。次のいずれかのオプションを選択します。

**true: **データ、バケット、および PV が、PVC の削除時に自動的に削除されます。 IBM Cloud Object Storage サービス・インスタンスは維持され、削除されません。このオプションを true に設定する場合は、ibm.io/auto-create-bucket: true および ibm.io/bucket: "" を設定して、tmp-s3fs-xxxx の形式の名前でバケットが自動的に作成されるようにする必要があります。
**false: **PVC を削除すると、PV は自動的に削除されますが、IBM Cloud Object Storage サービス・インスタンスのデータとバケットは維持されます。データにアクセスするには、既存のバケットの名前を持つ新しい PVC を作成する必要があります。

ibm.io/bucket

spec の volumeClaimTemplates の metadata セクションで、バケットの詳細についてのアノテーションを設定します。次のいずれかのオプションを選択します。

ibm.io/auto-create-bucket が true に設定されている場合: IBM Cloud Object Storage に作成するバケットの名前を入力します。さらに ibm.io/auto-delete-bucket が true に設定されている場合は、tmp-s3fs-xxxx の形式の名前が自動的にバケットに割り当てられるように、このフィールドをブランクのままにする必要があります。この名前は、IBM Cloud Object Storage において固有でなければなりません。
ibm.io/auto-create-bucket が false に設定されている場合: クラスター内でアクセスする既存のバケットの名前を入力します。

ibm.io/secret-name

spec volume claim templates metadata annotations セクションで、以前に作成した IBM Cloud Object Storage 資格情報を保持するシークレットの名前を入力します。 IBM Cloud Object Storage 資格情報をデフォルトのストレージ・クラスに追加する場合は、PVC で機密事項をリストしないでください。

kubernetes.io/storage-class

spec の volumeClaimTemplates の metadata の annotations セクションで、使用するストレージ・クラスを入力します。次のいずれかのオプションを選択します。

ibm.io/auto-create-bucket: "true"の場合: 新規バケットに使用するストレージ・クラスを入力します。
ibm.io/auto-create-bucket: "false"の場合: 既存のバケットを作成するために使用したストレージ・クラスを入力します。

既存のストレージクラスを一覧表示するには、oc get sc | grep s3 を実行してください。ストレージ・クラスを指定しない場合、クラスターに設定されているデフォルトのストレージ・クラスを使用して PVC が作成されます。オブジェクト・ストレージを使用してステートフル・セットがプロビジョンされるようにするために、デフォルト・ストレージ・クラスで ibm.io/ibmc-s3fs プロビジョナーが使用されていることを確認してください。

storageClassName

spec の volumeClaimTemplates の spec セクションで、ステートフル・セット YAML の spec.volumeClaimTemplates.metadata.annotations.volume.beta.kubernetes.io/storage-class セクションに入力したストレージ・クラスを入力します。

storage

spec の volumeClaimTemplates の resources の requests セクションで、ご使用の IBM Cloud Object Storage バケットの架空のサイズ (ギガバイト単位) を入力します。このサイズは Kubernetes で必要になりますが、IBM Cloud Object Storage では考慮されません。希望するサイズを入力できます。 IBM Cloud Object Storage で実際にご利用になる容量は異なる場合があり、料金表に基づいて課金されます。