O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Atualizar um cluster do serviço gerenciado do Google Cloud para Apache Kafka

É possível editar um cluster do serviço gerenciado do Google Cloud para Apache Kafka para atualizar propriedades como o tamanho do cluster, incluindo a contagem de vCPUs e a memória, a lista de sub-redes conectadas, os intervalos de IP de origem permitidos para clusters públicos, a configuração de reequilíbrio automático e a configuração de mTLS.

Para editar um cluster, use o Google Cloud console, a Google Cloud CLI, a biblioteca de cliente ou a API Managed Kafka. Não é possível usar a API Apache Kafka de código aberto para atualizar um cluster.

A atualização de determinadas propriedades, como a contagem de vCPUs e a memória, pode exigir que o serviço reinicie o cluster. O serviço reinicia o cluster um agente por vez. Durante esse processo, as solicitações para agentes individuais podem falhar, mas essas falhas são temporárias. As bibliotecas de cliente usadas com frequência processam esses erros automaticamente.

Papéis e permissões necessárias

Para receber as permissões necessárias para atualizar um cluster, peça ao administrador para conceder a você o papel do IAM de editor de cluster do Managed Kafka (roles/managedkafka.clusterEditor) no seu projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para atualizar um cluster. Para acessar as permissões exatas que são necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para atualizar um cluster:

Editar um cluster: managedkafka.clusters.update

Essas permissões também podem ser concedidas com papéis personalizados ou outros papéis predefinidos.

Redimensionar um cluster

Se você atualizar a contagem de vCPUs ou a memória de um cluster, as seguintes regras serão aplicadas:

A proporção geral de vCPU para memória do cluster precisa sempre permanecer entre 1:1 e 1:8.
É necessário ter pelo menos 1 vCPU e 1 GiB de memória para cada agente. O número de agentes nunca diminui.
Se o cluster tiver uma configuração de disco personalizada, a atualização precisará atender aos requisitos de configuração de disco para armazenamento local.
Se você fizer um upgrade, a vCPU média e a memória por agente não poderão diminuir em mais de 10% em comparação com as médias antes da atualização. Por exemplo, se você tentar fazer upgrade de um cluster de 45 vCPUs (3 agentes) para 48 vCPUs (4 agentes), a vCPU média por agente diminuirá de 15 para 12, o que é uma redução de 20%, excedendo o limite de 10%.

Se você precisar diminuir a contagem de vCPUs em mais de 10%, recomendamos reduzir em várias etapas. Após cada atualização, monitore a utilização de recursos e reequilibre as partições, se necessário.

No entanto, se você tiver certeza de que seus agentes terão capacidade suficiente após a atualização, poderá desativar essa verificação executando o gcloud managed-kafka clusters update comando com a allow_broker_downscale_on_cluster_upscale=true flag. Essa flag indica que você aceita o possível risco de performance.

Para mais informações, consulte Atualizar o tamanho do cluster.

Configuração do cluster público

É possível ativar ou desativar o acesso público a um cluster, bem como adicionar ou remover intervalos de IP de origem permitidos. Para mais informações sobre os requisitos e regras para intervalos de IP de origem permitidos, consulte Clusters públicos.

O serviço gerenciado para Apache Kafka usa o Cloud Next Generation Firewall para restringir o acesso a clusters públicos. A remoção de intervalos de IP de origem permitidos ou a desativação do acesso público se aplica apenas a novas conexões. Para mais informações, consulte Efeitos no tráfego atual.

Edite um cluster

Para editar um cluster, siga estas etapas:

Console

No Google Cloud console, acesse a página Clusters.

Acessar Clusters

Na lista de clusters, clique no cluster cujas propriedades você quer editar.

O console mostra a página de detalhes do cluster.

Na página de detalhes do cluster, clique em Editar.
Edite as propriedades conforme necessário. É possível editar as seguintes propriedades de um cluster no console:
- Memória
- vCPUs
- Sub-rede
- Configuração de reequilíbrio
- Configuração de mTLS
- Rótulos
Clique em Salvar.

gcloud

No Google Cloud consola, ative o Cloud Shell.

Ativar o Cloud Shell

