huaweicloud/huawei-cloud-obs-upload

Huawei Cloud OBS Upload Skill

Visão Geral

Faça upload de arquivos ou diretórios locais para buckets do Huawei Cloud OBS, liste buckets OBS com capacidade e contagem de objetos, e agende uploads periódicos via crontab. Operações de upload usam obsutil; listagem/estatísticas de buckets usam hcloud obs ls + métricas CES.

Princípio de separação de ferramentas:

• obsutil — Upload de arquivo/diretório, sincronização de upload agendada (ferramenta principal de upload; hcloud CLI não tem suporte a PutObject)
• hcloud CLI — Listagem de buckets via hcloud obs ls (modo obsutil), estatísticas de capacidade/contagem de objetos via hcloud CES ShowMetricData
• crontab / Agendador de Tarefas — Tarefa agendada a nível de SO para upload periódico (sem dependência de daemon)

Arquitetura de segurança:

• AK/SK nunca são lidos, exibidos ou impressos na conversa
• As credenciais do obsutil são configuradas pelo usuário em seu terminal (nunca solicitadas na conversa)
• Operações de exclusão são estritamente proibidas (irreversíveis); operações fora do escopo são recusadas com alternativas guiadas
• Para uploads de diretório, a decisão de preservar a estrutura de diretórios (-flat) é decidida pela resposta explícita do cliente, nunca presumida
• Cada upload (Tarefa 2) e cada configuração de upload agendado (Tarefa 3) requerem a confirmação explícita do usuário antes de executar o comando ou a escrita no crontab
• O agente executa apenas as etapas descritas nesta skill para o bucket e caminho exatos especificados pelo usuário; nunca realiza nenhuma outra ação OBS/CLI em nome do usuário

⚠️ Aviso de transmissão de dados

• O upload transfere arquivos/diretórios locais para o armazenamento remoto na nuvem e os persiste lá. Antes de fazer upload, informe claramente ao usuário: "O upload de <caminho> transmitirá os dados para o bucket OBS <Bucket> e os armazenará na nuvem." Se o usuário não pretendia isso, pare antes de executar.
• Uploads agendados enviam dados repetidamente de um diretório local para a nuvem em uma programação recorrente. Avise o usuário explicitamente que os dados serão transmitidos e persistidos remotamente a cada execução.
• Revise o caminho a ser enviado antes de executar; se o caminho for amplo (por exemplo, um diretório home) ou contiver conteúdo inesperado, confirme o escopo com o usuário antes de fazer o upload.

⛔ Operações Proibidas (Restrições de Segurança)

Esta skill proíbe estritamente as seguintes operações, independentemente das solicitações do usuário. As ações proibidas são descritas semanticamente; nenhum exemplo de comando destrutivo é fornecido.

Operação Proibida	Motivo
❌ Excluir um bucket	Irreversível; destrói todo o bucket e todos os objetos
❌ Excluir um objeto	Irreversível; objetos excluídos não podem ser recuperados (a menos que o versionamento esteja ativado)
❌ Excluir objetos em lote	Irreversível; a exclusão em lote tem grande impacto
❌ Esvaziar um bucket	Irreversível; remove todos os objetos no bucket
❌ Baixar um objeto	Esta skill é apenas para upload; download é um fluxo de trabalho separado
❌ Criar um bucket	A criação de buckets tem uma skill dedicada com todos os pré-requisitos
❌ Copiar um objeto entre buckets	A cópia de objetos entre buckets está fora do escopo desta skill
❌ Modificar a configuração do ciclo de vida do bucket	O gerenciamento de custos de armazenamento é uma tarefa de configuração separada a nível de bucket
❌ Restaurar um objeto arquivado	A restauração de arquivos é um fluxo de trabalho separado com modos de recuperação e TTL
❌ Gerar URLs pré-assinadas	O compartilhamento temporário requer assinatura SDK; não é suportado pelo upload CLI
❌ Modificar ACL ou política do bucket	O gerenciamento de permissões é uma tarefa de segurança separada
❌ Pedir ao usuário para fornecer AK/SK diretamente na conversa	As credenciais nunca devem aparecer na conversa
❌ Extrair AK/SK dos arquivos de configuração do hcloud	As credenciais são criptografadas e não podem ser usadas diretamente
❌ Pular a verificação de credenciais do obsutil antes das operações OBS	As operações falham sem credenciais configuradas
❌ Usar -flat para uploads de diretório sem perguntar ao cliente	-flat descarta a estrutura de diretórios; deve seguir a resposta explícita do cliente
❌ Adivinhar caminho local, nome do bucket ou prefixo de destino	Os parâmetros necessários devem ser fornecidos pelo usuário

