Implantação de um aplicativo que utiliza o COS

Crie uma solicitação de volume persistente (PVC) para provisionar o IBM Cloud Object Storage para seu cluster.

Dependendo das configurações que você escolher em seu PVC, é possível provisionar o IBM Cloud Object Storage das maneiras a seguir:

  • Provisionamento dinâmico: Ao criar o PVC, o volume persistente (PV) correspondente e o bucket na sua instância do serviço “ IBM Cloud Object Storage ” são criados automaticamente.
  • Provisionamento estático: você pode referenciar um bucket existente na sua instância do serviço “ IBM Cloud Object Storage ” no seu PVC. Quando você cria o PVC, somente o PV correspondente é criado e vinculado automaticamente ao seu bucket existente no IBM Cloud Object Storage.

Antes de Iniciar:

Para incluir o IBM Cloud Object Storage em seu cluster:

  1. Crie um arquivo de configuração para definir a sua solicitação de volume persistente (PVC). Se você adicionar suas credenciais do IBM Cloud Object Storage às classes de armazenamento padrão, não inclua seu segredo no 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
    Escolha entre as opções a seguir.
    true: Ao criar a PVC, o PV e o depósito na instância de serviço do IBM Cloud Object Storage são criados automaticamente. Escolha essa opção para criar um novo bucket em sua instância de serviço do IBM Cloud Object Storage. Note que as credenciais de serviço devem ter permissões de Gravador para criar o depósito automaticamente.
    false: Escolha esta opção para acessar dados em um depósito existente. Quando você cria o PVC, o PV é criado e vinculado automaticamente ao bucket especificado em ibm.io/bucket.
    ibm.io/auto-delete-bucket
    Escolha entre as opções a seguir.
    true: Seus dados, o depósito e o PV são removidos automaticamente quando a PVC é excluída. A instância de serviço do IBM Cloud Object Storage permanece e não é excluída. Se você escolhe configurar essa opção como true, deve-se configurar ibm.io/auto-create-bucket: true e ibm.io/bucket: "" para que seu bucket seja criado automaticamente com um nome com o formato tmp-s3fs-xxxx.
    false: Quando a PVC é excluída, o PV é excluído automaticamente, mas seus dados e o depósito na instância de serviço do IBM Cloud Object Storage permanecem. Para acessar seus dados, deve-se criar um novo PVC com o nome de seu bucket existente.
    ibm.io/bucket
    Escolha entre as opções a seguir.
    Se ibm.io/auto-create-bucket for configurado como true: insira o nome do depósito que você deseja criar em IBM Cloud Object Storage. Se, além disso, ibm.io/auto-delete-bucket está configurado como true, deve-se deixar esse campo em branco para designar automaticamente seu bucket a um nome com o formato tmp-s3fs-xxxx. O nome deve ser exclusivo no IBM Cloud Object Storage.
    Se ibm.io/auto-create-bucket for configurado como false: insira o nome do depósito existente que você deseja acessar no cluster.
    ibm.io/object-path
    Opcional: insira o nome do subdiretório existente no bucket que você deseja montar. Use essa opção se desejar montar somente um subdiretório e não o bucket inteiro. Para montar um subdiretório, deve-se configurar ibm.io/auto-create-bucket: "false" e fornecer o nome do bucket em ibm.io/bucket.
    ibm.io/quota-limit
    Para usar esta anotação, deve-se especificar a opção --set quotaLimit=true durante a instalação. Se você quiser usar esta anotação, mas não especificou --set quotaLimit=true durante a instalação, reinstale o gráfico do leme.
    Se a opção ibm.io/quota-limit estiver definida como true``, seu PVC definirá uma quantidade máxima de armazenamento (em bytes) disponível para o bucket com base no tamanho storage: que você especificar.
    Se ibm.io/quota-limit for configurado como false, a cota não é imposta em seu significado PVC que a quantidade real de armazenamento em bytes pode exceder o storage: <size> que você especificou dependendo do seu app.
    ibm.io/endpoint
    Se você criou a instância de serviço do IBM Cloud Object Storage em um local diferente de seu cluster, insira o terminal em serviço de nuvem privada ou pública da instância de serviço do IBM Cloud Object Storage que deseja usar. Para obter mais informações e uma visão geral dos terminais em serviço disponíveis, consulte Informações adicionais do terminal. Por padrão, o plug-in do Helm ibmc recupera automaticamente o local de seu cluster e cria as classes de armazenamento usando o terminal em serviço de nuvem privada do IBM Cloud Object Storage que corresponde ao local de seu cluster. Se o seu cluster clássico estiver em uma região metropolitana com várias zonas, como dal10, será utilizado o endpoint do serviço de nuvem privada IBM Cloud Object Storage para a região metropolitana com várias zonas, como Dallas. Para verificar se o terminal em serviço nas classes de armazenamento corresponde ao terminal em serviço da instância de serviço, execute oc describe storageclass <storageclassname>. Certifique-se de inserir o terminal em serviço no formato https://<s3fs_private_service_endpoint> para terminais em serviço de nuvem privada ou http://<s3fs_public_service_endpoint> para terminais em serviço em nuvem pública. Se o terminal em serviço na classe de armazenamento corresponder ao terminal em serviço da instância de serviço do IBM Cloud Object Storage, não inclua a opção ibm.io/endpoint no arquivo PVC YAML.
    ibm.io/add-mount-param
    Insira opções de montagem para os seus volumes s3fs Fuse. Por exemplo, ibm.io/add-mount-param: "del_cache,retries=6". Para obter uma lista de opções, consulte as páginas do manual do s3fs
    ibm.io/access-policy-allowed-ips
    Insira uma lista de IPs separados por vírgula que podem acessar seus volumes. Por exemplo, ibm.io/access-policy-allowed-ips: "XX.XXX.XX.XXX, XX.XX.XX.XXX, XX.XX.XX.XX".
    storage
    Na seção “Solicitações de recursos de especificação”, insira o tamanho do seu bucket do IBM Cloud Object Storage em gigabytes. O espaço real usado no IBM Cloud Object Storage pode ser diferente e é faturado com base na tabela de precificação. Se você ativou cotas quando instalou o plug-in, a cota para o seu balde é igual a este tamanho.
    storageClassName
    Escolha entre as opções a seguir.
    Se ibm.io/auto-create-bucket: "true": insira a classe de armazenamento que deseja usar para o novo depósito.
    Se ibm.io/auto-create-bucket: "false": insira a classe de armazenamento usada para criar o depósito existente.
    Se você criou o depósito manualmente na instância de serviço do IBM Cloud Object Storage, ou se não se lembrar da classe de armazenamento que usou, localize a instância de serviço no painel da IBM Cloud e revise a Classe e o Local do depósito existente. Em seguida, use a classe de armazenamento apropriada. O terminal de API do IBM Cloud Object Storage que está configurado em sua classe de armazenamento se baseia na região na qual seu cluster está. Se você quiser acessar um bucket localizado em uma região diferente daquela em que seu cluster está, será necessário criar sua própria classe de armazenamento e usar o endpoint da API apropriado para o seu bucket.
    ibm.io/secret-name
    Insira o nome do segredo que contém as credenciais do IBM Cloud Object Storage que você criou anteriormente. Se você adicionar o seu IBM Cloud Object Storage credenciais às classes de armazenamento padrão, você não deve listar segredos no PVC. Se você deseja integrar a criptografia Key Protect ao criar novos baldes de PVCs em seu cluster, você deve incluir a chave raiz CRN ao criar seu IBM Cloud Object Storage secreto. Note que você não pode adicionar Key Protect criptografia para baldes existentes.
    secret-namespace
    Por padrão, o plug-in do COS procura o segredo no mesmo espaço de nomes no qual a PVC é criada. Se você criou o segredo em um espaço de nomes diferente daquele no qual deseja criar a PVC, insira o espaço de nomes no qual o segredo foi criado.
    ibm.io/bucket-versioning
    O controle de versão do bucket está configurado como “ false ” por padrão. Defina como true para ativar o controle de versão do bucket. Defina como false para desativar o controle de versão de um bucket em que o controle de versão está ativado. Observe que as credenciais de serviço devem ter permissões de Manager ou Writer para ativar ou desativar o controle de versão do bucket no bucket. Para obter mais informações, acesse Introdução ao controle de versões.

  2. Crie o PVC em seu cluster.

    oc apply -f filepath/pvc.yaml

  3. Verifique se o PVC foi criado e ligado ao PV.

    oc get pvc

    Saída de exemplo

    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

  4. Opcional: se você planejar acessar seus dados com um usuário não raiz ou arquivos incluídos em um depósito do IBM Cloud Object Storage existente usando o console ou a API diretamente, certifique-se de que os arquivos tenham a permissão correta designada para que seu app possa ler e atualizar com êxito os arquivos, conforme necessário.

  5. Para montar o PV para a implementação, crie um arquivo .yaml de configuração e especifique a PVC que é ligada ao PV.

    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
    Na seção de metadados, digite o rótulo para a implementação.
    matchLabels.app e labels.app
    No seletor de especificação e nas seções de metadados do modelo de especificação, digite um rótulo para o seu app.
    image
    O nome da imagem de contêiner que você deseja usar. Para listar as imagens disponíveis em sua conta do IBM Cloud Container Registry, execute ibmcloud cr image-list.
    name
    O nome do contêiner que você deseja implementar em seu cluster.
    runAsUser
    Na seção de contexto de segurança de contêineres de especificação, é possível configurar opcionalmente a execução como valor de usuário.
    mountPath
    Na seção de montagens de volume de contêineres de especificação, digite o caminho absoluto do diretório para o qual o volume é montado dentro do contêiner. Para compartilhar um volume entre diferentes apps, é possível especificar subcaminhos de volume para cada um dos apps.
    volumeMounts.name
    Na seção de montagens de volume de contêineres de especificação, digite o nome do volume para montar em seu pod.
    volumes.name
    Na seção volumes, insira o nome do volume para montar em seu pod. Geralmente, esse nome é o mesmo que volumeMounts/name.
    claimName
    Na seção de solicitação de volume persistente de volumes, insira o nome da PVC que liga o PV que você deseja usar.

