Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Mettre à jour un cluster Google Cloud Managed Service pour Apache Kafka

Vous pouvez modifier un cluster Google Cloud Managed Service pour Apache Kafka afin de mettre à jour des propriétés telles que la taille du cluster (y compris le nombre de processeurs virtuels et la mémoire), la liste des sous-réseaux connectés, les plages d'adresses IP sources autorisées pour les clusters publics, la configuration du rééquilibrage automatique et la configuration mTLS.

Pour modifier un cluster, vous pouvez utiliser la Google Cloud console, Google Cloud CLI, la bibliothèque cliente ou l'API Managed Kafka. Vous ne pouvez pas utiliser l'API Apache Kafka Open Source pour mettre à jour un cluster.

La mise à jour de certaines propriétés, telles que le nombre de processeurs virtuels et la mémoire, peut nécessiter le redémarrage du cluster par le service. Le service redémarre le cluster un agent à la fois. Pendant ce processus, les requêtes adressées à des agents individuels peuvent échouer, mais ces échecs sont temporaires. Les bibliothèques clientes couramment utilisées gèrent automatiquement ces erreurs.

Rôles et autorisations requis

Pour obtenir les autorisations nécessaires pour mettre à jour un cluster, demandez à votre administrateur de vous attribuer le rôle IAM d'éditeur de cluster Managed Kafka (roles/managedkafka.clusterEditor) sur votre projet. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ce rôle prédéfini contient les autorisations nécessaires pour mettre à jour un cluster. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Les autorisations suivantes sont requises pour mettre à jour un cluster :

Modifier un cluster : managedkafka.clusters.update

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Redimensionner un cluster

Si vous mettez à jour le nombre de processeurs virtuels ou la mémoire d'un cluster, les règles suivantes s'appliquent :

Le ratio global processeurs virtuels/mémoire du cluster doit toujours rester compris entre 1:1 et 1:8.
Chaque agent existant doit disposer d'au moins un processeur virtuel et d'un Go de mémoire. Le nombre d'agents ne diminue jamais.
Si le cluster dispose d'une configuration de disque personnalisée, la mise à jour doit répondre aux exigences de configuration de disque pour le stockage local.
Si vous augmentez la capacité, la moyenne des processeurs virtuels et de la mémoire par agent ne peut pas diminuer de plus de 10% par rapport aux moyennes avant la mise à jour. Par exemple, si vous essayez d'augmenter la capacité d'un cluster de 45 processeurs virtuels (3 agents) à 48 processeurs virtuels (4 agents), la moyenne des processeurs virtuels par agent passe de 15 à 12, ce qui représente une réduction de 20 %, dépassant la limite de 10 %.

Si vous devez réduire le nombre de processeurs virtuels de plus de 10%, nous vous recommandons de le faire en plusieurs étapes. Après chaque mise à jour, surveillez l'utilisation des ressources et rééquilibrez les partitions si nécessaire.

Toutefois, si vous êtes certain que vos agents disposeront d'une capacité suffisante après la mise à jour, vous pouvez désactiver cette vérification en exécutant la gcloud managed-kafka clusters update commande avec l'indicateur allow_broker_downscale_on_cluster_upscale=true. Cet indicateur signale que vous acceptez le risque potentiel en termes de performances.

Pour en savoir plus, consultez Mettre à jour la taille du cluster.

Configuration du cluster public

Vous pouvez activer ou désactiver l'accès public pour un cluster existant, ainsi qu'ajouter ou supprimer des plages d'adresses IP sources autorisées. Pour en savoir plus sur les exigences et les règles concernant les plages d'adresses IP sources autorisées, consultez Clusters publics.

Managed Service pour Apache Kafka utilise Cloud Next Generation Firewall pour limiter l'accès aux clusters publics. La suppression des plages d'adresses IP sources autorisées ou la désactivation de l'accès public ne s'appliquent qu'aux nouvelles connexions. Pour en savoir plus, consultez Effets sur le trafic existant.

Modifier un cluster

Pour modifier un cluster, procédez comme suit :

Console

Dans la console Google Cloud , accédez à la page Clusters.

Accéder aux clusters

Dans la liste des clusters, cliquez sur celui dont vous souhaitez modifier les propriétés.

La console affiche la page des détails du cluster.

Sur la page d'informations du cluster, cliquez sur Modifier.
Modifiez les propriétés selon vos besoins. Vous pouvez modifier les propriétés suivantes d'un cluster à partir de la console :
- Mémoire
- vCPUs
- Sous-réseau
- Configuration du rééquilibrage
- Configuration mTLS
- Étiquettes
Cliquez sur Enregistrer.

gcloud

Dans la Google Cloud console, activez Cloud Shell.

Activer Cloud Shell

En bas de la Google Cloud console, une session Cloud Shell démarre et affiche une invite de ligne de commande. Cloud Shell est un environnement shell dans lequel Google Cloud CLI est déjà installé, et dans lequel des valeurs sont déjà définies pour votre projet actuel. L'initialisation de la session peut prendre quelques secondes.
Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :
- PROJECT_ID : ID du projet.
- LOCATION : emplacement du cluster.
- CLUSTER_ID : ID du cluster.
- CPU_COUNT : nombre de processeurs virtuels pour le cluster.
- MEMORY : quantité de mémoire pour le cluster. Exemple : 10GiB.
- SUBNET_ID : ID du sous-réseau auquel se connecter. Exemple : default.
- LABELS : étiquettes à associer au cluster.
- ALLOWED_SOURCE_IP_RANGES : plages CIDR IPv4 sources autorisées pour l'accès Internet au cluster public.
Exécutez la commande suivante :
Linux, macOS ou Cloud Shell