Se um usuário solicitar uma operação de exclusão, você deve recusar e informar: "Por restrições de segurança, esta skill não permite operações de exclusão (excluir bucket/objeto/exclusão em lote/esvaziar bucket). Use o console do Huawei Cloud OBS ou o obsutil manualmente."

Se um usuário solicitar uma operação fora do escopo, não tente realizá-la. Informe o usuário com a alternativa recomendada da tabela abaixo:

Operação	Alternativa recomendada
Baixar objeto	Use obsutil cp obs://<Bucket>/<Key> <CaminhoLocal> manualmente, ou o console OBS
Criar bucket	Use a skill dedicada huawei-cloud-obs-bucket-create, ou o console OBS
Copiar objeto	Use hcloud OBS CopyObject manualmente, ou o console OBS
Configuração de ciclo de vida	Use o console OBS (Bucket > Ciclo de Vida), ou hcloud OBS SetBucketLifecycle
Restaurar objeto arquivado	Use obsutil restore obs://<Bucket>/<Key> manualmente, ou o console OBS
URL pré-assinada	Use o SDK do Huawei Cloud (Java/Python/Go) para gerar URLs pré-assinadas, ou o console OBS
ACL/Política do bucket	Use o console OBS (Bucket > Permissões), ou hcloud OBS SetBucketAcl/SetBucketPolicy

Arquitetura

Gerenciamento de Upload OBS Huawei Cloud
├── Tarefa 1: ListBucketsWithStats   (Listar buckets com capacidade e contagem de objetos)
│   ├── 1a. hcloud obs ls: listar todos os buckets
│   ├── 1b. Métricas CES / API OBS: consultar capacidade e contagem de objetos do bucket
│   └── 1c. Relatar tabela de estatísticas do bucket ao usuário
├── Tarefa 2: UploadFile             (Fazer upload de arquivo ou diretório local para o bucket de destino)
│   ├── 2a. Confirmar caminho local + nome do bucket + prefixo de destino com o usuário
│   ├── 2b. Para diretório: perguntar ao cliente se deseja preservar a estrutura de diretórios (decidir -flat)
│   ├── 2c. Avisar que os dados persistem remotamente + obter confirmação explícita do usuário
│   ├── 2d. obsutil cp: arquivo único (-flat) ou diretório (-r, -flat opcional conforme resposta do cliente)
│   └── 2e. Verificar resultado do upload
└── Tarefa 3: ScheduledUpload       (Agendar upload periódico de diretório local para o bucket de destino)
    ├── 3a. Confirmar diretório local + bucket + prefixo + período de agendamento com o usuário
    ├── 3b. Perguntar ao cliente se deseja preservar a estrutura de diretórios (decidir -flat)
    ├── 3c. Avisar sobre persistência + obter confirmação explícita do usuário
    ├── 3d. Gerar script de upload obsutil (com/sem -flat conforme resposta do cliente)
    ├── 3e. Configurar tarefa agendada crontab / Agendador de Tarefas
    └── 3f. Verificar se a tarefa agendada foi configurada

Pré-requisitos

