Conectarse desde Google Kubernetes Engine

Esta página describe cómo configurar una conexión desde una aplicación que se ejecuta en Google Kubernetes Engine (GKE) a una instancia de Cloud SQL.

Para obtener instrucciones paso a paso sobre cómo ejecutar una aplicación web de muestra de Google Kubernetes Engine conectada a Cloud SQL, consulta la guía de inicio rápido para conectarse desde Google Kubernetes Engine .

Cloud SQL es un servicio de base de datos completamente administrado que le ayuda a configurar, mantener, administrar y gestionar sus bases de datos relacionales en la nube.

Google Kubernetes Engine es una forma sencilla de implementar, escalar y administrar Kubernetes automáticamente.

Acerca de la conexión de Google Kubernetes Engine a Cloud SQL

Para acceder a una instancia de Cloud SQL desde una aplicación que se ejecuta en Google Kubernetes Engine, puede usar el proxy de autenticación de Cloud SQL (con IP pública o privada) o conectarse directamente usando una dirección IP privada.

El proxy de autenticación de Cloud SQL es la forma recomendada de conectarse a Cloud SQL, incluso con una IP privada. Esto se debe a que proporciona un cifrado y una autenticación robustos mediante IAM, lo que ayuda a mantener la seguridad de su base de datos.

Las conexiones a bases de datos consumen recursos del servidor y de la aplicación que se conecta. Utilice siempre buenas prácticas de gestión de conexiones para minimizar el impacto de su aplicación y reducir la probabilidad de superar los límites de conexión de Cloud SQL. Para obtener más información, consulte Administrar conexiones a bases de datos .

Antes de empezar

Para conectarse a Cloud SQL debe tener:

  • Un clúster de GKE, con la herramienta de línea de comandos kubectl instalada y configurada para comunicarse con el clúster.

    Para obtener ayuda para comenzar a usar GKE, consulte Implementar una aplicación en un clúster de GKE .

    Para conectarse mediante IP privada, el clúster de GKE debe ser nativo de VPC y estar emparejado con la misma red de nube privada virtual (VPC) que la instancia de Cloud SQL.

  • Se creó una instancia.

    Para obtener ayuda para crear una instancia de Cloud SQL, consulte Creación de instancias .

  • Una cuenta de usuario de PostgreSQL configurada en la instancia.

    Su aplicación usará esta cuenta para conectarse a la base de datos. Para obtener ayuda con la creación de una cuenta de usuario, consulte "Crear un usuario" .

Acerca de Kubernetes Secrets

En Kubernetes, los secretos son una forma segura de pasar detalles de configuración a tu aplicación. Puedes crear un secreto con detalles como el nombre de tu base de datos, usuario y contraseña, que se pueden inyectar en tu aplicación como variables de entorno.

Hay muchas formas diferentes de utilizar los secretos, dependiendo del tipo de conexión:

  • Un secreto de credenciales de base de datos incluye el nombre del usuario de la base de datos con el que se está conectando y la contraseña de la base de datos del usuario.
  • Si se conecta con el proxy de autenticación de Cloud SQL, se puede usar un secreto para guardar el archivo de credenciales de su cuenta de servicio.
  • Si se conecta con una IP privada, se puede usar un secreto para especificar la dirección IP privada de su instancia de Cloud SQL.

Para obtener ejemplos completos de cómo usar Secrets, consulte los repositorios de GitHub a los que se hace referencia más adelante en esta página.

Crear un objeto secreto

  1. Los objetos secretos se crean mediante el comando kubectl create secret .

    Para crear un secreto de credenciales de base de datos:

    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. Una vez creados, puedes ver los objetos en la sección Configuración de la página de Google Kubernetes Engine en el Google Cloud consola .

Conectarse a Cloud SQL mediante el proxy de autenticación de Cloud SQL

Al conectarse mediante el proxy de autenticación de Cloud SQL, este se añade a su pod mediante el patrón de contenedor sidecar . El contenedor del proxy de autenticación de Cloud SQL se encuentra en el mismo pod que su aplicación, lo que permite que esta se conecte mediante localhost , lo que aumenta la seguridad y el rendimiento.

Para obtener más información sobre el proxy de autenticación de Cloud SQL, consulte Acerca del proxy de autenticación de Cloud SQL . Para obtener más información sobre cómo trabajar con pods, consulte Descripción general de pods en la documentación de Kubernetes.

Para conectarse mediante el proxy de autenticación de Cloud SQL, necesita lo siguiente:

  1. El nombre de conexión de instancia de su instancia de Cloud SQL.

    El nombre de la conexión de la instancia está disponible en la página de detalles de la instancia de Cloud SQL. Google Cloud consola o desde el comando gcloud sql instances describe INSTANCE_ID .

  2. La ubicación del archivo de clave asociado con una cuenta de servicio con los privilegios adecuados para su instancia de Cloud SQL.

    Consulte Crear una cuenta de servicio para obtener más información.

  3. La API de administración de Cloud SQL está habilitada.

    Enable the API

Proporcionar la cuenta de servicio al proxy de autenticación de Cloud SQL

El primer paso para ejecutar el proxy de autenticación de Cloud SQL en Google Kubernetes Engine es crear una cuenta de servicio de Google (GSA) que represente su aplicación. Se recomienda crear una cuenta de servicio única para cada aplicación, en lugar de usar la misma en todas partes. Este modelo es más seguro, ya que permite limitar los permisos por aplicación.

