Connettersi da Google Kubernetes Engine

Questa pagina descrive come configurare una connessione da un'applicazione in esecuzione in Google Kubernetes Engine (GKE) a un'istanza Cloud SQL.

Per istruzioni passo passo su come eseguire un'applicazione web di esempio di Google Kubernetes Engine connessa a Cloud SQL, consulta laguida rapida per la connessione da Google Kubernetes Engine.

Cloud SQL è un servizio di database completamente gestito che semplifica la configurazione, la manutenzione, la gestione e l'amministrazione dei database relazionali nel cloud.

Google Kubernetes Engine è un modo semplice per automatizzare il deployment, la scalabilità e la gestione di Kubernetes.

Informazioni sulla connessione di Google Kubernetes Engine a Cloud SQL

Per accedere a un'istanza Cloud SQL da un'applicazione in esecuzione in Google Kubernetes Engine, puoi utilizzare il proxy di autenticazione Cloud SQL (con IP pubblico o privato) oppure connetterti direttamente utilizzando un indirizzo IP privato.

Il proxy di autenticazione Cloud SQL è il modo consigliato per connettersi a Cloud SQL, anche quando si utilizza l'IP privato. Questo perché il proxy di autenticazione Cloud SQL fornisce una crittografia e un'autenticazione avanzate utilizzando IAM, che possono contribuire a proteggere il database.

Le connessioni ai database consumano risorse sul server e sull'applicazione di connessione. Utilizza sempre pratiche di gestione delle connessioni efficaci per ridurre al minimo l'impronta della tua applicazione e ridurre la probabilità di superare i limiti di connessione di Cloud SQL. Per ulteriori informazioni, consulta Gestire le connessioni ai database.

Prima di iniziare

Per connetterti a Cloud SQL devi disporre di:

  • Un cluster GKE, con lo strumento a riga di comando kubectl installato e configurato per comunicare con il cluster.

    Per iniziare a utilizzare GKE, consulta Eseguire il deployment di un'app in un cluster GKE.

    Per la connessione tramite IP privato, il cluster GKE deve essere nativo di VPC ed essere sottoposto a peering con la stessa rete Virtual Private Cloud (VPC) dell'istanza Cloud SQL.

  • Un'istanza creata.

    Per assistenza nella creazione di un'istanza Cloud SQL, consulta Creare istanze.

  • Un account utente PostgreSQL configurato sull'istanza.

    La tua applicazione utilizzerà questo account per connettersi al database. Per assistenza nella creazione di un account utente, consulta Creare un utente.

Informazioni sui secret di Kubernetes

In Kubernetes, i secret sono un modo sicuro per trasmettere i dettagli di configurazione alla tua applicazione. Puoi creare un secret con dettagli come il nome del database, l'utente e la password che possono essere inseriti nella tua applicazione come variabili di ambiente.

Esistono molti modi diversi per utilizzare i secret, a seconda del tipo di connessione:

  • Un secret delle credenziali del database include il nome dell'utente del database a cui ti stai connettendo e la password del database dell'utente.
  • Se ti connetti con il proxy di autenticazione Cloud SQL, puoi utilizzare un secret per archiviare il file delle credenziali del tuo account di servizio.
  • Se ti connetti con l'IP privato, puoi utilizzare un secret per specificare l'indirizzo IP privato della tua istanza Cloud SQL.

Per esempi completi di come utilizzare i secret, consulta i repository GitHub a cui si fa riferimento più avanti in questa pagina.

Creare un oggetto secret

  1. Crea gli oggetti secret utilizzando il kubectl create secret comando.

    Per creare un secret delle credenziali del database:

    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 volta creati, puoi visualizzare gli oggetti nella sezione Configurazione di la pagina Google Kubernetes Engine nella Google Cloud console.

Connettersi a Cloud SQL utilizzando il proxy di autenticazione Cloud SQL

Quando ti connetti utilizzando il proxy di autenticazione Cloud SQL, questo viene aggiunto al pod utilizzando il pattern del container sidecar. Il container del proxy di autenticazione Cloud SQL si trova nello stesso pod dell'applicazione, il che consente all'applicazione di connettersi al proxy di autenticazione Cloud SQL utilizzando localhost, aumentando la sicurezza e le prestazioni.

Per ulteriori informazioni sul proxy di autenticazione Cloud SQL, consulta Informazioni sul proxy di autenticazione Cloud SQL. Per ulteriori informazioni sull'utilizzo dei pod, consulta la panoramica dei pod nella documentazione di Kubernetes.

Per la connessione tramite il proxy di autenticazione Cloud SQL, sono necessari i seguenti elementi:

  1. Il nome di connessione istanza della tua istanza Cloud SQL.

    Il nome di connessione istanza è disponibile nella pagina Dettagli istanza Cloud SQL della Google Cloud console o dal comando gcloud sql instances describe INSTANCE_ID.

  2. La posizione del file delle chiavi associato a un account di servizio con i privilegi appropriati per l'istanza Cloud SQL.

    Per ulteriori informazioni, consulta Creare un account di servizio.

  3. L'API Cloud SQL Admin è abilitata.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin), che contiene l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

    Abilitare l'API

Fornire il account di servizio al proxy di autenticazione Cloud SQL

Il primo passo per eseguire il proxy di autenticazione Cloud SQL in Google Kubernetes Engine è creare un account di servizio Google (GSA) per rappresentare la tua applicazione. Ti consigliamo di creare un account di servizio univoco per ogni applicazione, anziché utilizzare lo stesso account di servizio ovunque. Questo modello è più sicuro perché ti consente di limitare le autorizzazioni per ogni applicazione.

