CDN Origin Server Diagnosis

Overview

This skill is used to diagnose CDN back-to-source failures, origin unreachable errors, and other origin-related issues. It queries the CDN domain's origin configuration (origin address, origin type, back-to-source port, back-to-source protocol) via hcloud CLI, and probes origin server connectivity using the Python probe script (scripts/origin_probe.py), helping users identify the root cause of back-to-source failures, such as abnormal origin server services, closed ports, or CDN back-to-source IP ranges not whitelisted.

Key Features:

• Automatically queries and parses CDN origin configuration (configs.sources)
• Supports connectivity probing for all three back-to-source protocols: http / https / follow
• Parses origin_addr, origin_type, http_port, https_port, origin_protocol
• Structured diagnosis report with IP whitelist prompts and remediation suggestions

Tool: hcloud CLI (KooCLI) + Python probe script (scripts/origin_probe.py) Probe Timeout: 10 seconds Core Principle: Read-only diagnosis; no configuration changes are performed

Scope

What this skill does:

• Query the CDN domain's origin configuration (configs.sources, origin_protocol) via ShowDomainFullConfig/v2
• Probe origin server connectivity (HTTP/HTTPS) using scripts/origin_probe.py
• Generate a structured diagnosis report with IP whitelist prompts and remediation suggestions

What this skill does NOT do:

• Does NOT modify, create, or delete any CDN domain or origin configuration (strictly read-only)
• Does NOT perform cache refresh / preheat operations
• Does NOT manage domain lifecycle (enable/disable), billing mode, or account settings
• Does NOT guarantee origin reachability from CDN edge nodes — the probe reflects the execution environment's network perspective

Use when:

• The user wants to diagnose back-to-source failures, origin unreachable errors, or abnormal origin responses
• The user wants to verify the origin configuration (origin_addr, origin_type, http_port, https_port, origin_protocol) and origin connectivity
• The user is troubleshooting origin 5xx responses, connection timeouts, or TLS handshake failures on the back-to-source path

Triggers

Use this skill when the user input matches any of the following intents:

Trigger keywords: origin diagnosis, origin unreachable, back-to-source failure, back-to-source timeout, origin connectivity, origin configuration check

Near-miss / Do NOT Use

Do NOT use this skill for the following requests — they are out of scope and will be refused:

• ❌ Modifying / creating / deleting CDN domains or origin configuration (configuration changes) → use the CDN console or manual hcloud CLI
• ❌ Cache refresh / preheat (CreateRefreshTasks / CreatePreheatingTasks are prohibited here)
• ❌ Domain lifecycle management (enable/disable), billing mode changes, or account-level operations
• ❌ Querying traffic statistics, cache hit ratios, or access logs (not origin-connectivity diagnosis)
• ❌ Generic network connectivity tests outside the CDN back-to-source path

See references/prohibited-operations.md for the full list of 55 prohibited non-GET operations.

⛔ Prohibited Operations (Security Constraints)

This skill strictly forbids all non-GET (write/modify/delete) CDN operations, regardless of user requests.

Total: 55 prohibited operations (24 POST + 25 PUT + 6 DELETE).

For the complete list of all 55 prohibited non-GET operations with risk descriptions, see references/prohibited-operations.md.

Representative prohibited operations (full list in the reference doc):

If a user requests a prohibited operation, you must refuse and inform: "Per security constraints, this skill does not allow write/delete/modify operations. This skill is for origin connectivity diagnosis only. Please use the Huawei Cloud CDN console or run hcloud CLI manually for configuration changes. The complete list of 55 prohibited operations is documented in references/prohibited-operations.md."

Architecture

CDN Origin Server Diagnosis
├── hcloud configure list                   (credential check)
├── ShowDomainDetailByName                  (domain permission check + basic info)
├── ShowDomainFullConfig/v2                 (origin configuration query)
│   ├── configs.sources empty       → report "origin not configured"
│   └── configs.sources non-empty   → parse origin_addr / origin_type / http_port / https_port / origin_protocol
├── python scripts/origin_probe.py          (origin connectivity probe, JSON output in {result, data, error_msg})
│   ├── origin_protocol=http      → origin_probe.py --scheme http --host <origin_addr> --port <http_port>
│   ├── origin_protocol=https     → origin_probe.py --scheme https --host <origin_addr> --port <https_port>
│   └── origin_protocol=follow    → probe both http and https
└── generate diagnosis report

API Call Budget

Total estimated duration: < 15 seconds

KooCLI Command Format Standard

All hcloud CDN commands follow this standard format:

hcloud CDN <Operation> --cli-region=<region> [--parameter=value ...]

