Utilisation des mappages de domaine personnalisés

Les mappages de domaines fournissent l'itinéraire URL vers votre application ou fonction Code Engine au sein d'un projet. Avec Code Engine, ces mappings sont automatiquement créés, par défaut, chaque fois que vous déployez une application ou créez une fonction. Toutefois, vous pouvez associer votre propre domaine personnalisé à une application ou à une fonction de Code Engine. Cette option permet d'acheminer les demandes de votre site URL personnalisé vers votre application ou fonction. Vous pouvez utiliser la console Code Engine ou le CLI.

Si vous souhaitez cibler votre application ou votre fonction Code Engine avec un domaine que vous possédez, vous pouvez utiliser un mappage de domaine personnalisé. Lorsque vous définissez un mappage de domaine personnalisé dans Code Engine, vous définissez un mappage un à un entre votre nom de domaine entièrement qualifié (FQDN) et une application ou une fonction de Code Engine dans votre projet.

Un mappage de domaine personnalisé doit pointer vers une seule application ou fonction Code Engine. Toutefois, vous pouvez configurer plusieurs mappages de domaine à une seule application ou fonction.

Pour utiliser des mappages de domaine personnalisés dans Code Engine, procédez comme suit. Notez que certaines étapes sont effectuées en dehors de Code Engine.

  1. Consultez les considérations à prendre en compte avant d'utiliser des mappages de domaine personnalisés dans Code Engine.
  2. Procurez-vous votre domaine personnalisé auprès d'un registre de domaine (en dehors de Code Engine).
  3. Configurez un mappage de domaine personnalisé dans Code Engine pour votre application ou fonction(à partir de la console Code Engine ou du CLI ).
  4. Complétez la configuration du domaine personnalisé avec votre registraire de domaine (en dehors de Code Engine ).

Une fois que vous avez terminé la configuration du domaine personnalisé avec votre registraire de domaine et que vous avez configuré un mappage de domaine pour votre application ou fonction dans Code Engine, testez le mappage de domaine.

Dans Code Engine, vous pouvez afficher, mettre à jour ou supprimer les mappages de domaine à vos applications ou fonctions.

Remarques à prendre en compte avant d'utiliser des mappages de domaine personnalisés dans Code Engine

Avant d'implémenter des mappages de domaine personnalisés dans Code Engine, tenez compte des considérations suivantes:

  • N'utilisez que des mappages de domaines personnalisés pour les domaines protégés par un certificat SSL/TLS, signé par une autorité de certification (CA) publique et fiable.
  • Vous pouvez définir des mappages de domaines personnalisés qui pointent vers des noms de domaines publics.
  • Si votre nom de domaine ne peut être résolu que par un système de noms de domaine non public (DNS), fournissez un certificat qui mentionne le nom de domaine et qui est signé par une autorité de certification publique de confiance.
  • Fournissez la chaîne de certificats complète, en commençant par le certificat correspondant au domaine personnalisé, suivi de tous les certificats intermédiaires jusqu'au certificat racine.
  • Vous ne pouvez pas utiliser de certificats autosignés.
  • Vous ne pouvez pas utiliser des certificats signés par une autorité de certification d'entreprise non sécurisée ou non publique.
  • Votre certificat doit avoir une date d'expiration définie.

Obtention d'un domaine personnalisé et de son certificat TLS et de sa clé privée