Na parte de baixo do Google Cloud consola, uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a Google Cloud CLI já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.
Antes de usar os dados do comando abaixo, faça estas substituições:
- PROJECT_ID: o ID do projeto;
- LOCATION: o local do cluster;
- CLUSTER_ID: o ID do cluster;
- CPU_COUNT: o número de vCPUs do cluster;
- MEMORY: a quantidade de memória do cluster. Exemplo: 10GiB.
- SUBNET_ID: o ID da sub-rede a ser conectada. Exemplo: default.
- LABELS: os rótulos a serem associados ao cluster;
- ALLOWED_SOURCE_IP_RANGES: os intervalos CIDR de IPv4 de origem permitidos para acesso à Internet do cluster público.
Execute o comando a seguir:
Linux, macOS ou Cloud Shell

Observação: Para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init; ou gcloud auth login e gcloud config set project.
```
gcloud managed-kafka clusters update CLUSTER_ID \
    --location=LOCATION \
    --cpu=CPU_COUNT \
    --memory=MEMORY \
    --subnets=projects/PROJECT_ID/regions/LOCATION/subnetworks/SUBNET_ID \
    --auto-rebalance \
    --labels=LABELS \
    --public-cluster \
    --allowed-source-ip-ranges=ALLOWED_SOURCE_IP_RANGES
```
Windows (PowerShell)

Observação: Para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init; ou gcloud auth login e gcloud config set project.
```
gcloud managed-kafka clusters update CLUSTER_ID `
    --location=LOCATION `
    --cpu=CPU_COUNT `
    --memory=MEMORY `
    --subnets=projects/PROJECT_ID/regions/LOCATION/subnetworks/SUBNET_ID `
    --auto-rebalance `
    --labels=LABELS `
    --public-cluster `
    --allowed-source-ip-ranges=ALLOWED_SOURCE_IP_RANGES
```
Windows (cmd.exe)

Observação: Para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init; ou gcloud auth login e gcloud config set project.
```
gcloud managed-kafka clusters update CLUSTER_ID ^
    --location=LOCATION ^
    --cpu=CPU_COUNT ^
    --memory=MEMORY ^
    --subnets=projects/PROJECT_ID/regions/LOCATION/subnetworks/SUBNET_ID ^
    --auto-rebalance ^
    --labels=LABELS ^
    --public-cluster ^
    --allowed-source-ip-ranges=ALLOWED_SOURCE_IP_RANGES
```
Você receberá uma resposta semelhante a esta:
```
done: false
metadata:
  '@type': type.googleapis.com/google.cloud.managedkafka.v1.OperationMetadata
  apiVersion: v1
  createTime: 'CREATE_TIME'
  requestedCancellation: false
  target: projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_ID
  verb: update
name: projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID
```
- Para desativar o acesso público, use a flag --no-public-cluster.
- Se você usar a flag --async com o comando, o sistema enviará a solicitação de atualização e retornará uma resposta imediatamente, sem aguardar a conclusão da operação. Com a flag --async, você pode continuar com outras tarefas enquanto a atualização do cluster acontece em segundo plano. Se você não usar a flag --async, o sistema vai aguardar a conclusão da operação antes de retornar uma resposta. Aguarde até que o cluster seja totalmente atualizado antes de continuar com outras tarefas.

REST

Antes de usar os dados da solicitação abaixo, faça estas substituições:

PROJECT_ID: ID do seu Google Cloud projeto
LOCATION: o local do cluster;
CLUSTER_ID: o ID do cluster;
UPDATE_MASK: quais campos atualizar, como uma lista separada por vírgulas de nomes totalmente qualificados; Exemplo: capacityConfig.vcpuCount,capacityConfig.memoryBytes
CPU_COUNT: o número de vCPUs do cluster;
MEMORY: a quantidade de memória do cluster, em bytes. Exemplo: 3221225472.
SUBNET_ID: ID da sub-rede a ser conectada. Exemplo: default.

Método HTTP e URL:

PATCH https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_ID?updateMask=UPDATE_MASK

Corpo JSON da solicitação:

{
  "capacityConfig": {
    "vcpuCount": CPU_COUNT,
    "memoryBytes": MEMORY
  },
  "gcpConfig": {
    "accessConfig": {
      "networkConfigs": [
        {
          "subnet": "projects/PROJECT_ID/regions/LOCATION/subnetworks/SUBNET_ID"
        }
      ]
    }
  }
}

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI do gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_ID?updateMask=UPDATE_MASK"

PowerShell (Windows)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_ID?updateMask=UPDATE_MASK" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.managedkafka.v1.OperationMetadata",
    "createTime": "CREATE_TIME",
    "target": "projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_ID",
    "verb": "update",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