Verificação de pré-requisito 1/3: Huawei Cloud CLI (hcloud / KooCLI) >= 3.2.0 necessário Execute hcloud version para verificar se a versão >= 3.2.0. Se não estiver instalado ou a versão for muito antiga, consulte references/cli-installation-guide.md para o guia de instalação.

hcloud version

Verificação de pré-requisito 2/3: obsutil >= 5.5.0 necessário (para recursos de upload) O upload de arquivos/diretórios requer a ferramenta CLI obsutil do Huawei Cloud. Execute obsutil version para verificar se a versão >= 5.5.0. Se não estiver instalado, consulte references/cli-installation-guide.md para o guia de instalação.

obsutil version

Verificação de pré-requisito 3/3: Configuração de credenciais obsutil necessária

O módulo hcloud obs mapeia para o obsutil internamente, que requer configuração separada de AK/SK e Endpoint. Antes de realizar operações OBS, você deve verificar se as credenciais do obsutil estão configuradas:

hcloud obs ls -limit=1

Se a resposta for Please set ak, sk and endpoint in the configuration file! ou InvalidAccessKeyId, as credenciais do obsutil não estão configuradas.

Resolução: Oriente o usuário a configurar as credenciais do obsutil em seu próprio terminal (não peça ao usuário para fornecer AK/SK diretamente na conversa), com o aviso de segurança abaixo:

As credenciais do obsutil não estão configuradas. Execute o seguinte comando em seu terminal para configurar (AK/SK podem ser obtidos na página "Minhas Credenciais" do console Huawei Cloud):

  hcloud obs config -i=<SeuAK> -k=<SeuSK> -e=obs.<Regiao>.myhuaweicloud.com

Exemplo (região Guangzhou):
  hcloud obs config -i=<SeuAK> -k=<SeuSK> -e=obs.cn-south-1.myhuaweicloud.com

Endpoints comuns:
  cn-north-4  → obs.cn-north-4.myhuaweicloud.com
  cn-east-3   → obs.cn-east-3.myhuaweicloud.com
  cn-south-1  → obs.cn-south-1.myhuaweicloud.com
  cn-southwest-2 → obs.cn-southwest-2.myhuaweicloud.com

⚠️ Aviso de segurança: colocar AK/SK na linha de comando os expõe ao histórico do shell e às listagens de processos do SO.
Prefira a configuração interativa (`hcloud configure`) ou variáveis de ambiente (HW_ACCESS_KEY / HW_SECRET_KEY).
Após a configuração, limpe o histórico do shell se o comando em texto simples foi usado.

Tente novamente após a configuração.

⚠️ Requisitos de formato de parâmetros hcloud

Os comandos da API de serviço em nuvem hcloud (KooCLI) (módulo em maiúsculas, ex: hcloud CES ShowMetricData) devem usar o formato --param=valor (conectado com sinal de igual); o formato separado por espaço não é suportado.

✅ Correto: hcloud CES ShowMetricData --region=cn-south-1 --namespace=SYS.OBS

❌ Incorreto: hcloud CES ShowMetricData --region cn-south-1

Nota: hcloud obs (minúsculo, modo obsutil) mapeia diretamente para comandos obsutil e usa o estilo de parâmetros do obsutil (ex: hcloud obs ls, hcloud obs config -i=...); a regra --param=valor não se aplica. Não existe o comando hcloud OBS ListBuckets — use hcloud obs ls para listar buckets.

---

Autenticação

Regras de segurança (devem ser seguidas):

• Proibido ler, ecoar ou imprimir valores de AK/SK
• Proibido pedir ao usuário para inserir AK/SK diretamente na conversa
• Proibido usar hcloud configure set para passar valores de credenciais em texto simples
• Proibido aceitar AK/SK fornecidos diretamente pelo usuário na conversa
• Permitido apenas ler credenciais de variáveis de ambiente ou arquivos de configuração CLI configurados