Como criar uma implementação

Após criar o PVC e os arquivos de configuração de implementação, crie a implementação em seu cluster.

  1. Crie a implementação.

    oc apply -f <local_yaml_path>

  2. Verifique se o PV foi montado com êxito.

    oc describe deployment <deployment_name>

    O ponto de montagem está no campo Montagens de volume e o volume está no campo 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

  3. Verifique se é possível gravar dados em sua instância de serviço do IBM Cloud Object Storage, efetuando login no pod do app e gravando dados. Efetue login no pod que monta seu PV.

    oc exec <pod_name> -it bash

  4. Navegue para o caminho de montagem do volume que você definiu em sua implementação de app.

  5. Crie um arquivo de texto.

    echo "This is a test" > test.txt

  6. No console do IBM Cloud, acesse sua instância do serviço IBM Cloud Object Storage.

  7. No menu, selecione ** Buckets **.

  8. Abra seu bucket e verifique se é possível ver o test.txt que você criou.

Usando o armazenamento de objetos em um conjunto stateful

Se você tiver um app stateful, como um banco de dados, será possível criar conjuntos stateful que usam o IBM Cloud Object Storage para armazenar os dados de seu app. Como alternativa, é possível usar um banco de dados como um serviço do IBM Cloud (tal como o IBM Cloudant) e armazenar seus dados na nuvem.

