Connexion depuis Google Kubernetes Engine

Cette page explique comment configurer une connexion à partir d'une application exécutée dans Google Kubernetes Engine (GKE) vers une instance Cloud SQL.

Pour obtenir des instructions détaillées sur l'exécution d'un exemple d'application Web Google Kubernetes Engine connectée à Cloud SQL, consultezDémarrage rapide pour la connexion depuis Google Kubernetes Engine.

Cloud SQL est un service de base de données entièrement géré qui vous aide à configurer, maintenir, gérer et administrer vos bases de données relationnelles dans le cloud.

Google Kubernetes Engine est un moyen simple de déployer, faire évoluer et gérer automatiquement Kubernetes.

À propos de la connexion de Google Kubernetes Engine à Cloud SQL

Pour accéder à une instance Cloud SQL depuis une application s'exécutant dans Google Kubernetes Engine, vous pouvez utiliser le proxy d'authentification Cloud SQL (avec une adresse IP publique ou privée) ou vous connecter directement à l'aide d'une adresse IP privée.

Le proxy d'authentification Cloud SQL est le mode de connexion à Cloud SQL recommandé même lorsque vous utilisez une adresse IP privée. En effet, le proxy d'authentification Cloud SQL assure un chiffrement et une authentification sécurisés à l'aide d'IAM, ce qui contribue à sécuriser votre base de données.

Les connexions aux bases de données consomment des ressources sur le serveur et sur l'application de connexion. Suivez toujours les bonnes pratiques en matière de gestion des connexions afin de réduire au maximum l'encombrement de votre application et les risques de dépassement des limites de connexion Cloud SQL. Pour en savoir plus, consultez la page Gérer les connexions à la base de données.

Avant de commencer

Pour vous connecter à Cloud SQL, vous devez disposer des éléments suivants :

  • Un cluster GKE sur lequel l'outil de ligne de commande kubectl est installé et configuré pour communiquer avec le cluster.

    Pour obtenir de l'aide sur la mise en route de GKE, consultez la page Déployer une application sur un cluster GKE.

    Pour vous connecter à l'aide d'une adresse IP privée, le cluster GKE doit être VPC natif et appairé avec le même réseau cloud privé virtuel (VPC) que l'instance Cloud SQL.

  • Une instance créée

    Pour savoir comment créer une instance Cloud SQL, consultez la page Créer des instances.

  • Un compte utilisateur PostgreSQL configuré sur l'instance

    Votre application utilisera ce compte pour se connecter à la base de données. Pour savoir comment créer un compte d'utilisateur, consultez la section Créer un utilisateur.

À propos des secrets Kubernetes

Dans Kubernetes, les secrets constituent un moyen sécurisé de transmettre les informations de configuration à votre application. Vous pouvez créer un secret contenant des informations telles que le nom de la base de données, l'utilisateur et le mot de passe, qui peuvent être injectées dans votre application sous forme de variables d'environnement.

Les secrets peuvent être utilisés de différentes manières, en fonction du type de connexion :

  • Un secret d'identifiants de base de données inclut le nom d'utilisateur de la base de données avec lequel vous vous connectez, ainsi que son mot de passe pour la base de données.
  • Si vous vous connectez avec le proxy d'authentification Cloud SQL, vous pouvez utiliser un secret pour conserver le fichier d'identifiants de votre compte de service.
  • Si vous vous connectez avec une adresse IP privée, un secret peut être utilisé pour spécifier l'adresse IP privée de votre instance Cloud SQL.

Pour obtenir des exemples complets d'utilisation des secrets, consultez les dépôts GitHub référencés ultérieurement sur cette page.

Créer un objet Secret

  1. Pour créer des objets Secret, utilisez la commande kubectl create secret.

    Pour créer un secret d'identifiants de base de données :

    kubectl create secret generic <YOUR-DB-SECRET> \
  --from-literal=username=<YOUR-DATABASE-USER> \
  --from-literal=password=<YOUR-DATABASE-PASSWORD> \
  --from-literal=database=<YOUR-DATABASE-NAME>

  2. Une fois les objets créés, vous pouvez les afficher dans la section Configuration de la page Google Kubernetes Engine de Google Cloud Console.

