서비스 또는 엔드포인트를 추가할 때 404 오류가 발생하면 엔드포인트를 추가하기 전에 네임스페이스와 서비스를 모두 만든 상태인지 확인합니다 (순서대로). 엔드포인트를 추가하려면 서비스가 있어야 합니다.
서비스를 조회해도 엔드포인트가 표시되지 않는 이유는 무엇인가요?
요청에서 프로젝트, 리전, 네임스페이스 이름, 서비스 이름이 모두 올바르고 엔드포인트를 등록한 위치와 일치하는지 확인합니다. 모든 서비스 디렉터리 서비스는 지역 네임스페이스에 있으므로 한 리전에 등록된 서비스는 다른 리전의 데이터와 일치하지 않습니다.
사용자에게 서비스 액세스 권한을 부여했는데 계속 permission denied 오류가 발생합니다.
여기에는 여러 가지 이유가 있을 수 있습니다. 먼저 지역이 올바른지 확인합니다.
네임스페이스 또는 서비스에 정책을 설정하면 해당 정책은 특정 리전에만 적용됩니다. 사용자가 다른 리전에서 동일한 서비스를 등록하거나 조회하려고 하는 경우 해당 지역 서비스에 대한 IAM 액세스 권한도 부여하지 않으면 액세스할 수 없습니다. 액세스 문제를 디버그하려면 서비스 및 네임스페이스에 TestIamPermissions 메서드를 사용해 보세요.
엔드포인트를 몇 개 추가한 후 서비스 백엔드를 삭제했습니다. 엔드포인트가 여전히 표시되는 이유는 무엇인가요?
서비스 디렉터리는 자동 상태 점검이나 하트비트를 실행하지 않으며 명시적으로 엔드포인트를 삭제하지 않는 한 엔드포인트를 삭제하지 않습니다. 더 이상 존재하지 않는 엔드포인트를 서비스 디렉터리에서 삭제하는 코드를 서비스 백엔드/오케스트레이터에 추가해야 합니다. 엔드포인트가 마지막으로 등록되었거나 업데이트된 시간을 기록하려면 엔드포인트에서 전체 기간 주석 필드를 사용하는 것이 좋습니다.
엔드포인트를 조회할 수 있지만 연결하려고 할 때마다 실패합니다.
서비스 디렉터리는 클라이언트의 도달성을 보장하지 않습니다. 서비스는 엔드포인트를 서비스 디렉터리에 직접 등록합니다. 그러나 서비스 디렉터리에 등록된 주소는 라우팅할 수 없을 수 있습니다 (특히 클라이언트와 서버가 모두 별도의 비공개 네트워크에 있는 경우). 클라이언트에서 엔드포인트로 라우팅할 수 있는 경우 비정상적인 엔드포인트로 인한 것일 수 있습니다.
다음 질문을 참고하세요.
클라이언트가 연결할 엔드포인트를 알 수 있도록 엔드포인트의 상태 데이터를 추가하려면 어떻게 해야 하나요?
클라이언트 측 부하 분산을 사용하는 경우 서비스 백엔드는 클라이언트가 연결할 백엔드를 결정하는 데 사용할 수 있는 주석 필드를 엔드포인트에서 가끔 업데이트하는 것이 좋습니다. 서비스 디렉터리는 이 데이터를 검사하거나 평가하지 않습니다.
네임스페이스를 만들었습니다. Cloud DNS 비공개 영역을 할당할 수 없는 이유는 무엇인가요?
이 권한이 있으면 연결된 비공개 영역을 만들 수 있으므로 네임스페이스에 대한 servicedirectory.namespaces.associatePrivateZone IAM 권한이 있는지 확인합니다. 기본적으로 프로젝트 편집자, 프로젝트 소유자, 서비스 디렉터리 관리자, 서비스 디렉터리 편집자 역할에는 이 권한이 있습니다.
서비스의 DNS 조회를 수행해도 엔드포인트가 표시되지 않는 이유는 무엇인가요?
다음과 같은 여러 가지 이유가 있을 수 있습니다.
연결된 네임스페이스가 삭제되었습니다. 비공개 영역에서 get 명령어를 실행하여 이를 확인할 수 있습니다.
serviceDirectoryConfig.deletionTime가 설정된 경우 연결된 네임스페이스와 모든 엔드포인트가 삭제된 것입니다.
비공개 영역을 쿼리할 수 있는 네트워크에서 요청을 실행하고 있는지 확인합니다. 비공개 영역에서 get 명령어를 실행하여 네트워크 목록을 찾을 수 있습니다.
서비스에 유효한 엔드포인트가 없습니다. Service Directory API를 통해 서비스에서 resolve 명령어를 실행하여 서비스가 비어 있지 않고 유효한 엔드포인트 IP가 하나 이상 있는지 확인합니다. DNS 지원은 유효한 IPv4 또는 IPv6 IP 주소가 있는 엔드포인트에서만 사용할 수 있습니다.
올바른 영역을 쿼리하고 있는지 확인합니다. 예를 들어 example.com이라는 서비스 디렉터리 영역을 만들고 billing.example.com이라는 다른 (표준) 비공개 영역이 있다고 가정해 보겠습니다. 그러면 billing.example.com에 대한 DNS 쿼리는 example.com과 연결된 서비스 디렉터리 네임스페이스의 billing 서비스가 아닌 billing.example.com 영역에 속한 리소스 레코드를 반환합니다.자세한 내용은 이름 확인 순서를 참고하세요.
GKE 서비스가 서비스 디렉터리에 동기화되지 않는 이유는 무엇인가요?
다음과 같은 여러 가지 이유가 있을 수 있습니다.
동기화하려는 네임스페이스의 GKE 클러스터에 ServiceDirectoryRegistrationPolicy가 배포되어 있는지 확인합니다. 또한 동기화하려는 서비스가 정책의 라벨 선택기와 일치하는지 확인합니다.
수동으로 만들었거나 동기화하려는 GKE 네임스페이스와 동일한 이름의 다른 통합을 사용하여 만든 기존 서비스 디렉터리 네임스페이스가 이미 있습니다. 충돌이 없도록 기존 서비스 디렉터리 네임스페이스의 이름을 바꾸거나 삭제해야 합니다.
서비스 디렉터리 서비스 계정의 권한이 삭제되었습니다.
service-{PROJECT_NUMBER}@gcp-sa-servicedirectory.iam.gserviceaccount.com에 Service Directory Service Agent IAM 권한이 있는지 확인합니다. IAM에 대한 자세한 내용은 IAM 문서를 참고하세요.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(UTC)"],[],[],null,["# Troubleshooting\n\nWhy do I get a `not found` error when adding an endpoint?\n---------------------------------------------------------\n\nIf you are getting 404 errors when adding services or endpoints,\nensure that you have created both the namespace and the service (in that order)\nbefore adding an endpoint. The service must exist before you can add additional\nendpoints.\n\nWhen I look up a service, why don't I get any of my endpoints?\n--------------------------------------------------------------\n\nEnsure that the project, region, namespace name, and service name are all correct\nin your request and match where you registered the endpoints. All\nService Directory services live in a regional namespace, so services\nregistered with one region do not match data in a separate region.\n\nI granted someone access to a service but they continue to get `permission denied`.\n-----------------------------------------------------------------------------------\n\nThis could be for a couple of reasons. First, check that the region is correct.\nIf you set a policy on a namespace or service, the policy only applies to that\nparticular region. If the user is trying to register or lookup the same service\nin another region, they won't have access unless you grant them\nIAM access to that regional service as well. To debug access\nissues, try the\n[`TestIamPermissions`](/resource-manager/reference/rest/v1/projects/testIamPermissions)\nmethod for services and namespaces.\n\nI added some endpoints and then removed the service backend. Why are the endpoints still there?\n-----------------------------------------------------------------------------------------------\n\nService Directory does not do automatic health-checking or heartbeating, and\ndoes not remove endpoints unless you explicitly remove them. Ensure that you\nadd code to your service backends/orchestrators that remove the endpoint from\nService Directory once it no longer exists. We recommend the use of time-to-live\nannotation fields on endpoints to record the last time an endpoint was registered\nor updated.\n\nI am able to look up endpoints but every time I try to connect to them, it fails.\n---------------------------------------------------------------------------------\n\nService Directory does not ensure the reachability from the client. Services\nregister their endpoints directly with Service Directory. However, the address\nregistered with Service Directory may not be routable (especially if both the\nclient and the server are on separate private networks). If the endpoint is\nroutable from the client, then it could be due to an unhealthy endpoint.\nSee the following question.\n\nHow can I add health data for endpoints so that my clients know which one to connect to?\n----------------------------------------------------------------------------------------\n\nWhen using client-side load balancing, we recommend that service backends\noccasionally update an annotation field on the endpoint that clients can use to\nmake decisions on which backend to connect to. Service Directory does not\ninspect or evaluate this data.\n\nI've created a namespace. Why can't I assign a Cloud DNS private zone to it?\n----------------------------------------------------------------------------\n\nEnsure that you have the `servicedirectory.namespaces.associatePrivateZone`\nIAM permission for the namespace as this permission lets you\ncreate the associated private zone. By default, the Project Editor, Project\nOwner, Service Directory Admin, and Service Directory Editor roles have this\npermission.\n\nWhen I do a DNS lookup of a service, why don't I get any of my endpoints?\n-------------------------------------------------------------------------\n\nThere could be several reasons, such as the following:\n\n1. The associated namespace has been deleted. You can check this by running the [`get`](/dns/docs/reference/v1/managedZones/get) command on the private zone. If the `serviceDirectoryConfig.deletionTime` is set, then the associated namespace and all of its endpoints have been deleted.\n2. Confirm that you are issuing the request from a network that is allowed to query the private zone. You can find the network list by running the [`get`](/dns/docs/reference/v1/managedZones/get) command on the private zone.\n3. There are no (valid) endpoints for the service. Run the [`resolve`](/service-directory/docs/reference/rest/v1beta1/projects.locations.namespaces.services/resolve) command on the service through the Service Directory API to ensure that the service is not empty and has at least one valid endpoint IP. DNS support is only available for endpoints with valid IPv4 or IPv6 IP addresses.\n4. Make sure that you're querying the correct zone. For example, suppose that you create a Service Directory zone called **example.com** , and you have another (standard) private zone named **billing.example.com** . Then any DNS query to **billing.example.com** returns resource records that belong to the **billing.example.com** zone, and not the **billing** service in the Service Directory namespace that is associated with **example.com.** For more information, see [Name resolution\n order](/dns/docs/vpc-name-res-order).\n\nWhy are my GKE services not syncing to Service Directory?\n---------------------------------------------------------\n\nThere could be several reasons, such as the following:\n\n1. Confirm that you have a `ServiceDirectoryRegistrationPolicy` deployed in your GKE cluster for the namespace that you are trying to sync. Also, confirm that the services you are trying to sync match the label selector in your policy.\n2. There is already an existing Service Directory namespace that was created manually or by using some other integration with the same name as the GKE namespace you are trying to sync. You must rename or delete your existing Service Directory namespace so that there are no conflicts.\n3. Permissions from your Service Directory Service Account were removed. Make sure that `service-{PROJECT_NUMBER}@gcp-sa-servicedirectory.iam.gserviceaccount.com` has the `Service Directory Service Agent` IAM permission. For details about IAM, see the [IAM\n documentation](/iam/docs).\n\nWhat's next\n-----------\n\n- To learn more about features, see [Service Directory\n overview](/service-directory/docs/overview).\n- To get additional help, see [Get\n support](/service-directory/docs/getting-support)."]]
