Instale o Kf

Este documento descreve como configurar um cluster do GKE e, em seguida, instalar o Kf e as respetivas dependências.

Antes de começar

Vista geral

Nota: atualmente, os clusters do GKE Autopilot não conseguem executar o Kf. Use um cluster do GKE padrão. Para mais informações acerca destes modos e para saber mais sobre o Autopilot, consulte a vista geral do Autopilot.

Requisitos do cluster do GKE.

• Opcional, mas recomendado. O cluster deve ser dedicado ao Kf. Recomendamos que instale apenas o Kf e as respetivas dependências para garantir que a matriz de compatibilidade é mantida.

• Pelo menos, quatro nós. Se precisar de adicionar nós, consulte o artigo Redimensionar um cluster.

• O tipo de máquina mínimo que tem, pelo menos, quatro vCPUs, como e2-standard-4. Se o tipo de máquina do seu cluster não tiver, pelo menos, quatro vCPUs, altere o tipo de máquina conforme descrito no artigo Migrar cargas de trabalho para diferentes tipos de máquinas.

• Opcional, mas recomendado, inscreva o cluster num canal de lançamento. Siga as instruções em Inscrever um cluster existente num canal de lançamento se tiver uma versão estática do GKE.

• Workload Identity ativado.

Requisitos do Kf. A matriz de dependências apresenta as versões específicas.

• Artifact Registry.

• Cloud Service Mesh.

• Config Connector.

• Tekton para utilização pelo Kf. Este não é um serviço orientado para o utilizador.

• Uma conta de serviço Google dedicada.

Nota: a secção Limpar tem instruções sobre como eliminar o cluster.

Ative o suporte para o Compute Engine

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. Ative a API Compute Engine.

   Ative a API

Ative o suporte para o Artifact Registry

1. Ative a API Artifact Registry.

   Ative a API Artifact Registry

Ative e configure o GKE

Antes de começar, certifique-se de que realizou as seguintes tarefas:

• Ative a API Google Kubernetes Engine.
Ative a API Google Kubernetes Engine
• Se quiser usar a CLI gcloud para esta tarefa, instale-a e, em seguida, inicialize-a. Se instalou anteriormente a CLI gcloud, execute gcloud components update para obter a versão mais recente.
  Nota: para instalações existentes da CLI gcloud, certifique-se de que define a compute/region propriedade. Se usar principalmente clusters zonais, defina o compute/zone. Ao definir uma localização predefinida, pode evitar erros na CLI gcloud, como os seguintes: One of [--zone, --region] must be supplied: Please specify location. Pode ter de especificar a localização em determinados comandos se a localização do seu cluster for diferente da predefinição que definiu.

Prepare um novo cluster do GKE e serviços relacionados

Configure variáveis de ambiente

Nota: exporte estas variáveis de ambiente no terminal ou no Cloud Shell para que os comandos subsequentes funcionem. Se se desligar do ambiente de shell e voltar a ligar mais tarde, tem de configurar as variáveis novamente.

Linux e Mac

export PROJECT_ID=YOUR_PROJECT_ID
export CLUSTER_PROJECT_ID=YOUR_PROJECT_ID
export CLUSTER_NAME=kf-cluster
export COMPUTE_ZONE=us-central1-a
export COMPUTE_REGION=us-central1
export CLUSTER_LOCATION=${COMPUTE_ZONE} # Replace ZONE with REGION to switch
export NODE_COUNT=4
export MACHINE_TYPE=e2-standard-4
export NETWORK=default

Windows PowerShell

Set-Variable -Name PROJECT_ID -Value YOUR_PROJECT_ID
Set-Variable -Name CLUSTER_PROJECT_ID -Value YOUR_PROJECT_ID
Set-Variable -Name CLUSTER_NAME -Value kf-cluster
Set-Variable -Name COMPUTE_ZONE -Value us-central1-a
Set-Variable -Name COMPUTE_REGION -Value us-central1
Set-Variable -Name CLUSTER_LOCATION -Value $COMPUTE_ZONE # Replace ZONE with REGION to switch
Set-Variable -Name NODE_COUNT -Value 4
Set-Variable -Name MACHINE_TYPE -Value e2-standard-4
Set-Variable -Name NETWORK -Value default

Configuração da conta de serviço