Se connecter à Cloud SQL à l'aide du proxy d'authentification Cloud SQL

Lorsque vous vous connectez à l'aide du proxy d'authentification Cloud SQL, celui-ci est ajouté à votre pod à l'aide du modèle de conteneur sidecar. Le conteneur du proxy d'authentification Cloud SQL se trouve dans le même pod que l'application, ce qui permet à celle-ci de se connecter au proxy Cloud SQL via localhost, améliorant ainsi la sécurité et les performances.

Pour en savoir plus sur le proxy d'authentification Cloud SQL, consultez la page À propos du proxy d'authentification Cloud SQL. Pour plus d'informations sur l'utilisation des pods, consultez la page Présentation des pods dans la documentation Kubernetes.

Pour vous connecter à l'aide du proxy d'authentification Cloud SQL, vous avez besoin des éléments suivants :

  1. Le nom de connexion de l'instance Cloud SQL.

    Le nom de connexion de l'instance est disponible sur la page de Google Cloud Console contenant les détails de l'instance Cloud SQL, ou à l'aide de la commande gcloud sql instances describe INSTANCE_ID.

  2. L'emplacement du fichier de clé associé à un compte de service doté des droits appropriés pour l'instance Cloud SQL

    Pour en savoir plus, consultez la section Créer un compte de service.

  3. L'API Cloud SQL Admin activée

    Activer l'API

Fournir le compte de service au proxy d'authentification Cloud SQL

La première étape de l'exécution du proxy d'authentification Cloud SQL dans Google Kubernetes Engine consiste à créer un compte de service Google pour représenter votre application. Il est recommandé de créer un compte de service unique pour chaque application plutôt que d'utiliser le même compte de service partout. Ce modèle est plus sécurisé, car il vous permet de limiter les autorisations par application.

Le compte de service de votre application doit répondre aux critères suivants :

  • Appartenir à un projet pour lequel l'API Cloud SQL Admin est activée.
  • Le rôle IAM (ou équivalent) du client Cloud SQL a été attribué pour le projet contenant l'instance à laquelle vous souhaitez vous connecter.
  • Si vous vous connectez à l'aide d'une adresse IP privée, vous devez utiliser un cluster GKE de VPC natif dans le même VPC que votre instance Cloud SQL.

Vous devez configurer GKE pour fournir le compte de service au proxy d'authentification Cloud SQL. Pour ce faire, deux méthodes sont recommandées : Workload Identity ou un fichier de clé du compte de service.

Workload Identity

Si vous utilisez Google Kubernetes Engine, la méthode recommandée consiste à utiliser la fonctionnalité Workload Identity de GKE. Cette méthode vous permet d'associer un compte de service Kubernetes (KSA) à un compte de service Google (GSA). Le GSA sera alors accessible aux applications utilisant le KSA correspondant.

Un compte de service Google (GSA) est une identité IAM qui représente votre application dans Google Cloud. De la même manière, un compte de service Kubernetes (KSA) est une identité qui représente votre application dans un cluster Google Kubernetes Engine.

Workload Identity associe un KSA à un GSA, ce qui entraîne l'authentification de tous les déploiements dotés de ce KSA en tant que GSA lors de leurs interactions avec Google Cloud.

  1. Activer Workload Identity pour votre cluster

  2. En règle générale, chaque application possède sa propre identité, représentée par une paire KSA et GSA. Créez un KSA pour votre application en exécutant la commande kubectl apply -f service-account.yaml :

    apiVersion: v1
kind: ServiceAccount
metadata:
  name: <YOUR-KSA-NAME> # TODO(developer): replace these values

  3. Activez la liaison IAM entre YOUR-GSA-NAME et YOUR-KSA-NAME :

    gcloud iam service-accounts add-iam-policy-binding \