Antes de começar, execute as etapas pré-requisitos descritas no início deste tópico.

Para implementar um conjunto stateful que usa armazenamento de objetos:

  1. Crie um arquivo de configuração para seu conjunto stateful e o serviço usado para expor o conjunto stateful. Os exemplos a seguir mostram como implementar o NGINX como um conjunto stateful com três réplicas. Cada réplica com um depósito separado ou compartilhando o mesmo depósito.

    Exemplo para criar um conjunto stateful com três réplicas, com cada réplica usando um depósito separado.

    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

    Exemplo para criar um conjunto stateful com três réplicas que compartilham o mesmo depósito mybucket.

    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

Insira um nome para seu conjunto stateful. O nome inserido é usado para criar o nome da PVC no formato: <volume_name>-< statefulset_name>-<replica_number>.

serviceName

Insira o nome do serviço que deseja usar para expor o conjunto stateful.

replicas

Insira o número de réplicas para seu conjunto stateful.

matchLabels

Na seção de rótulos de correspondência do seletor de especificação, digite todos os rótulos que você deseja incluir no seu conjunto stateful e no seu PVC. Os rótulos incluídos no volumeClaimTemplates de seu conjunto stateful não são reconhecidos pelo Kubernetes. Em vez disso, deve-se definir esses rótulos na seção spec.selector.matchLabels e spec.template.metadata.labels de seu YAML do conjunto stateful. Para se certificar de que todas as réplicas de conjunto stateful estejam no balanceamento de carga do serviço, inclua o mesmo rótulo que o usado na seção spec.selector do serviço YAML.

labels

Na seção de rótulos de metadados da especificação, insira os mesmos rótulos que você incluiu na seção spec.selector.matchLabels do seu conjunto stateful do YAML.

terminationGracePeriodSeconds

