Comment utiliser un runbook SAW pour résoudre les problèmes liés à mon nom de domaine personnalisé dans API Gateway ?

Brève description

Le runbook AWSSupport-TroubleshootAPIGatewayCustomDomainConfig fournit une solution automatisée pour vérifier la configuration de votre nom de domaine personnalisé dans API Gateway. Ce runbook vérifie que le nom de domaine personnalisé est configuré dans API Gateway avec des configurations correctes pour l'enregistrement DNS et les mappages d'API.

Pour plus d'informations sur SAW, consultez AWS Support Automation Workflows (Automatisation des flux de travail AWS Support).

Résolution

Le runbook AWSSupport-TroubleshootAPIGatewayCustomDomainConfig vérifie les caractéristiques suivantes :

• Si le nom de domaine personnalisé existe dans API Gateway.
• S'il existe des mappages entre le nom de domaine personnalisé et les API.
• Si la liste de mappages précédente contient un mappage entre le nom de domaine personnalisé et les API spécifiées.
• S'il existe un enregistrement DNS pour le nom de domaine personnalisé.
• Si l'enregistrement DNS pointe vers la valeur cible correcte, telle que générée par API Gateway lors de la création du nom de domaine personnalisé.

L'utilisateur actuel ou la fonction de service AWS Identity and Access Management (IAM) supposée qui exécute l'automatisation doit disposer des autorisations suivantes :

• apigateway:GET
• iam:ListRoles
• iam:PassRole
• route53:ListResourceRecordSets
• ssm:DescribeAutomationExecutions
• ssm:GetAutomationExecution
• ssm:DescribeAutomationStepExecutions
• ssm:StartAutomationExecution
• ssm:DescribeDocument
• ssm:GetDocument
• ssm:ListDocuments

Prérequis

Avant d'exécuter le runbook, assurez-vous que votre utilisateur ou votre rôle IAM dispose des autorisations appropriées. Ces autorisations incluent les autorisations spécifiques d'AWS Systems Manager et les autorisations supplémentaires spécifiques des services décrites dans les sections précédentes de cet article.

Exécuter l'automatisation AWSSupport-TroubleshootAPIGatewayCustomDomainConfig

1. Ouvrez le runbook AWSSupport-TroubleshootAPIGatewayCustomDomainConfig.
   Remarque : Le runbook se trouve dans la région AWS us-east-1.

2. Sélectionnez Exécuter l'automatisation.

   Pour les paramètres d'entrée, saisissez ce qui suit :

   • AutomationAssumeRole (facultatif): L'Amazon Resource Name (ARN) du rôle IAM qui permet à Automation, une fonctionnalité de Systems Manager, d'effectuer les actions en votre nom. Si aucun rôle n'est spécifié, Automation utilise les autorisations de l'utilisateur qui lance le runbook.
   • DomainName (obligatoire): Le nom de domaine personnalisé de votre API.
   • ApiId (obligatoire): L'identifiant de votre API.
   • DNSServerIp (facultatif): Un serveur DNS pour résoudre le problème du nom de domaine personnalisé. Lorsque la valeur n'est pas spécifiée, le serveur DNS AWS est utilisé.
   • HostedZoneId (facultatif): L'identifiant de la zone hébergée publique qui contient l'enregistrement DNS du nom de domaine personnalisé. Ceci n'est pas obligatoire lorsque Route 53 n'est pas utilisée pour le DNS.

3. Sélectionnez Exécuter. L'automatisation démarre.

4. Une fois l'automatisation terminée, consultez Sorties pour obtenir des résultats détaillés.

   Si les vérifications du runbook s'exécutent correctement, votre sortie affiche les détails de configuration du nom de domaine personnalisé.

   Si la configuration du nom de domaine personnalisé ne passe pas l'une des vérifications du runbook, alors ce sera l’échec runbook à l'étape appropriée. Les recommandations de dépannage sont disponibles dans la sortie du runbook.

Exemples de sorties pour le runbook AWSSupport-TroubleshootAPIGatewayCustomDomainConfig

Exemple de sortie pour des vérifications de configuration réussies :

{
  "Result": "The custom domain name is configured correctly",
  "DomainDetails": {
    "DomainName": "<<CUSTOM DOMAIN NAME>>",
    "APIGatewayDomainName": "d-XXXXXXXX.execute-api.<<REGION>>.amazonaws.com",
    "Status": "XXXXXX",
    "EndpointType": "XXXXXX"
  },
  "MappingDetails": [
    {
      "API": "XXXXXX",
      "MappingId": "XXXXXX",
      "MappingKey": "XXXXXX",
      "Stage": "XXXXXX",
      "Status": "ApiHasMappings"
    }
  ],
  "DNSDetails": {
    "<<RECORD TYPE>>": [
      "XXX.XXX.XXX.XXX",
      "XXX.XXX.XXX.XXX",
      "XXX.XXX.XXX.XXX"
    ]
  }
}

Exemple de sortie lorsque le nom de domaine personnalisé ne figure pas dans API Gateway :