--role="roles/iam.workloadIdentityUser" \
--member="serviceAccount:YOUR-GOOGLE-CLOUD-PROJECT.svc.id.goog[YOUR-K8S-NAMESPACE/YOUR-KSA-NAME]" \
YOUR-GSA-NAME@YOUR-GOOGLE-CLOUD-PROJECT.iam.gserviceaccount.com

  4. Ajoutez une annotation à YOUR-KSA-NAME pour terminer la liaison :

    kubectl annotate serviceaccount \
YOUR-KSA-NAME \
iam.gke.io/gcp-service-account=YOUR-GSA-NAME@YOUR-GOOGLE-CLOUD-PROJECT.iam.gserviceaccount.com

  5. Enfin, assurez-vous de spécifier le compte de service pour l'objet k8s.

    apiVersion: apps/v1
kind: Deployment
metadata:
  name: <YOUR-DEPLOYMENT-NAME>
spec:
  selector:
    matchLabels:
      app: <YOUR-APPLICATION-NAME>
  template:
    metadata:
      labels:
        app: <YOUR-APPLICATION-NAME>
    spec:
      serviceAccountName: <YOUR-KSA-NAME>

Fichier de clé du compte de service

Si vous ne pouvez pas utiliser Workload Identity, le modèle recommandé consiste à installer un fichier de clé de compte de service dans le pod du proxy d'authentification Cloud SQL et à utiliser l'option --credentials-file.

  1. Créez un fichier d'identifiants pour votre clé de compte de service :

    gcloud iam service-accounts keys create ~/key.json \
--iam-account=YOUR-SA-NAME@project-id.iam.gserviceaccount.com

  2. Transformez la clé de votre compte de service en secret k8s :

    kubectl create secret generic YOUR-SA-SECRET \
--from-file=service_account.json=~/key.json

  3. Installez le secret en tant que volume sous spec: pour votre objet k8s :

    volumes:
- name: <YOUR-SA-SECRET-VOLUME>
  secret:
    secretName: <YOUR-SA-SECRET>

  4. Suivez les instructions de la section suivante pour accéder au volume à partir du pod du proxy d'authentification Cloud SQL.

Exécuter le proxy d'authentification Cloud SQL dans un modèle side-car

Nous vous recommandons d'exécuter le proxy d'authentification Cloud SQL dans un modèle sidecar (en tant que conteneur supplémentaire partageant un pod avec votre application). Nous recommandons cette approche plutôt que de l'exécuter en tant que service distinct, pour plusieurs raisons :

  • Empêcher l'exposition locale de votre trafic SQL. Le proxy d'authentification Cloud SQL assure le chiffrement des connexions sortantes mais vous devez limiter l'exposition aux connexions entrantes.
  • Empêcher un point de défaillance unique : l'accès de chaque application à votre base de données est indépendant des autres, ce qui rend l'ensemble plus résilient.
  • Limiter l'accès au proxy d'authentification Cloud SQL, ce qui vous permet d'utiliser les autorisations IAM par application plutôt que d'exposer la base de données à l'ensemble du cluster.

  • Permettre d'étendre la portée des demandes de ressources : comme le proxy d'authentification Cloud SQL consomme les ressources de façon linéaire, ce modèle vous permet de définir plus précisément la portée et les demandes des ressources pour les adapter à vos applications.

  • Ajoutez le proxy Cloud SQL à la configuration du pod sous containers :

    - name: cloud-sql-proxy
  # It is recommended to use the latest version of the Cloud SQL Auth Proxy
  # Make sure to update on a regular schedule!
  image: gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.8.0
  args:
    # If connecting from a VPC-native GKE cluster, you can use the
    # following flag to have the proxy connect over private IP
    # - "--private-ip"

    # Enable structured logging with LogEntry format:
    - "--structured-logs"

    # Replace DB_PORT with the port the proxy should listen on
    - "--port=<DB_PORT>"
    - "<INSTANCE_CONNECTION_NAME>"

  securityContext:
    # The default Cloud SQL Auth Proxy image runs as the
    # "nonroot" user and group (uid: 65532) by default.
    runAsNonRoot: true
  # You should use resource requests/limits as a best practice to prevent
  # pods from consuming too many resources and affecting the execution of
  # other pods. You should adjust the following values based on what your
  # application needs. For details, see
  # https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
  resources:
    requests:
      # The proxy's memory use scales linearly with the number of active
      # connections. Fewer open connections will use less memory. Adjust
      # this value based on your application's requirements.
      memory: "2Gi"
      # The proxy's CPU use scales linearly with the amount of IO between
      # the database and the application. Adjust this value based on your
      # application's requirements.
      cpu:    "1"

    Si vous utilisez une clé de compte de service, spécifiez le volume de votre secret et ajoutez l'option --credentials-file à la commande :

      # This flag specifies where the service account key can be found
  - "--credentials-file=/secrets/service_account.json"