Il account di servizio della tua applicazione deve soddisfare i seguenti criteri:

  • Appartenere a un progetto con l'API Cloud SQL Admin abilitata
  • È stato concesso il ruolo IAM client Cloud SQL (o equivalente) per il progetto contenente l'istanza a cui vuoi connetterti
  • Se ti connetti utilizzando l'IP privato, devi utilizzare un cluster GKE nativo di VPC, nello stesso VPC dell'istanza Cloud SQL

Devi configurare GKE in modo che fornisca il account di servizio al proxy di autenticazione Cloud SQL. Esistono due modi consigliati per farlo: Workload Identity o un file delle chiavi del service account.

Workload Identity

Se utilizzi Google Kubernetes Engine, il metodo preferito è utilizzare la funzionalità Workload Identity di GKE. Questo metodo ti consente di associare un account di servizio Kubernetes (KSA) a un account di servizio Google (GSA). Il GSA sarà quindi accessibile alle applicazioni che utilizzano il KSA corrispondente.

Un account di servizio Google (GSA) è un'identità IAM che rappresenta la tua applicazione in Google Cloud. Allo stesso modo, un account di servizio Kubernetes (KSA) è un'identità che rappresenta la tua applicazione in un cluster Google Kubernetes Engine.

Workload Identity associa un KSA a un GSA, facendo in modo che tutti i deployment con quel KSA si autentichino come GSA nelle loro interazioni con Google Cloud.

  1. Abilita Workload Identity per il cluster

  2. In genere, ogni applicazione ha una propria identità, rappresentata da una coppia KSA e GSA. Crea un KSA per la tua applicazione eseguendo kubectl apply -f service-account.yaml:

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

  3. Abilita l'associazione IAM tra il tuo YOUR-GSA-NAME e 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. Aggiungi un'annotazione a YOUR-KSA-NAME per completare l'associazione:

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

  5. Infine, assicurati di specificare il account di servizio per l'oggetto 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>

File delle chiavi del service account

In alternativa, se non puoi utilizzare Workload Identity, il pattern consigliato è montare un file delle chiavi del account di servizio nel pod del proxy di autenticazione Cloud SQL e utilizzare il flag --credentials-file.

  1. Crea un file delle credenziali per la chiave del account di servizio:

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

  2. Trasforma la chiave del account di servizio in un secret k8s Secret:

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

  3. Monta il secret come volume in spec: per l'oggetto k8s:

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

  4. Segui le istruzioni nella sezione successiva per accedere al volume dal pod del proxy di autenticazione Cloud SQL.

Eseguire il proxy di autenticazione Cloud SQL in un pattern sidecar

Ti consigliamo di eseguire il proxy di autenticazione Cloud SQL in un pattern sidecar (come container aggiuntivo che condivide un pod con la tua applicazione). Ti consigliamo di eseguire questa operazione come servizio separato per diversi motivi:

  • Impedisce che il traffico SQL venga esposto localmente; il proxy di autenticazione Cloud SQL fornisce la crittografia sulle connessioni in uscita, ma devi limitare l'esposizione per le connessioni in entrata.
  • Impedisce un singolo punto di errore; l'accesso di ogni applicazione al database è indipendente dalle altre, il che lo rende più resiliente.
  • Limita l'accesso al proxy di autenticazione Cloud SQL, consentendoti di utilizzare le autorizzazioni IAM per ogni applicazione anziché esporre il database all'intero cluster.

  • Ti consente di definire l'ambito delle richieste di risorse in modo più accurato; poiché il proxy di autenticazione Cloud SQL consuma le risorse in modo lineare rispetto all'utilizzo, questo pattern ti consente di definire l'ambito e richiedere le risorse in modo che corrispondano alle tue applicazioni man mano che l'applicazione viene scalata.

  • Aggiungi il proxy di autenticazione Cloud SQL alla configurazione del pod in initContainers, a meno che tu non utilizzi Cloud Service Mesh o Istio.

    Se utilizzi Cloud Service Mesh o Istio, aggiungi il proxy di autenticazione Cloud SQL nella sezione containers.

    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"

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

  • Se utilizzi una chiave del account di servizio, specifica il volume del secret e aggiungi il flag --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
  • Infine, configura l'applicazione in modo che si connetta utilizzando 127.0.0.1 su qualsiasi DB_PORT specificato nella sezione dei comandi.

File di configurazione di esempio completi:

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

Chiave del service account

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

Connettersi a Cloud SQL senza il proxy di autenticazione Cloud SQL

Sebbene non sia altrettanto sicuro, è possibile connettersi da un cluster GKE nativo di VPC a un'istanza Cloud SQL sullo stesso VPC utilizzando l'IP privato senza il proxy di autenticazione Cloud SQL.

  1. Crea un secret con l'indirizzo IP privato dell'istanza:

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

  2. Assicurati di aggiungere il secret al container dell'applicazione:

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

  3. Infine, configura l'applicazione in modo che si connetta utilizzando l'indirizzo IP della variabile di ambiente DB_HOST. Dovrai utilizzare la porta corretta per PostgreSQL: 5432

File di configurazione di esempio completo:

IP privato

# 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

Risoluzione dei problemi

Serve aiuto? Per assistenza nella risoluzione dei problemi relativi al proxy, consulta Risolvere i problemi relativi alle connessioni del proxy di autenticazione Cloud SQL, o la nostra pagina di assistenza di Cloud SQL.

Passaggi successivi