" Check (1/5): Check custom domain name exists.
  Status: Failed.

  Troubleshooting Recommendations:
    - Custom domain name: <<CUSTOM DOMAIN NAME>> is not configured in API gateway.
    - Please see the link below for information on how to setup a custom domain for API Gateway:
      > https://aws.amazon.com/fr/premiumsupport/knowledge-center/custom-domain-name-amazon-api-gateway/

    - The remaining checks have not been run at this point hence there may be other errors in the current configuration.
    - After resolving the error above, please check that your custom domain name has:
      > A mapping to the API you are trying to reach
      > A DNS record pointing to the generated API Gateway domain name.

    - You can run this automation again to confirm the changes have been made correctly.
    - More details for this particular error can be found within the individual step details.

  Check (2/5): List mappings.
  Status: Skipped

  Check (3/5): Check mapping exists to API Id: <<API ID>>.
  Status: Skipped

  Check (4/5): Check DNS record exists for custom domain name.
  Status: Skipped

  Check (5/5): Validate DNS record.
  Status: Skipped "

Exemple de sortie lorsque le nom de domaine personnalisé ne comporte aucun mappage :

" Check (1/5): Check custom domain name exists.
  Status: Complete

  Check (2/5): List mappings.
  Status: Failed

  Troubleshooting Recommendations:
    - <<CUSTOM DOMAIN NAME>> does not contain any mappings.
    - Please see the documentation to create one here:
      > https://docs.aws.amazon.com/apigateway/latest/developerguide/rest-api-mappings.html

    - The remaining checks have not been run at this point hence there may be other errors in the current configuration.
    - After resolving the error above, please check that your custom domain name has:
      > A mapping to the API you are trying to reach
      > A DNS record pointing to the generated API Gateway domain name.

    - You can run this automation again to confirm the changes have been made correctly.
    - More details for this particular error can be found within the individual step details.

  Check (3/5): Check mapping exists to API Id: <<API ID>>.
  Status: Skipped

  Check (4/5): Check DNS record exists for custom domain name.
  Status: Skipped

  Check (5/5): Validate DNS record.
  Status: Skipped "

Exemple de sortie lorsque le nom de domaine personnalisé n'est pas mappé à l'identifiant d'API spécifié :

" Check (1/5): Check custom domain name exists.
  Status: Complete

  Check (2/5): List mappings.
  Status: Complete

  Check (3/5): Check mapping exists to API Id: <<API ID>>.
  Status: Failed

    Troubleshooting Recommendations:
    - A base path mapping does not exist between API Id: <<API ID>> and custom domain name: <<CUSTOM DOMAIN NAME>>.
    - Please see the documentation to create one here:
      > https://docs.aws.amazon.com/apigateway/latest/developerguide/rest-api-mappings.html

    - The remaining checks have not been run at this point hence there may be other errors in the current configuration.
    - After resolving the error above, please check that your custom domain name has:
      > A mapping to the API you are trying to reach
      > A DNS record pointing to the generated API Gateway domain name.

    - You can run this automation again to confirm the changes have been made correctly.
    - More details for this particular error can be found within the individual step details.

  Check (4/5): Check DNS record exists for custom domain name.
  Status: Not Run

  Check (5/5): Validate DNS record.
  Status: Skipped "

Exemple de sortie lorsqu'il n'y a aucun enregistrement DNS pour le nom de domaine personnalisé :

" Check (1/5): Check custom domain name exists.
  Status: Complete

  Check (2/5): List mappings.
  Status: Complete

  Check (3/5): Check mapping exists to API Id: <<API ID>>.
  Status: Complete

  Check (4/5): Check DNS record exists for custom domain name.
  Status: Failed

  Troubleshooting Recommendations:
    - There is no DNS record for the custom domain name: <<CUSTOM DOMAIN NAME>> or the domain could not be resolved.
    - Please check your DNS server for a record for this domain and ensure it can be resolved.

    - The remaining checks have not been run at this point hence there may be other errors in the current configuration.
    - After resolving the error above, please check that your custom domain name has:
      > A DNS record pointing to the generated API Gateway domain name.

    - You can run this automation again to confirm the changes have been made correctly.
    - More details for this particular error can be found within the individual step details.


  Check (5/5): Validate DNS record.
  Status: Skipped "

Exemple de sortie lorsque l'enregistrement DNS ne pointe pas vers la bonne cible :

" Check (1/5): Check custom domain name exists.
  Status: Complete

  Check (2/5): List mappings.
  Status: Complete

  Check (3/5): Check mapping exists to API Id: <<API ID>>.
  Status: Complete

  Check (4/5): Check DNS record exists for custom domain name.
  Status: Complete

  Check (5/5): Validate DNS record.
  Status: Failed

  Troubleshooting Recommendations:
    - The DNS record for the custom domain name: <<CUSTOM DOMAIN NAME>> may not be pointing to the correct target.
    - The API Gateway domain name generated for this custom domain name is: <<API GATEWAY DOMAIN NAME>> which should be the target of the DNS record created for the custom domain name.
    - Please check your DNS record for this domain and ensure it is pointing to the API Gateway domain name: <<API GATEWAY DOMAIN NAME>>.

    - After resolving the error above, you can run this automation again to confirm the changes have been made correctly.
    - More details for this particular error can be found within the individual step details."

Remarque : Pour vous aider à dépanner, à y remédier, à gérer et à réduire les coûts associés à vos ressources AWS, AWS Support gère un sous-ensemble des runbooks prédéfinis fournis par AWS. Les préfixes du runbook sont AWSSupport- et AWSPremiumSupport-.

Informations connexes

Exécuter une automatisation

Configuration de l'automatisation