huaweicloud/huawei-cloud-ecs-manage

Huawei Cloud ECS Manage (Diagnóstico de Falha de Criação e Gerenciamento de Instâncias)

PARE - Não responda com base em conhecimento geral. Siga o procedimento abaixo.

Etapa 0: Garantir o skill-quality-cli (obrigatório; instalado no primeiro uso)

bash scripts/ensure_cli.sh   # idempotente: instala apenas se ausente (sem auto-upgrade)
export PATH="$HOME/.local/bin:$PATH"
skill-quality-cli version    # verificar se funciona

Execute esta etapa primeiro: o relatório de qualidade depende do skill-quality-cli, garantido idempotentemente pelo scripts/ensure_cli.sh (instala uma vez se estiver faltando, pula se estiver presente; sem auto-upgrade — execute skill-quality-cli upgrade para atualizar manualmente). Se estiver offline ou o download falhar, a habilidade degrada silenciosamente (o fluxo de negócios não é afetado); reexecute esta etapa quando estiver online novamente. Sempre execute hcloud ECS <Operação> --help antes de construir comandos para descobrir nomes exatos parâmetros e requisitos.

Visão Geral

Esta habilidade fornece capacidades de Agente de IA para Huawei Cloud ECS (Elastic Cloud Server / 弹性云服务器): gerenciamento do ciclo de vida da instância (criar/iniciar/parar/reiniciar/excluir), consulta de instância/cota/sabor/imagem, e um diagnóstico de causa raiz de falha de criação em 6 etapas que elimina as causas mais comuns de "Falha na criação de instância ECS" na ordem: cota → sabor → imagem → rede → par de chaves → disco.

Expõe 23 ações huawei_* em cinco grupos de capacidade:

Capacidade	Nível de risco	Ações
Consulta (somente leitura)	R3 — execução automática	huawei_list_ecs_instances, huawei_get_ecs_instance, huawei_list_ecs_flavors, huawei_list_ecs_images, huawei_list_ecs_quotas
Diagnóstico (somente leitura)	R3 — execução automática	huawei_diagnose_ecs_create_failure, huawei_analyze_ecs_health
Gerenciar — ciclo de vida	R2 — pré-visualizar + confirmar	huawei_create_ecs_instance, huawei_start_ecs_instance, huawei_stop_ecs_instance, huawei_restart_ecs_instance
Gerenciar — ciclo de vida	R1 — pré-visualizar + confirmar	huawei_delete_ecs_instance
Gerenciar — operações de alteração (§5)	R2 — pré-visualizar + confirmar	huawei_resize_ecs_instance, huawei_reinstall_ecs_os, huawei_reset_ecs_password, huawei_replace_ecs_keypair, huawei_bind_ecs_eip, huawei_change_ecs_security_group, huawei_add_ecs_nic, huawei_attach_ecs_volume, huawei_detach_ecs_volume
Gerenciar — operações de alteração (§5)	R1 — pré-visualizar + confirmar	huawei_unbind_ecs_eip, huawei_remove_ecs_nic

Toda ação de gravação é assíncrona: a API retorna um job_id e o trabalho real continua em segundo plano. A varredura desse job é uma pós-etapa obrigatória, não um extra opcional — veja §6 Varredura de job assíncrono.

Limites de escopo:

• ✅ Consultar instâncias ECS, sabores, imagens, cotas (somente leitura)
• ✅ Diagnosticar falhas de criação de ECS (cota → sabor → imagem → rede → par de chaves → disco) e analisar saúde da instância (status / disco / rede)
• ✅ Criar (pós-pago), iniciar, parar, reiniciar, excluir instâncias ECS (R2/R1: sempre pré-visualizar + confirmar)
• ✅ Alterar uma instância existente: redimensionar sabor, reinstalar SO, redefinir senha, substituir par de chaves, vincular/desvincular EIP, anexar/desanexar um grupo de segurança existente, adicionar/remover uma NIC, anexar/desanexar um volume (R2/R1: sempre pré-visualizar + confirmar)
• ❌ NUNCA criar, excluir ou reconfigurar o recurso VPC / sub-rede / grupo de segurança ou o recurso volume EVS em si. Esta habilidade apenas anexa ou desanexa recursos existentes a uma instância; use as habilidades dedicadas de VPC / EVS para mutação no nível do recurso.
• ❌ NUNCA executar qualquer ação de gravação sem confirmação explícita do usuário
• ❌ NUNCA relatar uma gravação como "concluída" antes que seu job assíncrono atinja SUCCESS e, para create, antes que a instância atinja ACTIVE
• ❌ NUNCA exibir credenciais (AK/SK, senhas, tokens) em qualquer saída ou relatório
• ➡️ Fora do escopo: RDS / consultas de banco de dados. Esta habilidade gerencia apenas computação. Quando o usuário perguntar sobre um banco de dados do qual uma instância ECS depende, passe a pergunta de volta ao usuário com um ponteiro para uma habilidade RDS dedicada ou o console Huawei Cloud RDS — esta habilidade nunca invoca outra habilidade. Veja references/related-skills.md para o texto de transferência.

Dependência: A telemetria de qualidade é coletada automaticamente via skill-quality-cli (instalado pelo scripts/ensure_cli.sh se ausente).

Avisos Críticos

Armadilha	Por quê
Esgotamento de cota é a falha de criação nº 1	Insufficient quota / Quota exceeded significa que instâncias/núcleos/RAM/volumes atingiram o limite do projeto — verifique ShowServerLimits primeiro
O sabor deve existir na região/AZ de destino	Um sabor existe globalmente, mas pode estar esgotado ou indisponível na AZ escolhida — filtre ListFlavors por --availability_zone
A imagem deve estar active e corresponder à arquitetura do sabor	Imagem deletada/privada com __os_type/architecture errada (x86 vs ARM) falha no provisionamento — verifique IMS ListImages --status=active
Sub-rede sem IPs livres bloqueia a criação	Se o CIDR da sub-rede estiver esgotado ou o dhcp desabilitado, a alocação de NIC falha
O grupo de segurança deve existir antes da criação	Referenciar um ID de grupo de segurança inexistente falha na solicitação
Erros de par de chaves são enganosos	Se key_name estiver definido, mas o par de chaves não existir, a criação falha com KeypairNotFound — verifique com KPS ListKeypairs
Disponibilidade de disco/AZ	Tipos de volume raiz/dados (SATA/SAS/GPSSD) podem estar indisponíveis na AZ de destino — verifique EVS ListVolumes e cotas de volume
Exclusão é irreversível	R1: verifique a instância primeiro, confirme que não há dependência de dados e, em seguida, exija confirmação explícita do usuário

Pré-requisitos

1. CLI hcloud (KooCLI 7.2.x ou posterior) instalada e autenticada.
   • Guia de instalação e configuração: veja references/cli-installation-guide.md
   • Dois modos de autenticação suportados:
     • Credenciais AK/SK: variáveis de ambiente HUAWEICLOUD_SDK_AK / HUAWEICLOUD_SDK_SK (ou HUAWEI_ACCESS_KEY / HUAWEI_SECRET_KEY), ou configuração interativa via assistente hcloud configure
     • Perfil hcloud local: execute "hcloud configure list"; deve mostrar um perfil válido com modo AKSK e um accessKeyId real
   • Verifique a autenticação com "hcloud configure list"
2. Região: ECS é específico da região. Sempre passe --cli-region={região} (ex.: cn-north-4). --project_id é preenchido automaticamente a partir do perfil quando omitido.
3. Permissões IAM: políticas de privilégio mínimo são fornecidas em references/iam-policies.md.
   • Consulta/diagnóstico: ecs:cloudServers:list, ecs:cloudServers:get, ecs:cloudServerFlavors:list, ecs:cloudServerImages:list, ecs:jobs:get, ecs:serverVolumes:list, ims:images:list, vpc:subnets:list, vpc:securityGroups:list, vpc:publicIps:list, evs:volumes:list, kps:keypairs:list (etapa 5 de diagnóstico, hcloud KPS ListKeypairs)
   • Gerenciar: ecs:cloudServers:create, ecs:cloudServers:action (iniciar/parar/reiniciar, redimensionar, reinstalar, redefinir senha, alterações de NIC e grupo de segurança), ecs:cloudServers:delete
   • Operações de alteração (§5) também precisam da ação de gravação de cada recurso que tocam, ex.: evs:volumes:delete com --delete_volume=true, vpc:publicIps:delete com --delete_publicip=true; a lista exata está em references/iam-policies.md.