securityContext:
  # The default Cloud SQL Auth Proxy image runs as the
  # "nonroot" user and group (uid: 65532) by default.
  runAsNonRoot: true
volumeMounts:
- name: <YOUR-SA-SECRET-VOLUME>
  mountPath: /secrets/
  readOnly: true
  • Enfin, configurez votre application pour qu'elle se connecte à l'aide de 127.0.0.1 sur la valeur DB_PORT spécifiée dans la section de commande.

Exemple de fichier de configuration complet :

Workload Identity

# Copyright 2021 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: <YOUR-DEPLOYMENT-NAME>
spec:
  selector:
    matchLabels:
      app: <YOUR-APPLICATION-NAME>
  template:
    metadata:
      labels:
        app: <YOUR-APPLICATION-NAME>
    spec:
      serviceAccountName: <YOUR-KSA-NAME>
      containers:
      - name: <YOUR-APPLICATION-NAME>
        # ... other container configuration
        env:
        - name: DB_USER
          valueFrom:
            secretKeyRef:
              name: <YOUR-DB-SECRET>
              key: username
        - name: DB_PASS
          valueFrom:
            secretKeyRef:
              name: <YOUR-DB-SECRET>
              key: password
        - name: DB_NAME
          valueFrom:
            secretKeyRef:
              name: <YOUR-DB-SECRET>
              key: database
      - name: cloud-sql-proxy
        # It is recommended to use the latest version of the Cloud SQL Auth Proxy
        # Make sure to update on a regular schedule!
        image: gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.8.0
        args:
          # If connecting from a VPC-native GKE cluster, you can use the
          # following flag to have the proxy connect over private IP
          # - "--private-ip"

          # Enable structured logging with LogEntry format:
          - "--structured-logs"

          # Replace DB_PORT with the port the proxy should listen on
          - "--port=<DB_PORT>"
          - "<INSTANCE_CONNECTION_NAME>"

        securityContext:
          # The default Cloud SQL Auth Proxy image runs as the
          # "nonroot" user and group (uid: 65532) by default.
          runAsNonRoot: true
        # You should use resource requests/limits as a best practice to prevent
        # pods from consuming too many resources and affecting the execution of
        # other pods. You should adjust the following values based on what your
        # application needs. For details, see
        # https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
        resources:
          requests:
            # The proxy's memory use scales linearly with the number of active
            # connections. Fewer open connections will use less memory. Adjust
            # this value based on your application's requirements.
            memory: "2Gi"
            # The proxy's CPU use scales linearly with the amount of IO between
            # the database and the application. Adjust this value based on your
            # application's requirements.
            cpu:    "1"

Clé de compte de service

