Connettiti 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 dettagliate sull'esecuzione di un'applicazione web di esempio di Google Kubernetes Engine collegata a Cloud SQL, consulta la guida rapida per la connessione da Google Kubernetes Engine.

Cloud SQL è un servizio di database completamente gestito che consente di configurare, mantenere, gestire e amministrare i database relazionali nel cloud.

Google Kubernetes Engine è un modo semplice per eseguire il deployment, scalare e gestire automaticamente 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) o connetterti direttamente utilizzando un indirizzo IP privato.

Il proxy di autenticazione Cloud SQL è il metodo consigliato per connettersi a Cloud SQL, anche quando utilizzi l'IP privato. Questo perché il proxy di autenticazione Cloud SQL fornisce una crittografia e autenticazione efficaci utilizzando IAM, che possono contribuire a proteggere il tuo database.

Le connessioni al database consumano risorse sul server e nell'applicazione che si connette. Utilizza sempre buone pratiche di gestione delle connessioni per ridurre al minimo il carico della tua applicazione e ridurre la probabilità di superare i limiti di connessioni di Cloud SQL. Per ulteriori informazioni, consulta Gestione delle connessioni di database.

Prima di iniziare

Per connetterti a Cloud SQL, devi avere:

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

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

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

  • È stata creata un'istanza.

    Per informazioni sulla creazione di un'istanza Cloud SQL, consulta Creazione di istanze.

  • Un account utente PostgreSQL configurato sull'istanza.

    L'applicazione utilizzerà questo account per connettersi al database. Per assistenza con la creazione di un account utente, consulta Creazione di un utente.

Informazioni sui secret di Kubernetes

In Kubernetes, i secret sono un modo sicuro per passare i dettagli di configurazione all'applicazione. Puoi creare un secret con dettagli come il nome del database, l'utente e la password, che possono essere inseriti nell'applicazione come env vars.

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

  • Un secret delle credenziali del database include il nome dell'utente del database con cui ti stai collegando e la password del database dell'utente.
  • Se ti connetti al proxy di autenticazione Cloud SQL, è possibile utilizzare un secret per conservare il file delle credenziali dell'account di servizio.
  • Se ti connetti con un IP privato, un secret può essere utilizzato per specificare l'indirizzo IP privato della tua istanza Cloud SQL.

Per esempi completi su come utilizzare i secret, consulta i repository GitHub consultati più avanti in questa pagina.

Crea un oggetto Secret

  1. Per creare gli oggetti Secret, utilizza il comando kubectl create secret.

    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 della pagina di Google Kubernetes Engine nella console Google Cloud.

Connettiti a Cloud SQL utilizzando il proxy di autenticazione Cloud SQL

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

Per saperne di più sul proxy di autenticazione Cloud SQL, consulta Informazioni sul proxy di autenticazione Cloud SQL. Per ulteriori informazioni sull'utilizzo dei pod, consulta Panoramica dei pod nella documentazione di Kubernetes.

Per connetterti utilizzando il proxy di autenticazione Cloud SQL, hai bisogno di quanto segue:

  1. Il nome della connessione dell'istanza di Cloud SQL.

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

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

    Per ulteriori informazioni, consulta la sezione Creazione di un account di servizio.

  3. L'API Cloud SQL Admin è abilitata.

    Abilita l'API

Fornisci l'account di servizio al proxy di autenticazione Cloud SQL

Il primo passaggio 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 in quanto consente di limitare le autorizzazioni in base alla singola applicazione.

L'account di servizio per la tua applicazione deve soddisfare i seguenti criteri:

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

Devi configurare GKE per fornire l'account di servizio al proxy di autenticazione Cloud SQL. Esistono due modi consigliati per farlo: un' identità del carico di lavoro o un file delle chiavi dell'account di servizio.

Workload Identity

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

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

Workload Identity associa un Arabia Saudita a una Google Cloud, facendo in modo che tutti i deployment con quell'Arabia Saudita vengano autenticati come Google Cloud nelle interazioni con Google Cloud.

  1. Abilitare Workload Identity per il cluster

  2. In genere, ciascuna applicazione ha la propria identità, rappresentata da una coppia Arabia Saudita e Google Cloud. Crea un Arabia Saudita 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 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 l'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 della chiave dell'account di servizio

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

  1. Crea un file di credenziali per la chiave dell'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 dell'account di servizio in un secret k8s:

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

  3. Monta il secret come volume sotto spec: per il tuo 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.

Esegui 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). Consigliamo di adottare questa opzione di esecuzione come servizio separato per diversi motivi:

  • Impedisce che il traffico SQL venga esposto localmente; il proxy di autenticazione Cloud SQL fornisce la crittografia per le connessioni in uscita, ma devi limitare l'esposizione per le connessioni in arrivo.
  • Impedisce un single point of failure; l'accesso di ogni applicazione al tuo database è indipendente dagli altri, il che lo rende più resiliente.
  • Limita l'accesso al proxy di autenticazione Cloud SQL, in modo da utilizzare le autorizzazioni IAM per l'applicazione anziché esporre il database all'intero cluster.

  • Consente di definire l'ambito delle richieste di risorse in modo più preciso; poiché il proxy di autenticazione Cloud SQL consuma le risorse in modo lineare per l'utilizzo, questo pattern consente di definire l'ambito e richiedere le risorse in modo più preciso in modo che corrispondano alle applicazioni durante la scalabilità.

  • Aggiungi il proxy di autenticazione Cloud SQL alla configurazione del pod in 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.11.4
  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"

    Se utilizzi una chiave dell'account di servizio, specifica il volume 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 di comando.

Completa i file di configurazione di esempio:

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

Chiave account di servizio

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

Connettiti a Cloud SQL senza il proxy di autenticazione Cloud SQL

Sebbene non sia così sicuro, è possibile connettersi da un cluster GKE nativo 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 della tua 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 della tua 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 di DB_HOST env var. Dovrai usare la porta corretta per PostgreSQL: 5432

Completa il file di configurazione di esempio:

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 Risoluzione dei problemi di connessioni al proxy di autenticazione Cloud SQL o la nostra pagina di assistenza di Cloud SQL.

Passaggi successivi