No corpo da solicitação, inclua apenas os campos que você está atualizando, conforme especificado no UPDATE_MASK parâmetro de consulta.

Para adicionar uma sub-rede, anexe uma nova entrada a networkConfigs no seguinte formato: projects/PROJECT_ID/regions/LOCATION/subnetworks/SUBNET_ID. Exemplo: projects/sample-project/regions/us-central1/subnetworks/default.
Para ativar o acesso público ou atualizar os intervalos de IP de origem permitidos, inclua gcpConfig.accessConfig.publicClusterConfig no UPDATE_MASK parâmetro de consulta e especifique a matriz allowedSourceIpRanges no corpo da solicitação. Exemplo de corpo da solicitação:
```
{
  "gcpConfig": {
    "accessConfig": {
      "publicClusterConfig": {
        "allowedSourceIpRanges": [
          "203.0.113.0/24"
        ]
      }
    }
  }
}
```
Para desativar o acesso público, inclua gcpConfig.accessConfig.publicClusterConfig no UPDATE_MASK parâmetro de consulta e transmita um objeto JSON vazio {} no corpo da solicitação (ou omita publicClusterConfig). Exemplo de corpo da solicitação:
```
{}
```

Go

Antes de testar este exemplo, siga as instruções de configuração do Go em Instalar as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Serviço Gerenciado para Apache Kafka Go.

Para autenticar o serviço gerenciado para Apache Kafka, configure o Application Default Credentials(ADC). Para mais informações, consulte Configurar o ADC para um ambiente de desenvolvimento local.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/managedkafka/apiv1/managedkafkapb"
	"google.golang.org/api/option"
	"google.golang.org/protobuf/types/known/fieldmaskpb"

	managedkafka "cloud.google.com/go/managedkafka/apiv1"
)

func updateCluster(w io.Writer, projectID, region, clusterID string, memory int64, opts ...option.ClientOption) error {
	// projectID := "my-project-id"
	// region := "us-central1"
	// clusterID := "my-cluster"
	// memoryBytes := 4221225472
	ctx := context.Background()
	client, err := managedkafka.NewClient(ctx, opts...)
	if err != nil {
		return fmt.Errorf("managedkafka.NewClient got err: %w", err)
	}
	defer client.Close()

	clusterPath := fmt.Sprintf("projects/%s/locations/%s/clusters/%s", projectID, region, clusterID)
	capacityConfig := &managedkafkapb.CapacityConfig{
		MemoryBytes: memory,
	}
	cluster := &managedkafkapb.Cluster{
		Name:           clusterPath,
		CapacityConfig: capacityConfig,
	}
	paths := []string{"capacity_config.memory_bytes"}
	updateMask := &fieldmaskpb.FieldMask{
		Paths: paths,
	}

	req := &managedkafkapb.UpdateClusterRequest{
		UpdateMask: updateMask,
		Cluster:    cluster,
	}
	op, err := client.UpdateCluster(ctx, req)
	if err != nil {
		return fmt.Errorf("client.UpdateCluster got err: %w", err)
	}
	resp, err := op.Wait(ctx)
	if err != nil {
		return fmt.Errorf("op.Wait got err: %w", err)
	}
	fmt.Fprintf(w, "Updated cluster: %#v\n", resp)
	return nil
}

Java

Antes de testar este exemplo, siga as instruções de configuração do Java em Instalar as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Serviço Gerenciado para Apache Kafka Java.

Para autenticar o serviço gerenciado para Apache Kafka, configure o Application Default Credentials. Para mais informações, consulte Configurar o ADC para um ambiente de desenvolvimento local.


import com.google.api.gax.longrunning.OperationFuture;
import com.google.api.gax.longrunning.OperationSnapshot;
import com.google.api.gax.longrunning.OperationTimedPollAlgorithm;
import com.google.api.gax.retrying.RetrySettings;
import com.google.api.gax.retrying.TimedRetryAlgorithm;
import com.google.cloud.managedkafka.v1.CapacityConfig;
import com.google.cloud.managedkafka.v1.Cluster;
import com.google.cloud.managedkafka.v1.ClusterName;
import com.google.cloud.managedkafka.v1.ManagedKafkaClient;
import com.google.cloud.managedkafka.v1.ManagedKafkaSettings;
import com.google.cloud.managedkafka.v1.OperationMetadata;
import com.google.cloud.managedkafka.v1.UpdateClusterRequest;
import com.google.protobuf.FieldMask;
import java.time.Duration;
import java.util.concurrent.ExecutionException;

