Estabeleça ligação a partir do Google Kubernetes Engine

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

Para obter instruções passo a passo sobre a execução de uma aplicação Web de exemplo do Google Kubernetes Engine ligada ao Cloud SQL, consulte o início rápido para estabelecer ligação a partir do Google Kubernetes Engine.

O Cloud SQL é um serviço de base de dados totalmente gerido que ajuda na configuração, manutenção, gestão e administração das suas bases de dados relacionais na nuvem.

O Google Kubernetes Engine é uma forma simples de implementar, dimensionar e gerir automaticamente o Kubernetes.

Acerca da ligação do Google Kubernetes Engine ao Cloud SQL

Para aceder a uma instância do Cloud SQL a partir de uma aplicação em execução no Google Kubernetes Engine, pode usar o proxy Auth do Cloud SQL (com IP público ou privado) ou ligar diretamente através de um endereço IP privado.

O proxy Auth do Cloud SQL é a forma recomendada de estabelecer ligação ao Cloud SQL, mesmo quando usa o IP privado. Isto acontece porque o proxy Auth do Cloud SQL oferece uma encriptação forte e autenticação através da IAM, o que pode ajudar a manter a sua base de dados segura.

As ligações à base de dados consomem recursos no servidor e na aplicação de ligação. Use sempre boas práticas de gestão de ligações para minimizar a pegada da sua aplicação e reduzir a probabilidade de exceder os limites de ligações do Cloud SQL. Para mais informações, consulte o artigo Faça a gestão das ligações à base de dados.

Antes de começar

Para estabelecer ligação ao Cloud SQL, tem de ter:

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

    Para obter ajuda nos primeiros passos com o GKE, consulte o artigo Implemente uma app num cluster do GKE.

    Para estabelecer ligação através do IP privado, o cluster do GKE tem de ser nativo da VPC e ter uma relação de interligação com a mesma rede de nuvem virtual privada (VPC) que a instância do Cloud SQL.

  • Uma instância criada.

    Para obter ajuda na criação de uma instância do Cloud SQL, consulte o artigo Criar instâncias.

  • Uma conta de utilizador do SQL Server configurada na instância.

    A sua aplicação vai usar esta conta para estabelecer ligação à base de dados. Para obter ajuda com a criação de uma conta de utilizador, consulte o artigo Criar um utilizador.

Acerca dos segredos do Kubernetes

No Kubernetes, os segredos são uma forma segura de transmitir detalhes de configuração à sua aplicação. Pode criar um segredo com detalhes como o nome da base de dados, o utilizador e a palavra-passe que podem ser injetados na sua aplicação como variáveis de ambiente.

Existem muitas formas diferentes de usar os segredos, consoante o tipo de ligação:

  • Um segredo de credenciais da base de dados inclui o nome do utilizador da base de dados ao qual se está a ligar e a palavra-passe da base de dados do utilizador.
  • Se estiver a estabelecer ligação com o proxy Auth do Cloud SQL, pode usar um segredo para guardar o ficheiro de credenciais da sua conta de serviço.
  • Se estiver a estabelecer ligação com um IP privado, pode usar um segredo para especificar o endereço IP privado da sua instância do Cloud SQL.

Para ver exemplos completos de como usar segredos, consulte os repositórios do GitHub referidos mais adiante nesta página.

Crie um objeto Secret

  1. Crie os objetos Secret com o comando kubectl create secret.

    Para criar um segredo de credenciais da base 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, pode ver os objetos na secção Configuração da página do Google Kubernetes Engine na Google Cloud consola.

Estabeleça ligação ao Cloud SQL através do proxy Auth do Cloud SQL

Quando se liga através do proxy Auth do Cloud SQL, o proxy Auth do Cloud SQL é adicionado ao seu pod através do padrão de contentor sidecar. O contentor do proxy Auth do Cloud SQL está no mesmo pod que a sua aplicação, o que permite à aplicação ligar-se ao proxy Auth do Cloud SQL através de localhost, aumentando a segurança e o desempenho.

Para mais informações sobre o proxy Auth do Cloud SQL, consulte o artigo Acerca do proxy Auth do Cloud SQL. Para mais informações sobre como trabalhar com pods, consulte o artigo Vista geral dos pods na documentação do Kubernetes.

Para estabelecer ligação através do proxy Auth do Cloud SQL, precisa do seguinte:

  1. O nome de ligação da instância da sua instância do Cloud SQL.

    O nome de ligação da instância está disponível na página Detalhes da instância do Cloud SQL da Google Cloud consola ou no comando gcloud sql instances describe INSTANCE_ID.

  2. A localização do ficheiro de chave associado a uma conta de serviço com os privilégios adequados para a sua instância do Cloud SQL.

    Consulte o artigo Criar uma conta de serviço para mais informações.

  3. A API Admin do Cloud SQL está ativada.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

Faculte a conta de serviço ao proxy Auth do Cloud SQL