Avant de configurer des mappages de domaine personnalisés dans Code Engine, vous devez d'abord obtenir votre domaine personnalisé à partir d'un registre de domaine (en dehors de Code Engine).

  1. A partir d'un registre de domaine, obtenez votre domaine personnalisé ; par exemple, www.example.com.
  2. Obtenez votre certificat SSL/TLS pour votre domaine personnalisé :

    • Vous pouvez créer un certificat qui n'est pas auto-certifié en utilisant le service Let's Encrypt et Certbot. Si le domaine personnalisé est sous votre contrôle et que vous souhaitez créer rapidement un certificat, vous pouvez utiliser Certbot et les services Let's Encrypt pour obtenir un certificat.

    • Vous pouvez obtenir un certificat signé auprès d'une autorité de confiance. Ce type de certificat numérique est utilisé pour établir la confidentialité des communications entre un serveur et un client. Ces certificats contiennent des informations qui sont utilisées pour créer des connexions fiables et sécurisées entre les points d'extrémité. Vous devez également obtenir une clé privée correspondante pour le certificat TLS.

      Vous pouvez obtenir votre certificat et votre clé auprès de votre autorité de certification. Obtenez un certificat SSL/TLS signé pour votre domaine personnalisé. Pour des raisons de sécurité, Code Engine ne prend en charge que les mappages de domaines personnalisés qui sont configurés avec un certificat TLS/SSL signé par une autorité de certification publique de confiance.

      Vous pouvez également obtenir votre certificat et votre clé auprès de Cloud Internet Services (CIS) en commandant un certificat d'origine si la gestion de votre domaine personnalisé a été déléguée à CIS. En suivant cette approche, vous appliquez ensuite le mode TLS flexible de bout en bout.

Comment puis-je utiliser Certbot et le service Let's Encrypt pour mon domaine personnalisé ?

Dans un environnement d'entreprise, travaillez avec votre administrateur de domaine d'entreprise pour obtenir les certificats nécessaires. Cependant, si le domaine personnalisé est sous votre contrôle et que vous souhaitez un certificat rapide, vous pouvez utiliser Certbot et le service Let's Encrypt pour obtenir un certificat :

  1. Installez Certbot. Certbot est un client pour le protocole Automatic Certificate Management Environment(ACME) permettant d'automatiser les interactions entre une autorité de certification et un serveur. Le service Let's Encrypt utilise ce client pour vérifier la propriété du domaine et émettre des certificats. Dans la documentation de Certbot, sélectionnez Other comme logiciel et sélectionnez le système d'exploitation de votre poste de travail pour obtenir les informations nécessaires à l'installation de la ligne de commande de Certbot.

  2. Exécutez la commande suivante pour créer votre certificat. Cet exemple de commande crée un certificat pour les domaines personnalisés example.com et www.example.com. Veillez à mettre à jour la commande pour votre propre domaine personnalisé.

    certbot certonly --manual --preferred-challenges dns --email webmaster@example.com --server https://acme-v02.api.letsencrypt.org/directory --agree-tos --domain example.com --domain www.example.com

  3. Pour vérifier que vous possédez le domaine, définissez un enregistrement TXT avec votre registre de domaine pour les domaines que vous avez demandés à l'étape précédente avec les valeurs fournies avec la sortie de l'outil Certbot ; par exemple, _acme_challenge.example.com et _acme_challenge.ww.example.com. Après avoir défini l'enregistrement TXT, passez à la commande Certbot.

  4. Certbot extrait le certificat signé par Let's Encrypt. L'emplacement dans lequel le certificat est stocké est fourni par la sortie Certbot. Recherchez les fichiers fullchain.pem et privkey.pem.

Exemple de commande permettant d'exécuter Certbot sur un système Ubuntu

sudo certbot certonly --manual --preferred-challenges dns --email webmaster@example.com --server https://acme-v02.api.letsencrypt.org/directory --agree-tos --domain example.com --domain www.example.com

