Conectar do Google Kubernetes Engine

Esta página descreve como configurar uma conexão de um aplicativo em execução no Google Kubernetes Engine (GKE) para uma instância do Cloud SQL.

Para obter instruções passo a passo sobre como executar um aplicativo Web de exemplo do Google Kubernetes Engine conectado ao Cloud SQL, consulte o início rápido para conexão do Google Kubernetes Engine .

O Cloud SQL é um serviço de banco de dados totalmente gerenciado que ajuda você a configurar, manter, gerenciar e administrar seus bancos de dados relacionais na nuvem.

O Google Kubernetes Engine é uma maneira simples de implantar, dimensionar e gerenciar o Kubernetes automaticamente.

Sobre conectar o Google Kubernetes Engine ao Cloud SQL

Para acessar uma instância do Cloud SQL de um aplicativo em execução no Google Kubernetes Engine, você pode usar o Cloud SQL Auth Proxy (com IP público ou privado) ou conectar-se diretamente usando um endereço IP privado.

O Cloud SQL Auth Proxy é a maneira recomendada de se conectar ao Cloud SQL, mesmo usando um IP privado. Isso ocorre porque o Cloud SQL Auth Proxy oferece criptografia e autenticação robustas usando o IAM, o que pode ajudar a manter seu banco de dados seguro.

As conexões de banco de dados consomem recursos no servidor e no aplicativo conectado. Sempre use boas práticas de gerenciamento de conexões para minimizar o impacto do seu aplicativo e reduzir a probabilidade de exceder os limites de conexão do Cloud SQL. Para obter mais informações, consulte Gerenciando conexões de banco de dados .

Antes de começar

Para se conectar ao Cloud SQL, você deve ter:

  • Um cluster do GKE, com a ferramenta de linha de comando kubectl instalada e configurada para se comunicar com o cluster.

    Para obter ajuda para começar a usar o GKE, consulte Implantar um aplicativo em um cluster do GKE .

    Para conectar usando IP privado, o cluster do GKE deve ser nativo de VPC e pareado com a mesma rede de Nuvem Privada Virtual (VPC) que a instância do Cloud SQL.

  • Uma instância criada.

    Para obter ajuda para criar uma instância do Cloud SQL, consulte Criação de instâncias .

  • Uma conta de usuário do PostgreSQL configurada na instância.

    Seu aplicativo usará esta conta para se conectar ao banco de dados. Para obter ajuda na criação de uma conta de usuário, consulte Criação de um usuário .

Sobre os segredos do Kubernetes

No Kubernetes, segredos são uma maneira segura de passar detalhes de configuração para sua aplicação. Você pode criar um segredo com detalhes como nome do seu banco de dados, usuário e senha, que podem ser inseridos na sua aplicação como variáveis ​​de ambiente.

Existem muitas maneiras diferentes de usar os segredos, dependendo do tipo de conexão:

  • Um segredo de credenciais de banco de dados inclui o nome do usuário do banco de dados com o qual você está se conectando e a senha do usuário do banco de dados.
  • Se estiver se conectando com o Cloud SQL Auth Proxy, um segredo poderá ser usado para armazenar o arquivo de credenciais da sua conta de serviço.
  • Se estiver se conectando com um IP privado, um Segredo pode ser usado para especificar o endereço IP privado da sua instância do Cloud SQL.

Para obter exemplos completos de como usar o Secrets, consulte os repositórios do GitHub referenciados mais adiante nesta página.

Criar um objeto secreto

  1. Você cria os objetos Secret usando o comando kubectl create secret .

    Para criar um segredo de credenciais de banco de dados:

    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. Depois de criados, você pode visualizar os objetos na seção Configuração da página do Google Kubernetes Engine no Google Cloud console .

Conecte-se ao Cloud SQL usando o Cloud SQL Auth Proxy

Ao se conectar usando o Cloud SQL Auth Proxy, o Cloud SQL Auth Proxy é adicionado ao seu pod usando o padrão de contêiner sidecar . O contêiner do Cloud SQL Auth Proxy está no mesmo pod que o seu aplicativo, o que permite que o aplicativo se conecte ao Cloud SQL Auth Proxy usando localhost , aumentando a segurança e o desempenho.

Para obter mais informações sobre o Cloud SQL Auth Proxy, consulte Sobre o Cloud SQL Auth Proxy . Para obter mais informações sobre como trabalhar com pods, consulte Visão geral dos pods na documentação do Kubernetes.

Para conectar usando o Cloud SQL Auth Proxy, você precisa do seguinte:

  1. O nome da conexão da instância da sua instância do Cloud SQL.

    O nome da conexão da instância está disponível na página de detalhes da instância do Cloud SQL. Google Cloud console ou do comando gcloud sql instances describe INSTANCE_ID .

  2. O local do arquivo de chave associado a uma conta de serviço com os privilégios adequados para sua instância do Cloud SQL.

    Consulte Criando uma conta de serviço para obter mais informações.

  3. A API de administração do Cloud SQL está habilitada.

    Enable the API

Forneça a conta de serviço ao Cloud SQL Auth Proxy

O primeiro passo para executar o Cloud SQL Auth Proxy no Google Kubernetes Engine é criar uma Conta de Serviço do Google (GSA) para representar seu aplicativo. Recomenda-se criar uma conta de serviço exclusiva para cada aplicativo, em vez de usar a mesma conta de serviço em todos os lugares. Este modelo é mais seguro, pois permite limitar as permissões por aplicativo.

