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
method.
projects.locations.schemaRegistries.contexts.subjects.delete
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
method.projects.locations.schemaRegistries.contexts.subjects.delete
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
- In the Google Cloud console, go to the Schema registries page.
- Click on the name of the schema registry that contains the subject that
you want to delete.
The Schema registry details page opens.
- In the list of subjects, click the subject that you wish to delete.
- In the Subject details page, click Delete.
- If you are certain, confirm the deletion.
REST
To hard-delete a subject, 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
.