public class UpdateCluster {

  public static void main(String[] args) throws Exception {
    // TODO(developer): Replace these variables before running the example.
    String projectId = "my-project-id";
    String region = "my-region"; // e.g. us-east1
    String clusterId = "my-cluster";
    long memoryBytes = 25769803776L; // 24 GiB
    updateCluster(projectId, region, clusterId, memoryBytes);
  }

  public static void updateCluster(
      String projectId, String region, String clusterId, long memoryBytes) throws Exception {
    CapacityConfig capacityConfig = CapacityConfig.newBuilder().setMemoryBytes(memoryBytes).build();
    Cluster cluster =
        Cluster.newBuilder()
            .setName(ClusterName.of(projectId, region, clusterId).toString())
            .setCapacityConfig(capacityConfig)
            .build();
    FieldMask updateMask = FieldMask.newBuilder().addPaths("capacity_config.memory_bytes").build();

    // Create the settings to configure the timeout for polling operations
    ManagedKafkaSettings.Builder settingsBuilder = ManagedKafkaSettings.newBuilder();
    TimedRetryAlgorithm timedRetryAlgorithm = OperationTimedPollAlgorithm.create(
        RetrySettings.newBuilder()
            .setTotalTimeoutDuration(Duration.ofHours(1L))
            .build());
    settingsBuilder.updateClusterOperationSettings()
        .setPollingAlgorithm(timedRetryAlgorithm);

    try (ManagedKafkaClient managedKafkaClient = ManagedKafkaClient.create(
        settingsBuilder.build())) {
      UpdateClusterRequest request =
          UpdateClusterRequest.newBuilder().setUpdateMask(updateMask).setCluster(cluster).build();
      OperationFuture<Cluster, OperationMetadata> future =
          managedKafkaClient.updateClusterOperationCallable().futureCall(request);

      // Get the initial LRO and print details. CreateCluster contains sample code for polling logs.
      OperationSnapshot operation = future.getInitialFuture().get();
      System.out.printf("Cluster update started. Operation name: %s\nDone: %s\nMetadata: %s\n",
          operation.getName(),
          operation.isDone(),
          future.getMetadata().get().toString());

      Cluster response = future.get();
      System.out.printf("Updated cluster: %s\n", response.getName());
    } catch (ExecutionException e) {
      System.err.printf("managedKafkaClient.updateCluster got err: %s", e.getMessage());
    }
  }
}

Python

Antes de testar este exemplo, siga as instruções de configuração do Python em Instalar as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Managed Service for Apache Kafka Python.

Para autenticar o serviço gerenciado para Apache Kafka, configure o Application Default Credentials. Para mais informações, consulte Configurar o ADC para um ambiente de desenvolvimento local.

from google.api_core.exceptions import GoogleAPICallError
from google.cloud import managedkafka_v1
from google.protobuf import field_mask_pb2

# TODO(developer)
# project_id = "my-project-id"
# region = "us-central1"
# cluster_id = "my-cluster"
# memory_bytes = 4295000000

client = managedkafka_v1.ManagedKafkaClient()

cluster = managedkafka_v1.Cluster()
cluster.name = client.cluster_path(project_id, region, cluster_id)
cluster.capacity_config.memory_bytes = memory_bytes
update_mask = field_mask_pb2.FieldMask()
update_mask.paths.append("capacity_config.memory_bytes")

# For a list of editable fields, one can check https://cloud.google.com/managed-kafka/docs/create-cluster#properties.
request = managedkafka_v1.UpdateClusterRequest(
    update_mask=update_mask,
    cluster=cluster,
)

try:
    operation = client.update_cluster(request=request)
    print(f"Waiting for operation {operation.operation.name} to complete...")
    response = operation.result()
    print("Updated cluster:", response)
except GoogleAPICallError as e:
    print(f"The operation failed with error: {e.message}")

Limitações

Depois de criar um cluster do serviço gerenciado para Apache Kafka, não é possível atualizar as seguintes propriedades:

O nome do cluster
O local do cluster
O tipo de criptografia

Embora não seja possível mudar o tipo de criptografia, é possível alternar as chaves de criptografia.

A seguir

Apache Kafka® é uma marca registrada da The Apache Software Foundation ou afiliadas nos Estados Unidos e/ou em outros países.