4. skill-quality-cli — garantido por bash scripts/ensure_cli.sh (idempotente, pula se presente)
   • Atualização: execute skill-quality-cli upgrade manualmente (sem auto-upgrade)
   • Desabilitar relatório de telemetria: defina SKILL_QUALITY_REPORT=0

Fluxo de Trabalho

1. Identificar alvo → região, instance_id / flavor_id / image_id / vpc_id / subnet_id / key_name, palavras-chave de intenção
2. Classificar intenção →
     - Consulta/Diagnóstico (R3): listar / mostrar / analisar / diagnosticar — execução automática
     - Gerenciar ciclo de vida (R2): criar / iniciar / parar / reiniciar — SEMPRE mostrar pré-visualização e pedir confirmação explícita
     - Gerenciar ciclo de vida (R1): excluir — SEMPRE mostrar detalhes da instância, aviso de irreversibilidade, confirmação explícita
     - Gerenciar operações de alteração (R2): redimensionar / reinstalar / redefinir senha / substituir par de chaves / vincular EIP /
       alterar grupo de segurança / adicionar NIC / anexar volume — SEMPRE pré-visualizar + confirmar
     - Gerenciar operações de alteração (R1): desvincular EIP / remover NIC / excluir par de chaves — SEMPRE mostrar o anexo
       atual, aviso de irreversibilidade, confirmação explícita
3. Pré-verificação → para criar e para cada operação de alteração, execute as verificações somente leitura relevantes primeiro
   (cota, sabor, imagem, rede, par de chaves, disco) para que o usuário confirme com base no estado real
4. Executar → construir o comando hcloud a partir dos modelos verificados abaixo
5. Capturar o ID do job → a API de gravação retorna um job_id imediatamente; o trabalho ainda está em execução
6. Varrer job assíncrono → `hcloud ECS ShowJob` até `status=SUCCESS|FAIL`; para criar TAMBÉM varra
   `hcloud ECS ShowServer` até `status=ACTIVE`; em seguida, relate o estado FINAL ao usuário
7. Saída → resumo JSON estruturado + relatório de diagnóstico legível
8. Relatar qualidade → automático via invocação do skill-quality-cli run (consulte Etapa 0 / Pré-requisitos nº 4)

Portões de confirmação (NÃO devem ser ignorados):

• Ações R2 (huawei_create_ecs_instance, huawei_start_ecs_instance, huawei_stop_ecs_instance, huawei_restart_ecs_instance): mostre o comando completo, a(s) instância(s) de destino e pergunte "confirmar?" antes de executar.
• Ação R1 (huawei_delete_ecs_instance): primeiro execute a verificação somente leitura (ShowServer para confirmar que a instância existe e registrar seu status/sabor/volumes). Mostre o comando completo com o aviso de exclusão irreversível e exija confirmação explícita antes de executar.
• Ações de operação de alteração (R2: huawei_resize_ecs_instance, huawei_reinstall_ecs_os, huawei_reset_ecs_password, huawei_replace_ecs_keypair, huawei_bind_ecs_eip, huawei_change_ecs_security_group, huawei_add_ecs_nic, huawei_attach_ecs_volume): mostre o estado atual (via ShowServer / ListServerVolumeAttachments / ListServerInterfaces), o comando completo e o estado final esperado, e então pergunte "confirmar?".
• Ações de operação de alteração (R1: huawei_unbind_ecs_eip, huawei_remove_ecs_nic): mostre o que será desanexado e o impacto na conectividade (um EIP desvinculado perde acesso público; uma NIC removida perde aquele caminho de rede e seu IP privado), exija confirmação explícita e nunca os encadeie com uma exclusão. Para huawei_detach_ecs_volume (R2) avise que --delete_flag=1 exclui o disco de dados.
• Pré-verificação de criação: antes de huawei_create_ecs_instance, SEMPRE execute huawei_diagnose_ecs_create_failure (ou pelo menos as verificações de cota + sabor + imagem) para que o usuário veja que o ambiente está pronto, e então confirme.
• Varredura assíncrona é obrigatória: nunca encerre uma ação de gravação antes que o job atinja um estado terminal. Um job_id sem varredura é uma ação incompleta, não um sucesso.

