Aggiorna un cluster Google Cloud Managed Service per Apache Kafka

Puoi modificare un cluster Google Cloud Managed Service per Apache Kafka per aggiornare proprietà come le dimensioni del cluster, tra cui il numero di vCPU e la memoria, l'elenco delle subnet connesse, gli intervalli IP di origine consentiti per i cluster pubblici, la configurazione del bilanciamento automatico e la configurazione mTLS.

Per modificare un cluster, puoi utilizzare la console Google Cloud , Google Cloud CLI, la libreria client o l'API Managed Kafka. Non puoi utilizzare l'API Apache Kafka open source per aggiornare un cluster.

L'aggiornamento di alcune proprietà, come il numero di vCPU e la memoria, potrebbe richiedere il riavvio del cluster da parte del servizio. Il servizio riavvia il cluster un broker alla volta. Durante questo processo, le richieste ai singoli broker potrebbero non riuscire, ma questi errori sono temporanei. Le librerie client di uso comune gestiscono automaticamente questi errori.

Ruoli e autorizzazioni richiesti

Per ottenere l'autorizzazione necessaria per aggiornare un cluster, chiedi all'amministratore di concederti il ruolo IAM Editor cluster Kafka gestito (roles/managedkafka.clusterEditor) nel progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene l'autorizzazione managedkafka.clusters.update necessaria per aggiornare un cluster.

Potresti anche ottenere questa autorizzazione con ruoli personalizzati o altri ruoli predefiniti.

Autorizzazioni subnet del cluster

Se aggiorni la configurazione di rete di un cluster aggiungendo una subnet, l'agente di servizio Managed Kafka collega la subnet durante l'operazione di aggiornamento.

L'autorizzazione managedkafka.clusters.update consente indirettamente a un'entità di collegare qualsiasi subnet che l'agente di servizio è autorizzato a utilizzare, anche se l'entità non dispone dell'autorizzazione diretta per utilizzare la subnet.

Ridimensiona un cluster

Se aggiorni il numero di vCPU o la memoria di un cluster, si applicano le seguenti regole:

  • Il rapporto vCPU/memoria complessivo del cluster deve essere sempre compreso tra 1:1 e 1:8.

  • Deve essere presente almeno 1 vCPU e 1 GiB di memoria per ogni broker esistente. Il numero di broker non diminuisce mai.

  • Se il cluster ha una configurazione dei dischi personalizzata, l'aggiornamento deve soddisfare i requisiti di configurazione dei dischi per l'archiviazione locale.

  • Se esegui lo scale up, la vCPU e la memoria medie per broker non possono diminuire di oltre il 10% rispetto alle medie prima dell'aggiornamento. Ad esempio, se provi a fare lo scale up di un cluster da 45 vCPU (3 broker) a 48 vCPU (4 broker), il numero medio di vCPU per broker diminuisce da 15 a 12, ovvero una riduzione del 20%, superando il limite del 10%.

    Se devi ridurre il numero di vCPU di oltre il 10%, ti consigliamo di farlo in più fasi. Dopo ogni aggiornamento, monitora l'utilizzo delle risorse e, se necessario, riequilibra le partizioni.

    Tuttavia, se hai la certezza che i tuoi broker avranno capacità sufficiente dopo l'aggiornamento, puoi disattivare questo controllo eseguendo il comando gcloud managed-kafka clusters update con il flag allow_broker_downscale_on_cluster_upscale=true. Questo flag indica che accetti il potenziale rischio per le prestazioni.

Per ulteriori informazioni, consulta Aggiorna le dimensioni del cluster.

Configurazione del cluster pubblico

Puoi attivare o disattivare l'accesso pubblico per un cluster esistente, nonché aggiungere o rimuovere intervalli IP di origine consentiti. Per saperne di più sui requisiti e sulle regole per gli intervalli IP di origine consentiti, consulta Cluster pubblici.

Managed Service per Apache Kafka utilizza Cloud Next Generation Firewall per limitare l'accesso ai cluster pubblici. La rimozione degli intervalli IP di origine consentiti o la disattivazione dell'accesso pubblico si applica solo alle nuove connessioni. Per ulteriori informazioni, consulta Effetti sul traffico esistente.

Modifica di un cluster

Per modificare un cluster, segui questi passaggi:

Console

  1. Nella console Google Cloud , vai alla pagina Cluster.

Vai a Cluster

  1. Nell'elenco dei cluster, fai clic su quello di cui vuoi modificare le proprietà.

La console visualizza la pagina dei dettagli del cluster.

  1. Nella pagina dei dettagli del cluster, fai clic su Modifica.

  2. Modifica le proprietà in base alle esigenze. Puoi modificare le seguenti proprietà di un cluster dalla console:

    • Memoria
    • vCPU
    • Subnet
    • Configurazione del ribilanciamento
    • Configurazione mTLS
    • Etichette
  3. Fai clic su Salva.