⚠️ Aviso de exposição de credenciais (compartilhe com o usuário quando a configuração de credenciais for discutida):

• Passar AK/SK como argumentos de linha de comando (ex: obsutil config -ak=... -sk=... ou hcloud configure set --access-key-id=...) expõe as credenciais ao histórico do shell, listagens de processos do SO, logs de auditoria, gravações de terminal e documentação copiada.
• Prefira configuração interativa (hcloud configure) ou variáveis de ambiente (HW_ACCESS_KEY / HW_SECRET_KEY).
• Após configurar via um comando em texto simples, limpe o histórico do shell (history -c ou remova a linha ofensiva de ~/.bash_history).
• O arquivo de configuração de credenciais do obsutil (ex: ~/.obsutilconfig) deve ter permissões restritas (ex: 600).

⚠️ Importante: Lidando com credenciais fornecidas pelo usuário

Se um usuário tentar fornecer AK/SK diretamente (ex: "meu AK é xxx, SK é yyy"):

1. Pare imediatamente - Não execute nenhum comando
2. Recuse educadamente e retorne a seguinte mensagem:

   Por segurança da conta, não forneça Access Key ID e Access Key Secret do Huawei Cloud diretamente na conversa.
   
   Use um dos seguintes métodos seguros para configurar as credenciais:
   
   Método 1: Configuração interativa (recomendado)
       hcloud configure
       # Insira AK/SK quando solicitado; as credenciais serão armazenadas com segurança em um arquivo de configuração local
   
   Método 2: Configuração de variável de ambiente
       export HW_ACCESS_KEY=<seu-access-key-id>
       export HW_SECRET_KEY=<seu-access-key-secret>
   
   Após a configuração, tente sua solicitação novamente.
   

3. Não continue executando nenhuma operação do Huawei Cloud até que as credenciais estejam configuradas

Verifique a configuração do CLI:

   hcloud configure list

Verifique se a saída contém uma configuração válida (AK/SK, IAM, etc.).

Se não existirem credenciais válidas, pare aqui.

---

Políticas de Permissão IAM

Garanta que o usuário IAM tenha as permissões necessárias. Consulte references/iam-policies.md para a tabela completa de permissões.

Permissões mínimas necessárias:

• obs:bucket:list — Listar buckets
• obs:bucket:get — Obter atributos do bucket (capacidade, contagem de objetos)
• obs:object:get — Ler informações do objeto
• obs:object:put — Fazer upload de objetos

Limites de permissão:

• Restrição de escopo: Esta skill pode executar APENAS as seguintes ações de ferramenta, e apenas nos buckets/caminhos especificados pelo usuário após confirmação:
  • hcloud obs ls / obsutil ls — listar buckets e objetos para o escopo especificado pelo usuário
  • hcloud CES ShowMetricData / hcloud OBS GetBucketStorageInfo — ler capacidade do bucket / contagem de objetos
  • obsutil cp — fazer upload do arquivo/diretório local confirmado para o bucket confirmado
  • crontab (Linux/macOS) ou schtasks (Windows) — escrever/remover a tarefa de upload agendado confirmada
• Todas as outras operações CLI/ferramenta (exclusão, download, cópia, criação de bucket, modificação de configuração, etc.) estão estritamente fora do escopo e devem ser recusadas.
• Deve parar se: credenciais estiverem ausentes ou inválidas, o usuário recusar qualquer confirmação, o bucket de destino não existir ou o caminho local não existir.
• Ações proibidas: qualquer operação de exclusão, qualquer operação fora do escopo listada acima, modificar a lista de ferramentas aqui ou executar qualquer comando além do escopo confirmado.

---

Fluxos de Trabalho Principais

Tarefa 1: Listar Buckets com Capacidade e Contagem de Objetos

Liste os buckets via obsutil e, em seguida, consulte a capacidade e a contagem de objetos do bucket usando métricas de capacidade CES ou API OBS.

