huaweicloud/huawei-cloud-obs-website-host

Alojamiento web en OBS de Huawei Cloud

Descripción general

Configura un bucket OBS existente de Huawei Cloud para alojamiento de sitios web estáticos con el SDK de Python de OBS de Huawei Cloud y registra un dominio personalizado para el sitio.

Usa esta habilidad cuando el usuario quiera:

• Habilitar o reparar el alojamiento web estático de OBS
• Establecer un documento de índice o documento de error
• Hacer que el sitio sea accesible a través de un dominio personalizado respaldado por el endpoint del sitio web estático de OBS
• Agregar o reparar un dominio personalizado, incluido DNS de Huawei Cloud cuando sea aplicable
• Diagnosticar errores 403, 404 o problemas de DNS en un sitio alojado en OBS

Cómo se ve un buen resultado

Esta habilidad realiza operaciones de escritura: habilita el alojamiento web estático en un bucket (setBucketWebsite) y registra el dominio personalizado requerido en ese bucket (setBucketCustomDomain). Cuando el usuario lo solicita, también crea/actualiza registros DNS. Estas escrituras son ejecutadas por los scripts incluidos en la propia sesión de esta habilidad; no se simulan, no se difieren al usuario ni se reemplazan con comprobaciones de solo lectura. La verificación se ejecuta después de las escrituras para confirmar el resultado.

• El bucket tiene el alojamiento web estático habilitado por esta habilidad.
• El bucket puede servir index.html desde el endpoint del sitio web.
• Los usuarios anónimos pueden leer el contenido del sitio web.
• Una ruta faltante devuelve la página de error configurada o un 404 limpio.
• Un dominio personalizado está registrado por esta habilidad y se resuelve al endpoint del sitio web de OBS a través de DNS. Un dominio personalizado es obligatorio: el dominio predeterminado del bucket de OBS no está permitido para la vista previa en línea de objetos según los requisitos de cumplimiento de seguridad.
• La configuración no se considera completa hasta que el dominio personalizado esté registrado en el bucket y se resuelva correctamente.
• Se utiliza el endpoint del sitio web de OBS, no el endpoint normal de la API del bucket.
• Un error 403 generalmente tiene dos causas comunes: la lectura anónima/pública no está habilitada en el bucket o los objetos, o la AK/SK utilizada para las operaciones de OBS carece de los permisos IAM necesarios.
• Un error 404 generalmente significa que el nombre del documento de índice o la ruta de carga son incorrectos.

Cumplimiento de seguridad: requisito de dominio personalizado

Según los requisitos de cumplimiento de seguridad de Huawei Cloud, el nombre de dominio predeterminado del bucket de OBS (<nombre_bucket>.obs.<región>.myhuaweicloud.com) está prohibido para la vista previa en línea de objetos dentro del bucket. Por lo tanto, un dominio personalizado es obligatorio para el alojamiento web estático.

Si el usuario no tiene un dominio personalizado preparado:

1. Primero pregunte al usuario dónde se implementará el sitio web (región/jurisdicción de implementación) y dónde se registrará el dominio. Solo aplique requisitos específicos de la región (como el registro ICP) cuando la región de implementación realmente los exija.
2. Dirija al usuario a registrar un dominio a través del Servicio de registro de dominio de Huawei Cloud u otros sitios comunes de registro de dominio.
3. Si (y solo si) la región de implementación del usuario es China continental, el dominio también debe completar el registro ICP (网站备案) antes de que pueda usarse para el alojamiento web. Para implementaciones fuera de China continental, este paso no es necesario: no lo imponga.
4. Solo después de verificar la región y, cuando corresponda, confirmar el registro/declaración del dominio, se debe continuar con la configuración del alojamiento web estático.

Importante: No continúe con la configuración del alojamiento web estático hasta que se confirme el requisito previo del dominio personalizado. El dominio predeterminado de OBS no es una alternativa válida para el acceso al sitio web, ni siquiera en el entorno de prueba.

Entradas requeridas

Recoja estas antes de realizar cambios:

• region
• bucket_name
• custom_domain (obligatorio: consulte la sección de Cumplimiento de seguridad anterior)
• index_document (opcional, valor predeterminado: index.html)
• error_document (opcional)
• dns_zone o contexto de cuenta DNS (opcional; solo se requiere si el usuario desea cambios en Huawei Cloud DNS en esta ejecución)

Suponga que los archivos del sitio web estático ya han sido cargados por el usuario.

Dependencias

La habilidad depende de los siguientes componentes de tiempo de ejecución/herramientas:

• Python 3.10+ (necesario para scripts/set_obs_website_sdk.py y scripts/verify_obs_website.py)
• Paquete SDK de OBS de Python de Huawei: esdk-obs-python
• obsutil (para generar y mantener la configuración de credenciales .obsutilconfig)
• Credenciales AK/SK de Huawei Cloud (de .obsutilconfig)
• Acceso de red al endpoint de OBS y al endpoint del sitio web
• CLI hcloud (solo se requiere cuando esta habilidad gestiona operaciones de registros DNS de Huawei Cloud)
• dig / nslookup (opcional)

Comando de instalación:

pip install esdk-obs-python

Ámbito de capacidad y permisos

Esta habilidad declara su capacidad exacta y su ámbito de permisos para que los llamadores y revisores sepan lo que puede y no puede hacer antes de invocarla:

Lo que puede escribir (modificar):

• La configuración del sitio web del bucket OBS especificado por el usuario únicamente (setBucketWebsite: documento de índice, documento de error), a través de scripts/set_obs_website_sdk.py.
• La vinculación del dominio personalizado en ese mismo bucket (setBucketCustomDomain), incluida la vinculación opcional de un certificado HTTPS.
• Registros DNS en una zona DNS de Huawei Cloud solo cuando el usuario solicita explícitamente cambios en Huawei Cloud DNS en esta ejecución y proporciona/especifica la zona (hcloud DNS CreateRecordSet).
• Estos son cambios orientados a la producción: pueden afectar el tráfico web en vivo para el dominio personalizado y hacer que el contenido del bucket sea accesible públicamente. Se dan advertencias antes de cada escritura (consulte el Flujo de trabajo).

Lectura de credenciales (y sus fuentes):

• scripts/set_obs_website_sdk.py y scripts/verify_obs_website.py leen las credenciales de, en orden de prioridad: (1) banderas de CLI --access-key/--secret-key/--security-token, (2) variables de entorno HW_ACCESS_KEY / HW_SECRET_KEY / HW_SECURITY_TOKEN, (3) archivo local ~/.obsutilconfig. hcloud utiliza su propio perfil CLI configurado para las operaciones de DNS.
• Solo se informa la presencia de credenciales; los valores nunca se imprimen, repiten ni escriben en el disco.

Acceso de red:

• Solo al endpoint del servicio de OBS (https://obs.<región>.myhuaweicloud.com), al endpoint del sitio web de OBS y (solo si se solicita) al servicio DNS de Huawei Cloud de la región configurada.

Lo que nunca hace:

• Nunca carga, elimina ni modifica objetos/contenido dentro del bucket.
• Nunca toca buckets, dominios, zonas DNS o credenciales que no sean los especificados por el usuario.
• Nunca crea trabajos cron, scripts de inicio o archivos de estado, y nunca persiste nada entre sesiones (consulte "Comportamiento de la sesión" a continuación).
• Nunca expone ni reenvía las credenciales que lee a terceros.

Comportamiento de la sesión

Esta habilidad realiza una operación de una sola sesión y única: ejecuta las llamadas API de OBS/DNS solicitadas durante la ejecución actual y luego finaliza. No crea trabajos cron, inicia scripts, demonios en segundo plano ni archivos de estado, y no persiste la configuración para ejecuciones posteriores. Cada invocación es independiente y debe ser activada por el usuario; nada se programa ni se repite automáticamente. Cualquier paso de larga duración o programado externamente (por ejemplo, esperar la propagación de DNS) se describe al usuario como algo que debe verificar, no se instala como un trabajo realizado por esta habilidad.

Divulgación y confirmación de credenciales

Debido a que scripts/set_obs_website_sdk.py lee las credenciales de la nube de su entorno o de ~/.obsutilconfig local y luego cambia la configuración remota del bucket/DNS, ejecutarlo tiene un impacto real en la seguridad. Antes de ejecutarlo, debe:

1. Informar al usuario de que el script leerá las credenciales de sus banderas de CLI / variables de entorno / ~/.obsutilconfig y modificará la configuración del sitio web del bucket remoto y el dominio personalizado (y DNS, si se solicita).
2. Obtener la confirmación del usuario de que el nombre del bucket, el dominio personalizado y la zona DNS (si la hay) son correctos y que autoriza el cambio.
3. Solo después de esa confirmación, ejecutar el script.

Referencia de CLI hcloud

Cargue references/cli-installation-guide.md cuando se necesite la instalación y configuración de la CLI hcloud u obsutil. Cargue references/hcloud-dns-obs-website.md al crear o gestionar registros DNS CNAME para dominios personalizados de sitios web estáticos de OBS (guía paso a paso con comandos hcloud DNS CreateRecordSet).

Nota de seguridad:

• Nunca codifique AK/SK en scripts o archivos verificados en el repositorio.
• Prefiera variables de entorno para los scripts del SDK y almacenamiento de perfil local seguro para el uso de la CLI.

Dependencia de configuración de obsutil

Cargue references/cli-installation-guide.md cuando necesite orientación sobre la instalación de obsutil o la configuración de .obsutilconfig.

El script auxiliar del SDK de Python (scripts/set_obs_website_sdk.py) lee las credenciales de forma predeterminada desde:

1. Banderas de CLI (--access-key, --secret-key, --security-token)
2. Variables de entorno (HW_ACCESS_KEY, HW_SECRET_KEY, HW_SECURITY_TOKEN)
3. .obsutilconfig

Si ak/sk están vacíos en todas las fuentes, el script debe detenerse y pedir al usuario que complete las claves faltantes en .obsutilconfig (o proporcione credenciales de CLI/env).

Regla de verificación de credenciales:

• Solo informe la presencia/ausencia de claves (ak, sk, securitytoken).
• Nunca imprima los valores de las credenciales durante las comprobaciones.
• Nunca imprima líneas completas de .obsutilconfig en la consola.
• Trate la salida de la consola como contexto del modelo; cualquier valor filtrado es un incidente de seguridad.

Ejemplos de verificación segura (solo estado, sin valores secretos):

Linux/macOS:

CFG="${HOME}/.obsutilconfig"
if [ ! -f "$CFG" ]; then
  echo "obsutilconfig_exists=false"
  echo "ak_configured=false"
  echo "sk_configured=false"
  echo "securitytoken_configured=false"
else
  awk -F= '
    BEGIN { ak=0; sk=0; st=0 }
    /^[[:space:]]*#/ { next }
    /^[[:space:]]*(ak|access_key_id)[[:space:]]*=/ { if ($2 ~ /[^[:space:]]/) ak=1 }
    /^[[:space:]]*(sk|secret_access_key)[[:space:]]*=/ { if ($2 ~ /[^[:space:]]/) sk=1 }
    /^[[:space:]]*(securitytoken|security_token|token)[[:space:]]*=/ { if ($2 ~ /[^[:space:]]/) st=1 }
    END {
      print "obsutilconfig_exists=true"
      print "ak_configured=" (ak ? "true" : "false")
      print "sk_configured=" (sk ? "true" : "false")
      print "securitytoken_configured=" (st ? "true" : "false")
    }
  ' "$CFG"
fi

Windows (PowerShell):

$cfg = Join-Path $HOME ".obsutilconfig"
if (-not (Test-Path $cfg)) {
  "obsutilconfig_exists=false"
  "ak_configured=false"
  "sk_configured=false"
  "securitytoken_configured=false"
} else {
  $lines = Get-Content $cfg
  $ak = $false; $sk = $false; $st = $false
  foreach ($line in $lines) {
    if ($line -match '^\s*#') { continue }
    if ($line -match '^\s*(ak|access_key_id)\s*=\s*(\S.*)$') { $ak = $true }
    if ($line -match '^\s*(sk|secret_access_key)\s*=\s*(\S.*)$') { $sk = $true }
    if ($line -match '^\s*(securitytoken|security_token|token)\s*=\s*(\S.*)$') { $st = $true }
  }
  "obsutilconfig_exists=true"
  "ak_configured=$ak"
  "sk_configured=$sk"
  "securitytoken_configured=$st"
}

No utilice:

• cat ~/.obsutilconfig
• grep -E "ak|sk|token" ~/.obsutilconfig

Intención de uso del script

Utilice los scripts incluidos de forma predeterminada para las tareas para las que fueron creados. Estos scripts realizan las operaciones de escritura que esta habilidad promociona; no son verificadores de solo lectura:

• scripts/set_obs_website_sdk.py escribe la configuración del sitio web del bucket (setBucketWebsite) y registra el dominio personalizado (setBucketCustomDomain) en el bucket especificado. Úselo siempre que la tarea sea habilitar, reparar o cambiar la configuración de alojamiento web estático de OBS. Lee las credenciales según lo declarado en Ámbito de capacidad y permisos y requiere la confirmación del usuario antes de escribir (consulte Divulgación y confirmación de credenciales).
• scripts/verify_obs_website.py verifica el endpoint del sitio web publicado (DNS, HTTP, HTTPS) y ejecuta comprobaciones de solo lectura del SDK del bucket/región. Úselo después de cualquier cambio en la configuración del sitio web, y también cuando el usuario pregunte si el sitio es accesible o al solucionar problemas de comportamiento 403/404.
• No reemplace estos scripts con código ad hoc de una sola vez a menos que el script en sí esté roto y deba parchearse; parchear un script roto es el único caso en el que escribe llamadas directas al SDK de OBS.
• Use los scripts para mantener el manejo de credenciales, la construcción de objetos del SDK y el comportamiento de verificación consistentes entre ejecuciones.

Flujo de trabajo

1. Verifique que el runtime de Python y el SDK de OBS estén disponibles (pip install esdk-obs-python si falta).
2. Verifique el requisito previo del dominio personalizado (consulte la sección Cumplimiento de seguridad):
   • Confirme que el usuario ha proporcionado custom_domain.
   • Pregunte al usuario dónde se implementará el sitio (región/jurisdicción) antes de aplicar cualquier requisito específico de la región. Si el usuario no tiene un dominio y la región de implementación es China continental, guíelo para que registre uno en Registro de dominio de Huawei Cloud y complete el registro ICP (网站备案). Para implementaciones fuera de China continental, no imponga el registro ICP. Deténgase aquí y espere a que el usuario complete este paso.
   • Verifique si el usuario gestiona el DNS en Huawei Cloud DNS o con un proveedor externo.
   • Si los cambios en Huawei Cloud DNS son parte de esta ejecución, verifique que hcloud esté instalado y autenticado.
   • Si el DNS se gestiona fuera de Huawei Cloud o fuera de esta ejecución, recoja esa restricción explícitamente antes de continuar.
3. Verifique que el bucket exista en la región solicitada (use el Método de verificación de existencia y región del bucket a continuación).
4. Verifique que el llamador tenga permiso para actualizar la configuración del sitio web del bucket.
5. Verifique que la lectura anónima esté permitida para los archivos del sitio web (use el método en Método de verificación de lectura anónima a continuación).
6. No cargue ni modifique objetos de contenido del sitio web (index.html, activos, etc.). Suponga que el contenido ya existe en el bucket.
7. Confirme antes de escribir. Informe al usuario de que el siguiente paso lee sus credenciales de la nube (variables de env / ~/.obsutilconfig) y modifica la configuración del sitio web del bucket remoto y la vinculación del dominio personalizado (y DNS si se solicita), y que estos son cambios orientados a la producción que afectan al tráfico en vivo. Solo después de la confirmación, proceda. Luego ejecute scripts/set_obs_website_sdk.py con --custom-domain <dominio> (use index.html si no se proporciona index_document).