Crie uma conta de serviço do GCP (GSA) que vai ser associada a uma conta de serviço do Kubernetes através do Workload Identity. Isto evita a necessidade de criar e injetar uma chave de conta de serviço.

Nota: leia e compreenda as implicações de segurança da utilização da identidade da carga de trabalho no documento Vista geral da segurança.

1. Crie a conta de serviço que o Kf vai usar.

   gcloud iam service-accounts create ${CLUSTER_NAME}-sa \
   --project=${CLUSTER_PROJECT_ID} \
   --description="GSA for Kf ${CLUSTER_NAME}" \
   --display-name="${CLUSTER_NAME}"

2. Crie uma nova função personalizada do IAM.

   gcloud iam roles create serviceAccountUpdater \
   --project=${CLUSTER_PROJECT_ID} \
   --title "Service Account Updater" \
   --description "This role only updates members on a GSA" \
   --permissions iam.serviceAccounts.get,iam.serviceAccounts.getIamPolicy,iam.serviceAccounts.list,iam.serviceAccounts.setIamPolicy

3. Permitir que a conta de serviço modifique a respetiva política. O controlador Kf usa esta opção para adicionar novos espaços de nomes à política, o que permite a reutilização para a identidade de carga de trabalho.

   gcloud projects add-iam-policy-binding ${CLUSTER_PROJECT_ID} \
     --member="serviceAccount:${CLUSTER_NAME}-sa@${CLUSTER_PROJECT_ID}.iam.gserviceaccount.com" \
     --role="projects/${CLUSTER_PROJECT_ID}/roles/serviceAccountUpdater"

4. Atribua a função de métricas de monitorização para acesso de escrita ao Cloud Monitoring.

   gcloud projects add-iam-policy-binding ${CLUSTER_PROJECT_ID} \
     --member="serviceAccount:${CLUSTER_NAME}-sa@${CLUSTER_PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/monitoring.metricWriter"

5. Atribua a função de registo para acesso de escrita ao Cloud Logging.

   gcloud projects add-iam-policy-binding ${CLUSTER_PROJECT_ID} \
     --member="serviceAccount:${CLUSTER_NAME}-sa@${CLUSTER_PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/logging.logWriter"

Crie um cluster do GKE

Nota: para fins de demonstração, estas instruções usam um cluster zonal. Para implementações de produção, recomenda-se um cluster regional.

gcloud container clusters create ${CLUSTER_NAME} \
  --project=${CLUSTER_PROJECT_ID} \
  --zone=${CLUSTER_LOCATION} \
  --num-nodes=${NODE_COUNT} \
  --machine-type=${MACHINE_TYPE} \
  --network=${NETWORK} \
  --addons=HttpLoadBalancing,HorizontalPodAutoscaling,NetworkPolicy \
  --enable-stackdriver-kubernetes \
  --enable-ip-alias \
  --enable-network-policy \
  --enable-autorepair \
  --enable-autoupgrade \
  --scopes=https://www.googleapis.com/auth/cloud-platform \
  --release-channel=regular \
  --workload-pool="${CLUSTER_PROJECT_ID}.svc.id.goog" \
  --service-account="${CLUSTER_NAME}-sa@${CLUSTER_PROJECT_ID}.iam.gserviceaccount.com"

Defina regras de firewall

O Kf requer que algumas portas da firewall estejam abertas. O nó principal tem de conseguir comunicar com pods nas portas 80, 443, 8080, 8443 e 6443.

Ative o Workload Identity

Agora que tem uma conta de serviço e um cluster do GKE, associe o espaço de nomes de identidade do cluster ao cluster.

gcloud iam service-accounts add-iam-policy-binding \
  --project=${CLUSTER_PROJECT_ID} \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:${CLUSTER_PROJECT_ID}.svc.id.goog[kf/controller]" \
  "${CLUSTER_NAME}-sa@${CLUSTER_PROJECT_ID}.iam.gserviceaccount.com"

gcloud iam service-accounts add-iam-policy-binding \
  --project=${CLUSTER_PROJECT_ID} \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:${CLUSTER_PROJECT_ID}.svc.id.goog[cnrm-system/cnrm-controller-manager]" \
  "${CLUSTER_NAME}-sa@${CLUSTER_PROJECT_ID}.iam.gserviceaccount.com"

Cluster do GKE de destino

Configure o acesso à linha de comandos kubectl executando o seguinte comando.