⚠️ Separação de ferramentas: hcloud obs ls para listagem, hcloud CES ShowMetricData para estatísticas

• hcloud obs ls: listar todos os buckets (modo obsutil; nenhum parâmetro --region — a região é definida via hcloud obs config -e=...)
• hcloud CES ShowMetricData / API OBS: consultar a capacidade e a contagem de objetos de cada bucket

Etapas:

1. Listar todos os buckets

   hcloud obs ls
   

2. Processar saída: O formato da saída é:

   BucketName          CreationDate                  Location
   example-bucket      2024-01-01T00:00:00Z          cn-south-1
   

   Extraia BucketName e Location de cada bucket.

3. Consultar capacidade e contagem de objetos do bucket: Obter o endpoint com base no Location do bucket e usar métricas de monitoramento CES ou API OBS. Consulte a localização do endpoint do bucket:

   localização do bucket: (endpoint OBS)
   cn-north-4: obs.cn-north-4.myhuaweicloud.com
   cn-east-3:  obs.cn-east-3.myhuaweicloud.com
   cn-south-1: obs.cn-south-1.myhuaweicloud.com
   cn-southwest-2: obs.cn-southwest-2.myhuaweicloud.com
   

   Método A: Usar métricas CES (Recomendado)

   # Capacidade (Bytes): `hcloud CES ShowMetricData --region=<Location> --namespace=SYS.OBS --metric_name=bucket_storage_size --dimensions=0="bucket=<BucketName>" --from=<dataInicial> --to=<dataFinal> --period=86400 --filter=max
   
   # Contagem de objetos (Count): `hcloud CES ShowMetricData --region=<Location> --namespace=SYS.OBS --metric_name=bucket_object_count --dimensions=0="bucket=<BucketName>" --from=<dataInicial> --to=<dataFinal> --period=86400 --filter=max
   

   Nota: Parâmetros de data para consultas de métricas:

   • from: Timestamp Unix (em milissegundos) para a hora de início. Use $(date -d '7 days ago' +%s)000 para os últimos 7 dias.
   • to: Timestemp Unix (em milissegundos) para a hora de término. Use $(date +%s)000 para agora.

4. Gerar relatório: Apresentar ao usuário uma tabela de resumo do bucket:

   Nome do Bucket	Localização	Capacidade (GB)	Contagem de Objetos
   example-bucket	cn-south-1	1.23	456

Tarefa 2: Fazer Upload de Arquivo ou Diretório Local para um Bucket OBS

Faça upload de um arquivo ou diretório local para um bucket OBS específico.

⚠️ Separação de ferramentas: upload usa obsutil cp

• Upload de arquivo único: obsutil cp <ArquivoLocal> obs://<Bucket>[/<Prefixo>]
• Upload de diretório: obsutil cp <DiretórioLocal> obs://<Bucket>[/<Prefixo>] -r [-flat]
• hcloud obs cp NÃO EXISTE — hcloud CLI não tem suporte a PutObject; todas as operações de upload devem usar obsutil diretamente

Etapas:

1. Confirmar parâmetros com o usuário: Obter os seguintes parâmetros do usuário:

   • Caminho do arquivo/diretório local: O caminho absoluto ou relativo para o arquivo ou diretório a ser enviado
   • Nome do bucket de destino: O nome do bucket OBS para fazer upload
   • Prefixo de destino (opcional): O prefixo/caminho virtual do objeto dentro do bucket

2. Verificar se o caminho local existe

   ls -la <CaminhoLocal>
   

3. Se for um diretório: Pergunte ao cliente: "Você deseja preservar a estrutura de diretórios ao fazer upload? Se sim, a estrutura de diretórios será recriada no bucket. Se não (usar -flat), apenas os arquivos serão enviados sem a estrutura de diretórios."

   Aguarde a resposta explícita do cliente e então decida se deve usar -flat.