Exemple de sortie pour la demande de certificat pour example.com et www.example.com

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Please deploy a DNS TXT record under the name:
_acme-challenge.example.com.
with the following value:
<MASKED>
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Press Enter to Continue
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Please deploy a DNS TXT record under the name:
_acme-challenge.www.example.com
with the following value:
<MASKED>
(This must be set up in addition to the previous challenges; do not remove,
replace, or undo the previous challenge tasks yet. Note that you might be
asked to create multiple distinct TXT records with the same name. This is
permitted by DNS standards.)
Before continuing, verify the TXT record has been deployed. Depending on the DNS
provider, this may take some time, from a few seconds to multiple minutes. You can
check if it has finished deploying with aid of online tools, such as the Google
Admin Toolbox: https://toolbox.googleapps.com/apps/dig/#TXT/_acme-challenge.www.example.com.
Look for one or more bolded line(s) below the line ';ANSWER'. It should show the
value(s) you've just added.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Press Enter to Continue
Successfully received certificate.
Certificate is saved at: /etc/letsencrypt/live/example.com/fullchain.pem
Key is saved at: /etc/letsencrypt/live/example.com/privkey.pem
This certificate expires on 2023-02-01.
These files will be updated when the certificate renews.
NEXT STEPS:
- This certificate will not be renewed automatically. Autorenewal of --manual certificates requires the use of an authentication hook script (--manual-auth-hook) but one was not provided. To renew this certificate, repeat this same certbot command before the certificate's expiry date.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
If you like Certbot, please consider supporting our work by:
 * Donating to ISRG / Let's Encrypt: https://letsencrypt.org/donate
 * Donating to EFF: https://eff.org/donate-le
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Votre certificat est prêt.

Comment puis-je utiliser un certificat d'origine obtenu auprès de mon CIS pour mon domaine personnalisé?

Si vous obtenez votre certificat et votre clé auprès de votre autorité de certification publique et de confiance, ils sont signés et sécurisés. Vous travaillez avec votre autorité de certification pour obtenir le certificat SSL/TLS signé pour votre domaine personnalisé.

Vous pouvez également utiliser Cloud Internet Services (CIS) pour commander un certificat d'origine, puis configurer CIS pour transmettre les adresses IP des utilisateurs à votre application ou fonction conformément à ce flux :

  1. Commandez votre certificat d'origine :

    1. Dans la console IBM Cloud, allez dans la liste des ressources et filtrez votre instance Internet Services. Dans les résultats de la recherche, cliquez sur le nom de l'instance cible pour afficher sa page de détails.
    2. Sur la page des détails de l'instance CIS, accédez à la page Origine (Security>Origin ) et cliquez sur Order.
    3. Dans le volet "Commander le certificat d'origine", conservez toutes les valeurs par défaut et entrez le nom de domaine avec lequel vous voulez travailler. Par exemple, myapp.example.com. Cliquez sur Commander pour confirmer.
    4. Copiez les valeurs du certificat d'origine et de la clé privée. Vous avez besoin de ces informations lorsque vous mappez votre domaine.

  2. Configurer et appliquer le mode TLS flexible de bout en bout.

    Le certificat de bord est fourni par CIS. Le certificat d'origine est utilisé pour crypter uniquement le trafic entre CIS et l'application ou la fonction Code Engine.

Une fois votre enregistrement DNS créé avec succès dans CIS, vous avez configuré CIS pour transférer les adresses IP des utilisateurs vers votre application ou fonction.

Configuration des mappages de domaines personnalisés dans Code Engine

Vous êtes maintenant familiarisé avec les concepts de travail avec les mappages de domaines personnalisés et vous avez obtenu votre domaine personnalisé auprès d'un bureau d'enregistrement de domaines. Vous êtes prêt à configurer vos applications ou fonctions Code Engine pour utiliser des mappages de domaines personnalisés. Voir :

Affichage des mappages de domaine

Affichage des mappages de domaine à partir de la console

Vous pouvez afficher une liste de tous les mappages de domaine générés automatiquement et personnalisés pour votre application ou fonction à partir de la console. Par défaut, le contenu de la table est limité aux mappages de domaines personnalisés. Utilisez le filtre Type pour modifier la vue.

Cette vue affiche des informations sur l'expiration du certificat associé à votre mappage. Lorsque le certificat arrive à expiration, l'application ou la fonction n'est plus accessible avec le mappage de domaine et cette condition génère une erreur SSL. Si vous disposez d'un certificat qui est sur le point d'expirer, mettez à jour le mappage de domaine personnalisé pour utiliser un certificat mis à jour.