As operações de gravação são marcadas como [W] / 写操作 nos blocos de comando abaixo (palavras-chave de detecção: criar / iniciar / parar / reiniciar / excluir — os mesmos verbos que o detector de operação de gravação do pipeline de teste usa).

Comandos Principais

Todos os comandos abaixo são mostrados em forma dupla: o comando executável hcloud <Service> <Operation> e o payload idêntico encapsulado com skill-quality-cli run --skill-name huawei-cloud-ecs-manage -- ... para relatório de qualidade. Eles exigem a KooCLI (CLI hcloud) instalada e autenticada (consulte Pré-requisitos); nenhum pacote Python SDK é necessário para qualquer comando de negócios.

⚠️ Obrigatório: todo comando hcloud nesta habilidade DEVE ser encapsulado com skill-quality-cli run --skill-name huawei-cloud-ecs-manage -- <comando> — chamadas hcloud nuas são estritamente proibidas.

1. Consulta (R3 — somente leitura, execução automática)

huawei_list_ecs_instances — listar instâncias ECS e seus status:

# Opcional: --limit={n} --offset={n} --status={ACTIVE|SHUTOFF|ERROR|BUILD|...} --name={nome} --server_id={id1,id2}
hcloud ECS ListServersDetails --cli-region={região}
skill-quality-cli run --skill-name huawei-cloud-ecs-manage -- hcloud ECS ListServersDetails --cli-region={região}

huawei_get_ecs_instance — consultar detalhes completos de uma instância (status, endereços, sabor, volumes, falha):

hcloud ECS ShowServer --cli-region={região} --server_id={server_id}
skill-quality-cli run --skill-name huawei-cloud-ecs-manage -- hcloud ECS ShowServer --cli-region={região} --server_id={server_id}

huawei_list_ecs_flavors — listar sabores disponíveis (opcionalmente com escopo para uma AZ):

# Opcional: --availability_zone={az} --flavor_id={flavor_id} --limit={n} --marker={marcador}
hcloud ECS ListFlavors --cli-region={região}
skill-quality-cli run --skill-name huawei-cloud-ecs-manage -- hcloud ECS ListFlavors --cli-region={região}

huawei_list_ecs_images — listar imagens disponíveis (filtrar por tipo de SO / arquitetura / status):

# Opcional: --__os_type={Linux|Windows} --architecture={x86|arm} --status={active} --name={nome} --limit={n}
hcloud IMS ListImages --cli-region={região}
skill-quality-cli run --skill-name huawei-cloud-ecs-manage -- hcloud IMS ListImages --cli-region={região}

huawei_list_ecs_quotas — consultar uso de cota do projeto:

hcloud ECS ShowServerLimits --cli-region={região}
skill-quality-cli run --skill-name huawei-cloud-ecs-manage -- hcloud ECS ShowServerLimits --cli-region={região}

ShowServerLimits retorna limites absolutos e uso (maxTotalInstances/totalInstancesUsed, maxTotalCores/totalCoresUsed, maxTotalRAMSize/totalRamUsed, maxTotalKeypairs). Observe que não tem campo de volume — para cotas de volume de disco, use adicionalmente:

# Obrigatório: --target_project_id={project_id} --usage=True
hcloud EVS CinderListQuotas --target_project_id={project_id} --usage=True --cli-region={região}
skill-quality-cli run --skill-name huawei-cloud-ecs-manage -- hcloud EVS CinderListQuotas --target_project_id={project_id} --usage=True --cli-region={região}

2. Diagnóstico (R3 — somente leitura, execução automática)

huawei_diagnose_ecs_create_failure — diagnóstico de falha de criação em 6 etapas

[truncated for translation]