gcloud container clusters get-credentials ${CLUSTER_NAME} \
    --project=${CLUSTER_PROJECT_ID} \
    --zone=${CLUSTER_LOCATION}

Crie um repositório do Artifact Registry

1. Crie um Artifact Registry para armazenar imagens de contentores.

   gcloud artifacts repositories create ${CLUSTER_NAME} \
     --project=${CLUSTER_PROJECT_ID} \
     --repository-format=docker \
     --location=${COMPUTE_REGION}

2. Conceda autorização à conta de serviço no repositório do Artifact Registry.

   gcloud artifacts repositories add-iam-policy-binding ${CLUSTER_NAME} \
     --project=${CLUSTER_PROJECT_ID} \
     --location=${COMPUTE_REGION} \
     --member="serviceAccount:${CLUSTER_NAME}-sa@${CLUSTER_PROJECT_ID}.iam.gserviceaccount.com" \
     --role='roles/artifactregistry.writer'

Instale dependências de software no cluster

Nota: a matriz de dependências na página Transferências do Kf tem versões fixas para a versão do Kf especificada.

1. Instale a malha de serviço.

   1. Abra o guia de instalação do Cloud Service Mesh.

   2. Certifique-se de que o menu pendente de versões está definido para a versão 1.9 do Cloud Service Mesh.

   3. Siga o guia para instalar o ASM.

2. Instale o Config Connector.

   Nota: o Config Connector é necessário a partir do Kf v2.4.0.
   Aviso: não use o método de suplemento do GKE para instalar o Config Connector, uma vez que não é suportado pelo Kf. Use estes passos de instalação personalizados.

   1. Transfira o ficheiro tar do operador do Config Connector necessário.

      Nota: mantenha uma cópia do pacote de instalação, uma vez que precisa deste pacote para desinstalar o Config Connector.

   2. Extraia o ficheiro TAR.

      tar zxvf release-bundle.tar.gz

   3. Instale o operador do Config Connector no seu cluster.

      kubectl apply -f operator-system/configconnector-operator.yaml

   4. Configure o operador do Config Connector.

      1. Copie o seguinte YAML para um ficheiro com o nome configconnector.yaml:

         Aviso: substitua a variável KF_SERVICE_ACCOUNT_NAME no YAML abaixo pela conta de serviço completa resolvida a partir de ${CLUSTER_NAME}-sa@${CLUSTER_PROJECT_ID}.iam.gserviceaccount.com

         # configconnector.yaml
         apiVersion: core.cnrm.cloud.google.com/v1beta1
         kind: ConfigConnector
         metadata:
           # the name is restricted to ensure that there is only one
           # ConfigConnector resource installed in your cluster
           name: configconnector.core.cnrm.cloud.google.com
         spec:
           mode: cluster
           googleServiceAccount: "KF_SERVICE_ACCOUNT_NAME" # Replace with the full service account resolved from ${CLUSTER_NAME}-sa@${CLUSTER_PROJECT_ID}.iam.gserviceaccount.com

      2. Aplique a configuração ao cluster.

         kubectl apply -f configconnector.yaml

   5. Verifique se o Config Connector está totalmente instalado antes de continuar.

      • O Config Connector executa todos os respetivos componentes num espaço de nomes denominado cnrm-system. Verifique se os pods estão prontos executando o seguinte comando:

        Nota: o controlador Pod pode demorar vários minutos a iniciar, pelo que este comando pode não funcionar imediatamente.

        kubectl wait -n cnrm-system --for=condition=Ready pod --all

      • Se o Config Connector estiver instalado corretamente, deverá ver um resultado semelhante ao seguinte:

        pod/cnrm-controller-manager-0 condition met
        pod/cnrm-deletiondefender-0 condition met
        pod/cnrm-resource-stats-recorder-86858dcdc5-6lqzb condition met
        pod/cnrm-webhook-manager-58c799b8fb-kcznq condition met
        pod/cnrm-webhook-manager-58c799b8fb-n2zpx condition met

   6. Configure o Workload Identity.

      kubectl annotate serviceaccount \
      --namespace cnrm-system \
      --overwrite \
      cnrm-controller-manager \
      iam.gke.io/gcp-service-account=${CLUSTER_NAME}-sa@${CLUSTER_PROJECT_ID}.iam.gserviceaccount.com