Insira o número de segundos para que o kubelet encerre com segurança o pod que executa a réplica do seu stateful set. Para obter mais informações, consulte Excluir pods.

VolumeClaimTemplates.name

Na seção de metadados de modelos de solicitação de volume de especificação, insira um nome para o seu volume. Use o mesmo nome definido na seção spec.containers.volumeMount.name. O nome inserido aqui é usado para criar o nome para a PVC no formato: <volume_name>-<statefulset_name>-<replica_number>.

ibm.io/auto-create-bucket

Na seção de metadados de modelos de solicitação de volume de especificação, configure uma anotação para configurar como os depósitos são criados. Escolha entre as opções a seguir:

  • **true: **escolha essa opção para criar automaticamente um bucket para cada réplica do conjunto stateful. Note que as credenciais de serviço devem ter permissões de Gravador para criar o depósito automaticamente.
  • **false: **escolha essa opção se você desejar compartilhar um bucket existente em suas réplicas do conjunto stateful. Certifique-se de definir o nome do bucket na seção spec.volumeClaimTemplates.metadata.annotions.ibm.io/bucket de seu YAML do conjunto stateful.
ibm.io/auto-delete-bucket

Na seção de metadados de modelos de reclamação de volume de especificação, configure uma anotação para configurar como os depósitos são excluídos. Escolha entre as opções a seguir:

  • **true: **seus dados, o bucket e o PV são removidos automaticamente quando você exclui o PVC. A instância de serviço do IBM Cloud Object Storage permanece e não é excluída. Se você escolhe configurar essa opção como true, deve-se configurar ibm.io/auto-create-bucket: true e ibm.io/bucket: "" para que seu bucket seja criado automaticamente com um nome com o formato tmp-s3fs-xxxx.
  • false: quando você exclui o PVC, o PV é excluído automaticamente, mas os seus dados e o bucket em sua instância de serviço do IBM Cloud Object Storage permanecem. Para acessar seus dados, deve-se criar um novo PVC com o nome de seu bucket existente.
ibm.io/bucket

Na seção de metadados de modelos de reclamação de volume de especificação, configure uma anotação para os detalhes do depósito. Escolha entre as opções a seguir:

  • Se ibm.io/auto-create-bucket estiver configurado como true: insira o nome do bucket que você deseja criar no IBM Cloud Object Storage. Se, além disso, ibm.io/auto-delete-bucket está configurado como true, deve-se deixar esse campo em branco para designar automaticamente seu bucket a um nome com o formato tmp-s3fs-xxxx. O nome deve ser exclusivo no IBM Cloud Object Storage.
  • Se ibm.io/auto-create-bucket estiver configurado como false: insira o nome do bucket existente que você deseja acessar no cluster.
ibm.io/secret-name

Na seção de anotações de metadados de modelos de solicitação de volume de especificação, digite o nome do segredo que mantém as credenciais do IBM Cloud Object Storage que você criou anteriormente. Se incluir as credenciais do IBM Cloud Object Storage nas classes de armazenamento padrão, você não deverá listar o segredo na PVC.

kubernetes.io/storage-class

Na seção de anotações de metadados de modelos de solicitação de volume de especificação, digite a classe de armazenamento que você deseja usar. Escolha entre as opções a seguir:

  • Se ibm.io/auto-create-bucket: "true": insira a classe de armazenamento que deseja usar para o novo depósito.
  • Se ibm.io/auto-create-bucket: "false": insira a classe de armazenamento usada para criar o depósito existente.

Para listar as classes de armazenamento existentes, execute o comando oc get sc | grep s3. Se você não especificar uma classe de armazenamento, a PVC será criada com a classe de armazenamento padrão que está configurada no cluster. Certifique-se de que a classe de armazenamento padrão use o provisionador ibm.io/ibmc-s3fs para que seu conjunto stateful seja provisionado com armazenamento de objetos.

storageClassName

Na seção de especificação de modelos de solicitação de volume de especificação, digite a mesma classe de armazenamento que você inseriu na seção spec.volumeClaimTemplates.metadata.annotations.volume.beta.kubernetes.io/storage-class do seu conjunto stateful do YAML.

storage

Na seção de solicitações de recursos de especificação de modelos de solicitação de volume de especificação, digite um tamanho fictício para o seu depósito do IBM Cloud Object Storage em gigabytes. O tamanho é necessário para o Kubernetes, mas não é respeitado no IBM Cloud Object Storage. É possível inserir qualquer tamanho que desejar. O espaço real usado no IBM Cloud Object Storage pode ser diferente e é faturado com base na tabela de precificação.