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 vCPU 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 de l'équilibrage automatique et la configuration mTLS.

Pour modifier un cluster, vous pouvez utiliser la console Google Cloud , 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 vCPU et la mémoire, peut nécessiter le redémarrage du cluster par le service. Le service redémarre le cluster un courtier à la fois. Pendant ce processus, les requêtes adressées à des courtiers individuels peuvent échouer, mais ces échecs sont temporaires. Les bibliothèques clientes courantes gèrent automatiquement ces erreurs.

Rôles et autorisations nécessaires

Pour obtenir les autorisations nécessaires pour mettre à jour un cluster, demandez à votre administrateur de vous accorder le rôle IAM Éditeur de cluster Kafka géré (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 requises 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 modifiez le nombre de vCPU ou la mémoire d'un cluster, les règles suivantes s'appliquent :

Le ratio global processeur virtuel/mémoire du cluster doit toujours rester compris entre 1:1 et 1:8.
Chaque courtier existant doit disposer d'au moins un vCPU et 1 Gio de mémoire. Le nombre de courtiers ne diminue jamais.
Si le cluster possède une configuration de disque personnalisée, la mise à jour doit respecter les exigences de configuration de disque pour le stockage local.
Si vous augmentez la taille, la moyenne des vCPU 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 de faire passer un cluster de 45 processeurs virtuels (3 brokers) à 48 processeurs virtuels (4 brokers), le nombre moyen de processeurs virtuels par broker passe de 15 à 12, soit une réduction de 20 %, ce qui dépasse 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 sûr que vos courtiers auront suffisamment de capacité après la mise à jour, vous pouvez désactiver cette vérification en exécutant la commande gcloud managed-kafka clusters update avec l'indicateur allow_broker_downscale_on_cluster_upscale=true. Ce signal indique que vous acceptez le risque potentiel de dégradation des performances.

Pour en savoir plus, consultez Modifier 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 le pare-feu Cloud nouvelle génération pour restreindre 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 depuis la console :
- Mémoire
- vCPU
- Sous-réseau
- Configuration du rééquilibrage
- Configuration mTLS
- Étiquettes
Cliquez sur Enregistrer.

gcloud

Dans la console Google Cloud , activez Cloud Shell.

Activer Cloud Shell

En bas de la console Google Cloud , 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 : libellés à associer au cluster.
- ALLOWED_SOURCE_IP_RANGES : plages CIDR IPv4 sources autorisées pour l'accès à Internet du 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é 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
```
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'option --no-public-cluster.
- Si vous utilisez l'option --async avec votre commande, le système envoie la demande de mise à jour et renvoie immédiatement une réponse, sans attendre la fin de l'opération. L'indicateur --async vous permet de poursuivre d'autres tâches pendant que la mise à jour du cluster s'effectue en arrière-plan. Si vous n'utilisez pas l'option --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 poursuivre d'autres tâches.

REST

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

PROJECT_ID : ID de votre projet Google Cloud
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, puis 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, puis 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 indiqué dans le paramètre de requête UPDATE_MASK.

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 paramètre de requête UPDATE_MASK et spécifiez le tableau allowedSourceIpRanges 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 paramètre de requête UPDATE_MASK et transmettez un objet JSON vide {} dans le corps de la requête (ou omettez publicClusterConfig). Exemple de corps de 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, Application Default Credentials). 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 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 effectuer une rotation des clés de chiffrement.

Étape suivante

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