O primeiro passo para executar o Cloud SQL Auth Proxy no Google Kubernetes Engine é criar uma conta de serviço Google (GSA) para representar a sua aplicação. Recomendamos que crie uma conta de serviço exclusiva para cada aplicação, em vez de usar a mesma conta de serviço em todos os casos. Este modelo é mais seguro, uma vez que lhe permite limitar as autorizações por aplicação.

A conta de serviço da sua aplicação tem de cumprir os seguintes critérios:

  • Pertencer a um projeto com a API Admin do Cloud SQL ativada
  • Foi-lhe concedida a função de IAM de cliente do Cloud SQL (ou equivalente) para o projeto que contém a instância à qual quer ligar-se
  • Se estiver a estabelecer ligação através de um IP privado, tem de usar um cluster do GKE nativo da VPC na mesma VPC que a sua instância do Cloud SQL

Tem de configurar o GKE para fornecer a conta de serviço ao Cloud SQL Auth Proxy. Existem duas formas recomendadas de o fazer: identidade da carga de trabalho ou um ficheiro de chave da conta de serviço.

Workload Identity

Se estiver a usar o Google Kubernetes Engine, o método preferencial é usar a funcionalidade Workload Identity do GKE. Este método permite-lhe associar uma conta de serviço do Kubernetes (KSA) a uma conta de serviço da Google (GSA). Em seguida, o GSA fica acessível às aplicações que usam o KSA correspondente.

Uma conta de serviço Google (GSA) é uma identidade da IAM que representa a sua aplicação no Google Cloud. Da mesma forma, uma conta de serviço do Kubernetes (KSA) é uma identidade que representa a sua aplicação num cluster do Google Kubernetes Engine.

O Workload Identity associa um KSA a um GSA, fazendo com que todas as implementações com esse KSA sejam autenticadas como o GSA nas respetivas interações com o Google Cloud.

  1. Ative o Workload Identity para o seu cluster

  2. Normalmente, cada aplicação tem a sua própria identidade, representada por um par KSA e GSA. Crie um KSA para a sua aplicação executando o seguinte comando: kubectl apply -f service-account.yaml:

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

  3. Ative a vinculação da IAM entre o seu YOUR-GSA-NAME e o 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 a YOUR-KSA-NAME para concluir a associaçã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 último, certifique-se de que especifica 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>

Ficheiro de chave da conta de serviço

Em alternativa, se não puder usar a Workload Identity, o padrão recomendado é montar um ficheiro de chave da conta de serviço no pod do Cloud SQL Auth Proxy e usar a flag --credentials-file.

  1. Crie um ficheiro de credenciais para a chave da conta de serviço:

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

  2. Transforme a chave da conta de serviço num segredo do k8s:

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

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

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

  4. Siga as instruções na secção seguinte para aceder ao volume a partir do pod do proxy Auth do Cloud SQL.

Execute o proxy Auth do Cloud SQL num padrão de sidecar

Recomendamos que execute o proxy Auth do Cloud SQL num padrão sidecar (como um contentor adicional que partilha um pod com a sua aplicação). Recomendamos esta opção em vez de executar o serviço como um serviço separado por vários motivos:

  • Impede que o seu tráfego SQL seja exposto localmente. O proxy Auth do Cloud SQL fornece encriptação nas ligações de saída, mas tem de limitar a exposição para as ligações de entrada.
  • Impede um único ponto de falha. O acesso de cada aplicação à sua base de dados é independente das outras, o que a torna mais resiliente.
  • Limita o acesso ao proxy Auth do Cloud SQL, o que lhe permite usar autorizações da IAM por aplicação em vez de expor a base de dados a todo o cluster.

  • Permite-lhe definir o âmbito dos pedidos de recursos com maior precisão. Uma vez que o Cloud SQL Auth Proxy consome recursos linearmente à utilização, este padrão permite-lhe definir o âmbito e pedir recursos com maior precisão para corresponder às suas aplicações à medida que são dimensionadas.

  • Adicione o proxy Auth do Cloud SQL à 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 estiver a usar uma chave de conta de serviço, especifique o volume secreto e adicione a flag --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 a sua aplicação para estabelecer ligação através de 127.0.0.1 no DB_PORT que especificou na secção de comandos.

Ficheiros de configuração de exemplo completos:

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"

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>

Estabeleça ligação ao Cloud SQL sem o proxy Auth do Cloud SQL

Embora não seja tão seguro, é possível estabelecer ligação a partir de um cluster do GKE nativo da VPC a uma instância do Cloud SQL na mesma VPC através de um IP privado sem o proxy Auth do Cloud SQL.

  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 que adiciona o segredo ao contentor da sua aplicação:

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

  3. Por último, configure a sua aplicação para estabelecer ligação através do endereço IP da variável de ambiente DB_HOST. Tem de usar a porta correta para o SQL Server: 1433

Ficheiro 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

Resolução de problemas

Precisa de ajuda? Para obter ajuda na resolução de problemas do proxy, consulte o artigo Resolução de problemas de ligações do proxy Auth do Cloud SQL ou consulte a nossa página de apoio técnico do Cloud SQL.

O que se segue?