Remarque : Assurez-vous d'avoir initialisé la Google Cloud CLI avec l'authentification et un projet en exécutant la commande gcloud init, ou les commandes gcloud auth login et 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)

Remarque : Assurez-vous d'avoir initialisé la Google Cloud CLI avec l'authentification et un projet en exécutant la commande gcloud init, ou les commandes gcloud auth login et 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)

Remarque : Assurez-vous d'avoir initialisé Google Cloud CLI avec l'authentification et un projet en exécutant la commande gcloud init ou gcloud auth login et 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
```
Vous devriez obtenir un résultat semblable à celui-ci :
```
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
```
- Pour désactiver l'accès public, utilisez l'indicateur --no-public-cluster.
- Si vous utilisez l'indicateur --async avec votre commande, le système envoie la requête de mise à jour et renvoie immédiatement une réponse, sans attendre la fin de l'opération. Avec l'indicateur --async, vous pouvez continuer à effectuer d'autres tâches pendant que la mise à jour du cluster s'effectue en arrière-plan. Si vous n'utilisez pas l'indicateur --async, le système attend la fin de l'opération avant de renvoyer une réponse. Vous devez attendre que le cluster soit entièrement mis à jour avant de pouvoir continuer à effectuer d'autres tâches.

REST

Avant d'utiliser les données de la requête, effectuez les remplacements suivants :

PROJECT_ID: ID de votre Google Cloud projet
LOCATION : emplacement du cluster.
CLUSTER_ID : ID du cluster.
UPDATE_MASK : champs à mettre à jour, sous forme de liste de noms complets séparés par une virgule. Exemple : capacityConfig.vcpuCount,capacityConfig.memoryBytes
CPU_COUNT : nombre de processeurs virtuels pour le cluster.
MEMORY : quantité de mémoire pour le cluster, en octets. Exemple : 3221225472.
SUBNET_ID : ID du sous-réseau auquel se connecter. Exemple : default.

Méthode HTTP et URL :

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

Corps JSON de la requête :

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

Pour envoyer votre requête, développez l'une des options suivantes :

curl (Linux, macOS ou Cloud Shell)

Remarque : La commande suivante suppose que vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login, ou en utilisant Cloud Shell, qui vous connecte automatiquement à la CLI gcloud. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json, et exécutez la commande suivante :

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)

Remarque : La commande suivante suppose que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json, et exécutez la commande suivante :

$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

Vous devriez recevoir une réponse JSON de ce type :

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

Dans le corps de la requête, n'incluez que les champs que vous mettez à jour, comme spécifié dans le UPDATE_MASK paramètre de requête.

Pour ajouter un sous-réseau, ajoutez une entrée à networkConfigs au format suivant : projects/PROJECT_ID/regions/LOCATION/subnetworks/SUBNET_ID. Exemple : projects/sample-project/regions/us-central1/subnetworks/default.
Pour activer l'accès public ou mettre à jour les plages d'adresses IP sources autorisées, incluez gcpConfig.accessConfig.publicClusterConfig dans le UPDATE_MASK paramètre de requête et spécifiez le allowedSourceIpRanges tableau dans le corps de la requête. Exemple de corps de la requête :
```
{
  "gcpConfig": {
    "accessConfig": {
      "publicClusterConfig": {
        "allowedSourceIpRanges": [
          "203.0.113.0/24"
        ]
      }
    }
  }
}
```
Pour désactiver l'accès public, incluez gcpConfig.accessConfig.publicClusterConfig dans le UPDATE_MASK paramètre de requête et transmettez un objet JSON vide {} dans le corps de la requête (ou omettez publicClusterConfig). Exemple de corps de la requête :
```
{}
```

Go

Avant d'essayer cet exemple, suivez les instructions de configuration pour Go dans Installer les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Go pour Managed Service pour Apache Kafka.

Pour vous authentifier auprès de Managed Service pour Apache Kafka, configurez les identifiants par défaut de l'application(ADC). Pour en savoir plus, consultez Configurer les ADC pour un environnement de développement 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

Avant d'essayer cet exemple, suivez les instructions de configuration pour Java dans Installer les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Java pour Managed Service pour Apache Kafka.

Pour vous authentifier auprès de Managed Service pour Apache Kafka, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer les ADC pour un environnement de développement 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

Avant d'essayer cet exemple, suivez les instructions de configuration pour Python dans Installer les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Python pour Managed Service pour Apache Kafka.

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

Limites

Une fois que vous avez créé un cluster Managed Service pour Apache Kafka, vous ne pouvez plus modifier les propriétés suivantes :

Nom du cluster
Emplacement du cluster
Type de chiffrement

Bien que vous ne puissiez pas modifier le type de chiffrement, vous pouvez faire pivoter les clés de chiffrement.

Étape suivante

Apache Kafka® est une marque déposée d'Apache Software Foundation ou de ses filiales aux États-Unis et/ou dans d'autres pays.