Cette vue affiche également des informations sur l'application ou la fonction spécifique associée au mappage de domaine, ainsi que le type de mappage de domaine. Pour les correspondances générées par Code Engine, le type peut être System-public, System-private ou System-internal. Pour les mappages de domaines personnalisés que vous créez, le type est Custom.

  1. Une fois que votre projet est en statut actif, cliquez sur le nom de votre projet sur la page Code Engine Projects.
  2. Dans la page d'aperçu, cliquez sur Domain mappings.
  3. À partir de la page des correspondances de domaines, affichez une liste des correspondances de domaines définies pour vos applications ou fonctions existantes. Type indique si le mappage est généré automatiquement ou s'il s'agit d'un mappage de domaine personnalisé.

Affichage des mappages de domaine avec l'interface de ligne de commande

Pour afficher la liste de tous les mappages de domaine personnalisés pour vos applications ou fonctions à l'aide de l'interface de ligne de commande, utilisez la commande ibmcloud ce domainmapping list. Par exemple :

ibmcloud ce domainmapping list

Exemple de sortie

Listing domain mappings...
OK

Name              CNAME                                                        Target  Target-Type  Status  Secret Name  Age
www.example.com   custom.abcdabcdabc.us-south.codeengine.appdomain.cloud       myapp   app          ready   mytlssecret  36m

Pour afficher la liste de tous les mappages de domaine pour vos applications ou fonctions, y compris les mappages de domaine personnalisés que vous créez et les mappages de domaine générés automatiquement créés par Code Engine, spécifiez l'option --all avec la commande ibmcloud ce domainmapping list. Les mappages de domaines personnalisés affichent une valeur pour CNAME.

Mise à jour des mappages de domaine

Lorsque vous créez un mappage de domaine personnalisé, le secret TLS est valide jusqu'à l'expiration du certificat. A partir de la page de mappage de domaine, vous pouvez afficher des informations sur les jours restants jusqu'à l'expiration du certificat.

Il est important de savoir si le certificat utilisé avec votre domaine personnalisé répertorie plusieurs noms de domaine ou s'il utilise un certificat générique. Lorsque votre certificat est sur le point d'expirer (ou a expiré), modifiez le secret TLS existant pour le mappage de domaine avec les informations d'identification mises à jour. Ne créez pas un secret TLS différent avec des informations d'identification mises à jour pour votre mappage de domaine.

Mise à jour d'un mappage de domaine à partir de la console

Supposons que le mappage de domaine personnalisé pour www.example.com ait un certificat qui expire bientôt. Vous pouvez mettre à jour le mappage de domaine à partir de la console pour utiliser un certificat mis à jour ou même remplacer le secret TLS pour le mappage. Vous pouvez également mettre à jour votre mappage de domaine pour qu'il pointe vers une application ou une fonction différente dans votre projet.

  1. Sur la page Code Engine Projects, accédez à votre projet.
  2. Dans la page Présentation, cliquez sur Mappages de domaine.
  3. Dans la page Mappages de domaine, cliquez sur l'icône Actions Actions > Editer pour éditer le mappage. Vous pouvez également cliquer sur la ligne de votre domaine personnalisé défini pour mettre à jour le mappage.
  4. Dans le volet "Mise à jour d'un mappage de domaine", vous pouvez modifier l'application ou la fonction associée à ce mappage de domaine. Vous pouvez également remplacer ou mettre à jour le secret TLS pour ce mappage.
  5. Cliquez sur Mettre à jour pour enregistrer vos modifications.

Après avoir mis à jour le mappage, vous pouvez consulter la liste des mappages de domaines pour connaître les modifications les plus récentes.

Mise à jour d'un mappage de domaine avec l'interface de ligne de commande

Pour mettre à jour un mappage de domaine personnalisé, utilisez la commande ibmcloud ce domainmapping update.

