Configurar o operador do Cluster Services for OpenShift Telemetry

Neste documento, descrevemos como instalar o operador do Cluster Services for OpenShift Telemetry e configurá-lo para se conectar a um cluster do OpenShift que é executado em uma instância do Compute Engine.

Depois de instalar e configurar, esse operador de telemetria implanta um daemon de telemetria de rede de host que monitora continuamente a integridade e a configuração do cluster. O operador envia as métricas coletadas para o Workload Manager. Em seguida, use a avaliação do Workload Manager para verificar se as cargas de trabalho em execução no cluster estão de acordo com as práticas recomendadas para clusters do OpenShift.

Antes de começar

Antes de instalar e configurar o operador de telemetria, verifique se os seguintes pré-requisitos foram atendidos:

Ativar o acesso às APIs do Cloud

O Compute Engine recomenda configurar as instâncias para permitir todos os escopos de acesso a todas as APIs do Cloud, assim como recomenda usar apenas as permissões do IAM da conta de serviço da instância para controlar o acesso aos recursos do Google Cloud . Para mais informações, consulte Criar uma VM que usa uma conta serviço gerenciado pelo usuário.

Se você limitar o acesso às APIs do Cloud, o operador do Cluster Services for OpenShift Telemetry exigirá, no mínimo, os seguintes escopos de acesso às APIs do Cloud na instância de computação do host:

https://www.googleapis.com/auth/cloud-platform

Para mais informações, consulte Práticas recomendadas de escopos.

Se você estiver executando um cluster do OpenShift em uma instância de computação que não tenha um endereço IP externo, ative o Acesso privado do Google na sub-rede da instância para que o operador do Cluster Services for OpenShift Telemetry possa acessar as APIs e os serviços do Google. Para saber como ativar o Acesso privado do Google, consulte Configurar o Acesso privado do Google.

Autenticar usuários no cluster do OpenShift

Para realizar ações administrativas, você ou seus usuários precisam ser autenticados no cluster do OpenShift usando a CLI do OpenShift. Para autenticar usuários no cluster do OpenShift, escolha uma das seguintes opções:

  • Execute o comando a seguir e siga as instruções:

    oc login "https://api.CLUSTER_DOMAIN:6443" -u kubeadmin

  • Como alternativa, receba um token de autenticação de sessão para usar com o binário oc. Para receber esse token, abra o seguinte URL em um navegador da Web:

    https://oauth-openshift.apps.CLUSTER_DOMAIN/oauth/token/request

Substitua CLUSTER_DOMAIN pelo domínio do cluster do OpenShift. Por exemplo, mycluster.google.com.

Autenticar o operador no Google Cloud

Para permitir que o operador de telemetria se autentique e acesse os recursos do Google Cloud, crie uma conta de serviço para ele no projeto do Google Cloud .

É possível autenticar o operador de telemetria como a conta de serviço usando as seguintes opções:

Autenticar o operador usando a federação de identidade da carga de trabalho

Para autenticar o operador de telemetria como a conta de serviço usando a federação de identidade da carga de trabalho, siga estas etapas:

  1. No terminal, extraia o manifesto CredentialsRequest do pacote do operador de telemetria para um diretório local:

    mkdir -p credrequests
