Delete a subject

You can delete a subject in two ways: soft-delete and hard-delete.

Soft-delete marks a subject as deleted, but its information is retained and can be recovered. All versions for the subject are also soft-deleted. You can find soft-deleted subjects when listing subjects by using the deleted=true query parameter in the ListSubjects API call. This method is only supported using REST API calls. You cannot soft-delete a subject using the Google Cloud console.

Hard-delete permanently removes a subject and its associated data. This method is supported both in Google Cloud console and using the REST API call.

This document shows you how to delete a subject using the Google Cloud console or the Managed Kafka API.

Required roles and permissions

To get the permissions that you need to delete a subject, ask your administrator to grant you the Managed Kafka Schema Registry Editor (roles/managedkafka.schemaRegistryEditor) IAM role on your subject. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the permissions required to delete a subject. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to delete a subject:

  • Grant the following permission on the subject to be deleted: managedkafka.subjects.delete
  • If deleting in the console, grant the following permission to view the subject: managedkafka.subjects.list

You might also be able to get these permissions with custom roles or other predefined roles.

The Managed Kafka Schema Registry Admin (roles/managedkafka.schemaRegistryAdmin) role also let you delete subjects.

For more information about predefined roles, see the Managed Service for Apache Kafka predefined roles.

Soft-delete a subject

Make sure the following conditions are met:

  • The subject that you are going to delete is not referenced by other schemas. A request for deletion fails if any version in the subject is referenced by other schemas.

  • The schema registry to which the subject belongs or the subject itself must not be in the Read-only mode.

To soft-delete a subject, follow these steps.

REST

The request must be authenticated with an access token in the Authorization header. To obtain an access token for the current Application Default Credentials: gcloud auth application-default print-access-token.

To soft-delete a subject using the REST API, make a DELETE request to the appropriate URI using the projects.locations.schemaRegistries.contexts.subjects.delete method.

DELETE https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/subjects/SUBJECT_ID
Authorization: Bearer $(gcloud auth application-default print-access-token)

To soft-delete a subject under a specific context by using the REST API, make a DELETE request to the appropriate URI using the projects.locations.schemaRegistries.contexts.subjects.delete method.

DELETE https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/contexts/CONTEXT_ID/subjects/SUBJECT_ID
Authorization: Bearer $(gcloud auth application-default print-access-token)

Replace the following:

  • PROJECT_ID (required): your Google Cloud project ID.
  • LOCATION (required): the Google Cloud region where the schema registry is located.
  • REGISTRY_ID (required): the ID of your schema registry.
  • CONTEXT_ID (optional): the ID or name of the context, if deleting a subject within a specific context.
  • SUBJECT_ID (optional): the ID or name of the subject you want to delete.

For example, to soft-delete orders-topic-value from schema registry test_registry in project test-gcp-project and location us-central1, make the following request:

DELETE https://managedkafka.googleapis.com/v1/projects/test-gcp-project/locations/us-central1/schemaRegistries/test_registry/subjects/orders-topic-value
Authorization: Bearer $(gcloud auth application-default print-access-token)

If the request is successful, the API returns a 200 OK status code. The response body contains a JSON array of the version numbers of the schemas that belonged to the deleted subject.

Hard-delete a subject

Hard-deleting a subject is irreversible and also deletes all associated schema versions.

Make sure the following conditions are met:

  • The subject that you are going to delete is not referenced by other schemas. A request for deletion fails if any version in the subject is referenced by other schemas.

  • The schema registry to which the subject belongs or the subject itself must not be in the Read-only mode.

  • Back up any necessary schema information before proceeding with the deletion.

  • No active producers or consumers must rely on the schemas within this subject, as deleting it can cause disruptions.

Console

  1. In the Google Cloud console, go to the Schema registries page.

    Go to Schema registries

  2. Click the name of the schema registry that contains the subject to delete.

  3. Under Subjects in this schema registry, click the name of the subject.

  4. In the Subject details page, click Delete.

  5. In the Delete schema subject dialog, type delete into the field.

  6. Click Delete. This action soft-deletes the subject before permanently deleting it.

REST

To hard-delete a subject using the REST API, you must first soft-delete it. Once soft-deleted, you can proceed with the hard-deletion.

The request must be authenticated with an access token in the Authorization header. To obtain an access token for the current Application Default Credentials: gcloud auth application-default print-access-token.

To hard-delete a subject using the REST API, make a DELETE request to the appropriate URI, including the permanent=true query parameter and using the projects.locations.schemaRegistries.subjects.delete method.

DELETE https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/subjects/SUBJECT_ID?permanent=true
Authorization: Bearer $(gcloud auth application-default print-access-token)

To hard-delete a subject under a specific context by using the REST API, make a DELETE request to the appropriate URI, including the permanent=true query parameter and using the projects.locations.schemaRegistries.contexts.subjects.delete method.

DELETE https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/contexts/CONTEXT_ID/subjects/SUBJECT_ID?permanent=true
Authorization: Bearer $(gcloud auth application-default print-access-token)

Replace the following:

  • PROJECT_ID (required): your Google Cloud project ID.
  • LOCATION (required): the Google Cloud region where the schema registry is located.
  • REGISTRY_ID (required): the ID of your schema registry.
  • CONTEXT_ID (optional): the ID of the context, if deleting a subject within a specific context.
  • SUBJECT_ID (optional): the ID or name of the subject you want to delete.

For example, to hard-delete the previously soft-deleted subject orders-topic-value from schema registry test_registry in project test-gcp-project and location us-central1, make the following request:

DELETE https://managedkafka.googleapis.com/v1/projects/test-gcp-project/locations/us-central1/schemaRegistries/test_registry/subjects/orders-topic-value?permanent=true
Authorization: Bearer $(gcloud auth application-default print-access-token)

If the request is successful, the API returns a 200 OK status code. The response body contains a JSON array of the version numbers of the schemas that belonged to the deleted subject.

For more information, see projects.locations.schemaRegistries.contexts.subjects.delete.

What's next

Apache Kafka® is a registered trademark of The Apache Software Foundation or its affiliates in the United States and/or other countries.