Supposons que le mappage de domaine personnalisé pour www.example.com ait un certificat qui expire bientôt. Vous pouvez mettre à jour le mappage de domaine pour utiliser un certificat mis à jour ou même remplacer le secret TLS pour le mappage avec l'option --tls-secret. Vous pouvez également utiliser l'option --target pour mettre à jour votre mappage de domaine afin qu'il pointe vers une application ou une fonction différente dans votre projet.

L'exemple suivant met à jour le mappage du domaine personnalisé www.example.com afin d'utiliser un secret TLS mis à jour appelé mytlssecret.

  1. Mettez à jour le secret TLS mytlssecret avec les informations mises à jour sur le certificat et la clé privée, qui sont contenues dans les fichiers mycertchain2.txt et myprivatekey2 sur votre poste de travail local.

    ibmcloud ce secret update --name mytlssecret --cert-chain-file  mycertchain2.txt --private-key-file myprivatekey2.txt

    Exemple de sortie

    Updating secret mytlssecret..
OK

  2. Mettez à jour le mappage de domaine pour utiliser le secret TLS mis à jour.

    ibmcloud ce domainmapping update --domain-name www.example.com --tls-secret mytlssecret2

    Exemple de sortie

    Getting domain mapping 'www.example.com.org'...
Updating domain mapping 'www.example.com.org'...

Suppression de mappages de domaine

Lorsque vous supprimez un mappage de domaine, vous supprimez l'association de votre application ou fonction Code Engine avec votre mappage de domaine personnalisé dans Code Engine. Cette action ne supprime pas l'application, la fonction ou le secret TLS associé.

La suppression d'une application ou d'une fonction référencée dans un mappage de domaine supprime également tout mappage de domaine personnalisé associé à l'application ou à la fonction.

Lorsque vous supprimez un mappage de domaine personnalisé et que les paramètres DNS du domaine sont conservés, votre trafic est toujours acheminé vers le projet Code Engine. Par exemple, les points CNAME vers le projet Code Engine peuvent toujours être définis. Toutefois, la demande reçoit une réponse avec un message d'erreur 404 (introuvable). Assurez-vous que l'enregistrement CNAME associé au nom de domaine complet est mis à jour dans les paramètres DNS par le registre de domaine.

Suppression de mappages de domaine de la console

A partir de la console, vous pouvez supprimer uniquement les mappages de domaine de type Custom. Les mappages de domaines que Code Engine génère automatiquement ne peuvent pas être supprimés.

Pour supprimer un mappage de domaine personnalisé de la console,

  1. Sur la page Code Engine Projects, accédez à votre projet.
  2. Dans la page Présentation, cliquez sur Mappages de domaine pour afficher la liste des mappages de domaine définis.
  3. (Facultatif) Cliquez sur Type pour filtrer les mappages de domaine par type.
  4. Dans la page Mappages de domaine, supprimez le mappage de domaine personnalisé que vous souhaitez supprimer de votre application ou de votre fonction. Cliquez sur l'icône Actions Actions > Supprimer pour supprimer le mappage.

Suppression de mappages de domaine avec l'interface de ligne de commande

Pour supprimer un mappage de domaine personnalisé à l'aide de l'interface de ligne de commande, utilisez la commande ibmcloud ce domainmapping delete.

Vous ne pouvez supprimer que les mappages de domaines personnalisés ; vous ne pouvez pas supprimer les mappages de domaines générés par Code Engine. Exécutez la commande ibmcloud ce domainmapping list pour afficher la liste des mappages de domaines personnalisés à l'aide de l'interface de ligne de commande. Un mappage de domaine personnalisé comporte un enregistrement CNAME généré. Dans l'interface de ligne de commande, vous pouvez obtenir la valeur CNAME générée pour un mappage de domaine personnalisé spécifié à l'aide de la commande ibmcloud ce domainmapping get.

ibmcloud ce domainmapping delete --domain-name www.example.com -f