oc image extract us-docker.pkg.dev/workload-agent-products/cluster-services-for-openshift-telemetry/bundle:VERSION --path /manifests/:./credrequests --confirm

    Substitua VERSION pelo número da versão que você assinou para o operador de telemetria no OperatorHub. Confira a lista de números de versão certificados para o operador de telemetria no catálogo do ecossistema da Red Hat.

  2. Usando o utilitário ccoctl, processe o manifesto CredentialsRequest extraído e provisione as vinculações e credenciais do Identity and Access Management (IAM) de Google Cloud :

    • (Recomendado) Para o OpenShift versão 4.22 ou mais recente:

      Recomendamos o uso do OpenShift versão 4.22 ou mais recente com a flag --key-storage-method=pool-jwk-file para armazenar o conjunto de chaves da Web JSON (JWKS, na sigla em inglês) do cluster diretamente no provedor de pool de Identidade da carga de trabalho, eliminando a criação de um bucket do Cloud Storage:

      ccoctl gcp create-all \
  --name=NAME \
  --region=REGION \
  --project=PROJECT_ID \
  --credentials-requests-dir=./credrequests \
  --output-dir=./ccoctl-out \
  --key-storage-method=pool-jwk-file

    • Para as versões 4.18 a 4.21 do OpenShift:

      Depois de instalar o operador de telemetria, você também precisa concluir a etapa obrigatória de pós-instalação para restringir o provedor de federação de identidade da carga de trabalho.

      ccoctl gcp create-all \
  --name=NAME \
  --region=REGION \
  --project=PROJECT_ID \
  --credentials-requests-dir=./credrequests \
  --output-dir=./ccoctl-out

    Substitua:

    • NAME: um nome para as credenciais e os recursos criados pelo utilitário ccoctl. Recomendamos especificar um nome exclusivo e altamente aleatório (como incluir um sufixo alfanumérico aleatório) para o cluster ou a organização.
    • REGION: a região do Compute Engine em que o cluster do OpenShift é executado.
    • PROJECT_ID: o ID do projeto do Google Cloud projeto em que o cluster do OpenShift é executado

  3. Aplique o provedor do OpenID Connect (OIDC) gerado, os papéis do IAM e os manifestos de secret ao cluster:

    oc apply -f ./ccoctl-out/manifests/

As etapas anteriores criam uma conta de serviço no seu projeto do Google Cloud e atribuem a ela os seguintes papéis do IAM:

Autenticar o operador usando uma chave de conta de serviço

Se a organização não for compatível com o uso da federação de identidade da carga de trabalho para fins de autenticação, será possível autenticar o operador de telemetria usando uma chave de conta de serviço.

Para autenticar o operador de telemetria como a conta de serviço usando uma chave de conta de serviço, siga estas etapas:

  1. No terminal, extraia o manifesto CredentialsRequest do pacote do operador de telemetria para um diretório local:

    mkdir -p credrequests
oc image extract us-docker.pkg.dev/workload-agent-products/cluster-services-for-openshift-telemetry/bundle:VERSION --path /manifests/:./credrequests --confirm

  2. No projeto do Google Cloud , crie uma conta de serviço para o operador de telemetria:

    gcloud iam service-accounts create cso-telemetry-agent \
  --description="Service account for OpenShift Telemetry Operator" \
  --display-name="CSO Telemetry Agent" \
  --project=PROJECT_ID

    Substitua PROJECT_ID pelo ID do projeto doGoogle Cloud em que o cluster do OpenShift é executado.

  3. Para permitir que a conta de serviço acesse os recursos do Google Cloud , conceda a ela os papéis do IAM definidos no manifesto CredentialsRequest. Esse manifesto inclui o seguinte conjunto mínimo de papéis do IAM que o operador precisa:

    Para cada papel do IAM definido nesse manifesto, execute o seguinte comando:

    gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:cso-telemetry-agent@PROJECT_ID.iam.gserviceaccount.com" \
  --role="IAM_ROLE"

    Substitua IAM_ROLE pelo papel do IAM que você quer conceder à conta de serviço.

  4. Crie e faça o download de uma chave privada para a conta de serviço:

    gcloud iam service-accounts keys create ./sa_key.json \
  --iam-account=cso-telemetry-agent@PROJECT_ID.iam.gserviceaccount.com \
  --project=PROJECT_ID

  5. No namespace openshift-operators, crie um secret chamado telemetry-agent-sa para a chave da conta de serviço que você criou:

    oc create secret generic telemetry-agent-sa \
  --from-file=workload_agent_sa_key.json=./sa_key.json \
  -n openshift-operators

Instalar o operador Cluster Services for OpenShift Telemetry

É possível instalar o operador do Cluster Services for OpenShift Telemetry usando o console da Web da plataforma de contêineres do Red Hat OpenShift ou os manifestos YAML de assinatura declarativa. Para informações sobre essas opções, consulte o documento da Red Hat Como adicionar operadores a um cluster.

