Huawei Cloud SWR Image Management#

Overview#

This skill provides lifecycle management capabilities for Huawei Cloud SWR (Software Repository for Container) images using the hcloud CLI.

Architecture: hcloud CLI → SWR Service API → Namespace/Repository/Tag/Auth/Quota resources

Related Skills:

• huawei-cloud-swr-image-governance - Image governance (permissions, retention, sharing, tags, immutable rules)

• huawei-cloud-swr-image-automation - Image automation ops (sync, triggers, domains)

• huawei-cloud-swr-enterprise-instance - Enterprise instance management

• Create and manage SWR namespaces (organizations)

• Create and manage image repositories with public/private settings

• Query and manage image tags/versions

• Obtain docker login credentials (temporary and long-term)

• Check SWR resource quotas

Typical Use Cases:

• "Create a SWR namespace for my project"
• "List all image repositories in namespace 'group-dev'"
• "Query image tags for repository 'nginx' in namespace 'group-dev'"
• "Get docker login command for SWR"
• "Delete an old image tag to clean up storage"
• "Check my SWR quota usage"
• "Create a private repository for my custom image"
• "Update repository description and visibility"

Prerequisites#

1. hcloud CLI Requirements (MANDATORY)#

• hcloud CLI installed (version >= 7.2.2)
• Run hcloud version to verify installation
• First-time usage: printf "y\n" | hcloud version to accept privacy statement

2. Credential Configuration#

• Valid Huawei Cloud credentials (AK/SK mode)

• Security Rules:

  • 🚫 Never expose AK/SK values in code, conversation, or commands
  • 🚫 Never use echo $HUAWEI_CLOUD_AK or echo $HUAWEI_CLOUD_SK to check credentials
  • ✅ Use environment variables: HUAWEI_CLOUD_AK, HUAWEI_CLOUD_SK, HUAWEI_CLOUD_REGION
  • ✅ Prefer IAM users over root account for cloud operations
  • ✅ Enable MFA for sensitive operations

Configuration Method (Environment Variables Only):

bash

export HUAWEI_CLOUD_AK=<your-ak>
export HUAWEI_CLOUD_SK=<your-sk>
export HUAWEI_CLOUD_REGION=cn-north-4

⚠️ Important Security Notes:

• Never commit credentials to version control
• Use IAM users with minimal required permissions
• Enable MFA for sensitive operations
• Rotate AK/SK regularly

3. IAM Permission Requirements#

API ActionPermissionPurposeswr:namespace:createCreate namespaceCreate SWR organizationsswr:namespace:listList namespacesQuery all namespacesswr:namespace:getGet namespaceView individual namespace informationswr:namespace:deleteDelete namespaceRemove organizationsswr:repository:createCreate repoCreate image repositoriesswr:repository:listList reposQuery image repositoriesswr:repository:getGet repoView repository detailsswr:repository:updateUpdate repoModify repository propertiesswr:repository:deleteDelete repoRemove image repositoriesswr:tag:listList tagsQuery image tags/versionsswr:tag:getGet tagView specific tag detailsswr:tag:createCreate tagCreate image tagswr:tag:deleteDelete tagRemove image tagswr:login:getGet login tokenObtain docker login credentialsswr:quota:getGet quotaCheck resource quotas

See IAM Permission Policies for complete policy JSON.

Permission Failure Handling:

1. When any command fails due to permission errors, read references/iam-policies.md
2. Display the required permission list and policy JSON to the user
3. Guide the user to create a custom policy in the IAM console and grant authorization
4. Pause execution and wait for user confirmation that permissions have been granted

Core Commands#

1. Namespace (Organization) Management#

See Task: Namespace Management for detailed workflows.

bash

# List all namespaces
hcloud SWR ListNamespaces --cli-region=cn-north-4

# List namespaces with filter
hcloud SWR ListNamespaces --filter="namespace::group-dev|mode::visible" --cli-region=cn-north-4

# Show namespace details
hcloud SWR ShowNamespace --namespace=group-dev --cli-region=cn-north-4