Exemple de sortie

Deleting domain mapping 'www.example.com'...
OK

Etapes suivantes

Obtenir l'enregistrement CNAME pour un mappage de domaine personnalisé

Code Engine fournit la cible CNAME pour votre mappage de domaine personnalisé défini.

Pour obtenir l'enregistrement CNAME à partir de la console Code Engine, ouvrez votre mappage de domaine personnalisé défini et affichez la page Mettre à jour le mappage de domaine. Ouvrez la page Mettre à jour le mappage de domaine de l'une des manières suivantes:

  • Dans la table des mappages de domaine, cliquez sur la ligne de votre domaine personnalisé défini.
  • Cliquez sur l'icône Actions Actions > Editer pour éditer le mappage.

Dans la page Mettre à jour les mappages de domaine, vous pouvez obtenir la valeur CNAME target. Par exemple, le mappage www.example.com possède la valeur custom.abcdabcdabc.us-east.codeengine.appdomain.cloud CNAME, où abcdabcdabc est un identificateur unique généré automatiquement et us-east est la région de votre projet.

Pour obtenir l'enregistrement CNAME avec l'interface de ligne de commande, utilisez la commande ibmcloud ce domainmapping get. Exemple :

ibmcloud ce domainmapping get --domain-name www.example.com

Exemple de sortie

Getting domain mapping 'www.example.com'...
OK

Domain Name:  www.example.com
CNAME:        custom.abcdabcdabc.us-south.codeengine.appdomain.cloud
Target Name:  myapp
Target Type:  app
TLS Secret:   mytlssecret
Status:       ready

Une fois que vous avez la cible CNAME, vous êtes prêt à ajouter l'entrée d'enregistrement CNAME aux paramètres DNS de votre domaine personnalisé. Notez que la publication de l'enregistrement CNAME avec le registre de domaine peut prendre un certain temps pour remplir les modifications DNS sur Internet.

Ajout d'un enregistrement DNS dans CIS pour diriger le trafic vers votre application Code Engine

Si vous avez une instance CIS pour gérer votre domaine personnalisé, mettez à jour les enregistrements DNS pour qu'ils pointent vers votre projet Code Engine, comme suit. Notez que pour les bureaux d'enregistrement de domaines autres que CIS, les étapes diffèrent, mais l'objectif est le même : créer un enregistrement DNS de type CNAME, qui pointe vers le point de terminaison CNAME des projets Code Engine:

  1. Sur la page de détails de l'instance CIS, allez à Fiabilité>DNS. Faites défiler jusqu'aux enregistrements DNS et cliquez sur Ajouter.

  2. Dans le volet "Ajouter un enregistrement" :

    • Sélectionnez CNAME comme type.
    • Définissez votre sous-domaine; par exemple, myapp.
    • Indiquez la valeur cible CNAME que vous avez copiée précédemment, en tant que nom de domaine Alias.
    • Vérifiez que les détails de l'enregistrement DNS indiquent que votre mappage de domaine est un alias. Par exemple, recherchez un message similaire à : myapp.example.com is an alias of custom.<id>.<region>.codeeng.appdomain.cloud. Cliquez sur Ajouter pour confirmer l'ajout de l'enregistrement DNS.

    Si vous devez enregistrer plusieurs domaines et sous-domaines, tels que example.com et www.example.com, vous devez répéter les étapes pour chaque sous-domaine. Vous pouvez envisager de créer un certificat unique couvrant plusieurs domaines. Toutefois, vous ne pouvez utiliser ce certificat qu'une seule fois dans une région. Si vous prévoyez d'utiliser vos domaines personnalisés dans plus d'un projet dans une même région, séparez-les.

Vous êtes maintenant habitué à travailler avec des mappages de domaines personnalisés et vous avez obtenu un domaine personnalisé avec son certificat TLS et sa clé privée. Vous êtes prêt à configurer un mappage de domaine personnalisé dans Code Engine pour votre application ou fonction.