3. Instale o Tekton:

   kubectl apply -f "https://storage.googleapis.com/tekton-releases/pipeline/previous/v0.23.0/release.yaml"

Instale o Kf

Nota: certifique-se de que o cluster cumpre os requisitos indicados no artigo Crie e prepare um cluster do GKE para o Kf.

1. Instale a CLI Kf:

   Linux

   Este comando instala a CLI do Kf para todos os utilizadores no sistema. Siga as instruções no separador do Cloud Shell para o instalar apenas para si.

   gcloud storage cp gs://kf-releases/v2.4.1/kf-linux /tmp/kf
   chmod a+x /tmp/kf
   sudo mv /tmp/kf /usr/local/bin/kf

   Mac

   Este comando instala o kf para todos os utilizadores no sistema.

   gcloud storage cp gs://kf-releases/v2.4.1/kf-darwin /tmp/kf
   chmod a+x /tmp/kf
   sudo mv /tmp/kf /usr/local/bin/kf

   Cloud Shell

   Este comando instala o kf na sua instância do Cloud Shell se usar o bash. Caso contrário, pode ter de modificar as instruções para outras shells.

   mkdir -p ~/bin
   gcloud storage cp gs://kf-releases/v2.4.1/kf-linux ~/bin/kf
   chmod a+x ~/bin/kf
   echo "export PATH=$HOME/bin:$PATH" >> ~/.bashrc
   source ~/.bashrc

   Windows

   Este comando transfere kf para o diretório atual. Adicione-o ao caminho se quiser chamá-lo a partir de qualquer outro local que não seja o diretório atual.

   gcloud storage cp gs://kf-releases/v2.4.1/kf-windows.exe kf.exe

2. Instale o operador:

   kubectl apply -f "https://storage.googleapis.com/kf-releases/v2.4.1/operator.yaml"

3. Configure o operador para o Kf:

   kubectl apply -f "https://storage.googleapis.com/kf-releases/v2.4.1/kfsystem.yaml"

4. Configure segredos e predefinições:

   export CONTAINER_REGISTRY=${COMPUTE_REGION}-docker.pkg.dev/${CLUSTER_PROJECT_ID}/${CLUSTER_NAME}
   
   kubectl patch \
   kfsystem kfsystem \
   --type='json' \
   -p="[{'op': 'replace', 'path': '/spec/kf', 'value': {'enabled': true, 'config': {'spaceContainerRegistry': '${CONTAINER_REGISTRY}', 'secrets':{'workloadidentity':{'googleserviceaccount':'${CLUSTER_NAME}-sa', 'googleprojectid':'${CLUSTER_PROJECT_ID}'}}}}}]"
   

Valide a instalação

  kf doctor --retries=20

Nota: este comando inspeciona o cluster para garantir que o Kf e as respetivas dependências estão instalados e a funcionar. É executado até 20 vezes para dar tempo ao cluster do Kubernetes para reconciliar e deve resultar numa série de resultados PASS. Se o estado de qualquer componente resultar em FAIL após as novas tentativas, consulte a página de resolução de problemas do Kf.

Limpar

Estes passos devem remover todos os componentes criados na secção Crie e prepare um novo cluster do GKE.

1. Elimine a conta de serviço Google:

   gcloud iam service-accounts delete ${CLUSTER_NAME}-sa@${CLUSTER_PROJECT_ID}.iam.gserviceaccount.com

2. Elimine vinculações de políticas de IAM:

   gcloud projects remove-iam-policy-binding ${CLUSTER_PROJECT_ID} \
     --member="serviceAccount:${CLUSTER_NAME}-sa@${CLUSTER_PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/storage.admin"
   
   gcloud projects remove-iam-policy-binding ${CLUSTER_PROJECT_ID} \
     --member="serviceAccount:${CLUSTER_NAME}-sa@${CLUSTER_PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/iam.serviceAccountAdmin"
   
   gcloud projects remove-iam-policy-binding ${CLUSTER_PROJECT_ID} \
     --member="serviceAccount:${CLUSTER_NAME}-sa@${CLUSTER_PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/monitoring.metricWriter"

3. Elimine o repositório de imagens de contentores:

   gcloud artifacts repositories delete ${CLUSTER_NAME} \
     --location=${COMPUTE_REGION}

4. Eliminar cluster do GKE:

   gcloud container clusters delete ${CLUSTER_NAME} --zone ${CLUSTER_LOCATION}