# Create a namespace
hcloud SWR CreateNamespace --namespace=group-dev --cli-region=cn-north-4

# Delete a namespace (CAUTION: removes all repos under it)
hcloud SWR DeleteNamespaces --namespace=group-dev --cli-region=cn-north-4

Namespace Naming Rules:

• Start with lowercase letter
• Followed by lowercase letters, digits, dots, underscores, or hyphens
• Max 2 consecutive underscores
• Dots, underscores, hyphens cannot be directly connected
• End with lowercase letter or digit
• Length: 1-64 characters

2. Repository (Image Repository) Management#

See Task: Repository Management for detailed workflows.

bash

# List all repositories
hcloud SWR ListReposDetails --cli-region=cn-north-4

# List repositories in a namespace
hcloud SWR ListReposDetails --namespace=group-dev --cli-region=cn-north-4

# List repositories with pagination and sorting
hcloud SWR ListReposDetails --namespace=group-dev --limit=20 --offset=0 --order_column=updated_at --order_type=desc --cli-region=cn-north-4

# List repositories by category
hcloud SWR ListReposDetails --category=database --cli-region=cn-north-4

# Show repository details
hcloud SWR ShowRepository --namespace=group-dev --repository=nginx --cli-region=cn-north-4

# Create a repository
hcloud SWR CreateRepo --namespace=group-dev --repository=my-app --is_public=false --category=other --description="Custom app image" --cli-region=cn-north-4

# Update repository (change visibility, description, category)
hcloud SWR UpdateRepo --namespace=group-dev --repository=my-app --is_public=true --description="Updated description" --cli-region=cn-north-4

# Delete a repository (CAUTION: removes all image tags)
hcloud SWR DeleteRepo --namespace=group-dev --repository=my-app --cli-region=cn-north-4

Repository Naming Rules:

• Start with lowercase letter or digit
• Followed by lowercase letters, digits, dots, slashes, underscores, or hyphens
• Max 2 consecutive underscores
• Dots, slashes, underscores, hyphens cannot be directly connected
• End with lowercase letter or digit
• Length: 1-128 characters

Repository Categories: app_server, linux, framework_app, database, lang, other, windows, arm

3. Image Tag (Version) Management#

See Task: Tag Management for detailed workflows.

bash

# List all tags in a repository
hcloud SWR ListRepositoryTags --namespace=group-dev --repository=nginx --cli-region=cn-north-4

# List tags with pagination and sorting
hcloud SWR ListRepositoryTags --namespace=group-dev --repository=nginx --limit=50 --offset=0 --order_column=updated_at --order_type=desc --cli-region=cn-north-4

# Search for a specific tag
hcloud SWR ListRepositoryTags --namespace=group-dev --repository=nginx --filter="tag::v1.0" --cli-region=cn-north-4

# Show tag details (image digest, size, create time)
hcloud SWR ShowRepoTag --namespace=group-dev --repository=nginx --tag=v1.0 --cli-region=cn-north-4

# Create a tag (retag existing image)
hcloud SWR CreateRepoTag --namespace=group-dev --repository=nginx --source_tag=v1.0 --destination_tag=v1.0-stable --override=false --cli-region=cn-north-4

# Delete a tag (CAUTION: removes the image version permanently)
hcloud SWR DeleteRepoTag --namespace=group-dev --repository=nginx --tag=v1.0-old --cli-region=cn-north-4

4. Docker Login & Authentication#

See Task: Auth Management for detailed workflows.

bash

# Get temporary docker login credentials (valid for 12 hours)
hcloud SWR CreateAuthorizationToken --cli-region=cn-north-4

# Get long-term docker login credentials (valid for 1 year)
hcloud SWR CreateSecret --cli-region=cn-north-4

Response Format (verified against actual API):

The response returns a Docker auth config object:

json

{
  "auths": {
    "swr.cn-north-4.myhuaweicloud.com": {
      "auth": "base64-encoded-auth-token"
    }
  }
}

• auths: Docker config auth object, registry host as key
• auth: Base64-encoded username:password string

Docker Login Command:

bash