gcloud

Esegui il comando gcloud managed-kafka clusters update:

gcloud managed-kafka clusters update CLUSTER_ID \
  --location=LOCATION \
  --cpu=CPU \
  --memory=MEMORY \
  --subnets=SUBNETS \
  --async

Sostituisci quanto segue:

  • CLUSTER_ID: l'ID o il nome del cluster.

  • LOCATION: la località del cluster.

  • CPU: il numero di vCPU per il cluster.

  • MEMORY: la quantità di memoria per il cluster. Utilizza le unità "MB", "MiB", "GB", "GiB", "TB" o "TiB". Ad esempio, "10GiB".

  • SUBNETS: l'elenco delle subnet a cui connettersi. Utilizza le virgole per separare più valori di subnet.

Devi specificare almeno una proprietà da aggiornare.

Se includi il flag --async, il comando restituisce immediatamente il risultato, senza attendere il completamento dell'operazione. Se non imposti questo flag, il comando attende il completamento dell'operazione prima di restituire una risposta.

Aggiorna la configurazione del cluster pubblico

Per abilitare l'accesso pubblico al cluster, esegui questo comando.

gcloud managed-kafka clusters update CLUSTER_ID \
  --location=LOCATION \
  --public-cluster \
  --allowed-source-ip-ranges=ALLOWED_SOURCE_IP_RANGES \
  --async

Sostituisci ALLOWED_SOURCE_IP_RANGES con gli intervalli IP di origine consentiti per il cluster pubblico. Per saperne di più, consulta Configurazione di un cluster pubblico.

Per disattivare l'accesso pubblico, utilizza il flag --no-public-cluster.

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: il tuo ID progetto Google Cloud
  • LOCATION: la località del cluster.
  • CLUSTER_ID: l'ID del cluster.
  • UPDATE_MASK: i campi da aggiornare, come elenco separato da virgole di nomi completi. Esempio: capacityConfig.vcpuCount,capacityConfig.memoryBytes
  • CPU_COUNT: il numero di vCPU per il cluster.
  • MEMORY: la quantità di memoria per il cluster, in byte. Esempio: 3221225472.
  • SUBNET_ID: l'ID della subnet a cui connettersi. Esempio: default.

Metodo HTTP e URL:

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

Corpo JSON della richiesta:

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "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
}

Nel corpo della richiesta, includi solo i campi che stai aggiornando, come specificato nel parametro di query UPDATE_MASK.

  • Per aggiungere una subnet, aggiungi una nuova voce a networkConfigs nel seguente formato: projects/PROJECT_ID/regions/LOCATION/subnetworks/SUBNET_ID. Esempio: projects/sample-project/regions/us-central1/subnetworks/default.
  • Per abilitare l'accesso pubblico o aggiornare gli intervalli IP di origine consentiti, includi gcpConfig.accessConfig.publicClusterConfig nel parametro di query UPDATE_MASK e specifica l'array allowedSourceIpRanges nel corpo della richiesta. Esempio di corpo della richiesta:

    {
      "gcpConfig": {
        "accessConfig": {
          "publicClusterConfig": {
            "allowedSourceIpRanges": [
              "203.0.113.0/24"
            ]
          }
        }
      }
    }
    
  • Per disattivare l'accesso pubblico, includi gcpConfig.accessConfig.publicClusterConfig nel parametro di query UPDATE_MASK e passa un oggetto JSON vuoto {} nel corpo della richiesta (o ometti publicClusterConfig). Esempio di corpo della richiesta:

    {}
    

Vai

Prima di provare questo esempio, segui le istruzioni di configurazione di Go in Installa le librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Go di Managed Service per Apache Kafka.

Per eseguire l'autenticazione in Managed Service per Apache Kafka, configura le Credenziali predefinite dell'applicazione (ADC). Per saperne di più, consulta Configura ADC per un ambiente di sviluppo locale.

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

Prima di provare questo esempio, segui le istruzioni di configurazione di Java riportate in Installa le librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Java di Managed Service per Apache Kafka.

Per eseguire l'autenticazione in Managed Service per Apache Kafka, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura ADC per un ambiente di sviluppo locale.


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

Prima di provare questo esempio, segui le istruzioni di configurazione di Python in Installa le librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Python di Managed Service per Apache Kafka.

Per eseguire l'autenticazione in Managed Service per Apache Kafka, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura ADC per un ambiente di sviluppo locale.

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}")

Limitazioni

Dopo aver creato un cluster Managed Service per Apache Kafka, non puoi aggiornare le seguenti proprietà:

  • Il nome del cluster
  • La località del cluster
  • Il tipo di crittografia

Anche se non puoi modificare il tipo di crittografia, puoi ruotare le chiavi di crittografia.

Passaggi successivi

Apache Kafka® è un marchio registrato di Apache Software Foundation o delle sue società affiliate negli Stati Uniti e/o in altri paesi.