Console da Web do OpenShift

Para instalar o operador de telemetria no cluster do OpenShift usando o console da Web do OpenShift Container Platform, siga estas etapas:

  1. Faça login no console da Web do Red Hat OpenShift.
  2. Verifique se você está na perspectiva Administrador.
  3. Na navegação à esquerda, expanda a seção Operadores e clique em OperatorHub.

  4. Na barra de pesquisa em Todos os itens, digite Cluster Services for OpenShift Telemetry.

    Você também pode pesquisar digitando Google. Isso filtra os operadores fornecidos pelo Google, incluindo o operador Cluster Services for OpenShift Telemetry.

  5. Clique no card chamado Cluster Services for OpenShift Telemetry.

  6. No painel Cluster Services for OpenShift Telemetry, clique em Instalar.

  7. Na página Instalar operador, siga estas etapas:

    1. No campo Canal de atualização, selecione estável.
    2. No campo Modo de instalação, selecione Um namespace específico no cluster.
    3. No campo Namespace instalado, selecione o projeto openshift-operators ou crie um namespace de monitoramento personalizado.
    4. No campo Estratégia de aprovação, selecione Automática ou Manual.
    5. Clique em Instalar.

  8. Para verificar se o operador foi instalado, siga estas etapas:

    1. Acesse Operadores > Operadores instalados.
    2. Na lista de operadores, pesquise e verifique se o operador Cluster Services for OpenShift Telemetry está presente.
    3. Verifique se a coluna Status mostra o valor Concluído ou Atualizado.
    4. Se quiser, clique no operador para ver os detalhes.

CLI do OpenShift

Para instalar o operador de telemetria no cluster do OpenShift usando a CLI do OpenShift e um manifesto YAML Subscription declarativo, siga estas etapas:

  1. Crie um manifesto de recurso personalizado Subscription chamado subscription.yaml com a seguinte configuração:

    apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: google-cloud-cluster-services-for-openshift-telemetry
  namespace: openshift-operators
spec:
  channel: stable
  installPlanApproval: Automatic
  name: google-cloud-cluster-services-for-openshift-telemetry
  source: certified-operators
  sourceNamespace: openshift-marketplace

  2. Aplique a assinatura ao cluster:

    oc apply -f subscription.yaml

  3. Verifique se o operador de telemetria foi instalado corretamente verificando o status de ClusterServiceVersion:

    oc get csv -n openshift-operators

    Na saída, verifique se o valor na coluna PHASE para cluster-services-for-openshift-telemetry é Succeeded.

Restringir o provedor de federação de identidade da carga de trabalho

Se você configurou a federação de identidade da carga de trabalho no OpenShift versão 4.18 a 4.21 sem a flag --key-storage-method=pool-jwk-file, o cluster usa um bucket do Cloud Storage para hospedar a configuração do OIDC. Depois de instalar o operador do Cluster Services for OpenShift Telemetry, conclua as seguintes etapas obrigatórias pós-instalação para restringir o provedor de pool de Identidade da carga de trabalho ao UID da conta de serviço específica do cluster:

  1. Recupere o identificador exclusivo (uid) da conta de serviço do Kubernetes do operador de telemetria no namespace openshift-operators:

    KSA_UID=$(oc get serviceaccount google-cloud-cluster-services-telemetry-agent-workloadagent-service-account \
  -n openshift-operators \
  -o jsonpath='{.metadata.uid}')

  2. Atualize o provedor de pool de Identidade da carga de trabalho com uma condição de atributo que fixe a troca de tokens ao UID da conta de serviço recuperado:

    gcloud iam workload-identity-pools providers update-oidc PROVIDER_ID \
  --location="global" \
  --workload-identity-pool="POOL_ID" \
  --project="PROJECT_ID" \
  --attribute-condition="assertion['kubernetes.io']['serviceaccount']['uid']=='${KSA_UID}'"

    Substitua:

    • PROVIDER_ID: o ID do provedor do pool de Identidade da carga de trabalho criado pelo utilitário ccoctl (corresponde a NAME do comando ccoctl gcp create-all)
    • POOL_ID: o ID do pool de Identidade da carga de trabalho criado pelo utilitário ccoctl (corresponde a NAME do comando ccoctl gcp create-all)
    • PROJECT_ID: o ID do projeto do Google Cloud projeto em que o cluster do OpenShift é executado