Format Rules:

• Service name: CDN (uppercase)
• Operation name: PascalCase (e.g., ShowDomainDetailByName, ShowDomainFullConfig/v2)
• Region parameter: --cli-region=<region> (recommended; use cn-north-1 for CDN)
• Parameter format: --key=value (equals sign, no space)

Examples:

# Correct
hcloud CDN ShowDomainFullConfig/v2 --cli-region=<region> --domain_name=www.example.com

# Incorrect (space separator)
hcloud CDN ShowDomainFullConfig/v2 --cli-region <region>

Prerequisites

Prerequisite check: Huawei Cloud CLI (hcloud / KooCLI) >= 3.2.0 required Run hcloud version to verify the version. If not installed or the version is too low, see references/cli-installation-guide.md.

hcloud version

Prerequisite check: Python >= 3.8 required Python is used for the origin connectivity probe script (scripts/origin_probe.py).

python --version

Prerequisite check: Python library requests >= 2.25 available The scripts/origin_probe.py probe depends on the requests library.

python -c "import requests; assert requests.__version__ >= '2.25'; print('ok')"

Prerequisite check: hcloud credentials configured

Before performing CDN operations, you must verify that hcloud credentials are configured:

hcloud configure list

If no valid credentials exist, stop and guide the user to configure credentials.

hcloud parameter format requirements

hcloud (KooCLI) all parameters must use the --param=value format (connected with equals sign); space-separated format is not supported.

Correct: hcloud CDN ShowDomainFullConfig/v2 --cli-region=<region>

Incorrect: hcloud CDN ShowDomainFullConfig/v2 --cli-region <region>

CDN API region requirements

CDN APIs only support two regions: cn-north-1 (Beijing) and ap-southeast-1 (Singapore). Query results are region-independent (CDN is a global service). Recommended: use cn-north-1.

Authentication

Prerequisite check: Huawei Cloud credentials required

Security rules (must be followed):

• Prohibited from reading, echoing, or printing AK/SK values

• Prohibited from asking the user to input AK/SK directly in the conversation

• Prohibited from using hcloud configure set to pass plaintext credentials

• Prohibited from accepting AK/SK directly provided by the user in the conversation

• Only allowed to read credentials from environment variables or configured CLI config files

Important: Handling user-provided credentials

If a user attempts to provide AK/SK directly (e.g., "my AK is xxx, SK is yyy"):

• Stop immediately - Do not execute any commands
• Politely refuse and return the following message:

For account security, please do not provide Huawei Cloud Access Key ID and Access Key Secret directly in the conversation.

Please use one of the following secure methods to configure credentials:

Method 1: Interactive configuration (recommended)
    hcloud configure
    # Enter AK/SK as prompted; credentials will be securely stored in a local config file

Method 2: Environment variable configuration
    export HUAWEICLOUD_SDK_AK=<your-access-key-id>
    export HUAWEICLOUD_SDK_SK=<your-secret-key>

After configuration is complete, please retry your request.

• Do not continue executing any Huawei Cloud operations until credentials are configured

Check CLI configuration:

hcloud configure list

Check whether the output contains valid configuration (AK/SK, IAM, etc.).

If no valid credentials exist, stop here.

IAM Permission Policies

Ensure the IAM user has the required permissions. See references/iam-policies.md for details.

Minimum required permissions:

• cdn:*:query* — All CDN query-class actions used by this skill (ListDomains/v2, ShowDomainDetailByName, ShowDomainFullConfig/v2)
• cdn:configuration:queryDomains — List CDN domains (listed explicitly alongside the wildcard)

Core Commands

Quick reference for all hcloud CDN commands and probe commands used in this skill:

Notes:

• All hcloud commands should use --cli-region=<region>
• scripts/origin_probe.py enforces --timeout 10 (10-second timeout, default 10)
• scripts/origin_probe.py emits a single JSON object on stdout wrapped in {result, data, error_msg} (fields inside data: scheme, host, port, connected, http_status, is_private_address, duration_ms, error)
• The probe protocol is selected based on origin_protocol (http / https / follow)

Parameter Confirmation

Before executing the diagnosis, confirm the following parameters with the user:

User Confirmation Checklist:

• Target domain provided
• User understands this is a read-only diagnosis operation
• User understands that probe commands have a 10-second timeout
• User understands that probes send HTTP/HTTPS requests to the origin server (HEAD preferred, GET fallback on 405; read-only, no side effects)

Core Workflows

Target domain is required before any diagnosis step.