4. Avisar que os dados persistem remotamente: Informe claramente ao usuário: "O upload de <caminho> transmitirá os dados para o bucket OBS <Bucket> e os armazenará na nuvem." Aguarde a confirmação explícita do usuário.

5. Executar upload:

   • Upload de arquivo único:

     obsutil cp <ArquivoLocal> obs://<Bucket>[/<Prefixo>]
     

   • Upload de diretório (com estrutura de diretórios preservada):

     obsutil cp <DiretórioLocal> obs://<Bucket>[/<Prefixo>] -r
     

   • Upload de diretório (sem estrutura de diretórios, -flat):

     obsutil cp <DiretórioLocal> obs://<Bucket>[/<Prefixo>] -r -flat
     

   Nota: A flag -flat faz upload apenas dos arquivos do diretório especificado, descartando a estrutura de diretórios. Aplicável apenas para upload de diretório com -r.

6. Verificar resultado:

   # Verificar se o arquivo ou diretório foi enviado
   obsutil ls obs://<Bucket>[/<Prefixo>]
   

Tarefa 3: Agendar Upload Periódico (Crontab)

Configure uma tarefa de upload agendado que executa automaticamente a sincronização em um cronograma definido.

⚠️ Separação de ferramentas: agendamento usa crontab / Agendador de Tarefas do SO; nenhuma dependência de daemon.

• Linux/macOS: escreva uma tarefa crontab que execute o comando obsutil
• Windows: use schtasks para criar uma tarefa agendada
• obsutil é a única ferramenta de upload; o upload em si é tratado pelo obsutil, não pelo hcloud CLI

Etapas:

1. Confirmar parâmetros com o usuário: Obter:

   • Caminho do diretório local a ser sincronizado
   • Nome do bucket de destino
   • Prefixo de destino (opcional)
   • Período de agendamento: Expressão cron ou em linguagem natural (ex: "todos os dias às 2h", "a cada 2 horas", "todas as segundas-feiras")

2. Converter período em expressão cron: Converter a descrição do período do usuário em uma expressão cron padrão. Exemplo:

   • "todos os dias à meia-noite" → 0 0 * * *
   • "a cada hora" → 0 * * * *
   • "todas as segundas-feiras às 3h" → 0 3 * * 1

3. Perguntar sobre a preservação da estrutura de diretórios: "Para o upload agendado, você deseja preservar a estrutura de diretórios?" Aguarde a resposta explícita.

4. Avisar sobre persistência de dados e obter confirmação: "A tarefa agendada irá, a cada execução, transmitir o conteúdo do diretório <Diretório> para o bucket OBS <Bucket> e armazená-lo na nuvem. Confirma a configuração?" Aguarde a confirmação explícita do usuário.

5. Gerar script de upload: Criar um script shell com o comando obsutil:

   #!/bin/bash
   obsutil cp <DiretórioLocal> obs://<Bucket>[/<Prefixo>] -r [ -flat]
   

6. Configurar tarefa agendada:

   Linux/macOS (crontab):

   # Editar crontab
   crontab -e
   

   Adicionar linha (exemplo de execução diária à 1h):

   0 1 * * * /caminho/para/script.sh > /dev/null 2>&1
   

   Windows (schtasks):

   schtasks /create /tn "OBSUploadTask" /tr "obsutil cp C:\Local\Dir obs://<Bucket>[/<Prefixo>] -r [-flat]" /sc daily /st 01:00
   

   Observação: Em vez de inserir o comando diretamente em uma entrada crontab ou definição de tarefa, é altamente recomendável criar um script de upload dedicado e fazer referência a ele na tarefa agendada. Isso torna o agendamento mais gerenciável e evita problemas de escape de caracteres.

7. Verificar configuração:

   Linux/macOS:

   crontab -l
   

   Windows:

   schtasks /query /tn "OBSUploadTask"
   

---

Referências

• Guia de instalação do CLI
• Políticas IAM