# Decode auth field: echo <auth_value> | base64 -d → username:password
docker login -u <decoded_username> -p <decoded_password> swr.cn-north-4.myhuaweicloud.com

5. Quota Management#

See Task: Quota Management for detailed workflows.

bash

# Check SWR quotas
hcloud SWR ListQuotas --cli-region=cn-north-4

Parameter Reference#

Common Parameters#

ParameterRequired/OptionalDescriptionDefault--cli-regionRequiredHuawei Cloud region IDConfig value or HUAWEI_CLOUD_REGION``--namespaceContext-dependentSWR namespace (organization)N/A--repositoryContext-dependentImage repository nameN/A--tagContext-dependentImage tag/version nameN/A

Namespace Parameters#

ParameterRequiredDescriptionConstraints--namespaceYesNamespace name1-64 chars, lowercase start, specific rules--filterNoFilter by name/mode`namespace::{name}

Repository Parameters#

ParameterRequiredDescriptionConstraints--namespaceYesNamespace nameSee naming rules--repositoryYesRepository nameSee naming rules--is_publicYesPublic/privatetrue or false``--categoryNoRepository categorySee category list--descriptionNoRepository descriptionFree text--limitNoPage sizeMax 1000, default 100--offsetNoPage offsetMust pair with --limit``--order_columnNoSort columnname, updated_time, tag_count (note: tag_count is the param value even though response field is num_images)--order_typeNoSort directiondesc (descending), asc (ascending)--nameNoSearch by name (fuzzy)Partial match

Tag Parameters#

ParameterRequiredDescriptionConstraints--namespaceYesNamespace nameSee naming rules--repositoryYesRepository nameSee naming rules--tagYesTag/version nameFree text--source_tagYesSource tag (for create)Existing tag name--destination_tagYesTarget tag (for create)New tag name--overrideNoOverwrite existing tagtrue or false

Output Format#

Namespace List#

json

{
  "namespaces": [
    {
      "id": 3827347,
      "name": "group-dev",
      "creator_name": "user-name",
      "auth": 7,
      "access_user_count": 1,
      "repo_count": 2
    }
  ]
}

Repository List#

Response is a flat JSON array (not wrapped in an object):

json

[
  {
    "name": "nginx",
    "category": "app_server",
    "description": "Nginx web server",
    "size": 268435456,
    "is_public": true,
    "num_images": 5,
    "num_download": 120,
    "path": "swr.cn-north-4.myhuaweicloud.com/group-dev/nginx",
    "internal_path": "swr.cn-north-4.myhuaweicloud.com/group-dev/nginx",
    "namespace": "group-dev",
    "domain_name": "user-name",
    "tags": ["v1.0", "v1.1", "latest"],
    "created_at": "2026-04-15T10:30:00Z",
    "updated_at": "2026-05-20T14:20:00Z",
    "logo": "",
    "url": "",
    "status": false,
    "total_range": 2
  }
]

Note: num_images is the tag count (not tag_count). tags is an array of tag name strings included directly in the repository listing.

Tag List#

Response is a flat JSON array (not wrapped in an object):

json

[
  {
    "id": 32962315,
    "repo_id": 3374895,
    "Tag": "v1.0",
    "image_id": "f47c82866a20...",
    "digest": "sha256:c8cede14b121...",
    "schema": 2,
    "size": 134217728,
    "path": "swr.cn-north-4.myhuaweicloud.com/group-dev/nginx:v1.0",
    "internal_path": "swr.cn-north-4.myhuaweicloud.com/group-dev/nginx:v1.0",
    "is_trusted": false,
    "created": "2026-04-15T10:30:00Z",
    "updated": "2026-05-20T14:20:00Z",
    "domain_id": "xxx",
    "scanned": false,
    "tag_type": 0
  }
]

Note: Tag name field is Tag (capital T), timestamps use created/ updated (not created_at/ updated_at).

Show Repository Details#

json

{
  "id": 3374887,
  "ns_id": 3827347,
  "name": "nginx",
  "category": "other",
  "creator_id": "05949eb5...",
  "creator_name": "user-name",
  "num_images": 17,
  "num_download": 35,
  "is_public": false,
  "path": "swr.cn-north-4.myhuaweicloud.com/group-dev/nginx",
  "created": "2026-03-26T07:42:40Z",
  "updated": "2026-05-06T09:22:11Z",
  "domain_id": "05949eb4...",
  "priority": 0
}

Note: ShowRepository uses created/ updated and num_images — different from ListReposDetails which uses created_at/ updated_at.

Auth Token Response#

json

{
  "auths": {
    "swr.cn-north-4.myhuaweicloud.com": {
      "auth": "base64-encoded-username:password"
    }
  }
}

Note: The auth field is base64-encoded. Decode it to get docker login credentials. This is a Docker config format, NOT a header+body response.

Quota List#

json

{
  "quotas": [
    {
      "quota_key": "namespace",
      "quota_limit": 5,
      "used": 1,
      "unit": ""
    }
  ]
}

Note: Quotas are returned as an array of objects with quota_key/ quota_limit/ used/ unit fields, not flat key-value pairs like namespace_limit/ namespace_used.

Verification#

See Verification Method for step-by-step verification.

Common Region IDs#

Region NameRegion IDNorth China - Beijing 4cn-north-4North China - Beijing 1cn-north-1East China - Shanghai 1cn-east-3East China - Shanghai 2cn-east-2South China - Guangzhoucn-south-1South China - Shenzhencn-south-4Southwest China - Guiyang 1cn-southwest-2Asia Pacific - Bangkokap-southeast-2Asia Pacific - Singaporeap-southeast-1Asia Pacific - Hong Kongap-southeast-3Europe - Pariseu-west-0

Best Practices#

1. Namespace Organization: Use descriptive namespace names following team/project naming (e.g., team-backend, proj-ai)
2. Repository Visibility: Set is_public=false for internal images; only set is_public=true for images intended for public sharing
3. Tag Naming Convention: Use semantic versioning (e.g., v1.0, v1.0-stable, latest) and avoid ambiguous tags
4. Regular Cleanup: Periodically delete outdated tags to manage storage quotas
5. Retag Instead of Re-push: Use CreateRepoTag to create version aliases rather than pushing the same image multiple times
6. Long-term Login for CI/CD: Use CreateSecret for automation pipelines; use CreateAuthorizationToken for temporary access
7. Delete with Caution: Deleting a namespace removes ALL repositories under it; deleting a repository removes ALL tags

Reference Documents#

DocumentDescriptionSWR API Guidehcloud SWR API referenceIAM Permission PoliciesRequired permissions and policy JSONVerification MethodStep-by-step verificationCommon PitfallsTroubleshooting guidesTask: Namespace ManagementNamespace workflowsTask: Repository ManagementRepository workflowsTask: Tag ManagementTag workflowsTask: Auth ManagementLogin credential workflowsTask: Quota ManagementQuota check workflows

Notes#

• Namespace deletion is irreversible — removes all repositories and images under it
• Repository deletion is irreversible — removes all image tags permanently
• Tag deletion is irreversible — the image version cannot be recovered
• AK/SK must never be hardcoded — credentials should only be obtained via environment variables
• hcloud CLI is the only supported method — all operations use hcloud SWR <Operation> format
• Pagination required for large datasets — use --limit and --offset for repositories and tags listing

Common Pitfalls#

See Common Pitfalls & Solutions for detailed troubleshooting guides.

Quick Reference:

PitfallSymptomQuick FixInvalid namespace name400 Bad RequestFollow naming rules: lowercase, 1-64 charsNamespace not found404 Not FoundVerify namespace exists with ShowNamespaceRepo already exists409 ConflictUse ShowRepository to check firstTag digest mismatchRetag failsVerify source_tag exists with ShowRepoTagQuota exceeded403 Quota limitCheck quotas with ListQuotasAuth token expiredDocker login failsRegenerate with CreateAuthorizationToken``Tag field nameTag query returns unexpected structureUse Tag (capital T) not name``num_images not tag_countRepo listing field mismatchResponse uses num_images; --order_column uses tag_count