• If the user did not provide a target domain, ask the user for the domain name and wait for the reply before starting.
• Only if the user does not know the domain or asks you to look it up, list the account's domains via hcloud CDN ListDomains/v2 and ask the user to choose one.
• Never start the diagnosis without an explicit user-provided domain: do not guess a domain, do not fall back to an example/default domain, and do not pick a domain from the list yourself.

Step 1: Credential Check and Domain Permission Validation

Check hcloud credential availability, and validate that the domain belongs to the current account via ShowDomainDetailByName.

Detailed steps → references/task-permission-check.md

Step 2: Query Origin Configuration

Retrieve the CDN domain's origin configuration (configs.sources, origin_protocol) via ShowDomainFullConfig/v2.

Detailed steps → references/task-origin-config-query.md

Step 3: Origin Connectivity Probe

Select the probe protocol based on origin_protocol, and probe origin server connectivity via scripts/origin_probe.py, parsing the JSON output inside the {result, data, error_msg} envelope (data.http_status, data.connected, data.is_private_address, data.error).

Detailed steps → references/task-origin-probe.md

Step 4: Generate Diagnosis Report

Aggregate probe results and generate a structured text diagnosis report with IP whitelist prompts and remediation suggestions.

Detailed steps → references/task-report-generation.md

FAQ

Q1: What should I do when "Credentials not configured" is reported? A: Run hcloud configure to configure AK/SK interactively, or set the environment variables HUAWEICLOUD_SDK_AK / HUAWEICLOUD_SDK_SK, then verify with hcloud configure list.

Q2: ShowDomainDetailByName returns 404 / CDN.0171? A: The domain does not exist or does not belong to the current account. Check the domain spelling and account ownership; use hcloud CDN ListDomains/v2 --cli-region=<region> --page_size=100 to list onboarded domains.

Q3: 403 insufficient permissions? A: Ensure the IAM user has the CDN query permission (cdn:*:query*, plus cdn:configuration:queryDomains); contact the primary account administrator to grant them. See references/iam-policies.md for details.

Q4: Probe timeout (error.reason=connect_timeout)? A: Return partial results and note "Origin probe timed out. Manual verification recommended."; check local network connectivity, the origin address/port, and whether the origin firewall allows CDN back-to-source IP ranges.

Q5: connect_failed / tls_handshake_failed? A: connect_failed = connection refused / network unreachable / DNS resolution failure; tls_handshake_failed = TCP reachable but HTTPS certificate abnormal (the script never bypasses certificate validation). Both are handled as "origin unreachable" with an IP whitelist prompt.

Q6: missing_library? A: The requests library is missing; install requests>=2.25 following references/cli-installation-guide.md and retry.

Q7: Origin configuration query shows empty sources? A: Report "Origin not configured", skip the probe step, and prompt the user to configure the origin in the CDN console.

Known Limitations:

• CDN APIs only support two regions: cn-north-1 and ap-southeast-1
• Probe results reflect the execution environment's network perspective only, not the CDN edge node's back-to-source path
• With origin_protocol=follow, both http and https must be probed

Error Code Quick Reference:

See references/troubleshooting.md for the full troubleshooting guide.

Failure Modes

Known failure modes and recovery:

Self-check before output: Before emitting the diagnosis report, verify it contains the 6 mandatory blocks (analysis time / target domain / origin configuration / diagnosis items / conclusion / remediation suggestion); complete any missing block before output (see references/acceptance-criteria.md).

Failure propagation: When any preceding step (Step 1-3) fails and aborts, mark subsequent steps as N/A (do not execute), set the report Conclusion status to "Cannot Diagnose", and provide a clear next action (authorization / credential configuration / manual verification, etc.).

Output Format

Probe JSON output (scripts/origin_probe.py): A single JSON object on stdout, wrapped in the {result, data, error_msg} envelope; business fields are inside data:

Status enums:

• result ∈ {success, failed}
• data.error.reason ∈ {connect_timeout, connect_failed, tls_handshake_failed, missing_library, invalid_scheme, invalid_host, invalid_port, invalid_timeout}
• Report Status ∈ {Pass, Fail, Partial Pass, Cannot Diagnose}
• Diagnosis item markers ∈ {✅ Pass, ❌ Fail, ⚠️ Warning, N/A}

Diagnosis report template: The full template (separator line ====, section headers --- xxx ---, diagnosis item list, conclusion and remediation suggestion, IP whitelist prompt rules) and example reports are defined in references/task-report-generation.md.

Prohibited content: The report and any output must NEVER include AK/SK, account credentials, or other sensitive information; must NOT fabricate probe data — reflect the data.* fields truthfully.

References

Changelog