La cuenta de servicio de su aplicación debe cumplir los siguientes criterios:

  • Pertenecer a un proyecto con la API de administración de Cloud SQL habilitada
  • Se le ha otorgado el rol de IAM de cliente de Cloud SQL (o equivalente) para el proyecto que contiene la instancia a la que desea conectarse
  • Si se conecta mediante una IP privada, debe usar un clúster de GKE nativo de VPC, en la misma VPC que su instancia de Cloud SQL

Debe configurar GKE para proporcionar la cuenta de servicio al proxy de autenticación de Cloud SQL. Se recomiendan dos métodos: mediante la identidad de la carga de trabajo o un archivo de clave de cuenta de servicio .

Identidad de la carga de trabajo

Si usa Google Kubernetes Engine , el método recomendado es usar la función de identidad de carga de trabajo de GKE. Este método le permite vincular una cuenta de servicio de Kubernetes (KSA) a una cuenta de servicio de Google (GSA) . La GSA será entonces accesible para las aplicaciones que usen la KSA correspondiente.

Una cuenta de servicio de Google (GSA) es una identidad de IAM que representa tu aplicación en Google Cloud. De forma similar, una cuenta de servicio de Kubernetes (KSA) es una identidad que representa tu aplicación en un clúster de Google Kubernetes Engine.

Workload Identity vincula una KSA a una GSA, lo que hace que cualquier implementación con esa KSA se autentique como GSA en sus interacciones con Google Cloud.

  1. Habilitar la identidad de carga de trabajo para su clúster

  2. Normalmente, cada aplicación tiene su propia identidad, representada por un par de KSA y GSA. Cree una KSA para su aplicación ejecutando kubectl apply -f service-account.yaml : 

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

  3. Habilite el enlace IAM entre YOUR-GSA-NAME y 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. Agregue una anotación a YOUR-KSA-NAME para completar la vinculación:

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

  5. Por último, asegúrese de especificar la cuenta de servicio para el objeto 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>

Archivo de clave de cuenta de servicio

Como alternativa, si no puede usar Workload Identity, el patrón recomendado es montar un archivo de clave de cuenta de servicio en el pod de proxy de autenticación de Cloud SQL y usar el indicador --credentials-file .

  1. Cree un archivo de credenciales para la clave de su cuenta de servicio:

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

  2. Convierte tu clave de cuenta de servicio en un secreto de k8s:

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

  3. Monte el secreto como un volumen bajo la spec: para su objeto k8s: 

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

  4. Siga las instrucciones de la siguiente sección para acceder al volumen desde el pod del proxy de autenticación de Cloud SQL.

Ejecute el proxy de autenticación de Cloud SQL en un patrón sidecar

Recomendamos ejecutar el proxy de sidecar de Cloud SQL como un contenedor adicional que comparte un pod con la aplicación. Recomendamos ejecutarlo en lugar de como un servicio independiente por varias razones:

  • Evita que el tráfico de SQL quede expuesto localmente; Cloud SQL Auth Proxy proporciona cifrado en las conexiones salientes, pero debe limitar la exposición de las conexiones entrantes.
  • Evita un único punto de falla; el acceso de cada aplicación a su base de datos es independiente de las demás, lo que la hace más resistente.
  • Limita el acceso al proxy de autenticación de Cloud SQL, lo que le permite usar permisos de IAM por aplicación en lugar de exponer la base de datos a todo el clúster.

  • Le permite delimitar las solicitudes de recursos con mayor precisión; debido a que Cloud SQL Auth Proxy consume recursos de manera lineal al uso, este patrón le permite delimitar y solicitar recursos con mayor precisión para que coincidan con sus aplicaciones a medida que escalan.

  • Agregue el proxy de autenticación de Cloud SQL a la configuración del pod en initContainers : 

    initContainers:
  - name: cloud-sql-proxy
    restartPolicy: Always
    # 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.14.1
    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"

      # If you are not connecting with Automatic IAM, you can delete
      # the following flag.
      - "--auto-iam-authn"

      # 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 está utilizando una clave de cuenta de servicio, especifique su volumen secreto y agregue el indicador --credentials-file al comando: 

      # 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
  • Por último, configure su aplicación para conectarse usando 127.0.0.1 en cualquier DB_PORT que haya especificado en la sección de comandos.

Archivos de configuración de muestra completos:

Identidad de la carga de trabajo 

# 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
      initContainers:
        - name: cloud-sql-proxy
          restartPolicy: Always
          # 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.14.1
          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"

            # If you are not connecting with Automatic IAM, you can delete
            # the following flag.
            - "--auto-iam-authn"

            # 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"

Clave de cuenta de servicio 

# 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
      initContainers:
        - name: cloud-sql-proxy
          restartPolicy: Always
          # 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.14.1
          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"

            # If you are not connecting with Automatic IAM AuthN, you can delete
            # the following flag.
            - "--auto-iam-authn"

            # 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>

Conectarse a Cloud SQL sin el proxy de autenticación de Cloud SQL

Si bien no es tan seguro, es posible conectarse desde un clúster de GKE nativo de VPC a una instancia de Cloud SQL en la misma VPC usando una IP privada sin el proxy de autenticación de Cloud SQL.

  1. Crea un secreto con la dirección IP privada de tu instancia: 

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

  2. A continuación, asegúrese de agregar el secreto al contenedor de su aplicación: 

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

  3. Finalmente, configure su aplicación para que se conecte usando la dirección IP de la variable de entorno DB_HOST . Deberá usar el puerto correcto para PostgreSQL: 5432.

Archivo de configuración de muestra completo:

IP privada 

# 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

Solución de problemas

¿Necesitas ayuda? Para solucionar problemas con el proxy, consulta "Solucionar problemas de conexión con el proxy de autenticación de Cloud SQL" o nuestra página de soporte de Cloud SQL .

¿Qué sigue?