AWS Agent Registry: błędy po wycofaniu namespace bedrock-agentcore i migracja na agent-registry

Ten runbook dotyczy migracji namespace AWS Agent Registry. Gdzie rejestr mieści się w szerszej platformie, opisaliśmy w artykule Amazon Bedrock AgentCore: architektura i cennik. W sprawie zaplanowania migracji rejestru bez przestoju umów konsultację.

Objawy

Błąd pojawia się w kodzie, który do niedawna działał bez zmian, a sam rejestr nie zgłasza awarii.

# Wywołania do starego namespace zaczynają zawodzić
AccessDeniedException / ResourceNotFoundException
# ...przy operacjach, które wcześniej się udawały na "bedrock-agentcore"

# Albo odmowa po stronie IAM, bo polityka wskazuje stary namespace
User: arn:aws:sts::...:assumed-role/... is not authorized to perform:
agent-registry:<Action> because no identity-based policy allows it

Widoczny wpływ:

• Operacje na rejestrze (publikacja, wyszukiwanie, odczyt rekordów) nagle zwracają błąd mimo niezmienionego kodu
• Polityki IAM nadal zezwalają na akcje w starym namespace, więc nowe wywołania są odrzucane
• Skrypty CLI i klienci SDK wskazujący stary endpoint przestają działać
• Rekordy rejestru utworzone w preview nie są widoczne przez nowy namespace, dopóki ich nie przeniesiesz

Przyczyna

AWS Agent Registry wystartował publicznie pod nowym namespace agent-registry. Usługa, która wcześniej działała w ramach preview pod namespace bedrock-agentcore, została przeniesiona, a stary namespace jest wycofywany.

1. Zmiana namespace. Od momentu przeniesienia usługi funkcje rejestru odpowiadają pod agent-registry, a nie pod bedrock-agentcore. Endpointy, akcje IAM, klienci SDK i skrypty CLI odwołujące się do starej nazwy trafiają na usługę, która w tym miejscu już nie odpowiada tak jak wcześniej.
2. Wycofanie starego namespace. Wsparcie dla preview’owego namespace bedrock-agentcore kończy się w ogłoszonym terminie. Konkretna data bywa różna w poszczególnych stronach dokumentacji AWS, dlatego nie zakładaj jednej z góry - sprawdź termin dla swoich zasobów w przewodniku migracji AWS. Po tym terminie stary namespace przestaje obsługiwać ruch.
3. Dane rejestru nie migrują się same. Rejestry i rekordy utworzone w starym namespace trzeba przenieść do nowego osobno. AWS udostępnia narzędzie migracyjne, które wyodrębnia dane, przekształca je do nowego schematu i ładuje do nowego namespace. Dane pozostają w tym samym koncie i regionie, zmienia się wyłącznie namespace.

Reguła kciuka: to nie jest awaria usługi ani problem z uprawnieniami Twojego agenta, lecz zmiana nazwy przestrzeni, do której odwołuje się cała Twoja konfiguracja. Dopóki wszystkie cztery warstwy (endpointy, IAM, SDK, CLI) oraz dane nie wskazują nowego namespace, część wywołań nie będzie działać.

Naprawa

Krok 1: Ustal, czy problem dotyczy namespace

Sprawdź, czy Twoje polityki IAM i konfiguracja klienta wciąż odwołują się do starego namespace. Prefiks akcji IAM jest tu najszybszym sygnałem.

# Poszukaj w politykach IAM akcji ze starym prefiksem namespace
aws iam get-role-policy --role-name <twoja-rola-agenta> \
  --policy-name <nazwa-polityki> \
  --query 'PolicyDocument.Statement[].Action' --output json | grep -i "bedrock-agentcore"

Jeśli akcje nadal mają prefiks bedrock-agentcore tam, gdzie dotyczą rejestru, trafiłeś na przyczynę. Przejdź do kolejnych kroków.

Krok 2: Zaktualizuj polityki IAM na nowy namespace

Zmień akcje rejestru w politykach ról wykonawczych agentów i użytkowników z prefiksu starego namespace na agent-registry, utrzymując zasadę least-privilege.

{
  "Effect": "Allow",
  "Action": [
    "agent-registry:<KonkretnaAkcja>"
  ],
  "Resource": "<dokładny-arn-rejestru-lub-rekordu>"
}

Nadawaj konkretne akcje na konkretnych zasobach, zamiast szerokiego zakresu - migracja to dobry moment, żeby zawęzić zbyt szerokie uprawnienia z okresu preview.

Krok 3: Zaktualizuj endpointy, klientów SDK i skrypty CLI

Przejdź przez miejsca, w których kod wskazuje usługę rejestru, i przełącz je na nowy namespace: endpointy w konfiguracji, nazwę usługi w klientach SDK oraz wywołania w skryptach CLI i w infrastrukturze jako kodzie (na przykład w zasobach Terraform czy Pulumi odwołujących się do rejestru).

• Zaktualizuj klienta SDK, aby wskazywał usługę w namespace agent-registry
• Przejrzyj skrypty CLI i potoki, w których nazwa usługi lub endpoint są zahardkodowane
• Zaktualizuj definicje infrastruktury jako kodu, które tworzą lub odwołują się do zasobów rejestru

Krok 4: Przenieś dane rejestru narzędziem migracyjnym

Rejestry i rekordy z preview nie pojawią się w nowym namespace samoistnie. Użyj narzędzia migracyjnego AWS opisanego w przewodniku migracji, aby wyodrębnić dane ze starego namespace, przekształcić je do nowego schematu i załadować do nowego. Dane pozostają w tym samym koncie i regionie - zmienia się tylko namespace. Zaplanuj migrację przed terminem wycofania, bo po nim stary namespace przestaje obsługiwać ruch.

Weryfikacja

Potwierdź, że operacje rejestru działają pod nowym namespace, a dane są widoczne.

# Operacja na rejestrze w nowym namespace powinna się udać
# (polecenie zależy od Twojego SDK/CLI - kluczowe, że cel to agent-registry, nie bedrock-agentcore)
aws sts get-caller-identity --region us-west-2
# Następnie wykonaj operację odczytu rejestru i potwierdź, że przeniesione rekordy
# są widoczne pod nowym namespace, a wcześniej odrzucane wywołanie zwraca sukces.

Oczekiwane: operacje rejestru udają się pod agent-registry, przeniesione rekordy są widoczne, a wywołania wcześniej odrzucane przez IAM z powodu starego namespace przechodzą. Jeśli publikujesz lub wyszukujesz agentów i narzędzia przez rejestr w skali wielu zespołów, to ten sam problem nadzoru, który opisujemy przy agent sprawl - jeden spójny rejestr jest tańszy w utrzymaniu niż kilka rozjechanych.

Powiązane

• Amazon Bedrock AgentCore: architektura, komponenty i cennik - gdzie rejestr mieści się wśród komponentów
• AWS Loom: nadzór nad agentami AI - rejestr i proces zatwierdzania w ramach platformy
• AgentCore Gateway MCP OAuth 401 - powiązany błąd uwierzytelniania na warstwie Gateway
• AWS Agent Registry - przewodnik migracji (dokumentacja AWS)