Se a conta de serviço google-cloud-cluster-services-telemetry-agent-workloadagent-service-account ou o operador for excluído e recriado no cluster, um novo UID será gerado e você precisará executar novamente o comando update-oidc com o novo UID.

Ativar coleta de métricas

Para permitir que o operador colete métricas do cluster do OpenShift, aplique um recurso personalizado TelemetryConfig. Esse recurso implanta pods de daemon nos nós do cluster para o Agente para cargas de trabalho computacionais.

Para permitir que o operador colete métricas do cluster do OpenShift, siga estas etapas:

  1. Crie um manifesto de recurso personalizado TelemetryConfig chamado telemetryconfig.yaml:

    • Se você configurou a autenticação para o operador de telemetria usando a federação de identidade da carga de trabalho, use o seguinte recurso personalizado mínimo. Esse recurso personalizado busca automaticamente as credenciais armazenadas no secret google-cloud-cluster-services-telemetry-agent-wif-secret.

      apiVersion: cluster-services-openshift.cloud.google.com/v1alpha1
kind: TelemetryConfig
metadata:
  name: telemetryconfig
  namespace: openshift-operators
spec:
  enabled: true

    • Se você configurou a autenticação para o operador de telemetria usando uma chave de conta de serviço, use o seguinte recurso personalizado:

      apiVersion: cluster-services-openshift.cloud.google.com/v1alpha1
kind: TelemetryConfig
metadata:
  name: telemetryconfig
  namespace: openshift-operators
spec:
  enabled: true
  serviceAccountCredentialsSecretName: telemetry-agent-sa
  serviceAccountCredentialsPath: SERVICE_ACCOUNT_KEY_PATH

      Substitua SERVICE_ACCOUNT_KEY_PATH pelo caminho em que você montou a chave da conta de serviço. O nome da montagem precisa corresponder ao arquivo JSON da chave da conta de serviço. Por exemplo, /var/run/secrets/google/workload_agent_sa_key.json.

  2. Aplique o recurso personalizado ao cluster:

    oc apply -f telemetryconfig.yaml

  3. Verifique se o estado do pod do agente de telemetria é Running:

    oc get pods -n openshift-operators -l app.kubernetes.io/name=workloadagent-operator

    Também é possível verificar a coleta de métricas inspecionando os registros do pod:

    "openshiftmetrics/openshiftmetrics.go:126","msg":"Metric payload after collection","pid":5,"context":"OpenShiftMetricCollection","payload":"version:\"v0.1.0-pre\" agent_version:\"1.3\"

Ver registros do operador no Cloud Logging

Por padrão, os registros do operador do Cluster Services for OpenShift Telemetry são enviados para o Cloud Logging. É possível ver esses registros no Logging. Para ver os registros do operador no Logging, siga estas etapas:

  1. No console do Google Cloud , acesse a página Análise de registros.

    Acessar a Análise de registros

  2. No painel de consulta, insira uma consulta:

    • Para filtrar os registros do projeto do Google Cloud , use a seguinte consulta:

      logName="projects/PROJECT_ID/logs/google-cloud-workload-agent"

      Substitua PROJECT_ID pelo ID do projeto do Google Cloud projeto em que o cluster do OpenShift é executado.

    • Se você estiver executando vários clusters no projeto do Google Cloud e quiser filtrar registros de um cluster específico, use a seguinte consulta:

      resource.labels.instance_id=("COMPUTE_INSTANCE_ID_1" OR "COMPUTE_INSTANCE_ID_2" OR "COMPUTE_INSTANCE_ID_3")

      Substitua COMPUTE_INSTANCE_ID pelo ID da instância das instâncias do Compute Engine que executam o cluster do OpenShift. Para saber como encontrar o ID da instância de computação, consulte Ver os detalhes de uma VM.

  3. Clique em Executar consulta.

