L'auteur a sélectionné lesFree and Open Source Fund pour recevoir un don dans le cadre du programmeWrite for DOnations.
introduction
Ambassador est une passerelle API pour les applications cloud natives qui achemine le trafic entre des services hétérogènes et gère des flux de travail décentralisés. Il agit comme un point d'entrée unique et prend en charge des tâches telles que la découverte de services, la gestion de la configuration, les règles de routage et la limitation de débit. Il offre une grande flexibilité et une facilité de configuration pour vos services.
Envoy est un proxy de service open source conçu pour les applications cloud natives. Dans Kubernetes, Ambassador peut être utilisé pour installer et gérer la configuration Envoy. Ambassador prend en charge les modifications de configuration sans temps d'arrêt et l'intégration avec d'autres fonctionnalités telles que l'authentification, la découverte de services et lesservices meshes.
Dans ce didacticiel, vous allez configurer une passerelle API Ambassador sur un cluster Kubernetes à l'aide de Helm et le configurer pour acheminer le trafic entrant vers divers services en fonction de règles de routage. Vous allez configurer ces règles pour acheminer le trafic en fonction du nom d'hôte ou du chemin d'accès aux services appropriés.
Conditions préalables
Avant de commencer ce guide, vous aurez besoin des éléments suivants:
-
Un cluster DigitalOcean Kubernetes aveckubectl configuré. Pour créer un cluster Kubernetes sur DigitalOcean, consultez nosKubernetes Quickstart.
-
Le gestionnaire de paquets Helm installé sur votre ordinateur local et Tiller installé sur votre cluster. Effectuez les étapes 1 et 2 deHow To Install Software on Kubernetes Clusters with the Helm Package Manager
-
Un nom de domaine entièrement enregistré avec au moins deux enregistrements A configurés. Ce didacticiel utilisera
svc1.your-domain
,svc2.your-domain
etsvc3.your-domain
partout. Vous pouvez suivre lesDNS Quickstart pour configurer vos enregistrements sur DigitalOcean.
[[step-1 -—- Installing-ambassador]] == Étape 1 - Installer Ambassador
Dans cette section, vous allez installer Ambassador sur votre cluster Kubernetes. Ambassador peut être installé à l'aide d'un graphique Helm ou en passant un fichier de configuration YAML à la commandekubectl
.
[.note] #Note: DigitalOcean Kubernetes aRBAC activé par défaut, donc lorsque vous utilisez un fichier de configuration YAML pour l'installation, vous devez vous assurer que vous utilisez celui activé RBAC. Vous pouvez trouver plus de détails sur le déploiement d'Amabassador sur Kubernetes via YAML dans lesdocumentation d'Ambassador.
#
Pour les besoins de ce didacticiel, vous allez utiliser un graphiqueHelm pour installer Ambassador dans votre cluster. Après avoir suivi les conditions préalables, Helm sera installé sur votre cluster.
Pour commencer, exécutez la commande suivante pour installer Ambassador via Helm:
helm upgrade --install --wait ambassador stable/ambassador
Vous verrez une sortie semblable à celle-ci:
OutputRelease "ambassador" does not exist. Installing it now.
NAME: ambassador
LAST DEPLOYED: Tue Jun 18 02:15:00 2019
NAMESPACE: default
STATUS: DEPLOYED
RESOURCES:
==> v1/Deployment
NAME READY UP-TO-DATE AVAILABLE AGE
ambassador 3/3 3 3 2m39s
==> v1/Pod(related)
NAME READY STATUS RESTARTS AGE
ambassador-7d55c468cb-4gpq9 1/1 Running 0 2m38s
ambassador-7d55c468cb-jr9zr 1/1 Running 0 2m38s
ambassador-7d55c468cb-zhm7l 1/1 Running 0 2m38s
==> v1/Service
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
ambassador LoadBalancer 10.245.183.114 139.59.52.164 80:30001/TCP,443:31557/TCP 2m40s
ambassador-admins ClusterIP 10.245.46.43 8877/TCP 2m41s
==> v1/ServiceAccount
NAME SECRETS AGE
ambassador 1 2m43s
==> v1beta1/ClusterRole
NAME AGE
ambassador 2m41s
==> v1beta1/ClusterRoleBinding
NAME AGE
ambassador 2m41s
==> v1beta1/CustomResourceDefinition
NAME AGE
authservices.getambassador.io 2m42s
consulresolvers.getambassador.io 2m41s
kubernetesendpointresolvers.getambassador.io 2m42s
kubernetesserviceresolvers.getambassador.io 2m43s
mappings.getambassador.io 2m41s
modules.getambassador.io 2m41s
ratelimitservices.getambassador.io 2m42s
tcpmappings.getambassador.io 2m41s
tlscontexts.getambassador.io 2m42s
tracingservices.getambassador.io 2m43s
. . .
Cela créera un déploiement, un service et un équilibreur de charge Ambassador avec vos nœuds de cluster Kubernetes attachés. Vous aurez besoin de l’adresse IP de l’équilibreur de charge pour le mapper sur les enregistrements A de votre domaine.
Pour obtenir l'adresse IP de votre équilibreur de charge Ambassador, procédez comme suit:
kubectl get svc --namespace default ambassador
Vous verrez une sortie semblable à:
OutputNAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
ambassador LoadBalancer your_cluster_IP your-IP-address 80:30001/TCP,443:31557/TCP 8m4s
Notez les adresses IP externesyour-IP-address
à cette étape et mappez les domaines (via votre fournisseur de domaine)svc1.your-domain
,svc2.your-domain
etsvc3.your-domain
pour pointer vers cette adresse IP.
Vous pouvez activer HTTPS avec votre DigitalOcean Load Balancer en suivant les étapes indiquées àHow to Configure SSL Termination. Il est recommandé de configurer la terminaison TLS via Load Balancer. Une autre façon de configurer la terminaison TLS consiste à utiliserAmbassador’s TLS Support
Vous avez installé Ambassador sur votre cluster Kubernetes à l'aide de Helm qui a créé un déploiement Ambassador avec trois réplicas dans l'espace de noms par défaut. Cela a également créé un équilibreur de charge avec une adresse IP publique pour acheminer tout le trafic vers la passerelle API. Vous allez ensuite créer des déploiements Kubernetes pour trois services différents que vous utiliserez pour tester cette passerelle d’API.
[[step-2 -—- setting-up-web-server-deployments]] == Étape 2 - Configuration des déploiements de serveur Web
Dans cette section, vous allez créer trois déploiements pour exécuter trois conteneurs de serveur Web différents. Vous allez créer des fichiers YAML avec des définitions de déploiements Kubernetes pour les trois différents conteneurs de serveur Web et les déployer à l'aide dekubectl
.
Ouvrez votre éditeur de texte préféré pour créer votre premier déploiement sur un serveur Web Nginx:
nano svc1-deploy.yaml
Entrez la configuration yaml suivante dans votre fichier:
svc1-deploy.yaml
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
name: svc1
spec:
replicas: 1
selector:
matchLabels:
app: nginx
name: svc1
strategy:
type: RollingUpdate
template:
metadata:
labels:
app: nginx
name: svc1
spec:
containers:
- name: nginx
image: nginx:latest
ports:
- name: http
containerPort: 80
Ici, vous avez défini un KubernetesDeployment
avec l'image de conteneurnginx:latest
à déployer avec le réplica de1
, appelésvc1
. LeDeployment
est défini pour exposer dans le cluster au port80
.
Enregistrez et fermez le fichier.
Puis exécutez la commande suivante pour appliquer cette configuration:
kubectl apply -f svc1-deploy.yaml
Vous verrez la sortie confirmant la création:
Outputdeployment.extensions/svc1 created
Maintenant, créez un deuxième déploiement de serveur Web. Ouvrez un fichier appelésvc2-deploy.yaml
avec:
nano svc2-deploy.yaml
Entrez la configuration YAML suivante dans le fichier:
svc2-deploy.yaml
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
name: svc2
spec:
replicas: 1
selector:
matchLabels:
app: httpd
name: svc2
strategy:
type: RollingUpdate
template:
metadata:
labels:
app: httpd
name: svc2
spec:
containers:
- name: httpd
image: httpd:latest
ports:
- name: http
containerPort: 80
Ici, vous avez défini un KubernetesDeployment
avec l'image de conteneurhttpd
à déployer avec le réplica de1
, appelésvc2
.
Enregistrez et fermez le fichier.
Exécutez la commande suivante pour appliquer cette configuration:
kubectl apply -f svc2-deploy.yaml
Vous verrez cette sortie:
Outputdeployment.extensions/svc2 created
Enfin pour le troisième déploiement, ouvrez et créez le fichiersvc3-deploy.yaml
:
nano svc3-deploy.yaml
Ajoutez les lignes suivantes au fichier:
svc3-deploy.yaml
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
name: svc3
spec:
replicas: 1
selector:
matchLabels:
app: httpbin
name: svc3
strategy:
type: RollingUpdate
template:
metadata:
labels:
app: httpbin
name: svc3
spec:
containers:
- name: httpbin
image: kennethreitz/httpbin:latest
ports:
- name: http
containerPort: 80
Ici, vous avez défini un KubernetesDeployment
avec l'image de conteneurhttpbin
à déployer avec le réplica de1
, appelésvc3
.
Enregistrez et fermez le fichier.
Enfin, exécutez la commande suivante à appliquer:
kubectl apply -f svc3-deploy.yaml
Et vous verrez la sortie suivante:
Outputdeployment.extensions/svc3 created
Vous avez déployé trois conteneurs de serveur Web à l'aide de déploiements Kubernetes. Dans la prochaine étape, vous exposerez ces déploiements au trafic Internet.
[[step-3 -—- exposing-apps-using-services-with-ambassador-annotations]] == Étape 3 - Présentation des applications à l'aide des services avec les annotations Ambassador
Dans cette section, vous exposerez vos applications Web à Internet en créant des services Kubernetes avecAmbassador annotations pour configurer des règles pour acheminer le trafic vers elles. Les annotations dans Kubernetes permettent d'ajouter des métadonnées à des objets. Ambassador utilise ces valeurs d'annotation provenant des services pour configurer ses règles de routage.
Pour rappel, vous devez faire mapper vos domaines (par exemple:svc1.your-domain
,svc2.your-domain
etsvc3.your-domain
) à l'adresse IP publique de Load Balancer dans vos enregistrements DNS.
Définissez un service Kubernetes pour le déploiement desvc1
avec les annotations Ambassador en créant et en ouvrant ce fichier:
nano svc1-service.yaml
[.note] #Note: Le nom du mappage doit être unique pour chaque bloc d'annotation Ambassador. Le mappage agit comme un identifiant pour chaque bloc d'annotation et s'il est répété, il chevauchera l'ancien bloc d'annotation.
#
svc1-service.yaml
apiVersion: v1
kind: Service
metadata:
name: svc1
annotations:
getambassador.io/config: |
---
apiVersion: ambassador/v1
kind: Mapping
name: svc1-service_mapping
host: svc1.your-domain
prefix: /
service: svc1:80
spec:
selector:
app: nginx
name: svc1
ports:
- name: http
protocol: TCP
port: 80
Dans ce code YAML, vous avez défini un service Kubernetessvc1
avec des annotations Ambassador pour mapper le nom d'hôtesvc1.your-domain
à ce service.
Enregistrez et quittezsvc1-service.yaml
, puis exécutez ce qui suit pour appliquer cette configuration:
kubectl apply -f svc1-service.yaml
Vous verrez cette sortie:
Outputservice/svc1 created
Créez votre deuxième service Kubernetes pour le déploiement desvc2
avec les annotations Ambassador. Voici un autre exemple de routage basé sur l'hôte avec Ambassador:
svc2-service.yaml
Ajoutez la configuration suivante au fichier:
svc2-service.yaml
apiVersion: v1
kind: Service
metadata:
name: svc2
annotations:
getambassador.io/config: |
---
apiVersion: ambassador/v1
kind: Mapping
name: svc2-service_mapping
host: svc2.your-domain
prefix: /
service: svc2:80
spec:
selector:
app: httpd
name: svc2
ports:
- name: http
protocol: TCP
port: 80
Enregistrez-le soussvc2-service.yaml
. Ici, vous avez défini un autre service Kubernetes avec des annotations Ambassador pour acheminer le trafic verssvc2
lorsqu'une demande est reçue par Ambassador avec la valeur d'en-têtehost
commesvc2.your-domain
. Par conséquent, ce routage basé sur l'hôte vous permettra d'envoyer une requête au sous-domainesvc2.your-domain
, qui acheminera le trafic vers le servicesvc2
et servira votre requête depuis le serveur Web dehttpd
.
Pour créer ce service, exécutez les opérations suivantes:
kubectl apply -f svc2-service.yaml
Vous verrez le résultat suivant:
Outputservice/svc2 created
Créez un troisième service Kubernetes pour votre déploiementsvc3
et servez-le via le cheminsvc2.your-domain/bin
. Ceci configurera le routage basé sur les chemins pour Ambassador:
svc3-service.yaml
apiVersion: v1
kind: Service
metadata:
name: svc3
spec:
selector:
app: httpbin
name: svc3
ports:
- name: http
protocol: TCP
port: 80
Enregistrez-le soussvc3-service.yaml
et exécutez la commande suivante pour appliquer la configuration:
kubectl apply -f svc3-service.yaml
Votre sortie sera:
Outputservice/svc3 created
Modifiezsvc2-service.yaml
pour ajouter le deuxième bloc d'annotation Ambassador pour acheminer/bin
vers le servicesvc3
:
nano svc2-service.yaml
svc2-service.yaml
apiVersion: v1
kind: Service
metadata:
name: svc2
annotations:
getambassador.io/config: |
---
apiVersion: ambassador/v1
kind: Mapping
name: svc2-service_mapping
host: svc2.your-domain
prefix: /
service: svc2:80
---
apiVersion: ambassador/v1
kind: Mapping
name: svc3-service_mapping
host: svc2.your-domain
prefix: /bin
service: svc3:80
spec:
selector:
app: httpd
name: svc2
ports:
- name: http
protocol: TCP
port: 80
Vous avez ajouté le deuxième bloc d'annotation Ambassador pour configurer les chemins commençant par/bin
à mapper vers votre service Kubernetes desvc3
. Afin d'acheminer les demandes desvc2.your-domain/bin
verssvc3
, vous avez ajouté le deuxième bloc d'annotation ici en tant que valeur d'hôtesvc2.your-domain
, qui est la même pour les deux blocs. Par conséquent, le routage basé sur le chemin vous permettra d'envoyer une requête àsvc2.your-domain/bin
, qui sera reçue par le servicesvc3
et servie par l'applicationhttpbin
dans ce tutoriel
Maintenant, lancez ce qui suit pour appliquer les modifications:
kubectl apply -f svc2-service.yaml
Vous verrez cette sortie:
Outputservice/svc2 configured
Vous avez créé Kubernetes Services pour les trois déploiements et ajouté des règles de routage basées sur l'hôte et sur le chemin avec des annotations Ambassador. Vous allez ensuite ajouter une configuration avancée à ces services pour configurer le routage, la redirection et les en-têtes personnalisés.
[[step-4 -—- advanced-ambassador-configurations-for-routing]] == Étape 4 - Configurations Advanced Ambassador pour le routage
Dans cette section, vous allez configurer les services avec d'autres annotations Ambassador surmodify headers etconfigure redirection.
curl
le domainesvc1.your-domain
et vérifiez les en-têtes de réponse:
curl -I svc1.your-domain
Votre sortie sera semblable à la suivante:
OutputHTTP/1.1 200 OK
server: envoy
date: Mon, 17 Jun 2019 21:41:00 GMT
content-type: text/html
content-length: 612
last-modified: Tue, 21 May 2019 14:23:57 GMT
etag: "5ce409fd-264"
accept-ranges: bytes
x-envoy-upstream-service-time: 0
Cette sortie affiche les en-têtes reçus du service acheminé à l'aide d'Ambassador. Vous allez ajouter des en-têtes personnalisés à votre réponse de service à l'aide d'annotations Ambassador et valider la sortie pour les nouveaux en-têtes ajoutés.
Pour ajouter des en-têtes personnalisés à votre réponse de service, supprimez l'en-têtex-envoy-upstream-service-time
de la réponse et ajoutez un nouvel en-tête de réponsex-geo-location: India
poursvc1
. (Vous pouvez modifier cet en-tête selon vos besoins.)
Modifiez le fichiersvc1-service.yaml
:
nano svc1-service.yaml
Mettez à jour l'annotation avec les lignes en surbrillance suivantes:
svc1-service.yaml
apiVersion: v1
kind: Service
metadata:
name: svc1
annotations:
getambassador.io/config: |
---
apiVersion: ambassador/v1
kind: Mapping
name: svc1-service_mapping
host: svc1.example.com
prefix: /
remove_response_headers:
- x-envoy-upstream-service-time
add_response_headers:
x-geo-location: India
service: svc1:80
spec:
selector:
app: nginx
name: svc1
ports:
- name: http
protocol: TCP
port: 80
Ici, vous avez modifié le servicesvc1
pour supprimerx-envoy-upstream-service-time
et ajouté l'en-têtex-geo-location: India
dans la réponse HTTP.
Appliquez les modifications que vous avez apportées:
kubectl apply -f svc1-service.yaml
Vous verrez la sortie suivante:
Outputservice/svc1 configured
Exécutez maintenantcurl
pour valider les en-têtes mis à jour dans la réponse du service:
curl -I svc1.your-domain
Le résultat sera similaire à ceci:
OutputHTTP/1.1 200 OK
server: envoy
date: Mon, 17 Jun 2019 21:45:26 GMT
content-type: text/html
content-length: 612
last-modified: Tue, 21 May 2019 14:23:57 GMT
etag: "5ce409fd-264"
accept-ranges: bytes
x-geo-location: India
Maintenant, éditezsvc3-service.yaml
pour rediriger les requêtes de votre nom d'hôtesvc3.your-domain
vers le cheminsvc2.your-domain/bin
:
nano svc3-service.yaml
Ajoutez le bloc d'annotation Ambassador comme indiqué dans le fichier YAML suivant et enregistrez-le:
svc3-service.yaml
apiVersion: v1
kind: Service
metadata:
name: svc3
annotations:
getambassador.io/config: |
---
apiVersion: ambassador/v1
kind: Mapping
name: redirect_mapping
host: svc3.your-domain
prefix: /
service: svc2.your-domain
host_redirect: true
path_redirect: /bin
spec:
selector:
app: httpbin
name: svc3
ports:
- name: http
protocol: TCP
port: 80
Vous avez ajoutéhost_redirect: true
pour configurer une réponse de redirection 301 poursvc3
verssvc2.your-domain/bin
pour le nom d'hôtesvc3.your-domain
. Le paramètrehost_redirect
envoie une réponse de redirection 301 au client. Si elles ne sont pas définies, les demandes recevront 200 réponses HTTP au lieu de 301 réponses HTTP.
Maintenant, exécutez la commande suivante pour appliquer ces modifications:
kubectl apply -f svc3-service.yaml
Vous verrez une sortie similaire à:
Outputservice/svc3 configured
Vous pouvez maintenant vérifier la réponse poursvc3.your-domain
en utilisantcurl
:
curl -I svc3.your-domain
Votre sortie sera semblable à la suivante:
OutputHTTP/1.1 301 Moved Permanently
location: http://svc2.your-domain/bin
date: Mon, 17 Jun 2019 21:52:05 GMT
server: envoy
transfer-encoding: chunked
La sortie est un en-tête HTTP pour la réponse de la demande au servicesvc3.your-domain+`showing that the configuration of `+host_redirect: true
dans votre annotation de service a correctement fourni le code d'état HTTP:301 Moved Permanently
.
Vous avez configuré le service avec des annotations Ambassador pour modifier les en-têtes HTTP et configurer les redirections. Vous allez ensuite ajouter une configuration globale au service Ambassador API Gateway.
[[step-5 -—- setting-up-ambassador-global-configurations]] == Étape 5 - Configuration des configurations globales Ambassador
Dans cette section, vous allez modifier le service Ambassador pour ajouter une configuration globale de compression GZIP. La compression GZIP compresse la taille des actifs HTTP et réduit les besoins en bande passante du réseau, ce qui accélère les temps de réponse des clients Web. Cette configuration affecte tout le trafic en cours de routage via Ambassador API Gateway. De même, vous pouvez configurer d'autres modules globaux avec Ambassador, ce qui vous permet d'activer des comportements spéciaux pour Ambassador au niveau mondial. Ces configurations globales peuvent être appliquées à l'aide d'annotations au service Ambassador. Vous pouvez vous référer à la documentation deAmbassador’s Global Configuration pour plus d'informations.
La commandekubectl edit
suivante ouvrira l'éditeur par défaut, qui est vim. Pour utiliser nano, par exemple, vous pouvez définir la variable d'environnementKUBE_EDITOR
sur nano:
export KUBE_EDITOR="nano"
Editez le service Ambassador:
kubectl edit service ambassador
Ajoutez maintenant les lignes en surbrillance à un nouveau bloc d'annotation pour la compression GZIP:
Modification du service d'ambassadeur
apiVersion: v1
kind: Service
metadata:
annotations:
getambassador.io/config: |
---
apiVersion: ambassador/v1
kind: Module
name: ambassador
config:
service_port: 8080
---
apiVersion: ambassador/v0
kind: Module
name: ambassador
config:
gzip:
memory_level: 5
min_content_length: 256
compression_level: BEST
compression_strategy: DEFAULT
content_type:
- application/javascript
- application/json
- text/html
- text/plain
disable_on_etag_header: false
remove_accept_encoding_header: false
creationTimestamp: "2019-06-17T20:45:04Z"
labels:
app.kubernetes.io/instance: ambassador
app.kubernetes.io/managed-by: Tiller
app.kubernetes.io/name: ambassador
helm.sh/chart: ambassador-2.8.2
name: ambassador
namespace: default
resourceVersion: "2153"
. . .
Vous avez ajouté le bloc d'annotation Ambassador à votre service Ambassador et configuré GZIP globalement pour la passerelle API. Ici, vous avez inclus la configuration pour contrôler la quantité de mémoire interne utilisée avecmemory_level
, qui peut être une valeur de 1 à 9. Lecompression_level
réglé àBEST
assure un taux de compression plus élevé au prix d'une latence plus élevée. Avecmin_content_length
, vous avez configuré la longueur de réponse minimale sur256
octets. Pourcontent_type
, vous avez spécifiquement inclus un ensemble demedia types (anciennement de types MIME) qui génèrent une compression. Enfin, vous avez ajouté les deux dernières configurations en tant quefalse
pour permettre la compression.
Vous pouvez en savoir plus sur la compression GZIP surEnvoy’s GZIP page.
Toute modification de ce service s'applique en tant que configuration globale pour la passerelle API.
Une fois que vous avez quitté l'éditeur, vous verrez une sortie semblable à celle-ci:
Outputservice/ambassador edited
Vérifiezsvc1.your-domain
en utilisantcurl
pour l'en-têtecontent-encoding
ayant la valeurgzip
:
curl --compressed -i http://svc1.example.com
Le résultat sera similaire à ceci:
OutputHTTP/1.1 200 OK
server: envoy
date: Mon, 17 Jun 2019 22:25:35 GMT
content-type: text/html
last-modified: Tue, 21 May 2019 14:23:57 GMT
accept-ranges: bytes
x-geo-location: India
vary: Accept-Encoding
content-encoding: gzip
transfer-encoding: chunked
Welcome to nginx!
Welcome to nginx!
If you see this page, the nginx web server is successfully installed and
working. Further configuration is required.
For online documentation and support please refer to
nginx.org.
Commercial support is available at
nginx.com.
Thank you for using nginx.
Ici, vous pouvez voir la page HTML par défaut de Nginx avec son en-tête de réponse indiquant quecontent-encoding
de la réponse reçue estgzip
compressé.
Vous avez ajouté la configuration globale à Ambassador pour activer la configuration GZIP pour les réponses de type de contenu sélectionnées sur la passerelle API.
Conclusion
Vous avez correctement configuré une passerelle API pour votre cluster Kubernetes à l'aide d'Ambassador. Vous pouvez maintenant exposer vos applications à l'aide d'un routage basé sur un hôte et sur un chemin, des en-têtes personnalisés et une compression GZIP globale.
Pour plus d'informations sur les annotations Ambassador et les paramètres de configuration, lisezAmbassador’s official documentation.