A conta de serviço do seu aplicativo precisa atender aos seguintes critérios:

  • Pertence a um projeto com a API de administração do Cloud SQL habilitada
  • Foi concedida a função IAM do cliente Cloud SQL (ou equivalente) para o projeto que contém a instância à qual você deseja se conectar
  • Se estiver conectando usando IP privado, você deve usar um cluster GKE nativo de VPC, na mesma VPC que sua instância do Cloud SQL

Você precisa configurar o GKE para fornecer a conta de serviço ao Proxy de Autenticação do Cloud SQL. Há duas maneiras recomendadas de fazer isso: identidade da carga de trabalho ou um arquivo de chave da conta de serviço .

Identidade da Carga de Trabalho

Se você estiver usando o Google Kubernetes Engine , o método preferencial é usar o recurso de Identidade de Carga de Trabalho do GKE. Esse método permite vincular uma Conta de Serviço do Kubernetes (KSA) a uma Conta de Serviço do Google (GSA) . A GSA ficará então acessível aos aplicativos que usam a KSA correspondente.

Uma Conta de Serviço do Google (GSA) é uma identidade do IAM que representa seu aplicativo no Google Cloud. De forma semelhante, uma Conta de Serviço do Kubernetes (KSA) é uma identidade que representa seu aplicativo em um cluster do Google Kubernetes Engine.

A Identidade de Carga de Trabalho vincula um KSA a um GSA, fazendo com que qualquer implantação com esse KSA seja autenticada como GSA em suas interações com o Google Cloud.

  1. Habilitar identidade de carga de trabalho para seu cluster

  2. Normalmente, cada aplicativo tem sua própria identidade, representada por um par de KSA e GSA. Crie um KSA para seu aplicativo executando kubectl apply -f service-account.yaml : 

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

  3. Habilite a vinculação do IAM entre 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. Adicione uma anotação ao YOUR-KSA-NAME para completar a vinculação:

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

  5. Por fim, certifique-se de especificar a conta de serviço para o 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>

Arquivo de chave da conta de serviço

Como alternativa, se você não puder usar a Identidade de Carga de Trabalho, o padrão recomendado é montar um arquivo de chave de conta de serviço no pod do Proxy de Autenticação do Cloud SQL e usar o sinalizador --credentials-file .

  1. Crie um arquivo de credenciais para sua chave de conta de serviço:

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

  2. Transforme sua chave de conta de serviço em um segredo do k8s:

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

  3. Monte o segredo como um volume sob a spec: para seu objeto k8s: 

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

  4. Siga as instruções na próxima seção para acessar o volume do pod do Cloud SQL Auth Proxy.

Execute o Cloud SQL Auth Proxy em um padrão sidecar

Recomendamos executar o Cloud SQL Auth Proxy em um padrão sidecar (como um contêiner adicional compartilhando um pod com seu aplicativo). Recomendamos isso em vez de executar como um serviço separado por vários motivos:

  • Impede que seu tráfego SQL seja exposto localmente; o Cloud SQL Auth Proxy fornece criptografia em conexões de saída, mas você precisa limitar a exposição para conexões de entrada.
  • Evita um único ponto de falha; o acesso de cada aplicativo ao seu banco de dados é independente dos outros, tornando-o mais resiliente.
  • Limita o acesso ao Cloud SQL Auth Proxy, permitindo que você use permissões do IAM por aplicativo em vez de expor o banco de dados ao cluster inteiro.

  • Permite que você defina o escopo de solicitações de recursos com mais precisão; como o Cloud SQL Auth Proxy consome recursos linearmente em relação ao uso, esse padrão permite que você defina o escopo e solicite recursos com mais precisão para corresponder aos seus aplicativos à medida que eles são dimensionados.

  • Adicione o Cloud SQL Auth Proxy à configuração do pod em 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"

    Se você estiver usando uma chave de conta de serviço, especifique seu volume secreto e adicione o sinalizador --credentials-file ao 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 fim, configure seu aplicativo para se conectar usando 127.0.0.1 em qualquer DB_PORT que você especificou na seção de comando.

Arquivos de configuração de exemplo completos:

Identidade da carga de trabalho 

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

Chave da conta de serviço 

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

Conecte-se ao Cloud SQL sem o Cloud SQL Auth Proxy

Embora não seja tão seguro, é possível conectar-se de um cluster GKE nativo de VPC a uma instância do Cloud SQL na mesma VPC usando um IP privado sem o Cloud SQL Auth Proxy.

  1. Crie um segredo com o endereço IP privado da sua instância: 

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

  2. Em seguida, certifique-se de adicionar o segredo ao contêiner do seu aplicativo: 

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

  3. Por fim, configure sua aplicação para se conectar usando o endereço IP da variável de ambiente DB_HOST . Você precisará usar a porta correta para o PostgreSQL: 5432.

Arquivo de configuração de exemplo completo:

IP privado 

# 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

Solução de problemas

Precisa de ajuda? Para obter ajuda na solução de problemas do proxy, consulte Solução de problemas de conexões do Cloud SQL Auth Proxy ou consulte nossa página de suporte do Cloud SQL .

O que vem a seguir