Configurar políticas de alertas com base em registros

Por padrão, os registros do operador de telemetria são enviados para o Cloud Logging. Recomendamos que você configure políticas de alertas com base nos registros do operador de telemetria, que notificam quando mensagens específicas aparecem nos registros. Esses alertas ajudam a monitorar o funcionamento do operador e resolver problemas.

Para configurar uma política de alertas com base nos registros gerados pelo operador de telemetria, siga estas etapas:

  1. Verifique se você atende aos pré-requisitos descritos na seção "Antes de começar" de Configurar políticas de alertas com base em registros.

  2. No console do Google Cloud , acesse a página Análise de registros.

    Acessar a Análise de registros

  3. No painel de consulta, digite a consulta necessária:

    logName="projects/PROJECT_ID/logs/google-cloud-workload-agent"
severity=SEVERITY_LEVEL

    Substitua SEVERITY_LEVEL por um valor de nível de gravidade compatível, que inclui: DEBUG, INFO, WARNING e ERROR. Recomendamos que você use ERROR ou um valor de nível de registro mais alto.

  4. Clique em Executar consulta para validar a consulta.

  5. Criar um alerta de registro.

    Para saber como criar esse alerta, consulte a etapa três do procedimento descrito em Criar uma política de alertas com base em registros usando a Análise de registros.

Opcional: ativar avaliações específicas de produção

Das práticas recomendadas que o Workload Manager aceita para clusters do OpenShift, algumas são aplicadas apenas a ambientes de produção. O Workload Manager faz essa distinção verificando o cluster, a implantação ou o pod em busca do rótulo environment. Se o valor associado a esse rótulo for production, o Workload Manager vai considerar esse recurso como um recurso de produção.

Para informar ao Workload Manager que um cluster pertence a um ambiente de produção, siga estas etapas:

  1. Crie um namespace workloadmanager:

    oc create namespace workloadmanager

  2. Crie um ConfigMap no namespace workloadmanager usando a seguinte configuração:

    apiVersion: v1
kind: ConfigMap
metadata:
  name: wlm-cluster-environment
  namespace: workloadmanager
data:
  # Options: "production" or "non-production"
  environment: "production"

Para informar ao Workload Manager que uma implantação ou um pod pertence a um ambiente de produção, adicione um rótulo chamado environment à definição do recurso usando uma das seguintes opções:

  • Aplique manualmente a seguinte configuração:

    apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  labels:
    # Options: "production" or "non-production"
    environment: "production"
spec:
...

  • Execute este comando:

    oc label --overwrite deployments DEPLOYMENT_NAME environment=production

    Substitua DEPLOYMENT_NAME pelo nome da implantação.

Se você aplicar o rótulo environment ao cluster do OpenShift, bem como a uma implantação ou um pod executado no cluster, o Workload Manager vai priorizar o valor do rótulo definido para a implantação ou o pod em relação ao valor definido para o cluster.

Opcional: acionar a coleta de métricas

Depois de configurar o operador do Cluster Services for OpenShift Telemetry no cluster do OpenShift, ele coleta métricas do cluster e as envia ao Workload Manager a cada 30 minutos.

Se quiser, em vez de esperar 30 minutos pela coleta programada de métricas, acione manualmente o operador para coletar métricas e enviá-las ao Workload Manager.

Para acionar manualmente o operador para coleta de métricas, siga estas etapas:

  1. Abra o terminal.

  2. Encontre o nome do pod em execução:

    POD_NAME=$(oc get pods -l app.kubernetes.io/name=workloadagent-operator --field-selector=status.phase=Running -o=name)

  3. Acione o operador para coletar e enviar métricas:

    oc debug -t $POD_NAME -- /openshift-docker-entrypoint.sh

A seguir