# Copyright 2021 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: <YOUR-DEPLOYMENT-NAME>
spec:
  selector:
    matchLabels:
      app: <YOUR-APPLICATION-NAME>
  template:
    metadata:
      labels:
        app: <YOUR-APPLICATION-NAME>
    spec:
      containers:
      - name: <YOUR-APPLICATION-NAME>
        # ... other container configuration
        env:
        - name: DB_USER
          valueFrom:
            secretKeyRef:
              name: <YOUR-DB-SECRET>
              key: username
        - name: DB_PASS
          valueFrom:
            secretKeyRef:
              name: <YOUR-DB-SECRET>
              key: password
        - name: DB_NAME
          valueFrom:
            secretKeyRef:
              name: <YOUR-DB-SECRET>
              key: database
      - name: cloud-sql-proxy
        # It is recommended to use the latest version of the Cloud SQL Auth Proxy
        # Make sure to update on a regular schedule!
        image: gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.8.0
        args:
          # If connecting from a VPC-native GKE cluster, you can use the
          # following flag to have the proxy connect over private IP
          # - "--private-ip"

          # Enable structured logging with LogEntry format:
          - "--structured-logs"

          # Replace DB_PORT with the port the proxy should listen on
          - "--port=<DB_PORT>"
          - "<INSTANCE_CONNECTION_NAME>"

          # This flag specifies where the service account key can be found
          - "--credentials-file=/secrets/service_account.json"
        securityContext:
          # The default Cloud SQL Auth Proxy image runs as the
          # "nonroot" user and group (uid: 65532) by default.
          runAsNonRoot: true
        volumeMounts:
        - name: <YOUR-SA-SECRET-VOLUME>
          mountPath: /secrets/
          readOnly: true
        # Resource configuration depends on an application's requirements. You
        # should adjust the following values based on what your application
        # needs. For details, see https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
        resources:
          requests:
            # The proxy's memory use scales linearly with the number of active
            # connections. Fewer open connections will use less memory. Adjust
            # this value based on your application's requirements.
            memory: "2Gi"
            # The proxy's CPU use scales linearly with the amount of IO between
            # the database and the application. Adjust this value based on your
            # application's requirements.
            cpu:    "1"
      volumes:
      - name: <YOUR-SA-SECRET-VOLUME>
        secret:
          secretName: <YOUR-SA-SECRET>

Se connecter à Cloud SQL sans le proxy d'authentification Cloud SQL

Bien que cela soit moins sécurisé, il est possible de se connecter à partir d'un cluster GKE de VPC natif à une instance Cloud SQL sur le même VPC à l'aide d'une adresse IP privée sans le proxy d'authentification Cloud SQL.

  1. Créez un secret avec l'adresse IP privée de votre instance :

    kubectl create secret generic <YOUR-PRIVATE-IP-SECRET> \
    --from-literal=db_host=<YOUR-PRIVATE-IP-ADDRESS>

  2. Assurez-vous ensuite d'ajouter le secret au conteneur de votre application :

    - name: DB_HOST
  valueFrom:
    secretKeyRef:
      name: <YOUR-PRIVATE-IP-SECRET>
      key: db_host

  3. Enfin, configurez votre application pour qu'elle se connecte en utilisant l'adresse IP de la variable d'environnement DB_HOST. Dans le cas de PostgreSQL, il faut utiliser le port 5432.

Exemple de fichier de configuration complet :

Adresse IP privée

# Copyright 2021 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: <YOUR-DEPLOYMENT-NAME>
spec:
  selector:
    matchLabels:
      app: <YOUR-APPLICATION-NAME>
  template:
    metadata:
      labels:
        app: <YOUR-APPLICATION-NAME>
    spec:
      containers:
      - name: <YOUR-APPLICATION-NAME>
        # ... other container configuration
        env:
        - name: DB_USER
          valueFrom:
            secretKeyRef:
              name: <YOUR-DB-SECRET>
              key: username
        - name: DB_PASS
          valueFrom:
            secretKeyRef:
              name: <YOUR-DB-SECRET>
              key: password
        - name: DB_NAME
          valueFrom:
            secretKeyRef:
              name: <YOUR-DB-SECRET>
              key: database
        - name: DB_HOST
          valueFrom:
            secretKeyRef:
              name: <YOUR-PRIVATE-IP-SECRET>
              key: db_host

Dépannage

Besoin d'aide ? Pour obtenir de l'aide sur le dépannage du proxy, consultez la section Dépannage des connexions via le proxy d'authentification Cloud SQL ou la page Assistance Cloud SQL.

Étapes suivantes